@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-canvas",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "A canvas component.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -19,14 +19,9 @@
       "import": "./dist/lib/index.mjs"
     },
     "./scene": {
-      "source": "./src/scene.ts",
-      "types": "./dist/types/src/scene.d.ts",
-      "import": "./dist/lib/scene.mjs"
-    },
-    "./types": {
-      "source": "./src/archive/types.ts",
-      "types": "./dist/types/src/archive/types.d.ts",
-      "import": "./dist/lib/types.mjs"
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -39,19 +34,16 @@
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
     "@effect/atom-react": "4.0.0",
-    "bind-event-listener": "^3.0.0",
     "d3": "^7.9.0",
-    "react-resize-detector": "^11.0.1",
-    "transformation-matrix": "^2.16.1",
-    "@dxos/debug": "0.13.0",
-    "@dxos/diagram": "0.13.0",
-    "@dxos/echo": "0.13.0",
-    "@dxos/effect": "0.13.0",
-    "@dxos/react-hooks": "0.13.0",
-    "@dxos/react-ui-editor": "0.13.0",
-    "@dxos/react-ui-form": "0.13.0",
-    "@dxos/ui-editor": "0.13.0",
-    "@dxos/ui-types": "0.13.0"
+    "@dxos/diagram": "0.14.0",
+    "@dxos/echo": "0.14.0",
+    "@dxos/effect": "0.14.0",
+    "@dxos/react-hooks": "0.14.0",
+    "@dxos/react-ui-editor": "0.14.0",
+    "@dxos/react-ui-form": "0.14.0",
+    "@dxos/react-ui-list": "0.14.0",
+    "@dxos/ui-editor": "0.14.0",
+    "@dxos/ui-types": "0.14.0"
   },
   "devDependencies": {
     "@playwright/test": "1.63.0",
@@ -63,16 +55,18 @@
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
     "vite": "^8.2.2",
-    "@dxos/react-ui": "0.13.0",
-    "@dxos/test-utils": "0.13.0",
-    "@dxos/ui-theme": "0.13.0"
+    "@dxos/log": "0.14.0",
+    "@dxos/react-ui": "0.14.0",
+    "@dxos/react-ui-syntax-highlighter": "0.14.0",
+    "@dxos/test-utils": "0.14.0",
+    "@dxos/ui-theme": "0.14.0"
   },
   "peerDependencies": {
     "effect": "4.0.0",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/react-ui": "^0.13.0",
-    "@dxos/ui-theme": "^0.13.0"
+    "@dxos/react-ui": "^0.14.0",
+    "@dxos/ui-theme": "^0.14.0"
   },
   "publishConfig": {
     "access": "public"

package/src/components/About/About.stories.tsx

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { translations as uiTranslations } from '@dxos/react-ui/translations';
+
+import { About } from './About.tsx';
+
+const meta: Meta<typeof About> = {
+  title: 'ui/react-ui-canvas/About',
+  component: About,
+  decorators: [withTheme(), withLayout({ layout: 'centered' })],
+  parameters: { translations: uiTranslations },
+  args: {
+    classNames: 'w-80',
+    stats: [
+      { id: 'nodes', label: 'Nodes', value: 12 },
+      { id: 'links', label: 'Links', value: 9 },
+      { id: 'layers', label: 'Layers', value: 2 },
+      { id: 'zoom', label: 'Zoom', value: '100%' },
+    ],
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/About/About.tsx

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { Fragment, type ReactNode } from 'react';
+
+import * as Layout from '@dxos/react-ui/Layout';
+import * as Panel from '@dxos/react-ui/Panel';
+import * as Typography from '@dxos/react-ui/Typography';
+import type * as Util from '@dxos/react-ui/Util';
+
+export type AboutStat = { id: string; label: string; value: ReactNode };
+
+export type AboutProps = Util.ThemedClassName<{
+  stats: readonly AboutStat[];
+}>;
+
+/** A two-column table of the drawing's figures, one per list-height row: a label and its value. */
+export const About = ({ classNames, stats }: AboutProps) => (
+  <Panel.Root classNames={classNames} data-testid='about'>
+    <Panel.Body>
+      <Layout.Container>
+        <Layout.Grid cols={['fill', 'auto']}>
+          {stats.map(({ id, label, value }) => (
+            <Fragment key={id}>
+              <Typography.Text tone='muted' truncate>
+                {label}
+              </Typography.Text>
+              <Typography.Text classNames='text-end tabular-nums' data-testid={`about-${id}`}>
+                {value}
+              </Typography.Text>
+            </Fragment>
+          ))}
+        </Layout.Grid>
+      </Layout.Container>
+    </Panel.Body>
+  </Panel.Root>
+);

package/src/components/About/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './About.tsx';

package/src/components/Breadcrumbs/Breadcrumbs.tsx

@@ -21,9 +21,23 @@ export const Breadcrumbs = ({ path, nameOf, onSelect }: BreadcrumbsProps) => (
     {path.map((id, index) => (
       <Fragment key={`${index}:${id}`}>
         {index > 0 && <span className='text-fg-subtle'>›</span>}
-        <Button.Root variant='ghost' size='sm' disabled={index === path.length - 1} onClick={() => onSelect(index)}>
-          {nameOf(id)}
-        </Button.Root>
+        {/* The root is home whatever its scene is called. */}
+        {index === 0 ? (
+          <Button.Root
+            variant='ghost'
+            size='sm'
+            iconOnly
+            icon='ph--house--regular'
+            label={nameOf(id)}
+            disabled={index === path.length - 1}
+            data-testid='breadcrumb-root'
+            onClick={() => onSelect(index)}
+          />
+        ) : (
+          <Button.Root variant='ghost' size='sm' disabled={index === path.length - 1} onClick={() => onSelect(index)}>
+            {nameOf(id)}
+          </Button.Root>
+        )}
       </Fragment>
     ))}
   </nav>

package/src/components/ControlFrame/ControlFrame.tsx

@@ -12,7 +12,7 @@ import React, { memo } from 'react';
 
 import { mx } from '@dxos/ui-theme';
 
-import { type ControlPointRef, type Drag, type Handle } from '../../model/atoms.ts';
+import { type ControlPointRef, type Drag, type Handle, isMoving } from '../../model/atoms.ts';
 import { nodeDef } from '../../model/node-def.ts';
 import { type NodeRegistry } from '../../model/registry.ts';
 import {
@@ -21,6 +21,7 @@ import {
   type ElementId,
   type Endpoint,
   type Link,
+  type LinkId,
   type Node,
   type Point,
   type Port,
@@ -63,11 +64,17 @@ export type ControlFrameProps = {
   capabilities: Capabilities;
   selection: ReadonlySet<ElementId>;
   hover?: ElementId;
+  /** The link under the pointer: it shows its end handles, as a selected link does. */
+  hoveredLink?: LinkId;
+  /** The pointer entered or left a hovered link's handles, which keeps the link hovered while on them. */
+  onLinkHover?: (id: LinkId | undefined) => void;
   selectedPoint?: ControlPointRef;
   zoom: number;
   drag?: Drag;
   /** The bounds a create gesture in flight would land, drawn as a provisional frame. */
   createFrame?: Bounds;
+  /** Where the nodes of a move in flight will land, drawn under them as they follow the pointer. */
+  landing?: readonly Bounds[];
   /** The gesture in flight would be refused (an overlap on the lattice): its outlines turn red. */
   blocked?: boolean;
   /** The scene's lattice, so a selected smart link's handles sit on its gutter route. */
@@ -97,10 +104,13 @@ export const ControlFrame = memo(
     capabilities,
     selection,
     hover,
+    hoveredLink,
+    onLinkHover,
     selectedPoint,
     zoom,
     drag,
     createFrame,
+    landing,
     blocked,
     lattice,
     onHandlePointerDown,
@@ -114,10 +124,14 @@ export const ControlFrame = memo(
     const handleSize = 8 * unit;
     const portRadius = 5 * unit;
     const midpointRadius = 4 * unit;
-    const selectedNodes = [...selection].map((id) => scene.nodes[id]).filter((node) => node !== undefined);
-    const selectedLinks = [...selection].map((id) => scene.links[id]).filter((link) => link !== undefined);
+    // A move in flight shows the shapes themselves: no outlines or handles, just where they will land.
+    const chrome = isMoving(drag) ? [] : [...selection];
+    const selectedNodes = chrome.map((id) => scene.nodes[id]).filter((node) => node !== undefined);
+    const selectedLinks = chrome.map((id) => scene.links[id]).filter((link) => link !== undefined);
+    const linkUnder = hoveredLink && !selection.has(hoveredLink) ? scene.links[hoveredLink] : undefined;
+    // A hovered link shows the handles of a selected one; only its ends, its control points stay a selection's.
     const lanes =
-      lattice && selectedLinks.length > 0
+      lattice && (selectedLinks.length > 0 || linkUnder !== undefined)
         ? new Map(
             sceneLinkGeometry(scene, registry, Object.values(scene.links), lattice).map((geometry) => [
               geometry.link.id,
@@ -141,6 +155,21 @@ export const ControlFrame = memo(
     if (dropTarget) {
       portNodes.add(dropTarget);
     }
+    // The end a link drag holds still shows its ports too, a new link's source as an existing link's far end.
+    const draggedLink = drag?.kind === 'end' ? scene.links[drag.id] : undefined;
+    const fixedEnd =
+      drag?.kind === 'link'
+        ? drag.source
+        : draggedLink && drag?.kind === 'end'
+          ? drag.end === 'source'
+            ? draggedLink.target
+            : draggedLink.source
+          : undefined;
+    const fixedNode = fixedEnd && endpointNode(fixedEnd);
+    const anchor = fixedNode ? scene.nodes[fixedNode] : undefined;
+    if (anchor) {
+      portNodes.add(anchor);
+    }
     const marquee = drag?.kind === 'marquee' ? boundsFromPoints(drag.from, drag.to) : undefined;
     // The layer draws every provisional link that will land (over a target, or free-ended); the band is only
     // a port drag over free space, where dropping would create a node rather than a free end.
@@ -149,6 +178,74 @@ export const ControlFrame = memo(
         ? { from: { point: drag.from, side: drag.fromSide }, to: drag.to }
         : undefined;
 
+    /** A link's end handles, and a selected spline's control points; a hovered link shows only its ends. */
+    const linkHandles = (link: Link, hoverOnly: boolean) => {
+      // On a lattice the handles sit on the link's lane, which depends on the links around it.
+      const geometry = capabilities.update
+        ? (lanes?.get(link.id) ?? linkGeometry(scene, registry, link, lattice))
+        : undefined;
+      if (!geometry) {
+        return null;
+      }
+      const points =
+        link.type === 'spline' ? (drag?.kind === 'point' && drag.id === link.id ? drag.points : link.points) : [];
+      const ends: [LinkEnd, Point][] = [
+        ['source', geometry.source.point],
+        ['target', geometry.target.point],
+      ];
+      return (
+        <g key={link.id}>
+          {ends.map(([end, point]) => (
+            <circle
+              key={end}
+              cx={point.x}
+              cy={point.y}
+              r={portRadius}
+              className={mx(
+                'stroke-focus pointer-events-auto cursor-move hover:fill-focus',
+                drag?.kind === 'end' && drag.id === link.id && drag.end === end ? 'fill-focus' : 'fill-base-surface',
+              )}
+              strokeWidth={unit}
+              onPointerDown={(event) => onEndPointerDown?.(link, end, event)}
+              onPointerEnter={hoverOnly ? () => onLinkHover?.(link.id) : undefined}
+              onPointerLeave={hoverOnly ? () => onLinkHover?.(undefined) : undefined}
+            />
+          ))}
+          {/* Midpoints first, so a control point wins wherever the two land on each other. */}
+          {!hoverOnly &&
+            link.type === 'spline' &&
+            midpoints(geometry.source.point, points, geometry.target.point).map(({ index, point }) => (
+              <circle
+                key={`midpoint-${index}`}
+                cx={point.x}
+                cy={point.y}
+                r={midpointRadius}
+                className='fill-focus/40 pointer-events-auto cursor-copy hover:fill-focus'
+                onPointerDown={(event) => onMidpointPointerDown?.(link, index, point, event)}
+              />
+            ))}
+          {link.type === 'spline' &&
+            points.map((point, index) => (
+              <rect
+                key={index}
+                x={point.x - handleSize / 2}
+                y={point.y - handleSize / 2}
+                width={handleSize}
+                height={handleSize}
+                transform={`rotate(45 ${point.x} ${point.y})`}
+                className={mx(
+                  'stroke-focus pointer-events-auto cursor-move hover:fill-focus',
+                  selectedPoint?.link === link.id && selectedPoint.index === index ? 'fill-focus' : 'fill-base-surface',
+                )}
+                strokeWidth={unit}
+                onPointerDown={(event) => onPointPointerDown?.(link, index, event)}
+                onContextMenu={(event) => onPointContextMenu?.(link, index, event)}
+              />
+            ))}
+        </g>
+      );
+    };
+
     return (
       <svg className='absolute overflow-visible pointer-events-none' width={1} height={1}>
         {selectedNodes.map((node) => {
@@ -160,7 +257,7 @@ export const ControlFrame = memo(
               y={bounds.y}
               width={bounds.width}
               height={bounds.height}
-              className={mx('fill-none', blocked ? 'stroke-error-border' : 'stroke-primary-500')}
+              className={mx('fill-none', blocked ? 'stroke-error-border' : 'stroke-focus')}
               strokeWidth={unit}
               data-blocked={blocked || undefined}
             />
@@ -173,9 +270,7 @@ export const ControlFrame = memo(
             // Filled while it is an end of the drag in progress: the source, or the port it would drop on.
             const isEnd = (end: Endpoint | undefined) =>
               end !== undefined && !isPointEndpoint(end) && end.node === node.id && end.port === port.id;
-            const active =
-              (drag?.kind === 'link' && isEnd(drag.source)) ||
-              ((drag?.kind === 'link' || drag?.kind === 'end') && isEnd(drag.target));
+            const active = isEnd(fixedEnd) || ((drag?.kind === 'link' || drag?.kind === 'end') && isEnd(drag.target));
             return (
               <circle
                 key={`${node.id}/${port.id}`}
@@ -183,8 +278,8 @@ export const ControlFrame = memo(
                 cy={point.y}
                 r={portRadius}
                 className={mx(
-                  'stroke-primary-500 pointer-events-auto cursor-crosshair hover:fill-primary-500',
-                  active ? 'fill-primary-500' : 'fill-base-surface',
+                  'stroke-focus pointer-events-auto cursor-crosshair hover:fill-focus',
+                  active ? 'fill-focus' : 'fill-base-surface',
                 )}
                 strokeWidth={unit}
                 onPointerDown={(event) => onPortPointerDown?.(node, port, event)}
@@ -192,6 +287,8 @@ export const ControlFrame = memo(
             );
           });
         })}
+        {/* A hovered link's ends go under a node's handles, so a resize handle on the same point still wins. */}
+        {linkUnder && linkHandles(linkUnder, true)}
         {/* Handles after the ports so a handle wins where a port sits on the same point (a side centre). */}
         {single && capabilities.resize && nodeDef(registry, single)?.resizable && !single.locked && (
           <g>
@@ -204,7 +301,7 @@ export const ControlFrame = memo(
                   y={point.y - handleSize / 2}
                   width={handleSize}
                   height={handleSize}
-                  className='fill-base-surface stroke-primary-500 pointer-events-auto'
+                  className='fill-base-surface stroke-focus pointer-events-auto'
                   strokeWidth={unit}
                   style={{ cursor: cursorFor(handle) }}
                   onPointerDown={(event) => onHandlePointerDown?.(single, handle, event)}
@@ -214,91 +311,50 @@ export const ControlFrame = memo(
           </g>
         )}
         {/* A link's end and control-point handles all move it, so they follow the `update` capability together. */}
-        {selectedLinks.map((link) => {
-          // On a lattice the handles sit on the link's lane, which depends on the links around it.
-          const geometry = capabilities.update
-            ? (lanes?.get(link.id) ?? linkGeometry(scene, registry, link, lattice))
-            : undefined;
-          if (!geometry) {
-            return null;
-          }
-          const points =
-            link.type === 'spline' ? (drag?.kind === 'point' && drag.id === link.id ? drag.points : link.points) : [];
-          const ends: [LinkEnd, Point][] = [
-            ['source', geometry.source.point],
-            ['target', geometry.target.point],
-          ];
-          return (
-            <g key={link.id}>
-              {ends.map(([end, point]) => (
-                <circle
-                  key={end}
-                  cx={point.x}
-                  cy={point.y}
-                  r={portRadius}
-                  className={mx(
-                    'stroke-primary-500 pointer-events-auto cursor-move hover:fill-primary-500',
-                    drag?.kind === 'end' && drag.id === link.id && drag.end === end
-                      ? 'fill-primary-500'
-                      : 'fill-base-surface',
-                  )}
-                  strokeWidth={unit}
-                  onPointerDown={(event) => onEndPointerDown?.(link, end, event)}
-                />
-              ))}
-              {/* Midpoints first, so a control point wins wherever the two land on each other. */}
-              {link.type === 'spline' &&
-                midpoints(geometry.source.point, points, geometry.target.point).map(({ index, point }) => (
-                  <circle
-                    key={`midpoint-${index}`}
-                    cx={point.x}
-                    cy={point.y}
-                    r={midpointRadius}
-                    className='fill-primary-500/40 pointer-events-auto cursor-copy hover:fill-primary-500'
-                    onPointerDown={(event) => onMidpointPointerDown?.(link, index, point, event)}
-                  />
-                ))}
-              {link.type === 'spline' &&
-                points.map((point, index) => (
-                  <rect
-                    key={index}
-                    x={point.x - handleSize / 2}
-                    y={point.y - handleSize / 2}
-                    width={handleSize}
-                    height={handleSize}
-                    transform={`rotate(45 ${point.x} ${point.y})`}
-                    className={mx(
-                      'stroke-primary-500 pointer-events-auto cursor-move hover:fill-primary-500',
-                      selectedPoint?.link === link.id && selectedPoint.index === index
-                        ? 'fill-primary-500'
-                        : 'fill-base-surface',
-                    )}
-                    strokeWidth={unit}
-                    onPointerDown={(event) => onPointPointerDown?.(link, index, event)}
-                    onContextMenu={(event) => onPointContextMenu?.(link, index, event)}
-                  />
-                ))}
-            </g>
-          );
-        })}
+        {selectedLinks.map((link) => linkHandles(link, false))}
         {band && (
           <path
-            d={curvePath(band.from, { point: band.to, side: oppositeSide(band.from.side) })}
-            className='fill-none stroke-primary-500'
+            d={curvePath(band.from, { point: band.to, side: oppositeSide(band.from.side), free: true })}
+            className='fill-none stroke-focus'
             strokeWidth={2 * unit}
             strokeDasharray={`${6 * unit} ${4 * unit}`}
           />
         )}
+        {/* A link end over empty canvas carries a connection circle, as an end on a port does. */}
+        {(drag?.kind === 'link' || drag?.kind === 'end') && !drag.target && (
+          <circle
+            data-testid='free-end'
+            cx={drag.to.x}
+            cy={drag.to.y}
+            r={portRadius}
+            className='fill-focus stroke-focus pointer-events-none'
+            strokeWidth={unit}
+          />
+        )}
         {marquee && (
           <rect
             x={marquee.x}
             y={marquee.y}
             width={marquee.width}
             height={marquee.height}
-            className='fill-primary-500/10 stroke-primary-500'
+            className='fill-focus/10 stroke-focus'
             strokeWidth={unit}
           />
         )}
+        {landing?.map((frame, index) => (
+          <rect
+            key={index}
+            data-testid='landing-frame'
+            x={frame.x}
+            y={frame.y}
+            width={frame.width}
+            height={frame.height}
+            className={mx('fill-none', blocked ? 'stroke-error-border' : 'stroke-focus')}
+            data-blocked={blocked || undefined}
+            strokeWidth={unit}
+            strokeDasharray={`${4 * unit} ${4 * unit}`}
+          />
+        ))}
         {createFrame && (
           <rect
             data-testid='create-frame'
@@ -306,7 +362,7 @@ export const ControlFrame = memo(
             y={createFrame.y}
             width={createFrame.width}
             height={createFrame.height}
-            className={blocked ? 'fill-error-surface stroke-error-border' : 'fill-primary-500/10 stroke-primary-500'}
+            className={blocked ? 'fill-error-surface stroke-error-border' : 'fill-focus/10 stroke-focus'}
             data-blocked={blocked || undefined}
             strokeWidth={unit}
           />

package/src/components/Grid/Grid.stories.tsx

@@ -120,7 +120,7 @@ const DefaultStory = ({ size, showAxes }: GridProps) => {
 };
 
 const meta: Meta<GridProps> = {
-  title: 'ui/react-ui-canvas/scene/Grid',
+  title: 'ui/react-ui-canvas/Grid',
   component: GridComponent,
   render: DefaultStory,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],

package/src/components/Layers/Layers.stories.tsx

@@ -0,0 +1,131 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { translations as formTranslations } from '@dxos/react-ui-form/translations';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { translations as uiTranslations } from '@dxos/react-ui/translations';
+
+import { type Layer, type LayerId } from '../../model/types.ts';
+import { between } from '../../utils/order.ts';
+import { LayersPanel } from './Layers.tsx';
+
+/** Three layers, bottom first, the middle one hidden. */
+const LAYERS: Layer[] = (() => {
+  const background: Layer = { id: 'background', name: 'Background', z: between() };
+  const notes: Layer = { id: 'notes', name: 'Notes', z: between(background.z), hidden: true };
+  const diagram: Layer = { id: 'diagram', name: 'Diagram', z: between(notes.z) };
+  return [background, notes, diagram];
+})();
+
+/** The panel over local state, as a host keeps the scene's layers. */
+const DefaultStory = () => {
+  const [layers, setLayers] = useState(LAYERS);
+  const [selected, setSelected] = useState<LayerId[]>(['diagram']);
+  const update = (id: LayerId, values: Partial<Layer>) =>
+    setLayers((layers) => layers.map((layer) => (layer.id === id ? { ...layer, ...values } : layer)));
+  const remove = (ids: LayerId[]) => setLayers((layers) => layers.filter((layer) => !ids.includes(layer.id)));
+  return (
+    <LayersPanel
+      classNames='w-72 border border-separator rounded-sm'
+      layers={layers}
+      selected={selected}
+      onSelectedChange={setSelected}
+      onToggle={(id) => update(id, { hidden: !layers.find((layer) => layer.id === id)?.hidden })}
+      onRename={(id, name) => update(id, { name })}
+      onMove={(id, index) =>
+        setLayers((layers) => {
+          const moved = layers.find((layer) => layer.id === id);
+          const others = layers.filter((layer) => layer.id !== id);
+          return moved ? [...others.slice(0, index), moved, ...others.slice(index)] : layers;
+        })
+      }
+      onCreate={() => {
+        const id = `layer-${layers.length + 1}`;
+        setLayers((layers) => [
+          { id, name: `Layer ${layers.length + 1}`, z: between(undefined, layers[0]?.z) },
+          ...layers,
+        ]);
+        setSelected([id]);
+        return id;
+      }}
+      // In a scene, deleting takes the layer's shapes and merging moves them down; here there are none.
+      onDelete={(ids) => {
+        remove(ids);
+        setSelected([]);
+      }}
+      onMerge={(ids, into) => {
+        remove(ids.filter((id) => id !== into));
+        setSelected([into]);
+      }}
+    />
+  );
+};
+
+const meta: Meta<typeof DefaultStory> = {
+  title: 'ui/react-ui-canvas/Layers',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'centered' })],
+  parameters: { translations: [...uiTranslations, ...formTranslations] },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** Every toolbar action and an inline rename, against the panel's local state. */
+export const Test: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // 1. The layers list top first, as they stack.
+    const names = () => canvas.getAllByTestId(/^layer-name-/).map((element) => element.textContent);
+    await expect(names()).toEqual(['Diagram', 'Notes', 'Background']);
+
+    // 2. A new layer goes at the end of the list (the bottom of the stack).
+    await userEvent.click(canvas.getByTestId('layers-create'));
+    await waitFor(() => expect(names().at(-1)).toBe('Layer 4'));
+
+    // 3. The new layer's name opens for editing; the green check saves it.
+    const input = await canvas.findByTestId('layer-input-layer-4');
+    await waitFor(() => expect(input).toHaveFocus());
+    await userEvent.clear(input);
+    await userEvent.type(input, 'Sketch');
+    await userEvent.click(within(canvas.getByTestId('layer-layer-4')).getByTestId('editable.save'));
+    await waitFor(() => expect(names().at(-1)).toBe('Sketch'));
+
+    // 4. The eye shows a hidden layer.
+    await userEvent.click(canvas.getByTestId('layer-toggle-notes'));
+    await expect(canvas.getByTestId('layer-toggle-notes')).toHaveAccessibleName('Hide layer');
+
+    // 5. Merge, in the toolbar's menu, needs two layers: a Shift-click extends the selection to the next one, and
+    // merging keeps the top-most. Shift rather than Cmd/Ctrl, whose key the listbox picks by platform. The menu is
+    // portalled, so its items are found in the document body.
+    const body = within(canvasElement.ownerDocument.body);
+    await userEvent.click(canvas.getByTestId('layers-menu'));
+    await expect(await body.findByTestId('layers-merge')).toHaveAttribute('data-disabled');
+    await userEvent.keyboard('{Escape}');
+    await userEvent.click(canvas.getByTestId('layer-name-diagram'));
+    // One session, so the held key is still down for the click.
+    const user = userEvent.setup();
+    await user.keyboard('{Shift>}');
+    await user.click(canvas.getByTestId('layer-name-notes'));
+    await user.keyboard('{/Shift}');
+    await userEvent.click(canvas.getByTestId('layers-menu'));
+    const merge = await body.findByTestId('layers-merge');
+    await waitFor(() => expect(merge).not.toHaveAttribute('data-disabled'));
+    // Picked from the keyboard, as the react-ui Menu stories do: a synthetic click does not select a menu item.
+    await userEvent.keyboard('{Home}{Enter}');
+    await waitFor(() => expect(names()).toEqual(['Diagram', 'Background', 'Sketch']));
+
+    // 6. The arrows move along the list, and Enter opens the current row's name.
+    await userEvent.click(canvas.getByTestId('layer-name-diagram'));
+    await userEvent.keyboard('{ArrowDown}{Enter}');
+    await waitFor(() => expect(canvas.getByTestId('layer-input-background')).toHaveFocus());
+  },
+};