@principal-ai/principal-view-react 0.16.58 → 0.16.59

package/src/subsystem/model.test.ts

@@ -2,6 +2,9 @@ import { describe, expect, test } from 'bun:test';
 import {
   convertSubsystemToNodes,
   convertSubsystemToEdges,
+  convertSubsystemToGroups,
+  getSubsystemRegions,
+  processGroupNodeId,
   buildSubsystemGraph,
   deriveNameFromSymbol,
   formatPurl,
@@ -121,6 +124,59 @@ describe('subsystem graph model', () => {
     expect(formatPurl('not-a-purl')).toBe('not-a-purl');
   });
 
+  test('getSubsystemRegions groups by process, skipping process-less nodes', () => {
+    const regions = getSubsystemRegions({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['app/host', 'app/renderer']);
+    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+  });
+
+  test('convertSubsystemToNodes stamps parentId for process members only', () => {
+    const nodes = convertSubsystemToNodes({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+      edges: [],
+    });
+    expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
+      processGroupNodeId('app/host'),
+    );
+    expect((nodes.find((n) => n.id === 'd') as { parentId?: string }).parentId).toBeUndefined();
+  });
+
+  test('convertSubsystemToGroups emits one parent per process', () => {
+    const groups = convertSubsystemToGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+      ],
+    });
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.id).toBe(processGroupNodeId('app/host'));
+    expect(groups[0]!.type).toBe('subsystem-group');
+  });
+
+  test('buildSubsystemGraph drops singleton process frames (no parentId, no group)', async () => {
+    const { nodes, regions } = await buildSubsystemGraph({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+      ],
+      edges: [{ id: 'e1', from: 'a', to: 'b', mechanism: 'calls' }],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['app/host']);
+    expect((nodes.find((n) => n.id === 'solo') as { parentId?: string }).parentId).toBeUndefined();
+    expect(nodes.find((n) => n.id === processGroupNodeId('app/lonely'))).toBeUndefined();
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = { components: comps, edges };
     const withRef = {

package/src/subsystem/model.ts

@@ -17,7 +17,7 @@ import {
   type Edge,
   type Node,
 } from '@xyflow/react';
-import { computeElkLayout } from '../utils/elkLayout';
+import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 
@@ -292,6 +292,46 @@ export interface SubsystemGraphDocument {
 
 export type SubsystemGraphNodeType = 'subsystem-component' | 'subsystem-group';
 
+/**
+ * One process boundary region — all components sharing a `process` value.
+ * Nodes without a `process` sit outside every boundary (no region).
+ */
+export interface SubsystemProcessRegion {
+  /** The `process` value (e.g. `trail-viewer/host`). */
+  key: string;
+  /** Display label for the boundary frame. */
+  label: string;
+  /** Component ids that are members of this region. */
+  memberIds: string[];
+}
+
+/** React Flow id for a process boundary group node. */
+export function processGroupNodeId(processKey: string): string {
+  return `process:${processKey}`;
+}
+
+/**
+ * Derive boundary regions from a document — one per distinct non-empty
+ * `process` value, in first-appearance order.
+ */
+export function getSubsystemRegions(
+  doc: Pick<SubsystemGraphDocument, 'components'>,
+): SubsystemProcessRegion[] {
+  const byProcess = new Map<string, string[]>();
+  for (const c of doc.components) {
+    const p = c.process?.trim();
+    if (!p) continue;
+    const list = byProcess.get(p) ?? [];
+    list.push(c.id);
+    byProcess.set(p, list);
+  }
+  return [...byProcess.entries()].map(([key, memberIds]) => ({
+    key,
+    label: key,
+    memberIds,
+  }));
+}
+
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
   component: SubsystemComponent;
   /** Set while a file is open in the drawer: true if this node's component
@@ -302,7 +342,15 @@ export interface SubsystemGraphNodeData extends Record<string, unknown> {
   dimmed?: boolean;
 }
 
-export type SubsystemGraphNode = Node<SubsystemGraphNodeData, SubsystemGraphNodeType>;
+export interface SubsystemGroupNodeData extends Record<string, unknown> {
+  region: SubsystemProcessRegion;
+  /** True while the region's members are dimmed by flow focus. */
+  dimmed?: boolean;
+}
+
+export type SubsystemGraphNode =
+  | Node<SubsystemGraphNodeData, 'subsystem-component'>
+  | Node<SubsystemGroupNodeData, 'subsystem-group'>;
 
 export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   mechanism: SubsystemEdgeMechanism;
@@ -313,6 +361,8 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   /** ELK-computed label midpoint (from the actual edge path, not node centers). */
   labelX?: number;
   labelY?: number;
+  /** Polyline length in flow-space units (for capping screen-space label size). */
+  pathLength?: number;
   /** ELK-computed SVG edge path (overrides React Flow's default path). */
   elkPath?: string;
 }
@@ -394,12 +444,11 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
 };
 
 /**
- * Convert a subsystem graph document into React Flow nodes. We render **flat**
- * (no React Flow parent/group nodes) for robustness: package regions are laid
- * out in a grid and each component carries its package + a `pkgBounds`
- * rectangle on its node data so the group wrapper (drawn by the graph
- * component) can frame it. Only components' real positions matter to React
- * Flow; the package boundary is a visual region, not a sub-flow node.
+ * Convert a subsystem graph document into React Flow nodes. Components that
+ * carry a `process` get a `parentId` pointing at their boundary group node
+ * (`process:<process>`); nodes without one stay top-level (outside every
+ * boundary). The initial grid groups by `process ?? purl` so the pre-ELK
+ * positions are already clustered; ELK then refines with compound layout.
  */
 export function convertSubsystemToNodes(
   doc: SubsystemGraphDocument,
@@ -447,9 +496,11 @@ export function convertSubsystemToNodes(
       const cssBorder = 4; // 2px border each side
       const rawWidth = Math.max(cssMinWidth, textWidth + cssPadding + cssBorder);
       const nodeWidth = Math.max(cssMinWidth, Math.min(cap, rawWidth));
+      const processKey = c.process?.trim();
       nodes.push({
         id: c.id,
         type: 'subsystem-component',
+        ...(processKey ? { parentId: processGroupNodeId(processKey) } : {}),
         position: { x: PAD + col * COL_W, y: cursorY + row * ROW_H },
         width: nodeWidth,
         height: 84,
@@ -461,6 +512,24 @@ export function convertSubsystemToNodes(
   return nodes;
 }
 
+/**
+ * Convert boundary regions into React Flow parent (group) nodes. One per
+ * distinct `process` value; member components point at these via `parentId`.
+ * Positions/sizes are placeholders — ELK compound layout overwrites them.
+ */
+export function convertSubsystemToGroups(
+  doc: Pick<SubsystemGraphDocument, 'components'>,
+): SubsystemGraphNode[] {
+  return getSubsystemRegions(doc).map((region) => ({
+    id: processGroupNodeId(region.key),
+    type: 'subsystem-group',
+    position: { x: 0, y: 0 },
+    width: 400,
+    height: 300,
+    data: { region },
+  }));
+}
+
 /**
  * Convert a subsystem graph document into React Flow edges. Edges whose target
  * is an external label (not a component id) point at a synthetic stub so the
@@ -522,10 +591,23 @@ export async function buildSubsystemGraph(
 ): Promise<{
   nodes: SubsystemGraphNode[];
   edges: SubsystemGraphEdge[];
+  regions: SubsystemProcessRegion[];
 }> {
   const { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights } = opts;
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
   const edges = convertSubsystemToEdges(doc);
+  // Boundary regions: one per multi-member process. Singletons get no frame —
+  // strip the parentId convertSubsystemToNodes stamped so React Flow never
+  // points at a non-existent parent.
+  const regions = getSubsystemRegions(doc).filter((r) => r.memberIds.length >= 2);
+  const regionKeys = new Set(regions.map((r) => r.key));
+  for (const n of nodes) {
+    if (n.type !== 'subsystem-component') continue;
+    const proc = (n.data as SubsystemGraphNodeData).component?.process?.trim();
+    if (proc && !regionKeys.has(proc)) {
+      delete (n as { parentId?: string }).parentId;
+    }
+  }
 
   // External edge targets that aren't real components → create stub nodes so
   // cross-package edges have something to land on.
@@ -574,10 +656,12 @@ export async function buildSubsystemGraph(
     }
   }
 
-  // ELK auto-layout: position nodes (layered, minimized crossings).
+  // ELK auto-layout: position nodes (layered, minimized crossings) with
+  // process partitions as compound parents so boundaries shape the layout.
   let placedNodes = nodes;
   let labelPositions = new Map<string, { x: number; y: number }>();
   let elkPathStrings = new Map<string, string>();
+  let elkPathPoints = new Map<string, { x: number; y: number }[]>();
   if (nodes.length > 0) {
     try {
       const result = await computeElkLayout(nodes, edges, {
@@ -589,10 +673,29 @@ export async function buildSubsystemGraph(
         interLayerSpacing: 120,
         preserveNodePositions: false,
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
+        groups: regions.map((r) => ({
+          id: processGroupNodeId(r.key),
+          memberIds: r.memberIds,
+        })),
       });
-      placedNodes = result.nodes as SubsystemGraphNode[];
+      const groupNodes: SubsystemGraphNode[] = regions.flatMap((region) => {
+        const bounds = result.groupBounds.get(processGroupNodeId(region.key));
+        if (!bounds) return [];
+        const group: SubsystemGraphNode = {
+          id: processGroupNodeId(region.key),
+          type: 'subsystem-group',
+          position: { x: bounds.x, y: bounds.y },
+          width: Math.max(200, bounds.width),
+          height: Math.max(160, bounds.height),
+          data: { region },
+        };
+        return [group];
+      });
+      // Parents first — React Flow resolves children via parentId.
+      placedNodes = [...groupNodes, ...(result.nodes as SubsystemGraphNode[])];
       labelPositions = result.edgeLabelPositions;
       elkPathStrings = result.edgePaths;
+      elkPathPoints = result.edgePathPoints;
     } catch (err) {
       // Fall back to the (unpositioned) grid if ELK is unavailable.
       console.warn('[subsystem-graph] ELK layout failed, using manual positions:', err);
@@ -613,7 +716,12 @@ export async function buildSubsystemGraph(
       const d = (e as SubsystemGraphEdge).data as SubsystemGraphEdgeData;
       d.elkPath = elkP;
     }
+    const pts = elkPathPoints.get(e.id);
+    if (pts && pts.length > 1) {
+      const d = (e as SubsystemGraphEdge).data as SubsystemGraphEdgeData;
+      d.pathLength = calculatePathLength(pts);
+    }
   }
 
-  return { nodes: placedNodes, edges };
+  return { nodes: placedNodes, edges, regions };
 }

package/src/subsystem/nodes.tsx

@@ -11,6 +11,7 @@ import { useState } from 'react';
 import {
   Handle,
   Position,
+  type Node,
   type NodeProps,
   type EdgeProps,
 } from '@xyflow/react';
@@ -21,7 +22,9 @@ import {
   ROLE_COLOR,
   ROLE_LABEL,
   deriveNameFromSymbol,
-  type SubsystemGraphNode,
+  packageColor,
+  type SubsystemGraphNodeData,
+  type SubsystemGroupNodeData,
   type SubsystemGraphEdge,
 } from './model';
 import { constructColorsFromPierreTheme } from '../pierre/constructColors';
@@ -70,7 +73,7 @@ export interface SubsystemGraphCallbacks {
 /** Root callbacks carried through node data (injected by the graph component). */
 export const SUBSYSTEM_CALLBACKS: SubsystemGraphCallbacks = {};
 
-export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
+export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeData, 'subsystem-component'>>) {
   const { theme, mode } = useTheme();
   const { data, selected, width: nodeWidth, height: nodeHeight } = props;
   const c = data.component;
@@ -267,6 +270,65 @@ export function SubsystemComponentNode(props: NodeProps<SubsystemGraphNode>) {
   );
 }
 
+/**
+ * Process boundary frame — a React Flow parent node. Members render inside
+ * via `parentId`; this draws the labeled container only (no handles, no
+ * selection). The border color derives deterministically from the process key
+ * so each deployment unit reads as its own region.
+ */
+export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData, 'subsystem-group'>>) {
+  const { theme } = useTheme();
+  const { data, width, height, selected } = props as unknown as {
+    data: SubsystemGroupNodeData;
+    width?: number;
+    height?: number;
+    selected?: boolean;
+  };
+  const region = data.region;
+  const color = packageColor(region?.key ?? 'process');
+  const dimmed = data.dimmed === true;
+  const hidden = (data as { hidden?: boolean }).hidden === true;
+
+  if (!region) return null;
+
+  return (
+    <div
+      style={{
+        position: 'relative',
+        width: width ?? 400,
+        height: height ?? 300,
+        boxSizing: 'border-box',
+        borderRadius: 12,
+        border: `2px ${selected ? 'solid' : 'dashed'} ${color}`,
+        background: `${color}14`,
+        opacity: hidden ? 0 : dimmed ? 0.35 : 1,
+        transition: 'opacity 150ms ease',
+        pointerEvents: 'none',
+      }}
+    >
+      <div
+        style={{
+          position: 'absolute',
+          top: -13,
+          left: 12,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          fontWeight: 700,
+          letterSpacing: 0.6,
+          color,
+          background: theme.colors.backgroundSecondary ?? theme.colors.background,
+          border: `1px solid ${color}`,
+          borderRadius: 4,
+          padding: '1px 7px',
+          whiteSpace: 'nowrap',
+        }}
+      >
+        {`process: ${region.label}`}
+      </div>
+    </div>
+  );
+}
+
 /** `#rrggbb` + alpha → `#rrggbbaa`. Used to dim a stroke/marker by color so
  *  each opacity gets its own SVG marker id — path `opacity` leaks across every
  *  edge that shares a `url(#marker)` (the focused edge's arrowhead dims). */

package/src/utils/elkLayout.ts

@@ -71,6 +71,14 @@ export interface ElkLayoutOptions {
    * @default 'RIGHT'
    */
   direction?: 'RIGHT' | 'LEFT' | 'DOWN' | 'UP';
+
+  /**
+   * Compound groups — each becomes a nested ELK parent whose `memberIds`
+   * are laid out inside it. Members reference the group via React Flow
+   * `parentId`; ELK returns parent-relative child positions which this
+   * module flattens back to absolute flow coordinates.
+   */
+  groups?: Array<{ id: string; memberIds: string[] }>;
 }
 
 /** Result of ELK layout computation */
@@ -83,6 +91,8 @@ export interface ElkLayoutResult {
   edgeLabelPositions: Map<string, { x: number; y: number }>;
   /** Raw ELK path points per edge (for debugging). */
   edgePathPoints: Map<string, Point[]>;
+  /** Compound parent bounds from ELK (absolute flow coords), keyed by group id. */
+  groupBounds: Map<string, { x: number; y: number; width: number; height: number }>;
 }
 
 /** Point in 2D space */
@@ -102,6 +112,8 @@ interface ElkEdgeSection {
 /** Extended ELK edge with sections */
 interface ElkEdgeWithSections extends ElkExtendedEdge {
   sections?: ElkEdgeSection[];
+  /** Id of the compound node whose coordinate frame sections/labels use. */
+  container?: string;
 }
 
 // Create ELK instance lazily to avoid issues in test environments
@@ -228,6 +240,47 @@ export function calculatePathMidpoint(points: Point[]): Point {
   return points[points.length - 1];
 }
 
+/**
+ * Closest point on a polyline to a target (for snapping labels onto the stroke).
+ */
+export function closestPointOnPath(points: Point[], target: Point): Point {
+  if (points.length === 0) return { x: 0, y: 0 };
+  if (points.length === 1) return points[0];
+
+  let best = points[0];
+  let bestDist = Infinity;
+
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1];
+    const b = points[i];
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const lenSq = dx * dx + dy * dy;
+    const t = lenSq === 0 ? 0 : Math.max(0, Math.min(1, ((target.x - a.x) * dx + (target.y - a.y) * dy) / lenSq));
+    const px = a.x + dx * t;
+    const py = a.y + dy * t;
+    const dist = Math.hypot(target.x - px, target.y - py);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = { x: px, y: py };
+    }
+  }
+
+  return best;
+}
+
+/**
+ * Polyline length in flow-space units (sum of segment lengths).
+ * @public Exported for testing
+ */
+export function calculatePathLength(points: Point[]): number {
+  let total = 0;
+  for (let i = 1; i < points.length; i++) {
+    total += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
+  }
+  return total;
+}
+
 /**
  * Get ELK layout options based on configuration
  */
@@ -447,22 +500,103 @@ export async function computeElkLayout(
     return elkEdge;
   });
 
+  // Partition leaf nodes into compound parents when groups are given.
+  // Group shells themselves are NOT part of `nodes` — they are reconstructed
+  // by the caller from `groupBounds`. Only leaf ids in `memberIds` nest.
+  const groupDefs = (options.groups ?? []).filter((g) => g.memberIds.length > 0);
+  const memberToGroup = new Map<string, string>();
+  const groupedLeafIds = new Set<string>();
+  for (const g of groupDefs) {
+    for (const mid of g.memberIds) {
+      if (!memberToGroup.has(mid)) {
+        memberToGroup.set(mid, g.id);
+        groupedLeafIds.add(mid);
+      }
+    }
+  }
+  const elkById = new Map(elkNodes.map((n) => [n.id, n]));
+  const ungroupedElkNodes: ElkNode[] = [];
+  for (const n of elkNodes) {
+    if (!groupedLeafIds.has(n.id)) ungroupedElkNodes.push(n);
+  }
+  const elkParents: ElkNode[] = [];
+  for (const g of groupDefs) {
+    const children = g.memberIds
+      .map((mid) => elkById.get(mid))
+      .filter((n): n is ElkNode => !!n);
+    // Skip groups with <2 real members — a single-child frame adds noise;
+    // the caller drops the shell and leaves the node top-level.
+    if (children.length < 2) {
+      for (const c of children) ungroupedElkNodes.push(c);
+      memberToGroup.delete(g.memberIds[0]);
+      groupedLeafIds.delete(g.memberIds[0]);
+      continue;
+    }
+    elkParents.push({
+      id: g.id,
+      children,
+      layoutOptions: {
+        'elk.algorithm': 'layered',
+        'elk.direction': direction,
+        'elk.padding': '[top=48,left=24,bottom=24,right=24]',
+        'elk.spacing.nodeNode': '40',
+      },
+    });
+  }
+
   // Create ELK graph
+  const rootOptions = getElkOptions(options);
+  if (elkParents.length > 0) {
+    rootOptions['elk.hierarchyHandling'] = 'INCLUDE_CHILDREN';
+  }
   const elkGraph: ElkNode = {
     id: 'root',
-    layoutOptions: getElkOptions(options),
-    children: elkNodes,
+    layoutOptions: rootOptions,
+    children: [...ungroupedElkNodes, ...elkParents],
     edges: elkEdges,
   };
 
   // Run ELK layout
   const layoutedGraph = await getElkInstance().layout(elkGraph);
 
-  // Build a map of ELK-computed node positions
+  // Build maps of ELK-computed positions. Nested children report
+  // parent-relative coords — flatten to absolute for edges, and keep the
+  // relative form for React Flow children (whose position is parent-relative).
+  // Absolute offset of every ELK node (parents included), accumulated down
+  // the ancestor chain — edge sections/labels are relative to their
+  // `container`, so each edge needs its container's absolute offset.
+  const elkAbsOffsets = new Map<string, { x: number; y: number }>();
   const elkPositions = new Map<string, { x: number; y: number }>();
+  const elkRelativePositions = new Map<string, { x: number; y: number }>();
+  const groupBounds = new Map<string, { x: number; y: number; width: number; height: number }>();
+  const walkElk = (n: ElkNode, ox: number, oy: number) => {
+    const ax = ox + (n.x ?? 0);
+    const ay = oy + (n.y ?? 0);
+    elkAbsOffsets.set(n.id, { x: ax, y: ay });
+    for (const c of n.children ?? []) walkElk(c, ax, ay);
+  };
+  walkElk(layoutedGraph, 0, 0);
   if (layoutedGraph.children) {
     for (const child of layoutedGraph.children) {
-      elkPositions.set(child.id, { x: child.x ?? 0, y: child.y ?? 0 });
+      if (child.children && child.children.length > 0 && groupDefs.some((g) => g.id === child.id)) {
+        const gx = child.x ?? 0;
+        const gy = child.y ?? 0;
+        groupBounds.set(child.id, {
+          x: gx,
+          y: gy,
+          width: child.width ?? 0,
+          height: child.height ?? 0,
+        });
+        for (const grand of child.children) {
+          const rx = grand.x ?? 0;
+          const ry = grand.y ?? 0;
+          elkRelativePositions.set(grand.id, { x: rx, y: ry });
+          elkPositions.set(grand.id, { x: gx + rx, y: gy + ry });
+        }
+      } else {
+        elkPositions.set(child.id, { x: child.x ?? 0, y: child.y ?? 0 });
+        elkRelativePositions.set(child.id, { x: child.x ?? 0, y: child.y ?? 0 });
+      }
     }
   }
 
@@ -486,7 +620,10 @@ export async function computeElkLayout(
         const targetOriginal = targetId ? originalPositions.get(targetId) : null;
         const targetElk = targetId ? elkPositions.get(targetId) : null;
 
-        // Collect all points from sections
+        // Collect all points from sections. Sections (and labels) are
+        // relative to the edge's `container` — intra-group edges live in
+        // the parent's frame, so translate to root-absolute flow coords.
+        const containerOffset = elkAbsOffsets.get(edge.container ?? 'root') ?? { x: 0, y: 0 };
         const allPoints: Point[] = [];
 
         for (const section of edge.sections) {
@@ -496,6 +633,12 @@ export async function computeElkLayout(
           }
           allPoints.push(section.endPoint);
         }
+        if (containerOffset.x !== 0 || containerOffset.y !== 0) {
+          for (const p of allPoints) {
+            p.x += containerOffset.x;
+            p.y += containerOffset.y;
+          }
+        }
 
         // If preserving positions, we need to offset the edge points
         // The edge path is relative to ELK's layout, so we translate it
@@ -531,8 +674,8 @@ export async function computeElkLayout(
           const elkLabel = edge.labels[0];
           // ELK reports the label's top-left; convert to center so screen-space
           // overlays can anchor with translate(-50%, -50%) at any zoom.
-          let lx = (elkLabel.x ?? 0) + (elkLabel.width ?? 0) / 2;
-          let ly = (elkLabel.y ?? 0) + (elkLabel.height ?? 0) / 2;
+          let lx = (elkLabel.x ?? 0) + (elkLabel.width ?? 0) / 2 + containerOffset.x;
+          let ly = (elkLabel.y ?? 0) + (elkLabel.height ?? 0) / 2 + containerOffset.y;
           if (preserveNodePositions && sourceOriginal && sourceElk && targetOriginal && targetElk) {
             const sourceOffset = {
               x: sourceOriginal.x - sourceElk.x,
@@ -550,7 +693,11 @@ export async function computeElkLayout(
             lx += sourceOffset.x + (targetOffset.x - sourceOffset.x) * t;
             ly += sourceOffset.y + (targetOffset.y - sourceOffset.y) * t;
           }
-          edgeLabelPositions.set(edge.id, { x: lx, y: ly });
+          // Snap onto the polyline stroke. ELK's label box can sit slightly
+          // off the route (side selection / reserved label space); we keep
+          // its along-edge placement but center on the actual path.
+          const onPath = closestPointOnPath(allPoints, { x: lx, y: ly });
+          edgeLabelPositions.set(edge.id, onPath);
         }
 
         // For orthogonal routing with preserved positions, the offset can distort
@@ -599,15 +746,17 @@ export async function computeElkLayout(
     }
   }
 
-  // Process nodes (update positions if not preserving)
+  // Process nodes (update positions if not preserving). Grouped children use
+  // parent-relative coords (React Flow child semantics); everything else uses
+  // absolute coords.
   const resultNodes = preserveNodePositions
     ? nodes
     : nodes.map((node) => {
-        const elkNode = layoutedGraph.children?.find((n: ElkNode) => n.id === node.id);
-        if (elkNode && elkNode.x !== undefined && elkNode.y !== undefined) {
+        const rel = elkRelativePositions.get(node.id);
+        if (rel) {
           return {
             ...node,
-            position: { x: elkNode.x, y: elkNode.y },
+            position: { x: rel.x, y: rel.y },
           };
         }
         return node;
@@ -618,6 +767,7 @@ export async function computeElkLayout(
     edgePaths,
     edgeLabelPositions,
     edgePathPoints,
+    groupBounds,
   };
 }