@salsita-ai/sdk 0.50.0-develop.ae9a830ef0 → 0.50.0-develop.afbc5157e1

package/dist/docs/phoenix/sessions-and-access.mdx

@@ -169,8 +169,8 @@ Each handler returns _session data_, _role information_, and _token metadata_ th
 Once authentication succeeds:
 
 - Phoenix **stores session and refresh tokens**
-- Session determines user's **role** (admin, user, or anonymous)
-- Admin users receive an **additional admin session token** for accessing the Admin application
+- Session determines user's **role** (superadmin, admin, user, or anonymous)
+- Admin and superadmin users receive an **additional admin session token** for accessing the Admin application
 - Users can now access _general pages_ like presets and deployments
 
 ### 4. Configuration Access Validation
@@ -194,8 +194,8 @@ Finally, Phoenix creates an **authorized API client** that:
 
 Authentication logic is implemented through **webhook handlers** when the deployment is configured with **`useAuthHook: true`**. These handlers:
 
-- **Run in AWS Lambda** - Serverless execution environment
-- **Control user roles** - Determine admin, user, or anonymous access
+- **Run in AWS Lambda** - Serverless execution environment; under `phoenix dev` they run on the developer's machine through the development webhook tunnel
+- **Control user roles** - Determine superadmin, admin, user, or anonymous access
 - **Generate session data** - Custom data attached to user sessions
 - **Manage token generation** - Control session and refresh token creation
 
@@ -210,7 +210,7 @@ useAuthHook: true # Enable webhook authentication
 useClerk: true # Enables Clerk + sets useAuthHook automatically
 ```
 
-Webhook handlers are implemented in `src/webhooks/index.ts`. The builders and type definitions are auto-generated in `.phoenix/webhooks/builders.ts` based on your spec configuration.
+The webhook entry is the default export of `src/webhooks/index.ts`. The builders and their types are generated from your spec configuration into `.phoenix/webhook-builders.ts`, which sets the `phx.webhooks` global, so project code never imports builders from `.phoenix/`.
 
 The auth handler builder provides a fluent API for configuring authentication methods. You can combine multiple handlers to support different authentication scenarios. The builder is accessed through the `phx.webhooks` global namespace:
 
@@ -240,22 +240,37 @@ For custom third-party integrations (not SSO - use Clerk handlers for that), you
 ```typescript
 // src/webhooks/index.ts
 const authHandler = phx.webhooks.authHandlerBuilder
-  .withCodeHandler(async (payload, ctx) => {
-    const { code, accessToken, idToken } = payload
-    // Server retrieves tokens from Redis and passes them to webhook
+  .withCodeHandler(async ({ accessToken }, { logger }) => {
+    // The platform already redeemed the one-time code, so the payload holds
+    // { type: 'code', accessToken, refreshToken?, idToken? } and no code.
+    // PARTNER_API_URL is declared under `env.webhook` in a spec file
+    const response = await fetch(`${phx.webhooksEnv.PARTNER_API_URL}/me`, {
+      headers: { authorization: `Bearer ${accessToken}` },
+    })
+
+    if (!response.ok) {
+      logger.warn(`The partner API refused the access token with status ${response.status}.`)
+
+      return { success: false }
+    }
 
-    // Process third-party integration data
-    const userData = await processThirdPartyData(accessToken, idToken)
+    const userData: {
+      readonly id: string
+      readonly email: string
+      readonly permissions: string[]
+      readonly isAdmin: boolean
+    } = await response.json()
 
     return {
       success: true,
       data: {
-        userId: userData.id,
         email: userData.email,
         tags: userData.permissions,
       },
-      role: determineRole(userData),
-      refreshToken: await generateRefreshToken(userData),
+      role: userData.isAdmin ? 'admin' : 'user',
+      // The session user, a top-level field rather than part of the session data
+      userId: userData.id,
+      // An absolute Unix timestamp in seconds; three hours from now when omitted
       expirationTime: Math.floor(Date.now() / 1000) + 3600,
     }
   })
@@ -263,7 +278,6 @@ const authHandler = phx.webhooks.authHandlerBuilder
     return {
       success: true,
       data: {
-        userId: 'anonymous',
         tags: [],
       },
       role: 'anonymous',
@@ -275,7 +289,7 @@ const authHandler = phx.webhooks.authHandlerBuilder
 export default phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
 ```
 
-Each handler receives the authentication payload and returns session data, user role, and token metadata. The session data you return becomes available throughout the application and can include any custom fields defined in your domain's SessionData type.
+Each handler receives the authentication payload and returns session data, user role, and token metadata. A handler refuses the session with `{ success: false }`; log the reason with the `logger`, because the response carries no error message. The session data you return becomes available throughout the application and can include any custom fields declared in the spec's `sessionData` schema, which declares no required properties.
 
 Phoenix supports several types of authentication handlers:
 
@@ -305,17 +319,9 @@ To enable Clerk authentication:
 useClerk: true # Enables Clerk auth and sets useAuthHook automatically
 ```
 
-**2. Set environment variables** (defined in your project's `.env` file):
-
-```bash
-CLERK_SECRET_KEY=sk_...
-JWT_SECRET_BASE64=...
-OAUTH_PROVIDER_BASE_URL=https://...
-OAUTH_PROVIDER_CLIENT_ID=...
-OAUTH_PROVIDER_CLIENT_SECRET=...
-```
+**2. Configure Clerk for the workspace in Studio.** The Clerk credentials come from the workspace's Clerk settings in Studio and reach the webhook as generated variables (`CLERK_API_KEY`, `JWT_SECRET_BASE64`, `OAUTH_PROVIDER_CLIENT_ID`, `OAUTH_PROVIDER_CLIENT_SECRET`, `OAUTH_PROVIDER_BASE_URL`, `FRONTEND_URL` and `RESOURCES_URL`). The project neither declares them nor keeps them in its `.env`. See [Clerk Sign-In](?path=/docs/phoenix-clerk-sign-in--docs).
 
-**3. Use Clerk handlers** in your webhook (the builder is auto-generated in `.phoenix/webhooks/builders.ts`):
+**3. Use Clerk handlers** in your webhook (`phx.webhooks` is set by the generated `.phoenix/webhook-builders.ts`):
 
 ```typescript
 // src/webhooks/index.ts
@@ -427,6 +433,8 @@ The `readonly` web component property lets the host force view mode without chan
 
 Because an owner-token session can be forced read-only client-side while the server still accepts writes from that owner token, Phoenix skips persistence and logs a warning instead of updating the configuration. This guards against the configuration being silently overwritten by code paths that mutate state in read-only mode. UI that triggers significant changes (anything that produces a new revision) should still be disabled when `accessInfo.viewMode` is true — the warning is a backstop, not a substitute.
 
+The assistant follows the same read-only rule as the UI: its `apply` tool refuses changes while `accessInfo.viewMode` is true, that is with a read-revision token or while `readonly` is set, and makes them again once it is false. A switch of `readonly` takes effect at once, in both directions, and the configurator loads the configuration again. A change applied after `readonly` is cleared and before the configuration has loaded again is not saved; saving resumes once it has loaded. The `query` tool keeps working, including its dry-run mutations.
+
 ```html
 <salsita-configurator readonly></salsita-configurator>
 ```
@@ -491,24 +499,36 @@ Use custom code handlers for third-party integrations. The server handles Redis
 ```typescript
 // src/webhooks/index.ts
 const authHandler = phx.webhooks.authHandlerBuilder
-  .withCodeHandler(async (payload, ctx) => {
-    const { code, accessToken, idToken } = payload
+  .withCodeHandler(async ({ accessToken }, { logger }) => {
     // Server already retrieved tokens from Redis and passed them here
 
-    // Verify and process third-party tokens
-    const integrationUser = await thirdPartyAPI.validateToken(accessToken)
+    // Verify the third-party token; INTEGRATION_API_URL is declared under `env.webhook` in a spec file
+    const response = await fetch(`${phx.webhooksEnv.INTEGRATION_API_URL}/tokens/verify`, {
+      headers: { authorization: `Bearer ${accessToken}` },
+    })
+
+    if (!response.ok) {
+      logger.warn(`The integration rejected the access token with status ${response.status}.`)
+
+      return { success: false }
+    }
+
+    const integrationUser: {
+      readonly id: string
+      readonly email: string
+      readonly permissions?: string[]
+      readonly isAdmin: boolean
+    } = await response.json()
 
     // Map third-party data to Phoenix session
     return {
       success: true,
       data: {
-        userId: integrationUser.id,
         email: integrationUser.email,
-        customData: integrationUser.metadata,
-        tags: integrationUser.permissions || [],
+        tags: integrationUser.permissions ?? [],
       },
-      role: determineRoleFromIntegration(integrationUser),
-      refreshToken: await generateRefreshToken(integrationUser),
+      role: integrationUser.isAdmin ? 'admin' : 'user',
+      userId: integrationUser.id,
       expirationTime: Math.floor(Date.now() / 1000) + 3600,
     }
   })

package/dist/docs/phoenix/sharing.mdx

@@ -240,7 +240,7 @@ env:
 
 ```ts
 export const linkTasks = phx.webhooks.taskFactory.createGenerateConfigurationLinkTask((resources, data) => {
-  const frontendUrl = phx.runtimeConfig.CUSTOM_FRONTEND_URL ?? data.frontendUrl
+  const frontendUrl = phx.webhooksEnv.CUSTOM_FRONTEND_URL ?? data.frontendUrl
 
   return [
     {

package/dist/docs/phoenix/state-management.mdx

@@ -315,14 +315,15 @@ const update = phx.frontend.updates.DomainEntityModification({
   updateTag: 'UserResizing',
 })
 
-// Component modification
+// Component modification (distanceDimensionComponent from '@salsita-ai/sdk/domain')
 const componentUpdate = phx.frontend.updates.ComponentModification({
   componentInstance: {
     entityId: 'Cabinet-1',
-    componentType: selectionComponent,
-    instanceName: 'main',
+    componentType: distanceDimensionComponent,
+    instanceName: 'width',
   },
-  writableState: { selected: true },
+  writableState: { value: 1200 },
+  updateTag: 'UserResizing',
 })
 ```
 
@@ -356,7 +357,7 @@ storeSystem.commit()
 
 During commitment:
 
-- OnBeforeCommit hooks can intercept or modify the commit
+- `onBeforeCommit` hooks can hold the commit by returning `false`, for example to ask the user first; a held commit resets the rendered slice, and the hook can commit the same emission later through the `emit` callback it receives. A hook cannot change what is committed
 - Final validation occurs
 - Committed state is emitted to committed slice
 - All attempts (valid or invalid) are emitted to potentiallyInvalid slice
@@ -426,7 +427,7 @@ Validation produces structured results indicating state validity:
 type StateValidationResult =
   | { valid: true, severity: null }  // Perfect state
   | { valid: true, severity: 'warning' | 'notice', entityViolations: [...] }  // Valid with warnings
-  | { valid: false, severity: 'fatal' | 'fixable', entityViolations: [...] }  // Invalid but recoverable
+  | { valid: false, severity: 'fatal' | 'fixable', entityViolations: [...] }  // Invalid, never committed
   | { valid: false, severity: 'uncaught', error: Error }  // Critical error
 ```
 
@@ -434,7 +435,7 @@ type StateValidationResult =
 
 Different violation severities have different behavioral impacts:
 
-**Notice**: Informational only, doesn't affect functionality
+**Notice**: Informational only: the change is committed and saved, and nothing is blocked
 
 ```typescript
 // Example: Suggesting better material combinations
@@ -445,7 +446,7 @@ Different violation severities have different behavioral impacts:
 }
 ```
 
-**Warning**: Alerts user but allows operation
+**Warning**: The change is committed and saved, but the configuration cannot be finalized
 
 ```typescript
 // Example: Performance warnings
@@ -456,18 +457,18 @@ Different violation severities have different behavioral impacts:
 }
 ```
 
-**Fixable**: Prevents some actions but can be auto-corrected
+**Fixable**: Rejected like `fatal`; marks a violation that a project [transformer](?path=/docs/other-features-transformers--docs) repairs before validation. Nothing corrects it automatically: without such a transformer the change is not committed.
 
 ```typescript
 // Example: Dimension constraints
 {
   type: 'dimensionTooLarge',
   severity: 'fixable',
-  message: 'Cabinet width exceeds room width, adjusting automatically'
+  message: 'Cabinet width exceeds room width'
 }
 ```
 
-**Fatal**: Prevents finalization and major operations
+**Fatal**: The change is never committed: it does not reach the rendered state, the undo stack or the saved configuration
 
 ```typescript
 // Example: Critical business rules
@@ -488,8 +489,8 @@ const emission = storeSystem.stage(updates)
 if (emission.validity.valid) {
   // State is valid, can be rendered
   renderState(emission.state)
-} else if (emission.validity.severity === 'fatal') {
-  // Fatal errors prevent rendering updates
+} else if (emission.validity.severity === 'fatal' || emission.validity.severity === 'fixable') {
+  // The change is rejected: the rendered slice keeps the last valid state
   showErrors(emission.validity.entityViolations)
 }
 
@@ -552,9 +553,10 @@ Phoenix uses `useSyncExternalStore` to efficiently synchronize store state with
 // Select specific entities
 const cabinets = phx.frontend.useStoreSelector(state => state.state.entities.filter(e => e.type === 'Cabinet'), [])
 
-// Select computed values with dependencies
-const totalPrice = phx.frontend.useStoreSelector(
-  state => state.state.entities.filter(e => e.type === 'Cabinet').reduce((sum, cabinet) => sum + cabinet.$price, 0),
+// Select computed values: `state.state.entities` holds raw entities without `$` fields,
+// so read expressions and relations from an enhanced entity, here the root `Room`
+const totalPrice = phx.frontend.useRootEntitySelector(
+  room => room.$cabinets.reduce((sum, cabinet) => sum + cabinet.$price, 0),
   []
 )
 

package/dist/docs/phoenix/testing.mdx

@@ -33,6 +33,19 @@ invariants, actions, migrations, presets and the components declared in YAML. `c
 handler, element and transformer; it reads the frontend environment when it is imported, so a test that
 uses it stubs `phx.frontendEnv` first.
 
+A test that mounts the configurator's UI builds from `configuratorConfig`: it carries the SDK's default
+elements, the built-in layout, preset screen, not-found, not-authenticated and error pages, app loader content,
+controls, toolbar buttons and sidebar-footer pieces, which `configuratorBuilder` does not, so a test that mounts the UI from `createTestApplicationConfig(configuratorBuilder)`
+shows a "not found" box in place of every built-in element. The defaults also hold the configurator's
+visual providers and the error page and dialog its runtime renders, and a config without them runs the
+lifecycle without them, with a plain error message in place of the error page. Without them nothing
+provides the responsive context, so an SDK layout slot that reads it, for example
+`LayoutSlots.SharedCanvas`, stops the configurator with that plain error message instead of showing a
+"not found" box, and snackbar messages have no host. Code that assembles a config without the
+generated files calls `.withDefaultElements(defaultConfiguratorElements)` on its configurator builder, with
+the list from `@salsita-ai/sdk/configurator`, or `defaultAdminElements` from `@salsita-ai/sdk/admin` for
+the admin.
+
 A test passes the generated export to the helper and does not call the export's methods: they are how the
 SDK assembles an application, not an interface for tests, while the helper's call does not depend on that
 assembly.