@salsita-ai/sdk 0.50.0-develop.bd84173265 → 0.50.0-develop.bded01bb03

package/dist/docs/phoenix/migration-guide.mdx

@@ -292,7 +292,7 @@ This will:
 
 Other useful commands:
 
-- `pnpm phoenix sync` - Sync dependencies in package.json
+- `pnpm phoenix sync` - Regenerate the generated code and project files
 - `pnpm phoenix gen` - Regenerate project files
 - `pnpm phoenix dev` - Start development server with hot reload
 - `pnpm phoenix deployment:prepare` - Prepare for deployment
@@ -440,7 +440,7 @@ Use this checklist to verify migration completeness:
 - [ ] Configurator renders correctly
 - [ ] Admin interface works
 - [ ] All imports updated to new paths
-- [ ] Node 24 and pnpm v10 installed
+- [ ] Node 24 and a package manager installed
 
 ## Removed Files
 
@@ -486,7 +486,7 @@ Update imports to use these globals instead of importing from packages directly.
 ## Environment Requirements
 
 - Node 24
-- pnpm v10
+- A package manager; the commands in this guide use pnpm
 - `RESOURCES_URL` is an optional frontend environment variable; in local development it defaults to the Vite dev server at `http://localhost:5173`
 
 ## Next Steps

package/dist/docs/phoenix/phoenix-cli.mdx

@@ -16,7 +16,7 @@ The Phoenix CLI (`phoenix` command) is the unified tool for all configurator dev
 
 The SDK and its CLI run on Node.js 22.13 or newer, the range declared in `engines.node` of `@salsita-ai/sdk`. On an older Node.js, `phoenix` stops before it runs a command, names the running version and the required range, and exits with a non-zero code. The legacy binaries run no such check; package managers warn about the range when the SDK is installed.
 
-`phoenix init [folder]` starts a configurator project in `[folder]` (default: the working directory):
+`phoenix init [folder]` starts a configurator project in `[folder]` (default: the working directory). The project installs with any package manager. The commands on this page use pnpm; with npm, run `npm install` and `npx phoenix sync`, with Yarn `yarn phoenix sync`, with Bun `bunx phoenix sync`:
 
 ```bash
 npx -p @salsita-ai/sdk@canary phoenix init my-configurator
@@ -30,12 +30,17 @@ pnpm phoenix dev
 `phoenix init`:
 
 1. Refuses to run when a `spec/` folder already exists, so it never touches an existing project.
-2. Writes a `package.json` that depends on the CLI's SDK version when the folder has none. An existing `package.json` is kept, as long as it depends on the SDK.
+2. Writes a `package.json` when the folder has none, and an existing one is kept, as long as it depends on the SDK. Either way, `package.json` gains the entries it lacks, and an entry it already has stays as it is:
+   - the CLI's SDK version, in a new `package.json`;
+   - every package the SDK requires as a peer, at the version [`phoenix deps`](#phoenix-deps) writes: the lowest of the SDK's range, with the `@types/*` packages in `devDependencies`. A peer the project declares in any dependency field counts, whatever its version. `@clerk/clerk-react` is not among them, because the starter spec does not set `useClerk`;
+   - `eslint` and `prettier` in `devDependencies`, at the versions the SDK runs itself, so an editor formats and lints with the same versions as `phoenix check`.
+
+   With these, the install gives the project everything `phoenix dev`, `build` and `check` need. `init` writes no `packageManager` field and no package-manager settings: a project that installs with pnpm 11 adds the settings in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager) itself.
+
 3. Adds the `dev`, `build`, `deploy`, `check` and `fix` scripts to `package.json` (see [Project Scripts](#project-scripts)). A script the project already has under one of those names keeps its command.
 4. Writes a starter spec (`spec/application.yaml`, `spec/configurator.yaml`) with one resizable, recolorable box, and switches `package.json` to the application-spec pipeline.
-5. Writes `pnpm-workspace.yaml` with the pnpm settings the first install needs: the build scripts of the SDK's dependencies are allowed or denied, and `@salsita-ai/*` packages are exempt from pnpm's minimum release age. A project inside a pnpm monorepo gets no file; the workspace root holds these settings.
 
-It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
+The next steps it prints use the package manager you ran it with, or name none when it cannot tell. It asks nothing, writes no `.env` and contacts no server. `phoenix sync` then generates every other project file, including the agent skills described in [Project Structure](?path=/docs/phoenix-project-structure--docs). The `.gitignore` is among them only when the folder is inside a git repository, so run `git init` before the first sync, or sync again after it.
 
 ### Which project `phoenix dev` develops in
 
@@ -180,7 +185,7 @@ spec/application.yaml → Server prepares environment → CLI writes the generat
 | `check`  | `phoenix check`  | Run all checks (TypeScript, ESLint, Prettier) |
 | `fix`    | `phoenix fix`    | Auto-fix lint and formatting issues           |
 
-The scripts are yours: change, rename or delete them, and add your own. `phoenix sync` and `phoenix clean` leave the `scripts` section of `package.json` as it is, so they add no script, restore none you removed and remove none. Every CLI command also runs without a script, as `pnpm phoenix <command>`.
+The scripts are yours: change, rename or delete them, and add your own. `phoenix sync` and `phoenix clean` leave the `scripts` section of `package.json` as it is, so they add no script, restore none you removed and remove none. Every CLI command also runs without a script, through your package manager: `pnpm phoenix <command>`, `npx phoenix <command>`, `yarn phoenix <command>` or `bunx phoenix <command>`.
 
 A project may have other scripts than these five, such as `sync`, `test` or `verify:fix`; they are its own and stay as they are. All of this holds for a project on the application-spec pipeline, which `phoenix init` selects. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix sync` and `phoenix clean` write their own set of scripts into `package.json` on every run, over scripts of the same name.
 
@@ -398,7 +403,7 @@ Set initial values from a local production build with roughly 5–10% headroom t
 
 ### `phoenix clean`
 
-Removes all build artifacts (`.phoenix/`, `node_modules/`), reinstalls dependencies, and rebuilds all generated files from scratch. Use this when:
+Removes `.phoenix/` and regenerates all project files from scratch. It installs nothing and leaves `node_modules/` as it is; to reinstall too, delete `node_modules/` and install with your package manager. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix clean` also removes `node_modules/` and runs `pnpm install`. Use this when:
 
 - Generated files are corrupted or out of sync
 - After major SDK version upgrades
@@ -406,10 +411,12 @@ Removes all build artifacts (`.phoenix/`, `node_modules/`), reinstalls dependenc
 
 ### `phoenix sync`
 
-Syncs project dependencies and regenerates all project files without building Vite bundles or webhooks. Faster than `clean` — use this for routine updates after changing spec files or upgrading dependencies. Before installing, it adds the pnpm settings `phoenix init` writes to a standalone project's `pnpm-workspace.yaml` when they are missing; values you set there are kept.
+Regenerates all project files without building Vite bundles or webhooks. Faster than `clean` — use this for routine updates after changing spec files or updating the SDK. It installs nothing: install with your package manager before syncing, after any change to `package.json`. It writes no package-manager settings; `pnpm-workspace.yaml` is the project's own. In a project on the legacy pipeline, `phoenix sync` runs `pnpm install` first.
 
 With the application-spec pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `.gitignore` is written only when the project is inside a git repository: the project folder or one of its parent folders holds a `.git` entry. Outside a repository, sync neither creates the file nor changes one that is already there, and the same holds for `dev`, `build` and `clean`. Run `git init` before the first sync, or sync again after it, to get the file. The legacy pipeline writes `.gitignore` in every project.
 
+With the application-spec pipeline, sync never writes `package.json`. Before it generates any file, it checks that `package.json` declares every peer of the installed SDK at a version inside the SDK's range, and stops with a non-zero exit code when it does not. The message lists each peer that fails, with the range the SDK needs and the version found, or `missing`, and names the fix: run [`phoenix deps`](#phoenix-deps), then install with your package manager. `phoenix build`, `phoenix clean` and `phoenix dev` make the same check, and so does the platform build of [`phoenix deploy`](#phoenix-deploy). `phoenix dev` stops when the check fails at start; on a rebuild it reports the failure like a spec error and keeps running. [Dependencies](?path=/docs/phoenix-project-structure--docs#dependencies) has the rules. The legacy pipeline merges the SDK's dependencies into `package.json` on every sync.
+
 | Flag             | Env Variable    | Default | Description                    |
 | ---------------- | --------------- | ------- | ------------------------------ |
 | `--force` / `-f` | `FORCE_REBUILD` | `false` | Force full rebuild, skip cache |
@@ -423,12 +430,14 @@ pnpm phoenix deps
 pnpm install
 ```
 
+Run it after every SDK update: `phoenix sync`, `dev` and `build` stop while `package.json` does not declare the SDK's peers (see [`phoenix sync`](#phoenix-sync)).
+
 - A missing peer is added at the lowest version of the SDK's range, as an exact version, in alphabetical order: type packages (`@types/*`) to `devDependencies`, the others to `dependencies`.
 - A peer declared with a version range whose lowest version falls outside the SDK's range is set to the lowest version of the SDK's range, in the field that declares it. The output says when that is a downgrade.
 - A peer declared with a specifier that is not a version range, such as `workspace:`, `npm:`, `catalog:`, `file:`, `link:` or a git URL, stays as it is.
 - `@salsita-ai/common`, `@salsita-ai/contracts`, `@salsita-ai/platform-project-sdk`, `@salsita-ai/platform-common` and `@salsita-ai/platform-contracts` are removed, because `@salsita-ai/sdk` replaces them. No other entry is removed.
 
-Every other part of `package.json` keeps its order and formatting. `phoenix deps` installs nothing: it lists each change and names `pnpm install` as the next step, or says that nothing needed to change. Running it again changes nothing. It reads the spec to learn whether the project uses Clerk, so it stops with the spec's errors when the spec does not parse.
+Every other part of `package.json` keeps its order and formatting. `phoenix deps` installs nothing: it lists each change and names the install of the package manager you ran it with as the next step, or says that nothing needed to change. Running it again changes nothing. It reads the spec to learn whether the project uses Clerk, so it stops with the spec's errors when the spec does not parse.
 
 This holds for a project on the application-spec pipeline. In a project on the legacy pipeline (see [Current and legacy project tooling](#current-and-legacy-project-tooling)), `phoenix deps` changes nothing and says that `phoenix sync` manages the dependencies.
 
@@ -606,10 +615,11 @@ Generated projects carry the `phoenix-variants` agent skill, which tells coding
 
 ### `phoenix link`
 
-Link a local copy of the Phoenix SDK for development. This creates symlinks so that changes to the SDK source are reflected in your project without publishing.
+An internal tool for working on the SDK itself, and pnpm only: in a project with another package manager's lockfile and no `pnpm-lock.yaml`, it stops and changes nothing. Link a local copy of the Phoenix SDK for development in a project installed with pnpm. It writes a `file:` override for each SDK package into `pnpm-workspace.yaml`, so that after the next install changes to the SDK source are reflected in your project without publishing. It installs nothing; run the install it prints next:
 
 ```bash
 phoenix link --sdk-path ../configurator-phoenix
+pnpm install --config.optimistic-repeat-install=false
 ```
 
 | Flag         | Default                   | Description                |
@@ -620,10 +630,11 @@ When linked, `phoenix dev` automatically watches for changes in the linked SDK's
 
 ### `phoenix unlink`
 
-Remove the local SDK linking and restore normal package resolution.
+Remove the local SDK linking: it deletes the overrides `phoenix link` wrote. Like `phoenix link`, it is an internal tool and pnpm only. It installs nothing; the install it prints restores normal package resolution:
 
 ```bash
 phoenix unlink
+pnpm install --config.optimistic-repeat-install=false
 ```
 
 ## Utilities
@@ -739,7 +750,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
 To keep the conversation that led to a build, place a reviewed UTF-8 transcript in `conversation.log` at the project root before deploying. Deploy automatically includes it in the private source archive. Download the build's sources from Studio to read it; access is the same as for the rest of that build's sources. The build extractor skips the log, so it is not an application build input or a public asset. Missing logs produce a warning and deployment continues. Directories, links and special files at that path are rejected.
 

package/dist/docs/phoenix/project-structure.mdx

@@ -136,18 +136,37 @@ export default [CabinetModule, DrawerModule, ShelfModule]
 
 Phoenix auto-flattens both patterns during build. Use array exports when logically grouping related items in one file.
 
-## Dependencies Merging
+## Dependencies
 
-When running `phx sync` or `phx build`, Phoenix manages `package.json` dependencies:
+In a project on the application-spec pipeline, `package.json` is the project's own: `phoenix sync`, `phoenix dev` and `phoenix build` never write it. The SDK lists the packages its code imports from the project's install as peer dependencies (React, three.js, MUI, Lingui and others), and the project declares them next to `@salsita-ai/sdk`. [`phoenix deps`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deps) adds the missing ones and moves out-of-range ones into the SDK's range; run it, then install, after every SDK update. With pnpm, and the same through any other package manager (`npm install`, `npx phoenix deps` with npm):
 
-| Behavior              | Description                                                    |
-| --------------------- | -------------------------------------------------------------- |
-| Phoenix deps override | Required Phoenix dependencies override user-specified versions |
-| Versions pinned       | All Phoenix deps use exact versions (no ^ or ~)                |
-| User deps preserved   | Non-conflicting user dependencies are kept                     |
-| Manual deps safe      | Dependencies not in Phoenix's required list remain untouched   |
+```bash
+pnpm add @salsita-ai/sdk@<version>
+pnpm phoenix deps
+pnpm install
+pnpm phoenix sync
+```
+
+`phoenix sync`, `phoenix dev` and `phoenix build`, also on the platform when a deploy builds, check `package.json` before they generate any file. When a peer is missing, or declared at a version whose lowest match falls outside the SDK's range, they stop and list each such peer with the range the SDK needs and what `package.json` declares. A peer counts in `dependencies`, `devDependencies` or `optionalDependencies`, and a specifier that is not a version range, such as `workspace:` or `link:`, counts as declared. Add your own dependencies to `package.json` as usual; Phoenix leaves them, the Node.js and package-manager versions and the rest of the file as you wrote them.
+
+In a project on the legacy pipeline (see [Current and legacy project tooling](?path=/docs/phoenix-phoenix-cli--docs#current-and-legacy-project-tooling)), `phoenix sync` and `phoenix build` merge the SDK's required dependencies into `package.json` instead, at exact versions over the ones you set, and keep every other dependency.
+
+### Package manager
+
+A project installs with any package manager: pnpm, npm, Yarn or Bun. Phoenix writes no package-manager settings and no `packageManager` field; the lockfile, `pnpm-workspace.yaml`, `.npmrc` and `.yarnrc.yml` are the project's own. Run `phoenix` through the package manager the project uses, such as `pnpm phoenix sync` or `npx phoenix sync`.
+
+A project that installs with pnpm 11 needs a `pnpm-workspace.yaml` in its root before the first install. pnpm 11 stops an install until every dependency build script is allowed or denied, and the SDK's dependencies have three. Its default minimum release age also refuses a package published only recently, so the exclusion lets the project install an SDK build on the day it is released; it is optional:
+
+```yaml
+allowBuilds:
+  '@swc/core': true
+  esbuild: true
+  es5-ext: false
+minimumReleaseAgeExclude:
+  - '@salsita-ai/*'
+```
 
-To add custom dependencies, add them normally to `package.json`. Phoenix preserves them unless they conflict with required framework dependencies.
+The file is yours to extend, for example to allow the build script of a dependency you add. In a pnpm monorepo, these settings go into the workspace root's `pnpm-workspace.yaml`. [`phoenix deploy`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deploy) packs `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, and the platform build, which installs with pnpm, follows them.
 
 ## Global Interfaces
 
@@ -180,21 +199,21 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Root Level Files
 
-| File                                                   | Auto-Generated? | Notes                                  |
-| ------------------------------------------------------ | --------------- | -------------------------------------- |
-| `package.json`                                         | Partially       | Dependencies merged, scripts untouched |
-| `tsconfig.json`                                        | Once            | Yours; see below                       |
-| `eslint.config.js`                                     | Once            | Yours; see below                       |
-| `prettier.config.js`                                   | Once            | Yours; see below                       |
-| `.prettierignore`                                      | No              | Optional and your own; see below       |
-| `.nvmrc`                                               | Yes             | Managed by Phoenix                     |
-| `.gitignore`                                           | Partially       | Only in a git repository; see Markers  |
-| `.env`                                                 | No              | Git-ignored, local config              |
-| `.env.example`                                         | No              | Template for env vars                  |
-| `.env.generated`                                       | Yes             | Optional, git-ignored; see below       |
-| `README.md`                                            | No              | Project documentation                  |
-| `AGENTS.md`                                            | No              | Your own coding-agent instructions     |
-| `.claude/skills/phoenix*/`, `.agents/skills/phoenix*/` | Yes             | Phoenix agent skills                   |
+| File                                                   | Auto-Generated? | Notes                                 |
+| ------------------------------------------------------ | --------------- | ------------------------------------- |
+| `package.json`                                         | No              | Yours; see Dependencies               |
+| `tsconfig.json`                                        | Once            | Yours; see below                      |
+| `eslint.config.js`                                     | Once            | Yours; see below                      |
+| `prettier.config.js`                                   | Once            | Yours; see below                      |
+| `.prettierignore`                                      | No              | Optional and your own; see below      |
+| `pnpm-workspace.yaml`                                  | No              | Only with pnpm; see Package manager   |
+| `.gitignore`                                           | Partially       | Only in a git repository; see Markers |
+| `.env`                                                 | No              | Git-ignored, local config             |
+| `.env.example`                                         | No              | Template for env vars                 |
+| `.env.generated`                                       | Yes             | Optional, git-ignored; see below      |
+| `README.md`                                            | No              | Project documentation                 |
+| `AGENTS.md`                                            | No              | Your own coding-agent instructions    |
+| `.claude/skills/phoenix*/`, `.agents/skills/phoenix*/` | Yes             | Phoenix agent skills                  |
 
 Sync does not write `README.md`, `AGENTS.md`, `.env.example`, `.env.ci` or the `README.md` files in `assets/public/` and `assets/private/`. Earlier SDK versions wrote them once; a project that has them keeps them, and they are yours to edit.
 
@@ -210,21 +229,20 @@ With the application-spec pipeline, the project's TypeScript settings are in `.p
 
 The only root `tsconfig.json` sync replaces is the full file earlier SDK versions generated there, recognised by its settings; any other stays as it is. `phoenix dev`, `phoenix build` and the webhook bundle do not resolve `paths` aliases, so an alias added to the root file passes `phoenix check` and fails the build. `phoenix check` type-checks with the root `tsconfig.json`, or with `.phoenix/tsconfig.json` when the project has none. The legacy pipeline writes the full `tsconfig.json` on every sync.
 
-With the application-spec pipeline, sync writes `eslint.config.js` and `prettier.config.js` only when the project has none, each re-exporting the SDK's shared configuration so editors find it. They are yours to commit and to change. The only ones sync replaces are the files earlier SDK versions generated there; any other stays as it is. `phoenix check` and `phoenix fix` lint and format with the project's files, and with the SDK's configurations when a file is missing (see [`phoenix check`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-check)). Sync formats the files it generates in the project root, such as `package.json` and the agent skills, with the same Prettier configuration, so `phoenix check` accepts them; while the project's configuration cannot be loaded, as before the first install, they get the SDK's settings. The legacy pipeline writes both files on every sync.
+With the application-spec pipeline, sync writes `eslint.config.js` and `prettier.config.js` only when the project has none, each re-exporting the SDK's shared configuration so editors find it. They are yours to commit and to change. The only ones sync replaces are the files earlier SDK versions generated there; any other stays as it is. `phoenix check` and `phoenix fix` lint and format with the project's files, and with the SDK's configurations when a file is missing (see [`phoenix check`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-check)). Sync formats the files it generates in the project root, such as the agent skills, with the same Prettier configuration, so `phoenix check` accepts them; while the project's configuration cannot be loaded, as before the first install, they get the SDK's settings. The legacy pipeline writes both files on every sync.
 
 With the application-spec pipeline, the Lingui configuration is `.phoenix/.linguirc`, which sync rewrites with the rest of `.phoenix/` from `availableLocales` in `spec/application.yaml`. Phoenix passes that file to Lingui every time it extracts or compiles the catalogs and to its Vite builds, so a `.linguirc` in the project root is not read and can be deleted. To run Lingui yourself, name the file: `npx lingui extract --config .phoenix/.linguirc`, from the project root. The legacy pipeline writes `.linguirc` in the project root on every sync.
 
 ### DO NOT EDIT (Fully Auto-Generated)
 
 - **Everything in `.phoenix/`** - Completely regenerated on each build. The exceptions are `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`, and `.phoenix/.env.generated`, the generated env file of `phoenix dev`; a rebuild keeps both
-- `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
 - `.env.generated`
 - `phoenix` and `phoenix-*` skill folders under `.claude/skills/` and `.agents/skills/` — rewritten on every sync with anything else inside them removed, and other `phoenix`-prefixed skill folders are removed; to customise a skill, copy it to a folder whose name does not start with `phoenix`
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read the Phoenix agent skills. An `AGENTS.md` is yours to add for your own instructions; sync does not write one. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) read the Phoenix agent skills. An `AGENTS.md` is yours to add for your own instructions; sync does not write one. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK, runs `phoenix deps`, installs, then runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 

package/dist/docs/phoenix/quickstart.mdx

@@ -15,7 +15,7 @@ Build a working office desk configurator from an empty folder. You will describe
 
 ## Before you start
 
-Use Node.js 24 and pnpm 11. The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
+Use Node.js 24 and any package manager; the commands below use pnpm, and with pnpm 11 the project also needs the `pnpm-workspace.yaml` in [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager). The tutorial uses the office desk model served by this documentation site at `/models/office-desk.gltf`; download it first. Real client projects normally start from `phoenix init`. This tutorial creates the four essential files by hand so you can see what Phoenix owns.
 
 ## Step 0 — Create the project
 
@@ -40,17 +40,13 @@ Now add these four files.
   "dependencies": {
     "@salsita-ai/sdk": "0.48.0"
   },
-  "devDependencies": {
-    "@lingui/cli": "5.9.5",
-    "@lingui/swc-plugin": "5.11.0"
-  },
   "phoenix": {
     "applicationFlow": true
   }
 }
 ```
 
-Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The first sync uses Lingui while generating the rest of the dependencies, so its CLI and SWC plugin must also be present in the initial install.
+Use the SDK version supplied by your team if it differs from the repository's current `0.48.0` version. `phoenix.applicationFlow` selects the application-spec project structure. The SDK runs its own Lingui, so the SDK is the only dependency you write by hand; `phoenix deps` adds the packages it needs next to it in the install step below. A project started with `phoenix init` gets a `package.json` that already declares them.
 
 ### `.env`
 
@@ -97,13 +93,17 @@ components:
         layout: universal
 ```
 
-Install the SDK, then ask Phoenix to generate the rest of the project:
+Install the SDK, let it declare the packages it needs, such as React, three.js and MUI, install them, then ask Phoenix to generate the rest of the project:
 
 ```sh
 pnpm install
+pnpm phoenix deps
+pnpm install
 pnpm phoenix sync
 ```
 
+`phoenix sync` stops while `package.json` lacks one of those packages; after every SDK update, run `phoenix deps` and install again (see [`phoenix deps`](?path=/docs/phoenix-phoenix-cli--docs#phoenix-deps)). With npm, the same steps are `npm install`, `npx phoenix deps`, `npm install` and `npx phoenix sync`.
+
 `phoenix sync` keeps `spec/` and `src/` as your authored inputs and generates the application shell, types, and `.phoenix/` implementation. Start development without a server:
 
 ```sh

package/dist/docs/phoenix/sdk-builder-workflow.mdx

@@ -8,9 +8,9 @@ Your workspace's Studio shows the setup, the link to your configurator and the s
 
 ## Before you start
 
-- **Package access:** `@salsita-ai/sdk` is public on npm; `npx` and `pnpm install` download it without a registry token.
+- **Package access:** `@salsita-ai/sdk` is public on npm; any package manager downloads it without a registry token.
 - **Workspace details:** you need your workspace slug and its Phoenix region (`eu` or `us`), which you also received with your workspace.
-- **Tools:** Node.js and pnpm.
+- **Tools:** Node.js and a package manager. The commands below use pnpm; with npm, run `npm install` and `npx phoenix …` instead, with Yarn `yarn phoenix …`, with Bun `bunx phoenix …`.
 - **SDK build:** during the internal beta, use the `canary` build of the SDK, as the commands below do. It is published from every change to the platform, so it is newer than the last release.
 
 ## 1. Create a project
@@ -22,11 +22,11 @@ pnpm install
 pnpm phoenix sync
 ```
 
-`phoenix init [folder]` writes the starter project: `package.json`, `pnpm-workspace.yaml` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it, and its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: the TypeScript, lint and formatting config and the agent skills. It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
+`phoenix init [folder]` writes the starter project: `package.json` and the starter spec, `spec/application.yaml` and `spec/configurator.yaml`, which describe one box you can resize and recolour. The starter depends on the same SDK version as the CLI that created it and on the packages the SDK requires next to it (React, three.js, MUI, Lingui and the others, with their type packages), with ESLint and Prettier at the versions the SDK uses itself. Its `package.json` has the `dev`, `build`, `deploy`, `check` and `fix` scripts, which are yours to change. `phoenix sync` then adds the rest of the project: the TypeScript, lint and formatting config and the agent skills. It writes no webhook code: a project without `src/webhooks/index.ts` gets a built-in webhook (see [Webhook Entry Point](?path=/docs/phoenix-webhooks--docs#webhook-entry-point)). It writes a `.gitignore` only when the folder is inside a git repository; run `git init` before the first sync, or sync again after it, to get the file.
 
-`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK.
+`init` only writes these files: it asks nothing and contacts no server. It refuses a folder that already has a `spec/` folder. A `package.json` already in the folder is kept, as long as it depends on the SDK, and gains only the entries it lacks (see [Starting a New Project](?path=/docs/phoenix-phoenix-cli--docs#starting-a-new-project)).
 
-`pnpm-workspace.yaml` holds the pnpm settings the install needs: it allows the build scripts of the SDK's dependencies and exempts `@salsita-ai/*` packages from pnpm's minimum release age, so a build of the SDK published today installs. The file is yours to edit, for example to allow the build script of a dependency you add. `phoenix sync` adds these entries when they are missing and keeps the values you set. A project inside a pnpm monorepo gets no file of its own; the workspace root holds the settings.
+Phoenix writes no package-manager settings. With pnpm 11, add a `pnpm-workspace.yaml` that allows the build scripts of the SDK's dependencies before the first install; [Package manager](?path=/docs/phoenix-project-structure--docs#package-manager) has the file.
 
 The starter `spec/application.yaml` begins with `project: default`, which means the default project of the workspace you sign in to. Leave it as it is; a workspace has one project.
 
@@ -81,7 +81,7 @@ pnpm phoenix deploy
 4. It uploads the archive, which may be up to 200 MB.
 5. It starts the build, prints a link to the build's page in Studio and follows the build until your configurator is live, then prints its URL.
 
-On the server, the install follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml`, so it allows the same build scripts and package versions as `pnpm install` on your computer. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
+On the server, the install runs pnpm. It follows your `pnpm-lock.yaml` and `pnpm-workspace.yaml` when the project has them, so a pnpm project gets the same build scripts and package versions as on your computer; without them, pnpm resolves `package.json` with the settings the SDK needs. The build runs without platform secrets. It sees only your own environment variables and the public platform values, the [build environment](?path=/docs/phoenix-phoenix-cli--docs) that `phoenix deployment:build-envs` writes. The trusted deploy step then publishes the frontend, webhooks and assets.
 
 If the build fails, is cancelled or takes too long, `phoenix deploy` prints the end of the build log and exits with an error. `--no-wait` returns as soon as the build starts.
 

package/dist/docs/phoenix/testing.mdx

@@ -33,6 +33,14 @@ 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 and not-authenticated pages, 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. 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.

package/dist/domain/application/assistant/generate-assistant-prompt.js

@@ -1 +1 @@
-import{ASSISTANT_BUILT_IN_FORM_ELEMENTS as e}from"./assistant-form-elements.js";let t=[["Containers",["group","choice","choices"]],["Options",["option"]],["Inputs",["input"]]];export const generateAssistantPrompt=a=>{let n=Object.values(a.childRecipes??{}).some(e=>e.length>0),i=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),s=Object.values(a.fieldOptions??{}).some(e=>e.length>0),o=Object.keys(a.actions??{}).length>0,r=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||n||i||o,h=n||i||s,l=[...n?["`childRecipes` is what can be added to it"]:[],...i?["`replaceRecipes` what it can be replaced with"]:[],...s?["`<field>Options` the values a field accepts"]:[]],d=["`selected`",...(a.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",...r?[`- Use a mutation inside \`query\` to answer a what-if about a change ${h?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead."],...r?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...o?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...h?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${l.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...n||i?["recipes"]:[],...s?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${d} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...r?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(a.deletableTypes?.length??0)>0||i?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${r?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Links","- You may link an entity of the current configuration when you speak about that very entity: `[the left burner](entity:CookingTop-1)`. It helps the user find it in the configurator.",...h?["- Whenever you name recipes or options you read from `meta`, in a list, a table or a sentence, link each one: `[Single gas burner](recipe:KitchenRange-1/top/gas_single)` or `[Oak](option:Cabinet-2/finishOptions/oak)`. The link shows the user its picture or color and its description, so never draw previews yourself. The target is the entity id, the recipe group id or the options field you read, and the key or value, each encoded as in a URL."]:[]],["Replies","- Write Markdown only, never HTML: the panel does not render it."],["Forms","- To ask the user something they answer by picking or typing, end your reply with a form: a fenced code block with the language `form`. It holds only elements, written as lowercase tags with string attributes, without Markdown or text.","- Every element takes `label`, the text the user sees; on a container or an input it also names the answer. Options and inputs take `value`: an option sends it instead of its label, and an input starts with it.","- Options can also stand on their own, outside a `choice` or `choices`.","- An element or attribute not listed here, or an element other than an option inside a `choice` or `choices`, makes the whole form fail.","- The answer is the user's next message. Each container or input gives a line `Label: value`, or the bare value without a label; the lines of a labelled container are indented by two spaces under it, a `choices` lists each picked option on its own line, and `—` marks what was left unanswered.",'- Example: `<choice label="Plinth"><reply label="Black" /><reply label="Oak" /></choice>` is answered with `Plinth: Oak`.',...t.flatMap(([t,a])=>{let n=e.filter(({role:e})=>a.includes(e));return 0===n.length?[]:[`- ${t}:`,...n.map(e=>`  - \`${(({name:e,role:t,attributes:a})=>{let n=["label",..."option"===t||"input"===t?["value"]:[],...Object.keys(a)];return"option"===t||"input"===t?`<${e} ${n.join(" ")} />`:`<${e} ${n.join(" ")}>…</${e}>`})(e)}\`: ${e.description}`)]})],...a.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",a.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};
+import{ASSISTANT_BUILT_IN_FORM_ELEMENTS as e}from"./assistant-form-elements.js";let t=[["Containers",["group","choice","choices"]],["Options",["option"]],["Inputs",["input"]]];export const generateAssistantPrompt=a=>{let n=Object.values(a.childRecipes??{}).some(e=>e.length>0),s=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),i=Object.values(a.fieldOptions??{}).some(e=>e.length>0),o=Object.keys(a.actions??{}).length>0,r=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||n||s||o,h=n||s||i,l=[...n?["`childRecipes` is what can be added to it"]:[],...s?["`replaceRecipes` what it can be replaced with"]:[],...i?["`<field>Options` the values a field accepts"]:[]],d=["`selected`",...(a.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",...r?[`- Use a mutation inside \`query\` to answer a what-if about a change ${h?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead."],...r?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...o?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...h?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${l.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...n||s?["recipes"]:[],...i?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${d} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...r?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(a.deletableTypes?.length??0)>0||s?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${r?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Links","- You may link an entity of the current configuration when you speak about that very entity: `[the left burner](entity:CookingTop-1)`. It helps the user find it in the configurator.",...h?["- Whenever you name recipes or options you read from `meta`, in a list, a table or a sentence, link each one: `[Single gas burner](recipe:KitchenRange-1/top/gas_single)` or `[Oak](option:Cabinet-2/finishOptions/oak)`. The link shows the user its picture or color and its description, so never draw previews yourself. The target is the entity id, the recipe group id or the options field you read, and the key or value, each encoded as in a URL."]:[]],["Replies","- Write Markdown only, never HTML: the panel does not render it.","- An image, `![alt](path)`, is shown only when its path is relative."],["Forms","- To ask the user something they answer by picking or typing, end your reply with a form: a fenced code block with the language `form`. It holds only elements, written as lowercase tags with string attributes, without Markdown or text.","- Every element takes `label`, the text the user sees; on a container or an input it also names the answer. Options and inputs take `value`: an option sends it instead of its label, and an input starts with it.","- Options can also stand on their own, outside a `choice` or `choices`.","- An element or attribute not listed here, or an element other than an option inside a `choice` or `choices`, makes the whole form fail.","- The answer is the user's next message. Each container or input gives a line `Label: value`, or the bare value without a label; the lines of a labelled container are indented by two spaces under it, a `choices` lists each picked option on its own line, and `—` marks what was left unanswered.",'- Example: `<choice label="Plinth"><reply label="Black" /><reply label="Oak" /></choice>` is answered with `Plinth: Oak`.',"- The chat shows the answer as the user's own message, so a `value` reads as natural words, never as an id, key or code. Give `value` only when the label alone would be unclear as an answer, and map the answer's labels back to ids yourself.",...t.flatMap(([t,a])=>{let n=e.filter(({role:e})=>a.includes(e));return 0===n.length?[]:[`- ${t}:`,...n.map(e=>`  - \`${(({name:e,role:t,attributes:a})=>{let n=["label",..."option"===t||"input"===t?["value"]:[],...Object.keys(a)];return"option"===t||"input"===t?`<${e} ${n.join(" ")} />`:`<${e} ${n.join(" ")}>…</${e}>`})(e)}\`: ${e.description}`)]})],...a.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",a.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};

package/dist/domain/domain-runtime/spec/module-checks/element-registration.d.ts

@@ -26,15 +26,6 @@ export interface CustomPhoenixEntityElementProps {
     entityId: DomainEntityId<string>;
     children?: ReactNode;
 }
-export interface SystemElementRegistry {
-    layoutElements: Record<string, (props: PropsWithChildren) => JSX.Element>;
-    entityElements: Record<string, (props: CustomPhoenixEntityElementProps) => JSX.Element>;
-}
-/**
- * Internal registry for system-level elements registered at import time
- * via createPhoenixLayoutElement / createPhoenixEntityElement.
- */
-export declare const systemElementRegistry: SystemElementRegistry;
 type SchemaOfPhoenixLayoutElement<SCHEMA extends {
     kind: string;
     props?: Record<string, unknown>;
@@ -61,7 +52,12 @@ export interface PhoenixLayoutElementDefinition<SCHEMA extends {
     }>;
 }
 /**
- * For internal use in PHX only.
+ * Returns the component of a built-in layout element definition; it registers nothing. A layout
+ * element reaches the runtime only through a registration in `elements` or `defaultElements`.
+ *
+ * @deprecated Register a layout element with `createCustomPhoenixLayoutElement(name, component)`;
+ * the built-in ones are in `defaultConfiguratorElements` and `defaultAdminElements`. This API will
+ * be removed in a future version.
  */
 export declare const createPhoenixLayoutElement: <SCHEMA extends {
     kind: string;
@@ -95,7 +91,12 @@ export interface PhoenixEntityElementDefinition<SCHEMA extends {
     component: React.FunctionComponent<SCHEMA['props'] & CustomPhoenixEntityElementProps>;
 }
 /**
- * For internal use in PHX only.
+ * Returns the component of a built-in entity element definition; it registers nothing. An entity
+ * element reaches the runtime only through a registration in `elements` or `defaultElements`.
+ *
+ * @deprecated Register an entity element with `createCustomPhoenixEntityElement(name, component)`;
+ * the built-in ones are in `defaultConfiguratorElements` and `defaultAdminElements`. This API will
+ * be removed in a future version.
  */
 export declare const createPhoenixEntityElement: <SCHEMA extends {
     kind: string;

package/dist/domain/domain-runtime/spec/module-checks/element-registration.js

@@ -1 +1 @@
-import{SHARED_FOLDER_HINT as e,isRecord as t,resolveListModule as n}from"./project-modules.js";export const systemElementRegistry={layoutElements:{},entityElements:{}};export const createPhoenixLayoutElement=e=>(systemElementRegistry.layoutElements[e.schema.properties.kind.enum[0]]=e.component,e.component);export const createCustomPhoenixLayoutElement=(e,t)=>({type:"layout",name:e,element:t});export const createPhoenixEntityElement=e=>(systemElementRegistry.entityElements[e.schema.properties.kind.enum[0]]=e.component,e.component);export const createCustomPhoenixEntityElement=(e,t)=>({type:"entity",name:e,element:t});let o={expected:"an element registration, or an array of them",fix:`Create it with phx.frontend.createCustomPhoenixLayoutElement(...) or phx.frontend.createCustomPhoenixEntityElement(...), ${e}.`},r=e=>!!t(e)&&("icon"===e.type?Array.isArray(e.elements):("entity"===e.type||"layout"===e.type)&&"string"==typeof e.name&&"function"==typeof e.element);export const resolveElementModule=e=>n(e,o,r);export const resolveElementModules=e=>e.flatMap(resolveElementModule);
+import{SHARED_FOLDER_HINT as e,isRecord as t,resolveListModule as o}from"./project-modules.js";export const createPhoenixLayoutElement=e=>e.component;export const createCustomPhoenixLayoutElement=(e,t)=>({type:"layout",name:e,element:t});export const createPhoenixEntityElement=e=>e.component;export const createCustomPhoenixEntityElement=(e,t)=>({type:"entity",name:e,element:t});let n={expected:"an element registration, or an array of them",fix:`Create it with phx.frontend.createCustomPhoenixLayoutElement(...) or phx.frontend.createCustomPhoenixEntityElement(...), ${e}.`},r=e=>!!t(e)&&("icon"===e.type?Array.isArray(e.elements):("entity"===e.type||"layout"===e.type)&&"string"==typeof e.name&&"function"==typeof e.element);export const resolveElementModule=e=>o(e,n,r);export const resolveElementModules=e=>e.flatMap(resolveElementModule);

package/dist/domain/domain-runtime/spec/module-checks/index.d.ts

@@ -1,4 +1,4 @@
-export { type PhoenixEntityElementProps, type PhoenixEntityElementRegistration, type PhoenixLayoutElementRegistration, type PhoenixIconRegistration, type ElementRegistration, type CustomPhoenixEntityElementProps, type PhoenixLayoutElementDefinition, type PhoenixEntityElementDefinition, type CreateCustomPhoenixLayoutElement, type CreateCustomPhoenixEntityElement, createPhoenixLayoutElement, createPhoenixEntityElement, createCustomPhoenixLayoutElement, createCustomPhoenixEntityElement, resolveElementModule, resolveElementModules, systemElementRegistry, } from './element-registration.js';
+export { type PhoenixEntityElementProps, type PhoenixEntityElementRegistration, type PhoenixLayoutElementRegistration, type PhoenixIconRegistration, type ElementRegistration, type CustomPhoenixEntityElementProps, type PhoenixLayoutElementDefinition, type PhoenixEntityElementDefinition, type CreateCustomPhoenixLayoutElement, type CreateCustomPhoenixEntityElement, createPhoenixLayoutElement, createPhoenixEntityElement, createCustomPhoenixLayoutElement, createCustomPhoenixEntityElement, resolveElementModule, resolveElementModules, } from './element-registration.js';
 export { type PhoenixHandlerDefinition, type SystemPhoenixHandlerDefinition, type PhoenixHandlerRegistration, type SystemPhoenixHandlerRegistration, type SystemPhoenixAsyncHandlerDefinition, type SystemPhoenixAsyncHandlerRegistration, type HandlerRegistration, type CreatePhoenixHandler, createPhoenixHandler, createSystemPhoenixHandler, createSystemPhoenixAsyncHandler, resolveHandlerModule, resolveHandlerModules, } from './handler-registration.js';
 export { type ProjectModule } from './project-modules.js';
 export { resolveActionModules } from './resolve-action-modules.js';

package/dist/domain/domain-runtime/spec/module-checks/index.js

@@ -1 +1 @@
-export{createPhoenixLayoutElement,createPhoenixEntityElement,createCustomPhoenixLayoutElement,createCustomPhoenixEntityElement,resolveElementModule,resolveElementModules,systemElementRegistry}from"./element-registration.js";export{createPhoenixHandler,createSystemPhoenixHandler,createSystemPhoenixAsyncHandler,resolveHandlerModule,resolveHandlerModules}from"./handler-registration.js";export{resolveActionModules}from"./resolve-action-modules.js";export{resolveComponentOpticModules}from"./resolve-component-optic-modules.js";export{resolveExpressionModules}from"./resolve-expression-modules.js";export{resolveImportedTransformers,resolveTransformerModule,resolveTransformerModules}from"./resolve-imported-transformers.js";export{resolveInvariantModules}from"./resolve-invariant-modules.js";
+export{createPhoenixLayoutElement,createPhoenixEntityElement,createCustomPhoenixLayoutElement,createCustomPhoenixEntityElement,resolveElementModule,resolveElementModules}from"./element-registration.js";export{createPhoenixHandler,createSystemPhoenixHandler,createSystemPhoenixAsyncHandler,resolveHandlerModule,resolveHandlerModules}from"./handler-registration.js";export{resolveActionModules}from"./resolve-action-modules.js";export{resolveComponentOpticModules}from"./resolve-component-optic-modules.js";export{resolveExpressionModules}from"./resolve-expression-modules.js";export{resolveImportedTransformers,resolveTransformerModule,resolveTransformerModules}from"./resolve-imported-transformers.js";export{resolveInvariantModules}from"./resolve-invariant-modules.js";

package/dist/domain/domain-runtime/spec/selectors.js

@@ -1 +1 @@
-import{createSelector as e}from"@salsita-ai/common/utils";import{buildAssistantManifest as t}from"../../application/assistant/index.js";import{systemElementRegistry as n}from"./module-checks/index.js";export const createSpecSelectors=a=>{let{getState:s}=a,r=e.withTypes(),l=r([r.leaf(e=>e.spec)],e=>e),o=r([l],e=>e.version),i=r([l],e=>e.baseResourcesUrl),m=r([l],e=>e.configurator),g=r([l],e=>e.dataConfig),p=r([l],e=>e.chunks),d=r([l],e=>e.publishedDataHash),c=r([l],e=>e.initialPublishedData),u=r([l],e=>e.canCreate),h=r([l],e=>e.enableAdminRelease),y=r([l],e=>e.textLanguages),f=r([m],e=>e.modelVersion),C=r([l],e=>e.admin),E=r([C],e=>e.preset),x=r([C],e=>e.modelVersion),A=r([m],e=>e.theme),b=r([m],e=>e.assistant),H=r([b],e=>e?t(e):null),D=r([m],e=>e.factory),P=r([C],e=>e.factory),S=r([m],e=>e.componentOptics),w=r([C],e=>e.componentOptics),O=r([m],e=>e.appLoader),T=r([m],e=>e.preview),V=r([m],e=>e.alwaysExpand),L=r([m],e=>e.presets),R=r([m],e=>e.deploymentQueryDisabled),U=r([m],e=>e.prefetchTextureUrls),k=r([m],e=>e.handlerHashes),v=r([m],e=>e.handlers),j=r([v,k],(e,t)=>({...(e=>{let t={},n={},a={};for(let s of e)"phoenix"===s.type&&(t[s.name]=s.handler),"system"===s.type&&(n[s.name]=s.handler),"system-async"===s.type&&(a[s.name]=s.handler);return{handlers:t,systemHandlers:n,systemAsyncHandlers:a}})(e),hashes:t})),F=r([m],e=>e.elementHashes),M=r([m],e=>e.elements),Q=r([m],e=>e.defaultElements),B=r([Q,M,F],(e,t,a)=>({...(e=>{let t={},a={};for(let n of e)"layout"===n.type&&(t[n.name]=n.element),"entity"===n.type&&(a[n.name]=n.element);return{entityElements:{...n.entityElements,...a},layoutElements:{...n.layoutElements,...t}}})([...e,...t]),hashes:a}));return{selectSpec:l,selectVersion:o,selectBaseResourcesUrl:i,selectConfiguratorSpec:m,selectConfiguratorModelVersion:f,selectAdminSpec:C,selectAdminPreset:E,selectAdminModelVersion:x,selectThemeOptions:A,selectAssistant:H,selectConfiguratorFactory:D,selectAdminFactory:P,selectConfiguratorComponentOptics:S,selectAdminComponentOptics:w,selectAppLoader:O,selectPreview:T,selectAlwaysExpand:V,selectPresetSeed:L,selectDeploymentQueryDisabled:R,selectPrefetchTextureUrls:U,selectTextLanguages:y,selectHandlerHashes:k,selectHandlers:v,selectHandlerSlots:j,selectElementHashes:F,selectElements:M,selectElementSlots:B,selectDataConfig:g,selectChunks:p,selectPublishedDataHash:d,selectInitialPublishedData:c,selectCanCreate:u,selectEnableAdminRelease:h,getVersion:()=>o(s()),getBaseResourcesUrl:()=>i(s()),getConfiguratorSpec:()=>m(s()),getConfiguratorModelVersion:()=>f(s()),getAdminSpec:()=>C(s()),getAdminPreset:()=>E(s()),getAdminModelVersion:()=>x(s()),getThemeOptions:()=>A(s()),getAssistant:()=>H(s()),getConfiguratorFactory:()=>D(s()),getAdminFactory:()=>P(s()),getConfiguratorComponentOptics:()=>S(s()),getAdminComponentOptics:()=>w(s()),getAppLoader:()=>O(s()),getPreview:()=>T(s()),getAlwaysExpand:()=>V(s()),getPresetSeed:()=>L(s()),getDeploymentQueryDisabled:()=>R(s()),getPrefetchTextureUrls:()=>U(s()),getTextLanguages:()=>y(s()),getHandlerHashes:()=>k(s()),getHandlers:()=>v(s()),getHandlerSlots:()=>j(s()),getElementHashes:()=>F(s()),getElements:()=>M(s()),getElementSlots:()=>B(s()),getDataConfig:()=>g(s()),getChunks:()=>p(s()),getPublishedDataHash:()=>d(s()),getInitialPublishedData:()=>c(s()),getCanCreate:()=>u(s()),getEnableAdminRelease:()=>h(s())}};
+import{createSelector as e}from"@salsita-ai/common/utils";import{buildAssistantManifest as t}from"../../application/assistant/index.js";export const createSpecSelectors=a=>{let{getState:n}=a,s=e.withTypes(),r=s([s.leaf(e=>e.spec)],e=>e),l=s([r],e=>e.version),o=s([r],e=>e.baseResourcesUrl),i=s([r],e=>e.configurator),g=s([r],e=>e.dataConfig),m=s([r],e=>e.chunks),p=s([r],e=>e.publishedDataHash),d=s([r],e=>e.initialPublishedData),c=s([r],e=>e.canCreate),u=s([r],e=>e.enableAdminRelease),h=s([r],e=>e.textLanguages),y=s([i],e=>e.modelVersion),f=s([r],e=>e.admin),C=s([f],e=>e.preset),A=s([f],e=>e.modelVersion),b=s([i],e=>e.theme),x=s([i],e=>e.assistant),E=s([x],e=>e?t(e):null),H=s([i],e=>e.factory),D=s([f],e=>e.factory),P=s([i],e=>e.componentOptics),S=s([f],e=>e.componentOptics),w=s([i],e=>e.appLoader),O=s([i],e=>e.preview),T=s([i],e=>e.alwaysExpand),V=s([i],e=>e.presets),L=s([i],e=>e.deploymentQueryDisabled),R=s([i],e=>e.prefetchTextureUrls),U=s([i],e=>e.handlerHashes),v=s([i],e=>e.handlers),k=s([v,U],(e,t)=>({...(e=>{let t={},a={},n={};for(let s of e)"phoenix"===s.type&&(t[s.name]=s.handler),"system"===s.type&&(a[s.name]=s.handler),"system-async"===s.type&&(n[s.name]=s.handler);return{handlers:t,systemHandlers:a,systemAsyncHandlers:n}})(e),hashes:t})),F=s([i],e=>e.elementHashes),M=s([i],e=>e.elements),Q=s([i],e=>e.defaultElements),j=s([Q,M,F],(e,t,a)=>({...(e=>{let t={},a={};for(let n of e)"layout"===n.type&&(t[n.name]=n.element),"entity"===n.type&&(a[n.name]=n.element);return{entityElements:a,layoutElements:t}})([...e,...t]),hashes:a}));return{selectSpec:r,selectVersion:l,selectBaseResourcesUrl:o,selectConfiguratorSpec:i,selectConfiguratorModelVersion:y,selectAdminSpec:f,selectAdminPreset:C,selectAdminModelVersion:A,selectThemeOptions:b,selectAssistant:E,selectConfiguratorFactory:H,selectAdminFactory:D,selectConfiguratorComponentOptics:P,selectAdminComponentOptics:S,selectAppLoader:w,selectPreview:O,selectAlwaysExpand:T,selectPresetSeed:V,selectDeploymentQueryDisabled:L,selectPrefetchTextureUrls:R,selectTextLanguages:h,selectHandlerHashes:U,selectHandlers:v,selectHandlerSlots:k,selectElementHashes:F,selectElements:M,selectElementSlots:j,selectDataConfig:g,selectChunks:m,selectPublishedDataHash:p,selectInitialPublishedData:d,selectCanCreate:c,selectEnableAdminRelease:u,getVersion:()=>l(n()),getBaseResourcesUrl:()=>o(n()),getConfiguratorSpec:()=>i(n()),getConfiguratorModelVersion:()=>y(n()),getAdminSpec:()=>f(n()),getAdminPreset:()=>C(n()),getAdminModelVersion:()=>A(n()),getThemeOptions:()=>b(n()),getAssistant:()=>E(n()),getConfiguratorFactory:()=>H(n()),getAdminFactory:()=>D(n()),getConfiguratorComponentOptics:()=>P(n()),getAdminComponentOptics:()=>S(n()),getAppLoader:()=>w(n()),getPreview:()=>O(n()),getAlwaysExpand:()=>T(n()),getPresetSeed:()=>V(n()),getDeploymentQueryDisabled:()=>L(n()),getPrefetchTextureUrls:()=>R(n()),getTextLanguages:()=>h(n()),getHandlerHashes:()=>U(n()),getHandlers:()=>v(n()),getHandlerSlots:()=>k(n()),getElementHashes:()=>F(n()),getElements:()=>M(n()),getElementSlots:()=>j(n()),getDataConfig:()=>g(n()),getChunks:()=>m(n()),getPublishedDataHash:()=>p(n()),getInitialPublishedData:()=>d(n()),getCanCreate:()=>c(n()),getEnableAdminRelease:()=>u(n())}};

package/dist/editor/Editor.d.ts

@@ -32,6 +32,13 @@ export interface EditorProps {
     readonly mockTemplates?: MockTemplateDefinition[];
     /** If true, automatically apply the first template when templates are initialized */
     readonly autoApplyTemplate?: boolean;
+    /**
+     * Key of the mock template to apply on mount, in place of the template stored for this page.
+     * Applying it does not store it, so it never changes what an editor without this prop opens.
+     * An unknown key logs a warning and falls back to the stored template, or to the first template
+     * when `autoApplyTemplate` is set.
+     */
+    readonly initialTemplateKey?: string;
     /** Key used to scope localStorage template persistence (e.g. environment slug) */
     readonly environmentKey?: string;
     /** Web component tag name for creating and discovering reflection systems. */