@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/src/playwright/scene.spec.ts

@@ -9,9 +9,9 @@ import { setupPage, storybookUrl } from '@dxos/test-utils/playwright';
 import { SceneManager } from './SceneManager.ts';
 
 const PORT = 9006;
-const FREEHAND_URL = storybookUrl('ui-react-ui-canvas-scene-sceneview--freehand', PORT);
+const FREEHAND_URL = storybookUrl('ui-react-ui-canvas-sceneview--freehand', PORT);
 
-// The fixture (`createSceneTree(1)`): rectangle A, ellipse B, text T, class C; links A→B (curve), A→C
+// The fixture (`createSceneTree(1)`): rectangle A, ellipse B, text T, rectangle C; links A→B (curve), A→C
 // (line, directed) and B→C (spline). Every edge sits on the major grid.
 test.describe('SceneView', () => {
   let page: Page;
@@ -37,8 +37,8 @@ test.describe('SceneView', () => {
   test('draws the fixture with an arrowhead on the directed link', async () => {
     await expect(page.locator('[data-node-id]')).toHaveCount(4);
     expect(await scene.linkCount()).toBe(3);
-    // One marker set per layer (arrow and circle, start and end); the directed line uses the end arrow.
-    await expect(page.locator('[data-testid="scene-view"] marker')).toHaveCount(4);
+    // One marker set per layer (arrow, triangle and circle, start and end); the directed line uses the end arrow.
+    await expect(page.locator('[data-testid="scene-view"] marker')).toHaveCount(6);
     await expect(page.locator('[data-testid="scene-view"] path[marker-end]')).toHaveCount(1);
   });
 
@@ -83,7 +83,7 @@ test.describe('SceneView', () => {
     await expect(ports).toHaveCount(0);
     const box = await scene.box(scene.node('scene:root/a'));
     await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
-    await expect(scene.node('scene:root/a')).toHaveClass(/border-primary-500\/50/);
+    await expect(scene.node('scene:root/a')).toHaveClass(/border-focus\/50/);
     await expect(ports).not.toHaveCount(0);
     await page.mouse.move(box.x + box.width + 200, box.y + box.height + 200);
     await expect(ports).toHaveCount(0);
@@ -139,6 +139,8 @@ test.describe('SceneView', () => {
   });
 
   test('a marquee replaces the selection, shift adds and alt subtracts', async () => {
+    // Fit frames the shapes tightly, so step out to leave empty canvas around A for the marquee to start on.
+    await scene.zoomOut();
     const a = await scene.box(scene.node('scene:root/a'));
     // The empty canvas above and left of A, dragging back over A's corner. Not the other corner: the
     // B→C spline passes below and right of A, and a press on a link starts an endpoint drag.
@@ -217,12 +219,12 @@ test.describe('SceneView', () => {
     // No node was created: the drop landed on an existing one rather than on empty canvas.
     expect(await scene.nodeCount()).toBe(4);
     // The new link is the selection, and nothing else is.
-    await expect(page.locator('[data-link-id].stroke-primary-500')).toHaveCount(1);
+    await expect(page.locator('[data-link-id].stroke-focus')).toHaveCount(1);
     expect(await scene.selectedNodes()).toEqual([]);
     // The hover follows the pointer, not the gesture: the source is no longer highlighted, the target under
     // the released pointer is.
-    await expect(scene.node('scene:root/a')).not.toHaveClass(/border-primary-500\/50/);
-    await expect(scene.node('scene:root/c')).toHaveClass(/border-primary-500\/50/);
+    await expect(scene.node('scene:root/a')).not.toHaveClass(/border-focus\/50/);
+    await expect(scene.node('scene:root/c')).toHaveClass(/border-focus\/50/);
   });
 
   test('the line tool draws nothing when a press on a node never moves', async () => {
@@ -245,7 +247,7 @@ test.describe('SceneView', () => {
     // One step is ×1.25; both readouts round, so they can disagree by a point.
     await expect.poll(async () => Math.abs((await scene.zoom()) - fitted * 1.25)).toBeLessThanOrEqual(1);
     await page.getByTestId('toolbar-create').click();
-    await page.getByTestId('create-class').click();
+    await page.getByTestId('create-note').click();
     await expect(page.locator('[data-node-id]')).toHaveCount(5);
     await page.getByTestId('toolbar-delete').click();
     await expect(page.locator('[data-node-id]')).toHaveCount(4);
@@ -260,25 +262,25 @@ test.describe('SceneView', () => {
         return rows[0] < rows[1] && rows[1] < rows[2];
       })
       .toBe(true);
-    // A portal made from the toolbar gets its child scene, so Enter opens it.
+    // A frame made from the toolbar gets its child scene, so Enter opens it.
     await page.getByTestId('toolbar-create').click();
-    await page.getByTestId('create-scene').click();
+    await page.getByTestId('create-frame').click();
     await scene.focus();
     await page.keyboard.press('Enter');
     await expect(page.getByTestId('toolbar-up')).toBeEnabled();
   });
 
-  test('a scene shape opens from its zoom-in control', async () => {
+  test('a frame opens from its zoom-in control', async () => {
     await page.getByTestId('toolbar-create').click();
-    await page.getByTestId('create-scene').click();
+    await page.getByTestId('create-frame').click();
     await page.getByTestId('portal-open').first().click();
     await expect(page.getByTestId('toolbar-up')).toBeEnabled();
   });
 
-  test('the properties panel edits the selected class', async () => {
+  test('the properties panel edits the selected node', async () => {
     await scene.clickNode('scene:root/c');
     const labels = await page.locator('[data-testid="properties"] label').allTextContents();
-    expect(labels).toEqual(expect.arrayContaining(['Name', 'Attributes', 'Methods', 'Style']));
+    expect(labels).toEqual(expect.arrayContaining(['Label', 'Style']));
     // Geometry is two labelled number fields per row.
     expect(labels).toEqual(expect.arrayContaining(['X', 'Y', 'Width', 'Height', 'Ports per side']));
   });
@@ -289,14 +291,15 @@ test.describe('SceneView', () => {
     const option = (key: string) => grid.locator(`[data-style-option="${key}"]`);
     // An unstyled node matches no swatch.
     await expect(grid.locator('[aria-checked="true"]')).toHaveCount(0);
-    await option('blue:3').click();
-    await expect(option('blue:3')).toHaveAttribute('aria-checked', 'true');
-    await expect(scene.node('scene:root/a')).toHaveClass(/bg-blue-bg/);
+    // Tone 1 is the strongest fill.
+    await option('blue:1').click();
+    await expect(option('blue:1')).toHaveAttribute('aria-checked', 'true');
+    await expect(scene.node('scene:root/a')).toHaveClass(/bg-blue-500/);
     await option('neutral:0').click();
     await expect(option('neutral:0')).toHaveAttribute('aria-checked', 'true');
     // Outline: the fill goes (the selected frame's border shows the selection, not the hue).
     await expect(scene.node('scene:root/a')).toHaveClass(/bg-transparent/);
-    await expect(scene.node('scene:root/a')).not.toHaveClass(/bg-blue-bg/);
+    await expect(scene.node('scene:root/a')).not.toHaveClass(/bg-blue-500/);
   });
 
   test('the geometry fields step by the grid and move the node', async () => {
@@ -315,10 +318,10 @@ test.describe('SceneView', () => {
     await expect.poll(async () => (await scene.box(scene.node('scene:root/c'))).x).toBeGreaterThan(node.x);
   });
 
-  test('a read-only view selects but draws no handles and applies no edit', async ({ browser }) => {
+  test('a read-only view selects nothing, draws no handles and applies no edit', async ({ browser }) => {
     await close?.();
     ({ page, close } = await setupPage(browser, {
-      url: storybookUrl('ui-react-ui-canvas-scene-sceneview--readonly', PORT),
+      url: storybookUrl('ui-react-ui-canvas-sceneview--readonly', PORT),
       viewportSize: { width: 1400, height: 800 },
     }));
     page.on('pageerror', (error) => errors.push(error.message));
@@ -326,16 +329,15 @@ test.describe('SceneView', () => {
     await scene.ready();
     const before = await scene.nodeCount();
     await scene.clickNode('scene:root/a');
-    expect(await scene.selectedNodes()).toEqual(['scene:root/a']);
+    expect(await scene.selectedNodes()).toEqual([]);
     await expect(page.locator('[data-testid="scene-view"] svg rect[style*="cursor"]')).toHaveCount(0);
     const hovered = await scene.box(scene.node('scene:root/a'));
     await page.mouse.move(hovered.x + hovered.width / 2, hovered.y + hovered.height / 2);
     await expect(page.locator('[data-testid="scene-view"] circle.cursor-crosshair')).toHaveCount(0);
     await page.keyboard.press('Delete');
     expect(await scene.nodeCount()).toBe(before);
-    // Only the select and pan tools remain, and nothing on the toolbar can change the scene.
+    // Only the select and pan tools remain, and the actions bar, which only edits, is gone.
     await expect(page.locator('[data-testid="palette"] button')).toHaveCount(2);
-    await expect(page.getByTestId('toolbar-create')).toBeDisabled();
-    await expect(page.getByTestId('toolbar-delete')).toBeDisabled();
+    await expect(page.getByTestId('canvas-actions')).toHaveCount(0);
   });
 });

package/src/utils/builder.test.ts

@@ -4,8 +4,9 @@
 
 import { describe, test } from 'vitest';
 
-import { isClassNode, isEllipseNode, isPortalNode, isRectNode } from '../model/types.ts';
+import { isEllipseNode, isFrameNode, isNoteNode, isRectNode } from '../model/types.ts';
 import { SceneBuilder } from './builder.ts';
+import { DEFAULT_LAYER } from './layers.ts';
 
 const box = (x: number, y: number) => ({ x, y, width: 200, height: 100 });
 
@@ -14,10 +15,7 @@ describe('SceneBuilder', () => {
     const { root, scenes } = SceneBuilder.scene('s', [
       SceneBuilder.rect('a', box(0, 0)).properties({ label: 'A' }),
       SceneBuilder.ellipse('b', box(400, 0)).properties({ label: 'B' }),
-      SceneBuilder.class('c', { x: 0, y: 300, width: 200, height: 150 }).properties({
-        name: 'C',
-        attributes: ['id: string'],
-      }),
+      SceneBuilder.note('c', { x: 0, y: 300, width: 200, height: 150 }).properties({ style: { hue: 'teal' } }),
       SceneBuilder.link('line', 'a#e2', 'b#w2'),
       SceneBuilder.link('spline', 'b', 'c').properties({ points: [{ x: 300, y: 250 }] }),
       SceneBuilder.link('line', '@10,20', 'a')
@@ -33,9 +31,9 @@ describe('SceneBuilder', () => {
     expect(Object.keys(scene.nodes)).toEqual(['a', 'b', 'c']);
     expect(scene.nodes.a.center).toEqual({ x: 100, y: 50 });
     expect(isEllipseNode(scene.nodes.b) && scene.nodes.b.size).toEqual({ width: 200, height: 100 });
-    expect(isClassNode(scene.nodes.c) && scene.nodes.c.attributes).toEqual(['id: string']);
-    // A class keeps its type's default methods where the fixture does not set them.
-    expect(isClassNode(scene.nodes.c) && scene.nodes.c.methods).toEqual(['save(): void']);
+    expect(scene.nodes.c.style).toEqual({ hue: 'teal' });
+    // A note keeps its type's default text where the fixture does not set it.
+    expect(isNoteNode(scene.nodes.c) && scene.nodes.c.text).toEqual('Note');
     expect(scene.links['a-b'].source).toEqual({ node: 'a', port: 'e2' });
     expect(scene.links['a-b'].target).toEqual({ node: 'b', port: 'w2' });
     expect(scene.links['b-c'].type === 'spline' && scene.links['b-c'].points).toEqual([{ x: 300, y: 250 }]);
@@ -70,7 +68,7 @@ describe('SceneBuilder', () => {
     expect(root).toBe('root');
     expect(scenes.map((scene) => scene.id)).toEqual(['root', 'f']);
     const portal = scenes[0].nodes.f;
-    expect(isPortalNode(portal) && [portal.scene, portal.label, portal.center]).toEqual([
+    expect(isFrameNode(portal) && [portal.scene, portal.label, portal.center]).toEqual([
       'f',
       'Inner',
       { x: 500, y: 50 },
@@ -80,6 +78,45 @@ describe('SceneBuilder', () => {
     expect(() => SceneBuilder.scene('root', [SceneBuilder.scene('f')]).build()).toThrow(/needs a frame/);
   });
 
+  test('every scene has the default layer, and every element is on it', ({ expect }) => {
+    const { scenes } = SceneBuilder.scene('root', [
+      SceneBuilder.rect('a', box(0, 0)),
+      SceneBuilder.rect('b', box(400, 0)).properties({ layer: 'top' }),
+      SceneBuilder.link('line', 'a', 'b').id('ab'),
+      SceneBuilder.scene('f', [SceneBuilder.rect('f1', box(0, 0))]).at(box(0, 200)),
+    ]).build();
+    for (const scene of scenes) {
+      expect(scene.layers).toEqual({ [DEFAULT_LAYER.id]: DEFAULT_LAYER });
+    }
+    expect([scenes[0].nodes.a.layer, scenes[0].nodes.f.layer, scenes[0].links.ab.layer]).toEqual([
+      DEFAULT_LAYER.id,
+      DEFAULT_LAYER.id,
+      DEFAULT_LAYER.id,
+    ]);
+    // A layer the fixture names is kept.
+    expect(scenes[0].nodes.b.layer).toBe('top');
+    expect(scenes[1].nodes.f1.layer).toBe(DEFAULT_LAYER.id);
+  });
+
+  test('two elements with one id fail the build', ({ expect }) => {
+    const rect = SceneBuilder.rect('a', box(0, 0));
+    expect(() => SceneBuilder.scene('s', [rect, rect]).build()).toThrow(/Duplicate id a in scene s/);
+    const link = SceneBuilder.link('line', 'a', 'a').id('l');
+    expect(() => SceneBuilder.scene('s', [rect, link, link]).build()).toThrow(/Duplicate id l/);
+    // An explicit id that repeats one already generated clashes too.
+    const generated = SceneBuilder.link('line', 'a', 'a');
+    expect(() => SceneBuilder.scene('s', [rect, generated, generated.id('a-a')]).build()).toThrow(/Duplicate id a-a/);
+  });
+
+  test('an id an object inherits is not taken, and any id is kept', ({ expect }) => {
+    const rect = SceneBuilder.rect('constructor', box(0, 0));
+    const proto = SceneBuilder.rect('__proto__', box(0, 0));
+    const link = SceneBuilder.link('line', 'constructor', '__proto__').id('toString');
+    const [scene] = SceneBuilder.scene('s', [rect, proto, link]).build().scenes;
+    expect(Object.keys(scene.nodes)).toEqual(['constructor', '__proto__']);
+    expect(Object.keys(scene.links)).toEqual(['toString']);
+  });
+
   test('a node its type does not describe fails the build', ({ expect }) => {
     const host = SceneBuilder.node('rect', 'a', box(0, 0)).properties({ portsPerSide: 2 });
     expect(() => SceneBuilder.scene('s', [host]).build()).not.toThrow();

package/src/utils/builder.ts

@@ -17,16 +17,17 @@ import {
   type BuiltinNode,
   type BuiltinNodeType,
   type Endpoint,
+  type FrameNode,
   type Link,
   type LinkType,
   type Node,
   type NodeBase,
   type NodeStyle,
   type Point,
-  type PortalNode,
   type Scene,
   type SceneId,
 } from '../model/types.ts';
+import { DEFAULT_LAYER } from './layers.ts';
 import { initialKeys } from './order.ts';
 import { createNode } from './shapes.ts';
 
@@ -110,7 +111,7 @@ export class SceneElement {
     readonly elements: readonly BuilderElement[],
     readonly frame?: Box,
     readonly sceneName?: string,
-    readonly portal: NodeProperties<PortalNode> = {},
+    readonly portal: NodeProperties<FrameNode> = {},
   ) {}
 
   /** The scene's name (breadcrumbs, previews). */
@@ -124,7 +125,7 @@ export class SceneElement {
   }
 
   /** The scene shape's own properties (label, contents, style). */
-  properties(values: NodeProperties<PortalNode>): SceneElement {
+  properties(values: NodeProperties<FrameNode>): SceneElement {
     return new SceneElement(this.id, this.elements, this.frame, this.sceneName, {
       ...this.portal,
       ...values,
@@ -143,42 +144,59 @@ export class SceneElement {
 export type SceneTree = { root: SceneId; scenes: Scene[] };
 
 const buildScene = (element: SceneElement, registry: NodeRegistry, scenes: Scene[]): void => {
-  const nodes: Record<string, Node> = {};
-  const links: Record<string, Link> = {};
+  // Maps, so any id (`constructor`, `__proto__`) is an ordinary key; `fromEntries` keeps them own properties.
+  const nodes = new Map<string, Node>();
+  const links = new Map<string, Link>();
   const keys = initialKeys(element.elements.length);
-  const index = scenes.push({ id: element.id, name: element.sceneName, nodes, links }) - 1;
+  // Every element names its layer, so a fixture reads as a scene the editor wrote.
+  const index =
+    scenes.push({
+      id: element.id,
+      name: element.sceneName,
+      nodes: {},
+      links: {},
+      layers: { [DEFAULT_LAYER.id]: DEFAULT_LAYER },
+    }) - 1;
   element.elements.forEach((child, order) => {
     const z = keys[order];
     switch (child.kind) {
       case 'node': {
-        const node = { ...child.node, z };
+        // A host's type starts from its own `create`, as a built-in starts from `createNode`, so a
+        // fixture sets only what it means and the type supplies the rest of its content.
+        const def = isBuiltinType(child.node.type) ? undefined : registry[child.node.type];
+        const fresh = def?.create({ id: child.node.id, z, center: child.node.center, size: child.node.size });
+        const node = { layer: DEFAULT_LAYER.id, ...fresh, ...child.node, z };
         check(registry, node);
-        nodes[node.id] = node;
+        claim(nodes, node.id, element.id);
+        nodes.set(node.id, node);
         break;
       }
       case 'link': {
         const id = child.linkId ?? uniqueId(links, linkId(child.link.source, child.link.target));
-        links[id] = { ...child.link, id, z };
+        claim(links, id, element.id);
+        links.set(id, { layer: DEFAULT_LAYER.id, ...child.link, id, z });
         break;
       }
       case 'scene': {
         if (!child.frame) {
           throw new Error(`Nested scene ${child.id} needs a frame: call at(box).`);
         }
-        const node: PortalNode = {
-          ...createNode({ type: 'scene', id: child.id, z, center: center(child.frame), size: sizeOf(child.frame) }),
+        const node: FrameNode = {
+          ...createNode({ type: 'frame', id: child.id, z, center: center(child.frame), size: sizeOf(child.frame) }),
+          layer: DEFAULT_LAYER.id,
           ...child.portal,
-          type: 'scene',
+          type: 'frame',
           scene: child.id,
         };
         check(registry, node);
-        nodes[node.id] = node;
+        claim(nodes, node.id, element.id);
+        nodes.set(node.id, node);
         buildScene(child, registry, scenes);
         break;
       }
     }
   });
-  scenes[index] = { ...scenes[index], nodes, links };
+  scenes[index] = { ...scenes[index], nodes: Object.fromEntries(nodes), links: Object.fromEntries(links) };
 };
 
 /** A node its type does not describe (a wrong value, or a property the type does not have) fails the build. */
@@ -193,14 +211,21 @@ const check = (registry: NodeRegistry, node: Node): void => {
   }
 };
 
+/** Two elements given one id would leave only the second, so the fixture fails instead. */
+const claim = (taken: ReadonlyMap<string, unknown>, id: string, sceneId: SceneId): void => {
+  if (taken.has(id)) {
+    throw new Error(`Duplicate id ${id} in scene ${sceneId}.`);
+  }
+};
+
 const linkId = (source: Endpoint, target: Endpoint): string => {
   const name = (end: Endpoint) => ('node' in end ? end.node : `${end.point.x},${end.point.y}`);
   return `${name(source)}-${name(target)}`;
 };
 
-const uniqueId = (taken: Record<string, unknown>, id: string): string => {
+const uniqueId = (taken: ReadonlyMap<string, unknown>, id: string): string => {
   let candidate = id;
-  for (let suffix = 2; candidate in taken; ++suffix) {
+  for (let suffix = 2; taken.has(candidate); ++suffix) {
     candidate = `${id}-${suffix}`;
   }
   return candidate;
@@ -221,7 +246,7 @@ function node(type: string, id: string, box: Box): NodeElement<NodeBase> {
   return new NodeElement<NodeBase>(base);
 }
 
-const BUILTIN_TYPES: readonly string[] = ['rect', 'ellipse', 'class', 'note', 'scene'] satisfies BuiltinNodeType[];
+const BUILTIN_TYPES: readonly string[] = ['rect', 'ellipse', 'note', 'frame'] satisfies BuiltinNodeType[];
 const isBuiltinType = (type: string): type is BuiltinNodeType => BUILTIN_TYPES.includes(type);
 
 type Ends = Pick<Link, 'source' | 'target'>;
@@ -244,7 +269,6 @@ export const SceneBuilder = {
   node,
   rect: (id: string, box: Box) => node('rect', id, box),
   ellipse: (id: string, box: Box) => node('ellipse', id, box),
-  class: (id: string, box: Box) => node('class', id, box),
   note: (id: string, box: Box) => node('note', id, box),
   link,
 };

package/src/utils/camera.test.ts

@@ -4,7 +4,7 @@
 
 import { type ExpectStatic, describe, test } from 'vitest';
 
-import { type Bounds, type Camera, type PortalNode, type Scene } from '../model/types.ts';
+import { type Bounds, type Camera, type FrameNode } from '../model/types.ts';
 import {
   MAX_ZOOM,
   MIN_ZOOM,
@@ -13,17 +13,16 @@ import {
   exitPortal,
   fitBounds,
   portalFrame,
-  portalScale,
   sceneToScreen,
   screenToScene,
   zoomAt,
 } from './camera.ts';
-import { contentBounds, sceneBounds } from './hit.ts';
+import { nodeBounds } from './shapes.ts';
 
 const viewport = { width: 800, height: 600 };
 
-const portal: PortalNode = {
-  type: 'scene',
+const portal: FrameNode = {
+  type: 'frame',
   id: 'p',
   z: 'V',
   center: { x: 640, y: 620 },
@@ -101,58 +100,30 @@ describe('camera', () => {
     expect(coverage(camera, { x: -100, y: -100, width: 10, height: 10 }, viewport)).toBe(0);
   });
 
-  test('portalFrame is a power-of-four multiple of the portal on the grid, containing the child bounds', ({
+  test("portalFrame centres the child in the smallest region of the portal's proportions that holds it", ({
     expect,
   }) => {
     const frame = portalFrame(portal, child);
-    // 1600 × 1000 needs four 480 × 300 portals across; the frame is 1920 × 1200.
-    expect([frame.width, frame.height]).toEqual([1920, 1200]);
-    // On the major grid scaled by the factor, so the child's major lines land on the parent's major lines
-    // (a frame on the plain major grid only matches their spacing, up to three minor cells out of phase).
-    expect(Math.abs(frame.x % 256)).toBe(0);
-    expect(Math.abs(frame.y % 256)).toBe(0);
-    expect(frame.x).toBeLessThanOrEqual(child.x);
-    expect(frame.y).toBeLessThanOrEqual(child.y);
-    expect(frame.x + frame.width).toBeGreaterThanOrEqual(child.x + child.width);
-    expect(frame.y + frame.height).toBeGreaterThanOrEqual(child.y + child.height);
-    // As near the child's centre as containing it allows.
-    expect(Math.abs(frame.x + frame.width / 2 - (child.x + child.width / 2))).toBeLessThanOrEqual(256);
-    expect(Math.abs(frame.y + frame.height / 2 - (child.y + child.height / 2))).toBeLessThanOrEqual(256);
+    const { width, height } = nodeBounds(portal);
+    // The portal's proportions, just large enough for the child on its tighter axis.
+    expect(frame.width / frame.height).toBeCloseTo(width / height);
+    expect(Math.max(child.width / frame.width, child.height / frame.height)).toBeCloseTo(1);
+    // Centred on the child.
+    expect(frame.x + frame.width / 2).toBeCloseTo(child.x + child.width / 2);
+    expect(frame.y + frame.height / 2).toBeCloseTo(child.y + child.height / 2);
     // A frame is its own frame, so drilling in and out is stable.
     expect(portalFrame(portal, frame)).toEqual(frame);
-    // A child smaller than the portal still gets four portals across: the parent's minor grid is the
-    // child's major one, never the same level.
-    const small = portalFrame(portal, { x: 64, y: 64, width: 128, height: 128 });
-    expect([small.width, small.height]).toEqual([1920, 1200]);
-    expect(small.x).toBeLessThanOrEqual(64);
-    expect(small.x + small.width).toBeGreaterThanOrEqual(192);
-    // A child past four portals across jumps to sixteen, never to an in-between factor whose grid
-    // would miss the parent's lines.
-    const large = portalFrame(portal, { x: 0, y: 0, width: 2400, height: 600 });
-    expect([large.width, large.height]).toEqual([7680, 4800]);
   });
 
-  test('a small child in a small portal is framed by its content, not by the editing floor', ({ expect }) => {
-    // A portal small enough that the default extent does not fit four of it across: framed by the floor
-    // the child would need sixteen and so draw a quarter of the size, for content it does not have.
-    const tile: PortalNode = {
-      type: 'scene',
-      id: 'p',
-      z: 'A',
-      center: { x: 0, y: 0 },
-      size: { width: 256, height: 160 },
-      scene: 'c',
-    };
-    const scene: Scene = {
-      id: 'c',
-      nodes: { a: { type: 'rect', id: 'a', z: 'A', center: { x: 0, y: 0 }, size: { width: 128, height: 128 } } },
-      links: {},
-    };
-    const framed = portalFrame(tile, contentBounds(scene));
-    const floored = portalFrame(tile, sceneBounds(scene));
-    expect([framed.width, framed.height]).toEqual([1024, 640]);
-    expect([floored.width, floored.height]).toEqual([4096, 2560]);
-    // The child therefore draws four times the size in the same tile.
-    expect(portalScale(tile, framed) / portalScale(tile, floored)).toBe(4);
+  test("a small or empty child is never magnified: the frame is at least the portal's own box", ({ expect }) => {
+    const { width, height } = nodeBounds(portal);
+    const small = portalFrame(portal, { x: 64, y: 64, width: 128, height: 128 });
+    expect([small.width, small.height]).toEqual([width, height]);
+    expect(small.x + small.width / 2).toBe(128);
+    const empty = portalFrame(portal, undefined);
+    expect(empty).toEqual({ x: -width / 2, y: -height / 2, width, height });
+    // So a shape inside keeps its size through the drill-in: entering maps the zoom one to one.
+    const camera = { x: 0, y: 0, zoom: 0.79 };
+    expect(enterPortal(camera, portal, empty).zoom).toBeCloseTo(0.79);
   });
 });

package/src/utils/camera.ts

@@ -9,20 +9,15 @@
 
 import { interpolateZoom } from 'd3';
 
-import {
-  type Bounds,
-  type Camera,
-  MAJOR_GRID,
-  MAJOR_GRID_RATIO,
-  type Node,
-  type Point,
-  type Size,
-} from '../model/types.ts';
+import { type Bounds, type Camera, type Node, type Point, type Size } from '../model/types.ts';
 import { nodeBounds } from './shapes.ts';
 
 export const MIN_ZOOM = 1 / 32;
 export const MAX_ZOOM = 32;
 
+/** True size: one scene px is one screen px, at every level. Fit never zooms past it. */
+export const NOMINAL_ZOOM = 1;
+
 export const clampZoom = (zoom: number) => Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom));
 
 export const sceneToScreen = (camera: Camera, point: Point): Point => ({
@@ -82,35 +77,25 @@ export const portalScale = (portal: Node, region: Bounds) => {
 };
 
 /**
- * The frame a portal gives its child: the child-space region that maps exactly onto the portal. It is
- * the portal's box scaled by the smallest power of the grid ratio, at least one, that contains the child's
- * derived bounds, placed on the major grid scaled by that factor as near their centre as containing them
- * allows. A power of the ratio maps every child grid level onto a parent level (the child's major grid is
- * the parent's minor one, one level down), and placing the frame on the scaled grid puts the child's lines
- * on the parent's, not merely at their spacing, so the grids stay aligned through a drill-in. Drilling in
- * shows this frame; a portal draws the child centred in it.
+ * The frame a portal gives its child: the child-space region, of the portal's proportions, that maps onto
+ * the portal's box. It is the child's content (`child`) centred in the smallest such region that holds it,
+ * and never smaller than the box itself, so the preview shrinks a large scene to fit but never magnifies a
+ * small one. Every scene keeps its own scale: the frame only says where the child sits under the portal,
+ * and entering it maps the camera through the frame, so a shape is the same size at the same zoom on any
+ * level. An empty child is the box itself, centred on its origin.
  */
-export const portalFrame = (portal: Node, child: Bounds, unit = MAJOR_GRID, ratio = MAJOR_GRID_RATIO): Bounds => {
+export const portalFrame = (portal: Node, child: Bounds | undefined): Bounds => {
   const { width, height } = nodeBounds(portal);
-  let factor = ratio;
-  while (factor * width < child.width || factor * height < child.height) {
-    factor *= ratio;
-  }
+  const content = child ?? { x: 0, y: 0, width: 0, height: 0 };
+  const factor = Math.max(1, content.width / width, content.height / height);
   const frame = { width: width * factor, height: height * factor };
   return {
-    x: place(child.x, child.width, frame.width, unit * factor),
-    y: place(child.y, child.height, frame.height, unit * factor),
+    x: content.x + (content.width - frame.width) / 2,
+    y: content.y + (content.height - frame.height) / 2,
     ...frame,
   };
 };
 
-/** The grid-aligned start of a span of `length` centred on `[start, start + inner]` as far as containing it allows. */
-const place = (start: number, inner: number, length: number, unit: number): number => {
-  const centred = Math.round((start + inner / 2 - length / 2) / unit) * unit;
-  // Rounding a small negative yields -0, which `toEqual` and `Object.is` tell apart from 0.
-  return Math.max(Math.min(centred, start), start + inner - length) + 0;
-};
-
 /** Child-scene CSS transform inside a portal node whose own origin is the node's top-left. */
 export const portalTransform = (portal: Node, frame: Bounds) => {
   const scale = portalScale(portal, frame);
@@ -142,6 +127,24 @@ export const exitPortal = (camera: Camera, portal: Node, child: Bounds): Camera
   };
 };
 
+/** A portal filling this share of the viewport (on its tighter axis) leaves the rest of its layer fully shown… */
+const FADE_START = 0.25;
+/** …and this share hides it: zooming into a portal fades out what is around it, and zooming out fades it back. */
+const FADE_END = 0.75;
+
+/**
+ * The opacity of a layer around a portal, from how much of the viewport the portal fills on its tighter axis:
+ * 1 while it is small, falling to 0 as it grows towards filling the view. A wheel zoom, a drill-in and a
+ * drill-out all move the camera, so all three fade alike.
+ */
+export const layerOpacity = (camera: Camera, bounds: Bounds, viewport: Size): number => {
+  if (viewport.width === 0 || viewport.height === 0) {
+    return 1;
+  }
+  const fill = Math.min((bounds.width * camera.zoom) / viewport.width, (bounds.height * camera.zoom) / viewport.height);
+  return Math.min(1, Math.max(0, (FADE_END - fill) / (FADE_END - FADE_START)));
+};
+
 /** Fraction of the viewport covered by the bounds' screen rectangle. */
 export const coverage = (camera: Camera, bounds: Bounds, viewport: Size) => {
   if (viewport.width === 0 || viewport.height === 0) {
@@ -168,16 +171,20 @@ const fromView = ([cx, cy, width]: [number, number, number], viewport: Size): Ca
 export const MIN_ANIMATION_MS = 250;
 export const MAX_ANIMATION_MS = 800;
 
-/** Animate between cameras; returns a cancel function. */
+/** How long a drill in or out takes, either way, so entering and leaving a scene feel the same. */
+export const DRILL_ANIMATION_MS = 1000;
+
+/** Animate between cameras, over `fixedDuration` ms or a time fitted to the distance; returns a cancel function. */
 export const animateCamera = (
   from: Camera,
   to: Camera,
   viewport: Size,
   apply: (camera: Camera) => void,
   done?: () => void,
+  fixedDuration?: number,
 ): (() => void) => {
   const interpolate = interpolateZoom(toView(from, viewport), toView(to, viewport));
-  const duration = Math.min(MAX_ANIMATION_MS, Math.max(MIN_ANIMATION_MS, interpolate.duration));
+  const duration = fixedDuration ?? Math.min(MAX_ANIMATION_MS, Math.max(MIN_ANIMATION_MS, interpolate.duration));
   const start = performance.now();
   let frame = 0;
   const tick = (now: number) => {