@salsita-ai/sdk 0.50.0-develop.801a817d3f → 0.50.0-develop.9267bdc12e

package/dist/docs/layouts/custom-price.mdx

@@ -78,24 +78,22 @@ Your custom component has full access to the Material-UI theme and SDK utilities
 
 ### Step 3: Attach the component to your entity
 
-Use the configurator builder to attach your custom price component to the root entity:
+Attach your custom price component to the root entity in a file under `src/components/`. The generated code picks the
+file up by its location and registers its default export:
 
 ```typescript
-const config = configuratorBuilder
-  .withComponentOptics([
-    attachComponent
-      .withEntity('Scene')
-      .withComponent(customPriceFooterComponent, 'default')
-      .attach(
-        memoEval(
-          (s) => [s.$price],
-          (price) => ({
-            node: <AppPrice price={price} />,
-          })
-        )
-      ),
-  ])
-  .buildConfig()
+// src/components/custom-price.tsx
+export default phx.domain.attachComponent
+  .withEntity('Scene')
+  .withComponent(customPriceFooterComponent, 'default')
+  .attach(
+    memoEval(
+      (s) => [s.$price],
+      (price) => ({
+        node: <AppPrice price={price} />,
+      })
+    )
+  )
 ```
 
 The `memoEval` function takes two arguments:

package/dist/docs/layouts/sidebar/tabs.mdx

@@ -179,27 +179,30 @@ When a selected entity has no `sidebarTabs`, its property pages replace the root
 You can use transformers to automatically navigate to specific tabs when entities are selected or deselected:
 
 ```typescript
-const config = configuratorBuilder
-  .withTransformers(ctx => {
-    return [
-      // Navigate to BuckyBall's first tab when selected
-      phx.frontend.transformerBuilder.when
-        .entity(['BuckyBall'])
-        .selected()
-        .then.navigateTo('BuckyBallTab1')
-        .build('Navigate to BuckyBallTab1')
-        .register(ctx),
-
-      // Return to global tab1 when BuckyBall is deselected
-      phx.frontend.transformerBuilder.when
-        .entity(['BuckyBall'])
-        .deselected()
-        .then.navigateTo('tab1')
-        .build('Navigate to Tab1')
-        .register(ctx),
-    ]
-  })
-  .buildConfig()
+// src/transformers/bucky-ball-tab.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['BuckyBall'])
+  .selected()
+  .then.navigateTo('BuckyBallTab1')
+  .build('buckyBallTab')
+```
+
+```typescript
+// src/transformers/tab.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['BuckyBall'])
+  .deselected()
+  .then.navigateTo('tab1')
+  .build('tab')
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: buckyBallTab
+  - name: tab
 ```
 
 This creates smooth navigation flows where selecting specific entities automatically switches to their relevant tabs, and deselecting returns to a default tab state.

package/dist/docs/other-features/domain-actions.mdx

@@ -83,7 +83,7 @@ export default phx.domain.implementActions({
 })
 ```
 
-Throw to reject a call: the message reaches the user through the control's hint and the assistant through the failed mutation, so say what went wrong and what to send instead. An action declared without an implementation, or an implementation of a name the spec does not declare, is a type error. A declared action without an implementation also stops the domain from initializing, and under `phoenix dev` the editor reports it as a `MISSING_ACTION_IMPLEMENTATIONS` diagnostic and does not apply the change; an implementation of an undeclared name is logged.
+Throw to reject a call: the message reaches the user through the control's hint and the assistant through the failed mutation, so say what went wrong and what to send instead. An implementation of a name the spec does not declare is a type error. A declared action without an implementation is not: it stops the domain from initializing, and under `phoenix dev` the editor reports it as a `MISSING_ACTION_IMPLEMENTATIONS` diagnostic and does not apply the change; an implementation of an undeclared name is logged.
 
 ## Run it from the UI
 

package/dist/docs/other-features/side-effects.mdx

@@ -32,17 +32,14 @@ finishNotAvailable:
 ```
 
 ```ts
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Plate: {
-        finishNotAvailable: s => {
-          return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+// src/invariants/invariants.ts
+export default phx.domain.implementCustomInvariants({
+  Plate: {
+    finishNotAvailable: s => {
+      return availableMaterials.some(state => state.material === s.material && state.finish === s.finish)
+    },
+  },
+})
 ```
 
 With following control structure. The top input selects the material, the bottom one selects the finish.
@@ -66,48 +63,59 @@ With following control structure. The top input selects the material, the bottom
 The transformer is used to change the finish if necessary and show the notification.
 
 ```typescript
-configuratorBuilder
-  .withTransformers(domainContext => [
-    phx.frontend.transformerBuilder.when
-      .entity(['Plate'])
-      .modified({ atFields: ['material'] })
-      .causes.self.violation(['finishNotAvailable'])
-      .then.applySideEffect(({ update, getOld$Entity }) => {
-        const oldPlate = getOld$Entity()
-        const newMaterial = update.stateDelta.material
-
-        const validMaterial =
-          availableMaterials.find(m => m.material === newMaterial && m.finish === oldPlate.finish) ??
-          availableMaterials.find(m => m.material === newMaterial)
-
-        if (!validMaterial || validMaterial.finish === oldPlate.finish) {
-          return []
-        }
-
-        // create an additional update that will fix the material finish
-        const fixUpdate = phx.frontend.updates.DomainEntityModification({
-          entityId: oldPlate.id,
-          stateDelta: {
-            finish: validMaterial.finish,
-          },
-          updateTag: 'fix.finish',
-          hint: msg`Material finish was adjusted`, // specify a hint for the user (side effect)
-        })
-
-        return [fixUpdate]
-      })
-      .build('Fix material finish')
-      .register(domainContext),
-  ])
-  .buildConfig()
+// src/transformers/fix-finish.ts
+import { msg } from '@lingui/core/macro'
+
+import { availableMaterials } from '../_shared/materials.js'
+
+export default phx.frontend.transformerBuilder.when
+  .entity(['Plate'])
+  .modified({ atFields: ['material'] })
+  .causes.self.violation(['finishNotAvailable'])
+  .then.applySideEffect(({ update, getOld$Entity }) => {
+    const oldPlate = getOld$Entity()
+    const newMaterial = update.stateDelta.material
+
+    const validMaterial =
+      availableMaterials.find(m => m.material === newMaterial && m.finish === oldPlate.finish) ??
+      availableMaterials.find(m => m.material === newMaterial)
+
+    if (!validMaterial || validMaterial.finish === oldPlate.finish) {
+      return []
+    }
+
+    // create an additional update that will fix the material finish
+    const fixUpdate = phx.frontend.updates.DomainEntityModification({
+      entityId: oldPlate.id,
+      stateDelta: {
+        finish: validMaterial.finish,
+      },
+      updateTag: 'fix.finish',
+      hint: msg`Material finish was adjusted`, // specify a hint for the user (side effect)
+    })
+
+    return [fixUpdate]
+  })
+  .build('fix-finish')
+```
+
+Each file in `src/transformers/` default-exports one transformer and is picked up by its location. The `transformers` section of the spec turns it on by name. For a transformer made with `build(name)` that is the name passed to `build(...)`, which must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). For a plain-function export it is the file name:
+
+```yaml
+# spec/application.yaml
+transformers:
+  - name: fix-finish
 ```
 
 ### Hints and the AI assistant
 
 In a configurator with the AI assistant, the assistant is told the same hints: they arrive as
 `sideEffects` with the result of its changes and in the dry-runs of recipes and options, so it can
-tell the user what else happened. Set `agentHint` beside `hint` when the assistant needs different
-wording, for example with ids or values a snackbar would not show:
+tell the user what else happened. The hints also explain what the user changed between two messages:
+every message carries a change record of the configuration, and each of its lines ends with the hint
+of the last update that touched it, or with the `updateTag` when the update has none. Set `agentHint`
+beside `hint` when the assistant needs different wording, for example with ids or values a snackbar
+would not show:
 
 ```ts
 phx.frontend.updates.DomainEntityModification({
@@ -120,7 +128,9 @@ phx.frontend.updates.DomainEntityModification({
 ```
 
 - `agentHint` is a plain string, never shown to the user and not localized.
-- `agentHint: null` keeps the update from the assistant while the user still gets the `hint`.
+- `agentHint: null` keeps the wording from the assistant while the user still gets the `hint`: the
+  update is left out of `sideEffects`, and the change record explains its line by the `updateTag`. It
+  does not hide the change itself, which the assistant can always read from the configuration.
 - `agentHint` without a `hint` tells only the assistant.
 
 ## Example

package/dist/docs/other-features/transformers.mdx

@@ -102,7 +102,7 @@ export const removeExtraneousBranchesAndLeavesWhenShortened = phx.frontend.trans
     - With `overrideMatchinUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace the original **matched update**. This will be triggered for every matching update. Note that this action is not available in events which are not bound to a specific update - such as a violation check without a defined cause.
     - With `overrideAllUpdates(ctx => /* side effect updates */)` the updates returned by the provided callback will replace all original updates. This will be triggered only once for a single run of the transformer. This allows for implementation of transformers that behave similarly as the raw `UpdateTransformer`
   - High-level actions: `select`, `deselect`, `navigate`, `changeView` - more on these in the other examples.
-- `build(name)` is the final step to create the transformer. Assign a descriptive name (no restrictions) to easily identify the transformer while tracing. Note that this returns a `RegistrableTransformer` which needs to be registered using the `register(domainContext)` method. This is usually done in the `.withTransformers()` method of the configurator builder.
+- `build(name)` is the final step to create the transformer. The name identifies the transformer while tracing, and it is the name the `transformers` section of the spec refers to, so it must match the file name with case and dashes ignored (`fix-finish.ts` and `fixFinish` match). Note that this returns a `RegistrableTransformer`. Default-export it from a file in `src/transformers/` and list the name passed to `build(...)` in the `transformers` section of the spec; the generated code registers it. The shorter snippets on this page use descriptive names for readability; the complete implementation below uses names that match its files.
 
 ### Side-Effect on Update Causing Another Entity's Violation
 

package/dist/docs/other-features/violation-messages.mdx

@@ -153,10 +153,10 @@ The `formatControlViolationMessage` function is where the magic happens. It rece
 3. **Actionable guidance**: Tell users exactly what values are valid or how to fix the problem
 4. **Consistent terminology**: Use the same terms and units throughout your application
 
-Implement violations with custom message formatting in your domain TypeScript file:
+Implement violations with custom message formatting in a file of `src/invariants/`:
 
 ```typescript
-// domain/index.ts
+// src/invariants/invariants.ts
 
 // Pre-define translatable labels for nested localization
 const colorLabels = {
@@ -166,60 +166,56 @@ const colorLabels = {
   yellow: msg`yellow`,
 } as const
 
-const violationExpressions = invariantBuilder
-  .withInvariants(
-    implementCustomInvariants({
-      Scene: {
-        itIsNotZero: s => {
-          if (s.x !== 0) {
-            return [
-              {
-                type: 'itIsNotZero',
-                severity: 'fatal',
-                message: 'Scene is not zero',
-                controlViolationPriority: 1,
-                formatControlViolationMessage: () => {
-                  return msg({
-                    message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
-                  })
-                },
-              },
-            ]
-          }
-          return []
-        },
-        // ... tooMuchRight omitted for brevity ...
-
-        // Static violation: severity, message and controlViolationPriority
-        // are declared in YAML. Implementation only returns a boolean.
-        wayTooFarRight: s => s.x < 200,
-
-        colorPositionIncompatible: s => {
-          const compatibleColors = ['red', 'blue', 'green'] as const
-          if (s.x >= 200 && !compatibleColors.includes(s.color)) {
-            return [
-              {
-                type: 'colorPositionIncompatible',
-                severity: 'fatal',
-                message: 'Color is not compatible with far right position',
-                controlViolationPriority: 3,
-                formatControlViolationMessage: (_emission, { i18n }) => {
-                  const labels = new Intl.ListFormat(i18n.locale, {
-                    style: 'long',
-                    type: 'disjunction',
-                  }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
-
-                  return msg({ message: `Far right position is only available for ${labels}` })
-                },
-              },
-            ]
-          }
-          return []
-        },
-      },
-    })
-  )
-  .buildViolationExpressions()
+export default phx.domain.implementCustomInvariants({
+  Buckyball: {
+    itIsNotZero: s => {
+      if (s.x !== 0) {
+        return [
+          {
+            type: 'itIsNotZero',
+            severity: 'fatal',
+            message: 'Scene is not zero',
+            controlViolationPriority: 1,
+            formatControlViolationMessage: () => {
+              return msg({
+                message: `Scene is not zero: The position would be ${s.x} which is not equal to 0`,
+              })
+            },
+          },
+        ]
+      }
+      return []
+    },
+    // ... tooMuchRight omitted for brevity ...
+
+    // Static violation: severity, message and controlViolationPriority
+    // are declared in YAML. Implementation only returns a boolean.
+    wayTooFarRight: s => s.x < 200,
+
+    colorPositionIncompatible: s => {
+      const compatibleColors = ['red', 'blue', 'green'] as const
+      if (s.x >= 200 && !compatibleColors.includes(s.color)) {
+        return [
+          {
+            type: 'colorPositionIncompatible',
+            severity: 'fatal',
+            message: 'Color is not compatible with far right position',
+            controlViolationPriority: 3,
+            formatControlViolationMessage: (_emission, { i18n }) => {
+              const labels = new Intl.ListFormat(i18n.locale, {
+                style: 'long',
+                type: 'disjunction',
+              }).format(compatibleColors.map(c => i18n.t(colorLabels[c])))
+
+              return msg({ message: `Far right position is only available for ${labels}` })
+            },
+          },
+        ]
+      }
+      return []
+    },
+  },
+})
 ```
 
 ### Internationalization with Dynamic Content

package/dist/docs/phoenix/admin.mdx

@@ -427,43 +427,28 @@ For technical details about data transformation and storage, see [Data Sources -
 
 ## Web Component Integration
 
-Admin functionality integrates through the configurator builder rather than requiring separate web component setup.
+Admin functionality is part of the same application as the configurator and needs no separate web component setup.
 
-### Configurator Builder Setup
+### Registering Admin Components
 
-In phx-cli projects, frontend entry is auto-generated in `.phoenix/`. Admin components are registered through `src/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:
 
 ```typescript
 // src/admin/components/admin-components.tsx
-import { configuratorBuilder } from '.phoenix/frontend.js'
-import { customAdminOptics } from './optics.js'
-import { NotAuthenticatedPage } from '../pages/NotAuthenticatedPage.js'
-
-const config = configuratorBuilder
-  .withComponentOptics(customConfiguratorComponents)
-  .withAdminComponentOptics(customAdminOptics) // Register admin components
-  .buildConfig({
-    deploymentId: phx.runtimeConfig.DEPLOYMENT_ID,
-    persistence: {
-      type: 'server',
-      serverUrl: phx.runtimeConfig.SERVER_URL,
-    },
-    ui: {
-      notAuthenticatedPage: <NotAuthenticatedPage />, // Show when user not authenticated
-    },
-    // ... other config
-  })
+// ... customAdminOptics as defined in the example above
 
-phx.frontend.mountApplication(config)
+export default customAdminOptics
 ```
 
-Admin component files go in `src/admin/components/` and are automatically discovered by phx-cli.
+The page shown to a user who is not authenticated is an element. Create it with
+`phx.frontend.createNotAuthenticatedPage(...)` in a file under `src/elements/`.
 
 ### Built-in Admin Integration
 
 Phoenix automatically provides admin functionality when:
 
-1. Admin components are registered via `withAdminComponentOptics()`
+1. Admin components are default-exported from files in `src/admin/components/`
 2. Admin configuration exists in `phoenix.config.ts`
 3. User has admin session token