@eventcatalog/core 5.0.0-beta.5 → 5.0.0-beta.7

package/eventcatalog/src/features/studio/components/canvas-nodes.tsx

@@ -0,0 +1,79 @@
+import { createContext, memo, useCallback, useContext } from 'react';
+import { NodeResizer, type NodeProps, type NodeTypes } from '@xyflow/react';
+import { DomainCardNode, Note, nodeComponents, SystemGroupNode, type NoteNode as NoteNodeType } from '@eventcatalog/visualiser';
+import { GROUP_TYPES, nodeDefinitions } from '../node-types';
+
+/** How the canvas draws each kind of node: the visualiser's nodes, editable notes and resizable containers */
+
+export type UpdateNodeData = (id: string, updater: (data: Record<string, unknown>) => Record<string, unknown>) => void;
+
+// Notes are edited in place, so their callbacks need to reach the shared design
+export const UpdateNodeDataContext = createContext<UpdateNodeData>(() => {});
+
+// Which container something dragged would drop into, to highlight it
+export const DropTargetContext = createContext<string | null>(null);
+
+// The visualiser types its node components' props as nodes (Node<Data>) rather than React Flow's NodeProps, so
+// they don't type-check as NodeTypes, though that's what React Flow renders them with
+const visualiserNodes = nodeComponents as unknown as NodeTypes;
+const SystemGroupComponent: NodeTypes[string] = SystemGroupNode;
+
+const NoteNode = memo(function NoteNode(props: NodeProps<NoteNodeType>) {
+  const updateNodeData = useContext(UpdateNodeDataContext);
+  const onTextChange = useCallback(
+    (id: string, text: string) => updateNodeData(id, (data) => ({ ...data, text })),
+    [updateNodeData]
+  );
+  const onColorChange = useCallback(
+    (id: string, color: string) => updateNodeData(id, (data) => ({ ...data, color })),
+    [updateNodeData]
+  );
+  return <Note {...props} onTextChange={onTextChange} onColorChange={onColorChange} />;
+});
+
+/**
+ * A domain or system as a container: resizable when selected, highlighted when something's dragged over it.
+ * Like frames in design tools, it's moved and selected by its header, and dragging inside it draws a selection
+ * box (its body lets the pointer through to the canvas: see studio.css).
+ */
+const GroupNode = memo(function GroupNode(props: NodeProps) {
+  const isDropTarget = useContext(DropTargetContext) === props.id;
+  return (
+    <div style={{ width: '100%', height: '100%', position: 'relative' }}>
+      <NodeResizer
+        isVisible={props.selected}
+        minWidth={240}
+        minHeight={160}
+        lineClassName="!border-[rgb(var(--ec-accent))]"
+        handleClassName="!h-2.5 !w-2.5 !rounded-sm !border-2 !bg-[rgb(var(--ec-card-bg))] !border-[rgb(var(--ec-accent))]"
+      />
+      <SystemGroupComponent {...props} />
+      {/* The header (and the badge on its border) */}
+      <div className="ec-group-grip absolute inset-x-0 -top-3 h-[60px] cursor-grab" />
+      {(isDropTarget || props.selected) && (
+        <div
+          className={`pointer-events-none absolute inset-0 rounded-[14px] ${
+            isDropTarget
+              ? 'ring-4 ring-[rgb(var(--ec-accent)/0.5)] bg-[rgb(var(--ec-accent)/0.05)]'
+              : 'ring-2 ring-[rgb(var(--ec-accent)/0.7)]'
+          }`}
+        />
+      )}
+    </div>
+  );
+});
+
+export const nodeTypes: NodeTypes = {
+  ...Object.fromEntries(
+    nodeDefinitions.map((definition) => [
+      definition.type,
+      definition.type === 'note' ? NoteNode : visualiserNodes[definition.type],
+    ])
+  ),
+  // Only dropped in from the catalog
+  system: visualiserNodes.system,
+  'context-domain': DomainCardNode,
+  // Domains and systems as containers
+  [GROUP_TYPES.domain]: GroupNode,
+  [GROUP_TYPES.system]: GroupNode,
+};

package/eventcatalog/src/features/studio/components/icons.ts

@@ -0,0 +1,48 @@
+import type { LucideIcon } from 'lucide-react';
+import {
+  ArrowRightLeft,
+  Bot,
+  Boxes,
+  Database,
+  Globe,
+  Group,
+  Mail,
+  MonitorSmartphone,
+  Search,
+  ServerIcon,
+  StickyNote,
+  User,
+  Zap,
+} from 'lucide-react';
+import { GROUP_TYPES } from '../node-types';
+
+/** How each kind of node, and each catalog collection, looks in the canvas's lists (the colours are each kind's own) */
+export type NodeIcon = { icon: LucideIcon; className: string };
+
+export const NODE_ICONS: Record<string, NodeIcon> = {
+  [GROUP_TYPES.domain]: { icon: Boxes, className: 'text-yellow-500' },
+  [GROUP_TYPES.system]: { icon: Group, className: 'text-violet-600' },
+  service: { icon: ServerIcon, className: 'text-pink-600' },
+  event: { icon: Zap, className: 'text-orange-600' },
+  command: { icon: Mail, className: 'text-blue-600' },
+  query: { icon: Search, className: 'text-green-600' },
+  channel: { icon: ArrowRightLeft, className: 'text-gray-600' },
+  data: { icon: Database, className: 'text-blue-600' },
+  view: { icon: MonitorSmartphone, className: 'text-indigo-600' },
+  externalSystem: { icon: Globe, className: 'text-purple-600' },
+  agent: { icon: Bot, className: 'text-violet-600' },
+  actor: { icon: User, className: 'text-sky-600' },
+  note: { icon: StickyNote, className: 'text-yellow-500' },
+};
+
+/** The catalog's collections, in the order the catalog list shows them, with the icon of the node each becomes */
+export const CATALOG_GROUPS: ({ collection: string; label: string } & NodeIcon)[] = [
+  { collection: 'domains', label: 'Domains', ...NODE_ICONS[GROUP_TYPES.domain] },
+  { collection: 'systems', label: 'Systems', ...NODE_ICONS[GROUP_TYPES.system] },
+  { collection: 'services', label: 'Services', ...NODE_ICONS.service },
+  { collection: 'events', label: 'Events', ...NODE_ICONS.event },
+  { collection: 'commands', label: 'Commands', ...NODE_ICONS.command },
+  { collection: 'queries', label: 'Queries', ...NODE_ICONS.query },
+  { collection: 'channels', label: 'Channels', ...NODE_ICONS.channel },
+  { collection: 'containers', label: 'Data Stores', ...NODE_ICONS.data },
+];

package/eventcatalog/src/features/studio/components/status.ts

@@ -0,0 +1,22 @@
+import type { Status } from '../hooks/use-studio-flow';
+
+/**
+ * Status and destructive colours for the canvas, from the theme's badge colours (EventCatalog has no status
+ * variables), so they follow light, dark and custom themes. Kept here rather than repeated in each component.
+ */
+export const STATUS = {
+  success: { text: 'text-[rgb(var(--ec-badge-color-green-text))]', dot: 'bg-[rgb(var(--ec-badge-color-green-text))]' },
+  warning: { dot: 'bg-[rgb(var(--ec-badge-color-yellow-text))]' },
+  danger: {
+    text: 'text-[rgb(var(--ec-badge-color-red-text))]',
+    dot: 'bg-[rgb(var(--ec-badge-color-red-text))]',
+    hover: 'hover:bg-[rgb(var(--ec-badge-color-red-background))]',
+  },
+} as const;
+
+/** The dot showing whether the canvas is connected */
+export const CONNECTION_DOT: Record<Status, string> = {
+  connected: STATUS.success.dot,
+  connecting: STATUS.warning.dot,
+  disconnected: STATUS.danger.dot,
+};

package/eventcatalog/src/features/studio/edges.ts

@@ -0,0 +1,54 @@
+import type { Connection, Edge, EdgeMarker } from '@xyflow/react';
+
+/** Connections on a canvas, labelled with EventCatalog's wording (e.g. "publishes event", "subscribed by") */
+
+/** Node types that are messages, and their catalog collection */
+export const MESSAGE_COLLECTIONS: Record<string, string> = {
+  event: 'events',
+  command: 'commands',
+  query: 'queries',
+};
+
+export const EDGE_COLOR = '#6b7280';
+export const EDGE_MARKER: EdgeMarker = { type: 'arrowclosed', color: EDGE_COLOR, width: 18, height: 18 };
+
+const PRODUCERS = ['service', 'agent', 'actor', 'externalSystem', 'view'];
+const PRODUCER_LABELS: Record<string, string> = { commands: 'invokes', events: 'publishes \nevent', queries: 'requests' };
+const MESSAGE_LABELS: Record<string, string> = { commands: 'accepts', events: 'subscribed by', queries: 'accepts' };
+
+const getCollection = (sourceType?: string, targetType?: string) =>
+  MESSAGE_COLLECTIONS[sourceType ?? ''] ?? MESSAGE_COLLECTIONS[targetType ?? ''];
+
+export const getEdgeLabel = (sourceType = '', targetType = ''): string => {
+  const sourceCollection = MESSAGE_COLLECTIONS[sourceType];
+  const targetCollection = MESSAGE_COLLECTIONS[targetType];
+
+  if (PRODUCERS.includes(sourceType) && targetCollection) return PRODUCER_LABELS[targetCollection];
+  if (sourceCollection && targetType === 'channel') return 'sent to';
+  if (sourceCollection) return MESSAGE_LABELS[sourceCollection];
+  if (sourceType === 'channel') return 'routes to';
+  if (targetType === 'channel') return 'publishes to';
+  if (targetType === 'data') return 'writes to';
+  if (sourceType === 'data') return 'read by';
+  if (sourceType === 'actor') return 'uses';
+  if (targetType === 'view') return 'serves';
+  if (targetType === 'externalSystem') return 'calls';
+  if (targetType === 'actor') return 'notifies';
+  return '';
+};
+
+/** Message edges get the animated envelope edge from the visualiser, everything else a labelled smooth step edge */
+export const createEdge = (connection: Connection, sourceType?: string, targetType?: string): Edge => {
+  const collection = getCollection(sourceType, targetType);
+  return {
+    id: `edge-${crypto.randomUUID().slice(0, 8)}`,
+    source: connection.source,
+    target: connection.target,
+    sourceHandle: connection.sourceHandle ?? null,
+    targetHandle: connection.targetHandle ?? null,
+    type: collection ? 'animated' : 'smoothstep',
+    label: getEdgeLabel(sourceType, targetType),
+    markerEnd: EDGE_MARKER,
+    data: collection ? { message: { collection } } : {},
+  };
+};

package/eventcatalog/src/features/studio/flow-state.ts

@@ -0,0 +1,92 @@
+import type { Edge, Node, XYPosition } from '@xyflow/react';
+
+/**
+ * The design (nodes and edges) comes from the shared document; some state stays with each person: what they
+ * have selected, what they're dragging and resizing, and the sizes React Flow measured in their browser.
+ */
+export const LOCAL_NODE_KEYS = ['selected', 'dragging', 'resizing', 'measured'] as const satisfies readonly (keyof Node)[];
+export const LOCAL_EDGE_KEYS = ['selected'] as const satisfies readonly (keyof Edge)[];
+
+/** A shared item with the local-only state of the one already shown. Nothing else is kept from the local one. */
+export const withLocalState = <T extends object>(shared: T, local: T | undefined, localKeys: readonly (keyof T)[]): T => {
+  if (!local) return shared;
+  const kept: Partial<T> = {};
+  for (const key of localKeys) if (local[key] !== undefined) kept[key] = local[key];
+  return { ...shared, ...kept };
+};
+
+/**
+ * Applies changes to shared items (by id) to the items shown, keeping every unchanged item as the same object
+ * (so React Flow doesn't re-render it) and the order they were first seen in (new ones go at the end).
+ * `getShared` returns an item's shared value, or undefined if it was deleted. Returns `local` itself when
+ * nothing changed.
+ */
+export const patchShared = <T extends { id: string }>(
+  local: T[],
+  changedIds: Iterable<string>,
+  getShared: (id: string) => T | undefined,
+  localKeys: readonly (keyof T)[]
+): T[] => {
+  const indexById = new Map(local.map((item, index) => [item.id, index]));
+  let next: T[] | undefined;
+  const removed = new Set<string>();
+  const added: T[] = [];
+
+  for (const id of changedIds) {
+    const shared = getShared(id);
+    const index = indexById.get(id);
+    if (!shared) {
+      if (index !== undefined) removed.add(id);
+      continue;
+    }
+    if (index === undefined) {
+      added.push(shared);
+      continue;
+    }
+    next ??= [...local];
+    next[index] = withLocalState(shared, local[index], localKeys);
+  }
+
+  if (!next && removed.size === 0 && added.length === 0) return local;
+  const patched = next ?? local;
+  return [...(removed.size ? patched.filter((item) => !removed.has(item.id)) : patched), ...added];
+};
+
+/** Where nodes being dragged are, by id, until they're dropped (and saved) */
+export type Moves = ReadonlyMap<string, XYPosition>;
+
+const samePosition = (a: XYPosition, b: XYPosition) => a.x === b.x && a.y === b.y;
+
+/**
+ * Nodes moved to the positions given (e.g. where someone else is dragging them), except ones being dragged
+ * here. Returns `nodes` itself when none move.
+ */
+export const withPositions = (nodes: Node[], positions: Moves): Node[] => {
+  if (positions.size === 0) return nodes;
+  let next: Node[] | undefined;
+  nodes.forEach((node, index) => {
+    const position = positions.get(node.id);
+    if (!position || node.dragging || samePosition(position, node.position)) return;
+    next ??= [...nodes];
+    next[index] = { ...node, position };
+  });
+  return next ?? nodes;
+};
+
+/**
+ * After shared changes are applied (`next`, from `previous`): nodes being dragged here stay where they're being
+ * dragged (when they're dropped, the drop is saved and wins). Returns `next` itself when none are.
+ */
+export const keepDragged = (next: Node[], previous: Node[]): Node[] => {
+  if (next === previous) return next;
+  const dragged = new Map(previous.filter((node) => node.dragging).map((node) => [node.id, node.position]));
+  if (dragged.size === 0) return next;
+  let kept: Node[] | undefined;
+  next.forEach((node, index) => {
+    const position = dragged.get(node.id);
+    if (!position || samePosition(position, node.position)) return;
+    kept ??= [...next];
+    kept[index] = { ...node, position };
+  });
+  return kept ?? next;
+};

package/eventcatalog/src/features/studio/grouping.ts

@@ -0,0 +1,133 @@
+import type { Node, XYPosition } from '@xyflow/react';
+import { getNodeSize, isGroupType } from './node-types';
+
+/**
+ * Containers: domains and systems shown as boxes that other nodes sit in.
+ * A node inside one has its parentId, and its position is relative to the container.
+ */
+
+/** Room around what's in a container, and for its header */
+export const GROUP_PADDING = { top: 80, right: 40, bottom: 40, left: 40 };
+
+type Rect = { x: number; y: number; width: number; height: number };
+
+const byId = (nodes: Node[]) => new Map(nodes.map((node) => [node.id, node]));
+
+/** A node's size: as rendered (in the browser), as set (containers, notes), or what its type renders at */
+export const sizeOf = (node: Node) => ({
+  width: node.measured?.width ?? node.width ?? getNodeSize(node.type).width,
+  height: node.measured?.height ?? node.height ?? getNodeSize(node.type).height,
+});
+
+/** Nodes are positioned relative to their container, so walk up the chain to get the canvas position */
+export const getAbsolutePosition = (node: Node, lookup: Map<string, Node>): XYPosition => {
+  const parent = node.parentId ? lookup.get(node.parentId) : undefined;
+  if (!parent) return node.position;
+  const parentPosition = getAbsolutePosition(parent, lookup);
+  return { x: parentPosition.x + node.position.x, y: parentPosition.y + node.position.y };
+};
+
+export const getAbsoluteRect = (node: Node, lookup: Map<string, Node>): Rect => ({
+  ...getAbsolutePosition(node, lookup),
+  ...sizeOf(node),
+});
+
+const getDepth = (node: Node, lookup: Map<string, Node>): number => {
+  const parent = node.parentId ? lookup.get(node.parentId) : undefined;
+  return parent ? 1 + getDepth(parent, lookup) : 0;
+};
+
+const isDescendantOf = (node: Node, ancestorId: string, lookup: Map<string, Node>): boolean => {
+  if (!node.parentId) return false;
+  if (node.parentId === ancestorId) return true;
+  const parent = lookup.get(node.parentId);
+  return parent ? isDescendantOf(parent, ancestorId, lookup) : false;
+};
+
+const containsPoint = (rect: Rect, point: XYPosition) =>
+  point.x >= rect.x && point.x <= rect.x + rect.width && point.y >= rect.y && point.y <= rect.y + rect.height;
+
+/** React Flow needs containers before what's in them in the nodes array */
+export const sortByHierarchy = (nodes: Node[]): Node[] => {
+  const lookup = byId(nodes);
+  return nodes
+    .map((node, index) => ({ node, index, depth: getDepth(node, lookup) }))
+    .sort((a, b) => a.depth - b.depth || a.index - b.index)
+    .map(({ node }) => node);
+};
+
+/** The innermost container under the centre of a node (never itself, or one of its own children) */
+export const findDropTarget = (nodeId: string, nodes: Node[]): Node | undefined => {
+  const lookup = byId(nodes);
+  const node = lookup.get(nodeId);
+  if (!node) return undefined;
+  const rect = getAbsoluteRect(node, lookup);
+  const center = { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+  return nodes
+    .filter((candidate) => isGroupType(candidate.type) && candidate.id !== nodeId && !isDescendantOf(candidate, nodeId, lookup))
+    .filter((candidate) => containsPoint(getAbsoluteRect(candidate, lookup), center))
+    .sort((a, b) => getDepth(b, lookup) - getDepth(a, lookup))[0];
+};
+
+/** The innermost container at a canvas point, for things dropped there */
+export const findGroupAtPoint = (point: XYPosition, nodes: Node[]): Node | undefined => {
+  const lookup = byId(nodes);
+  return nodes
+    .filter((candidate) => isGroupType(candidate.type) && containsPoint(getAbsoluteRect(candidate, lookup), point))
+    .sort((a, b) => getDepth(b, lookup) - getDepth(a, lookup))[0];
+};
+
+/** A node moved into (or out of, without a parentId) a container, staying in the same place on the canvas */
+export const withParent = (node: Node, parentId: string | undefined, nodes: Node[]): Node => {
+  const lookup = byId(nodes);
+  const absolute = getAbsolutePosition(node, lookup);
+  const parent = parentId ? lookup.get(parentId) : undefined;
+  const parentPosition = parent ? getAbsolutePosition(parent, lookup) : { x: 0, y: 0 };
+  const { parentId: _, extent: __, ...rest } = node;
+  return {
+    ...rest,
+    ...(parent && { parentId: parent.id }),
+    position: { x: absolute.x - parentPosition.x, y: absolute.y - parentPosition.y },
+  };
+};
+
+/** A canvas point, relative to a container */
+export const toRelativePosition = (point: XYPosition, parentId: string, nodes: Node[]): XYPosition => {
+  const lookup = byId(nodes);
+  const parent = lookup.get(parentId);
+  if (!parent) return point;
+  const parentPosition = getAbsolutePosition(parent, lookup);
+  return { x: point.x - parentPosition.x, y: point.y - parentPosition.y };
+};
+
+/** Nodes and everything inside them (deleted with their container) */
+export const withDescendants = (ids: string[], nodes: Node[]): Set<string> => {
+  const lookup = byId(nodes);
+  const result = new Set(ids);
+  nodes.forEach((node) => {
+    if (ids.some((id) => isDescendantOf(node, id, lookup))) result.add(node.id);
+  });
+  return result;
+};
+
+/**
+ * The size a container needs to fit what's inside it, never smaller than it is, and how far its children
+ * must shift when some sit above or left of its content area (so the header stays clear).
+ */
+export const fitGroup = (groupId: string, nodes: Node[]) => {
+  const lookup = byId(nodes);
+  const group = lookup.get(groupId);
+  const children = nodes.filter((node) => node.parentId === groupId);
+  if (!group || children.length === 0) return undefined;
+  const rects = children.map((child) => ({ ...child.position, ...sizeOf(child) }));
+  const shift = {
+    x: Math.max(0, GROUP_PADDING.left - Math.min(...rects.map((rect) => rect.x))),
+    y: Math.max(0, GROUP_PADDING.top - Math.min(...rects.map((rect) => rect.y))),
+  };
+  const current = sizeOf(group);
+  return {
+    shift,
+    width: Math.max(current.width, Math.max(...rects.map((rect) => rect.x + rect.width)) + shift.x + GROUP_PADDING.right),
+    height: Math.max(current.height, Math.max(...rects.map((rect) => rect.y + rect.height)) + shift.y + GROUP_PADDING.bottom),
+  };
+};

package/eventcatalog/src/features/studio/hooks/presence-sender.ts

@@ -0,0 +1,46 @@
+import type { Awareness } from 'y-protocols/awareness';
+
+/** About 30 times a second, like Excalidraw and tldraw: smooth for others, without a message on every mousemove */
+export const PRESENCE_INTERVAL_MS = 33;
+
+export type PresenceSender = {
+  /** Share these fields of our presence: straight away if nothing was sent lately, otherwise with the next send */
+  send: (fields: Record<string, unknown>) => void;
+  /** Send anything waiting now (e.g. a node dropped, so the drop isn't behind the drag) */
+  flush: () => void;
+  destroy: () => void;
+};
+
+/**
+ * Our presence (pointer, nodes being dragged, selection, view), sent to everyone at most every interval. Awareness
+ * sends the whole state on every change, so fields changed together (the pointer and the node it drags) go in one
+ * message, and the latest value always goes out (the pointer stops where it really stopped).
+ */
+export function createPresenceSender(awareness: Awareness, intervalMs = PRESENCE_INTERVAL_MS): PresenceSender {
+  let pending: Record<string, unknown> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let lastSent = -Infinity;
+
+  const flush = () => {
+    clearTimeout(timer);
+    timer = undefined;
+    if (!pending) return;
+    const fields = pending;
+    pending = undefined;
+    lastSent = performance.now();
+    awareness.setLocalState({ ...awareness.getLocalState(), ...fields });
+  };
+
+  return {
+    send: (fields) => {
+      pending = { ...pending, ...fields };
+      if (timer) return;
+      timer = setTimeout(flush, Math.max(0, intervalMs - (performance.now() - lastSent)));
+    },
+    flush,
+    destroy: () => {
+      clearTimeout(timer);
+      pending = undefined;
+    },
+  };
+}

package/eventcatalog/src/features/studio/hooks/presence-store.ts

@@ -0,0 +1,115 @@
+import { useSyncExternalStore } from 'react';
+import type { XYPosition } from '@xyflow/react';
+import type { Awareness } from 'y-protocols/awareness';
+
+export type Peer = {
+  clientId: number;
+  name: string;
+  color: string;
+  /** An AI agent (joined over MCP, or working through this tab with WebMCP), rather than a person */
+  agent?: boolean;
+  /** What an agent is doing, e.g. "Adding OrderService" */
+  activity?: string;
+  pointer: XYPosition | null;
+  selection: string[];
+  /** What they're looking at: the canvas position in the middle of their screen, and their zoom */
+  viewport?: { x: number; y: number; zoom: number };
+  /** Where a connection they're dragging starts (agents show theirs) */
+  connecting?: XYPosition | null;
+};
+
+type Listener = () => void;
+
+/**
+ * Who's on a canvas and what they're doing (pointers, selections, views), from Yjs awareness, kept out of React
+ * state: only the components that draw presence subscribe, so a pointer moving doesn't re-render the canvas.
+ * Our own pointer, selection and view are sent to others but don't notify here (nothing here draws them).
+ */
+export type PresenceStore = {
+  subscribe: (listener: Listener) => () => void;
+  /** Everyone, including us and an agent working through this tab. Changes whenever anyone does anything. */
+  getPeers: () => Peer[];
+  /**
+   * Everyone, for lists of who's here: changes only when people join, leave or rename, or agents change what
+   * they're doing (pointers and views in it may be out of date: read getPeers() for those)
+   */
+  getPeople: () => Peer[];
+  /** Show an agent working through this tab (WebMCP), which only this tab sees */
+  setLocalAgent: (agent: Peer | null) => void;
+  destroy: () => void;
+};
+
+const EMPTY: Peer[] = [];
+
+const toPeers = (awareness: Awareness): Peer[] => {
+  const peers: Peer[] = [];
+  awareness.getStates().forEach((state, clientId) => {
+    if (!state.user) return;
+    peers.push({
+      clientId,
+      ...state.user,
+      activity: state.activity,
+      pointer: state.pointer ?? null,
+      selection: state.selection ?? [],
+      viewport: state.viewport,
+      connecting: state.connecting,
+    });
+  });
+  return peers;
+};
+
+// What getPeople() changes on: who people are, what agents are doing, and whether they're on the canvas (a pointer)
+const identity = (peer: Peer) =>
+  [peer.clientId, peer.name, peer.color, peer.agent ? 1 : 0, peer.activity ?? '', peer.pointer ? 1 : 0].join('|');
+
+export function createPresenceStore(awareness: Awareness): PresenceStore {
+  const listeners = new Set<Listener>();
+  let remote = toPeers(awareness);
+  let localAgent: Peer | null = null;
+  let peers = remote;
+  let people = remote;
+  let ownUser = JSON.stringify(awareness.getLocalState()?.user ?? null);
+
+  const update = () => {
+    peers = localAgent ? [...remote, localAgent] : remote;
+    const nextPeople = peers.length ? peers : EMPTY;
+    if (nextPeople.map(identity).join() !== people.map(identity).join()) people = nextPeople;
+    listeners.forEach((listener) => listener());
+  };
+
+  const onChange = ({ added, updated, removed }: { added: number[]; updated: number[]; removed: number[] }) => {
+    const others = [...added, ...updated, ...removed].some((id) => id !== awareness.clientID);
+    const user = JSON.stringify(awareness.getLocalState()?.user ?? null);
+    // Only our own pointer, selection or view changed: nothing shown here changed
+    if (!others && user === ownUser) return;
+    ownUser = user;
+    remote = toPeers(awareness);
+    update();
+  };
+  awareness.on('change', onChange);
+
+  return {
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getPeers: () => peers,
+    getPeople: () => people,
+    setLocalAgent: (agent) => {
+      localAgent = agent;
+      update();
+    },
+    destroy: () => {
+      awareness.off('change', onChange);
+      listeners.clear();
+    },
+  };
+}
+
+const noStore = { subscribe: () => () => {}, getPeers: () => EMPTY, getPeople: () => EMPTY };
+
+/** Everyone on the canvas, re-rendering only when people join, leave, rename or start or stop working */
+export const usePeople = (store: PresenceStore | null) => {
+  const source = store ?? noStore;
+  return useSyncExternalStore(source.subscribe, source.getPeople);
+};