@datalayer/agent-runtimes 1.3.85 → 1.3.87

package/lib/components/teams/A2ATeamGraph.js

@@ -21,11 +21,19 @@ const NOTEBOOK_BALLOON_ROOM = 480;
 const NOTEBOOK_PREVIEW_HEIGHT = 180;
 const GAP = 220;
 const WIDTH = NODE_WIDTH * 2 + GAP;
+/** Between two rows of members. */
+const ROW_GAP = 48;
 /** A connection's node: half a member's. */
 const CONNECTION_WIDTH = NODE_WIDTH / 2;
-/** Between a member and its connections. */
+/** Between a member and its connections, to its right. */
 const CONNECTION_GAP = 44;
 const CONNECTIONS_APART = 16;
+/** Where a member's connections start: right of it. */
+const CONNECTION_X = NODE_WIDTH + CONNECTION_GAP;
+/** Below the character's middle, so the A2A edge leaving it passes above. */
+const CONNECTION_DROP = 12;
+/** What a member's connections take beside it. */
+const CONNECTIONS_BESIDE = CONNECTION_GAP + CONNECTION_WIDTH;
 /** Where the edge leaves and reaches a member: the middle of its character. */
 const HANDLE = (size) => ({
     opacity: 0,
@@ -37,6 +45,50 @@ const HANDLE = (size) => ({
     minHeight: 0,
     border: 0,
 });
+/**
+ * The handles an edge leaves and reaches a member by, named: the middle of
+ * its character on each side, chosen by where the other member stands.
+ */
+export const MEMBER_HANDLES = {
+    inLeft: 'in-left',
+    outRight: 'out-right',
+    inTop: 'in-top',
+    outBottom: 'out-bottom',
+    inRight: 'in-right',
+    outLeft: 'out-left',
+    inBottom: 'in-bottom',
+    outTop: 'out-top',
+    connections: 'connections',
+};
+/**
+ * The handles for an edge from one place to another: rightward across,
+ * leftward across, or down or up when the other member is mostly below or
+ * above.
+ */
+export function handlesBetween(from, to) {
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    if (Math.abs(dx) >= Math.abs(dy)) {
+        return dx >= 0
+            ? {
+                sourceHandle: MEMBER_HANDLES.outRight,
+                targetHandle: MEMBER_HANDLES.inLeft,
+            }
+            : {
+                sourceHandle: MEMBER_HANDLES.outLeft,
+                targetHandle: MEMBER_HANDLES.inRight,
+            };
+    }
+    return dy >= 0
+        ? {
+            sourceHandle: MEMBER_HANDLES.outBottom,
+            targetHandle: MEMBER_HANDLES.inTop,
+        }
+        : {
+            sourceHandle: MEMBER_HANDLES.outTop,
+            targetHandle: MEMBER_HANDLES.inBottom,
+        };
+}
 /**
  * The members as they are now, by id. Not in the nodes' data: a node whose
  * object changes is taken by React Flow for a new one, measured again, and
@@ -72,7 +124,7 @@ const Moving = createContext({
     move: () => undefined,
     reset: () => undefined,
 });
-/** A connection's node id: under its member. */
+/** A connection's node id: beside its member. */
 const connectionNodeId = (member, connection) => `${member}/${connection}`;
 const MemberNode = memo(function MemberNode({ data, }) {
     const { id, side, size } = data;
@@ -159,7 +211,7 @@ const MemberNode = memo(function MemberNode({ data, }) {
             pointerEvents: 'all',
         }, "data-team-member": member.id, "data-member-balloon": shown, "data-member-moved": offset.dx || offset.dy
             ? `${Math.round(offset.dx)},${Math.round(offset.dy)}`
-            : undefined, "data-member-state": persona.state, children: [_jsx(Handle, { type: "target", position: Position.Left, style: HANDLE(size), isConnectable: false }), _jsx(Box, { sx: { width: size, height: size, position: 'relative' }, children: persona.away ? (_jsxs(Button, { size: "small", sx: { position: 'absolute', top: size / 2 - 16, left: -24 }, onClick: () => member.onAway?.(false), children: ["Call ", member.name, " back"] })) : (_jsx(AssistantStage, { character: member.character, state: persona.state, size: size, 
+            : undefined, "data-member-state": persona.state, children: [_jsx(Handle, { id: MEMBER_HANDLES.inLeft, type: "target", position: Position.Left, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.inRight, type: "target", position: Position.Right, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.inTop, type: "target", position: Position.Top, style: { ...HANDLE(size), top: 0 }, isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.inBottom, type: "target", position: Position.Bottom, style: { ...HANDLE(size), top: size }, isConnectable: false }), _jsx(Box, { sx: { width: size, height: size, position: 'relative' }, children: persona.away ? (_jsxs(Button, { size: "small", sx: { position: 'absolute', top: size / 2 - 16, left: -24 }, onClick: () => member.onAway?.(false), children: ["Call ", member.name, " back"] })) : (_jsx(AssistantStage, { character: member.character, state: persona.state, size: size, 
                     // In the node, not over the page; the balloon opens toward the
                     // middle of the graph: rightward from the left member.
                     place: side === 'left'
@@ -236,7 +288,7 @@ const MemberNode = memo(function MemberNode({ data, }) {
                     stayPut: true, 
                     // Named as the member, not its character: `Sales (in your
                     // browser)`; the character describes it.
-                    agentName: member.name, label: memberLabel(member) })) }), _jsxs(Text, { sx: { fontWeight: 600, textAlign: 'center' }, children: [member.emoji ? `${member.emoji} ` : '', member.name] }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', textAlign: 'center' }, "data-member-where": "", children: member.where }), _jsx(Handle, { type: "source", position: Position.Right, style: HANDLE(size), isConnectable: false }), member.connections?.length ? (_jsx(Handle, { id: "connections", type: "source", position: Position.Bottom, style: { ...HANDLE(size), top: 'auto', bottom: 0 }, isConnectable: false })) : null] }));
+                    agentName: member.name, label: memberLabel(member) })) }), _jsxs(Text, { sx: { fontWeight: 600, textAlign: 'center' }, children: [member.emoji ? `${member.emoji} ` : '', member.name] }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', textAlign: 'center' }, "data-member-where": "", children: member.where }), _jsx(Handle, { id: MEMBER_HANDLES.outRight, type: "source", position: Position.Right, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outLeft, type: "source", position: Position.Left, style: HANDLE(size), isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outBottom, type: "source", position: Position.Bottom, style: { ...HANDLE(size), top: size }, isConnectable: false }), _jsx(Handle, { id: MEMBER_HANDLES.outTop, type: "source", position: Position.Top, style: { ...HANDLE(size), top: 0 }, isConnectable: false }), member.connections?.length ? (_jsx(Handle, { id: MEMBER_HANDLES.connections, type: "source", position: Position.Right, style: { ...HANDLE(size), left: 'auto', right: 0 }, isConnectable: false })) : null] }));
 });
 /** A member's accessible name: its name, and where it runs. */
 export function memberLabel(member) {
@@ -268,7 +320,7 @@ const ConnectionNode = memo(function ConnectionNode({ id, data, }) {
             gap: '2px',
             cursor: 'default',
             pointerEvents: 'all',
-        }, title: connection.name, "data-team-connection": connection.id, "data-connection-busy": tool ? 'true' : 'false', children: [_jsx(Handle, { type: "target", position: Position.Top, style: { ...HANDLE(0), top: 0 }, isConnectable: false }), _jsx(Box, { as: "button", type: "button", className: tool ? 'a2a-team-connection-busy' : undefined, "aria-label": connectionLabel(connection, owner?.name), "aria-expanded": told, "aria-controls": detailsId, "data-connection-figure": "", onClick: () => setTold(shown => !shown), onKeyDown: (event) => {
+        }, title: connection.name, "data-team-connection": connection.id, "data-connection-busy": tool ? 'true' : 'false', children: [_jsx(Handle, { type: "target", position: Position.Left, style: { ...HANDLE(size), left: 0 }, isConnectable: false }), _jsx(Box, { as: "button", type: "button", className: tool ? 'a2a-team-connection-busy' : undefined, "aria-label": connectionLabel(connection, owner?.name), "aria-expanded": told, "aria-controls": detailsId, "data-connection-figure": "", onClick: () => setTold(shown => !shown), onKeyDown: (event) => {
                     if (event.key === 'Escape' && told) {
                         event.stopPropagation();
                         setTold(false);
@@ -317,14 +369,29 @@ export function flowWords(flow, entry, peer) {
             : '';
 }
 const ARROW = 9;
+/**
+ * An arrowhead at the end a message goes to — the target's when `forward`,
+ * the source's otherwise — pointing along the edge.
+ */
+export function arrowPath(source, target, forward) {
+    const tip = forward ? target : source;
+    const from = forward ? source : target;
+    const length = Math.hypot(tip.x - from.x, tip.y - from.y) || 1;
+    // Along the edge, toward the tip; and across it.
+    const ax = (tip.x - from.x) / length;
+    const ay = (tip.y - from.y) / length;
+    const bx = tip.x - ax * ARROW;
+    const by = tip.y - ay * ARROW;
+    const px = -ay * (ARROW / 1.6);
+    const py = ax * (ARROW / 1.6);
+    return `M ${tip.x},${tip.y} L ${bx + px},${by + py} L ${bx - px},${by - py} Z`;
+}
 const LinkEdge = memo(function LinkEdge({ id, sourceX, sourceY, targetX, targetY, data, }) {
     const flow = data?.flow ?? 'still';
     const path = `M ${sourceX},${sourceY} L ${targetX},${targetY}`;
-    // The arrow at the end the message goes to.
+    // The arrow at the end the message goes to, along the edge.
     const towardPeer = flow === 'asking';
-    const tipX = towardPeer ? targetX : sourceX;
-    const back = towardPeer ? -ARROW : ARROW;
-    const arrow = `M ${tipX},${targetY} L ${tipX + back},${targetY - ARROW / 1.6} L ${tipX + back},${targetY + ARROW / 1.6} Z`;
+    const arrow = arrowPath({ x: sourceX, y: sourceY }, { x: targetX, y: targetY }, towardPeer);
     return (_jsxs(_Fragment, { children: [_jsx(BaseEdge, { id: id, path: path, style: {
                     stroke: data?.connected
                         ? 'var(--borderColor-accent-emphasis, #0969da)'
@@ -358,23 +425,78 @@ export const CallEdge = memo(function CallEdge({ id, sourceX, sourceY, targetX,
 });
 const NODE_TYPES = { member: MemberNode, connection: ConnectionNode };
 const EDGE_TYPES = { a2a: LinkEdge, mcp: CallEdge };
-/** Where a member's connections sit: under it, side by side, centred. */
-function connectionsX(memberX, count) {
-    const row = count * CONNECTION_WIDTH + (count - 1) * CONNECTIONS_APART;
-    const left = memberX + (NODE_WIDTH - row) / 2;
-    return Array.from({ length: count }, (_, at) => left + at * (CONNECTION_WIDTH + CONNECTIONS_APART));
+/** Where a member's connections sit: right of it, one under another from its character's middle. */
+function connectionsY(memberY, size, count, connectionHeight) {
+    const top = memberY + size / 2 + CONNECTION_DROP;
+    return Array.from({ length: count }, (_, at) => top + at * (connectionHeight + CONNECTIONS_APART));
+}
+/** How far down a member's connections reach, from its top; none, 0. */
+function connectionsReach(size, count, connectionHeight) {
+    return count
+        ? size / 2 +
+            CONNECTION_DROP +
+            count * connectionHeight +
+            (count - 1) * CONNECTIONS_APART
+        : 0;
 }
 /** What a member's call says, on its edge and to a screen reader. */
 export function callWords(member, connection, tool) {
     return `${member} calls ${connection.label} · ${toolWords(tool, connection)}`;
 }
-/** The viewport that shows the graph's width whole in a box `width` wide, never larger than drawn. */
-export function teamViewport(width) {
-    const zoom = Math.min(1, width / WIDTH);
-    return { zoom, x: (width - WIDTH * zoom) / 2, y: 0 };
+/** The viewport that shows a graph `drawn` wide whole in a box `width` wide, never larger than drawn. */
+export function teamViewport(width, drawn = WIDTH) {
+    const zoom = Math.min(1, width / drawn);
+    return { zoom, x: (width - drawn * zoom) / 2, y: 0 };
+}
+/**
+ * Where each member stands, as columns and rows: from the positions given
+ * (the distinct `x` values are the columns left to right, the distinct `y`
+ * values the rows top to bottom), or the entry in the first column and the
+ * peers one under another in the second.
+ */
+export function placeMembers(entryId, peerIds, positions) {
+    const ids = [entryId, ...peerIds];
+    const placed = positions ?? {};
+    if (ids.every(id => placed[id])) {
+        const xs = [...new Set(ids.map(id => placed[id].x))].sort((a, b) => a - b);
+        const ys = [...new Set(ids.map(id => placed[id].y))].sort((a, b) => a - b);
+        return {
+            places: Object.fromEntries(ids.map(id => [
+                id,
+                { column: xs.indexOf(placed[id].x), row: ys.indexOf(placed[id].y) },
+            ])),
+            columns: xs.length,
+            rows: ys.length,
+        };
+    }
+    return {
+        places: {
+            [entryId]: { column: 0, row: 0 },
+            ...Object.fromEntries(peerIds.map((id, at) => [id, { column: 1, row: at }])),
+        },
+        columns: peerIds.length ? 2 : 1,
+        rows: Math.max(1, peerIds.length),
+    };
+}
+/** The one flow the graph reports for all its edges: asking before answering before still. */
+export function flowOfAll(flows) {
+    return flows.includes('asking')
+        ? 'asking'
+        : flows.includes('answering')
+            ? 'answering'
+            : 'still';
 }
-/** Draw a team of two over A2A, the link moving with what travels on it. */
-export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size = 96, calls = [], balloonRoom = BALLOON_ROOM, }) {
+const NO_PEERS = [];
+/** Draw a team over A2A, each link moving with what travels on it. */
+export function A2ATeamGraph({ entry, peer, peers: more = NO_PEERS, flow, flows, connected, label = 'A2A', labels, links, positions, size = 96, calls = [], balloonRoom = BALLOON_ROOM, }) {
+    const peers = useMemo(() => [...(peer ? [peer] : []), ...more], [peer, more]);
+    const members = useMemo(() => [entry, ...peers], [entry, peers]);
+    const memberOf = (id) => members.find(member => member.id === id);
+    const flowOf = (peerId) => flows?.[peerId] ??
+        (peer && peerId === peer.id ? (flow ?? 'still') : 'still');
+    const connectedOf = (peerId) => typeof connected === 'boolean' ? connected : Boolean(connected[peerId]);
+    const labelOf = (peerId) => labels?.[peerId] ?? label;
+    const edgesWanted = links ?? peers.map(one => ({ from: entry.id, to: one.id }));
     const box = useRef(null);
     const [width, setWidth] = useState(0);
     useEffect(() => {
@@ -391,7 +513,15 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
         observer.observe(element);
         return () => observer.disconnect();
     }, []);
-    const viewport = useMemo(() => teamViewport(width || WIDTH), [width]);
+    // Where the members stand, as columns and rows, and the width that takes.
+    const peerIds = peers.map(one => one.id);
+    const placing = placeMembers(entry.id, peerIds, positions);
+    const hasConnections = members.some(member => member.connections?.length);
+    // The last column's connections sit beside it, inside the graph.
+    const drawn = Math.max(WIDTH, placing.columns * NODE_WIDTH +
+        (placing.columns - 1) * GAP +
+        (hasConnections ? CONNECTIONS_BESIDE : 0));
+    const viewport = useMemo(() => teamViewport(width || drawn, drawn), [width, drawn]);
     // The members' height: the character, its name and where it runs.
     const memberHeight = size + 56;
     const connectionSize = Math.round(size / 2);
@@ -399,43 +529,46 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
     // and room under it before the graph's edge.
     const connectionHeight = connectionSize + 58;
     // The connections' ids, member by member: the nodes change only when they do.
-    const placed = [entry, peer].map(member => ({
+    const placed = members.map(member => ({
         member: member.id,
         connections: (member.connections ?? []).map(connection => connection.id),
     }));
     const placedKey = JSON.stringify(placed);
-    const hasConnections = placed.some(({ connections }) => connections.length);
     // A notebook in a balloon: more room above the members.
-    const room = [entry, peer].some(member => member.persona.notebook)
+    const room = members.some(member => member.persona.notebook)
         ? Math.max(NOTEBOOK_BALLOON_ROOM, balloonRoom)
         : balloonRoom;
-    const height = Math.ceil((room +
-        memberHeight +
-        (hasConnections ? CONNECTION_GAP + connectionHeight : 0)) *
-        viewport.zoom);
+    // Beside a member, its connections may reach below it: the row takes them.
+    const reach = Math.max(0, ...placed.map(({ connections }) => connectionsReach(size, connections.length, connectionHeight)));
+    const rowHeight = Math.max(memberHeight, reach);
+    const total = room + placing.rows * rowHeight + (placing.rows - 1) * ROW_GAP;
+    const height = Math.ceil(total * viewport.zoom);
+    // Where each member is laid out, before it is moved.
+    const layoutOf = (id) => {
+        const place = placing.places[id] ?? { column: 0, row: 0 };
+        return {
+            x: place.column * (NODE_WIDTH + GAP),
+            y: room + place.row * (rowHeight + ROW_GAP),
+        };
+    };
     // Where the members were moved, kept inside the graph's box.
-    const total = room +
-        memberHeight +
-        (hasConnections ? CONNECTION_GAP + connectionHeight : 0);
     const boundsOf = (id) => {
-        const layoutX = id === entry.id ? 0 : NODE_WIDTH + GAP;
-        const below = placed.find(({ member }) => member === id)?.connections.length
-            ? CONNECTION_GAP + connectionHeight
-            : 0;
+        const layout = layoutOf(id);
+        const count = placed.find(({ member }) => member === id)?.connections.length ?? 0;
+        const beside = count ? CONNECTIONS_BESIDE : 0;
+        const tall = Math.max(memberHeight, connectionsReach(size, count, connectionHeight));
         return {
-            minDx: -layoutX,
-            maxDx: WIDTH - NODE_WIDTH - layoutX,
-            minDy: -room,
-            maxDy: total - room - memberHeight - below,
+            minDx: -layout.x,
+            maxDx: drawn - NODE_WIDTH - beside - layout.x,
+            minDy: -layout.y,
+            maxDy: total - layout.y - tall,
         };
     };
-    const [moved, setMoved] = useState(() => ({
-        [entry.id]: MOVED.get(movedKey(entry.id)) ?? AT_PLACE,
-        [peer.id]: MOVED.get(movedKey(peer.id)) ?? AT_PLACE,
-    }));
+    const [moved, setMoved] = useState(() => Object.fromEntries(members.map(member => [
+        member.id,
+        MOVED.get(movedKey(member.id)) ?? AT_PLACE,
+    ])));
     const offsetOf = (id) => clampOffset(moved[id] ?? AT_PLACE, boundsOf(id));
-    const entryOffset = offsetOf(entry.id);
-    const peerOffset = offsetOf(peer.id);
     const movingValue = {
         zoom: viewport.zoom,
         offsetOf,
@@ -449,66 +582,55 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
             setMoved(current => ({ ...current, [id]: AT_PLACE }));
         },
     };
-    const nodes = useMemo(() => [
+    // Each member's place and move, and its connections: the nodes are made
+    // again only when one of them changes.
+    const layout = members.map(member => {
+        const at = layoutOf(member.id);
+        const offset = offsetOf(member.id);
+        return {
+            id: member.id,
+            x: at.x + offset.dx,
+            y: at.y + offset.dy,
+            // Its balloon opens toward the middle of the graph.
+            side: at.x + NODE_WIDTH / 2 <= drawn / 2
+                ? 'left'
+                : 'right',
+            connections: (member.connections ?? []).map(connection => connection.id),
+        };
+    });
+    const layoutKey = JSON.stringify(layout);
+    const nodes = useMemo(() => JSON.parse(layoutKey).flatMap(({ id, x, y, side, connections }) => [
         {
-            id: entry.id,
+            id,
             type: 'member',
-            position: { x: entryOffset.dx, y: room + entryOffset.dy },
+            position: { x, y },
             width: NODE_WIDTH,
             height: memberHeight,
             draggable: false,
             selectable: false,
             // Above the edge and its label: a balloon overflows its node.
             zIndex: 10,
-            data: { id: entry.id, side: 'left', size },
-        },
-        {
-            id: peer.id,
-            type: 'member',
-            position: {
-                x: NODE_WIDTH + GAP + peerOffset.dx,
-                y: room + peerOffset.dy,
-            },
-            width: NODE_WIDTH,
-            height: memberHeight,
-            draggable: false,
-            selectable: false,
-            zIndex: 10,
-            data: { id: peer.id, side: 'right', size },
+            data: { id, side, size },
         },
-        ...JSON.parse(placedKey).flatMap(({ member, connections }, side) => {
-            // A member's connections move with it.
-            const moveBy = side === 0 ? entryOffset : peerOffset;
-            const xs = connectionsX((side === 0 ? 0 : NODE_WIDTH + GAP) + moveBy.dx, connections.length);
-            return connections.map((connection, at) => ({
-                id: connectionNodeId(member, connection),
+        // A member's connections move with it.
+        ...connections.map((connection, at) => {
+            const ys = connectionsY(y, size, connections.length, connectionHeight);
+            return {
+                id: connectionNodeId(id, connection),
                 type: 'connection',
                 position: {
-                    x: xs[at],
-                    y: room + memberHeight + CONNECTION_GAP + moveBy.dy,
+                    x: x + CONNECTION_X,
+                    y: ys[at],
                 },
                 width: CONNECTION_WIDTH,
                 height: connectionHeight,
                 draggable: false,
                 selectable: false,
                 zIndex: 5,
-                data: { member, connection, size: connectionSize },
-            }));
+                data: { member: id, connection, size: connectionSize },
+            };
         }),
-    ], [
-        entry.id,
-        peer.id,
-        size,
-        room,
-        memberHeight,
-        placedKey,
-        connectionSize,
-        connectionHeight,
-        entryOffset.dx,
-        entryOffset.dy,
-        peerOffset.dx,
-        peerOffset.dy,
-    ]);
+    ]), [layoutKey, size, memberHeight, connectionSize, connectionHeight]);
     // The notebook open under the graph runs on a Pyodide kernel in the page:
     // the entry's sandbox, while it is open.
     const notebookKernel = useSignalValue(teamNotebookKernel);
@@ -526,16 +648,23 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
                 }
                 : { kind: 'browser', status: 'not running' },
         }, [entry, notebookKernel]);
-    const members = useMemo(() => ({ [entry.id]: entryMember, [peer.id]: peer }), [entry.id, entryMember, peer]);
-    const words = flowWords(flow, entry.name, peer.name);
+    const membersById = useMemo(() => ({
+        [entry.id]: entryMember,
+        ...Object.fromEntries(peers.map(one => [one.id, one])),
+    }), [entry.id, entryMember, peers]);
+    // The words for each flow, for the edges and for a screen reader.
+    const wordsOf = (link) => link.from === entry.id
+        ? flowWords(flowOf(link.to), entry.name, memberOf(link.to)?.name ?? link.to)
+        : '';
+    const words = edgesWanted.map(wordsOf).filter(Boolean);
     // The tool each connection is answering now, in words, by its node's id.
     const busy = useMemo(() => {
         const byNode = {};
         const said = [];
         for (const call of calls) {
-            const member = call.member === entry.id ? entry : peer;
-            const connection = member.connections?.find(known => known.id === call.connection);
-            if (!connection || member.id !== call.member) {
+            const member = members.find(one => one.id === call.member);
+            const connection = member?.connections?.find(known => known.id === call.connection);
+            if (!member || !connection) {
                 continue;
             }
             const node = connectionNodeId(member.id, connection.id);
@@ -543,28 +672,35 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
             said.push(callWords(member.name, connection, call.tool));
         }
         return { byNode, said: [...new Set(said)] };
-    }, [calls, entry, peer]);
+    }, [calls, members]);
+    const linkKey = JSON.stringify(edgesWanted.map(link => ({
+        ...link,
+        flow: link.from === entry.id ? flowOf(link.to) : 'still',
+        connected: connectedOf(link.to),
+        label: wordsOf(link)
+            ? `${labelOf(link.to)} · ${wordsOf(link)}`
+            : labelOf(link.to),
+        ...handlesBetween(layoutOf(link.from), layoutOf(link.to)),
+    })));
     const edges = useMemo(() => [
-        {
-            id: `${entry.id}->${peer.id}`,
-            source: entry.id,
-            target: peer.id,
+        ...JSON.parse(linkKey).map(({ from, to, flow: linkFlow, connected: reached, label: said, sourceHandle, targetHandle, }) => ({
+            id: `${from}->${to}`,
+            source: from,
+            sourceHandle,
+            target: to,
+            targetHandle,
             type: 'a2a',
             selectable: false,
             focusable: false,
-            data: {
-                flow,
-                connected,
-                label: words ? `${label} · ${words}` : label,
-            },
-        },
+            data: { flow: linkFlow, connected: reached, label: said },
+        })),
         ...JSON.parse(placedKey).flatMap(({ member, connections }) => connections.map(connection => {
             const node = connectionNodeId(member, connection);
             const calling = busy.byNode[node] ?? '';
             return {
                 id: `${member}->${node}`,
                 source: member,
-                sourceHandle: 'connections',
+                sourceHandle: MEMBER_HANDLES.connections,
                 target: node,
                 type: 'mcp',
                 selectable: false,
@@ -572,9 +708,10 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
                 data: { calling },
             };
         })),
-    ], [entry.id, peer.id, flow, connected, label, words, placedKey, busy]);
-    const heard = [words, ...busy.said].filter(Boolean).join('. ');
-    return (_jsxs(Box, { ref: box, "data-a2a-team-graph": "", "data-a2a-flow": flow, "data-a2a-calls": calls.length, sx: {
+    ], [linkKey, placedKey, busy]);
+    const heard = [...words, ...busy.said].filter(Boolean).join('. ');
+    const flowNow = flowOfAll(peers.map(one => flowOf(one.id)));
+    return (_jsxs(Box, { ref: box, "data-a2a-team-graph": "", "data-a2a-flow": flowNow, "data-a2a-calls": calls.length, "data-a2a-members": members.length, sx: {
             width: '100%',
             height,
             position: 'relative',
@@ -626,8 +763,8 @@ export function A2ATeamGraph({ entry, peer, flow, connected, label = 'A2A', size
                     overflow: 'hidden',
                     clip: 'rect(0 0 0 0)',
                     whiteSpace: 'nowrap',
-                }, children: heard }), _jsx(Moving.Provider, { value: movingValue, children: _jsx(Members.Provider, { value: members, children: _jsx(Busy.Provider, { value: busy.byNode, children: _jsx(ReactFlow, { nodes: nodes, edges: edges, nodeTypes: NODE_TYPES, edgeTypes: EDGE_TYPES, viewport: viewport, nodesDraggable: false, nodesConnectable: false, nodesFocusable: false, edgesFocusable: false, elementsSelectable: false, deleteKeyCode: null, selectionKeyCode: null, multiSelectionKeyCode: null, panOnDrag: false, panOnScroll: false, zoomOnScroll: false, zoomOnPinch: false, zoomOnDoubleClick: false, preventScrolling: false, style: { overflow: 'visible', background: 'transparent' }, 
+                }, children: heard }), _jsx(Moving.Provider, { value: movingValue, children: _jsx(Members.Provider, { value: membersById, children: _jsx(Busy.Provider, { value: busy.byNode, children: _jsx(ReactFlow, { nodes: nodes, edges: edges, nodeTypes: NODE_TYPES, edgeTypes: EDGE_TYPES, viewport: viewport, nodesDraggable: false, nodesConnectable: false, nodesFocusable: false, edgesFocusable: false, elementsSelectable: false, deleteKeyCode: null, selectionKeyCode: null, multiSelectionKeyCode: null, panOnDrag: false, panOnScroll: false, zoomOnScroll: false, zoomOnPinch: false, zoomOnDoubleClick: false, preventScrolling: false, style: { overflow: 'visible', background: 'transparent' }, 
                             // The library is MIT: its credit is not required on the page.
-                            proOptions: { hideAttribution: true }, "aria-label": `${entry.name} and ${peer.name}, over A2A` }) }) }) })] }));
+                            proOptions: { hideAttribution: true }, "aria-label": `${entry.name} and ${peers.map(one => one.name).join(', ')}, over A2A` }) }) }) })] }));
 }
 export default A2ATeamGraph;

package/lib/components/teams/index.d.ts

@@ -16,3 +16,4 @@ export * from './NotebookPreview';
 export * from './sceneTranscript';
 export * from './SceneTranscript';
 export * from './SceneView';
+export * from './sceneStage';

package/lib/components/teams/index.js

@@ -20,3 +20,4 @@ export * from './NotebookPreview';
 export * from './sceneTranscript';
 export * from './SceneTranscript';
 export * from './SceneView';
+export * from './sceneStage';

package/lib/components/teams/sceneStage.d.ts

@@ -0,0 +1,120 @@
+/**
+ * A scene as a page stages it (LOOP A-13, A-15), read from the scene spec
+ * and its team: who is on stage and where each one stands, who asks whom
+ * over A2A, what the entry suggests, and where the members on a runtime are
+ * reached when the scene plays against local servers.
+ *
+ * Pure, so the examples app, the landing and the tests read a scene the
+ * same way.
+ *
+ * @module components/teams/sceneStage
+ */
+import type { AppSpec } from '../../types/agentspecs';
+import type { SceneCastMemberSpec, SceneSpec } from '../../types/scenes';
+import type { TeamSpec } from '../../types/teams';
+/** Who talks to whom over A2A: an edge of the team's graph. */
+export type A2ATeamLink = {
+    /** The member that asks, by its id. */
+    from: string;
+    /** The member asked. */
+    to: string;
+};
+/** A reference without its version: `accounting:0.0.1` is `accounting`. */
+export declare function refId(ref: string): string;
+/** The application a cast member is, from the catalogue, or undefined. */
+export declare function appOfMember(member: Pick<SceneCastMemberSpec, 'app'>): AppSpec | undefined;
+/**
+ * The links of a team over A2A, in the order its members say them: each
+ * member's `talks_to … over: a2a`. A link to a server (over `mcp`) is a
+ * connection, drawn under the member, not an edge between members.
+ */
+export declare function teamLinksOf(team: Pick<TeamSpec, 'agents'> | Pick<SceneSpec, 'cast'>): A2ATeamLink[];
+/** A suggestion the entry offers: a label on its chip, and what is sent. */
+export type SceneSuggestion = {
+    label: string;
+    prompt: string;
+};
+/**
+ * The entry's suggestions: the script's cues, each labelled by the starter
+ * of the entry's Appspec that says the same words, or by its first words.
+ * Without a scene, the starters themselves.
+ */
+export declare function sceneCuesOf(scene: Pick<SceneSpec, 'script'> | undefined, starters: readonly {
+    label: string;
+    message: string;
+}[]): SceneSuggestion[];
+/** One member of a scene, as a page stages it. */
+export type SceneStageMember = {
+    /** Its id in the cast. */
+    id: string;
+    /** The application it is. */
+    app: AppSpec;
+    cast: SceneCastMemberSpec;
+    /** Whether it is the member the audience talks to. */
+    entry: boolean;
+    /** Where its loop turns. */
+    runsIn: 'browser' | 'runtime';
+    /** The variable its address is read from, when it runs on a runtime. */
+    addressVariable?: string;
+    /** Where it stands: fractions of the box, from the stage directions. */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** What its application needs that is not set up, in sentences. */
+    setup: string[];
+};
+/** A scene as a page stages it. */
+export type SceneStage = {
+    scene: SceneSpec;
+    entry: SceneStageMember;
+    /** The members the entry asks over A2A, in the cast's order. */
+    peers: SceneStageMember[];
+    /** Every member, the entry first. */
+    members: SceneStageMember[];
+    /** The edges between members: the team's `talks_to` over A2A. */
+    links: A2ATeamLink[];
+    /** Where each member stands, by its id. */
+    positions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Whose balloon opens first. */
+    opensFirst: string;
+    /** What the audience is told: the line under the title. */
+    assumes: string;
+};
+/**
+ * Read a scene's stage: its members with their applications, who the entry
+ * is and whom it asks, the links, the positions. Refused when a cast member
+ * is an application the catalogue does not have, or the entry is not in the
+ * cast: a page cannot stage what it cannot draw.
+ */
+export declare function sceneStageOf(scene: SceneSpec): SceneStage;
+/** The port the examples serve Accounting on, as `npm run examples` starts it. */
+export declare const ACCOUNTING_PORT = 8767;
+/** The first port `serve_scenes.py` starts a runtime on for the other members. */
+export declare const SCENE_PORTS_FROM = 8768;
+/**
+ * The members on a runtime across the catalogue's scenes, each once, in
+ * the catalogue's order (a scene's cast in its order): what
+ * `examples/sales-accounting-a2a/serve_scenes.py` serves, in that order.
+ */
+export declare function sceneRuntimeMembers(scenes?: readonly SceneSpec[]): string[];
+/**
+ * The port each runtime member is served on locally: Accounting on
+ * {@link ACCOUNTING_PORT}, the others from {@link SCENE_PORTS_FROM} on, in
+ * the order of {@link sceneRuntimeMembers}. `serve_scenes.py` gives the
+ * same ports by the same rule.
+ */
+export declare function sceneRuntimePorts(scenes?: readonly SceneSpec[]): Record<string, number>;
+/** The variable the examples read a member's local address from: `VITE_A2A_CHANGE_DETECTION_URL`. */
+export declare function sceneAddressVariable(appId: string): string;
+/** Where a member is served over A2A on a local runtime at `port`. */
+export declare function localA2AUrl(appId: string, port: number): string;
+/**
+ * Where a member on a runtime is reached by the examples: its variable
+ * (`VITE_A2A_<MEMBER>_URL`) when set in `env`, else the local runtime
+ * `serve_scenes.py` serves it on.
+ */
+export declare function sceneMemberUrl(appId: string, env: Record<string, string | undefined>, ports?: Record<string, number>): string;