pmx-canvas 0.8.2 → 0.9.0

package/src/client/canvas/graph-geometry.ts

@@ -0,0 +1,195 @@
+import type { Point } from './memory-layout';
+
+/** Painted bounds, collision clearance, ports and Fit share this footprint. */
+export const GRAPH_NODE = { width: 220, height: 96, gap: 64 };
+interface Rect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+export interface GraphRoute {
+  path: string;
+  points: Point[];
+  label?: Point & Rect;
+}
+interface Link {
+  id: string;
+  from: string;
+  to: string;
+  label: string;
+}
+const distance = (a: Point, b: Point) => Math.hypot(a.x - b.x, a.y - b.y);
+const inside = (point: Point, r: Rect) =>
+  point.x > r.left && point.x < r.right && point.y > r.top && point.y < r.bottom;
+
+/** Open-interior intersection: following a rectangle boundary is permitted. */
+function crosses(a: Point, b: Point, r: Rect) {
+  let low = 0,
+    high = 1;
+  for (const [start, delta, min, max] of [
+    [a.x, b.x - a.x, r.left, r.right],
+    [a.y, b.y - a.y, r.top, r.bottom],
+  ]) {
+    if (!delta) {
+      if (start <= min || start >= max) return false;
+    } else {
+      const p = (min - start) / delta,
+        q = (max - start) / delta;
+      low = Math.max(low, Math.min(p, q));
+      high = Math.min(high, Math.max(p, q));
+    }
+  }
+  return low < high && high > 0 && low < 1;
+}
+
+/** Obstacle visibility is shared across routes and independent of zoom/hover. */
+export function graphRoutes(positions: Map<string, Point>, links: Link[]) {
+  // Keep route clearance inside the larger node-spacing gap.
+  const clearance = 8;
+  const boxes = [...positions].map(([key, p]) => ({
+    key,
+    left: p.x - GRAPH_NODE.width / 2 - clearance,
+    right: p.x + GRAPH_NODE.width / 2 + clearance,
+    top: p.y - GRAPH_NODE.height / 2 - clearance,
+    bottom: p.y + GRAPH_NODE.height / 2 + clearance,
+  }));
+  const clear = (a: Point, b: Point) => !boxes.some((r) => crosses(a, b, r));
+  const corners = boxes
+    .flatMap((r) => [
+      { x: r.left, y: r.top },
+      { x: r.right, y: r.top },
+      { x: r.right, y: r.bottom },
+      { x: r.left, y: r.bottom },
+    ])
+    .filter((p) => !boxes.some((r) => inside(p, r)));
+  const neighbors = new Map<number, Array<{ index: number; length: number }>>();
+  const ports = (p: Point, fraction: number) =>
+    [
+      { x: p.x - GRAPH_NODE.width / 2, y: p.y + fraction * GRAPH_NODE.height },
+      { x: p.x + GRAPH_NODE.width / 2, y: p.y + fraction * GRAPH_NODE.height },
+      { x: p.x + fraction * GRAPH_NODE.width, y: p.y - GRAPH_NODE.height / 2 },
+      { x: p.x + fraction * GRAPH_NODE.width, y: p.y + GRAPH_NODE.height / 2 },
+    ].map((port, index) => ({
+      port,
+      stub: {
+        x: port.x + (index === 0 ? -clearance : index === 1 ? clearance : 0),
+        y: port.y + (index === 2 ? -clearance : index === 3 ? clearance : 0),
+      },
+    }));
+  const result = new Map<string, GraphRoute>();
+  const labels: Rect[] = [];
+  const lanes = new Map<string, number>();
+  const pairs = new Map<string, number>();
+  for (const link of links) {
+    const pair = JSON.stringify([link.from, link.to].sort());
+    pairs.set(pair, (pairs.get(pair) ?? 0) + 1);
+  }
+  for (const link of links) {
+    const a = positions.get(link.from)!,
+      b = positions.get(link.to)!;
+    const pair = JSON.stringify([link.from, link.to].sort());
+    const lane = lanes.get(pair) ?? 0;
+    lanes.set(pair, lane + 1);
+    // Distinct boundary ports keep every reciprocal/parallel fact selectable.
+    const fraction = ((lane + 1) / (pairs.get(pair)! + 1) - 0.5) * 0.8;
+    const starts = ports(a, fraction),
+      ends = ports(b, fraction);
+    let points: Point[] | undefined;
+    let best = Infinity;
+    for (const s of starts)
+      for (const t of ends) {
+        const length = distance(s.stub, t.stub);
+        if (length && length < best && clear(s.stub, t.stub)) {
+          best = length;
+          points = [s.port, s.stub, t.stub, t.port];
+        }
+      }
+    if (!points) {
+      const distances = corners.map(() => Infinity),
+        previous = corners.map(() => -1);
+      const origins = corners.map(() => 0),
+        visited = new Set<number>();
+      for (let i = 0; i < corners.length; i++)
+        for (let s = 0; s < starts.length; s++) {
+          const length = distance(starts[s].stub, corners[i]);
+          if (length < distances[i] && clear(starts[s].stub, corners[i])) {
+            distances[i] = length;
+            origins[i] = s;
+          }
+        }
+      let finish = -1,
+        endPort = 0;
+      while (visited.size < corners.length) {
+        let current = -1;
+        for (let i = 0; i < corners.length; i++)
+          if (!visited.has(i) && (current < 0 || distances[i] < distances[current])) current = i;
+        if (current < 0 || distances[current] >= best || !Number.isFinite(distances[current])) break;
+        visited.add(current);
+        for (let t = 0; t < ends.length; t++) {
+          const length = distances[current] + distance(corners[current], ends[t].stub);
+          if (length < best && clear(corners[current], ends[t].stub)) {
+            best = length;
+            finish = current;
+            endPort = t;
+          }
+        }
+        let peers = neighbors.get(current);
+        if (!peers) {
+          peers = corners.flatMap((point, index) =>
+            index !== current && clear(corners[current], point)
+              ? [{ index, length: distance(corners[current], point) }]
+              : [],
+          );
+          neighbors.set(current, peers);
+        }
+        for (const peer of peers)
+          if (distances[current] + peer.length < distances[peer.index]) {
+            distances[peer.index] = distances[current] + peer.length;
+            previous[peer.index] = current;
+            origins[peer.index] = origins[current];
+          }
+      }
+      if (finish >= 0) {
+        const path: Point[] = [];
+        for (let at = finish; at >= 0; at = previous[at]) path.unshift(corners[at]);
+        const s = starts[origins[finish]],
+          t = ends[endPort];
+        points = [s.port, s.stub, ...path, t.stub, t.port];
+      }
+    }
+    if (!points) continue; // Only overlapping footprints can seal every boundary port.
+    const half = Math.max(24, link.label.length * 3.6 + 6);
+    const segments = points
+      .slice(1)
+      .map((point, index) => ({ first: points![index], point, length: distance(points![index], point) }))
+      .filter((segment) => segment.length > 0)
+      .sort((a, b) => b.length - a.length);
+    let label: GraphRoute['label'];
+    // Expand only as needed. Finite obstacles cannot hide a required label forever.
+    for (let radius = 16; link.label && !label; radius += 20) {
+      const candidates = segments.flatMap(({ first, point, length }) =>
+        [0.5, 0.25, 0.75].flatMap((along) =>
+          [-radius, radius].map((offset) => {
+            const x = first.x + (point.x - first.x) * along - ((point.y - first.y) * offset) / length;
+            const y = first.y + (point.y - first.y) * along + ((point.x - first.x) * offset) / length;
+            return { x, y, left: x - half, right: x + half, top: y - 16, bottom: y + 8 };
+          }),
+        ),
+      );
+      label = candidates.find(
+        (p) =>
+          ![...boxes, ...labels].some(
+            (r) => p.left < r.right && p.right > r.left && p.top < r.bottom && p.bottom > r.top,
+          ),
+      );
+    }
+    if (label) labels.push(label);
+    result.set(link.id, {
+      points,
+      path: points.map((p, index) => `${index ? 'L' : 'M'} ${p.x} ${p.y}`).join(' '),
+      label,
+    });
+  }
+  return result;
+}

package/src/client/canvas/graph-model.ts

@@ -0,0 +1,254 @@
+import type { MemoryGraphEdge, MemoryGraphNode } from '../../shared/memory-graph.js';
+import { GRAPH_NODE } from './graph-geometry';
+import type { Point } from './memory-layout';
+
+export type GraphScene =
+  | { kind: 'overview' }
+  | { kind: 'board'; boardId: string }
+  | { kind: 'card'; boardId: string; cardId: string };
+export const graphSceneKey = (scene: GraphScene) => (scene.kind === 'overview' ? 'overview' : JSON.stringify(scene));
+export const pairKey = (a: string, b: string) => JSON.stringify([a, b].sort());
+
+/** Partition original facts once; grouping never changes authored endpoints. */
+export function graphEvidence(edges: MemoryGraphEdge[]) {
+  const pairs = new Map<string, { boardId: string; peerId: string; edges: MemoryGraphEdge[] }>();
+  const internal = new Map<string, number>();
+  const missing: MemoryGraphEdge[] = [];
+  const evidence = edges.filter((edge) => edge.kind !== 'member');
+  for (const edge of evidence) {
+    if (edge.missing) {
+      missing.push(edge);
+      continue;
+    }
+    if (edge.source.boardId === edge.target.boardId) {
+      internal.set(edge.source.boardId, (internal.get(edge.source.boardId) ?? 0) + 1);
+      continue;
+    }
+    const key = pairKey(edge.source.boardId, edge.target.boardId);
+    const pair = pairs.get(key);
+    if (pair) pair.edges.push(edge);
+    else pairs.set(key, { boardId: edge.source.boardId, peerId: edge.target.boardId, edges: [edge] });
+  }
+  return { evidence, pairs, internal, missing };
+}
+
+/** Stable seed, independent of traversal order and the host's random source. */
+function seed(key: string) {
+  let hash = 2166136261;
+  for (let i = 0; i < key.length; i++) hash = Math.imul(hash ^ key.charCodeAt(i), 16777619);
+  return (hash >>> 0) / 4294967296;
+}
+
+function graphAdjacency(keys: string[], edges: ReadonlyArray<{ from: string; to: string; weight?: number }>) {
+  const adjacency = new Map(keys.map((key) => [key, new Map<string, number>()]));
+  // Sort before summing parallel facts so floating-point sums are order-independent too.
+  const links = edges
+    .filter((edge) => edge.from !== edge.to && adjacency.has(edge.from) && adjacency.has(edge.to))
+    .map((edge) => ({ ends: [edge.from, edge.to].sort(), weight: Math.max(0.1, edge.weight ?? 1) }))
+    .sort((a, b) => a.ends[0].localeCompare(b.ends[0]) || a.ends[1].localeCompare(b.ends[1]) || a.weight - b.weight);
+  for (const {
+    ends: [a, b],
+    weight,
+  } of links) {
+    adjacency.get(a)!.set(b, (adjacency.get(a)!.get(b) ?? 0) + weight);
+    adjacency.get(b)!.set(a, (adjacency.get(b)!.get(a) ?? 0) + weight);
+  }
+  return adjacency;
+}
+
+/** Shared forces for the initial solve and interaction, in footprint-normalized coordinates. */
+function graphForce(key: string, positions: Map<string, Point>, keys: string[], neighbors: Map<string, number>) {
+  const point = positions.get(key)!;
+  // Share a gentle pull across links instead of multiplying it by a node's degree.
+  const totalWeight = [...neighbors.values()].reduce((sum, weight) => sum + Math.sqrt(weight), 0);
+  let fx = 0,
+    fy = 0;
+  for (const other of keys) {
+    if (other === key) continue;
+    const peer = positions.get(other)!;
+    const dx = point.x - peer.x || (seed(key) - 0.5) * 0.01;
+    const dy = point.y - peer.y || (seed(`${key}:y`) - 0.5) * 0.01;
+    const distance = Math.max(1, Math.hypot(dx, dy));
+    const repulsion = 14000 / (distance * distance);
+    const weight = neighbors.get(other) ?? 0;
+    const attraction = weight ? ((distance - 290) * 0.006 * Math.sqrt(weight)) / totalWeight : 0;
+    fx += (dx / distance) * (repulsion - attraction);
+    fy += (dy / distance) * (repulsion - attraction);
+    const width = GRAPH_NODE.width + GRAPH_NODE.gap;
+    const height = ((GRAPH_NODE.height + GRAPH_NODE.gap) * GRAPH_NODE.width) / GRAPH_NODE.height;
+    if (Math.abs(dx) < width && Math.abs(dy) < height) {
+      if (width - Math.abs(dx) < height - Math.abs(dy)) fx += Math.sign(dx) * (width - Math.abs(dx)) * 0.2;
+      else fy += Math.sign(dy) * (height - Math.abs(dy)) * 0.2;
+    }
+  }
+  return { x: fx, y: fy };
+}
+
+/** One animation step. The pointer/drop anchor stays fixed while its visible neighbors respond. */
+export function relaxGraphPositions(
+  positions: Map<string, Point>,
+  edges: ReadonlyArray<{ from: string; to: string; weight?: number }>,
+  held: string,
+  cooling: number,
+) {
+  const keys = [...positions.keys()].sort();
+  const adjacency = graphAdjacency(keys, edges);
+  const aspect = GRAPH_NODE.width / GRAPH_NODE.height;
+  const normalized = new Map([...positions].map(([key, point]) => [key, { x: point.x, y: point.y * aspect }]));
+  let movement = 0;
+  for (const key of keys) {
+    if (key === held) continue;
+    const point = normalized.get(key)!;
+    const force = graphForce(key, normalized, keys, adjacency.get(key)!);
+    const step = Math.min(1, 24 / Math.max(1, Math.hypot(force.x, force.y))) * cooling;
+    const dx = force.x * step,
+      dy = (force.y * step) / aspect;
+    positions.set(key, { x: point.x + dx, y: point.y / aspect + dy });
+    movement = Math.max(movement, Math.hypot(dx, dy));
+  }
+  // Resolve rectangular collisions, rather than letting springs seal a node's connection ports.
+  for (const [index, key] of keys.entries())
+    for (const other of keys.slice(index + 1)) {
+      const point = positions.get(key)!,
+        peer = positions.get(other)!;
+      const dx = point.x - peer.x,
+        dy = point.y - peer.y;
+      const width = GRAPH_NODE.width + GRAPH_NODE.gap - Math.abs(dx),
+        height = GRAPH_NODE.height + GRAPH_NODE.gap - Math.abs(dy);
+      if (width <= 0 || height <= 0) continue;
+      const push =
+        width < height ? { x: (Math.sign(dx) || -1) * width, y: 0 } : { x: 0, y: (Math.sign(dy) || -1) * height };
+      const a = other === held ? 1 : 0.5,
+        b = key === held ? 1 : 0.5;
+      if (key !== held) positions.set(key, { x: point.x + push.x * a, y: point.y + push.y * a });
+      if (other !== held) positions.set(other, { x: peer.x - push.x * b, y: peer.y - push.y * b });
+      movement = Math.max(movement, Math.hypot(push.x, push.y));
+    }
+  return movement;
+}
+
+/** Deterministic initial placement; live additions preserve retained coordinates. */
+export function graphPositions(
+  nodes: MemoryGraphNode[],
+  edges: ReadonlyArray<{ from: string; to: string; weight?: number }>,
+  retained: Map<string, Point>,
+): Map<string, Point> {
+  const keys = [...new Set(nodes.map((node) => node.key))].sort();
+  if (keys.every((key) => retained.has(key))) return new Map(keys.map((key) => [key, retained.get(key)!]));
+  const adjacency = graphAdjacency(keys, edges);
+  const components: string[][] = [];
+  const visited = new Set<string>();
+  for (const key of keys) {
+    if (visited.has(key)) continue;
+    const component = [key];
+    visited.add(key);
+    for (const member of component) {
+      for (const neighbor of adjacency.get(member)!.keys()) {
+        if (visited.has(neighbor)) continue;
+        visited.add(neighbor);
+        component.push(neighbor);
+      }
+    }
+    components.push(component.sort());
+  }
+  const positions = new Map<string, Point>();
+  // Solve in footprint-normalized coordinates, then return screen-shaped rectangles.
+  const aspect = GRAPH_NODE.width / GRAPH_NODE.height;
+  for (const key of keys) {
+    const anchor = retained.get(key);
+    if (anchor) positions.set(key, { x: anchor.x, y: anchor.y * aspect });
+  }
+  for (const component of components) {
+    // Grow from anchors (or one seeded root), placing each newcomer near real neighbors.
+    if (!component.some((key) => positions.has(key))) positions.set(component[0], { x: 0, y: 0 });
+    while (component.some((key) => !positions.has(key))) {
+      for (const key of component) {
+        if (positions.has(key)) continue;
+        const neighbors = [...adjacency.get(key)!.keys()].filter((neighbor) => positions.has(neighbor));
+        if (!neighbors.length) continue;
+        positions.set(key, {
+          x:
+            neighbors.reduce((sum, neighbor) => sum + positions.get(neighbor)!.x, 0) / neighbors.length +
+            (seed(key) - 0.5) * 240,
+          y:
+            neighbors.reduce((sum, neighbor) => sum + positions.get(neighbor)!.y, 0) / neighbors.length +
+            (seed(`${key}:y`) - 0.5) * 240,
+        });
+      }
+    }
+    for (let iteration = 0; iteration < 180; iteration++) {
+      const updates = new Map<string, Point>();
+      for (const key of component) {
+        if (retained.has(key)) continue;
+        const point = positions.get(key)!;
+        const { x: fx, y: fy } = graphForce(key, positions, component, adjacency.get(key)!);
+        const step = Math.min(1, 24 / Math.max(1, Math.hypot(fx, fy))) * (1 - iteration / 200);
+        updates.set(key, { x: point.x + fx * step, y: point.y + fy * step });
+      }
+      for (const [key, point] of updates) positions.set(key, point);
+    }
+  }
+  for (const [key, point] of positions) positions.set(key, retained.get(key) ?? { x: point.x, y: point.y / aspect });
+  // Exact footprint clearance after cooling. Anchors always win, even across components.
+  const occupied = keys.filter((key) => retained.has(key)).map((key) => positions.get(key)!);
+  const width = GRAPH_NODE.width + GRAPH_NODE.gap,
+    height = GRAPH_NODE.height + GRAPH_NODE.gap;
+  const overlaps = (a: Point, b: Point) => Math.abs(a.x - b.x) < width && Math.abs(a.y - b.y) < height;
+  let packLeft = 0,
+    packX = 0;
+  let packY = 0,
+    rowHeight = 0;
+  const rowWidth = Math.sqrt(keys.length) * 380;
+  const anchoredComponent = (component: string[]) => component.some((key) => retained.has(key));
+  components.sort((a, b) => Number(anchoredComponent(b)) - Number(anchoredComponent(a)));
+  let packing = false;
+  for (const component of components) {
+    const anchored = anchoredComponent(component);
+    if (!anchored && !packing) {
+      packLeft = occupied.length ? Math.max(...occupied.map((point) => point.x)) + 340 : 0;
+      packX = packLeft;
+      packing = true;
+    }
+    const obstacles = anchored ? occupied : [];
+    const placed: Point[] = [];
+    for (const key of component) {
+      if (retained.has(key)) continue;
+      const desired = positions.get(key)!;
+      let point = desired;
+      if (obstacles.some((peer) => overlaps(point, peer))) {
+        const candidates = obstacles.flatMap((peer) => [
+          { x: peer.x - width, y: desired.y },
+          { x: peer.x + width, y: desired.y },
+          { x: desired.x, y: peer.y - height },
+          { x: desired.x, y: peer.y + height },
+        ]);
+        point = candidates
+          .filter((candidate) => !obstacles.some((peer) => overlaps(candidate, peer)))
+          .sort(
+            (a, b) => Math.hypot(a.x - desired.x, a.y - desired.y) - Math.hypot(b.x - desired.x, b.y - desired.y),
+          )[0];
+      }
+      positions.set(key, point);
+      obstacles.push(point);
+      placed.push(point);
+    }
+    if (!anchored && placed.length) {
+      const left = Math.min(...placed.map((point) => point.x));
+      const top = Math.min(...placed.map((point) => point.y));
+      for (const point of placed) {
+        point.x += packX - left;
+        point.y += packY - top;
+      }
+      occupied.push(...placed);
+      packX = Math.max(...placed.map((point) => point.x)) + 340;
+      rowHeight = Math.max(rowHeight, Math.max(...placed.map((point) => point.y)) - packY + 200);
+      if (packX - packLeft > rowWidth) {
+        packX = packLeft;
+        packY += rowHeight;
+        rowHeight = 0;
+      }
+    }
+  }
+  for (const [key, point] of positions) if (!retained.has(key)) retained.set(key, point);
+  return positions;
+}

package/src/client/canvas/memory-layout.ts

@@ -0,0 +1,106 @@
+import type { MemoryGraphNode } from '../../shared/memory-graph.js';
+
+export type Point = { x: number; y: number };
+export const MAP_CARD = { width: 220, height: 92 };
+export interface MemoryRegion extends Point {
+  path: string;
+  width: number;
+  height: number;
+  count: number;
+  depth: number;
+  collapsed: boolean;
+}
+
+/** Folder membership determines regions; authored Map positions never change membership. */
+export function mapLayout(nodes: MemoryGraphNode[], collapsed: Set<string>) {
+  const boards = nodes.filter((node) => node.kind === 'board');
+  const positions = new Map<string, Point>();
+  const regions: MemoryRegion[] = [];
+  const hidden = new Set<string>();
+  const paths = new Set<string>();
+  for (const board of boards) {
+    const parts = (board.folder ?? '').split('/');
+    parts.forEach((_, index) => {
+      paths.add(parts.slice(0, index + 1).join('/'));
+    });
+  }
+  const inside = (node: MemoryGraphNode, path: string) =>
+    (node.folder ?? '') === path || (!!path && !!node.folder?.startsWith(`${path}/`));
+  const measure = (path: string, x: number, y: number, depth: number): { width: number; height: number } => {
+    const members = boards.filter((node) => inside(node, path));
+    const folded = collapsed.has(path);
+    const region: MemoryRegion = {
+      path,
+      x,
+      y,
+      width: 280,
+      height: 72,
+      count: members.length,
+      depth,
+      collapsed: folded,
+    };
+    regions.push(region);
+    if (folded) {
+      for (const node of members) hidden.add(node.key);
+      return region;
+    }
+    const direct = members
+      .filter((node) => (node.folder ?? '') === path)
+      .sort((a, b) => a.title.localeCompare(b.title));
+    const columns = Math.min(3, Math.max(1, Math.ceil(Math.sqrt(direct.length))));
+    direct.forEach((node, index) => {
+      const topLeft = node.position ?? {
+        x: x + 24 + (index % columns) * (MAP_CARD.width + 28),
+        y: y + 52 + Math.floor(index / columns) * (MAP_CARD.height + 28),
+      };
+      positions.set(node.key, { x: topLeft.x + MAP_CARD.width / 2, y: topLeft.y + MAP_CARD.height / 2 });
+    });
+    let nextY = y + 52 + Math.ceil(direct.length / columns) * (MAP_CARD.height + 28);
+    let width = direct.length ? columns * (MAP_CARD.width + 28) + 20 : 280;
+    const children = [...paths]
+      .filter((item) => item && item.slice(0, item.lastIndexOf('/')) === path && item.includes('/'))
+      .sort();
+    let childX = 20,
+      childHeight = 0;
+    for (const child of children) {
+      if (childX > 650) {
+        childX = 20;
+        nextY += childHeight + 24;
+        childHeight = 0;
+      }
+      const size = measure(child, x + childX, nextY, depth + 1);
+      childX += size.width + 24;
+      childHeight = Math.max(childHeight, size.height);
+      width = Math.max(width, childX);
+    }
+    nextY += childHeight + (children.length ? 20 : 0);
+    region.width = width;
+    region.height = Math.max(100, nextY - y + 4);
+    // Include saved positions and nested regions without discarding a person's arrangement.
+    const points = members.flatMap((node) => {
+      const point = positions.get(node.key);
+      return point ? [point] : [];
+    });
+    const right = Math.max(x + region.width, ...points.map((point) => point.x + MAP_CARD.width / 2 + 20));
+    const bottom = Math.max(y + region.height, ...points.map((point) => point.y + MAP_CARD.height / 2 + 20));
+    region.x = Math.min(x, ...points.map((point) => point.x - MAP_CARD.width / 2 - 20));
+    region.y = Math.min(y, ...points.map((point) => point.y - MAP_CARD.height / 2 - 48));
+    region.width = right - region.x;
+    region.height = bottom - region.y;
+    return region;
+  };
+  let x = 32,
+    y = 32,
+    rowHeight = 0;
+  for (const path of [...paths].filter((path) => !path.includes('/')).sort()) {
+    if (x > 1100) {
+      x = 32;
+      y += rowHeight + 36;
+      rowHeight = 0;
+    }
+    const size = measure(path, x, y, 0);
+    x += size.width + 36;
+    rowHeight = Math.max(rowHeight, size.height);
+  }
+  return { positions, regions, hidden };
+}

package/src/client/canvas/use-chrome-height.ts

@@ -0,0 +1,20 @@
+import { useLayoutEffect, useRef } from 'preact/hooks';
+
+/** Keep floating canvas controls clear when their content wraps or is hidden. */
+export function useChromeHeight(property: string) {
+  const ref = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const element = ref.current;
+    const region = element?.parentElement;
+    if (!element || !region) return;
+    const measure = () => region.style.setProperty(property, `${element.getBoundingClientRect().height}px`);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+      region.style.removeProperty(property);
+    };
+  }, [property]);
+  return ref;
+}

package/src/client/canvas/use-focus-trap.ts

@@ -1,7 +1,7 @@
-import { useEffect } from 'preact/hooks';
+import { useLayoutEffect, useRef } from 'preact/hooks';
 
 const FOCUSABLE =
-  'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), summary, [tabindex]:not([tabindex="-1"])';
 
 /**
  * Focus trap for modal overlays (rail-chrome-v2 item 18): while `active`, Tab
@@ -12,15 +12,31 @@ const FOCUSABLE =
 export function useFocusTrap(
   ref: { current: HTMLElement | null },
   active: boolean,
-  options: { initial?: { current: HTMLElement | null }; restoreTo?: () => HTMLElement | null } = {},
+  options: {
+    initial?: { current: HTMLElement | null };
+    restoreTo?: () => HTMLElement | null;
+    onEscape?: () => void;
+  } = {},
 ): void {
-  useEffect(() => {
+  const escapeHandler = useRef(options.onEscape);
+  escapeHandler.current = options.onEscape;
+  useLayoutEffect(() => {
     if (!active) return;
     const root = ref.current;
     if (!root) return;
     const previous = document.activeElement as HTMLElement | null;
     const restoreTo = options.restoreTo;
-    const focusables = () => Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE));
+    const focusables = () =>
+      Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter((item) => {
+        if (item.closest('[hidden], [inert]')) return false;
+        for (let parent: HTMLElement | null = item; parent && parent !== root; parent = parent.parentElement) {
+          if (getComputedStyle(parent).display === 'none' || getComputedStyle(parent).visibility === 'hidden')
+            return false;
+          if (parent.matches('details:not([open])') && !parent.querySelector(':scope > summary')?.contains(item))
+            return false;
+        }
+        return true;
+      });
     const initial = options.initial?.current ?? focusables()[0];
     if (initial && !root.contains(document.activeElement)) initial.focus();
     const onKey = (e: KeyboardEvent) => {
@@ -38,9 +54,19 @@ export function useFocusTrap(
         first.focus();
       }
     };
+    // Disabling the focused button during a save can move focus to body. Keep
+    // modal Escape ownership there; keys inside retain local/nested handling.
+    const onOutsideKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || !escapeHandler.current || root.contains(event.target as Node)) return;
+      event.preventDefault();
+      event.stopPropagation();
+      escapeHandler.current();
+    };
     root.addEventListener('keydown', onKey);
+    window.addEventListener('keydown', onOutsideKey, true);
     return () => {
       root.removeEventListener('keydown', onKey);
+      window.removeEventListener('keydown', onOutsideKey, true);
       // `restoreTo` wins: an overlay that replaced the element it was opened
       // from (focus mode unmounts the node while expanded) names the element
       // to return to, which may only exist after the next frame.