@salsita-ai/sdk 0.50.0-develop.91d65bd507 → 0.50.0-develop.9239ced550

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

@@ -450,11 +450,13 @@ 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 +482,7 @@ export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ en
       onClick={event => {
         event.stopPropagation()
         select(piece.id)
+        announcePinTap()
       }}
       onPointerEnter={() => setPointed(true)}
       onPointerLeave={() => setPointed(false)}
@@ -542,12 +545,45 @@ components:
 
 ```ts
 import { useEffect } from 'react'
+import type { RefObject } from 'react'
 
 import { phx } from '../../.phoenix/phx.js'
 
-// 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 = () => {
+// 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()
+
+  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 +591,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 +624,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.
@@ -995,7 +1043,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}>
@@ -1206,7 +1255,7 @@ 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'
@@ -1387,7 +1436,7 @@ 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'
@@ -1395,7 +1444,7 @@ 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 +1528,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,10 +1653,35 @@ 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'
 
@@ -1615,17 +1693,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>
@@ -1718,16 +1804,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
 
@@ -3360,7 +3448,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}>
@@ -3588,6 +3677,30 @@ 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
@@ -3861,7 +3974,7 @@ 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 +4058,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 (
@@ -4350,12 +4467,45 @@ export const ViewSwitch = () => {
 
 ```ts
 import { useEffect } from 'react'
+import type { RefObject } from 'react'
 
 import { phx } from '../../.phoenix/phx.js'
 
-// 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 = () => {
+// 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()
+
+  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()
@@ -4363,10 +4513,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)
 
-      if (event.defaultPrevented || isTyping) {
+      // 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 +4546,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,6 +4769,7 @@ export const FADE_IN = keyframes`
 
 ```tsx
 import { Box } from '@mui/material'
+import { useRef } from 'react'
 
 import { LayoutSlots } from '@salsita-ai/sdk/configurator'
 
@@ -4620,17 +4781,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>
@@ -4647,11 +4816,13 @@ 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 +4848,7 @@ export default phx.frontend.createCustomPhoenixEntityElement('DecorLabel', ({ en
       onClick={event => {
         event.stopPropagation()
         select(piece.id)
+        announcePinTap()
       }}
       onPointerEnter={() => setPointed(true)}
       onPointerLeave={() => setPointed(false)}

package/dist/docs/phoenix/domain-model.mdx

@@ -842,7 +842,10 @@ Phoenix automatically:
 During `phoenix dev`, schema-compatible configurator changes can refresh the mounted application in
 place. Changes to the domain model itself are rejected from live application and require a restart;
 this preserves the last valid runtime and loaded configuration until migration and deployment can be
-coordinated atomically.
+coordinated atomically. With server persistence, restart `phoenix dev` itself: it logs an error that
+asks for the restart, and registers the changed model with its development deployment when it starts
+again. Then open the preview address it prints rather than a tab whose address has `?cid=`, which
+loads a configuration saved with the earlier model.
 
 ### The phx Global Namespace
 

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -164,6 +164,8 @@ A project has one generated env file. Phoenix keeps it in `.phoenix/`, as `.phoe
 - The deployment and environment commands (`deployment:prepare`, `deployment:prepare-dev`, `deployment:prepare-local`, `deployment:build-envs` and the others with an `--outFile` option) write `.env.generated` in the project root unless `--outFile` or `OUT_FILE` names another file. Deploy pipelines read it there. Once one of them has written it, `phoenix dev` and `phoenix build` use it.
 - Everything that reads environment variables follows the same rule: the root `.env.generated` when it exists, otherwise `.phoenix/.env.generated`. The two files are never merged.
 - `phoenix clean` removes `.phoenix/` and with it `.phoenix/.env.generated`; the next `phoenix dev` prepares the development deployment again. A root `.env.generated` stays.
+- `phoenix dev` starts on the deployment the file names, and prepares a new one when the file was written for another project, environment or server, when the spec registers something on the server the deployment was not prepared with (the domain model, the published data schema, the auth hook, the roles that may create configurations, or the assistant), and on `--force`. A running `phoenix dev` does not prepare again after such a change: it logs an error that asks for a restart.
+- Asset contents do not trigger preparation. After changing uploaded assets, restart with `phoenix dev --force` to prepare and upload them again.
 
 This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix dev` always reads and writes `.env.generated` in the project root.
 
@@ -305,14 +307,16 @@ Starts the full development environment: Vite dev server, development webhook tu
 | `--environmentSlug`     | `ENVIRONMENT_SLUG` | package.json name    | Environment slug                                                                |
 | `--withLingui`          | `WITH_LINGUI`      | `false`              | Enable i18n extraction/compilation and watch i18n sources during dev            |
 | `--persistence`         | `PERSISTENCE_MODE` | `server`             | Persistence mode                                                                |
-| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache                                                  |
+| `--force` / `-f`        | `FORCE_REBUILD`    | `false`              | Force full rebuild, skip cache, and prepare the development deployment again    |
 | `--serverUrl`           | `SERVER_URL`       | the region's server  | Phoenix server URL                                                              |
 | `--region`              | `PHOENIX_REGION`   | `eu`                 | Region of the signed-in workspace, used when no server URL is set               |
 | `--skipUpload` / `--su` | `SKIP_UPLOAD`      | `false`              | Skip the S3 asset upload when the development deployment is prepared at startup |
 
 With the application-spec pipeline, `phoenix dev` creates an empty `src/` folder when the project has none, so that it rebuilds when the first source file, such as `src/webhooks/index.ts`, is added.
 
-With the application-spec pipeline, the SDK's own Lingui CLI runs with the configuration in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
+By default, with the application-spec pipeline, `phoenix dev` bootstraps missing compiled catalogs for every configured locale at startup, so a fresh project can start without a prior sync. It compiles existing `.po` translations as they are and extracts a locale only when its `.po` source is also missing. Existing compiled catalogs and `.po` sources stay unchanged. New or changed messages still need `phoenix sync` or continuous updates enabled by `--withLingui` or `WITH_LINGUI=true`.
+
+The SDK's own Lingui CLI uses the configuration generated in `.phoenix/.linguirc`, both for `--withLingui` and when `phoenix sync` and `phoenix build` extract and compile the catalogs; see [Root Level Files](?path=/docs/phoenix-project-structure--docs#root-level-files). The dev server and `phoenix build` compile the Lingui macros (`msg`, `t`, `Trans` and the others, imported from `@lingui/core/macro`, `@lingui/react/macro` or `@lingui/macro`) with the SDK's own Lingui macro plugin and the same configuration, so the project needs neither `babel-plugin-macros` nor `@lingui/macro` for them. Babel macros of other packages are not compiled.
 
 In `server` persistence mode the project comes from `--projectSlug`, `PROJECT_SLUG` or `project` in the spec, and the credential from `DEVELOPMENT_KEY` or the `phoenix login` sign-in; see [Starting a New Project](#starting-a-new-project). When signed in, the environment is always your own development environment and `--environmentSlug` is ignored.
 
@@ -336,7 +340,11 @@ Restart the application after fixing either failure; a subscriber or generation
 observed the attempted update.
 
 Domain-model changes are not applied live yet. Phoenix rejects them with a restart-required
-diagnostic so the mounted application cannot observe a new model with old configuration data. Other
+diagnostic so the mounted application cannot observe a new model with old configuration data. With
+server persistence, `phoenix dev` logs an error that asks for its own restart, because the
+development deployment keeps the schema it was prepared with until `phoenix dev` starts again and
+prepares it. After the restart, open the preview address it prints: a tab whose address has `?cid=`
+loads a configuration saved with the earlier model, which the new model rejects. Other
 generated bootstrap, admin, data, environment, and host-integration surfaces should also be treated
 as restart-required unless their feature documentation explicitly states live-update support.
 
@@ -609,7 +617,7 @@ Known limits:
 - Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
 - Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
 
-Generated projects carry the `phoenix-variants` agent skill, which tells coding agents when to offer options, how to write each kind and what to do with your answer.
+Generated projects carry the `phoenix` agent skill, whose linked Variants guide tells coding agents when to offer options, how to write each kind and what to do with your answer.
 
 ## SDK Development
 
@@ -750,7 +758,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation in the Feedback guide linked from the `phoenix` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
 To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
 
@@ -779,7 +787,7 @@ Pass the message as the argument for a short note, or `--file` for a longer repo
 
 A message holds at most 100,000 characters, from the argument or from the file. Besides the message and the flags, the CLI sends only the SDK version, the operating system and the Node.js version; no file of the project is attached, and the Phoenix team reads a build's sources through the build's page in Studio. The project must belong to the signed-in workspace, otherwise the server refuses the feedback; without a project, the feedback is sent on its own.
 
-Generated projects carry the `phoenix-feedback` agent skill. It tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
+Generated projects carry the `phoenix` agent skill. Its linked Feedback guide tells coding agents when to draft feedback, to show you the draft and send it only after you approve it, and how to write a report: the build id with its Studio page link, the live configurator link, what the agent was doing, what happened and what was expected, the exact error or output, the workaround and a condensed conversation log. When you say you are done, or a deploy went live and you confirm the run is finished, the agent asks you to evaluate the run, one question at a time: minutes spent, then a score from 0 to 10 for the agent's guidance, the configurator's functionality, its UX, the quality of the 3D, the UI visuals and the overall result, then your comments. It never picks a score for you and sends nothing when you decline. Secrets, credentials and personal data never go into a message; file paths, spec and code snippets and your own words may, once you approved the draft that contains them. The command needs a server with API 1.40.0 or newer; a message over 5000 characters needs API 1.43.0 or newer.
 
 ## Next Steps
 

package/dist/docs/phoenix/project-structure.mdx

@@ -199,21 +199,21 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Root Level Files
 
-| File                                                   | Auto-Generated? | Notes                                 |
-| ------------------------------------------------------ | --------------- | ------------------------------------- |
-| `package.json`                                         | No              | Yours; see Dependencies               |
-| `tsconfig.json`                                        | Once            | Yours; see below                      |
-| `eslint.config.js`                                     | Once            | Yours; see below                      |
-| `prettier.config.js`                                   | Once            | Yours; see below                      |
-| `.prettierignore`                                      | No              | Optional and your own; see below      |
-| `pnpm-workspace.yaml`                                  | No              | Only with pnpm; see Package manager   |
-| `.gitignore`                                           | Partially       | Only in a git repository; see Markers |
-| `.env`                                                 | No              | Git-ignored, local config             |
-| `.env.example`                                         | No              | Template for env vars                 |
-| `.env.generated`                                       | Yes             | Optional, git-ignored; see below      |
-| `README.md`                                            | No              | Project documentation                 |
-| `AGENTS.md`                                            | No              | Your own coding-agent instructions    |
-| `.claude/skills/phoenix*/`, `.agents/skills/phoenix*/` | Yes             | Phoenix agent skills                  |
+| File                                                 | Auto-Generated? | Notes                                 |
+| ---------------------------------------------------- | --------------- | ------------------------------------- |
+| `package.json`                                       | No              | Yours; see Dependencies               |
+| `tsconfig.json`                                      | Once            | Yours; see below                      |
+| `eslint.config.js`                                   | Once            | Yours; see below                      |
+| `prettier.config.js`                                 | Once            | Yours; see below                      |
+| `.prettierignore`                                    | No              | Optional and your own; see below      |
+| `pnpm-workspace.yaml`                                | No              | Only with pnpm; see Package manager   |
+| `.gitignore`                                         | Partially       | Only in a git repository; see Markers |
+| `.env`                                               | No              | Git-ignored, local config             |
+| `.env.example`                                       | No              | Template for env vars                 |
+| `.env.generated`                                     | Yes             | Optional, git-ignored; see below      |
+| `README.md`                                          | No              | Project documentation                 |
+| `AGENTS.md`                                          | No              | Your own coding-agent instructions    |
+| `.claude/skills/phoenix/`, `.agents/skills/phoenix/` | Yes             | Phoenix agent skills                  |
 
 Sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. Earlier SDK versions wrote them once; a project that has them keeps them, and they are yours to edit.
 
@@ -242,9 +242,13 @@ With the application-spec pipeline, the Lingui configuration is `.phoenix/.lingu
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read the Phoenix agent skills. An `AGENTS.md` is yours to add for your own instructions; sync does not write one. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK, runs `phoenix deps`, installs, then runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) enter through the single `phoenix` skill under `.claude/skills/phoenix/` or `.agents/skills/phoenix/`. Its `SKILL.md` routes to the existing project, CLI, configurator workflow, code review, variants and feedback guides in `references/`. Agents read the guides for their task rather than the whole tree. The configurator workflow retains its five stages and supporting discovery, UX, asset-conversion and appearance-review references.
 
-Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
+Phoenix keeps this guidance in step with the installed SDK. During the internal beta, a project created from a canary build gets the canary-update instructions in the linked project guide: once per conversation the agent checks for a newer canary and, after telling you, updates the SDK, runs `phoenix deps`, installs, then runs `phoenix sync`.
+
+An `AGENTS.md` is yours to add; sync does not write one. Sync removes retired `phoenix-*` skill folders but leaves unrelated skills alone. If your own instructions name an earlier separate skill such as `phoenix-review`, point them at `phoenix` and the same task instead.
+
+Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; ask `phoenix` to review instead of using `/review`.
 
 ### Markers for Partial Auto-Generation