@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/src/utils/hit.ts

@@ -11,13 +11,6 @@ import { type Bounds, MAJOR_GRID, type Node, type Point, type Scene } from '../m
 import { sortByZ } from './order.ts';
 import { nodeBounds } from './shapes.ts';
 
-/**
- * Centred on the origin, not anchored at it: a scene is laid out around (0, 0), so an extent running
- * from the origin to (1600, 1024) puts its own centre well below and right of the content and the
- * initial fit — which centres the frame — pushes everything into the top-left corner. Each half is a
- * whole number of major cells, so the frame still lands on grid lines.
- */
-export const DEFAULT_EXTENT: Bounds = { x: -832, y: -512, width: 1664, height: 1024 };
 export const BOUNDS_PADDING = MAJOR_GRID;
 
 export const containsPoint = (bounds: Bounds, point: Point) =>
@@ -78,27 +71,12 @@ export const alignBounds = (bounds: Bounds, unit: number): Bounds => {
 export const nodeList = (scene: Scene): Node[] => Object.values(scene.nodes);
 
 /**
- * Derived scene bounds (decision 6): the union of nodes plus padding, grown to the major grid so the
- * frame sits on grid lines. The default extent is a floor rather than a fallback for an empty scene:
- * content only ever grows the frame, so drawing the first node does not collapse the scene around it.
- *
- * This is the frame of a scene shown on its own — the surface the user edits on. A scene shown through
- * a portal is framed by {@link contentBounds} instead.
- */
-export const sceneBounds = (scene: Scene, padding = BOUNDS_PADDING, unit = MAJOR_GRID): Bounds => {
-  const content = unionBounds(nodeList(scene).map(nodeBounds));
-  const union = unionBounds(content ? [DEFAULT_EXTENT, padBounds(content, padding)] : [DEFAULT_EXTENT]);
-  return alignBounds(union ?? DEFAULT_EXTENT, unit);
-};
-
-/**
- * What a scene is worth showing: the same frame without the floor under it, so a child drawn in a portal
- * fills its tile rather than being shrunk to fit an editing surface it is not being edited on. An empty
- * scene has no content to frame, so there the floor is the frame.
+ * What a scene holds (decision 6): the union of its nodes plus padding, grown to the major grid. Fit and a
+ * portal's preview frame it; an empty scene has none.
  */
-export const contentBounds = (scene: Scene, padding = BOUNDS_PADDING, unit = MAJOR_GRID): Bounds => {
+export const contentBounds = (scene: Scene, padding = BOUNDS_PADDING, unit = MAJOR_GRID): Bounds | undefined => {
   const content = unionBounds(nodeList(scene).map(nodeBounds));
-  return content ? alignBounds(padBounds(content, padding), unit) : alignBounds(DEFAULT_EXTENT, unit);
+  return content ? alignBounds(padBounds(content, padding), unit) : undefined;
 };
 
 /** Topmost node under `point`, or none; `margin` widens every node, e.g. to reach its ports. */

package/src/utils/index.ts

@@ -7,14 +7,17 @@ export * from './camera.ts';
 export * from './clipboard.ts';
 export * from './diagram.ts';
 export * from './dnd.ts';
+export * from './group.ts';
 export * from './hit.ts';
 export * from './lattice.ts';
+export * from './layers.ts';
 export * from './layout.ts';
 export * from './order.ts';
 export * from './parts.ts';
 export * from './ports.ts';
 export * from './resize.ts';
 export * from './route.ts';
+export * from './scenes.ts';
 export * from './shapes.ts';
 export * from './style.ts';
 export * from './undo.ts';

package/src/utils/lattice.ts

@@ -110,6 +110,12 @@ export const coveredCells = ({ col, row, spanX, spanY }: LatticeCell): string[]
 /** Which node covers each lattice position, for the nodes not in `except` (those being moved or resized). */
 export type Occupancy = ReadonlyMap<string, ElementId>;
 
+/**
+ * Whether a node takes part in the lattice: a guide (a group's backdrop) or a bare caption annotates the shapes rather
+ * than being one, so it neither snaps, occupies cells nor blocks a gutter route.
+ */
+export const onLattice = (node: Node): boolean => !node.style?.guide && node.style?.border !== false;
+
 export const occupancy = (
   nodes: Iterable<Node>,
   spec: LatticeSpec,
@@ -117,7 +123,7 @@ export const occupancy = (
 ): Occupancy => {
   const cells = new Map<string, ElementId>();
   for (const node of nodes) {
-    if (!except.has(node.id)) {
+    if (!except.has(node.id) && onLattice(node)) {
       for (const key of coveredCells(toCell(nodeBounds(node), spec))) {
         cells.set(key, node.id);
       }

package/src/utils/layers.test.ts

@@ -0,0 +1,139 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { reduceIntent } from '../model/projection.ts';
+import { type Layer, type Scene } from '../model/types.ts';
+import { SceneBuilder } from './builder.ts';
+import {
+  DEFAULT_LAYER,
+  createLayer,
+  elementLayer,
+  layerOrder,
+  mergeLayersIntent,
+  moveLayer,
+  pinLayers,
+  sceneLayers,
+  visibleScene,
+} from './layers.ts';
+import { between } from './order.ts';
+
+describe('layers', () => {
+  const box = (x: number) => ({ x, y: 0, width: 100, height: 50 });
+  const {
+    scenes: [base],
+  } = SceneBuilder.scene('s', [
+    SceneBuilder.rect('a', box(0)),
+    SceneBuilder.rect('b', box(200)),
+    SceneBuilder.link('line', 'a', 'b').id('ab'),
+  ]).build();
+
+  /** The base scene with a second layer above, holding `b`. */
+  const layered = (): Scene => {
+    const top: Layer = { id: 'top', name: 'Top', z: between(DEFAULT_LAYER.z) };
+    const scene = reduceIntent(base, { kind: 'layer', layer: top });
+    return reduceIntent(scene, { kind: 'update', id: 'b', values: { layer: 'top' } });
+  };
+
+  test('a scene with no layers has one, and every element is on it', ({ expect }) => {
+    expect(sceneLayers(base)).toEqual([DEFAULT_LAYER]);
+    expect(elementLayer(base.nodes.a, sceneLayers(base))).toBe(DEFAULT_LAYER.id);
+  });
+
+  test('a new layer goes below the others', ({ expect }) => {
+    const scene = layered();
+    const layer = createLayer(scene, 'new');
+    const added = reduceIntent(scene, { kind: 'layer', layer });
+    expect(layer.name).toBe('Layer 3');
+    expect(sceneLayers(added).map((layer) => layer.id)).toEqual(['new', DEFAULT_LAYER.id, 'top']);
+  });
+
+  /** The base scene as a drawing saved before layers: no layers, and no element naming one. */
+  const legacy = (): Scene => {
+    const { layers: _, ...scene } = base;
+    return {
+      ...scene,
+      nodes: Object.fromEntries(Object.entries(scene.nodes).map(([id, node]) => [id, { ...node, layer: undefined }])),
+      links: Object.fromEntries(Object.entries(scene.links).map(([id, link]) => [id, { ...link, layer: undefined }])),
+    };
+  };
+
+  test('adding a layer below keeps elements that name no layer where they were drawn', ({ expect }) => {
+    const below = createLayer(legacy(), 'below');
+    const scene = reduceIntent(legacy(), { kind: 'layer', layer: below });
+    expect(sceneLayers(scene).map((layer) => layer.id)).toEqual(['below', DEFAULT_LAYER.id]);
+    expect([scene.nodes.a.layer, scene.nodes.b.layer, scene.links.ab.layer]).toEqual([
+      DEFAULT_LAYER.id,
+      DEFAULT_LAYER.id,
+      DEFAULT_LAYER.id,
+    ]);
+  });
+
+  test("pinning names the layers and each element's, and leaves a pinned scene as it is", ({ expect }) => {
+    expect(legacy().layers).toBeUndefined();
+    expect(legacy().nodes.a.layer).toBeUndefined();
+    const pinned = pinLayers(legacy());
+    expect(pinned.layers).toEqual({ [DEFAULT_LAYER.id]: DEFAULT_LAYER });
+    expect(Object.values(pinned.nodes).every((node) => node.layer === DEFAULT_LAYER.id)).toBe(true);
+    expect(pinLayers(pinned)).toBe(pinned);
+    // A layer the scene does not have resolves to the bottom one.
+    const stray = { ...pinned, nodes: { ...pinned.nodes, a: { ...pinned.nodes.a, layer: 'gone' } } };
+    expect(pinLayers(stray).nodes.a.layer).toBe(DEFAULT_LAYER.id);
+  });
+
+  test('a new layer takes a name no other layer has', ({ expect }) => {
+    // Two layers, one already named after the count a new one would otherwise take.
+    const scene = reduceIntent(layered(), { kind: 'layer', layer: { ...DEFAULT_LAYER, name: 'Layer 3' } });
+    expect(createLayer(scene, 'new').name).toBe('Layer 4');
+  });
+
+  test('a second layer makes the implicit layer real, so it keeps its elements', ({ expect }) => {
+    const scene = layered();
+    expect(sceneLayers(scene).map((layer) => layer.id)).toEqual([DEFAULT_LAYER.id, 'top']);
+    expect(elementLayer(scene.nodes.a, sceneLayers(scene))).toBe(DEFAULT_LAYER.id);
+    expect(elementLayer(scene.nodes.b, sceneLayers(scene))).toBe('top');
+  });
+
+  test('nodes paint by layer, then by their own order', ({ expect }) => {
+    const scene = layered();
+    // `b` is above `a` by layer even with the lower z.
+    const lowered = reduceIntent(scene, { kind: 'reorder', id: 'b', z: between(undefined, scene.nodes.a.z) });
+    expect(layerOrder(Object.values(lowered.nodes), sceneLayers(lowered)).map((node) => node.id)).toEqual(['a', 'b']);
+    // Moving the top layer to the bottom swaps them.
+    const moved = moveLayer(lowered, 'top', 0);
+    const reordered = moved ? reduceIntent(lowered, { kind: 'layer', layer: moved }) : lowered;
+    expect(layerOrder(Object.values(reordered.nodes), sceneLayers(reordered)).map((node) => node.id)).toEqual([
+      'b',
+      'a',
+    ]);
+  });
+
+  test('a hidden layer hides its elements and the links to them', ({ expect }) => {
+    const scene = layered();
+    const top = sceneLayers(scene)[1];
+    const hidden = reduceIntent(scene, { kind: 'layer', layer: { ...top, hidden: true } });
+    const visible = visibleScene(hidden);
+    expect(Object.keys(visible.nodes)).toEqual(['a']);
+    expect(Object.keys(visible.links)).toEqual([]);
+    expect(visibleScene(scene)).toBe(scene);
+  });
+
+  test('removing a layer removes its elements; the last layer stays', ({ expect }) => {
+    const scene = reduceIntent(layered(), { kind: 'removeLayer', id: 'top' });
+    expect(Object.keys(scene.nodes)).toEqual(['a']);
+    expect(Object.keys(scene.links)).toEqual([]);
+    expect(reduceIntent(scene, { kind: 'removeLayer', id: DEFAULT_LAYER.id })).toBe(scene);
+  });
+
+  test('merging a layer moves its elements onto the other and removes it', ({ expect }) => {
+    const scene = layered();
+    const merge = mergeLayersIntent(scene, ['top', DEFAULT_LAYER.id], DEFAULT_LAYER.id);
+    expect(merge).toBeDefined();
+    const merged = merge ? reduceIntent(scene, merge) : scene;
+    expect(sceneLayers(merged).map((layer) => layer.id)).toEqual([DEFAULT_LAYER.id]);
+    expect(Object.keys(merged.nodes).sort()).toEqual(['a', 'b']);
+    expect(Object.keys(merged.links)).toEqual(['ab']);
+  });
+});

package/src/utils/layers.ts

@@ -0,0 +1,175 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// Scene layers: every node and link is on exactly one, the layers are ordered, and a hidden one is neither drawn nor
+// hit. A scene that names no layers has one, implicitly, which the first layer edit makes real.
+//
+
+import {
+  type Element,
+  type Intent,
+  type Layer,
+  type LayerId,
+  type Link,
+  type Node,
+  type Scene,
+  endpointNode,
+} from '../model/types.ts';
+import { between, sortByZ } from './order.ts';
+
+/** The layer of a scene that names none: every element is on it. */
+export const DEFAULT_LAYER: Layer = { id: 'layer', name: 'Layer 1', z: between() };
+
+/** A scene's layers, bottom first; a scene with none has the implicit `DEFAULT_LAYER`. */
+export const sceneLayers = (scene: Scene): Layer[] => {
+  const layers = sortByZ(Object.values(scene.layers ?? {}));
+  return layers.length > 0 ? layers : [DEFAULT_LAYER];
+};
+
+/** The layer an element is on: its own, else (unset, or a layer the scene does not have) the bottom one. */
+export const elementLayer = (element: Element, layers: readonly Layer[]): LayerId =>
+  element.layer !== undefined && layers.some((layer) => layer.id === element.layer)
+    ? element.layer
+    : (layers[0]?.id ?? DEFAULT_LAYER.id);
+
+/** The layer new elements go on: the active one when the scene has it, else the top layer. */
+export const activeLayer = (scene: Scene, active: LayerId | undefined): LayerId => {
+  const layers = sceneLayers(scene);
+  return layers.find((layer) => layer.id === active)?.id ?? layers[layers.length - 1].id;
+};
+
+/** Nodes in paint order: by their layer's order, then by their own `z`. */
+export const layerOrder = (nodes: readonly Node[], layers: readonly Layer[]): Node[] => {
+  const rank = new Map(layers.map((layer, index) => [layer.id, index]));
+  const rankOf = (node: Node) => rank.get(elementLayer(node, layers)) ?? 0;
+  return sortByZ(nodes).sort((left, right) => rankOf(left) - rankOf(right));
+};
+
+/**
+ * The scene as drawn and hit: without the elements of hidden layers, or the links to a node that is hidden. The same
+ * scene when no layer is hidden, so a memo over it holds.
+ */
+export const visibleScene = (scene: Scene): Scene => {
+  const layers = sceneLayers(scene);
+  const hidden = new Set(layers.filter((layer) => layer.hidden).map((layer) => layer.id));
+  if (hidden.size === 0) {
+    return scene;
+  }
+  const nodes = Object.fromEntries(
+    Object.entries(scene.nodes).filter(([, node]) => !hidden.has(elementLayer(node, layers))),
+  );
+  const shown = (link: Link) =>
+    !hidden.has(elementLayer(link, layers)) &&
+    [link.source, link.target].every((end) => {
+      const node = endpointNode(end);
+      return node === undefined || nodes[node] !== undefined;
+    });
+  const links = Object.fromEntries(Object.entries(scene.links).filter(([, link]) => shown(link)));
+  return { ...scene, nodes, links };
+};
+
+/** The scene's layers as a record, the implicit layer made real so a new layer does not take its elements. */
+const layerRecord = (scene: Scene): Record<LayerId, Layer> =>
+  scene.layers && Object.keys(scene.layers).length > 0 ? { ...scene.layers } : { [DEFAULT_LAYER.id]: DEFAULT_LAYER };
+
+/**
+ * The scene with its layers named and every element on one by name: an element with no layer, or one the scene does not
+ * have, takes the layer it is drawn on (`elementLayer`). The same scene when nothing changes, so a memo over it holds.
+ */
+export const pinLayers = (scene: Scene): Scene => {
+  const layers = sceneLayers(scene);
+  const pin = <T extends Element>(record: Record<string, T>): Record<string, T> | undefined => {
+    const loose = Object.values(record).filter((element) => element.layer !== elementLayer(element, layers));
+    return loose.length === 0
+      ? undefined
+      : {
+          ...record,
+          ...Object.fromEntries(
+            loose.map((element) => [element.id, { ...element, layer: elementLayer(element, layers) }]),
+          ),
+        };
+  };
+  const named = scene.layers && Object.keys(scene.layers).length > 0;
+  const nodes = pin(scene.nodes);
+  const links = pin(scene.links);
+  return named && !nodes && !links
+    ? scene
+    : { ...scene, layers: layerRecord(scene), nodes: nodes ?? scene.nodes, links: links ?? scene.links };
+};
+
+/** Applies a layer intent to the scene (`reduceIntent` delegates here). */
+export const reduceLayerIntent = (scene: Scene, intent: Extract<Intent, { kind: 'layer' | 'removeLayer' }>): Scene => {
+  if (intent.kind === 'layer') {
+    // Pinned first: an element without a layer is on the bottom one, so a layer added below would otherwise take it.
+    const pinned = pinLayers(scene);
+    return { ...pinned, layers: { ...layerRecord(pinned), [intent.layer.id]: intent.layer } };
+  }
+  const layers = sceneLayers(scene);
+  if (layers.length < 2 || !layers.some((layer) => layer.id === intent.id)) {
+    return scene;
+  }
+  const { [intent.id]: _, ...rest } = layerRecord(scene);
+  // The elements on the removed layer go with it; `elementLayer` is read against the layers before the removal.
+  const keep = (element: Element) => elementLayer(element, layers) !== intent.id;
+  const nodes = Object.fromEntries(Object.entries(scene.nodes).filter(([, node]) => keep(node)));
+  const links = Object.fromEntries(
+    Object.entries(scene.links).filter(
+      ([, link]) =>
+        keep(link) &&
+        [link.source, link.target].every((end) => {
+          const node = endpointNode(end);
+          return node === undefined || nodes[node] !== undefined;
+        }),
+    ),
+  );
+  return { ...scene, nodes, links, layers: rest };
+};
+
+/** A new layer below the others, so it ends the top-first list, named after the first `Layer <n>` not taken. */
+export const createLayer = (scene: Scene, id: LayerId): Layer => {
+  const layers = sceneLayers(scene);
+  const names = new Set(layers.map((layer) => layer.name));
+  let index = layers.length + 1;
+  while (names.has(`Layer ${index}`)) {
+    index++;
+  }
+  return { id, name: `Layer ${index}`, z: between(undefined, layers[0]?.z) };
+};
+
+/** The layer moved to `index` in the bottom-first order. */
+export const moveLayer = (scene: Scene, id: LayerId, index: number): Layer | undefined => {
+  const layers = sceneLayers(scene);
+  const layer = layers.find((candidate) => candidate.id === id);
+  if (!layer) {
+    return undefined;
+  }
+  const others = layers.filter((candidate) => candidate.id !== id);
+  return { ...layer, z: between(others[index - 1]?.z, others[index]?.z) };
+};
+
+/**
+ * Merging layers into `into`, as one batch: the elements of every layer in `from` move onto `into`, keeping their own
+ * order, and those layers are removed. None unless `into` and at least one other of `from` are layers of the scene.
+ */
+export const mergeLayersIntent = (scene: Scene, from: readonly LayerId[], into: LayerId): Intent | undefined => {
+  const layers = sceneLayers(scene);
+  const ids = new Set(layers.map((layer) => layer.id));
+  const merged = new Set(from.filter((id) => id !== into && ids.has(id)));
+  if (!ids.has(into) || merged.size === 0) {
+    return undefined;
+  }
+  const moved = [...Object.values(scene.nodes), ...Object.values(scene.links)].filter((element) =>
+    merged.has(elementLayer(element, layers)),
+  );
+  return {
+    kind: 'batch',
+    intents: [
+      // The implicit layer is made real first, so the elements left on it keep it once the others are gone.
+      ...(scene.layers ? [] : layers.map((layer): Intent => ({ kind: 'layer', layer }))),
+      ...moved.map((element): Intent => ({ kind: 'update', id: element.id, values: { layer: into } })),
+      ...[...merged].map((id): Intent => ({ kind: 'removeLayer', id })),
+    ],
+  };
+};

package/src/utils/parts.test.ts

@@ -2,52 +2,85 @@
 // Copyright 2026 DXOS.org
 //
 
+import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
+import { type NodeRegistry, defaultNodeRegistry } from '../model/registry.ts';
+import { nodeBase } from '../model/types.ts';
 import { SceneBuilder } from './builder.ts';
-import { isMultiline, partKey, partText, partValues } from './parts.ts';
+import { isMultiline, nodeParts, nodeTitle, partText, partValues } from './parts.ts';
 import { frameClasses, hueClasses, resolveStyle } from './style.ts';
 
 describe('parts', () => {
   const box = { x: 0, y: 0, width: 256, height: 128 };
+  // A host type with a list part, the way a contributed type declares its text.
+  const ListNode = Schema.Struct({
+    type: Schema.Literal('list'),
+    ...nodeBase,
+    title: Schema.String,
+    items: Schema.Array(Schema.String),
+  });
+  const registry: NodeRegistry = {
+    ...defaultNodeRegistry,
+    list: {
+      ...defaultNodeRegistry.rect,
+      type: 'list',
+      schema: ListNode,
+      parts: [{ field: 'title' }, { field: 'items', lines: true }],
+    },
+  };
   const {
     scenes: [{ nodes }],
   } = SceneBuilder.scene('s', [
     SceneBuilder.rect('r', box),
-    SceneBuilder.class('c', box).properties({ name: 'Person', attributes: ['name: string'], methods: [] }),
-  ]).build();
+    SceneBuilder.note('n', box),
+    SceneBuilder.node('list', 'l', box).properties({ title: 'Todo', items: ['buy milk'] }),
+  ]).build(registry);
   const rect = nodes.r;
-  const cls = nodes.c;
+  const note = nodes.n;
+  const list = nodes.l;
 
-  test('reads a part as text and writes it back as the node property', ({ expect }) => {
-    expect(partText(rect, 'label')).toBe('');
-    expect(partText(rect, 'name')).toBeUndefined();
-    expect(partText(cls, 'attributes')).toBe('name: string');
-    expect(partValues(rect, 'label', 'A')).toEqual({ label: 'A' });
-    expect(partValues(cls, 'attributes', 'a: string\n\n b: number \n')).toEqual({
-      attributes: ['a: string', 'b: number'],
-    });
-    expect(partValues(cls, 'name', ' Org ')).toEqual({ name: 'Org' });
-    expect(partValues(rect, 'methods', 'x')).toBeUndefined();
+  test("reads a part as text and writes it back as the node property, by the type's declared parts", ({ expect }) => {
+    expect(partText(registry, rect, 'label')).toBe('');
+    expect(partText(registry, rect, 'items')).toBeUndefined();
+    expect(partText(registry, list, 'items')).toBe('buy milk');
+    expect(partValues(registry, rect, 'label', 'A')).toEqual({ label: 'A' });
+    expect(partValues(registry, list, 'items', 'a\n\n b \n')).toEqual({ items: ['a', 'b'] });
+    expect(partValues(registry, rect, 'items', 'x')).toBeUndefined();
+    // The first part is the node's main text.
+    expect(nodeTitle(registry, list)).toBe('Todo');
+    expect(nodeTitle(registry, note)).toBe('Note');
   });
 
-  test('lists and bodies are multi-line; labels and names are not', ({ expect }) => {
-    expect(isMultiline('attributes')).toBe(true);
-    expect(isMultiline('text')).toBe(true);
-    expect(isMultiline('label')).toBe(false);
-    expect(partKey('label')).toBe('label');
-    expect(partKey('other')).toBeUndefined();
+  test('lists and bodies are multi-line; labels are not', ({ expect }) => {
+    const [label] = nodeParts(registry, rect);
+    const [body] = nodeParts(registry, note);
+    const [, items] = nodeParts(registry, list);
+    expect([isMultiline(label), isMultiline(body), isMultiline(items)]).toEqual([false, true, true]);
   });
 
   test('frame classes follow the style', ({ expect }) => {
-    expect(frameClasses(rect, false)).toEqual(['bg-base-surface', '', 'border-separator', '', 'rounded-sm', '']);
-    expect(frameClasses(rect, true)[2]).toBe('border-primary-500');
-    expect(frameClasses(rect, false, true)[2]).toBe('border-primary-500/50');
+    expect(frameClasses(rect, false)).toEqual(['bg-base-surface', '', 'border-separator', '', 'rounded-sm']);
+    expect(frameClasses(rect, true)[2]).toBe('border-focus');
+    expect(frameClasses(rect, false, true)[2]).toBe('border-focus/50');
     const styled = { ...rect, style: { hue: 'teal', rounded: true, fill: false, border: false } };
-    expect(frameClasses(styled, false)).toEqual(['', 'text-teal-fg', 'border-transparent', '', 'rounded-2xl', '']);
-    // A guide is dashed and unfilled whatever fill and border say; the host's class comes last.
-    const guide = { ...rect, style: { guide: true, border: false, className: 'shadow' } };
-    expect(frameClasses(guide, false)).toEqual(['', '', 'border-separator', 'border-dashed', 'rounded-sm', 'shadow']);
+    expect(frameClasses(styled, false)).toEqual(['', 'text-teal-fg', 'border-transparent', '', 'rounded-2xl']);
+    // A guide is dashed and unfilled whatever fill and border say.
+    const guide = { ...rect, style: { guide: true, border: false } };
+    expect(frameClasses(guide, false)).toEqual(['', '', 'border-separator', 'border-dashed', 'rounded-sm']);
+  });
+
+  test('a scene shape showing its contents is opaque even in outline', ({ expect }) => {
+    const { scenes } = SceneBuilder.scene('s', [
+      SceneBuilder.scene('open')
+        .at(box)
+        .properties({ style: { hue: 'green', tone: 0 } }),
+      SceneBuilder.scene('closed')
+        .at(box)
+        .properties({ label: 'Closed', style: { hue: 'green', tone: 0 } }),
+    ]).build();
+    expect(frameClasses(scenes[0].nodes.open, false)[0]).toBe('bg-base-surface');
+    expect(frameClasses(scenes[0].nodes.closed, false)[0]).toBe('bg-transparent');
   });
 
   test('every tone keeps the hue border; tone 0 drops the fill, unset is tone 2', ({ expect }) => {
@@ -56,9 +89,10 @@ describe('parts', () => {
       text: '',
       border: 'border-blue-border',
     });
+    // Tones 1 to 3 run strongest to lightest.
     expect(hueClasses('blue', 1)).toEqual({
-      surface: 'bg-blue-200',
-      text: 'text-blue-900',
+      surface: 'bg-blue-500',
+      text: 'text-neutral-50',
       border: 'border-blue-border',
     });
     expect(hueClasses('blue')).toEqual(hueClasses('blue', 2));
@@ -68,11 +102,11 @@ describe('parts', () => {
       border: 'border-blue-border',
     });
     expect(hueClasses('blue', 3)).toEqual({
-      surface: 'bg-blue-bg',
-      text: 'text-neutral-50',
+      surface: 'bg-blue-300',
+      text: 'text-blue-900',
       border: 'border-blue-border',
     });
-    // A hue the picker does not offer draws its stronger tones as medium; no hue ignores the tone.
+    // A hue the picker does not offer draws its stronger tones as its role pair; no hue ignores the tone.
     expect(hueClasses('lime', 3)).toEqual(hueClasses('lime'));
     expect(hueClasses(undefined, 3)).toEqual(hueClasses(undefined));
   });