@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/src/components/SceneView/SceneViewContext.ts

@@ -7,7 +7,13 @@ import { type KeyboardEvent, type MouseEvent, type RefObject } from 'react';
 import { createContext } from '@dxos/react-hooks';
 
 import { type useRegistry } from '../../hooks/index.ts';
-import { type ControlPointRef, type Drag, type EditingPart, type SceneViewAtoms } from '../../model/atoms.ts';
+import {
+  type ControlPointRef,
+  type Drag,
+  type EditingPart,
+  type PanelMode,
+  type SceneViewAtoms,
+} from '../../model/atoms.ts';
 import { type Projection } from '../../model/projection.ts';
 import { type LinkRegistry, type NodeRegistry } from '../../model/registry.ts';
 import { type SceneStore } from '../../model/store.ts';
@@ -16,6 +22,8 @@ import {
   type Camera,
   type Capabilities,
   type ElementId,
+  type LinkId,
+  type NodeId,
   type Scene,
   type SceneId,
   type Tool,
@@ -39,6 +47,8 @@ export type SceneViewContextValue = {
   store: SceneStore;
   projection: Projection;
   capabilities: Capabilities;
+  /** The scene is only looked at: the parts that edit it (selection frame, ports, actions, properties) hide. */
+  readonly: boolean;
   nodeRegistry: NodeRegistry;
   linkRegistry: LinkRegistry;
 
@@ -49,16 +59,19 @@ export type SceneViewContextValue = {
   blocked: boolean;
   /** The current scene's frame. */
   bounds: Bounds;
+  /** The scene's frame and the visible viewport together, for the lattice cells. */
+  latticeBounds: Bounds;
   path: SceneId[];
   camera: Camera;
   /** The zoom against this level's own 1:1 rather than the root's; display only. */
-  nominalZoom: number;
   /** The centre of the view in scene coordinates. */
   pointer: { x: number; y: number };
   /** Whether the viewport has been measured; the scene stays hidden until it has. */
   measured: boolean;
   /** One screen pixel in scene units, for chrome that should not grow with the camera. */
   frameUnit: number;
+  /** The portal filling most of the view and the opacity of the rest of the layer around it (`layerOpacity`). */
+  focus: { id: ElementId; opacity: number } | undefined;
   /** Minor grid spacing in scene px. */
   grid: number;
   snapEnabled: boolean;
@@ -70,14 +83,22 @@ export type SceneViewContextValue = {
   hover: ElementId | undefined;
   selectedPoint: ControlPointRef | undefined;
   editing: EditingPart | undefined;
+  /** The node whose embedded content takes input. */
+  active: NodeId | undefined;
   clipboard: Clipboard | undefined;
   drag: Drag | undefined;
   tool: Tool;
   debug: boolean;
+  /** Where the properties and layers panels sit. */
+  panels: PanelMode;
 
   /** The bounds a create gesture would land, drawn whether or not the node itself previews. */
   createFrame: Bounds | undefined;
+  /** Where the nodes of a move in flight will land, while they follow the pointer. */
+  landing: readonly Bounds[] | undefined;
   handlers: ElementHandlers;
+  /** The link under the pointer. */
+  linkHover: LinkId | undefined;
   select: (ids: Iterable<ElementId>) => void;
   toolbarActions: ToolbarActions;
 } & Pick<SceneCamera, 'navigating' | 'opening'> &

package/src/components/SceneView/Scored.stories.tsx

@@ -21,7 +21,7 @@ import { type SceneStore, createMemoryStore } from '../../model/store.ts';
 import { type Scene, type SceneId } from '../../model/types.ts';
 import { SceneBuilder } from '../../utils/builder.ts';
 import { diagnosticElements, toDiagramObjects } from '../../utils/diagram.ts';
-import { createClassSceneTree } from '../../utils/testing.ts';
+import { createModelSceneTree } from '../../utils/testing.ts';
 import { SceneView } from './SceneView.tsx';
 
 /**
@@ -95,7 +95,7 @@ const fromMermaid = async (source: string): Promise<Seed> => {
     ...graph.edges.map(({ from, to }, index) =>
       SceneBuilder.link('smart', nodeId(from), nodeId(to))
         .id(nodeId(`${from}-${to}-${index}`))
-        .properties({ directed: true }),
+        .properties({ ends: { end: 'arrow' } }),
     ),
   ]).build();
   return { scenes, root: ROOT, engine: result.chosen.evaluation };
@@ -319,9 +319,9 @@ const Editor = ({ store, root, engine }: EditorProps) => {
 };
 
 type StoryArgs = {
-  /** Mermaid flowchart laid out by the engine; ignored when `fixture` is `classes`. */
+  /** Mermaid flowchart laid out by the engine; ignored when `fixture` is `model`. */
   source?: string;
-  fixture?: 'mermaid' | 'classes';
+  fixture?: 'mermaid' | 'model';
 };
 
 const DefaultStory = ({ source = BASIC, fixture = 'mermaid' }: StoryArgs) => {
@@ -330,8 +330,8 @@ const DefaultStory = ({ source = BASIC, fixture = 'mermaid' }: StoryArgs) => {
   const [failure, setFailure] = useState<string>();
   useEffect(() => {
     const key = `${fixture}:${source}`;
-    if (fixture === 'classes') {
-      setSeed({ ...createClassSceneTree(), key });
+    if (fixture === 'model') {
+      setSeed({ ...createModelSceneTree(), key });
       setFailure(undefined);
       return;
     }
@@ -364,12 +364,12 @@ const DefaultStory = ({ source = BASIC, fixture = 'mermaid' }: StoryArgs) => {
 };
 
 const meta: Meta<StoryArgs> = {
-  title: 'ui/react-ui-canvas/scene/Scored',
+  title: 'ui/react-ui-canvas/Scored',
   render: DefaultStory,
   decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen' })],
   argTypes: {
     source: { control: 'text', description: 'Mermaid flowchart laid out by the engine' },
-    fixture: { control: 'radio', options: ['mermaid', 'classes'] },
+    fixture: { control: 'radio', options: ['mermaid', 'model'] },
   },
 };
 
@@ -387,7 +387,7 @@ export const Platform: Story = {
   args: { source: PLATFORM.trim(), fixture: 'mermaid' },
 };
 
-/** The scene engine's own class fixture, graded as drawn. */
-export const Classes: Story = {
-  args: { fixture: 'classes' },
+/** The scene engine's own model fixture, graded as drawn. */
+export const Model: Story = {
+  args: { fixture: 'model' },
 };

package/src/components/SceneView/usePointerMachine.ts

@@ -12,7 +12,7 @@ import {
   useState,
 } from 'react';
 
-import { type useRegistry } from '../../hooks/index.ts';
+import { SCENE_OVERLAY_ATTRIBUTE, type useRegistry } from '../../hooks/index.ts';
 import { type ControlPointRef, type Drag, type Handle, type SceneViewAtoms } from '../../model/atoms.ts';
 import { nodeDef } from '../../model/node-def.ts';
 import { type Projection } from '../../model/projection.ts';
@@ -33,17 +33,18 @@ import {
   type SplineLink,
   type Tool,
   endpointNode,
+  isFrameNode,
   isPointEndpoint,
-  isPortalNode,
 } from '../../model/types.ts';
 import { boundsCenter, panBy, screenToScene } from '../../utils/camera.ts';
 import { duplicateSelection } from '../../utils/clipboard.ts';
 import { boundsFromPoints, hitTest, nodesIntersecting } from '../../utils/hit.ts';
+import { DEFAULT_LAYER, activeLayer } from '../../utils/layers.ts';
 import { topZ } from '../../utils/order.ts';
 import { nodePorts, portAccepts, portPoint } from '../../utils/ports.ts';
 import { resizeBounds } from '../../utils/resize.ts';
 import { insertIndex, linkGeometry, sideToward } from '../../utils/route.ts';
-import { DEFAULT_SIZES, cloneShape, createLink, createNode, nodeBounds } from '../../utils/shapes.ts';
+import { NOMINAL_SIZES, cloneShape, createLink, createNode, nodeBounds, nominalSize } from '../../utils/shapes.ts';
 import { type LinkEnd, handlePoint } from '../ControlFrame/ControlFrame.tsx';
 import { type SceneCamera } from './useSceneCamera.ts';
 import { type SceneSnap } from './useSceneSnap.ts';
@@ -91,6 +92,8 @@ export type UsePointerMachineOptions = {
   /** Set once the user takes the camera over, which stops the view re-fitting itself. */
   interactedRef: MutableRefObject<boolean>;
   select: (ids: Iterable<ElementId>) => void;
+  /** Scene px of one nominal unit (the model's major grid cell), which a new node's default size is counted in. */
+  cell: number;
 } & Pick<SceneCamera, 'setCamera' | 'cancelAnimation' | 'isNavigating'> &
   Pick<SceneSnap, 'minor' | 'major' | 'snap' | 'snapMinor'>;
 
@@ -153,6 +156,7 @@ export const usePointerMachine = ({
   setCamera,
   cancelAnimation,
   isNavigating,
+  cell,
   minor,
   major,
   snap,
@@ -248,6 +252,17 @@ export const usePointerMachine = ({
     [registry, atoms.selection, select],
   );
 
+  /** Makes a node's embedded content live (`SceneViewAtoms.active`), when it has any. */
+  const activate = useCallback(
+    (id: NodeId) => {
+      // Escaped: a host's node id may hold characters a selector would misread.
+      if (rootRef.current?.querySelector(`[data-node-id="${CSS.escape(id)}"] [${SCENE_OVERLAY_ATTRIBUTE}]`)) {
+        registry.set(atoms.active, id);
+      }
+    },
+    [rootRef, registry, atoms.active],
+  );
+
   const onNodePointerDown = useCallback(
     (node: Node, event: PointerEvent) => {
       const currentTool = registry.get(atoms.tool);
@@ -265,6 +280,12 @@ export const usePointerMachine = ({
         return;
       }
       const next = clickSelect(node.id, event);
+      // A press on the content of the active node (its own toolbar or editor) starts no move: the drag's pointer
+      // capture would take the click from that content's controls. Inactive, the content is inert and the node moves.
+      const embedded = event.target instanceof Element && event.target.closest(`[${SCENE_OVERLAY_ATTRIBUTE}]`);
+      if (embedded && registry.get(atoms.active) === node.id) {
+        return;
+      }
       if (capabilities.move && !node.locked) {
         const { x, y } = nodeBounds(node);
         const ids = [...next].filter((id) => scene.nodes[id] !== undefined);
@@ -272,9 +293,23 @@ export const usePointerMachine = ({
           { kind: 'move', ids, origin: toScene(event), anchor: { x, y }, delta: { x: 0, y: 0 }, copy: event.metaKey },
           event,
         );
+      } else if (next.size === 1) {
+        // A node that cannot move has no drag to end in a click, so the press itself activates it.
+        activate(node.id);
       }
     },
-    [registry, atoms.tool, clickSelect, capabilities.move, capabilities.link, scene.nodes, toScene, startDrag],
+    [
+      registry,
+      atoms.tool,
+      atoms.active,
+      activate,
+      clickSelect,
+      capabilities.move,
+      capabilities.link,
+      scene.nodes,
+      toScene,
+      startDrag,
+    ],
   );
 
   const onLinkPointerDown = useCallback(
@@ -529,6 +564,7 @@ export const usePointerMachine = ({
           const raw = { x: point.x - current.origin.x, y: point.y - current.origin.y };
           setDrag({
             ...current,
+            raw,
             delta: {
               x: snapMinor(current.anchor.x + raw.x) - current.anchor.x,
               y: snapMinor(current.anchor.y + raw.y) - current.anchor.y,
@@ -652,7 +688,7 @@ export const usePointerMachine = ({
       if (!drag.dropped && (drawn.width === 0 || drawn.height === 0)) {
         return undefined;
       }
-      const size = drag.dropped ? { ...def.defaultSize } : { ...drawn };
+      const size = drag.dropped ? nominalSize(def.defaultSize, cell) : { ...drawn };
       const center = drag.dropped
         ? { x: drag.from.x + size.width / 2, y: drag.from.y + size.height / 2 }
         : { x: drawn.x + drawn.width / 2, y: drawn.y + drawn.height / 2 };
@@ -663,21 +699,27 @@ export const usePointerMachine = ({
       pendingRef.current = { type: drag.type, node };
       return node;
     },
-    [nodeRegistry, scene.nodes],
+    [nodeRegistry, scene.nodes, cell],
   );
 
   /** Adds a new node; a new portal opens onto a fresh scene of its own, whichever path created it. */
   const addNode = useCallback(
     (node: Node) => {
-      if (isPortalNode(node)) {
+      if (isFrameNode(node)) {
         registry.set(store.scenes, {
           ...registry.get(store.scenes),
-          [node.scene]: { id: node.scene, name: 'Untitled', nodes: {}, links: {} },
+          [node.scene]: {
+            id: node.scene,
+            name: 'Untitled',
+            nodes: {},
+            links: {},
+            layers: { [DEFAULT_LAYER.id]: DEFAULT_LAYER },
+          },
         });
       }
-      projection.apply({ kind: 'create', node });
+      projection.apply({ kind: 'create', node: { ...node, layer: activeLayer(scene, registry.get(atoms.layer)) } });
     },
-    [projection, registry, store],
+    [projection, registry, store, scene, atoms.layer],
   );
 
   /** The node the gesture made, committed: the next gesture starts from a fresh `create`. */
@@ -722,6 +764,10 @@ export const usePointerMachine = ({
         }
         case 'move': {
           if (current.delta.x === 0 && current.delta.y === 0) {
+            // A click (a press that never moved) on a node with embedded content makes that content live.
+            if (current.ids.length === 1) {
+              activate(current.ids[0]);
+            }
             break;
           }
           // ⌘-drag leaves the selection where it was and drops a copy, which becomes the selection.
@@ -750,27 +796,34 @@ export const usePointerMachine = ({
             break;
           }
           let target = current.target;
+          let created: Node | undefined;
           if (!target && isPointEndpoint(current.source)) {
             // A free-ended link that never reached a node ends free too.
             target = { point: current.to };
           } else if (!target && capabilities.create) {
             // Dropping a link drag on empty canvas creates a node there and links to it (canvas-editor
-            // behaviour): a copy of the shape it left, without its text, else a rectangle. Its top-left is
-            // what snaps, so the edges land on the grid.
+            // behaviour): a copy of the shape it left, without its text, else a rectangle. It is centred on
+            // the release point (not the settled end, already snapped to the coarse grid) with its top-left
+            // on the minor grid, as a palette drop lands.
+            const drop = raw.kind === 'link' ? raw.to : current.to;
             const source = scene.nodes[endpointNode(current.source) ?? ''];
             const def = source ? nodeRegistry[source.type] : undefined;
-            const size = source?.size ?? DEFAULT_SIZES.rect;
+            const size = source?.size ?? nominalSize(NOMINAL_SIZES.rect, cell);
             const props = {
               id: createId(source?.type ?? 'rect'),
               z: topZ(Object.values(scene.nodes)),
               center: {
-                x: snap(current.to.x - size.width / 2) + size.width / 2,
-                y: snap(current.to.y - size.height / 2) + size.height / 2,
+                x: snapMinor(drop.x - size.width / 2) + size.width / 2,
+                y: snapMinor(drop.y - size.height / 2) + size.height / 2,
               },
               size,
             };
-            const node = source && def ? cloneShape(source, def.create(props)) : createNode({ type: 'rect', ...props });
+            const node =
+              source && def
+                ? cloneShape(source, def.create(props), nodeDef(nodeRegistry, source)?.parts)
+                : createNode({ type: 'rect', ...props });
             addNode(node);
+            created = node;
             target = { node: node.id };
           }
           if (target) {
@@ -782,11 +835,15 @@ export const usePointerMachine = ({
               target,
               midpoint: { x: snap((current.from.x + current.to.x) / 2), y: snap((current.from.y + current.to.y) / 2) },
               // A link between ports that declare a direction is drawn with one.
-              directed: isDirected(scene, nodeRegistry, current.source, target),
+              ends: isDirected(scene, nodeRegistry, current.source, target) ? { end: 'arrow' } : undefined,
+            });
+            projection.apply({
+              kind: 'link',
+              link: { ...link, layer: activeLayer(scene, registry.get(atoms.layer)) },
             });
-            projection.apply({ kind: 'link', link });
-            // The new link is what the user just made, so it is what they act on next (style, delete).
-            select([link.id]);
+            // What the user just made is what they act on next (style, delete): the link, and the node
+            // the drop created with it.
+            select(created ? [link.id, created.id] : [link.id]);
           }
           break;
         }
@@ -832,6 +889,9 @@ export const usePointerMachine = ({
       commitCreated,
       addNode,
       minor,
+      cell,
+      snapMinor,
+      activate,
     ],
   );
 

package/src/components/SceneView/useSceneCamera.ts

@@ -15,8 +15,8 @@ const NAVIGATION_SETTLE_MS = 150;
 export type SceneCamera = {
   /** Write the camera, from a value or from its predecessor. */
   setCamera: (next: Camera | ((camera: Camera) => Camera)) => void;
-  /** Animate to `target`, calling `done` when the last frame lands. */
-  animateTo: (target: Camera, done?: () => void) => void;
+  /** Animate to `target`, calling `done` when the last frame lands; `duration` fixes its length in ms. */
+  animateTo: (target: Camera, done?: () => void, duration?: number) => void;
   /** Abandon an animation in flight, leaving the camera where it reached. */
   cancelAnimation: () => void;
   /** The camera is moving on its own, so the canvas ignores the pointer. */
@@ -88,14 +88,21 @@ export const useSceneCamera = (
   }, [setNavigation]);
 
   const animateTo = useCallback(
-    (target: Camera, done?: () => void) => {
+    (target: Camera, done?: () => void, duration?: number) => {
       cancelAnimation();
       setNavigation(true);
-      cancelRef.current = animateCamera(registry.get(atoms.camera), target, viewport, setCamera, () => {
-        cancelRef.current = undefined;
-        setNavigation(false);
-        done?.();
-      });
+      cancelRef.current = animateCamera(
+        registry.get(atoms.camera),
+        target,
+        viewport,
+        setCamera,
+        () => {
+          cancelRef.current = undefined;
+          setNavigation(false);
+          done?.();
+        },
+        duration,
+      );
     },
     [registry, atoms.camera, viewport, setCamera, cancelAnimation, setNavigation],
   );

package/src/components/SceneView/useSceneClipboard.ts

@@ -9,6 +9,7 @@ import { type SceneViewAtoms } from '../../model/atoms.ts';
 import { type Projection } from '../../model/projection.ts';
 import { type Capabilities, type ElementId, type Point, type Scene } from '../../model/types.ts';
 import { clipboardBounds, copySelection, pasteFragment } from '../../utils/clipboard.ts';
+import { activeLayer } from '../../utils/layers.ts';
 import { between, topZ } from '../../utils/order.ts';
 import { type SceneSnap } from './useSceneSnap.ts';
 
@@ -78,6 +79,7 @@ export const useSceneClipboard = ({
         createId,
         nodeZ: () => (nodeZ = between(nodeZ, undefined)),
         linkZ: () => (linkZ = between(linkZ, undefined)),
+        layer: activeLayer(scene, registry.get(atoms.layer)),
       });
       projection.apply(intent);
       registry.set(atoms.clipboard, { ...fragment, pasted: at ? fragment.pasted : fragment.pasted + 1 });
@@ -91,6 +93,8 @@ export const useSceneClipboard = ({
       snap,
       scene.nodes,
       scene.links,
+      scene,
+      atoms.layer,
       projection,
       select,
       createId,

package/src/components/SceneView/useSceneKeys.ts

@@ -11,7 +11,7 @@ import { nodeDef } from '../../model/node-def.ts';
 import { type Projection } from '../../model/projection.ts';
 import { type LinkRegistry, type NodeRegistry } from '../../model/registry.ts';
 import { type Bounds, type Capabilities, type ElementId, type Scene, type Size } from '../../model/types.ts';
-import { fitBounds, zoomAt } from '../../utils/camera.ts';
+import { NOMINAL_ZOOM, fitBounds, zoomAt } from '../../utils/camera.ts';
 import { unionBounds } from '../../utils/hit.ts';
 import { nodeBounds } from '../../utils/shapes.ts';
 import { toolForKey } from '../Palette/Palette.tsx';
@@ -119,18 +119,20 @@ export const useSceneKeys = ({
           break;
         }
         case 'fit':
-          animateTo(fitBounds(bounds, viewport, inset));
+          animateTo(fitBounds(bounds, viewport, inset, NOMINAL_ZOOM));
           event.preventDefault();
           break;
         case 'fitSelection': {
           const union = unionBounds(selectedNodes.map((id) => nodeBounds(scene.nodes[id])));
           if (union) {
-            animateTo(fitBounds(union, viewport, inset));
+            animateTo(fitBounds(union, viewport, inset, NOMINAL_ZOOM));
           }
           break;
         }
         case 'zoomReset':
-          animateTo(zoomAt(registry.get(atoms.camera), { x: viewport.width / 2, y: viewport.height / 2 }, 1));
+          animateTo(
+            zoomAt(registry.get(atoms.camera), { x: viewport.width / 2, y: viewport.height / 2 }, NOMINAL_ZOOM),
+          );
           break;
         case 'back':
           goHistory(-1);

package/src/components/SceneView/useSceneNavigation.ts

@@ -6,6 +6,8 @@ import { type MutableRefObject, useCallback, useEffect, useMemo, useRef } from '
 
 import { type useRegistry } from '../../hooks/index.ts';
 import { type Drag, type HistoryEntry, type SceneViewAtoms } from '../../model/atoms.ts';
+import { nodeDef } from '../../model/node-def.ts';
+import { type NodeRegistry } from '../../model/registry.ts';
 import { type SceneStore } from '../../model/store.ts';
 import {
   type Bounds,
@@ -15,13 +17,27 @@ import {
   type Scene,
   type SceneId,
   type Size,
-  isPortalNode,
+  isFrameNode,
 } from '../../model/types.ts';
-import { coverage, enterPortal, exitPortal, fitBounds, portalFrame, portalScale } from '../../utils/camera.ts';
-import { contentBounds, sceneBounds } from '../../utils/hit.ts';
+import {
+  DRILL_ANIMATION_MS,
+  NOMINAL_ZOOM,
+  coverage,
+  enterPortal,
+  exitPortal,
+  fitBounds,
+  portalFrame,
+} from '../../utils/camera.ts';
+import { contentBounds } from '../../utils/hit.ts';
 import { nodeBounds } from '../../utils/shapes.ts';
 import { type SceneCamera } from './useSceneCamera.ts';
 
+/** An empty root has nothing to frame: fitting it centres the origin at true size. */
+const EMPTY_FRAME: Bounds = { x: 0, y: 0, width: 0, height: 0 };
+
+/** The shapes of a scene, unpadded: what Fit frames, with its inset as the only margin. */
+const fitFrame = (scene: Scene): Bounds => contentBounds(scene, 0, 1) ?? EMPTY_FRAME;
+
 /** A portal covering this much of the viewport becomes the root; a root below this yields to its parent. */
 const AUTO_ENTER = 0.85;
 const AUTO_EXIT = 0.3;
@@ -30,6 +46,7 @@ const AUTO_DRILL_MS = 150;
 export type UseSceneNavigationOptions = {
   registry: ReturnType<typeof useRegistry>;
   atoms: SceneViewAtoms;
+  nodeRegistry: NodeRegistry;
   store: SceneStore;
   scenes: Record<SceneId, Scene>;
   scene: Scene;
@@ -48,13 +65,14 @@ export type SceneNavigation = {
   nameOf: (id: SceneId) => string;
   /** The portal in `parent` that shows `childId`, if any. */
   portalTo: (parentId: SceneId | undefined, childId: SceneId) => Node | undefined;
-  /** The frame of the scene at the head of `path`: its parent portal's frame, or its derived bounds. */
+  /** What fitting the scene at the head of `path` shows: its parent portal's frame, or its content. */
   frameOf: (path: SceneId[], scene: Scene) => Bounds;
   /** The current scene's frame, held for the visit rather than re-derived as its content changes. */
   bounds: Bounds;
-  /** The zoom against this level's own 1:1 rather than the root's; display only. */
-  nominalZoom: number;
+  /** What Fit shows: the current scene's shapes themselves (the margin is the fit's own inset). */
+  fitTarget: Bounds;
   pushHistory: (entry: HistoryEntry) => void;
+  /** Drills into a frame's scene, or opens the node in the host when its type has `hostOpen` for it. */
   drillIn: (portal: Node, animate?: boolean) => void;
   drillOut: (levels?: number, animate?: boolean) => void;
   goHistory: (offset: number) => void;
@@ -68,6 +86,7 @@ export type SceneNavigation = {
 export const useSceneNavigation = ({
   registry,
   atoms,
+  nodeRegistry,
   scenes,
   scene,
   path,
@@ -88,7 +107,7 @@ export const useSceneNavigation = ({
     (parentId: SceneId | undefined, childId: SceneId): Node | undefined => {
       const parent = parentId ? scenes[parentId] : undefined;
       return parent
-        ? Object.values(parent.nodes).find((node) => isPortalNode(node) && node.scene === childId)
+        ? Object.values(parent.nodes).find((node) => isFrameNode(node) && node.scene === childId)
         : undefined;
     },
     [scenes],
@@ -97,7 +116,7 @@ export const useSceneNavigation = ({
   const frameOf = useCallback(
     (scenePath: SceneId[], current: Scene): Bounds => {
       const portal = portalTo(scenePath[scenePath.length - 2], current.id);
-      return portal ? portalFrame(portal, contentBounds(current)) : sceneBounds(current);
+      return portal ? portalFrame(portal, contentBounds(current)) : (contentBounds(current) ?? EMPTY_FRAME);
     },
     [portalTo],
   );
@@ -118,23 +137,7 @@ export const useSceneNavigation = ({
     return frameRef.current.frame;
   }, [frameOf, path, scene]);
 
-  /**
-   * A portal frame is the portal's box times a power of the grid ratio, so entering one divides the
-   * camera by that factor; reported raw, the number would drop fourfold on a drill-in that changed
-   * nothing the user can see. Display only — nothing derives geometry from it, so the frame growing
-   * with its content cannot feed back.
-   */
-  const nominalZoom = useMemo(() => {
-    const scale = path.slice(1).reduce((accumulated, sceneId, index) => {
-      const parent = scenes[path[index]];
-      const child = scenes[sceneId];
-      const portal = parent && child ? portalTo(parent.id, sceneId) : undefined;
-      return portal && child
-        ? accumulated * portalScale(portal, portalFrame(portal, contentBounds(child)))
-        : accumulated;
-    }, 1);
-    return camera.zoom / scale;
-  }, [path, scenes, portalTo, camera.zoom]);
+  const fitTarget = useMemo(() => fitFrame(scene), [scene]);
 
   const pushHistory = useCallback(
     (entry: HistoryEntry) => {
@@ -145,9 +148,16 @@ export const useSceneNavigation = ({
     [registry, atoms.history],
   );
 
+  const hostOpen = useCallback((node: Node) => nodeDef(nodeRegistry, node)?.hostOpen?.(node), [nodeRegistry]);
+
   const drillIn = useCallback(
     (portal: Node, animate = true) => {
-      const child = isPortalNode(portal) ? scenes[portal.scene] : undefined;
+      const open = hostOpen(portal);
+      if (open) {
+        open();
+        return;
+      }
+      const child = isFrameNode(portal) ? scenes[portal.scene] : undefined;
       if (!child) {
         return;
       }
@@ -168,14 +178,15 @@ export const useSceneNavigation = ({
         // Land the child where fitting it would, margin and all, but never past 1:1, so its text lands at
         // its natural size rather than magnified to fill the view. Expressed in the child's own space and
         // mapped back out, so the zoom ends exactly where the swap puts the camera.
-        const target = exitPortal(fitBounds(childBounds, viewport, inset, 1), portal, childBounds);
-        animateTo(target, () => swap(target));
+        const target = exitPortal(fitBounds(fitFrame(child), viewport, inset, NOMINAL_ZOOM), portal, childBounds);
+        animateTo(target, () => swap(target), DRILL_ANIMATION_MS);
         setOpening(portal.id);
       } else {
         swap(registry.get(atoms.camera));
       }
     },
     [
+      hostOpen,
       scenes,
       registry,
       atoms.path,
@@ -205,7 +216,7 @@ export const useSceneNavigation = ({
         const child = scenes[next[next.length - 1]];
         const parent = scenes[next[next.length - 2]];
         const portal = parent
-          ? Object.values(parent.nodes).find((node) => isPortalNode(node) && node.scene === child?.id)
+          ? Object.values(parent.nodes).find((node) => isFrameNode(node) && node.scene === child?.id)
           : undefined;
         if (!child || !portal) {
           break;
@@ -220,7 +231,7 @@ export const useSceneNavigation = ({
       setCamera(exited);
       const parent = scenes[next[next.length - 1]];
       if (animate && parent) {
-        animateTo(fitBounds(frameOf(next, parent), viewport, inset));
+        animateTo(fitBounds(fitFrame(parent), viewport, inset, NOMINAL_ZOOM), undefined, DRILL_ANIMATION_MS);
       }
       pushHistory({ path: next, camera: exited });
     },
@@ -266,7 +277,7 @@ export const useSceneNavigation = ({
     }
     const timer = setTimeout(() => {
       const portal = Object.values(scene.nodes).find(
-        (node) => isPortalNode(node) && coverage(camera, nodeBounds(node), viewport) >= AUTO_ENTER,
+        (node) => isFrameNode(node) && !hostOpen(node) && coverage(camera, nodeBounds(node), viewport) >= AUTO_ENTER,
       );
       if (portal) {
         drillIn(portal, false);
@@ -282,7 +293,7 @@ export const useSceneNavigation = ({
       }
     }, AUTO_DRILL_MS);
     return () => clearTimeout(timer);
-  }, [camera, scene, bounds, path, viewport, drag, drillIn, drillOut, registry, atoms.history, isAnimating]);
+  }, [camera, scene, bounds, path, viewport, drag, hostOpen, drillIn, drillOut, registry, atoms.history, isAnimating]);
 
-  return { nameOf, portalTo, frameOf, bounds, nominalZoom, pushHistory, drillIn, drillOut, goHistory };
+  return { nameOf, portalTo, frameOf, bounds, fitTarget, pushHistory, drillIn, drillOut, goHistory };
 };