@salsita-ai/sdk 0.0.0-stage → 0.49.0-develop.cbee856178

package/dist/docs/phoenix/integration/imperative-api-external.mdx

@@ -0,0 +1,93 @@
+# Imperative API — Integration Guide
+
+Some configurator deployments expose a custom JavaScript API that the host application can call directly — for example, to clone a configuration, trigger an export, or query internal state. The API is delivered as a regular web component property.
+
+> **Important:** The configurator does not validate arguments passed to API functions and does not prevent the host from reassigning or mutating the `api` property. Treat the API object as read-only — do not overwrite it or modify its functions. Always check for `null` before calling.
+
+## Availability
+
+The API property (typically named `api`) starts as `null` and becomes available once the configurator's session is ready. It is reset back to `null` when the configurator powers off. The host must check for availability before calling any function.
+
+### Detecting readiness
+
+Listen to the `property-changed` event to know when the API becomes available or is removed:
+
+```js
+const configurator = document.getElementById('configurator')
+
+configurator.addEventListener('property-changed', event => {
+  if (event.detail.name === 'api') {
+    if (event.detail.newValue) {
+      // API is ready — enable UI controls that depend on it
+      enableCloneButton()
+    } else {
+      // API was removed (configurator powered off) — disable controls
+      disableCloneButton()
+    }
+  }
+})
+```
+
+Alternatively, check the property directly after the configurator has powered on and the session has been established:
+
+```js
+if (configurator.api) {
+  // safe to call
+}
+```
+
+### Lifecycle
+
+| Configurator state                      | `api` value |
+| --------------------------------------- | ----------- |
+| `power="off"`                           | `null`      |
+| `power="standby"` (session not ready)   | `null`      |
+| `power="standby"` (session ready)       | API object  |
+| `power="on"` (session ready)            | API object  |
+| Session expired / authentication failed | `null`      |
+
+The API becomes available during `standby` once the session is authenticated — you don't need to wait for `power="on"`.
+
+## Calling API Functions
+
+Always check for `null` before calling. Some functions may be async — check the project-specific documentation provided during onboarding. The configurator does not validate the arguments you pass — calling a function with wrong types or missing fields will result in undefined behavior or runtime errors, not a clean validation error.
+
+```js
+if (!configurator.api) {
+  throw new Error('Configurator API is not available')
+}
+
+const result = await configurator.api.cloneConfiguration({
+  configurationId,
+  accessToken,
+})
+```
+
+## Example: Cloning a Finalized Configuration
+
+A common use case in dealer portals: the user views a finalized (read-only) configuration and wants to create a copy to make changes. The host calls `cloneConfiguration` with the finalized revision's read-only token, then opens the new configuration.
+
+```js
+async function cloneAndOpen(quote) {
+  // clone using the read-revision token to ensure we clone the finalized revision
+  const { configurationId, accessToken } = await configurator.api.cloneConfiguration({
+    configurationId: quote.configuration.configurationId,
+    accessToken: quote.readRevisionToken ?? quote.configuration.accessToken,
+  })
+
+  // create a new quote in the host system
+  const newQuote = await createQuote(`${quote.name} (copy)`)
+  await saveQuoteConfiguration(newQuote.id, { configurationId, accessToken })
+
+  // open the cloned configuration in the configurator
+  configurator.route = {
+    route: 'Configuration',
+    configurationId,
+    accessToken,
+  }
+  configurator.quoteId = newQuote.id
+  configurator.power = 'on'
+}
+```
+
+After cloning, the configurator emits a `navigated` event with the new `configurationId` and `accessToken` — the host should persist these as usual.

package/dist/docs/phoenix/integration/imperative-api-internal.mdx

@@ -0,0 +1,168 @@
+# Imperative API — Internal
+
+> The live example uses the custom tag `salsita-3d-configurator`.
+
+## Overview
+
+Headless integrations sometimes need the host to call configurator functionality programmatically — cloning a configuration, triggering an export, or querying internal state. The pattern for this is a **custom imperative API**: an object of functions published as a WC property that the host reads from the element.
+
+> **This is an advanced, low-level pattern.** Phoenix does not validate calls to the API methods — the Zod function schema only serves as documentation and TypeScript type inference. Phoenix also does not prevent the host from reassigning or mutating the property. Only use this pattern with integration partners who are technically capable and understand the risks. For simpler integrations, prefer events and declarative properties.
+
+The API property is `null` when the configurator is powered off or the session is not yet ready. It becomes available once the session is authenticated and is reset back to `null` on unmount. The host detects availability via the `property-changed` event.
+
+See also:
+
+- [WebComponent API - Basics](?path=/docs/integrations-webcomponent-api-basics--docs) — background on how custom WC properties and events work in Phoenix.
+- [Imperative API (External)](?path=/docs/phoenix-integration-imperative-api-external--docs) — share this page with the partner doing the integration.
+
+## Setup
+
+Three pieces are needed:
+
+1. Declare the API property in `web-component-api.ts`
+2. Implement and publish the API in a session-ready provider
+3. Expose the property via the `GetWebComponentOptions` handler (same as any other custom property)
+
+### 1. Declare the API property
+
+The API property is a regular WC property whose schema is an object of functions. It has no `attributeParser` or `attributeNames` — the API is JS-only, not settable via HTML attributes. The `defaultValue` is `null` so the host can check for availability.
+
+```ts
+// src/_shared/web-component-api.ts
+import { z } from 'zod'
+
+import { createWebComponentPropertyDescriptor } from '@salsita-ai/sdk/domain'
+
+export const webComponentProperties = {
+  api: createWebComponentPropertyDescriptor({
+    schema: z.object({
+      cloneConfiguration: z
+        .function()
+        .args(
+          z.object({
+            configurationId: z.string(),
+            accessToken: z.string(),
+          })
+        )
+        .returns(
+          z.promise(
+            z.object({
+              configurationId: z.string(),
+              accessToken: z.string(),
+            })
+          )
+        ),
+    }),
+    defaultValue: null,
+  }),
+}
+```
+
+The Zod function schema is **not validated at call time** — Phoenix only validates the shape of the property when it is set (i.e., that it is an object with the right function keys), not the arguments or return values of individual function calls. The `z.function().args().returns()` declarations serve purely as documentation and TypeScript type inference for the configurator's internal code.
+
+### 2. Publish the API via a session-ready provider
+
+Use `phx.frontend.createOnSessionReadyProvider` to implement a provider that publishes the API once the session is authenticated. This handler:
+
+- Runs after the session is established (the API can safely make authenticated server calls)
+- Unmounts when the configurator powers off, which triggers the cleanup that resets the property to `null`
+
+`createOnSessionReadyProvider` is used here because `cloneConfiguration` is not scoped to any particular configuration — it only needs an authenticated session. If your API needs access to configuration-specific state (e.g. the current domain state, selected entities, or computed values), mount it in a different lifecycle provider that has access to that context.
+
+```tsx
+// src/elements/SessionReadyProvider.tsx
+import { useEffect, useMemo } from 'react'
+import type { z } from 'zod'
+
+import { decodeAccessInfo, useWebComponentPropertySetter } from '@salsita-ai/sdk/react'
+
+import { webComponentProperties } from '../_shared/web-component-api.js'
+
+export default phx.frontend.createOnSessionReadyProvider(({ children }) => {
+  const setApi = useWebComponentPropertySetter(webComponentProperties.api)
+  const createAuthorizedClient = phx.frontend.useCreateAuthorizedClient()
+
+  const api = useMemo<z.infer<typeof webComponentProperties.api.schema>>(
+    () => ({
+      cloneConfiguration: async ({ configurationId, accessToken }) => {
+        const authorizedClient = createAuthorizedClient(accessToken)
+
+        const accessInfo = decodeAccessInfo(accessToken, configurationId)
+        if (!accessInfo) {
+          throw new Error('Invalid access token')
+        }
+
+        let revisionId: string
+        if (accessInfo.revisionId) {
+          revisionId = accessInfo.revisionId
+        } else {
+          const originalConfiguration = await authorizedClient.getConfiguration(configurationId)
+          revisionId = originalConfiguration.revisionId
+        }
+
+        const newConfiguration = await authorizedClient.cloneConfiguration(configurationId, revisionId)
+        return { configurationId: newConfiguration.configurationId, accessToken: newConfiguration.accessToken }
+      },
+    }),
+    [createAuthorizedClient]
+  )
+
+  useEffect(() => {
+    setApi(api)
+
+    return () => {
+      // reset the API when the component is unmounted
+      // this is important to properly support the power="off" mode
+      setApi(null)
+    }
+  }, [api, setApi])
+
+  return <>{children}</>
+})
+```
+
+Key points:
+
+- **`useWebComponentPropertySetter`** — returns a stable setter that pushes a new value into the property's BehaviorSubject. When the value changes, a `property-changed` DOM event is dispatched automatically.
+- **`useCreateAuthorizedClient`** — creates an API client scoped to a specific access token. Each call to `cloneConfiguration` may use a different token (owner vs read-revision), so the client is created per-call, not per-session.
+- **`decodeAccessInfo`** — extracts `configurationId` and optional `revisionId` from an access token JWT without server verification. Used here to determine which revision to clone.
+- **Cleanup (`setApi(null)`)** — when the configurator powers off, the provider unmounts and resets the property. The host sees a `property-changed` event with `newValue: null` and must stop calling the API. Without cleanup, the host would hold references to stale closures.
+
+### 3. Expose in GetWebComponentOptions
+
+The API property must be included in the handler like any other custom property:
+
+```ts
+// src/handlers/GetWebComponentOptions.ts
+export default phx.frontend.createGetWebComponentOptionsHandler(() => ({
+  properties: webComponentProperties,
+  events: webComponentEvents,
+}))
+```
+
+## Extending the API
+
+To add more functions, extend the Zod schema and the implementation. Functions can be sync or async depending on what they do — there's no requirement either way.
+
+```ts
+// in web-component-api.ts
+api: createWebComponentPropertyDescriptor({
+  schema: z.object({
+    cloneConfiguration: z.function()...
+    exportPdf: z.function().args(z.void()).returns(z.promise(z.string())),
+    getSummary: z.function().args(z.void()).returns(z.string()),
+  }),
+  defaultValue: null,
+}),
+```
+
+```tsx
+// in SessionReadyProvider.tsx
+const api = useMemo(() => ({
+  cloneConfiguration: async (...) => { ... },
+  exportPdf: async () => { ... },
+  getSummary: () => 'Oak table, 120x80cm, natural finish',
+}), [...])
+```
+
+All functions on the API object share the same lifecycle — they all become available when the session is ready and are all reset to `null` together on power-off.

package/dist/docs/phoenix/integration/integration-modes-external.mdx

@@ -0,0 +1,148 @@
+# Integration Modes
+
+The Salsita 3D configurator is designed to be embedded into your application or website — whether customer-facing or internal. The surrounding context might be a marketing page, a dealer portal, a B2B platform, an internal order-management tool, or a standalone site. To keep things simple, the configurator ships four integration modes that each bundle a coherent set of defaults for one of these scenarios. You pick a mode when you embed it; everything else falls into place.
+
+```html
+<salsita-configurator integration-mode="widget" />
+```
+
+The four modes are: **`page`**, **`handoff`**, **`widget`**, and **`headless`**. Each is described below from your perspective — what the user sees, what your application does, and what we set up on our side.
+
+## Quick Reference
+
+| Mode       | What it looks like                                                                                                         | Typical scenario                                                            |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `page`     | Configurator owns the whole page. Always on. Users come and go via direct URL.                                             | Standalone configurator site, or a CMS page that wraps it with your header. |
+| `handoff`  | Configurator runs on its own page; users navigate in and back, same tab.                                                   | Platform that can't embed web components (legacy CMS, strict CSP).          |
+| `widget`   | Configurator embeds as a web component, opened on demand by a host trigger (e.g. a button). Renders inline or full-screen. | Product page with a "Customize" button that opens the configurator.         |
+| `headless` | Configurator embeds as a web component; your application drives everything.                                                | B2B platform where the configurator is one view among many.                 |
+
+## The Modes
+
+### page
+
+The configurator **is** the page. Users land on a URL, configure their product, and leave when they're done. There is no surrounding application — or, if there is, it sits around the configurator (a header, a footer) rather than driving it.
+
+The configurator manages its own state. The active configuration is reflected in the URL, so users can bookmark it or refresh without losing their place. Sharing a configuration with another user uses the configurator's built-in share dialog.
+
+**Use when** the configurator is the destination — a standalone configuration site, or a page on your marketing site where the configurator is the primary content.
+
+**What your application does:** creates a page, places the configurator's web component on it, and includes our script tag. The configurator handles everything from there — no further integration code needed.
+
+> **No-integration alternative.** If you don't plan to integrate the configurator into your own pages at all, we can host the configurator page on our side and (optionally) serve it under your own domain via DNS. Under the hood this still uses `page` mode, but there is nothing to integrate on your side — point us at a domain and we deliver a working URL. The trade-off: the page is **just the configurator** — there's no way to add your own header, footer, navigation, or other markup around it. If you need any surrounding content of your own, host the page yourself and embed the web component.
+
+### handoff
+
+The configurator runs on its own page. Users navigate from your application to the configurator — same tab — configure the product, and return to your application via the `back` URL when they close or finalize. The journey is "leave the app, configure, come back" rather than "open a separate tab"; in-app close and finalize controls drive the return.
+
+This is the right mode when your platform **can't embed web components** — legacy CMS, strict iframe or CSP policies, certain B2B platforms — and a standalone configurator page is the only viable option.
+
+Resuming an existing configuration is supported: pass `cid` (configuration ID) and `ca` (access token) on the handoff URL to open a saved configuration for editing — useful for "saved quote → edit later" flows.
+
+**Use when** your platform can't host a web component but you still want the configurator integrated into a user journey that starts and ends in your application.
+
+**What your application does:**
+
+- Adds a link or button somewhere in your UI that navigates the user to the configurator URL.
+- Provides a `back` URL on every handoff so the configurator knows where to return the user.
+- On return, reads any parameters appended to the `back` URL (e.g. a finalized quote ID) and updates the UI.
+- For saved-configuration flows: persists the configuration ID and access token on your side, and passes them back on subsequent handoff URLs.
+- Optionally, for **external authentication**: calls our token exchange from your backend to obtain a one-time code, and passes it on the handoff URL. Without external auth, the configurator uses its default authentication.
+- Optionally receives finalization results on a callback endpoint on your backend.
+
+> **Hosting the handoff target.** The configurator page can be hosted by either side — driven by whether you want your own content around the configurator on that page. **Hosted by us:** simplest, no surrounding content possible; we deliver a URL (optionally under your domain via DNS), you build links pointing at it. **Hosted by you:** host a page yourself, embed the configurator's web component with `integration-mode="handoff"`, and add any surrounding content you want.
+
+**What we set up:**
+
+- If we host the handoff target: a URL (optionally served under your own domain via DNS) that accepts the entry parameters.
+- Optional: a token exchange between your backend and our servers, when you want to plug your platform's identity into the configurator session.
+- The agreed callback contract for finalization results, if applicable.
+- Any custom URL parameters round-tripped through the `back` URL.
+
+### widget
+
+The configurator embeds as a web component and stays hidden by default. The host page provides a trigger — typically a "Customize" button — that powers it on. When open, the configurator can render **inline** within the page or take over the viewport as a **full-screen overlay**; you pick which on a per-placement basis. The configurator manages its own state, URL handling, and authentication.
+
+`widget` sits between `page` (always-on, no host control) and `headless` (host drives everything): your page controls when the configurator opens and how it appears, but the configurator still owns its own navigation and authentication.
+
+**Use when** the host page can host a web component and you want a trigger (a button, a link) that opens the configurator for the user — inline alongside your content, or as a full-screen overlay.
+
+**What your application does:**
+
+- Embeds the configurator's web component on the page.
+- Renders a trigger (e.g. a "Customize" button) and powers the configurator on when the user activates it.
+- Picks between inline and full-screen for each placement.
+
+### headless
+
+Maximum control on your side. The configurator embeds as a web component, but your application drives **everything** — when it opens, which configuration it shows, when it closes, and how it integrates with the rest of your UI. The configurator focuses on the 3D experience; your application handles routing, authentication, and lifecycle.
+
+This is the right fit for platforms that already have their own application architecture — their own router, their own login, their own concept of users, quotes, and projects — and want the configurator to slot in cleanly as one view among many.
+
+**Use when** you have a real application (typically a B2B portal, a CRM, or a dealer platform) and the configurator should integrate into it as a first-class part of the UI, not as a separate page.
+
+**What your application does:**
+
+- Embeds the configurator's web component as part of one of its views.
+- Drives navigation programmatically (open the preset screen, open a specific saved configuration, close, switch modes).
+- Persists configuration IDs and access tokens on your side (e.g. inside a quote record) so users can return to in-progress configurations later.
+- Handles finalization completion via a custom event and updates its own UI in response.
+- Optionally, for **external authentication**: authenticates the user against your own backend and passes a one-time authorization code to the configurator. Without external auth, the configurator uses its default authentication.
+- Manages session lifetime — proactively re-authenticating before tokens expire to avoid data loss.
+
+**What we set up:**
+
+- Optional: the token exchange and session handling for your authentication flow, when you want to plug your platform's identity into the configurator session.
+- The finalization callback contract, if applicable.
+- A project-specific event payload, so finalization can carry the values your application needs (typically a quote ID and any other identifiers we agree on).
+- Optionally, a project-specific API on the configurator for actions like cloning a finalized configuration or other host-driven operations.
+
+## Choosing a Mode
+
+If your scenario looks like…
+
+| Scenario                                                                                                        | Mode                  |
+| --------------------------------------------------------------------------------------------------------------- | --------------------- |
+| A standalone configurator at its own domain                                                                     | `page`                |
+| A configurator under your domain where you don't want to integrate anything — fully hosted by us                | `page` (fully hosted) |
+| A page on your marketing site with your header and footer around the configurator                               | `page`                |
+| A dealer portal that can't host a web component, with a "Configure" button that hands users to the configurator | `handoff`             |
+| A product page with a "Customize" button that opens the configurator inline or full-screen                      | `widget`              |
+| A B2B platform where your application owns routing, auth, and navigation                                        | `headless`            |
+
+## Comparison
+
+| Aspect                             | `page`       | `handoff`                                   | `widget`                       | `headless`                                  |
+| ---------------------------------- | ------------ | ------------------------------------------- | ------------------------------ | ------------------------------------------- |
+| **How it appears**                 | Full page    | Full page (linked in)                       | Embedded inline or full-screen | Embedded inline or full-screen              |
+| **Who controls when it opens**     | URL          | Link from your app                          | Your page                      | Your application                            |
+| **Who controls navigation inside** | Configurator | Configurator                                | Configurator                   | Your application                            |
+| **Authentication**                 | Built-in     | Optional¹                                   | Built-in                       | Optional¹                                   |
+| **Server-side integration needed** | None         | Only if using external auth or finalization | None                           | Only if using external auth or finalization |
+| **Multiple instances on one page** | —            | —                                           | —                              | Supported                                   |
+| **Relative integration effort**    | Lowest       | Medium                                      | Low                            | Highest                                     |
+
+¹ Plugging external authentication (your platform's identity, your JWT format) into the configurator session is optional. Without it, the configurator uses its default authentication. External auth is a common reason to pick `handoff` or `headless`.
+
+## What We Set Up
+
+These items are agreed and implemented per project — they are part of the integration scope, not something that can be toggled at runtime. Switching between modes after delivery may require revisiting them.
+
+**For every project**
+
+- A configurator build (a script bundle). We host it; your page — or our hosted page — loads it via a script tag.
+
+**For external authentication** (optional, available in `handoff` and `headless`)
+
+- A **token exchange** between your backend and our servers. You supply a token format (typically a JWT signed with a key you control); we configure our servers to accept and validate it.
+- A **client identifier** and **server URL** that you use when calling the token exchange — provided by us during onboarding.
+
+**For finalization** (any mode where users finalize a configuration)
+
+- A **callback endpoint** on your side that receives the finalization payload (configuration links, summary, thumbnail). We agree on the URL, the payload shape, and the authentication mechanism upfront.
+- Optionally, **custom return parameters** appended to the user's return URL (`handoff`) or carried by a custom event (`headless`).
+
+**For `headless` specifically**
+
+- The schema and wiring of the finalization event payload — what fields your application needs to receive when the user finalizes.
+- Optionally, a **project-specific API** for actions like cloning a finalized configuration. These are bespoke per project and agreed during onboarding.

package/dist/docs/phoenix/integration/integration-modes-internal.mdx

@@ -0,0 +1,110 @@
+# Integration Modes
+
+> The element name is the project's `webComponentTag` from `application.yaml`; it defaults to `salsita-configurator`. Snippets here use the default. See the [Application Configuration Reference](?path=/docs/phoenix-project-structure--docs#application-configuration-reference).
+
+Phoenix configurators are designed to be embedded into third-party systems — e-commerce sites, dealer portals, CMS pages, B2B platforms, and more. Each integration scenario has different requirements around URL handling, authentication, navigation control, and lifecycle management.
+
+Rather than exposing dozens of individual flags for every axis (`routingMode`, `urlReadWrite`, `storageType`, `closeButtonBehavior`, …), the SDK provides a single `integrationMode` attribute that bundles a coherent set of defaults for each scenario. Set it once when mounting the web component — no other flags needed.
+
+```html
+<salsita-configurator integration-mode="widget" />
+```
+
+## Quick Reference
+
+| Mode       | Description                                                        | Typical scenario                                                    |
+| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `page`     | Full-page configurator that owns the URL. **Default.**             | Standalone SPA, CMS page with header/footer around the configurator |
+| `handoff`  | Full-page configurator entered via deep link from an external app. | Dealer portal opens configurator in a new tab with auth code        |
+| `widget`   | Embedded web component on a host page, self-contained.             | Product page with an inline "Customize" widget                      |
+| `headless` | Embedded web component, host app drives everything.                | B2B portal where the configurator is one view in a larger app       |
+
+## Modes
+
+### [page](?path=/docs/phoenix-integration-page-mode-internal--docs)
+
+The simplest mode. The configurator occupies a full page and is the primary content. It reads and writes URL parameters (`cid`, `ca`) to track the active configuration. Authentication tokens are stored in localStorage. The Back button (← in the header) navigates back through configurator routes only — there is nothing above the configurator to close into.
+
+Also consumes `?code=` on mount for the internal Clerk OAuth redirect (not intended for the partner auth-code flow — that's `handoff` / `headless`).
+
+Use when the configurator **is** the page — a standalone SPA or a CMS page that optionally wraps the configurator in its own header and footer.
+
+### [handoff](?path=/docs/phoenix-integration-handoff-mode-internal--docs)
+
+Like `page`, but designed for cross-application flows where the user is deep-linked into the configurator from an external system and expected to return when done.
+
+- Accepts `code` URL param for auth-code authentication
+- Stores auth tokens in sessionStorage (tab-scoped — closing the tab ends the session)
+- Accepts `back` URL param — when present, the Back button on the configurator's start route navigates the user to the originating application
+- Two-page setup: the external app links to the configurator page with `?code=…&back=…`
+
+### [widget](?path=/docs/phoenix-integration-widget-mode-internal--docs)
+
+The configurator is embedded as a web component on a host page alongside other content. It still reads and writes URL parameters, so the active configuration is shareable and survives page refreshes.
+
+- Supports `power` prop (`"on"` / `"standby"` / `"off"`) — the configurator can start hidden and appear on demand
+- Automatically powers on when a `cid` is detected in the URL
+- Back button on the configurator's start route puts the configurator into `standby` mode
+- Supports `expanded` prop for fullscreen toggling
+- `power: "standby"` or `"off"` overrides `expanded` and resets its side effects (fullscreen overlay, scroll lock)
+
+### [headless](?path=/docs/phoenix-integration-headless-mode-internal--docs)
+
+Maximum host control. The configurator is embedded as a web component, but the host application drives routing, authentication, and close behavior. The URL is completely ignored.
+
+- Host navigates via the `route` prop
+- Auth-code flow via the `authorizationCode` prop, tokens stored in sessionStorage
+- Back button on the configurator's start route dispatches a `close` event with no default action — the host decides what happens
+- Supports `power` and `expanded` props
+- The only mode that supports multiple configurator instances on the same page
+
+Despite the name, the configurator still renders its full UI — "headless" refers to the host providing the brain (routing, auth, lifecycle decisions), not the absence of a visual interface.
+
+## Which Mode Do I Pick?
+
+Start at the top, stop at the first match:
+
+1. **The host page has its own router and wants to control when the configurator opens, what it shows, and how it closes** → `headless`
+2. **The host page wants an embedded, self-contained widget** — open it, configure, close it, no routing management → `widget`
+3. **The user is handed off from another application** with auth-code and expected to return → `handoff`
+4. **Everything else** — the configurator is the page → `page`
+
+### If the Integration Looks Like…
+
+| Scenario                                                                           | Mode       |
+| ---------------------------------------------------------------------------------- | ---------- |
+| A standalone configurator at `configure.example.com`                               | `page`     |
+| A page on the client's marketing site with their nav/footer around it              | `page`     |
+| A "Configure" button in a dealer portal that opens the configurator in another tab | `handoff`  |
+| A product page with a "Customize" widget inline                                    | `widget`   |
+| A B2B portal where the surrounding app owns routing, auth, and navigation          | `headless` |
+
+## Comparison Matrix
+
+Legend: ✅ enabled · ❌ disabled · ⚠️ discouraged · 🤷 supported but rarely useful · — n/a
+
+| Axis                         | `page`       | `handoff`               | `widget`        | `headless`         |
+| ---------------------------- | ------------ | ----------------------- | --------------- | ------------------ |
+| **Mount context**            | Full page    | Full page (deep-linked) | WC on host page | WC on host page    |
+| **URL: reads `cid` / `ca`**  | ✅           | ✅                      | ✅              | ❌                 |
+| **URL: reads `code`**        | ✅⁵          | ✅                      | ❌              | ❌                 |
+| **URL: reads `back`**        | ❌           | ✅                      | ❌              | ❌                 |
+| **URL: writes `cid`**        | ✅           | ✅                      | ✅              | ❌                 |
+| **`authorizationCode` prop** | ⚠️¹          | use `code` URL param    | ⚠️¹             | ✅                 |
+| **Auth storage**             | localStorage | sessionStorage          | localStorage    | sessionStorage     |
+| **`power` prop**             | 🤷²          | 🤷²                     | ✅              | ✅                 |
+| **`expanded` prop**          | 🤷²          | 🤷²                     | ✅              | ✅                 |
+| **Auto power-on on `cid`**   | ❌           | ❌                      | ✅              | ❌                 |
+| **Host drives `route` prop** | ❌           | ❌                      | ⚠️³             | ✅                 |
+| **Back on start route**      | ❌           | ✅ → `back` URL         | ✅ → standby    | ✅ → `close` event |
+| **Preset screen on close**   | —            | not bypassed⁴           | not bypassed⁴   | host-defined       |
+
+¹ Tokens stored in localStorage leak across tabs. Use `handoff` or `headless` for auth-code flow.
+
+² Works, but the configurator owns the full page — standby/expanded toggling has no practical effect.
+
+³ `route` prop can be set, but may clash with URL-based `cid`/`ca` params.
+
+⁴ When more than one preset exists, the close action does not bypass the preset screen. Override via the `navigated` event.
+
+⁵ `page` consumes `?code=` for the internal Clerk OAuth redirect, not intended for the partner auth-code flow (which belongs in `handoff` / `headless`).

package/dist/docs/phoenix/integration/page-mode-external.mdx

@@ -0,0 +1,38 @@
+# Page Mode — Integration Guide
+
+The configurator runs as a standalone page — it manages its own URL state and authentication. No server-side integration is required.
+
+## Embedding
+
+Add the configurator to the page and include the script:
+
+```html
+<salsita-configurator id="configurator"></salsita-configurator>
+
+<script src="https://example.com/salsita-configurator.iife.js"></script>
+```
+
+The configurator fills its parent container. Set a height on the element or its parent:
+
+```css
+#configurator {
+  block-size: 100dvb; /* full viewport height */
+}
+```
+
+## URL Behavior
+
+The configurator reads and writes URL query parameters:
+
+- **`cid`** — configuration ID. Read on mount, written when the user picks a preset and a new configuration is created.
+- **`ca`** — access token. Read on mount, cleared when `cid` is written.
+
+Because `cid` is persisted in the URL, the active configuration survives page reloads and bookmarks (the access token is retrieved from localStorage).
+
+## Sharing
+
+Sharing a configuration with another user requires the built-in share dialog — it generates a link with a proper access token. The raw page URL with `cid` alone is not enough, since the access token in localStorage is not transferable.
+
+## Filtering Presets
+
+Use the `preset-tags` attribute (or `presetTags` property) to show only a subset of presets on the preset selection screen — useful when the same build serves multiple entry points. See [Preset Tags](?path=/docs/phoenix-integration-preset-tags-external--docs).

package/dist/docs/phoenix/integration/page-mode-internal.mdx

@@ -0,0 +1,25 @@
+# Page Mode — Internal
+
+> The live example uses the custom tag `salsita-3d-configurator`.
+
+## Overview
+
+The default mode. The configurator owns the full page and is the primary content. Simplest setup — no auth-code flow, no host communication, and no way to close the configurator (the Back button still navigates through the configurator's routes, but there is nothing to close into).
+
+See also: [Page Mode (External)](?path=/docs/phoenix-integration-page-mode-external--docs) — share this page with the partner if they need to embed the configurator on their site.
+
+## Behavior Summary
+
+- Reads `cid` / `ca` from URL → opens an existing configuration
+- Reads `code` from URL → consumes the internal Clerk OAuth redirect (not intended for the partner auth-code flow)
+- Writes `cid` to URL on navigation (new configuration created from preset)
+- Auth tokens stored in localStorage (persists across tabs and sessions)
+- Back button (← in the header) only navigates between configurator routes; on the start route it has nowhere to go and is not displayed (the configurator IS the page — no exit action exists)
+- No `back` URL param
+- `power` and `expanded` props are supported but have no practical effect — the configurator owns the full page
+
+## Setup
+
+This is the default mode. The built-in `index.html` works out of the box — no template file or additional configuration needed.
+
+If the client wraps the configurator in their own page (e.g. a CMS or marketing site with their own header/footer), the `integration-mode` attribute can be omitted since `page` is the default.

package/dist/docs/phoenix/integration/preset-tags-external.mdx

@@ -0,0 +1,57 @@
+# Preset Tags — Integration Guide
+
+The `presetTags` property lets the host restrict which presets the configurator shows on the preset selection screen. Useful when the same configurator build is embedded in multiple contexts (e.g. different product pages, dealer portals, landing pages) and each context should only expose a relevant subset of presets.
+
+## Why Use It
+
+A single configurator deployment often serves many entry points. Instead of building a separate deployment per context, tag each preset with one or more labels and let the host pick the relevant subset at embed time:
+
+- A product page shows only presets for that product
+- A dealer portal shows only presets the dealer is certified to sell
+- A marketing campaign links directly into a curated subset
+- Auto-select a single preset to skip the preset screen entirely
+
+## Tagging Presets in Admin
+
+Each preset in the admin portal has a `tags` field — an array of free-form strings. Open the preset in the admin UI and add one or more tags (e.g. `product-a`, `b2b`, `promo-2026`). Tags are saved with the published preset data and take effect on the next publish.
+
+## Setting the Attribute / Property
+
+**HTML attribute** — comma-separated list of tags:
+
+```html
+<salsita-configurator preset-tags="product-a,promo-2026" />
+```
+
+**JavaScript property** — array of strings (or `null` to disable filtering):
+
+```js
+const configurator = document.getElementById('configurator')
+configurator.presetTags = ['product-a', 'promo-2026']
+```
+
+Setting `presetTags = null` (or omitting the attribute) disables filtering — all presets are shown.
+
+Prefer the attribute when the tag set is static for the page. Use the property when the host needs to switch tags at runtime (e.g. the user selects a different product variant).
+
+## How Selection Works
+
+A preset matches when **at least one** of its tags appears in `presetTags` (OR semantics, not AND). The matched set drives the preset screen:
+
+- **Multiple matches** — the preset selection screen shows only the matched presets. The user picks one manually.
+- **Exactly one match** — the configurator auto-selects that preset and skips the preset screen. The user lands directly in the configuration.
+- **No matches** — the configurator shows a "not found" state. No fallback is attempted beyond the tag filter.
+
+### Seed Preset Fallback
+
+A configurator build ships with a small set of **seed presets** — presets baked into the build by Salsita as part of the project delivery. They exist so the configurator has something meaningful to show before any presets are published from the admin portal, and as a safety net if published data becomes unavailable. Seed presets also carry tags, but those tags are fixed at build time — they cannot be edited in the admin portal or at runtime.
+
+Published presets are tried first. If no published preset matches the tags, the configurator falls back to seed presets — also filtered by the same tags. This can be used deliberately: reserve a marker tag (e.g. `fallback`) on the seed presets and include it in `presetTags` to guarantee a default when published presets are missing or don't match.
+
+For the fallback to behave as intended, the marker tag must be **unique to seed presets** — never used on any published preset. Otherwise a published preset carrying the same tag would match first and the seed fallback would never kick in. Because seed preset tags are baked into the build, agree on the marker with Salsita up front, and treat it as reserved in the admin portal.
+
+```html
+<salsita-configurator preset-tags="product-a,fallback" />
+```
+
+If a published preset is tagged `product-a`, it wins. Otherwise the seed preset tagged `fallback` is used.