@principal-ai/subsystems-react 0.53.0 → 0.53.2

package/dist/subsystem/C4Graph.js

@@ -11,18 +11,43 @@ 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 { useCallback, 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, LayoutGrid } from 'lucide-react';
-import { computeElkLayout, pointAlongPath, pointsToSmoothPath } from '../utils/elkLayout';
+import { Box, Minimize2 } from 'lucide-react';
+import { absoluteBoundsOf, computeElkLayout, flowPositionOf, 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, nodeStyle } 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, componentCount } = props.data;
-    return (_jsx(C4NodeCard, { node: element, selected: selected, componentCount: componentCount ?? 0, 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, growFrom, frameRect } = props.data;
+    const grown = open === true;
+    // Position-only FLIP. The card resizes through its own `width`/`height`
+    // transition, so scaling here would distort the text and fight that transition.
+    // A card that only changed *size* has nothing to slide — no transform and no
+    // transition, so its resize is the card's own and nothing competes with it.
+    const { flipping, placed, dx, dy } = useFlip(growFrom, frameRect);
+    const sliding = flipping && (dx !== 0 || dy !== 0);
+    // 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 }
+                : {}),
+            // Position only — the card's own transition owns the size, so these two
+            // compose without either fighting the other.
+            transformOrigin: 'top left',
+            transform: sliding && !placed ? `translate(${dx}px, ${dy}px)` : 'none',
+            transition: sliding && placed ? `transform ${MORPH_MS}ms ease-out` : 'none',
+        }, children: _jsx(C4NodeCard, { node: element, selected: selected, componentCount: componentCount ?? 0, onExpand: onExpand, width: props.width, height: props.height, showDescription: showDescriptionFor(open, settled), 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.
@@ -100,17 +125,41 @@ function C4GroupView(props) {
     const { theme } = useTheme();
     const color = props.data.color;
     const isSystem = props.data.kind === 'system';
-    // A system frame is the box we draw; a container frame groups components
-    // inside one. Boxes for each, so the badge says which level you are looking at.
-    const FrameIcon = isSystem ? Box : LayoutGrid;
+    const onCollapse = props.data.onCollapse;
+    const brand = props.data.brand;
+    const { growFrom, frameRect } = props.data;
+    // Position-only FLIP, same as the cards. The frame resizes through its own
+    // width/height transition below, so scaling here would fight it *and* distort
+    // what it draws: a scaled dashed border changes weight as it grows, and the
+    // label chip's border and text scale with it.
+    const { flipping, placed, dx, dy } = useFlip(growFrom, frameRect);
+    const sliding = flipping && (dx !== 0 || dy !== 0);
+    // 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%',
+            // ELK's own fitted size, as numbers — the same trick the cards use. At
+            // `100%` this element inherits the React Flow node box, which snaps to
+            // each new layout, and only a scale could disguise that. Transitioning the
+            // numbers grows and shrinks the boundary for real, in both directions, and
+            // keeps the dashed border a constant weight throughout.
+            width: props.width ?? '100%',
+            height: props.height ?? '100%',
+            // Size is always transitioned; the transform only while sliding, and
+            // `transform: none` needs no transition.
+            transition: [
+                'width 420ms ease-out',
+                'height 420ms ease-out',
+                ...(sliding && placed ? [`transform ${MORPH_MS}ms ease-out`] : []),
+            ].join(', '),
             boxSizing: 'border-box',
             borderRadius: 12,
             border: `2px dashed ${color}`,
             background: 'transparent',
             pointerEvents: 'none',
+            transformOrigin: 'top left',
+            transform: sliding && !placed ? `translate(${dx}px, ${dy}px)` : 'none',
         }, children: _jsxs("span", { style: {
                 position: 'absolute',
                 top: 0,
@@ -134,7 +183,24 @@ function C4GroupView(props) {
                 padding: '4px 10px',
                 boxSizing: 'border-box',
                 whiteSpace: 'nowrap',
-            }, children: [_jsx(FrameIcon, { size: 13, strokeWidth: 2.25, "aria-hidden": true }), 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,
@@ -143,7 +209,184 @@ 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;
+/**
+ * When to re-frame the camera after a drill-down: the morph, plus a beat.
+ *
+ * The extra 60ms is not padding for looks. `fitView` reads the system frame's
+ * *measured* size, and that frame's own height transition runs on the same
+ * MORPH_MS clock — so asking on the same tick reads it mid-flight and fits to a
+ * height that never existed. The beat is for React Flow's resize observer to
+ * report the final geometry.
+ */
+const CAMERA_AFTER_MORPH_MS = MORPH_MS + 60;
+/**
+ * Whether committing a layout should also move the camera.
+ *
+ * A morph — a commit that has rects to FLIP from — must not. Every element
+ * already on screen is sliding from the rect the reader last saw it at, and that
+ * anchoring *is* the morph; a viewport move on top of it makes each card's
+ * on-screen path the sum of two independent animations, so nothing lands where
+ * the FLIP said it would. `CAMERA_MS` also outlasts `MORPH_MS`, so the camera
+ * would still be drifting for 100ms after the cards had settled — which is what
+ * reads as the cards "still moving".
+ *
+ * A commit with no `grows` is a genuine change: the first paint, a new system, a
+ * different element set, or the grid fallback after an ELK failure. There is no
+ * continuity to preserve there and the content may genuinely not be on screen, so
+ * fit.
+ *
+ * An *empty* map fits for the same reason — no element is anchoring, so there is
+ * nothing a camera move could contradict. Testing the size rather than the
+ * identity keeps that total over the whole input domain instead of leaning on a
+ * caller convention (`growsFor` happens to hand back `null` rather than an empty
+ * map, but nothing forces it to).
+ *
+ * @param grows the rects to animate from, exactly as `injectGrow` received them.
+ */
+export function shouldRefitCamera(grows) {
+    return !grows || grows.size === 0;
+}
+/**
+ * Whether a card shows its description line.
+ *
+ * Off for the whole morph: the card is resizing under it, so the line would slide
+ * across a moving box.
+ *
+ * And off for good once the container is grown, which is the half that is easy to
+ * get wrong. `settled` alone is not enough — the line comes back the moment the
+ * grow finishes, straight into the space the components now occupy. ELK reserves
+ * header chrome only (`padTop`), never a description, so the returning line does
+ * not push the internals down; it lands on top of the first component.
+ */
+export function showDescriptionFor(open, settled) {
+    return settled === true && open !== true;
+}
+/**
+ * `groupBounds` with every entry in absolute flow coordinates.
+ *
+ * `result.groupBounds` is absolute for a root-level group and *parent-relative*
+ * for a nested one — two spaces in one map, which is the same trap as
+ * `result.nodes`. The opened container is nested (inside the system frame), and
+ * `containerRect` reads this map before the node box, so an unrebased entry would
+ * be handed to the morph offset by the frame's origin: the container would glide
+ * to a place it was never drawn.
+ */
+export function rebaseGroupBoundsAbsolute(result) {
+    const rebased = new Map();
+    for (const [id, b] of result.groupBounds) {
+        // A flat frame has no node of its own, so `absoluteRects` has no entry and
+        // `absoluteBoundsOf` falls back to the entry — already absolute, since it was
+        // synthesized from absolute member bounds.
+        const abs = absoluteBoundsOf(result, id) ?? b;
+        rebased.set(id, { ...b, x: abs.x, y: abs.y });
+    }
+    return rebased;
+}
+/**
+ * The compound groups one open state hands to ELK: the frames it draws, and the
+ * group defs that make ELK lay them out.
+ *
+ * Exported because the nesting here is the load-bearing part and it is invisible
+ * from the rendered output. The opened container sits *inside* the system frame, so
+ * the frame is the origin its contents are laid out from — as a sibling, or as a
+ * flat union, the frame has no stable corner and the whole boundary slides as
+ * ELK re-places its members.
+ */
+export function c4GroupDefs(model, openId) {
+    // 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 } : {}),
+    }));
+    // 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,
+            // INSIDE the system frame, not beside it. The boundary *is* the system, so a
+            // sibling here would draw the opened container outside the very boundary it
+            // belongs to.
+            parentId: model.system.id,
+            // 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,
+            // Drawn as a card, laid out as a group — both are needed, and only ELK knows
+            // which one a bare member id means.
+            drawnAsCard: true,
+        });
+    }
+    return { frames, groups };
+}
+/** 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,
+    };
+}
+/**
+ * FLIP between two absolute flow rects: render transformed back onto `from`,
+ * then release onto `to`.
+ *
+ * The step back **must** happen while rendering, not in an effect. An effect runs
+ * after the browser has already painted, so the element is painted at its new
+ * position for one frame and only then jumps back — a visible teleport, which is
+ * the exact thing this hook exists to remove. Adjusting state during render lets
+ * React apply the transform in the same commit, so the new position is never
+ * painted untransformed.
+ *
+ * The rects are keyed by value: `injectGrow` mints fresh objects each layout, so
+ * comparing identity would re-fire the whole morph on unrelated re-renders.
+ */
+function useFlip(from, to) {
+    const key = from && to ? `${from.x},${from.y},${to.x},${to.y}` : '';
+    const [lastKey, setLastKey] = useState(key);
+    const [placed, setPlaced] = useState(!key);
+    if (key !== lastKey) {
+        setLastKey(key);
+        setPlaced(false);
+    }
+    useEffect(() => {
+        if (!key)
+            return;
+        const raf = requestAnimationFrame(() => setPlaced(true));
+        return () => cancelAnimationFrame(raf);
+    }, [key]);
+    return {
+        flipping: key !== '',
+        placed,
+        dx: from && to ? from.x - to.x : 0,
+        dy: from && to ? from.y - to.y : 0,
+    };
+}
+function Inner({ model, onSelectNode, onOpenContainer, onCloseContainer, gutter = 28 }) {
     const { theme } = useTheme();
     const { fitView } = useReactFlow();
     const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -152,22 +395,73 @@ 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 the whole reveal:
+     * the opened container's components stay hidden, every card drops its
+     * description, and the edges and their labels are withheld — all returning
+     * together 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 post-morph re-frame; see `CAMERA_AFTER_MORPH_MS`. */
+    const cameraTimer = useRef(null);
+    /** The open id rendered last, so a change can morph between the two layouts. */
+    const prevOpenRef = useRef(null);
+    /**
+     * Frame the whole system. Fit the SYSTEM node explicitly rather than the drawn
+     * nodes: on a drill-down those are just the opened container and its components,
+     * so fitting them would zoom to the container instead of the system.
+     */
+    const fitSystem = useCallback(() => {
+        fitView({ padding: 0.15, duration: CAMERA_MS, maxZoom: 1, nodes: [{ id: model.system.id }] });
+    }, [fitView, model.system.id]);
+    // Fit the camera AFTER the new nodes are committed (when `ready` flips true),
+    // so `fitView` measures the real geometry.
+    useEffect(() => {
+        if (!ready || !pendingFitRef.current)
+            return;
+        pendingFitRef.current = false;
+        fitSystem();
+    }, [ready, fitSystem]);
+    /** Called once the new layout is committed, from the layout effect. */
+    const afterLayout = (grows) => {
+        pendingFitRef.current = shouldRefitCamera(grows);
+    };
     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';
-        // How many components each container groups — computed once here because
-        // the card only receives its own element, not the model.
+        // 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')
@@ -176,193 +470,386 @@ function Inner({ model, title, onSelectNode, gutter = 28 }) {
             if (parent)
                 childComponentCount.set(parent, (childComponentCount.get(parent) ?? 0) + 1);
         }
-        // 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).
         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, componentCount: childComponentCount.get(n.id) ?? 0 },
+                ...(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) => ({
-            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);
+        const { frames, groups } = c4GroupDefs(model, openId);
+        // 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.
+        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.
+        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;
+        // The system boundary is a REAL ELK parent: its containers lay out *inside* it,
+        // so ELK owns both the frame's origin and its size. That is what holds the
+        // boundary's top-left corner steady between the two layouts, which is the whole
+        // point of the drill-down. Measured, not assumed — with the frame as a parent,
+        // ELK holds the frame at (12,12) and the opened container at (12,202) across
+        // both layouts, the container growing 150 -> 556 *downward* while its siblings
+        // reflow around it.
+        //
+        // Synthesized as a flat union instead, the boundary had no position of its own:
+        // it inherited its members' top edge, so it slid 206px the moment ELK re-placed
+        // one of them, and the FLIP dutifully animated the slide. A union means we own
+        // the boundary's geometry; a parent means ELK does.
+        //
+        // The component view keeps every frame flat. Its container frames nest *inside*
+        // the system frame, and flattening a group whose parent is a real group would
+        // leave that parent holding a reference to a group ELK never sees.
+        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: model.view === 'component' ? true : new Set(),
             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) } };
+        });
+        // `result.groupBounds` mixes coordinate spaces; everything downstream here
+        // reads it as absolute, so normalize it once at the boundary.
+        const groupBounds = rebaseGroupBoundsAbsolute(result);
+        const builtGroups = new Set(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(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;
+        };
+        // Node positions must live in the same space as the edges and the frames:
+        // absolute. `flowPositionOf` does the one conversion (and the shells below use
+        // the same absolute origin), so nodes, edges and frames cannot disagree.
+        const absBoundsOf = (id) => absoluteBoundsOf(result, id);
+        const parentOriginOf = (id) => {
+            if (!id)
+                return { x: 0, y: 0 };
+            const r = absBoundsOf(id);
+            return r ? { x: r.x, y: r.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.keys()]
+            .sort((a, b) => depthOf(a) - depthOf(b))
+            .map((id) => {
+            const def = groupById.get(id);
+            const parentId = def?.parentId && builtGroups.has(def.parentId) ? def.parentId : undefined;
+            const origin = parentOriginOf(parentId);
+            const b = absBoundsOf(id) ?? { x: 0, y: 0, width: 0, height: 0 };
+            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) => {
+            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;
+            }
+            // `flowPositionOf` covers every node ELK placed; the fallback is for the
+            // pathological case of a node ELK did not return at all.
+            const abs = flowPositionOf(result, n.id, parentId) ??
+                positioned.get(n.id)?.position ??
+                n.position;
+            // 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 ? groupBounds.get(openId) : undefined;
+            const node = {
+                ...n,
+                position: { x: abs.x, y: abs.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);
-                // A container frame borrows its container node's border colour, so a
-                // frame and the box it wraps read as the same thing. Falls back to
-                // the accent when no element matches (e.g. a hand-authored group id).
-                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,
-                    },
-                };
-            });
-            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 });
+        });
+        // `groupBounds`, not `result.groupBounds`: the rebased one. `Rendered` readers
+        // all assume absolute.
+        return { nodes: [...shells, ...leaves], edges: withPaths, labelPositions, groupBounds };
+    };
+    /**
+     * Stamp each growing element's span onto its node, so its view can FLIP from the
+     * old rect to its own. `grows` is keyed by element id, flow-space.
+     */
+    const injectGrow = (nodes, grows) => {
+        if (!grows || grows.size === 0)
+            return nodes;
+        return nodes.map((n) => {
+            const g = grows.get(n.id);
+            // A child is hidden until the morph settles, and its absolute position also
+            // moves with its parent — one transform on the parent covers both.
+            if (!g || n.parentId)
+                return n;
+            return n.type === 'c4-group' || n.type === 'c4-node'
+                ? { ...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(grows);
+    };
+    // 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);
+            // Re-frame once the grow has landed, not while it is running. The drill-down
+            // more than doubles the boundary, so the extent the camera was fitted to no
+            // longer contains the content — but moving *during* the morph compounds with
+            // the FLIP glide, and every card then travels the sum of two animations
+            // instead of the one the FLIP specified (see `shouldRefitCamera`). Waiting
+            // out the morph is the honest way to get both.
+            if (cameraTimer.current)
+                clearTimeout(cameraTimer.current);
+            cameraTimer.current = setTimeout(fitSystem, CAMERA_AFTER_MORPH_MS);
+        }
+        paintedRef.current = true;
+        /**
+         * Every element whose rect changes between the previous and new layouts, so
+         * boundaries *and* cards grow/shrink and slide together. Empty when nothing
+         * changed (e.g. the initial paint).
+         *
+         * Frames alone are not enough: ELK re-lays out the whole diagram, so every
+         * root card moves too. Without a card in this set it keeps its new slot the
+         * instant the layout swaps — a teleport, which is the most visible part of a
+         * bad morph. Child nodes are excluded: they are hidden until the box settles,
+         * so there is nothing to animate, and a transform on them would only fight
+         * the parent's.
+         */
+        const growsFor = (next) => {
+            if (prevOpen === openId)
+                return null;
+            const prevLayout = layoutCache.current.get(prevOpen ?? '');
+            if (!prevLayout)
+                return null;
+            const grows = new Map();
+            const rootCardIds = (l) => l.nodes.filter((n) => !n.parentId).map((n) => n.id);
+            const ids = new Set([
+                ...prevLayout.groupBounds.keys(),
+                ...next.groupBounds.keys(),
+                ...rootCardIds(prevLayout),
+                ...rootCardIds(next),
+            ]);
+            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 }));
+            // A grid's geometry is arbitrary and nothing FLIPped from the previous
+            // layout, so this commit genuinely needs a fit.
+            afterLayout(null);
         });
         return () => {
             alive = false;
+            if (settleTimer.current) {
+                clearTimeout(settleTimer.current);
+                settleTimer.current = null;
+            }
+            // Same for the re-frame: it outlives the effect that armed it, and firing
+            // into an unmounted React Flow instance is a wasted camera move at best.
+            if (cameraTimer.current) {
+                clearTimeout(cameraTimer.current);
+                cameraTimer.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.
@@ -374,14 +861,32 @@ 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;
-    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) => {
+    /** 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]);
+    /**
+     * An edge's polyline is routed for the *settled* layout, so while the cards are
+     * gliding between the two slots the old lines would visibly point at the wrong
+     * boxes. Hiding them for the morph is honest and cheap; interpolating the
+     * polylines to match is not.
+     */
+    const displayEdges = useMemo(() => (settled ? rfEdges : rfEdges.map((e) => ({ ...e, hidden: true }))), [rfEdges, settled]);
+    return (_jsxs("div", { style: { position: 'relative', width: '100%', height: '100%', background: theme.colors.background }, children: [_jsx(GraphLayerStyle, {}), _jsx(ReactFlow, { nodes: displayNodes, edges: displayEdges, nodeTypes: nodeTypes, edgeTypes: edgeTypes, className: GRAPH_CANVAS_CLASS, ...GRAPH_NAV_PROPS, onNodeClick: (_e, node) => {
                     if (node.type !== 'c4-node')
                         return;
                     const next = node.id === selectedId ? null : node.id;
@@ -394,7 +899,7 @@ function Inner({ model, title, onSelectNode, gutter = 28 }) {
                 // Pin the flow to its container. The label overlay is a sibling sized
                 // `inset: 0`, so the two must share an origin or `viewport.y` (measured
                 // in the flow's own box) lands the chips off vertically.
-                style: { width: '100%', height: '100%' }, children: _jsx(GraphChrome, {}) }), ready && labelPositions.size > 0 && (_jsx(C4EdgeLabels, { positions: labelPositions, edges: model.edges })), !ready && (_jsx("div", { style: {
+                style: { width: '100%', height: '100%' }, children: _jsx(GraphChrome, {}) }), ready && settled && labelPositions.size > 0 && (_jsx(C4EdgeLabels, { positions: labelPositions, edges: model.edges })), !ready && (_jsx("div", { style: {
                     position: 'absolute',
                     inset: 0,
                     display: 'flex',
@@ -404,20 +909,7 @@ 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,
-                    // Above the edge-label overlay (zIndex 5).
-                    zIndex: 10,
-                    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,