@salsita-ai/sdk 0.50.0-develop.662fa65a4c → 0.50.0-develop.6806625cca

package/dist/docs/layouts/gallery/tidepool-aquascape.mdx

@@ -218,7 +218,6 @@ components:
 The recipes are expressions, so each new piece gets the first free slot. `src/_catalog/recipes.ts` makes one recipe per variety with `phx.domain.createRecipe`, and the tank's expressions pass it the slot; a piece's **Swap for…** uses the same recipes for its own slot.
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { FISH, PLANTS, STONES, WOODS } from './pieces.js'
 
 // The recipes of each kind of piece, one per variety, for the slot the piece goes to. The tank's palette offers them
@@ -275,7 +274,6 @@ export const fishRecipes = (slot: number) => {
 ```tsx
 import { Box, ButtonBase, Tooltip, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LABEL_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 const PLUS_ICON = 'M12 6v12M6 12h12'
@@ -401,8 +399,6 @@ export const Palette = () => {
 The tank holds eight pieces, and a 60 cm tank four. The rule is a `fixable` invariant, so a change that breaks it is rejected. The palette never makes that change: while the tank is full every recipe is `disabled` with the rule's message as its `tooltipTitle`, and the palette shows it in a banner with what to do. The same rule disables the 60 cm option of the tank's size while more than four pieces stand in it.
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Tank: {
     // `fixable`: a change that puts more pieces in the tank than it holds is rejected. Before it is made, the palette's
@@ -449,12 +445,13 @@ components:
 import { Box, ButtonBase } from '@mui/material'
 import { useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
+import { announcePinTap } from '../_inspector/index.js'
 import { PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 // Rendered by the spec's `htmlHotspot` above every piece: a pin with the piece's icon, which opens into a label with
 // its name while the pointer is over the piece in the scene or over the pin, and stays open in coral while the piece
-// is selected. A click selects the piece; it stops there, so the scene does not take it as a click on empty water.
+// is selected. A click selects the piece and announces the tap, so the phone page opens the inspector even for a piece
+// that is selected already. The click goes no further, so the scene does not take it as a click on empty water.
 export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ entityId }) => {
   const tank = phx.frontend.useRootEntityState()
   const selectedId = phx.frontend.useSelectedDomainEntityId()
@@ -480,6 +477,7 @@ export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ en
       onClick={event => {
         event.stopPropagation()
         select(piece.id)
+        announcePinTap()
       }}
       onPointerEnter={() => setPointed(true)}
       onPointerLeave={() => setPointed(false)}
@@ -542,12 +540,43 @@ components:
 
 ```ts
 import { useEffect } from 'react'
+import type { RefObject } from 'react'
+
+// The input types that take text; in these Ctrl+Z belongs to the field
+const TEXT_INPUT_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'search',
+  'email',
+  'url',
+  'tel',
+  'password',
+  'number',
+  'date',
+  'datetime-local',
+  'month',
+  'time',
+  'week',
+])
+
+const isTextEntry = (target: EventTarget | null | undefined) => {
+  return (
+    target instanceof HTMLTextAreaElement ||
+    (target instanceof HTMLInputElement && TEXT_INPUT_TYPES.has(target.type)) ||
+    (target instanceof HTMLElement && target.isContentEditable)
+  )
+}
 
-import { phx } from '../../.phoenix/phx.js'
+// The configurator sits in a closed shadow root, so to the window a key pressed in it comes from the root's host; the
+// root itself says which of its elements has focus
+const getKeyTarget = (container: HTMLElement, event: KeyboardEvent) => {
+  const root = container.getRootNode()
+  const [first] = event.composedPath()
 
-// Escape puts the selected piece down; Ctrl+Z or ⌘Z undoes, with Shift it redoes. The configurator sits in a shadow
-// root, so the key's real target is the first entry of the event's composed path.
-export const useWorkspaceKeys = () => {
+  return root instanceof ShadowRoot && first === root.host ? root.activeElement : first
+}
+
+// Escape puts the selected piece down; Ctrl+Z or ⌘Z undoes, with Shift it redoes
+export const useWorkspaceKeys = (containerRef: RefObject<HTMLElement>) => {
   const tankId = phx.frontend.useRootEntityId()
   const selectedId = phx.frontend.useSelectedDomainEntityId()
   const deselect = phx.frontend.useDeselect()
@@ -555,10 +584,20 @@ export const useWorkspaceKeys = () => {
 
   useEffect(() => {
     const onKeyDown = (event: KeyboardEvent) => {
-      const target = event.composedPath()[0]
-      const isTyping = target instanceof HTMLInputElement && target.type === 'text'
+      const container = containerRef.current
+
+      if (!container) {
+        return
+      }
+
+      const target = getKeyTarget(container, event)
+
+      // Another field's keys are not the layout's; the body's are, as focus falls there when the focused button goes
+      if (target !== document.body && !(target instanceof Node && container.contains(target))) {
+        return
+      }
 
-      if (event.defaultPrevented || isTyping) {
+      if (event.defaultPrevented || isTextEntry(target)) {
         return
       }
 
@@ -578,10 +617,12 @@ export const useWorkspaceKeys = () => {
     window.addEventListener('keydown', onKeyDown)
 
     return () => window.removeEventListener('keydown', onKeyDown)
-  }, [tankId, selectedId, deselect, undo, redo])
+  }, [containerRef, tankId, selectedId, deselect, undo, redo])
 }
 ```
 
+The listener sits on `window`, but it acts only on keys pressed inside the layout's own container, which `ConfiguratorLayout` passes in as a ref, so another field on the page keeps its own Ctrl+Z, such as the multiline YAML field in the editor's Mocks panel. The configurator sits in a closed shadow root, so the window sees a key pressed in it as coming from the root's host; `getKeyTarget` asks the root which element has focus instead. A key pressed with nothing focused counts too, as its target is the page's `body`: focus falls there when the button just pressed leaves the page, as **Remove**, **Done** and a swap do, and the next Ctrl+Z must still work. Inside the container the hook still leaves a text field alone, whether a `textarea`, a content-editable element or an `input` whose type takes text. The container is focusable (`tabIndex={-1}`), so a click on the scene gives it focus and the shortcuts work after one.
+
 ## The camera frames the selection
 
 The tank has a `fitRootPerspectiveCamera` for each of the spec's two view states, **Front** and **Top**. Every piece has a `fitSelectionPerspectiveCamera` for each too, with a higher `priority`: a selection camera is active only while its entity is selected, so selecting a piece moves the camera to it, and putting it down moves the camera back to the tank. Both follow the view state, with no camera code in the layout.
@@ -640,7 +681,6 @@ The cameras fit into the safe area the page leaves free between the palette and
 ```tsx
 import { Box, ButtonBase, IconButton, Tooltip } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { TIDEPOOL } from '../_theme/index.js'
 
 const RECENTER_ICON = 'M4 9V5h4M20 9V5h-4M4 15v4h4M20 15v4h-4M12 9v6M9 12h6'
@@ -721,7 +761,6 @@ The inspector shows the selected piece, or the tank while nothing is selected. I
 ```tsx
 import { Box } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { MessageCallout } from './MessageCallout.js'
 import { PieceInspector } from './PieceInspector.js'
 import { TankInspector } from './TankInspector.js'
@@ -752,7 +791,6 @@ export const Inspector = ({ messages }: InspectorProps) => {
 ```tsx
 import { Box, Button, Tooltip, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { ControlFields } from '../_fields/index.js'
 import { FADE_IN, KIND_LABELS, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 import { PieceActions } from './PieceActions.js'
@@ -830,7 +868,6 @@ import { useMemo } from 'react'
 
 import { attributeSelectionComponent, genericDimensionComponent } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
 import { byFieldOrder } from './fields.js'
 
 export type ControlKind = 'selection' | 'dimension'
@@ -884,7 +921,6 @@ components:
 ```tsx
 import { Slider, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { TIDEPOOL } from '../_theme/index.js'
 import { FieldShell } from './FieldShell.js'
 
@@ -969,7 +1005,6 @@ components:
 import { Box, Button, ButtonBase, Collapse, Tooltip, Typography } from '@mui/material'
 import { useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LABEL_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 const SWAP_ICON = 'M7 7h11l-3-3M17 17H6l3 3'
@@ -995,7 +1030,8 @@ export const PieceActions = ({ pieceId }: PieceActionsProps) => {
         <Button
           variant="outlined"
           aria-expanded={swapOpen}
-          aria-controls="tidepool-swap"
+          // The list unmounts while collapsed, so the button points at it only while it is open
+          aria-controls={swapOpen ? 'tidepool-swap' : undefined}
           onClick={() => setSwapOpen(open => !open)}
           startIcon={
             <svg viewBox="0 0 24 24" width={18} height={18} fill="none" stroke="currentColor" strokeWidth={1.8}>
@@ -1115,7 +1151,6 @@ At the bottom of the inspector, the outline lists every piece in the order it wa
 ```tsx
 import { Box, ButtonBase, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LABEL_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 type Piece = ReturnType<typeof phx.frontend.useRootEntityState>['$decor'][number]
@@ -1206,12 +1241,11 @@ export const Outline = () => {
 
 ## Undo and redo
 
-Every change is one step of the undo history: adding, changing, swapping and removing a piece, and the tank's size and substrate. Selecting a piece is not a change, so undo passes over it; undoing a removal puts the piece back selected. The top bar's buttons read `canUndo` and `canRedo` from `phx.frontend.useUndoRedo()` and call `undo()` and `redo()`, which push the same analytics events as the built-in toolbar buttons; `use-workspace-keys` above binds them to Ctrl+Z and Ctrl+Shift+Z, or ⌘Z and ⇧⌘Z on a Mac. The top bar also shows the tank's name and size, how full it is and the total from `phx.frontend.useRootEntityPrice()`.
+Every change is one step of the undo history: adding, changing, swapping and removing a piece, and the tank's size and substrate. Selecting a piece is not a change, so undo passes over it; undoing a removal puts the piece back selected. The top bar's buttons read `canUndo` and `canRedo` from `phx.frontend.useUndoRedo()` and call `undo()` and `redo()`, which push the same analytics events as the built-in toolbar buttons; `use-workspace-keys` above binds them to Ctrl+Z and Ctrl+Shift+Z, or ⌘Z and ⇧⌘Z on a Mac, for keys pressed inside the layout or with nothing focused. The top bar also shows the tank's name and size, how full it is and the total from `phx.frontend.useRootEntityPrice()`.
 
 ```tsx
 import { Box, IconButton, Tooltip, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { BrandMark, CARD_SX, TIDEPOOL } from '../_theme/index.js'
 
 const UNDO_ICON = 'M9 14 4 9l5-5M4 9h10.5a5.5 5.5 0 0 1 0 11H11'
@@ -1345,8 +1379,6 @@ The layout mounts no `LayoutSlots.Services`, so the configurator's messages come
 ```ts
 import { useEffect, useRef, useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // A message stays this long unless the customer closes it or a newer one replaces it
 const SHOW_FOR_MS = 6000
 
@@ -1387,15 +1419,14 @@ export type LatestMessageState = ReturnType<typeof useLatestMessage>
 
 ## On a phone
 
-The same layout in a frame 390 pixels wide, as on a phone. The tank fills the screen, a bar at the bottom offers **Add**, **Inspect** and **Undo**, and the palette and the inspector rise as sheets above it. The safe area ends at the bar, or at the open sheet, so the camera keeps the tank, or the selected piece, in the free space. Selecting a piece, by tapping its pin or by adding it, opens it in the inspector. A pin shows only its icon until its piece is selected, as there is no pointer to open it. Opened on its own from the sidebar, the **Phone** story sets Storybook's viewport to 390 × 844.
+The same layout in a frame 390 pixels wide, as on a phone. The tank fills the screen, a bar at the bottom offers **Add**, **Inspect** and **Undo**, and the palette and the inspector rise as sheets above it. The safe area ends at the bar, or at the open sheet, so the camera keeps the tank, or the selected piece, in the free space. Selecting a piece, by tapping its pin or by adding it, opens it in the inspector, and tapping the pin of the piece that is still selected opens the inspector again after it was closed. A pin shows only its icon until its piece is selected, as there is no pointer to open it. Opened on its own from the sidebar, the **Phone** story sets Storybook's viewport to 390 × 844.
 
 ```tsx
 import { Box, ButtonBase, Typography } from '@mui/material'
 import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-import { Inspector, Outline } from '../_inspector/index.js'
+import { Inspector, Outline, onPinTap } from '../_inspector/index.js'
 import type { LatestMessageState } from '../_inspector/index.js'
 import { BrandMark, CARD_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 import { Palette } from './Palette.js'
@@ -1479,12 +1510,16 @@ export const PhonePage = ({ messages }: PhonePageProps) => {
   const selected = tank.$decor.find(piece => piece.id === selectedId)
   const selectedLook = selected ? pieceLook(selected) : null
 
+  // Adding a piece selects it, and so does a click on it in the scene; the inspector follows the new selection
   useEffect(() => {
     if (selectedId !== tankId) {
       setSheet('inspect')
     }
   }, [selectedId, tankId])
 
+  // A pin tap reopens the inspector for a piece that stayed selected, which the selection above does not show
+  useEffect(() => onPinTap(() => setSheet('inspect')), [])
+
   const toggle = (next: Sheet) => setSheet(current => (current === next ? null : next))
 
   return (
@@ -1600,14 +1635,38 @@ export const PhonePage = ({ messages }: PhonePageProps) => {
 }
 ```
 
-`ConfiguratorLayout` keeps the scene mounted and lays the desktop or the phone page over it, by the width of the configurator's container from `phx.frontend.useActiveViewports()`. It also holds the messages and the keyboard shortcuts, so both work whichever page shows.
+A pin is drawn inside the scene, so it cannot hand the phone page a prop. `DecorLabel` announces each tap through a small channel, and the phone page opens the inspector on it. The channel is what reopens the sheet for a piece that is still selected, where the selection does not change; a piece that is added, or clicked in the scene, opens the inspector through the new selection.
+
+```ts
+type PinTapListener = () => void
+
+const listeners = new Set<PinTapListener>()
+
+// A pin is drawn inside the scene, so it cannot hand the phone page a prop. It announces each tap here, also the tap
+// on a piece that is already selected, which the selection alone does not show. The channel is shared by every copy of
+// the layout in the page; a tap there only opens a sheet, so that costs nothing.
+export const announcePinTap = () => {
+  listeners.forEach(listener => listener())
+}
+
+/** Calls `listener` on every pin tap until the returned function is called. */
+export const onPinTap = (listener: PinTapListener) => {
+  listeners.add(listener)
+
+  return () => {
+    listeners.delete(listener)
+  }
+}
+```
+
+`ConfiguratorLayout` keeps the scene mounted and lays the desktop or the phone page over it, by the width of the configurator's container from `phx.frontend.useActiveViewports()`. It also holds the messages and the keyboard shortcuts, so both work whichever page shows; the shortcuts act on keys inside the container it renders, or with nothing focused.
 
 ```tsx
 import { Box } from '@mui/material'
+import { useRef } from 'react'
 
 import { LayoutSlots } from '@salsita-ai/sdk/configurator'
 
-import { phx } from '../../.phoenix/phx.js'
 import { useLatestMessage } from '../_inspector/index.js'
 import { DesktopPage } from '../_shared/DesktopPage.js'
 import { PhonePage } from '../_shared/PhonePage.js'
@@ -1615,17 +1674,25 @@ import { useWorkspaceKeys } from '../_shared/use-workspace-keys.js'
 import { TIDEPOOL } from '../_theme/index.js'
 
 // A workspace over the scene. The canvas stays mounted the whole time; the desktop or the phone page lies over it.
-// The messages and the keyboard shortcuts live here, so they work whichever page shows and whatever is open.
+// The messages and the keyboard shortcuts live here, so they work whichever page shows and whatever is open. The
+// shortcuts act on keys pressed inside this container, or on the body, where focus falls when the focused control goes;
+// the container takes focus when the scene is clicked, so they work there too.
 const ConfiguratorLayout = () => {
   // `null` until the container has been measured; only the scene shows until then
   const viewports = phx.frontend.useActiveViewports()
   const messages = useLatestMessage()
   const isDesktop = viewports?.includes('desktop') ?? false
+  const containerRef = useRef<HTMLDivElement>(null)
 
-  useWorkspaceKeys()
+  useWorkspaceKeys(containerRef)
 
   return (
-    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: TIDEPOOL.foam }}>
+    <Box
+      component="div"
+      ref={containerRef}
+      tabIndex={-1}
+      sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: TIDEPOOL.foam, outline: 'none' }}
+    >
       <LayoutSlots.SharedCanvas />
       {viewports !== null && (isDesktop ? <DesktopPage messages={messages} /> : <PhonePage messages={messages} />)}
     </Box>
@@ -1642,7 +1709,6 @@ The spec's `canvasCustomEnvironment` names `TidepoolStage`, a layout element ren
 ```tsx
 import { ContactShadows, Environment, Lightformer } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
 import { TIDEPOOL } from '../_theme/index.js'
 
 // The stage named by the spec's `canvasCustomEnvironment`: the page's foam colour behind the tank, a cool lamp above
@@ -1718,16 +1784,18 @@ The aquarium is `public/models/gallery/aquarium.glb`, generated by `scripts/mode
 - On the neon tetras, the **School size** slider adds and takes away fish two at a time while it moves; at 12 the school costs $42.00.
 - **Swap for…** on a stone lists plants, wood and fish; **Amazon sword** puts a green Amazon sword in the stone's place, selected.
 - **Remove** takes the piece out, the count drops to "4 / 8" and the inspector shows the tank. **Undo**, or Ctrl+Z, puts the piece back, selected; **Redo**, or Ctrl+Shift+Z, removes it again.
-- **Done**, Escape and a click on empty water put the selected piece down, and the camera returns to the whole tank.
+- Select a piece, press **Remove** and press Ctrl+Z, or ⌘Z on a Mac, at once, with no click in between: the piece comes back, selected. The button just pressed has left the page, so the shortcut must work with nothing focused. The same holds after **Done**, where Ctrl+Z takes back the last change, and after a swap from **Swap for…**, where it puts the first piece back.
+- **Done**, Escape and a click on empty water put the selected piece down, and the camera returns to the whole tank. Ctrl+Z and Escape work after a click on the tank too.
+- In the editor's **Mocks** panel, **Create Mock**, **Edit** and a click in a YAML field: typing there and pressing Ctrl+Z undoes the typing; the tank, its total and its undo history stay as they are.
 - A row of the palette adds its piece in the first free slot and selects it. With eight pieces in the tank every row is disabled, a banner says "The tank holds 8 pieces at most. Remove a piece to make room.", and "8 / 8" turns coral.
 - While more than four pieces stand in the tank, **60 cm** is faded with "A 60 cm tank holds 4 pieces at most." below it. Clicking it shows the same message at the top of the inspector, and the tank keeps its size.
 - With four pieces left, **60 cm** shrinks the tank, its pieces close up and the camera frames the smaller tank; the palette is disabled with "A 60 cm tank holds 4 pieces at most. Remove a piece, or choose a larger tank." **120 cm** spreads the pieces out, and the camera frames the larger tank.
 - With every piece removed, the outline says "Nothing yet." and the inspector suggests where to start.
 - **Top** moves the camera above the tank, also while a piece is selected, and **Front** moves it back; the third button undoes an orbit or a zoom.
 - **Aqua soil** and **River gravel** recolour the substrate and change the total.
-- Applying **Full tank** in the editor's **Mocks** panel opens a full 90 cm tank on aqua soil.
-- In the **Phone** story the tank fills the screen above a bar with **Add**, **Inspect** and **Undo**. **Add** raises the palette as a sheet, and the camera frames the tank above it; adding a piece opens it in the inspector sheet; tapping a pin opens that piece; closing the sheet gives the tank the screen again.
-- The browser console shows no errors.
+- Applying **Full tank** in the editor's **Mocks** panel opens a full 90 cm tank on aqua soil. The canvas system logs three "Force flush timeout" errors to the browser console while it does; opening the story with that template does not.
+- In the **Phone** story the tank fills the screen above a bar with **Add**, **Inspect** and **Undo**. **Add** raises the palette as a sheet, and the camera frames the tank above it; adding a piece opens it in the inspector sheet; tapping a pin opens that piece; closing the sheet gives the tank the screen again, and tapping the same pin opens it once more.
+- The browser console shows no errors, apart from the three "Force flush timeout" errors that applying **Full tank** logs.
 
 ## What this layout leaves out
 
@@ -2573,7 +2641,6 @@ export const SUBSTRATES = {
 ### ./src/\_catalog/recipes.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { FISH, PLANTS, STONES, WOODS } from './pieces.js'
 
 // The recipes of each kind of piece, one per variety, for the slot the piece goes to. The tank's palette offers them
@@ -2712,7 +2779,6 @@ export const firstFreeSlot = (taken: readonly number[]) => {
 import { Box, ButtonBase, Typography } from '@mui/material'
 import type { KeyboardEvent } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 import { FieldShell } from './FieldShell.js'
 import type { ChoiceStyle } from './fields.js'
@@ -2899,7 +2965,6 @@ export const ChoiceField = ({ entityId, entityType, instanceName, label, style,
 ```tsx
 import { Box } from '@mui/material'
 
-import type { phx } from '../../.phoenix/phx.js'
 import { ChoiceField } from './ChoiceField.js'
 import { CountField } from './CountField.js'
 import { fieldOf } from './fields.js'
@@ -2944,7 +3009,6 @@ export const ControlFields = ({ entityId, entityType }: ControlFieldsProps) => {
 ```tsx
 import { Slider, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { TIDEPOOL } from '../_theme/index.js'
 import { FieldShell } from './FieldShell.js'
 
@@ -3111,7 +3175,6 @@ import { useMemo } from 'react'
 
 import { attributeSelectionComponent, genericDimensionComponent } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
 import { byFieldOrder } from './fields.js'
 
 export type ControlKind = 'selection' | 'dimension'
@@ -3152,7 +3215,6 @@ export const useActiveControls = (entityId: ReturnType<typeof phx.frontend.useSe
 ```tsx
 import { Box } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { MessageCallout } from './MessageCallout.js'
 import { PieceInspector } from './PieceInspector.js'
 import { TankInspector } from './TankInspector.js'
@@ -3239,7 +3301,6 @@ export const MessageCallout = ({ message, dismiss }: LatestMessageState) => {
 ```tsx
 import { Box, ButtonBase, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LABEL_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 type Piece = ReturnType<typeof phx.frontend.useRootEntityState>['$decor'][number]
@@ -3334,7 +3395,6 @@ export const Outline = () => {
 import { Box, Button, ButtonBase, Collapse, Tooltip, Typography } from '@mui/material'
 import { useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LABEL_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 const SWAP_ICON = 'M7 7h11l-3-3M17 17H6l3 3'
@@ -3360,7 +3420,8 @@ export const PieceActions = ({ pieceId }: PieceActionsProps) => {
         <Button
           variant="outlined"
           aria-expanded={swapOpen}
-          aria-controls="tidepool-swap"
+          // The list unmounts while collapsed, so the button points at it only while it is open
+          aria-controls={swapOpen ? 'tidepool-swap' : undefined}
           onClick={() => setSwapOpen(open => !open)}
           startIcon={
             <svg viewBox="0 0 24 24" width={18} height={18} fill="none" stroke="currentColor" strokeWidth={1.8}>
@@ -3478,7 +3539,6 @@ export const PieceActions = ({ pieceId }: PieceActionsProps) => {
 ```tsx
 import { Box, Button, Tooltip, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { ControlFields } from '../_fields/index.js'
 import { FADE_IN, KIND_LABELS, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 import { PieceActions } from './PieceActions.js'
@@ -3542,7 +3602,6 @@ export const PieceInspector = ({ pieceId }: PieceInspectorProps) => {
 ```tsx
 import { Box, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { ControlFields } from '../_fields/index.js'
 import { FADE_IN, TIDEPOOL } from '../_theme/index.js'
 
@@ -3588,13 +3647,35 @@ export const TankInspector = () => {
 }
 ```
 
+### ./src/\_inspector/pin-taps.ts
+
+```ts
+type PinTapListener = () => void
+
+const listeners = new Set<PinTapListener>()
+
+// A pin is drawn inside the scene, so it cannot hand the phone page a prop. It announces each tap here, also the tap
+// on a piece that is already selected, which the selection alone does not show. The channel is shared by every copy of
+// the layout in the page; a tap there only opens a sheet, so that costs nothing.
+export const announcePinTap = () => {
+  listeners.forEach(listener => listener())
+}
+
+/** Calls `listener` on every pin tap until the returned function is called. */
+export const onPinTap = (listener: PinTapListener) => {
+  listeners.add(listener)
+
+  return () => {
+    listeners.delete(listener)
+  }
+}
+```
+
 ### ./src/\_inspector/use-latest-message.ts
 
 ```ts
 import { useEffect, useRef, useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // A message stays this long unless the customer closes it or a newer one replaces it
 const SHOW_FOR_MS = 6000
 
@@ -3638,7 +3719,6 @@ export type LatestMessageState = ReturnType<typeof useLatestMessage>
 ```tsx
 import { Box, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { Inspector, Outline } from '../_inspector/index.js'
 import type { LatestMessageState } from '../_inspector/index.js'
 import { CARD_SX, TIDEPOOL } from '../_theme/index.js'
@@ -3730,7 +3810,6 @@ export const DesktopPage = ({ messages }: DesktopPageProps) => {
 ```tsx
 import { Box, ButtonBase, Tooltip, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { LABEL_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 const PLUS_ICON = 'M12 6v12M6 12h12'
@@ -3860,8 +3939,7 @@ import { Box, ButtonBase, Typography } from '@mui/material'
 import { useEffect, useState } from 'react'
 import type { ReactNode } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-import { Inspector, Outline } from '../_inspector/index.js'
+import { Inspector, Outline, onPinTap } from '../_inspector/index.js'
 import type { LatestMessageState } from '../_inspector/index.js'
 import { BrandMark, CARD_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 import { Palette } from './Palette.js'
@@ -3945,12 +4023,16 @@ export const PhonePage = ({ messages }: PhonePageProps) => {
   const selected = tank.$decor.find(piece => piece.id === selectedId)
   const selectedLook = selected ? pieceLook(selected) : null
 
+  // Adding a piece selects it, and so does a click on it in the scene; the inspector follows the new selection
   useEffect(() => {
     if (selectedId !== tankId) {
       setSheet('inspect')
     }
   }, [selectedId, tankId])
 
+  // A pin tap reopens the inspector for a piece that stayed selected, which the selection above does not show
+  useEffect(() => onPinTap(() => setSheet('inspect')), [])
+
   const toggle = (next: Sheet) => setSheet(current => (current === next ? null : next))
 
   return (
@@ -4140,7 +4222,6 @@ export const PhoneSheet = ({ title, closeLabel, bottom, height, onClose, childre
 ```tsx
 import { Box, IconButton, Tooltip, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { BrandMark, CARD_SX, TIDEPOOL } from '../_theme/index.js'
 
 const UNDO_ICON = 'M9 14 4 9l5-5M4 9h10.5a5.5 5.5 0 0 1 0 11H11'
@@ -4272,7 +4353,6 @@ export const TopBar = () => {
 ```tsx
 import { Box, ButtonBase, IconButton, Tooltip } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { TIDEPOOL } from '../_theme/index.js'
 
 const RECENTER_ICON = 'M4 9V5h4M20 9V5h-4M4 15v4h4M20 15v4h-4M12 9v6M9 12h6'
@@ -4350,12 +4430,43 @@ export const ViewSwitch = () => {
 
 ```ts
 import { useEffect } from 'react'
+import type { RefObject } from 'react'
+
+// The input types that take text; in these Ctrl+Z belongs to the field
+const TEXT_INPUT_TYPES: ReadonlySet<string> = new Set([
+  'text',
+  'search',
+  'email',
+  'url',
+  'tel',
+  'password',
+  'number',
+  'date',
+  'datetime-local',
+  'month',
+  'time',
+  'week',
+])
+
+const isTextEntry = (target: EventTarget | null | undefined) => {
+  return (
+    target instanceof HTMLTextAreaElement ||
+    (target instanceof HTMLInputElement && TEXT_INPUT_TYPES.has(target.type)) ||
+    (target instanceof HTMLElement && target.isContentEditable)
+  )
+}
+
+// The configurator sits in a closed shadow root, so to the window a key pressed in it comes from the root's host; the
+// root itself says which of its elements has focus
+const getKeyTarget = (container: HTMLElement, event: KeyboardEvent) => {
+  const root = container.getRootNode()
+  const [first] = event.composedPath()
 
-import { phx } from '../../.phoenix/phx.js'
+  return root instanceof ShadowRoot && first === root.host ? root.activeElement : first
+}
 
-// Escape puts the selected piece down; Ctrl+Z or ⌘Z undoes, with Shift it redoes. The configurator sits in a shadow
-// root, so the key's real target is the first entry of the event's composed path.
-export const useWorkspaceKeys = () => {
+// Escape puts the selected piece down; Ctrl+Z or ⌘Z undoes, with Shift it redoes
+export const useWorkspaceKeys = (containerRef: RefObject<HTMLElement>) => {
   const tankId = phx.frontend.useRootEntityId()
   const selectedId = phx.frontend.useSelectedDomainEntityId()
   const deselect = phx.frontend.useDeselect()
@@ -4363,10 +4474,20 @@ export const useWorkspaceKeys = () => {
 
   useEffect(() => {
     const onKeyDown = (event: KeyboardEvent) => {
-      const target = event.composedPath()[0]
-      const isTyping = target instanceof HTMLInputElement && target.type === 'text'
+      const container = containerRef.current
+
+      if (!container) {
+        return
+      }
 
-      if (event.defaultPrevented || isTyping) {
+      const target = getKeyTarget(container, event)
+
+      // Another field's keys are not the layout's; the body's are, as focus falls there when the focused button goes
+      if (target !== document.body && !(target instanceof Node && container.contains(target))) {
+        return
+      }
+
+      if (event.defaultPrevented || isTextEntry(target)) {
         return
       }
 
@@ -4386,7 +4507,7 @@ export const useWorkspaceKeys = () => {
     window.addEventListener('keydown', onKeyDown)
 
     return () => window.removeEventListener('keydown', onKeyDown)
-  }, [tankId, selectedId, deselect, undo, redo])
+  }, [containerRef, tankId, selectedId, deselect, undo, redo])
 }
 ```
 
@@ -4609,10 +4730,10 @@ export const FADE_IN = keyframes`
 
 ```tsx
 import { Box } from '@mui/material'
+import { useRef } from 'react'
 
 import { LayoutSlots } from '@salsita-ai/sdk/configurator'
 
-import { phx } from '../../.phoenix/phx.js'
 import { useLatestMessage } from '../_inspector/index.js'
 import { DesktopPage } from '../_shared/DesktopPage.js'
 import { PhonePage } from '../_shared/PhonePage.js'
@@ -4620,17 +4741,25 @@ import { useWorkspaceKeys } from '../_shared/use-workspace-keys.js'
 import { TIDEPOOL } from '../_theme/index.js'
 
 // A workspace over the scene. The canvas stays mounted the whole time; the desktop or the phone page lies over it.
-// The messages and the keyboard shortcuts live here, so they work whichever page shows and whatever is open.
+// The messages and the keyboard shortcuts live here, so they work whichever page shows and whatever is open. The
+// shortcuts act on keys pressed inside this container, or on the body, where focus falls when the focused control goes;
+// the container takes focus when the scene is clicked, so they work there too.
 const ConfiguratorLayout = () => {
   // `null` until the container has been measured; only the scene shows until then
   const viewports = phx.frontend.useActiveViewports()
   const messages = useLatestMessage()
   const isDesktop = viewports?.includes('desktop') ?? false
+  const containerRef = useRef<HTMLDivElement>(null)
 
-  useWorkspaceKeys()
+  useWorkspaceKeys(containerRef)
 
   return (
-    <Box component="div" sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: TIDEPOOL.foam }}>
+    <Box
+      component="div"
+      ref={containerRef}
+      tabIndex={-1}
+      sx={{ position: 'absolute', inset: 0, overflow: 'clip', bgcolor: TIDEPOOL.foam, outline: 'none' }}
+    >
       <LayoutSlots.SharedCanvas />
       {viewports !== null && (isDesktop ? <DesktopPage messages={messages} /> : <PhonePage messages={messages} />)}
     </Box>
@@ -4646,12 +4775,13 @@ export default phx.frontend.createCustomPhoenixLayoutElement('ConfiguratorLayout
 import { Box, ButtonBase } from '@mui/material'
 import { useState } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
+import { announcePinTap } from '../_inspector/index.js'
 import { PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
 
 // Rendered by the spec's `htmlHotspot` above every piece: a pin with the piece's icon, which opens into a label with
 // its name while the pointer is over the piece in the scene or over the pin, and stays open in coral while the piece
-// is selected. A click selects the piece; it stops there, so the scene does not take it as a click on empty water.
+// is selected. A click selects the piece and announces the tap, so the phone page opens the inspector even for a piece
+// that is selected already. The click goes no further, so the scene does not take it as a click on empty water.
 export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ entityId }) => {
   const tank = phx.frontend.useRootEntityState()
   const selectedId = phx.frontend.useSelectedDomainEntityId()
@@ -4677,6 +4807,7 @@ export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ en
       onClick={event => {
         event.stopPropagation()
         select(piece.id)
+        announcePinTap()
       }}
       onPointerEnter={() => setPointed(true)}
       onPointerLeave={() => setPointed(false)}
@@ -4719,7 +4850,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ en
 ```tsx
 import { ContactShadows, Environment, Lightformer } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
 import { TIDEPOOL } from '../_theme/index.js'
 
 // The stage named by the spec's `canvasCustomEnvironment`: the page's foam colour behind the tank, a cool lamp above
@@ -4758,7 +4888,6 @@ export default phx.frontend.createCustomPhoenixLayoutElement('TidepoolStage', ()
 ### ./src/expressions/decor.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import {
   FISH,
   LEAF_COLORS,
@@ -4928,7 +5057,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/expressions/tank.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import {
   SLOT_COUNT,
   SUBSTRATES,
@@ -5002,8 +5130,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/tank.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Tank: {
     // `fixable`: a change that puts more pieces in the tank than it holds is rejected. Before it is made, the palette's