@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/src/utils/scenes.test.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { SceneBuilder } from './builder.ts';
+import { sceneOptions } from './scenes.ts';
+
+describe('sceneOptions', () => {
+  const box = (x: number) => ({ x, y: 0, width: 200, height: 100 });
+  const { scenes: list } = SceneBuilder.scene('root', [
+    SceneBuilder.scene('a', [SceneBuilder.scene('x').at(box(0)).properties({ label: 'Inner' })])
+      .name('A')
+      .at(box(0)),
+    SceneBuilder.scene('b').name('B').at(box(300)),
+  ]).build();
+  const scenes = Object.fromEntries(list.map((scene) => [scene.id, scene]));
+
+  test('lists every scene a shape may open, named or by the label of a shape that opens it', ({ expect }) => {
+    expect(sceneOptions(scenes, ['root'])).toEqual([
+      { value: 'a', label: 'A' },
+      { value: 'b', label: 'B' },
+      { value: 'x', label: 'Inner' },
+    ]);
+  });
+
+  test('never offers a scene that would open the path again', ({ expect }) => {
+    // Inside `a`: neither `a` nor the root, which opens `a`, may be opened from it; `b` and `x` may.
+    expect(sceneOptions(scenes, ['root', 'a']).map((option) => option.value)).toEqual(['b', 'x']);
+    // Inside `x`: `a` opens `x`, so it is out too.
+    expect(sceneOptions(scenes, ['root', 'a', 'x']).map((option) => option.value)).toEqual(['b']);
+  });
+
+  test('a host narrows the candidates', ({ expect }) => {
+    expect(sceneOptions(scenes, ['root'], (id) => id !== 'x').map((option) => option.value)).toEqual(['a', 'b']);
+  });
+});

package/src/utils/scenes.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type SceneMap } from '../model/store.ts';
+import { type Scene, type SceneId, isFrameNode } from '../model/types.ts';
+
+/** A scene a scene shape may open, as the properties panel lists it. */
+export type SceneOption = { value: SceneId; label: string };
+
+/** The scenes the shapes of `scene` open. */
+const childScenes = (scene: Scene | undefined): SceneId[] =>
+  scene ? Object.values(scene.nodes).flatMap((node) => (isFrameNode(node) ? [node.scene] : [])) : [];
+
+/** Whether `from`, or any scene it opens however deep, is one of `targets`. */
+const reaches = (scenes: SceneMap, from: SceneId, targets: ReadonlySet<SceneId>): boolean => {
+  const seen = new Set<SceneId>();
+  const pending = [from];
+  for (let id = pending.pop(); id !== undefined; id = pending.pop()) {
+    if (targets.has(id)) {
+      return true;
+    }
+    if (!seen.has(id)) {
+      seen.add(id);
+      pending.push(...childScenes(scenes[id]));
+    }
+  }
+  return false;
+};
+
+/**
+ * The scenes a shape in the scene at the head of `path` may open: any scene of the store, shared by as many shapes
+ * as open it, except one that would open the path again, which would nest the scene in itself without end. An
+ * unnamed scene reads as the label of a shape that opens it.
+ */
+export const sceneOptions = (
+  scenes: SceneMap,
+  path: readonly SceneId[],
+  filter: (id: SceneId) => boolean = () => true,
+): SceneOption[] => {
+  const ancestors = new Set(path);
+  const labels = new Map<SceneId, string>();
+  for (const scene of Object.values(scenes)) {
+    for (const node of Object.values(scene.nodes)) {
+      if (isFrameNode(node) && node.label && !labels.has(node.scene)) {
+        labels.set(node.scene, node.label);
+      }
+    }
+  }
+  return Object.values(scenes)
+    .filter((scene) => filter(scene.id) && !reaches(scenes, scene.id, ancestors))
+    .map((scene) => ({ value: scene.id, label: scene.name ?? labels.get(scene.id) ?? scene.id }))
+    .sort((left, right) => left.label.localeCompare(right.label));
+};

package/src/utils/shapes.test.ts

@@ -4,7 +4,8 @@
 
 import { describe, test } from 'vitest';
 
-import { cloneShape, createNode } from './shapes.ts';
+import { type SplineLink } from '../model/types.ts';
+import { cloneShape, createNode, flipLink } from './shapes.ts';
 
 describe('shapes', () => {
   test('a cloned shape keeps the look and size but not the text, identity or place', ({ expect }) => {
@@ -15,7 +16,7 @@ describe('shapes', () => {
       style: { hue: 'teal', rounded: true },
     };
     const fresh = createNode({ type: 'rect', id: 'b', z: 'a1', center: { x: 400, y: 0 }, size: source.size });
-    expect(cloneShape(source, fresh)).toEqual({
+    expect(cloneShape(source, fresh, [{ field: 'label' }])).toEqual({
       type: 'rect',
       id: 'b',
       z: 'a1',
@@ -26,13 +27,37 @@ describe('shapes', () => {
     });
   });
 
-  test('a cloned portal opens onto its own scene, and a class gets its type text', ({ expect }) => {
-    const portal = createNode({ type: 'scene', id: 'p', z: 'a0', center: { x: 0, y: 0 }, scene: 'scene:p' });
-    const copy = cloneShape(portal, createNode({ type: 'scene', id: 'q', z: 'a1', center: { x: 0, y: 0 } }));
+  test('a cloned portal opens onto its own scene, and a note gets its type text', ({ expect }) => {
+    const portal = createNode({ type: 'frame', id: 'p', z: 'a0', center: { x: 0, y: 0 }, scene: 'scene:p' });
+    const copy = cloneShape(portal, createNode({ type: 'frame', id: 'q', z: 'a1', center: { x: 0, y: 0 } }));
     expect(copy).toMatchObject({ id: 'q', scene: 'q' });
 
-    const named = { ...createNode({ type: 'class', id: 'c', z: 'a0', center: { x: 0, y: 0 } }), name: 'Person' };
-    const fresh = createNode({ type: 'class', id: 'd', z: 'a1', center: { x: 0, y: 0 } });
-    expect(cloneShape(named, fresh)).toMatchObject({ id: 'd', name: 'Class' });
+    const named = { ...createNode({ type: 'note', id: 'c', z: 'a0', center: { x: 0, y: 0 } }), text: 'Mine' };
+    const fresh = createNode({ type: 'note', id: 'd', z: 'a1', center: { x: 0, y: 0 } });
+    expect(cloneShape(named, fresh, [{ field: 'text', multiline: true }])).toMatchObject({ id: 'd', text: 'Note' });
+  });
+
+  test('flipping a link swaps its ends, keeps its markers and reverses a spline', ({ expect }) => {
+    const link: SplineLink = {
+      type: 'spline',
+      id: 'l',
+      z: 'a',
+      source: { node: 'a', port: 'e1' },
+      target: { point: { x: 100, y: 0 } },
+      ends: { end: 'arrow' },
+      points: [
+        { x: 10, y: 0 },
+        { x: 20, y: 5 },
+      ],
+    };
+    const flipped = flipLink(link);
+    expect(flipped).toEqual({
+      source: { point: { x: 100, y: 0 } },
+      target: { node: 'a', port: 'e1' },
+      points: [
+        { x: 20, y: 5 },
+        { x: 10, y: 0 },
+      ],
+    });
   });
 });

package/src/utils/shapes.ts

@@ -12,19 +12,18 @@ import {
   type Bounds,
   type BuiltinNode,
   type BuiltinNodeType,
+  DEFAULT_GRID,
   type Endpoint,
   type Link,
   type LinkEnds,
   type LinkType,
+  type LinkValues,
+  MAJOR_GRID_RATIO,
   type Node,
   type Point,
   type Size,
-  isClassNode,
-  isEllipseNode,
-  isNoteNode,
-  isRectNode,
 } from '../model/types.ts';
-import { partKey } from './parts.ts';
+import { type PartField } from './parts.ts';
 
 /** Axis-aligned frame of a node: its size centred on its centre. */
 export const nodeBounds = (node: Node): Bounds => ({
@@ -43,24 +42,44 @@ export const resizeNode = <N extends Node>(node: N, bounds: Bounds): N => ({
   size: { width: bounds.width, height: bounds.height },
 });
 
-/** The bounding box a new basic shape gets: rectangle, ellipse and class share it, so a new circle matches a new square. */
-export const DEFAULT_SHAPE_SIZE: Size = { width: 256, height: 256 };
+/** Scene px of one nominal unit (a major grid cell) at the default grid. */
+export const DEFAULT_CELL = DEFAULT_GRID * MAJOR_GRID_RATIO;
 
+/** A nominal size (in major grid cells) in scene px, for a drawing whose major cell is `cell` px. */
+export const nominalSize = (size: Size, cell: number = DEFAULT_CELL): Size => ({
+  width: size.width * cell,
+  height: size.height * cell,
+});
+
+/**
+ * The built-in types' sizes when created, in nominal units: one unit is the drawing's major grid cell, so a
+ * new shape scales with the drawing's grid.
+ */
+export const NOMINAL_SIZES: Record<BuiltinNodeType, Size> = {
+  rect: { width: 2, height: 1 },
+  ellipse: { width: 2, height: 2 },
+  note: { width: 4, height: 2 },
+  frame: { width: 4, height: 2 },
+};
+
+/** The built-in types' sizes in scene px, for fixtures and imports, whose layouts are written against them. */
 export const DEFAULT_SIZES: Record<BuiltinNodeType, Size> = {
-  rect: DEFAULT_SHAPE_SIZE,
-  ellipse: DEFAULT_SHAPE_SIZE,
-  class: DEFAULT_SHAPE_SIZE,
+  rect: { width: 256, height: 256 },
+  ellipse: { width: 256, height: 256 },
   note: { width: 256, height: 128 },
-  scene: { width: 512, height: 256 },
+  frame: { width: 512, height: 256 },
 };
 
+/** The bounding box a new basic shape gets at the default grid. */
+export const DEFAULT_SHAPE_SIZE: Size = DEFAULT_SIZES.rect;
+
 export type CreateNodeProps = {
   type: BuiltinNodeType;
   id: string;
   z: string;
   center: Point;
   size?: Size;
-  /** A portal's child scene id. */
+  /** A frame's child scene id. */
   scene?: string;
 };
 
@@ -79,11 +98,9 @@ export const createNode = ({
       return { type, id, z, center, size };
     case 'ellipse':
       return { type, id, z, center, size };
-    case 'class':
-      return { type, id, z, center, size, name: 'Class', attributes: ['id: string'], methods: ['save(): void'] };
     case 'note':
       return { type, id, z, center, size, text: 'Note' };
-    case 'scene':
+    case 'frame':
       return { type, id, z, center, size, scene: scene ?? id };
   }
 };
@@ -95,23 +112,12 @@ const OWN_FIELDS = new Set(['id', 'type', 'z', 'center', 'scene']);
  * A new shape like `source` (its size, look and ports) built on `fresh`, the type's own new node at the
  * new place: it keeps its own identity and child scene, and the type's text rather than the source's.
  */
-export const cloneShape = (source: Node, fresh: Node): Node => ({
-  ...fresh,
-  ...Object.fromEntries(Object.entries(source).filter(([key]) => !OWN_FIELDS.has(key) && !partKey(key))),
-});
-
-/** The node's display text, in the field its type uses for it; a type without one is returned as is. */
-export const withLabel = <N extends Node>(node: N, label: string): N => {
-  if (isRectNode(node) || isEllipseNode(node)) {
-    return { ...node, label };
-  }
-  if (isClassNode(node)) {
-    return { ...node, name: label };
-  }
-  if (isNoteNode(node)) {
-    return { ...node, text: label };
-  }
-  return node;
+export const cloneShape = (source: Node, fresh: Node, parts: readonly PartField[] = []): Node => {
+  const text = new Set(parts.map(({ field }) => field));
+  return {
+    ...fresh,
+    ...Object.fromEntries(Object.entries(source).filter(([key]) => !OWN_FIELDS.has(key) && !text.has(key))),
+  };
 };
 
 export type CreateLinkProps = {
@@ -122,13 +128,12 @@ export type CreateLinkProps = {
   target: Endpoint;
   /** Where a new spline gets its first control point; ignored by the other types. */
   midpoint?: Point;
-  directed?: boolean;
   ends?: LinkEnds;
 };
 
 /** A new link of `type`; a spline starts with one control point so it is editable at once. */
-export const createLink = ({ type, id, z, source, target, midpoint, directed, ends }: CreateLinkProps): Link => {
-  const base = { id, z, source, target, ...(directed ? { directed } : {}), ...(ends ? { ends } : {}) };
+export const createLink = ({ type, id, z, source, target, midpoint, ends }: CreateLinkProps): Link => {
+  const base = { id, z, source, target, ...(ends ? { ends } : {}) };
   switch (type) {
     case 'line':
     case 'curve':
@@ -138,3 +143,14 @@ export const createLink = ({ type, id, z, source, target, midpoint, directed, en
       return { type, ...base, points: midpoint ? [midpoint] : [] };
   }
 };
+
+/**
+ * The `update` values that reverse a link: source and target swap while the markers stay at the start and
+ * end, so an arrow comes to point the other way; a spline's control points run the other way, so the drawn
+ * path keeps its shape.
+ */
+export const flipLink = (link: Link): LinkValues => ({
+  source: link.target,
+  target: link.source,
+  ...(link.type === 'spline' ? { points: [...link.points].reverse() } : {}),
+});

package/src/utils/style.test.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type StyleMap } from '../model/types.ts';
+import { SceneBuilder } from './builder.ts';
+import { classedLink, classedNode, frameClasses, splitClassEdit } from './style.ts';
+
+describe('style classes', () => {
+  const styles: StyleMap = {
+    warn: { id: 'warn', name: 'Warning', style: { hue: 'red', lineStyle: 'dashed', rounded: true } },
+  };
+  const box = { x: 0, y: 0, width: 200, height: 100 };
+  const {
+    scenes: [{ nodes, links }],
+  } = SceneBuilder.scene('s', [
+    SceneBuilder.rect('a', box).properties({ class: 'warn', style: { hue: 'blue' } }),
+    SceneBuilder.rect('b', { ...box, x: 400 }).properties({ class: 'gone' }),
+    SceneBuilder.link('line', 'a', 'b')
+      .id('l')
+      .properties({ class: 'warn', style: { lineStyle: 'solid' } }),
+  ]).build();
+
+  test('an element takes its class look under its own', ({ expect }) => {
+    expect(classedNode(nodes.a, styles).style).toEqual({ hue: 'blue', lineStyle: 'dashed', rounded: true });
+    // A link takes only the common base of the class's style: its colour and line style.
+    expect(classedLink(links.l, styles).style).toEqual({ hue: 'red', lineStyle: 'solid' });
+  });
+
+  test("a node's line style draws its border", ({ expect }) => {
+    expect(frameClasses(classedNode(nodes.a, styles), false)).toEqual(expect.arrayContaining(['border-dashed']));
+  });
+
+  test('a missing class leaves the element as it is', ({ expect }) => {
+    expect(classedNode(nodes.b, styles)).toBe(nodes.b);
+  });
+
+  test('an edit of a classed look goes to the class, and the element stops overriding it', ({ expect }) => {
+    // A shows blue over the class's red; the user picks green and turns rounding off.
+    const shown = classedNode(nodes.a, styles).style;
+    const edited = { hue: 'green', rounded: false };
+    expect(splitClassEdit(shown, edited, styles.warn.style ?? {}, nodes.a.style)).toEqual({
+      classLook: { hue: 'green', lineStyle: 'dashed', rounded: false },
+      own: {},
+    });
+    // An unchanged field stays where it was: A keeps its own blue, the class its red.
+    expect(splitClassEdit(shown, { ...shown, rounded: false }, styles.warn.style ?? {}, nodes.a.style)).toEqual({
+      classLook: { hue: 'red', lineStyle: 'dashed', rounded: false },
+      own: { hue: 'blue' },
+    });
+  });
+});

package/src/utils/style.ts

@@ -7,7 +7,20 @@
 // every hue is spelled out here rather than composed from the hue name.
 //
 
-import { type Node, type NodeStyle, type NodeTone, isEllipseNode } from '../model/types.ts';
+import {
+  type HorizontalAlign,
+  type Link,
+  type Node,
+  type NodeStyle,
+  type NodeTone,
+  STYLE_HUES,
+  type StyleHue,
+  type StyleMap,
+  type VerticalAlign,
+  isEllipseNode,
+  isFrameNode,
+  showsContents,
+} from '../model/types.ts';
 
 export type HueClasses = { surface: string; text: string; border: string };
 
@@ -32,14 +45,10 @@ const HUES: Record<string, HueClasses> = {
   rose: { surface: 'bg-rose-surface', text: 'text-rose-fg', border: 'border-rose-border' },
 };
 
-/** The hues the style picker offers, neutral first; any theme hue still renders, at its `medium` tone. */
-export const STYLE_HUES = ['neutral', 'red', 'orange', 'amber', 'green', 'teal', 'blue', 'violet', 'pink'] as const;
-export type StyleHue = (typeof STYLE_HUES)[number];
-
 export const TONES: readonly NodeTone[] = [0, 1, 2, 3];
 
 /** What each tone is called, for labels. */
-export const TONE_NAMES: Record<NodeTone, string> = { 0: 'outline', 1: 'light', 2: 'medium', 3: 'strong' };
+export const TONE_NAMES: Record<NodeTone, string> = { 0: 'outline', 1: 'strong', 2: 'medium', 3: 'light' };
 
 /** The tone a hue without one draws at: the look a hue had before tones. */
 export const DEFAULT_TONE: NodeTone = 2;
@@ -47,56 +56,56 @@ export const DEFAULT_TONE: NodeTone = 2;
 type ToneClasses = { surface: string; text: string };
 
 /**
- * The fills lighter and stronger than a hue's `surface` role: the scale's 200 under its darkest text, and the
- * hue's solid `bg` role under light text (tones 1 and 3). Tone 2 is the role pair in `HUES`; tone 0 has no fill.
+ * The fills either side of a hue's `surface` role (its 400): the scale's 500 under light text (tone 1), and its
+ * 300 under its darkest text (tone 3). Tone 2 is the role pair in `HUES`; tone 0 has no fill.
  */
-const TONE_FILLS: Record<StyleHue, Record<1 | 3, ToneClasses>> = {
+const TONE_FILLS: Record<StyleHue, Record<'strong' | 'light', ToneClasses>> = {
   neutral: {
-    1: { surface: 'bg-neutral-200', text: 'text-neutral-900' },
-    3: { surface: 'bg-neutral-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-neutral-300', text: 'text-neutral-900' },
+    strong: { surface: 'bg-neutral-500', text: 'text-neutral-50' },
   },
   red: {
-    1: { surface: 'bg-red-200', text: 'text-red-900' },
-    3: { surface: 'bg-red-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-red-300', text: 'text-red-900' },
+    strong: { surface: 'bg-red-500', text: 'text-neutral-50' },
   },
   orange: {
-    1: { surface: 'bg-orange-200', text: 'text-orange-900' },
-    3: { surface: 'bg-orange-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-orange-300', text: 'text-orange-900' },
+    strong: { surface: 'bg-orange-500', text: 'text-neutral-50' },
   },
   amber: {
-    1: { surface: 'bg-amber-200', text: 'text-amber-900' },
-    3: { surface: 'bg-amber-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-amber-300', text: 'text-amber-900' },
+    strong: { surface: 'bg-amber-500', text: 'text-neutral-50' },
   },
   green: {
-    1: { surface: 'bg-green-200', text: 'text-green-900' },
-    3: { surface: 'bg-green-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-green-300', text: 'text-green-900' },
+    strong: { surface: 'bg-green-500', text: 'text-neutral-50' },
   },
   teal: {
-    1: { surface: 'bg-teal-200', text: 'text-teal-900' },
-    3: { surface: 'bg-teal-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-teal-300', text: 'text-teal-900' },
+    strong: { surface: 'bg-teal-500', text: 'text-neutral-50' },
+  },
+  sky: {
+    light: { surface: 'bg-sky-300', text: 'text-sky-900' },
+    strong: { surface: 'bg-sky-500', text: 'text-neutral-50' },
   },
   blue: {
-    1: { surface: 'bg-blue-200', text: 'text-blue-900' },
-    3: { surface: 'bg-blue-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-blue-300', text: 'text-blue-900' },
+    strong: { surface: 'bg-blue-500', text: 'text-neutral-50' },
   },
   violet: {
-    1: { surface: 'bg-violet-200', text: 'text-violet-900' },
-    3: { surface: 'bg-violet-bg', text: 'text-neutral-50' },
-  },
-  pink: {
-    1: { surface: 'bg-pink-200', text: 'text-pink-900' },
-    3: { surface: 'bg-pink-bg', text: 'text-neutral-50' },
+    light: { surface: 'bg-violet-300', text: 'text-violet-900' },
+    strong: { surface: 'bg-violet-500', text: 'text-neutral-50' },
   },
 };
 
-const isStyleHue = (hue: string): hue is StyleHue => STYLE_HUES.some((candidate) => candidate === hue);
+const isStyleHue = (hue: string | undefined): hue is StyleHue => STYLE_HUES.some((candidate) => candidate === hue);
 
 /** The default look: the base surface, the base text and the separator border. */
 const DEFAULT: HueClasses = { surface: 'bg-base-surface', text: '', border: 'border-separator' };
 
 /**
  * The classes a hue at a tone draws with. Every tone keeps the hue's border; tone 0 drops the fill and
- * keeps the default text, and a tone a hue has no fills for draws as `medium`.
+ * keeps the default text, and a tone a hue has no fills for draws as `medium` (its role pair).
  */
 export const hueClasses = (hue: string | undefined, tone: NodeTone = DEFAULT_TONE): HueClasses => {
   const base = (hue && HUES[hue]) || DEFAULT;
@@ -107,11 +116,38 @@ export const hueClasses = (hue: string | undefined, tone: NodeTone = DEFAULT_TON
     return { surface: 'bg-transparent', text: '', border: base.border };
   }
   if ((tone === 1 || tone === 3) && isStyleHue(hue)) {
-    return { ...TONE_FILLS[hue][tone], border: base.border };
+    return { ...TONE_FILLS[hue][tone === 1 ? 'strong' : 'light'], border: base.border };
   }
   return base;
 };
 
+/** `base` with every field `own` sets over it; an `undefined` field of `own` is unset, so it leaves the base's. */
+const overlay = <T extends object>(base: T | undefined, own: T | undefined): T | undefined => {
+  if (!base || !own) {
+    return own ?? base;
+  }
+  const merged = { ...base };
+  for (const [key, value] of Object.entries(own)) {
+    if (value !== undefined) {
+      Reflect.set(merged, key, value);
+    }
+  }
+  return merged;
+};
+
+/** A node as drawn: its class's style under its own (`StyleClass`). */
+export const classedNode = (node: Node, styles: StyleMap | undefined): Node => {
+  const style = node.class ? styles?.[node.class]?.style : undefined;
+  return style ? { ...node, style: overlay(style, node.style) } : node;
+};
+
+/** A link as drawn: its class's colour and line style under its own. */
+export const classedLink = (link: Link, styles: StyleMap | undefined): Link => {
+  const style = link.class ? styles?.[link.class]?.style : undefined;
+  // A link draws only the common base (`LineStyle`) of its class's style.
+  return style ? { ...link, style: overlay({ hue: style.hue, lineStyle: style.lineStyle }, link.style) } : link;
+};
+
 /**
  * A node's style with the defaults the frame draws spelled out: an unset `fill` or `border` is drawn, so
  * the properties panel must show it as on rather than as an unset (off) toggle.
@@ -124,24 +160,101 @@ export const resolveStyle = (style: NodeStyle = {}): NodeStyle => ({
 
 /**
  * Frame classes for a node: fill and text colour, border and corner radius from its style; a guide is
- * dashed and unfilled, and the host's `className` comes last so it wins.
+ * dashed and unfilled.
  */
 export const frameClasses = (node: Node, selected: boolean, hovered = false): string[] => {
   const style = resolveStyle(node.style);
   const hue = hueClasses(style.hue, style.tone);
   const filled = style.fill && !style.guide;
+  // A scene shape drawing its contents is a window onto another canvas, so it is opaque even in outline: the
+  // grid behind it would read as part of the child scene.
+  const opaque = isFrameNode(node) && showsContents(node);
+  const clear = !filled || hue.surface === 'bg-transparent';
+  const surface = opaque && clear ? 'bg-base-surface' : filled ? hue.surface : '';
   return [
-    filled ? hue.surface : '',
-    hue.text,
+    surface,
+    // A guide's hue marks its edge (a group's backdrop); its title reads in the default text colour.
+    style.guide ? '' : hue.text,
     selected
-      ? 'border-primary-500'
+      ? 'border-focus'
       : hovered
-        ? 'border-primary-500/50'
-        : style.border === false && !style.guide
+        ? 'border-focus/50'
+        : // A frame always shows its edge: it bounds a scene or an embedded object, which has none of its own.
+          style.border === false && !style.guide && !isFrameNode(node)
           ? 'border-transparent'
           : hue.border,
-    style.guide ? 'border-dashed' : '',
+    style.guide || style.lineStyle === 'dashed' ? 'border-dashed' : style.lineStyle === 'dotted' ? 'border-dotted' : '',
     isEllipseNode(node) ? 'rounded-[50%]' : style.rounded ? 'rounded-2xl' : 'rounded-sm',
-    style.className ?? '',
   ];
 };
+
+export type LineClasses = { stroke: string; fill: string };
+
+/** A link's stroke and its end markers' fill, in the hue's border colour so a link matches a node of its hue. */
+const LINE_CLASSES: Record<StyleHue, LineClasses> = {
+  neutral: { stroke: 'stroke-neutral-border', fill: 'fill-neutral-border' },
+  red: { stroke: 'stroke-red-border', fill: 'fill-red-border' },
+  orange: { stroke: 'stroke-orange-border', fill: 'fill-orange-border' },
+  amber: { stroke: 'stroke-amber-border', fill: 'fill-amber-border' },
+  green: { stroke: 'stroke-green-border', fill: 'fill-green-border' },
+  teal: { stroke: 'stroke-teal-border', fill: 'fill-teal-border' },
+  sky: { stroke: 'stroke-sky-border', fill: 'fill-sky-border' },
+  blue: { stroke: 'stroke-blue-border', fill: 'fill-blue-border' },
+  violet: { stroke: 'stroke-violet-border', fill: 'fill-violet-border' },
+};
+
+/** The default line: the grey every link drew before lines took a hue. */
+const DEFAULT_LINE: LineClasses = { stroke: 'stroke-neutral-500', fill: 'fill-neutral-500' };
+
+export const lineClasses = (hue: string | undefined): LineClasses =>
+  isStyleHue(hue) ? LINE_CLASSES[hue] : DEFAULT_LINE;
+
+/**
+ * Splits an edit of a classed element's look (`edited`, against what the panel `shown`): every field that changed
+ * goes to the class, so each element of the class derives it, and the element drops its own value for that field,
+ * which would otherwise hide the class's.
+ */
+export const splitClassEdit = <T extends object>(
+  shown: object | undefined,
+  edited: unknown,
+  classLook: T,
+  own: T | undefined,
+): { classLook: T; own: T | undefined } => {
+  const nextClass = { ...classLook };
+  const nextOwn = own ? { ...own } : undefined;
+  if (typeof edited === 'object' && edited !== null) {
+    for (const [key, value] of Object.entries(edited)) {
+      if (Reflect.get(shown ?? {}, key) !== value) {
+        Reflect.set(nextClass, key, value);
+        if (nextOwn) {
+          Reflect.deleteProperty(nextOwn, key);
+        }
+      }
+    }
+  }
+  return { classLook: nextClass, own: nextOwn };
+};
+
+const HORIZONTAL_CLASSES: Record<HorizontalAlign, string> = {
+  left: 'items-start text-left',
+  center: 'items-center text-center',
+  right: 'items-end text-right',
+};
+
+const VERTICAL_CLASSES: Record<VerticalAlign, string> = {
+  top: 'justify-start',
+  middle: 'justify-center',
+  bottom: 'justify-end',
+};
+
+/**
+ * Classes placing a text part in its shape by the style's alignment, else by the type's own (`defaults`): the part
+ * is a column, so `justify` places it down the shape and `items` across it.
+ */
+export const alignClasses = (
+  style: NodeStyle | undefined,
+  defaults: { horizontal: HorizontalAlign; vertical: VerticalAlign },
+): string =>
+  `flex flex-col ${HORIZONTAL_CLASSES[style?.alignHorizontal ?? defaults.horizontal]} ${
+    VERTICAL_CLASSES[style?.alignVertical ?? defaults.vertical]
+  }`;

package/src/utils/testing.test.ts

@@ -8,7 +8,7 @@ import { solve } from '../model/projections/constrained.ts';
 import { layoutGraph } from '../model/projections/dynamic.ts';
 import { MAJOR_GRID, type Point, type Scene } from '../model/types.ts';
 import { nodeBounds } from './shapes.ts';
-import { createClassSceneTree, createSceneTree } from './testing.ts';
+import { createModelSceneTree, createSceneTree } from './testing.ts';
 
 /** Every edge of every node lies on the grid, which is what move and resize snap to. */
 const offGrid = (scene: Scene): string[] =>
@@ -42,8 +42,8 @@ describe('initial layouts conform to the major grid', () => {
     }
   });
 
-  test('class scene tree fixture', ({ expect }) => {
-    const { scenes, root } = createClassSceneTree();
+  test('model scene tree fixture', ({ expect }) => {
+    const { scenes, root } = createModelSceneTree();
     expect(scenes.map(({ id }) => id)).toContain(root);
     // Three levels: the root, its two subsystems, and one leaf under each.
     expect(scenes).toHaveLength(5);