@principal-ai/subsystems-react 0.53.0 → 0.53.1

package/src/subsystem/C4Graph.tsx

@@ -11,7 +11,7 @@
  * drawers, no trail playback.
  */
 
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import {
   Edge,
   EdgeProps,
@@ -26,18 +26,28 @@ import {
   useViewport,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { Box, LayoutGrid } from 'lucide-react';
+import { Box, Minimize2 } from 'lucide-react';
 import { computeElkLayout, pointAlongPath, pointsToSmoothPath } from '../utils/elkLayout';
+import type { CompoundGroupDef } 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 type { TechBrand } from './techIcons';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
 import type { C4Element, C4Model } from './c4';
 
 export interface C4GraphProps {
   model: C4Model;
-  title?: string;
   onSelectNode?: (id: string | null) => void;
+  /**
+   * Drill-down. Called from the expand affordance on a container card; the host
+   * sets `openContainerId` on the model to swap the box for a frame with its
+   * components inside.
+   */
+  onOpenContainer?: (id: string) => void;
+  /** Called from the collapse affordance inside an opened container frame. */
+  onCloseContainer?: () => void;
   /**
    * Breathing room around each card, in flow px, applied as ELK spacing (not by
    * inflating the node box — that left the edge lines starting short of the
@@ -48,21 +58,56 @@ export interface C4GraphProps {
 }
 
 function C4NodeView(
-  props: NodeProps<Node<{ element: C4Element; selected: boolean; componentCount?: number }>>,
+  props: NodeProps<
+    Node<{
+      element: C4Element;
+      selected: boolean;
+      componentCount?: number;
+      onExpand?: () => void;
+      /** This container is the open one: ELK sized the box to hold its components. */
+      open?: boolean;
+      /**
+       * False while the drill-down grow/shrink is in flight. The description is
+       * hidden for the whole animation and only returns once the box settles.
+       */
+      settled?: boolean;
+    }>
+  >,
 ) {
-  const { element, selected, componentCount } = props.data;
+  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 (
-    <C4NodeCard
-      node={element}
-      selected={selected}
-      componentCount={componentCount ?? 0}
-      handles={
-        <>
-          <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
-          <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
-        </>
+    <div
+      style={
+        grown
+          ? { position: 'absolute', top: 0, left: 0, width: props.width, height: props.height }
+          : undefined
       }
-    />
+    >
+      <C4NodeCard
+        node={element}
+        selected={selected}
+        componentCount={componentCount ?? 0}
+        onExpand={onExpand}
+        width={props.width}
+        height={props.height}
+        showDescription={settled !== false}
+        handles={
+          <>
+            <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
+            <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+          </>
+        }
+      />
+    </div>
   );
 }
 
@@ -176,13 +221,46 @@ function C4EdgeView({ data, markerEnd }: EdgeProps<Edge<{ path?: string; color?:
   );
 }
 
-function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'container'; color: string }>>) {
+function C4GroupView(
+  props: NodeProps<
+    Node<{
+      label: string;
+      kind: 'system' | 'container';
+      color: string;
+      onCollapse?: () => void;
+      brand?: TechBrand;
+      /** FLIP: absolute flow rects — where to grow from, and the frame's own. */
+      growFrom?: FlowRect;
+      frameRect?: FlowRect;
+    }>
+  >,
+) {
   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;
+
+  // 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 (
     <div
       style={{
@@ -193,6 +271,9 @@ function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'co
         border: `2px dashed ${color}`,
         background: 'transparent',
         pointerEvents: 'none',
+        transformOrigin: 'top left',
+        transform: grown ? 'none' : `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`,
+        transition: grown ? `transform ${MORPH_MS}ms ease-out` : 'none',
       }}
     >
       <span
@@ -221,8 +302,39 @@ function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'co
           whiteSpace: 'nowrap',
         }}
       >
-        <FrameIcon size={13} strokeWidth={2.25} aria-hidden />
+        {FrameIcon ? (
+          <FrameIcon size={13} strokeWidth={2.25} aria-hidden />
+        ) : brand ? (
+          <TechMark brand={brand} size={14} />
+        ) : null}
         {props.data.label}
+        {onCollapse && (
+          <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,
+            }}
+          >
+            <Minimize2 size={12} strokeWidth={2.5} />
+          </button>
+        )}
       </span>
     </div>
   );
@@ -232,12 +344,44 @@ const nodeTypes = {
   'c4-node': C4NodeView,
   'c4-group': C4GroupView,
 };
-
 const edgeTypes = {
   'c4-edge': C4EdgeView,
 };
 
-function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
+/** Drill-down animation durations, in ms. */
+const MORPH_MS = 420;
+const CAMERA_MS = 520;
+
+/** A fully laid-out open state: the RF nodes/edges and label anchors. */
+interface Rendered {
+  nodes: Node[];
+  edges: Edge[];
+  labelPositions: Map<string, { x: number; y: number }>;
+  groupBounds: Map<string, { x: number; y: number; width: number; height: number }>;
+}
+
+/** Flow-space rect of a box node or a frame, for the drill-down morph. */
+interface FlowRect { x: number; y: number; width: number; height: number }
+
+/** A frame's growth for the drill-down morph: its flow rect before → after. */
+interface FrameGrow { from: FlowRect; to: FlowRect }
+
+/** The container's rect in a laid-out state: its box node, or its frame bounds. */
+function containerRect(layout: Rendered | undefined, id: string): FlowRect | null {
+  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 }: C4GraphProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -248,31 +392,70 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
   const [labelPositions, setLabelPositions] = useState<Map<string, { x: number; y: number }>>(
     () => 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<string, Rendered>());
+  /**
+   * 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<ReturnType<typeof setTimeout> | null>(null);
+  /** The open id rendered last, so a change can morph between the two layouts. */
+  const prevOpenRef = useRef<string | null>(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: string | null) => {
     // 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: C4Element): boolean =>
-      model.view === 'component' ? n.kind !== 'container' : n.kind !== 'component';
+    // component view — or to a container that has been opened.
+    const inView = (n: C4Element): boolean => {
+      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;
+    };
 
-    // How many components each container groups — computed once here because
-    // the card only receives its own element, not the model.
     const childComponentCount = new Map<string, number>();
     for (const n of model.nodes) {
       if (n.kind !== 'component') continue;
@@ -280,200 +463,379 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
       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: Node[] = 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) => ({
+    // 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: CompoundGroupDef[] = 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<string, number>(
       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];
       }),
     );
+    // 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 rfEdges: Edge[] = 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 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: '' },
-      };
-    });
+    const drawnIds = new Set(rfNodes.map((n) => n.id));
+    const rfEdges: Edge[] = 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,
+          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: string | null,
+    inputs: ReturnType<typeof buildInputs>,
+  ): Promise<Rendered> => {
+    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<string, { x: number; y: number }>();
-        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: string): number => {
-          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<string, { x: number; y: number }>();
+    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: string): number => {
+      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: string | undefined): { x: number; y: number } => {
+      if (!id) return { x: 0, y: 0 };
+      const b = shellAbs.get(id);
+      return b ? { x: b.x, y: b.y } : { x: 0, y: 0 };
+    };
 
-        // 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: string | undefined): { x: number; y: number } => {
-          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: Node[] = [...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?.() }
+              : {}),
+          },
         };
+      });
 
-        const shells: Node[] = [...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: string | undefined;
-          if (n.data && typeof n.data === 'object') {
-            const modelNode = (n.data as { element?: C4Element }).element;
-            if (modelNode?.parentId && builtGroups.has(modelNode.parentId)) parentId = modelNode.parentId;
-          }
-          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 }) as Node;
-        });
-
-        setNodes([...shells, ...leaves]);
-        setRfEdges(withPaths);
-        setReady(true);
-        requestAnimationFrame(() => fitView({ padding: 0.15 }));
+    const leaves = rfNodes.map((n) => {
+      const p = positioned.get(n.id);
+      const abs = p ? p.position : n.position;
+      let parentId: string | undefined;
+      if (n.data && typeof n.data === 'object') {
+        const modelNode = (n.data as { element?: C4Element }).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 } : {}),
+      };
+      return (parentId ? { ...node, parentId } : { ...node, parentId: undefined }) as Node;
+    });
+
+    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: Node[], grows: Map<string, FrameGrow> | null): Node[] => {
+    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: Rendered, grows: Map<string, FrameGrow> | null) => {
+    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: Rendered): Map<string, FrameGrow> | null => {
+      if (prevOpen === openId) return null;
+      const prevLayout = layoutCache.current.get(prevOpen ?? '');
+      if (!prevLayout) return null;
+      const grows = new Map<string, FrameGrow>();
+      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;
+        }
+        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],
@@ -497,25 +859,30 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
     [model, selected],
   );
 
+  /** The container currently opened for drill-down, if any. */
+  const openContainerId = model.openContainerId ?? null;
+
   const displayNodes = useMemo(
     () =>
-      nodes.map((n) =>
-        n.type === 'c4-node'
-          ? { ...n, data: { ...n.data, selected: n.id === selectedId } }
-          : n,
-      ),
-    [nodes, selectedId],
+      nodes.map((n) => {
+        if (n.type !== 'c4-node') return n;
+        const element = (n.data as { element?: C4Element } | undefined)?.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],
   );
 
-  // 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 (
     <div style={{ position: 'relative', width: '100%', height: '100%', background: theme.colors.background }}>
       <GraphLayerStyle />
@@ -564,29 +931,6 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
           Laying out C4 view…
         </div>
       )}
-      {title && (
-        <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',
-          }}
-        >
-          {title}
-          <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0], color: muted, marginLeft: 8 }}>
-            {model.view} view · {runtime} {model.view === 'container' ? 'containers' : 'components'} · {outside} outside
-          </span>
-        </div>
-      )}
       {selected && (
         <div
           style={{