@principal-ai/subsystems-react 0.52.0 → 0.53.1

package/dist/subsystem/C4Graph.js

@@ -11,17 +11,30 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * `GRAPH_NAV_PROPS` chrome. Deliberately small — no measurement passes, no
  * drawers, no trail playback.
  */
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { Handle, MarkerType, Position, ReactFlow, ReactFlowProvider, useReactFlow, useViewport, } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
+import { Box, Minimize2 } from 'lucide-react';
 import { computeElkLayout, pointAlongPath, pointsToSmoothPath } from '../utils/elkLayout';
 import { EDGE_LABEL_FONT_SIZE, EDGE_LABEL_HEIGHT, C4_LABEL_WIDTH, estimateEdgeLabelWidth } from '../utils/edgeLabel';
-import { protocolColor } from './c4';
-import { C4NodeCard, NODE_H, NODE_W, nodeSize } from './C4NodeCard';
+import { deriveC4Groups, protocolColor } from './c4';
+import { C4NodeCard, NODE_H, NODE_W, OPEN_HEADER_PAD, nodeSize, nodeStyle } from './C4NodeCard';
+import { TechMark, technologyBrand } from './techIcons';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
 function C4NodeView(props) {
-    const { element, selected } = props.data;
-    return (_jsx(C4NodeCard, { node: element, selected: selected, handles: _jsxs(_Fragment, { children: [_jsx(Handle, { type: "target", position: Position.Left, style: { opacity: 0 } }), _jsx(Handle, { type: "source", position: Position.Right, style: { opacity: 0 } })] }) }));
+    const { element, selected, componentCount, onExpand, open, settled } = props.data;
+    const grown = open === true;
+    // The card takes its box from the React Flow node rather than from its own
+    // `nodeSize`, so on the opened container ELK's fitted size drives it — and
+    // because the element persists across the swap, the card's own width/height
+    // transition *is* the grow. No FLIP needed, and no text distortion.
+    //
+    // While grown it is taken out of flow: the node box already carries the layout
+    // (and is what sibling containers and edges are positioned against), so the
+    // card must not compete with it.
+    return (_jsx("div", { style: grown
+            ? { position: 'absolute', top: 0, left: 0, width: props.width, height: props.height }
+            : undefined, children: _jsx(C4NodeCard, { node: element, selected: selected, componentCount: componentCount ?? 0, onExpand: onExpand, width: props.width, height: props.height, showDescription: settled !== false, handles: _jsxs(_Fragment, { children: [_jsx(Handle, { type: "target", position: Position.Left, style: { opacity: 0 } }), _jsx(Handle, { type: "source", position: Position.Right, style: { opacity: 0 } })] }) }) }));
 }
 /**
  * Edge-label overlay.
@@ -98,6 +111,29 @@ function C4EdgeView({ data, markerEnd }) {
 function C4GroupView(props) {
     const { theme } = useTheme();
     const color = props.data.color;
+    const isSystem = props.data.kind === 'system';
+    const onCollapse = props.data.onCollapse;
+    const brand = props.data.brand;
+    const { growFrom, frameRect } = props.data;
+    // FLIP the real frame: start it transformed back onto the box's rect, then
+    // release to identity so it grows into place. `transform-origin: top left`
+    // makes the scale anchor match the absolute rects.
+    const [grown, setGrown] = useState(!growFrom || !frameRect);
+    useEffect(() => {
+        if (!growFrom || !frameRect)
+            return;
+        setGrown(false);
+        const raf = requestAnimationFrame(() => setGrown(true));
+        return () => cancelAnimationFrame(raf);
+    }, [growFrom, frameRect]);
+    const dx = growFrom && frameRect ? growFrom.x - frameRect.x : 0;
+    const dy = growFrom && frameRect ? growFrom.y - frameRect.y : 0;
+    const sx = growFrom && frameRect && frameRect.width ? growFrom.width / frameRect.width : 1;
+    const sy = growFrom && frameRect && frameRect.height ? growFrom.height / frameRect.height : 1;
+    // A container frame shows its technology mark (React/Bun/Node…) so the
+    // boundary says what it is built with, same as the node it wraps. The system
+    // frame has no single technology, so it keeps a neutral `Box`.
+    const FrameIcon = isSystem || !brand ? Box : undefined;
     return (_jsx("div", { style: {
             width: '100%',
             height: '100%',
@@ -106,12 +142,18 @@ function C4GroupView(props) {
             border: `2px dashed ${color}`,
             background: 'transparent',
             pointerEvents: 'none',
-        }, children: _jsx("span", { style: {
+            transformOrigin: 'top left',
+            transform: grown ? 'none' : `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`,
+            transition: grown ? `transform ${MORPH_MS}ms ease-out` : 'none',
+        }, children: _jsxs("span", { style: {
                 position: 'absolute',
                 top: 0,
                 transform: 'translateY(-50%)',
                 left: 12,
                 zIndex: 1,
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: 6,
                 fontFamily: theme.fonts.monospace,
                 fontSize: theme.fontSizes[2],
                 fontWeight: 600,
@@ -126,7 +168,24 @@ function C4GroupView(props) {
                 padding: '4px 10px',
                 boxSizing: 'border-box',
                 whiteSpace: 'nowrap',
-            }, children: props.data.label }) }));
+            }, children: [FrameIcon ? (_jsx(FrameIcon, { size: 13, strokeWidth: 2.25, "aria-hidden": true })) : brand ? (_jsx(TechMark, { brand: brand, size: 14 })) : null, props.data.label, onCollapse && (_jsx("button", { type: "button", onClick: (e) => {
+                        e.stopPropagation();
+                        onCollapse();
+                    }, "aria-label": "Collapse", style: {
+                        pointerEvents: 'auto',
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        width: 18,
+                        height: 18,
+                        marginLeft: 2,
+                        padding: 0,
+                        border: 'none',
+                        background: 'transparent',
+                        color,
+                        cursor: 'pointer',
+                        lineHeight: 1,
+                    }, children: _jsx(Minimize2, { size: 12, strokeWidth: 2.5 }) }))] }) }));
 }
 const nodeTypes = {
     'c4-node': C4NodeView,
@@ -135,7 +194,27 @@ const nodeTypes = {
 const edgeTypes = {
     'c4-edge': C4EdgeView,
 };
-function Inner({ model, title, onSelectNode, gutter = 28 }) {
+/** Drill-down animation durations, in ms. */
+const MORPH_MS = 420;
+const CAMERA_MS = 520;
+/** The container's rect in a laid-out state: its box node, or its frame bounds. */
+function containerRect(layout, id) {
+    if (!layout)
+        return null;
+    const frame = layout.groupBounds.get(id);
+    if (frame)
+        return { x: frame.x, y: frame.y, width: frame.width, height: frame.height };
+    const node = layout.nodes.find((n) => n.id === id);
+    if (!node)
+        return null;
+    return {
+        x: node.position.x,
+        y: node.position.y,
+        width: node.width ?? 0,
+        height: node.height ?? 0,
+    };
+}
+function Inner({ model, onSelectNode, onOpenContainer, onCloseContainer, gutter = 28 }) {
     const { theme } = useTheme();
     const { fitView } = useReactFlow();
     const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -144,198 +223,431 @@ function Inner({ model, title, onSelectNode, gutter = 28 }) {
     const [ready, setReady] = useState(false);
     const [selectedId, setSelectedId] = useState(null);
     const [labelPositions, setLabelPositions] = useState(() => new Map());
+    /** Set by the layout effect; consumed by the `ready` effect to run the fit. */
+    const pendingFitRef = useRef(false);
+    /** Prefetched layouts, keyed by open-container id ('' = closed). */
+    const layoutCache = useRef(new Map());
+    /**
+     * False while the drill-down grow/shrink is in flight. It gates both halves of
+     * the reveal: the opened container's components stay hidden, and every card
+     * drops its description — returning only once the box settles.
+     *
+     * Driven by one timer keyed to MORPH_MS rather than `transitionend`: the grow
+     * is the card's own width/height transition *and* the system frame's
+     * transform, so a DOM event would fire twice per open and gate on the wrong
+     * property.
+     */
+    const [settled, setSettled] = useState(true);
+    /** Set once the first layout has rendered, so only a real change animates. */
+    const paintedRef = useRef(false);
+    /** The in-flight settle timer; cancelled if the open state changes again. */
+    const settleTimer = useRef(null);
+    /** The open id rendered last, so a change can morph between the two layouts. */
+    const prevOpenRef = useRef(null);
+    // Fit the camera AFTER the new nodes are committed (when `ready` flips true),
+    // so `fitView` measures the real geometry. Fit the SYSTEM frame explicitly:
+    // on a drill-down the drawn nodes are just the opened container's contents,
+    // so fitting them would zoom to the container, not the whole system.
+    useEffect(() => {
+        if (!ready || !pendingFitRef.current)
+            return;
+        pendingFitRef.current = false;
+        fitView({ padding: 0.15, duration: CAMERA_MS, maxZoom: 1, nodes: [{ id: model.system.id }] });
+    }, [ready, model.system.id, fitView]);
+    /** Called once the new layout is committed, from the layout effect. */
+    const afterLayout = () => {
+        pendingFitRef.current = true;
+    };
     const layoutKey = useMemo(() => [
         ...model.nodes.map((n) => `${n.id}\0${n.parentId ?? ''}\0${n.label}`).sort(),
-        ...model.groups.map((g) => `${g.id}\0${g.parentId ?? ''}\0${g.memberIds.length}`).sort(),
         ...model.edges.map((e) => `${e.id}\0${e.count}`).sort(),
+        `open:${model.openContainerId ?? ''}`,
     ].join('\n'), [model]);
-    useEffect(() => {
-        let alive = true;
-        setReady(false);
-        setSelectedId(null);
+    /**
+     * Build the React Flow inputs for a given open state — everything ELK needs,
+     * independent of whether a layout has been run yet. Pure over `openId`, so it
+     * serves both the rendered state and the background prefetch.
+     */
+    const buildInputs = (openId) => {
         // Draw only the elements for this view. A container diagram shows the
         // runtime units (containers, externals, people); components belong to the
-        // component view. Components are still carried on the model (see the side
-        // panel), just not drawn here.
-        const inView = (n) => model.view === 'component' ? n.kind !== 'container' : n.kind !== 'component';
-        // Layout against the true card size, so ELK's ports sit on the card's
-        // border — an inflated box leaves the line starting short of the card edge.
-        // The `gutter` becomes ELK spacing instead (see `nodeSpacing` below).
+        // component view — or to a container that has been opened.
+        const inView = (n) => {
+            if (model.view === 'component')
+                return n.kind !== 'container';
+            if (n.kind === 'component')
+                return (n.container ?? n.parentId) === openId;
+            // A container is always drawn — it is a card either way. Opened, it grows
+            // and nests its components; closed, it is the bare box.
+            return true;
+        };
+        const childComponentCount = new Map();
+        for (const n of model.nodes) {
+            if (n.kind !== 'component')
+                continue;
+            const parent = n.container ?? n.parentId;
+            if (parent)
+                childComponentCount.set(parent, (childComponentCount.get(parent) ?? 0) + 1);
+        }
         const rfNodes = model.nodes.filter(inView).map((n, i) => {
             const size = nodeSize(n);
+            // A component of the opened container nests under it (a React Flow child),
+            // so edges between components can be drawn later. Everything else keeps its
+            // authored parentId.
+            const nested = n.kind === 'component' && openId ? openId : undefined;
+            const parentId = nested ?? n.parentId;
             return {
                 id: n.id,
                 type: 'c4-node',
-                // Fallback grid pitch uses the container box — the largest, so the
-                // pre-layout positions never overlap. ELK replaces them on success.
                 position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
                 width: size.width,
                 height: size.height,
-                ...(n.parentId ? { parentId: n.parentId } : {}),
-                data: { element: n, selected: false },
+                ...(parentId ? { parentId } : {}),
+                // Nested cards are separate node divs in the viewport, so they must be
+                // told to paint above the grown container they sit inside — DOM order
+                // follows the model, not the containment.
+                ...(nested ? { zIndex: 2 } : {}),
+                data: {
+                    element: n,
+                    selected: false,
+                    componentCount: childComponentCount.get(n.id) ?? 0,
+                    // A container with components opens; the same affordance closes it
+                    // again, so the toggle lives in one place.
+                    ...(n.kind === 'container' && (childComponentCount.get(n.id) ?? 0) > 0 && onOpenContainer
+                        ? {
+                            onExpand: () => {
+                                if (n.id === openId)
+                                    onCloseContainer?.();
+                                else
+                                    onOpenContainer?.(n.id);
+                            },
+                            open: n.id === openId,
+                        }
+                        : {}),
+                },
             };
         });
-        const groups = model.groups.map((g) => ({
+        // Every frame this layout draws: the system boundary, plus a container frame per
+        // container whose components are in view (the component view leans on these).
+        // The *opened* container's frame is dropped — it is drawn as a grown card
+        // instead, as an ELK parent below.
+        const frames = deriveC4Groups({ ...model, openContainerId: openId }).filter((g) => g.id !== openId);
+        const groups = frames.map((g) => ({
             id: g.id,
             memberIds: g.memberIds,
             ...(g.parentId ? { parentId: g.parentId } : {}),
         }));
-        // Band nodes so a flat layout still reads as C4 and frames can't interleave.
-        //
-        // Flat mode has no ELK parents, so without bands ELK mixes members of
-        // different frames across the whole graph — their synthesized bounding
-        // boxes then overlap. A partition per frame keeps each frame's members
-        // contiguous; people lead, externals trail.
-        //
-        // Order (ascending = earlier in the layout direction): people, then each
-        // frame in model order, then external systems.
-        const frameIds = model.groups.map((g) => g.id);
+        // Opened: the container becomes a real ELK parent so it is sized to hold
+        // its components — the "layout B" the closed layout transitions to. Only in
+        // the container view: that is where a container is a card, and where the
+        // drill-down is offered.
+        const openMembers = model.view === 'container' && openId
+            ? model.nodes
+                .filter((n) => n.kind === 'component' && (n.container ?? n.parentId) === openId)
+                .map((n) => n.id)
+            : [];
+        if (openId && openMembers.length > 0) {
+            groups.push({
+                id: openId,
+                memberIds: openMembers,
+                // Never narrower than the closed card, so opening only ever grows the box.
+                minWidth: NODE_W,
+                // Room for the container's own label slot + technology row.
+                padTop: OPEN_HEADER_PAD,
+            });
+        }
+        // Bands come from the *frames* only. The opened container is an ELK parent,
+        // not a band — treating it as one would push it into its own layer, away from
+        // the containers it belongs beside (and, the system frame being flat, drag
+        // that frame's union across the gap).
+        const frameIds = frames.map((g) => g.id);
         const frameIndex = new Map(frameIds.map((id, i) => [id, i]));
         const partitionByNode = new Map(model.nodes.map((n) => {
             if (n.kind === 'person')
                 return [n.id, 0];
             if (n.kind === 'external-system')
                 return [n.id, frameIds.length + 1];
-            // A node inside a frame shares its frame's band; a frame-less node
-            // (a container at container view) gets its own by id order.
             const band = n.parentId ? (frameIndex.get(n.parentId) ?? 0) : (frameIndex.get(n.id) ?? 0);
             return [n.id, 1 + band];
         }));
-        const rfEdges = model.edges.map((e) => {
-            // Colour keys off the protocol, not the trail verb: on a container
-            // diagram the transport is what a reader distinguishes at a glance.
+        // The compound parent needs its band stated explicitly — partitioning is
+        // activated on the root, and an unset parent falls to partition 0 (the
+        // people band), which would land the opened container outside the frame.
+        const openGroup = openId ? groups.find((g) => g.id === openId) : undefined;
+        if (openId && openGroup)
+            openGroup.partition = partitionByNode.get(openId) ?? 1;
+        const drawnIds = new Set(rfNodes.map((n) => n.id));
+        const rfEdges = model.edges
+            .filter((e) => drawnIds.has(e.source) && drawnIds.has(e.target))
+            .map((e) => {
             const color = protocolColor(e.protocol);
             return {
                 id: e.id,
                 type: 'c4-edge',
                 source: e.source,
                 target: e.target,
-                // The reserved label box and the chip must agree on size, so ELK is
-                // given the same text the chip draws (protocol first, then label). The
-                // chip itself is the C4EdgeLabels overlay, not this field.
                 label: e.protocol ?? e.label,
                 markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
                 data: { edge: e, color, path: '' },
             };
         });
-        void computeElkLayout(rfNodes, rfEdges, {
+        return { rfNodes, rfEdges, groups, partitionByNode, frames };
+    };
+    /**
+     * Run ELK for one open state and turn the result into React Flow nodes /
+     * edges. The heavy step the prefetch caches.
+     */
+    const layoutFor = async (openId, inputs) => {
+        const { rfNodes, rfEdges, groups, partitionByNode, frames } = inputs;
+        // Flatten every frame *except* the opened container. The system frame is
+        // decorative and flattens (one spacing, no nested edge runs); the opened
+        // container has to be a real ELK parent so ELK sizes it to hold its nested
+        // components — that fitted box is "layout B". Both passes are precomputed,
+        // so the drill-down is a swap between two ELK results, not a reflow at click.
+        const result = await computeElkLayout(rfNodes, rfEdges, {
             direction: 'RIGHT',
             preserveNodePositions: false,
             groups,
             keepSingletonGroups: true,
             edgeLabels: { enabled: true, placement: 'CENTER', width: C4_LABEL_WIDTH, measure: estimateEdgeLabelWidth },
-            // The gutter that used to inflate each node box is now real spacing, so
-            // the ports still sit on the card edge.
             nodeSpacing: gutter * 2,
             edgeNodeSpacing: gutter,
-            // Between-layer/between-partition gap. This is what keeps the external
-            // band clear of the system frame's padding — ELK gives partitions zero
-            // default separation. It stacks on top of ELK's reserved label layer, so
-            // it is kept modest.
             interLayerSpacing: 40,
-            // Draw the system frame as a decoration around the boxes rather than an
-            // ELK parent. Nesting made in-frame edges inherit the frame's padding and
-            // spacing, so they ran longer than a root-level edge touching the same
-            // nodes; flattening gives every edge one spacing.
-            flatGroups: true,
+            flatGroups: openId ? new Set(groups.map((g) => g.id).filter((id) => id !== openId)) : true,
             partitionByNode,
-        })
-            .then((result) => {
-            if (!alive)
-                return;
-            const positioned = new Map(result.nodes.map((n) => [n.id, n]));
-            // Draw each edge along ELK's routed polyline and place its label from
-            // the same points — one geometry for the line and the chip.
-            const labelPositions = new Map();
-            const withPaths = rfEdges.map((e) => {
-                const pts = result.edgePathPoints?.get(e.id);
-                if (!pts || pts.length === 0)
-                    return e;
-                labelPositions.set(e.id, pointAlongPath(pts, 0.5));
-                // Rounded corners on ELK's orthogonal route — gentler than raw right
-                // angles, and still the exact polyline the label is placed on.
-                return { ...e, data: { ...e.data, path: pointsToSmoothPath(pts, 12) } };
-            });
-            setLabelPositions(labelPositions);
-            const builtGroups = new Set(result.groupBounds.keys());
-            const groupById = new Map(model.groups.map((g) => [g.id, g]));
-            const depthOf = (id) => {
-                let d = 0;
-                let g = groupById.get(id);
-                while (g?.parentId) {
-                    d += 1;
-                    g = groupById.get(g.parentId);
-                }
-                return d;
+        });
+        const positioned = new Map(result.nodes.map((n) => [n.id, n]));
+        const labelPositions = new Map();
+        const withPaths = rfEdges.map((e) => {
+            const pts = result.edgePathPoints?.get(e.id);
+            if (!pts || pts.length === 0)
+                return e;
+            labelPositions.set(e.id, pointAlongPath(pts, 0.5));
+            return { ...e, data: { ...e.data, path: pointsToSmoothPath(pts, 12) } };
+        });
+        const builtGroups = new Set(result.groupBounds.keys());
+        // The opened container comes back from ELK as a parent, so it lands in
+        // `groupBounds` — but it is drawn as a grown *card*, not a frame. Drop it
+        // from the shells; keep it in `groupBounds` so nested children can take
+        // their coordinates relative to it.
+        const shellBounds = new Map(result.groupBounds);
+        if (openId)
+            shellBounds.delete(openId);
+        const groupById = new Map(frames.map((g) => [g.id, g]));
+        const depthOf = (id) => {
+            let d = 0;
+            let g = groupById.get(id);
+            while (g?.parentId) {
+                d += 1;
+                g = groupById.get(g.parentId);
+            }
+            return d;
+        };
+        const shellAbs = result.groupBounds;
+        const shellOrigin = (id) => {
+            if (!id)
+                return { x: 0, y: 0 };
+            const b = shellAbs.get(id);
+            return b ? { x: b.x, y: b.y } : { x: 0, y: 0 };
+        };
+        // Only the system frame is emitted today (the drill-down's container frames
+        // became grown cards), but the mapping stays keyed off the derived group so a
+        // container frame can come back without reshaping this.
+        const shells = [...shellBounds.entries()]
+            .sort((a, b) => depthOf(a[0]) - depthOf(b[0]))
+            .map(([id, b]) => {
+            const def = groupById.get(id);
+            const parentId = def?.parentId && builtGroups.has(def.parentId) ? def.parentId : undefined;
+            const origin = shellOrigin(parentId);
+            const element = model.nodes.find((n) => n.id === id);
+            const frameColor = def?.kind === 'system'
+                ? (theme.colors.text ?? '#888')
+                : element
+                    ? nodeStyle(element, theme).color
+                    : (theme.colors.accent ?? theme.colors.info);
+            return {
+                id,
+                type: 'c4-group',
+                position: { x: b.x - origin.x, y: b.y - origin.y },
+                width: Math.max(200, b.width),
+                height: Math.max(120, b.height),
+                draggable: false,
+                selectable: false,
+                ...(parentId ? { parentId } : {}),
+                data: {
+                    label: def?.label ?? id,
+                    kind: def?.kind ?? 'container',
+                    color: frameColor,
+                    ...(def?.kind !== 'system' && element
+                        ? { brand: technologyBrand('technology' in element ? element.technology : undefined) }
+                        : {}),
+                    ...(def?.kind === 'container' && openId === id && onCloseContainer
+                        ? { onCollapse: () => onCloseContainer?.() }
+                        : {}),
+                },
             };
-            // Shell positions from flat synthesis are absolute. React Flow reads a
-            // child's `position` as relative to its parent, so a shell nested in
-            // another shell must be made relative to it.
-            const shellAbs = new Map(result.groupBounds);
-            const shellOrigin = (id) => {
-                if (!id)
-                    return { x: 0, y: 0 };
-                const b = shellAbs.get(id);
-                return b ? { x: b.x, y: b.y } : { x: 0, y: 0 };
+        });
+        const leaves = rfNodes.map((n) => {
+            const p = positioned.get(n.id);
+            const abs = p ? p.position : n.position;
+            let parentId;
+            if (n.data && typeof n.data === 'object') {
+                const modelNode = n.data.element;
+                // Only the opened container's own components nest under it — the sibling
+                // containers and out-of-boundary nodes in the same layout must not.
+                const nested = modelNode?.kind === 'component' &&
+                    openId &&
+                    (modelNode.container ?? modelNode.parentId) === openId
+                    ? openId
+                    : undefined;
+                const candidate = nested ?? modelNode?.parentId;
+                if (candidate && builtGroups.has(candidate))
+                    parentId = candidate;
+            }
+            const origin = shellOrigin(parentId);
+            // The opened container is an ELK parent, so its box is whatever ELK fitted
+            // to the nested components — `nodeSize` only knows the closed card.
+            const fitted = openId === n.id ? result.groupBounds.get(openId) : undefined;
+            const node = {
+                ...n,
+                position: { x: abs.x - origin.x, y: abs.y - origin.y },
+                ...(fitted ? { width: fitted.width, height: fitted.height } : {}),
             };
-            const shells = [...result.groupBounds.entries()]
-                .sort((a, b) => depthOf(a[0]) - depthOf(b[0]))
-                .map(([id, b]) => {
-                const def = groupById.get(id);
-                const parentId = def?.parentId && builtGroups.has(def.parentId) ? def.parentId : undefined;
-                const origin = shellOrigin(parentId);
-                return {
-                    id,
-                    type: 'c4-group',
-                    position: { x: b.x - origin.x, y: b.y - origin.y },
-                    width: Math.max(200, b.width),
-                    height: Math.max(120, b.height),
-                    draggable: false,
-                    selectable: false,
-                    ...(parentId ? { parentId } : {}),
-                    data: {
-                        label: def?.label ?? id,
-                        kind: def?.kind ?? 'container',
-                        color: def?.kind === 'system' ? (theme.colors.text ?? '#888') : (theme.colors.accent ?? theme.colors.info),
-                    },
-                };
-            });
-            const leaves = rfNodes.map((n) => {
-                const p = positioned.get(n.id);
-                // Absolute flow position from the flat layout.
-                const abs = p ? p.position : n.position;
-                // Re-parent to the shell this node sits in, if any: a component's
-                // container, or a container's system frame. React Flow positions a
-                // child relative to its parent, so subtract the shell origin.
-                let parentId;
-                if (n.data && typeof n.data === 'object') {
-                    const modelNode = n.data.element;
-                    if (modelNode?.parentId && builtGroups.has(modelNode.parentId))
-                        parentId = modelNode.parentId;
+            return (parentId ? { ...node, parentId } : { ...node, parentId: undefined });
+        });
+        return { nodes: [...shells, ...leaves], edges: withPaths, labelPositions, groupBounds: result.groupBounds };
+    };
+    /**
+     * Stamp each growing frame's span onto its shell node, so its view can FLIP
+     * from the old rect to its own. `grows` is keyed by frame id, flow-space.
+     */
+    const injectGrow = (nodes, grows) => {
+        if (!grows || grows.size === 0)
+            return nodes;
+        return nodes.map((n) => {
+            const g = grows.get(n.id);
+            return n.type === 'c4-group' && g
+                ? { ...n, data: { ...n.data, growFrom: g.from, frameRect: g.to } }
+                : n;
+        });
+    };
+    const renderLayout = (r, grows) => {
+        setNodes(injectGrow(r.nodes, grows));
+        setRfEdges(r.edges);
+        setLabelPositions(r.labelPositions);
+        setReady(true);
+        afterLayout();
+    };
+    // Render the current open state. Uses the prefetched layout when present
+    // (instant swap), else computes it now.
+    useEffect(() => {
+        let alive = true;
+        setReady(false);
+        setSelectedId(null);
+        const openId = model.openContainerId ?? null;
+        const prevOpen = prevOpenRef.current;
+        const inputs = buildInputs(openId);
+        // Only a real open-state change animates; the first paint is already at rest.
+        if (paintedRef.current && prevOpen !== openId) {
+            setSettled(false);
+            if (settleTimer.current)
+                clearTimeout(settleTimer.current);
+            settleTimer.current = setTimeout(() => setSettled(true), MORPH_MS);
+        }
+        paintedRef.current = true;
+        /**
+         * Every frame whose rect changes between the previous and new layouts, so
+         * all boundaries can grow/shrink together (container frames *and* the
+         * system frame). Empty when nothing changed (e.g. the initial paint).
+         */
+        const growsFor = (next) => {
+            if (prevOpen === openId)
+                return null;
+            const prevLayout = layoutCache.current.get(prevOpen ?? '');
+            if (!prevLayout)
+                return null;
+            const grows = new Map();
+            const ids = new Set([...prevLayout.groupBounds.keys(), ...next.groupBounds.keys()]);
+            for (const id of ids) {
+                const fromRect = containerRect(prevLayout, id);
+                const to = containerRect(next, id);
+                if (!fromRect || !to)
+                    continue;
+                if (fromRect.x === to.x &&
+                    fromRect.y === to.y &&
+                    fromRect.width === to.width &&
+                    fromRect.height === to.height) {
+                    continue;
                 }
-                const origin = shellOrigin(parentId);
-                const node = { ...n, position: { x: abs.x - origin.x, y: abs.y - origin.y } };
-                return (parentId ? { ...node, parentId } : { ...node, parentId: undefined });
-            });
-            setNodes([...shells, ...leaves]);
-            setRfEdges(withPaths);
-            setReady(true);
-            requestAnimationFrame(() => fitView({ padding: 0.15 }));
+                grows.set(id, { from: fromRect, to });
+            }
+            return grows.size > 0 ? grows : null;
+        };
+        const cached = layoutCache.current.get(openId ?? '');
+        if (cached) {
+            prevOpenRef.current = openId;
+            renderLayout(cached, growsFor(cached));
+            return () => {
+                alive = false;
+            };
+        }
+        void layoutFor(openId, inputs)
+            .then((r) => {
+            if (!alive)
+                return;
+            layoutCache.current.set(openId ?? '', r);
+            const span = growsFor(r);
+            prevOpenRef.current = openId;
+            renderLayout(r, span);
         })
             .catch((err) => {
             if (!alive)
                 return;
             console.warn('[c4-graph] ELK layout failed, using grid:', err);
-            setNodes(rfNodes);
-            setRfEdges(rfEdges);
+            setNodes(inputs.rfNodes.map((n) => ({ ...n, parentId: undefined })));
+            setRfEdges(inputs.rfEdges);
             setReady(true);
-            requestAnimationFrame(() => fitView({ padding: 0.15 }));
+            afterLayout();
         });
         return () => {
             alive = false;
+            if (settleTimer.current) {
+                clearTimeout(settleTimer.current);
+                settleTimer.current = null;
+            }
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [layoutKey]);
+    // After the first paint, prefetch the opened layout for every container, so a
+    // click swaps to a cached result instead of waiting on ELK.
+    useEffect(() => {
+        if (model.view !== 'container')
+            return;
+        let alive = true;
+        const containers = model.nodes.filter((n) => n.kind === 'container' && model.nodes.some((c) => c.kind === 'component' && (c.container ?? c.parentId) === n.id));
+        void (async () => {
+            for (const c of containers) {
+                if (!alive)
+                    return;
+                if (layoutCache.current.has(c.id))
+                    continue;
+                try {
+                    const inputs = buildInputs(c.id);
+                    const r = await layoutFor(c.id, inputs);
+                    if (!alive)
+                        return;
+                    layoutCache.current.set(c.id, r);
+                }
+                catch {
+                    // Prefetch is best-effort; a miss just falls back to compute-on-click.
+                }
+            }
+        })();
+        return () => {
+            alive = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [layoutKey, model.view]);
     const selected = useMemo(() => model.nodes.find((n) => n.id === selectedId) ?? null, [model, selectedId]);
     /**
      * The components authored inside the selected element, if it is a container.
@@ -347,13 +659,24 @@ function Inner({ model, title, onSelectNode, gutter = 28 }) {
         ? model.nodes.filter((n) => n.kind === 'component' &&
             (n.container === selected.id || n.parentId === selected.id))
         : [], [model, selected]);
-    const displayNodes = useMemo(() => nodes.map((n) => n.type === 'c4-node'
-        ? { ...n, data: { ...n.data, selected: n.id === selectedId } }
-        : n), [nodes, selectedId]);
-    // What the current view draws: runtime units at container level, components
-    // at component level. Mirrors the `inView` filter used for the nodes.
-    const runtime = model.nodes.filter((n) => model.view === 'component' ? n.kind === 'component' : n.kind === 'container').length;
-    const outside = model.nodes.filter((n) => n.kind === 'external-system' || n.kind === 'person').length;
+    /** The container currently opened for drill-down, if any. */
+    const openContainerId = model.openContainerId ?? null;
+    const displayNodes = useMemo(() => nodes.map((n) => {
+        if (n.type !== 'c4-node')
+            return n;
+        const element = n.data?.element;
+        // The nested components are already positioned inside the grown card,
+        // but they only *appear* once the grow settles — otherwise they are
+        // squeezed and clipped mid-animation.
+        const nested = element?.kind === 'component' &&
+            openContainerId != null &&
+            (element.container ?? element.parentId) === openContainerId;
+        return {
+            ...n,
+            ...(nested ? { hidden: !settled } : {}),
+            data: { ...n.data, selected: n.id === selectedId, settled },
+        };
+    }), [nodes, selectedId, settled, openContainerId]);
     return (_jsxs("div", { style: { position: 'relative', width: '100%', height: '100%', background: theme.colors.background }, children: [_jsx(GraphLayerStyle, {}), _jsx(ReactFlow, { nodes: displayNodes, edges: rfEdges, nodeTypes: nodeTypes, edgeTypes: edgeTypes, className: GRAPH_CANVAS_CLASS, ...GRAPH_NAV_PROPS, onNodeClick: (_e, node) => {
                     if (node.type !== 'c4-node')
                         return;
@@ -377,21 +700,13 @@ function Inner({ model, title, onSelectNode, gutter = 28 }) {
                     color: muted,
                     fontFamily: theme.fonts.monospace,
                     fontSize: theme.fontSizes[0],
-                }, children: "Laying out C4 view\u2026" })), title && (_jsxs("div", { style: {
-                    position: 'absolute',
-                    top: 12,
-                    left: 12,
-                    fontSize: theme.fontSizes[2],
-                    fontWeight: 600,
-                    color: theme.colors.text,
-                    background: theme.colors.backgroundSecondary ?? theme.colors.background,
-                    border: `1px solid ${theme.colors.border ?? '#333'}`,
-                    borderRadius: 6,
-                    padding: '4px 10px',
-                }, children: [title, _jsxs("span", { style: { fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0], color: muted, marginLeft: 8 }, children: [model.view, " view \u00B7 ", runtime, " ", model.view === 'container' ? 'containers' : 'components', " \u00B7 ", outside, " outside"] })] })), selected && (_jsxs("div", { style: {
+                }, children: "Laying out C4 view\u2026" })), selected && (_jsxs("div", { style: {
                     position: 'absolute',
                     top: 12,
                     right: 12,
+                    // Above the edge-label overlay (zIndex 5), or chips paint over the
+                    // panel.
+                    zIndex: 10,
                     width: 280,
                     maxHeight: 'calc(100% - 24px)',
                     overflowY: 'auto',