@salsita-ai/sdk 0.50.0-develop.bb71259564 → 0.50.0-develop.bc204720a8

package/dist/docs/performance/dynamic-components.mdx

@@ -428,8 +428,6 @@ import {
   sceneEntityRemoteObjectComponent,
 } from '@salsita-ai/sdk/domain'
 
-import { phx } from '../../.phoenix/phx.js'
-
 export default [
   phx.domain.attachComponent
     .withComponent(sceneEntityRemoteObjectComponent, 'drawers')
@@ -464,7 +462,6 @@ export default [
 import { memoEval } from '@salsita-ai/sdk/domain'
 
 import type { $DrawerCabinet } from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 
 const SEPARATOR_WIDTH = 30
 const FRAME_WIDTH = 50
@@ -616,7 +613,6 @@ export default phx.domain.implementCustomExpressions({
 
 ```ts
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { isOverlapping } from '../_shared/overlap.js'
 
 const getCollisionFixingUpdates = (
@@ -678,8 +674,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/editable-dimension-stress-test.mdx

@@ -232,8 +232,6 @@ components:
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   Scene: {
     $width: s => s.width,

package/dist/docs/performance/fast-highlight.mdx

@@ -177,7 +177,6 @@ import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('ConsoleUnit', phx.domain.attachComponent),
@@ -211,8 +210,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   ConsoleUnit: {
     $x: s => s.x,
@@ -224,7 +221,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isConsoleOverlapping } from '../_shared/overlap.js'
 
 export default phx.domain.implementCustomInvariants({
@@ -254,7 +250,6 @@ export default phx.domain.implementCustomInvariants({
 import { type DomainEntityId } from '@salsita-ai/sdk/domain'
 
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { CONSOLE_DEPTH, CONSOLE_WIDTH, type Coords, isConsoleOverlapping } from '../_shared/overlap.js'
 
 const distance = (a: Coords, b: Coords) => Math.sqrt((a.x - b.x) ** 2 + (a.z - b.z) ** 2)
@@ -330,8 +325,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/general.mdx

@@ -208,7 +208,6 @@ import { SelectionHotspot } from '@salsita-ai/sdk/configurator'
 import { htmlHotspotComponent, memoEval } from '@salsita-ai/sdk/domain'
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('ConsoleUnit', phx.domain.attachComponent),
@@ -242,8 +241,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   ConsoleUnit: {
     $x: s => s.x,
@@ -255,7 +252,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/invariants/invariants.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isConsoleOverlapping } from '../_shared/overlap.js'
 
 export default phx.domain.implementCustomInvariants({
@@ -285,7 +281,6 @@ export default phx.domain.implementCustomInvariants({
 import { type DomainEntityId } from '@salsita-ai/sdk/domain'
 
 import type * as EnhancedModel from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 import { CONSOLE_DEPTH, CONSOLE_WIDTH, type Coords, isConsoleOverlapping } from '../_shared/overlap.js'
 
 const distance = (a: Coords, b: Coords) => Math.sqrt((a.x - b.x) ** 2 + (a.z - b.z) ** 2)
@@ -361,8 +356,6 @@ export default phx.frontend.transformerBuilder.when
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.frontend.transformerBuilder.always.then
   .applySideEffect(ctx => {
     const $root = ctx.getNew$Root()

package/dist/docs/performance/render-isolation.mdx

@@ -409,7 +409,6 @@ export const RenderFlash = ({ overlayRef, size: [width, height, depth], position
 import type { IdSequence } from '@salsita-ai/sdk/domain'
 
 import type * as Model from '../../.phoenix/application-types.js'
-import { phx } from '../../.phoenix/phx.js'
 
 // All distances are in millimetres, the default data unit of the application.
 export const ROOM_WIDTH = 2000
@@ -509,7 +508,6 @@ export const createBatchUpdates = ({ $scene, sequence, roomCount }: BatchContext
 ```tsx
 import { Text } from '@react-three/drei'
 
-import { phx } from '../../.phoenix/phx.js'
 import { RenderFlash, useRenderFlash } from '../_shared/RenderFlash.js'
 
 export default phx.frontend.createCustomPhoenixEntityElement('BoxMesh', ({ entityId }) => {
@@ -564,7 +562,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('BoxMesh', ({ entit
 ```tsx
 import { Box, Button, Stack, Typography } from '@mui/material'
 
-import { phx } from '../../.phoenix/phx.js'
 import { ROOMS_PER_CLICK, createBatchUpdates } from '../_shared/layout.js'
 
 export default phx.frontend.createCustomPhoenixLayoutElement('PerformancePanel', () => {
@@ -609,7 +606,6 @@ import { Billboard, Text } from '@react-three/drei'
 import { useEffect, useMemo } from 'react'
 import { BoxGeometry, EdgesGeometry } from 'three'
 
-import { phx } from '../../.phoenix/phx.js'
 import { RenderFlash, useRenderFlash } from '../_shared/RenderFlash.js'
 import { ROOM_HEIGHT } from '../_shared/layout.js'
 
@@ -681,7 +677,6 @@ export default phx.frontend.createCustomPhoenixEntityElement('RoomFrame', ({ ent
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { isInsideRoom, roomColor } from '../_shared/layout.js'
 
 interface RoomFloor {
@@ -765,7 +760,6 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/transformers/initial.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
 import { INITIAL_ROOM_COUNT, createBatchUpdates } from '../_shared/layout.js'
 
 export default phx.frontend.transformerBuilder.always.then

package/dist/docs/phoenix/admin.mdx

@@ -119,15 +119,13 @@ useAuthHook: true
 useClerk: true
 ```
 
-This generates the necessary configuration in `.phoenix/config.js`. The `phoenix.config.ts` file is auto-generated by phx-cli from your spec files.
+phx-cli generates the frontend and webhook configuration in `.phoenix/` from your spec files, so the project writes no configuration file for it.
 
 **Webhook Auth Handler**: Create an auth handler for Clerk integration:
 
 ```typescript
 // src/webhooks/handlers/auth-handler.ts
-import { authHandlerBuilder } from '.phoenix/webhooks.js'
-
-export const authHandler = authHandlerBuilder
+export const authHandler = phx.webhooks.authHandlerBuilder
   .withClerkSessionHandler() // Handles inline Clerk session exchange
   .withClerkCodeHandler() // Handles Clerk OAuth integration
   .withClerkRefreshHandler() // Handles Clerk token refresh
@@ -140,26 +138,19 @@ export const authHandler = authHandlerBuilder
   .build()
 ```
 
-**Clerk Integration**: In phx-cli projects, webhook builders are auto-generated and Clerk credentials come from environment variables configured in `spec/application.yaml`:
-
-```yaml
-# spec/application.yaml
-useAuthHook: true
-useClerk: true
-```
+**Clerk Integration**: In phx-cli projects, the webhook builders are generated into `.phoenix/webhook-builders.ts`, which sets the `phx.webhooks` global, so project code uses them without importing anything from `.phoenix/`. With `useClerk: true`, the Clerk credentials come from the workspace's Clerk settings in Studio and reach the webhook as generated variables; the project declares none of them.
 
-The builders are available from the generated `.phoenix/webhooks.js`:
+Register the auth handler in the webhook entry, the default export of `src/webhooks/index.ts`:
 
 ```typescript
-// Available from generated code:
-import { adminFinalizeHandlerBuilder, authHandlerBuilder, webhookBuilder } from '.phoenix/webhooks.js'
+// src/webhooks/index.ts
+import { authHandler } from './handlers/auth-handler.js'
 
-// Or via phx global:
-phx.webhooks.authHandlerBuilder
-phx.webhooks.adminFinalizeHandlerBuilder
-phx.webhooks.webhookBuilder
+export default phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
 ```
 
+Admin publishing needs no builder: the SDK adds the Admin finalization to the webhook itself (see [Webhook Integration](#webhook-integration)).
+
 ### Admin Domain Configuration
 
 Create your admin domain model with entities that represent the content you want to manage.
@@ -221,17 +212,17 @@ model:
           type: boolean
 ```
 
-**Phoenix Config for Admin**: In phx-cli projects, the phoenix config is auto-generated from your spec files. When you create admin spec files with `$admin: true`, phx-cli automatically:
+**Phoenix Config for Admin**: In phx-cli projects, the admin configuration is generated from your spec files. When you create admin spec files with `$admin: true`, phx-cli automatically:
 
-1. Generates `AdminModel` with entities and model version
-2. Configures the admin section in `.phoenix/config.js`
-3. Exports types from `.phoenix/domain.js`
+1. Generates the admin model types, available as `Phx['AdminModel']`
+2. Generates the admin configuration in `.phoenix/admin-config.ts`
+3. Sets the admin entity reflections on `phx.domain.admin.model`
 
 ```typescript
-// Generated and available from .phoenix/domain.js:
-import { AdminModel, ApplicationTypes, Model } from '.phoenix/domain.js'
+// No import needed: `Phx` and `phx` are generated globals
+type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
-// AdminModel.modelVersion, AdminModel.entities, etc. are auto-generated
+const isCustomMaterial = phx.domain.admin.model.CustomMaterial.is
 ```
 
 ## Admin Navigation System
@@ -240,123 +231,85 @@ Phoenix provides a built-in navigation system for admin interfaces that automati
 
 ### Navigation Components
 
-**Built-in Admin Pages**: The `createAdminPages` function generates common admin functionality:
+**Built-in Admin Pages**: Declare the admin pages in the `$adminPages` section of an admin spec file. Phoenix generates each page, its sidebar, the navigation states it uses and the admin navigation menu:
 
-```typescript
-// src/admin/components/admin-components.tsx
-import {
-  createAdminPages,
-  adminSidebarComponent,
-  memoEval,
-  navigationPageComponent,
-  navigationPanelListComponent,
-  attachAdminComponent,
-} from '.phoenix/domain.js'
-import { ApplicationTypes } from '.phoenix/domain.js'
-
-// Create common admin pages (presets, recipes)
-const { commonComponents: commonAdminComponents, commonPages } = createAdminPages({
-  presets: {
-    categoryNavigationState: ApplicationTypes.AdminNavigationState.PresetCategories,
-    presetNavigationState: ApplicationTypes.AdminNavigationState.Presets,
-  },
-  recipes: {
-    collections: [
-      {
-        name: 'Hoods',
-        navigationState: ApplicationTypes.AdminNavigationState.HoodRecipes,
-      },
-      {
-        name: 'Modules',
-        navigationState: ApplicationTypes.AdminNavigationState.ModuleRecipes,
-      },
-    ],
-  },
-})
+```yaml
+# spec/admin/pages.yaml
+$admin: true
 
-export const customAdminOptics = [
-  ...commonAdminComponents, // Include built-in admin components
+$adminPages:
+  presets: true
+  recipes:
+    - name: Hoods
+    - name: Modules
+  pages:
+    - key: customMaterials
+      title: Materials
+      icon: PaletteBold
+      entity: CustomMaterial
+      component: MaterialsPage
+      actionsComponent: MaterialActions
+      sidebar:
+        title: Edit Material
+        component: MaterialSidebar
+```
 
-  // Create navigation page for custom content
-  attachAdminComponent
-    .withEntity('Admin')
-    .withComponent(navigationPageComponent, 'customMaterials')
-    .withGradualFilter({
-      navigationStates: [ApplicationTypes.AdminNavigationState.Other],
-    })
-    .attach(
-      memoEval(
-        () => [],
-        () => ({
-          title: 'Materials',
-          breadcrumbs: [
-            {
-              label: 'Materials',
-              navigationState: ApplicationTypes.AdminNavigationState.Other,
-            },
-          ],
-          content: <MaterialsPage />,
-          actions: <MaterialActions />,
-        })
-      )
-    ),
+- `presets: true` adds the preset category and preset pages on the `PresetCategories` and `Presets` navigation states; an object with `categoryNavigationState` and `presetNavigationState` names the states instead.
+- Each `recipes` entry adds a page for that recipe collection on the `<name>Recipes` navigation state, or on its `navigationState`; the menu groups them under **Recipes**.
+- Each `pages` entry adds a custom page on the navigation state named by its `key`, or by its `navigationState`. `component` and `actionsComponent` name the layout elements rendered as the page content and its actions; `sidebar.component` names the entity element shown in the sidebar when an entity of type `entity` is selected on the page.
+
+Phoenix adds the generated navigation states to the admin spec, so they are not listed under `navigationStates` as well; listing one there is an error. Only one admin spec file can declare `$adminPages`.
+
+The page content and actions are layout elements, and the sidebar is an entity element, each the default export of a file in `src/admin/elements/`:
+
+```tsx
+// src/admin/elements/MaterialsPage.tsx
+export default phx.frontend.createCustomPhoenixLayoutElement('MaterialsPage', () => {
+  const materials = phx.frontend.admin.useStoreSelector(
+    emission => emission.state.entities.filter(phx.domain.admin.model.CustomMaterial.is),
+    []
+  )
+  const select = phx.frontend.admin.useSelectEntity()
+
+  return (
+    <ul>
+      {materials.map(material => (
+        <li key={material.id}>
+          <button onClick={() => select(material.id)}>{material.name}</button>
+        </li>
+      ))}
+    </ul>
+  )
+})
+```
 
-  // Create sidebar for editing entities
-  attachAdminComponent
-    .withEntity('CustomMaterial')
-    .withComponent(adminSidebarComponent, 'customMaterialsSidebar')
-    .withGradualFilter({
-      navigationStates: [ApplicationTypes.AdminNavigationState.Other],
-      selectedEntityIds: s => [s.id],
-    })
-    .attach(
-      memoEval(
-        s => [s.id],
-        id => ({
-          title: 'Edit Material',
-          page: <MaterialSidebar id={id} />,
-        })
-      )
-    ),
+```tsx
+// src/admin/elements/MaterialSidebar.tsx
+import { TextValueInput } from '@salsita-ai/sdk/react'
 
-  // Create navigation panel with menu items
-  attachAdminComponent
-    .withEntity('Admin')
-    .withComponent(navigationPanelListComponent, 'main')
-    .attach(
-      memoEval(
-        () => [],
-        () => ({
-          items: [
-            ...commonPages, // Include built-in pages
-            {
-              label: 'Materials',
-              icon: 'PaletteBold',
-              navigationStates: [ApplicationTypes.AdminNavigationState.Other],
-            },
-          ],
-        })
-      )
-    ),
-]
+export default phx.frontend.createCustomPhoenixEntityElement('MaterialSidebar', ({ entityId }) => (
+  <TextValueInput entityId={entityId} instanceName="name" label="Name" />
+))
 ```
 
+`MaterialActions` is a layout element like `MaterialsPage`. The Catalog Builder demo (`packages/demos/demo-catalog-builder/src/admin/elements/`) has complete pages, actions and sidebars.
+
 ### Navigation Component Types
 
 - **`navigationPageComponent`**: Creates full pages with title, breadcrumbs, content, and actions
 - **`adminSidebarComponent`**: Creates sidebars for editing selected entities
 - **`navigationPanelListComponent`**: Creates the main navigation menu with items and icons
-- **`createAdminPages`**: Generates common admin functionality for presets and recipes
+- **`$adminPages`**: Generates these components for presets, recipes and custom pages; attach them yourself with `phx.domain.admin.attachComponent` only for a page the section does not describe
 
 ### Optional Admin Modules
 
-The `createAdminPages` function provides optional built-in modules:
+The `$adminPages` section provides optional built-in modules:
 
 **Presets Module**: Allows admins to create and manage preset configurations that users can select as starting points in the configurator. Presets can be organized into categories and include thumbnails, descriptions, and predefined entity configurations. Each preset also accepts free-form `tags` that the host can filter on at runtime via the `presetTags` WC attribute — see [Preset Tags](?path=/docs/phoenix-integration-preset-tags-external--docs).
 
 **Recipes Module**: Enables admins to define recipes that control how entities are created and configured. Recipes can be organized into collections (like "Hoods" and "Modules") and define the logic for automatically generating complex entity structures.
 
-Both modules are entirely optional - you can use one, both, or neither depending on your admin needs. If you don't need preset management or recipe functionality, simply omit them from the `createAdminPages` configuration or don't call the function at all.
+Both modules are entirely optional - you can use one, both, or neither depending on your admin needs. If you don't need preset management or recipe functionality, simply omit `presets` or `recipes` from `$adminPages`.
 
 ## Publishing Workflow
 
@@ -408,20 +361,24 @@ Presets, recipes, and swatch options are published automatically - no custom map
 
 ### Webhook Integration
 
-Include admin finalize in your webhook setup:
+Admin finalization needs nothing in your webhook entry: the SDK builds it and adds it to the webhook itself, so `phx.webhooks` has no builder for it. The entry, the default export of `src/webhooks/index.ts`, registers only the project's own hooks:
 
 ```typescript
 // src/webhooks/index.ts
-export const handler = webhookBuilder
+import { authHandler } from './handlers/auth-handler.js'
+import { configuratorFinalizeHandler } from './handlers/configurator-finalize-handler.js'
+
+export default phx.webhooks.webhookBuilder
   .withAuthHook(authHandler)
-  .withAdminFinalize(adminFinalizeHandler)
   .withConfiguratorFinalize(configuratorFinalizeHandler)
   .build()
 ```
 
+You customize publishing only with handlers default-exported from files in `src/handlers/`, which join the webhook automatically: `phx.domain.admin.createMapPublishedRevisionDataHandler` or `phx.domain.admin.createMapPublishedChunkedDataHandler` for the published data, and `phx.domain.admin.createDataRowValidatorHandler` and `phx.domain.admin.createSheetValidatorHandler` for validating manual and connected data.
+
 The publishing workflow validates admin state, transforms entities, and stores JSON to S3. Configurators access published data via `ctx.publishedData` in expressions.
 
-For implementation examples, see `packages/demos/demo-catalog-builder/src/handlers/map-published-chunked-data.ts`.
+For chunked publishing, the chunked mapping handler and access scopes, see [Publishing](?path=/docs/phoenix-publishing--docs).
 
 For technical details about data transformation and storage, see [Data Sources - Published Data](?path=/docs/phoenix-data-sources--docs#published-data).
 
@@ -432,13 +389,26 @@ Admin functionality is part of the same application as the configurator and need
 ### Registering Admin Components
 
 The frontend entry is generated into `.phoenix/`, so a project never calls the configurator builder itself. Every file
-in `src/admin/components/` is picked up by its location and its default export is registered as admin components:
+in `src/admin/components/` is picked up by its location and its default export is registered as admin components. This
+one adds a Settings item beside the navigation menu that `$adminPages` generates:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-// ... customAdminOptics as defined in the example above
+import { memoEval, navigationPanelListComponent } from '@salsita-ai/sdk/domain'
 
-export default customAdminOptics
+export default [
+  phx.domain.admin.attachComponent
+    .withEntity('Admin')
+    .withComponent(navigationPanelListComponent, 'settings')
+    .attach(
+      memoEval(
+        () => [],
+        () => ({
+          items: [{ label: 'Settings', navigationStates: ['Settings'] }],
+        })
+      )
+    ),
+]
 ```
 
 The page shown to a user who is not authenticated is an element. Create it with
@@ -449,7 +419,7 @@ The page shown to a user who is not authenticated is an element. Create it with
 Phoenix automatically provides admin functionality when:
 
 1. Admin components are default-exported from files in `src/admin/components/`
-2. Admin configuration exists in `phoenix.config.ts`
+2. Admin spec files marked with `$admin: true` exist, so phx-cli generates the admin configuration
 3. User has admin session token
 
 ### Web Component Mode Property
@@ -493,10 +463,11 @@ Phoenix's admin system enables sophisticated content management that scales with
 
 Ready to implement admin functionality in your Phoenix project? Here's what to explore next:
 
-- **[Domain Model](./Domain%20Model.mdx)** - Learn how to create admin domain models with the `$admin: true` flag
-- **[Components](./Components.mdx)** - Build admin UI components using Phoenix's component system
-- **[Deployments](./Deployments.mdx)** - Configure admin applications in your Phoenix deployment
-- **[Webhooks](./Webhooks.mdx)** - Set up admin finalize handlers for publishing workflows
+- **[Domain Model](?path=/docs/phoenix-domain-model--docs)** - Learn how to create admin domain models with the `$admin: true` flag
+- **[Components](?path=/docs/phoenix-components--docs)** - Build admin UI components using Phoenix's component system
+- **[Deployments](?path=/docs/phoenix-deployments--docs)** - Configure admin applications in your Phoenix deployment
+- **[Publishing](?path=/docs/phoenix-publishing--docs)** - Map admin entities into published data, split it into chunks and scope access to it
+- **[Webhooks](?path=/docs/phoenix-webhooks--docs)** - Set up the webhook entry with authentication and finalization hooks
 - **[Sessions and Access](?path=/docs/phoenix-sessions-and-access--docs)** - Understand admin authentication and permissions
 - **[Connected Data Sources](?path=/docs/phoenix-connected-data-sources--docs)** - Wire `$data` entries to Google Sheets or Excel; requires the embedded admin mode