@salsita-ai/sdk 0.50.0-develop.f16492b14e → 0.50.0-develop.f354d3576d

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,7 +445,6 @@ 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'
 
@@ -547,8 +542,6 @@ components:
 import { useEffect } from 'react'
 import type { RefObject } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // The input types that take text; in these Ctrl+Z belongs to the field
 const TEXT_INPUT_TYPES: ReadonlySet<string> = new Set([
   'text',
@@ -688,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'
@@ -769,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'
@@ -800,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'
@@ -878,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'
@@ -932,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'
 
@@ -1017,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'
@@ -1164,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]
@@ -1260,7 +1246,6 @@ Every change is one step of the undo history: adding, changing, swapping and rem
 ```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'
@@ -1394,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
 
@@ -1443,7 +1426,6 @@ 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, onPinTap } from '../_inspector/index.js'
 import type { LatestMessageState } from '../_inspector/index.js'
 import { BrandMark, CARD_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
@@ -1685,7 +1667,6 @@ 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'
@@ -1728,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
@@ -2661,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
@@ -2800,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'
@@ -2987,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'
@@ -3032,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'
 
@@ -3199,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'
@@ -3240,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'
@@ -3327,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]
@@ -3422,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'
@@ -3567,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'
@@ -3631,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'
 
@@ -3706,8 +3676,6 @@ export const onPinTap = (listener: PinTapListener) => {
 ```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
 
@@ -3751,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'
@@ -3843,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'
@@ -3973,7 +3939,6 @@ 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, onPinTap } from '../_inspector/index.js'
 import type { LatestMessageState } from '../_inspector/index.js'
 import { BrandMark, CARD_SX, PieceIcon, TIDEPOOL, pieceLook } from '../_theme/index.js'
@@ -4257,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'
@@ -4389,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'
@@ -4469,8 +4432,6 @@ export const ViewSwitch = () => {
 import { useEffect } from 'react'
 import type { RefObject } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // The input types that take text; in these Ctrl+Z belongs to the field
 const TEXT_INPUT_TYPES: ReadonlySet<string> = new Set([
   'text',
@@ -4773,7 +4734,6 @@ 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'
@@ -4815,7 +4775,6 @@ 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'
 
@@ -4891,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
@@ -4930,7 +4888,6 @@ export default phx.frontend.createCustomPhoenixLayoutElement('TidepoolStage', ()
 ### ./src/expressions/decor.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import {
   FISH,
   LEAF_COLORS,
@@ -5100,7 +5057,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/expressions/tank.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import {
   SLOT_COUNT,
   SUBSTRATES,
@@ -5174,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

package/dist/docs/layouts/header/custom.mdx

@@ -267,8 +267,6 @@ import { Box, Stack, Typography } from '@mui/material'
 
 import { useRootEntityPrice } from '@salsita-ai/sdk/react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixLayoutElement('CustomHeaderContent', () => {
   const formattedPrice = useRootEntityPrice()
 

package/dist/docs/layouts/icon-sets.mdx

@@ -166,8 +166,6 @@ import { Stack } from '@mui/material'
 
 import { EditableDistanceDimensionButton, PhxIcon } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixEntityElement('customIcon', () => {
   return (
     <Stack spacing={1}>
@@ -188,8 +186,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('customIcon', () =>
 ```tsx
 import { SvgIcon, type SvgIconProps } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const NotVeryMuchShoppingCartSimple = (props: SvgIconProps) => (
   <SvgIcon {...props}>
     <svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 256 256">
@@ -228,8 +224,6 @@ import { createElement } from 'react'
 
 import { PhxIcon } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createGetThemeHandler(
   () =>
     ({

package/dist/docs/layouts/phoenix-elements.mdx

@@ -236,8 +236,6 @@ components:
 ```tsx
 import { Box, Chip, Stack, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.createCustomPhoenixLayoutElement('SpecialShapeFooter', () => {
   const rootEntity = phx.frontend.useRootEntityState()
 
@@ -277,8 +275,6 @@ export default phx.frontend.createCustomPhoenixLayoutElement('SpecialShapeFooter
 ### ./src/expressions/scene.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Scene: {
     $specialShapeOptions: () => {

package/dist/docs/layouts/phoenix-handlers.mdx

@@ -12,7 +12,7 @@ Phoenix handlers are the foundational system for defining custom behavior for ac
 
 ## Guide
 
-Phoenix handlers are defined in your frontend implementation using the `createPhoenixHandler` function. Each handler connects to a button defined in your domain YAML through the `handler` property.
+Phoenix handlers are defined with `phx.frontend.createPhoenixHandler`. Each handler is the default export of a file in `src/handlers/` and connects to a button defined in your domain YAML through the `handler` property.
 
 ### Define actions in domain YAML
 
@@ -34,14 +34,13 @@ The `handler` property is the link between your YAML configuration and your fron
 
 ### Implement handlers in frontend
 
-In your frontend implementation file, use `createPhoenixHandler` to define what happens when the button is clicked:
+In a file in `src/handlers/`, default-export `phx.frontend.createPhoenixHandler` to define what happens when the button is clicked. A handler that is not the file's default export is not registered:
 
 ```tsx
+// src/handlers/MyActionHandler.tsx
 import { useCallback } from 'react'
 
-import { createPhoenixHandler } from '@salsita-ai/sdk/ui'
-
-createPhoenixHandler('myActionHandler', () => {
+export default phx.frontend.createPhoenixHandler('myActionHandler', () => {
   return {
     handler: useCallback(async () => {
       // Your custom logic here
@@ -56,7 +55,7 @@ createPhoenixHandler('myActionHandler', () => {
 Every handler must return an object with a `handler` property that is an async function:
 
 ```tsx
-createPhoenixHandler('handlerName', () => {
+export default phx.frontend.createPhoenixHandler('handlerName', () => {
   // You can use React hooks here
   const configurationId = phx.frontend.useConfigurationId()
 
@@ -76,7 +75,7 @@ The outer function runs during render, so you can use React hooks. The inner `ha
 For simple synchronous actions:
 
 ```tsx
-createPhoenixHandler('simpleAlert', () => {
+export default phx.frontend.createPhoenixHandler('simpleAlert', () => {
   return {
     handler: useCallback(async () => {
       alert('Action performed!')
@@ -92,7 +91,7 @@ To show a modal dialog, use the `useModal` hook. Set `disableAutoDestroy: true`
 ```tsx
 import { useModal } from '@salsita-ai/sdk/react'
 
-createPhoenixHandler('openModal', () => {
+export default phx.frontend.createPhoenixHandler('openModal', () => {
   const { showModal } = useModal({ disableAutoDestroy: true })
 
   return {
@@ -122,7 +121,7 @@ The `disableAutoDestroy: true` option prevents the modal from being automaticall
 The system automatically shows a loading spinner while your handler runs:
 
 ```tsx
-createPhoenixHandler('apiCall', () => {
+export default phx.frontend.createPhoenixHandler('apiCall', () => {
   const configurationId = phx.frontend.useConfigurationId()
 
   return {
@@ -152,7 +151,7 @@ import { useSnackbar } from 'notistack'
 
 import { useModal } from '@salsita-ai/sdk/react'
 
-createPhoenixHandler('saveConfiguration', () => {
+export default phx.frontend.createPhoenixHandler('saveConfiguration', () => {
   const { enqueueSnackbar } = useSnackbar()
   const { showModal } = useModal()
 
@@ -188,7 +187,7 @@ createPhoenixHandler('saveConfiguration', () => {
 **Poor error handling** (avoid):
 
 ```tsx
-createPhoenixHandler('saveConfiguration', () => {
+export default phx.frontend.createPhoenixHandler('saveConfiguration', () => {
   return {
     handler: useCallback(async () => {
       // No try-catch - relies on generic error snackbar
@@ -205,20 +204,18 @@ createPhoenixHandler('saveConfiguration', () => {
 
 ### Access configurator context
 
-Use the `phx.frontend` to access configurator state and functionality:
+Use the `phx.frontend` hooks to access configurator state and functionality:
 
 ```tsx
-import { phx.frontend } from './interface.js'
-
-createPhoenixHandler('contextExample', () => {
+export default phx.frontend.createPhoenixHandler('contextExample', () => {
   const configurationId = phx.frontend.useConfigurationId()
-  const { entities } = phx.frontend.useEntities()
+  const rootEntity = phx.frontend.useRootEntityState()
 
   return {
     handler: useCallback(async () => {
       console.log('Configuration ID:', configurationId)
-      console.log('Entities:', entities)
-    }, [configurationId, entities]),
+      console.log('Root entity:', rootEntity)
+    }, [configurationId, rootEntity]),
   }
 })
 ```
@@ -245,10 +242,10 @@ Switch to "Read Mode" to see that action buttons are not available for read-only
 
 Phoenix handlers are used throughout the footer customization examples:
 
-- **[General Footer](../?path=/docs/layouts-footer-general)**: See how the default finalize button works without custom handlers
-- **[Universal Footer](../?path=/docs/layouts-footer-universal)**: Complete example with multiple custom handlers for different actions
-- **[Custom Footer](../?path=/docs/layouts-footer-custom)**: Advanced example showing handlers with custom React components
-- **[Hidden Footer](../?path=/docs/layouts-footer-hidden)**: Alternative action placement when footer is hidden
+- **[General Footer](?path=/docs/layouts-sidebar-footer-basic--docs)**: See how the default finalize button works without custom handlers
+- **[Universal Footer](?path=/docs/layouts-sidebar-footer-universal--docs)**: Complete example with multiple custom handlers for different actions
+- **[Custom Footer](?path=/docs/layouts-sidebar-footer-custom--docs)**: Advanced example showing handlers with custom React components
+- **[Hidden Footer](?path=/docs/layouts-sidebar-footer-hidden--docs)**: Alternative action placement when footer is hidden
 
 ## Complete Implementation
 
@@ -357,8 +354,6 @@ components:
 // This demonstrates the generic error snackbar that appears when errors are not caught.
 import { useCallback } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // In production code, you should use try-catch blocks to provide better user experience.
 export default phx.frontend.createPhoenixHandler('errorExample', () => {
   return {
@@ -380,8 +375,6 @@ import { useCallback } from 'react'
 
 import { useModal } from '@salsita-ai/sdk/react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // Dialog component for modal example
 interface ConfirmDialogProps extends DialogProps {
   onConfirm: () => void
@@ -435,8 +428,6 @@ export default phx.frontend.createPhoenixHandler('openModal', () => {
 ```tsx
 import { useCallback } from 'react'
 
-import { phx } from '../../.phoenix/phx.js'
-
 // Pattern 1: Simple synchronous action
 export default phx.frontend.createPhoenixHandler('simpleAlert', () => {
   return {

package/dist/docs/layouts/presets/action-and-overlay.mdx

@@ -25,8 +25,6 @@ import { useState } from 'react'
 
 import { Dialog } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const PresetPageAction = () => {
   const [isOpen, setOpen] = useState(false)
 
@@ -61,8 +59,6 @@ import { useState } from 'react'
 
 import { Dialog, useResponsive } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const SmallScreenNotice = () => {
   const { isPhone } = useResponsive()
   const [dismissed, setDismissed] = useState(false)
@@ -215,8 +211,6 @@ import { useState } from 'react'
 
 import { Dialog } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const PresetPageAction = () => {
   const [isOpen, setOpen] = useState(false)
 
@@ -278,8 +272,6 @@ import { useState } from 'react'
 
 import { Dialog, useResponsive } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const SmallScreenNotice = () => {
   const { isPhone } = useResponsive()
   const [dismissed, setDismissed] = useState(false)

package/dist/docs/layouts/presets/custom.mdx

@@ -59,7 +59,7 @@ The minimal wiring is:
 ```tsx
 const CustomPresetScreen = () => {
   const { presetCategories, selectPreset, creatingPresetId, selectionError } = phx.frontend.usePresetSelection()
-  const resolve = useResolveLocalizable()
+  const resolve = phx.frontend.useResolveLocalizable()
   const presets = presetCategories.flatMap(category => category.presets)
 
   return (
@@ -87,7 +87,7 @@ The complete file below adds the branded header, search, pinned-card ordering, t
 
 ## Preserve preview mode
 
-A full replacement must preserve the small-container entry flow itself. Check `usePreview().isPreview` before rendering the cards and return `PresetPreviewLayout`; its button calls the SDK's preview `enter` action, which expands the embedded configurator. Without this branch, a configurator with `preview: auto` in a narrow embed renders the whole preset screen inside the collapsed preview area and never expands.
+A full replacement must preserve the small-container entry flow itself. Check `phx.frontend.usePreview().isPreview` before rendering the cards and return `PresetPreviewLayout`; its button calls the SDK's preview `enter` action, which expands the embedded configurator. Without this branch, a configurator with `preview: auto` in a narrow embed renders the whole preset screen inside the collapsed preview area and never expands.
 
 ```tsx
 if (isPreview) {
@@ -238,23 +238,16 @@ components:
 import { Alert, Box, Button, CardActionArea, Chip, CircularProgress, TextField, Typography } from '@mui/material'
 import { useState } from 'react'
 
-import {
-  ClosePresetPreviewButton,
-  PresetPreviewLayout,
-  PresetSnackbarsRoot,
-  usePreview,
-} from '@salsita-ai/sdk/configurator'
-import { useResolveLocalizable, useResourceUrl } from '@salsita-ai/sdk/react'
+import { ClosePresetPreviewButton, PresetPreviewLayout, PresetSnackbarsRoot } from '@salsita-ai/sdk/configurator'
+import { useResourceUrl } from '@salsita-ai/sdk/react'
 import { PhxIcon } from '@salsita-ai/sdk/ui'
 
-import { phx } from '../../.phoenix/phx.js'
-
 const START_FROM_SCRATCH = 'Start from scratch'
 
 const CustomPresetScreen = () => {
-  const { isPreview } = usePreview()
+  const { isPreview } = phx.frontend.usePreview()
   const { presetCategories, selectPreset, creatingPresetId, selectionError } = phx.frontend.usePresetSelection()
-  const resolve = useResolveLocalizable()
+  const resolve = phx.frontend.useResolveLocalizable()
   const { getResourceUrl } = useResourceUrl()
   const [query, setQuery] = useState('')
 

package/dist/docs/layouts/preview/always-expand.mdx

@@ -38,16 +38,11 @@ This feature now works out of the box only for simple layouts, if top or step na
 
 ## Code
 
-The preview behavior can be configured directly in the `createConfiguratorAppConfig`
+Set the preview behavior with the top-level `preview` and `alwaysExpand` keys of a spec file, beside `model` and `components`:
 
-```ts
-const config = {
-  //...
-  ui: {
-    preview: 'auto',
-    alwaysExpand: true,
-  },
-}
+```yaml
+preview: always # auto | always | never | hide
+alwaysExpand: true # defaults to false; expands the configurator when users leave the preview, on desktop too
 ```
 
 ## Test cases
@@ -171,7 +166,6 @@ components:
 import { propertyPageComponent } from '@salsita-ai/sdk/domain'
 
 import { MockSidebarOne } from '../../../../common/MockSidebar.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   phx.domain.attachComponent
@@ -186,8 +180,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Table: {
     $edgeFinishFacet: s => {
@@ -230,8 +222,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomInvariants({
   Table: {
     trunkDisabled: s => {