@salsita-ai/sdk 0.50.0-develop.f03b563886 → 0.50.0-develop.f16492b14e

package/dist/application-spec/generate-application/code/templates/skills/phoenix-variants-skill.js

@@ -1,6 +1,6 @@
-import{renderAgentSkill as e}from"./agent-skill.js";let t=`## When to Offer Options
+import{renderAgentSkill as e}from"./agent-skill.js";import{sdkGuidanceSections as t}from"./sdk-content.js";let n=`## When to Offer Options
 - Offer options when the answer is a matter of taste or brand and the supplied materials do not settle it.
 - Do not offer options for facts (dimensions, prices, rules), for something the user already decided, or to avoid a decision you can make yourself and state.
 - One decision per set, one set open at a time. Vary one thing and keep everything else identical.
 - Usually offer two to four options; the system has no fixed option limit. Original is always available as the captured baseline.
-- Make the options differ in a way the UI or scene can show. Three sheens of one matte wood in soft light look the same.`;export const generatePhoenixVariantsSkill=()=>e({name:"phoenix-variants",description:"Showing the user a few options over the dev preview and getting their pick back, with the phoenix variants command. Use when a visual or interaction decision has several reasonable answers and the taste of the user decides it, such as a shape, a material setting, lighting, an environment, a control or a flow.",sections:[t,"## Choose the Kind of Option\n- Use `<id>.variant.js` to edit real frontend project files on top of one captured baseline. Use `<id>.html` for a standalone branding, layout or flow proposal rendered in an iframe.\n- Use the same mechanism for controls, layout, brand, lights, visuals, materials, positions, components, elements and transformers.\n- Keep the model, schemas, data, assistant server settings, webhooks and code shared with them, dependencies, environment and uploaded assets unchanged. The preview rejects changes needing server preparation.\n- Options reuse the already loaded configurator, one at a time. Variant transactions bypass file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.",'## Write the Options\n- One folder per set: `.phoenix/variants/<name>/`, one script or HTML file per option. HTML and scripts can share a set, but option ids must be unique. Keep HTML self-contained. This folder survives rebuilds and is never committed.\n- For HTML, set `<title>` and `<meta name="description" content="...">`; choosing a page changes no source files.\n- For scripts, export `title` and `description` as plain string literals, and a default function `({ read, write, remove }) => {}`; it may be async.\n- `read(path)` returns the original baseline file contents. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Paths are relative to the project root.\n- Scripts run once per selection in the browser and collect edits. Phoenix validates and writes the whole batch locally; it owns backups and undo. Do not perform your own filesystem or network operations.\n- Supported edits are YAML in `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants run on the server too, so they cannot be edited.\n- Every option starts from the same baseline. Original restores it; switching restores files the previous option alone changed.\n- Keep the working tree untouched while comparing. Phoenix never overwrites an edit made outside the preview: it refuses to switch options over one, and when the comparison ends it leaves that file as it is and warns in the dev log.\n- Name options in the user\'s product language; explain what changes in one line.','## Run It and Wait\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the user the options are open there.\n- Put the title and the description in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside them as `\'\\\'\'`; in PowerShell, double it instead.\n- The command waits for the answer, 540 seconds unless `--timeout <seconds>` says otherwise, so give it a command timeout longer than that. It prints JSON:\n  - `"status": "chosen"` with `choice` (the option id, or `null` for Original) and `label`;\n  - `"status": "waiting"` when the wait ran out. The options stay open: run the same command again, or end your turn and run it when the user is back. An answer given in between is returned by the next run;\n  - `"status": "closed"` when the preview was closed without an answer.\n- `pnpm phoenix variants --close` closes the open set when you give up on it.\n- `--port <port>` names the editor WebSocket port when `phoenix dev` does not use 3020.\n- The live configurator keeps its current configuration. Interactions still change it; restoring source files does not undo configuration changes.',"## Use the Answer\n- **Chosen:** a script's exact file edits remain in the project. For an HTML choice, implement the selected proposal using the SDK and compare the result with the page. With `choice: null`, the user chose Original and the baseline remains. Verify the result using `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the user anything that came out differently.\n- Record the decision and its reason where the project keeps its decisions, such as `configurator-spec.md`.\n- The user confirms Original or another option; Escape and the backdrop do not close the comparison. The agent can use `--close` to restore baseline source files without an answer. The folder is removed once the user answers. Pass `--keep` when you still need the files to build from, and remove the folder yourself afterwards."]});
+- Make the options differ in a way the UI or scene can show. Three sheens of one matte wood in soft light look the same.`;export const generatePhoenixVariantsSkill=()=>e({name:"phoenix-variants",description:"Showing the user a few options over the dev preview and getting their pick back, with the phoenix variants command. Use when a visual or interaction decision has several reasonable answers and the taste of the user decides it, such as a shape, a material setting, lighting, an environment, a control or a flow.",sections:[t.packageManager,n,"## Choose the Kind of Option\n- Use `<id>.variant.js` to edit real frontend project files on top of one captured baseline. Use `<id>.html` for a standalone branding, layout or flow proposal rendered in an iframe.\n- Use the same mechanism for controls, layout, brand, lights, visuals, materials, positions, components, elements and transformers.\n- Keep the model, schemas, data, assistant server settings, webhooks and code shared with them, dependencies, environment and uploaded assets unchanged. The preview rejects changes needing server preparation.\n- Options reuse the already loaded configurator, one at a time. Variant transactions bypass file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.",'## Write the Options\n- One folder per set: `.phoenix/variants/<name>/`, one script or HTML file per option. HTML and scripts can share a set, but option ids must be unique. Keep HTML self-contained. This folder survives rebuilds and is never committed.\n- For HTML, set `<title>` and `<meta name="description" content="...">`; choosing a page changes no source files.\n- For scripts, export `title` and `description` as plain string literals, and a default function `({ read, write, remove }) => {}`; it may be async.\n- `read(path)` returns the original baseline file contents. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Paths are relative to the project root.\n- Scripts run once per selection in the browser and collect edits. Phoenix validates and writes the whole batch locally; it owns backups and undo. Do not perform your own filesystem or network operations.\n- Supported edits are YAML in `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants run on the server too, so they cannot be edited.\n- Every option starts from the same baseline. Original restores it; switching restores files the previous option alone changed.\n- Keep the working tree untouched while comparing. Phoenix never overwrites an edit made outside the preview: it refuses to switch options over one, and when the comparison ends it leaves that file as it is and warns in the dev log.\n- Name options in the user\'s product language; explain what changes in one line.','## Run It and Wait\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the user the options are open there.\n- Put the title and the description in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside them as `\'\\\'\'`; in PowerShell, double it instead.\n- The command waits for the answer, 540 seconds unless `--timeout <seconds>` says otherwise, so give it a command timeout longer than that. It prints JSON:\n  - `"status": "chosen"` with `choice` (the option id, or `null` for Original) and `label`;\n  - `"status": "waiting"` when the wait ran out. The options stay open: run the same command again, or end your turn and run it when the user is back. An answer given in between is returned by the next run;\n  - `"status": "closed"` when the preview was closed without an answer.\n- `pnpm phoenix variants --close` closes the open set when you give up on it.\n- `--port <port>` names the editor WebSocket port when `phoenix dev` does not use 3020.\n- The live configurator keeps its current configuration. Interactions still change it; restoring source files does not undo configuration changes.',"## Use the Answer\n- **Chosen:** a script's exact file edits remain in the project. For an HTML choice, implement the selected proposal using the SDK and compare the result with the page. With `choice: null`, the user chose Original and the baseline remains. Verify the result using `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the user anything that came out differently.\n- Record the decision and its reason where the project keeps its decisions, such as `configurator-spec.md`.\n- The user confirms Original or another option; Escape and the backdrop do not close the comparison. The agent can use `--close` to restore baseline source files without an answer. The folder is removed once the user answers. Pass `--keep` when you still need the files to build from, and remove the folder yourself afterwards."]});

package/dist/application-spec/generate-application/code/templates/skills/sdk-content.d.ts

@@ -1,20 +1,29 @@
 /**
  * Documented Phoenix SDK guidance, one Markdown section per entry.
  *
- * The agent guidance shipped into generated projects — the starter `AGENTS.md` and the Phoenix-owned
- * agent skills — is composed from these sections, so each documented fact has exactly one home and
- * the generated files differ only in which sections they carry.
+ * The agent guidance shipped into generated projects — the Phoenix-owned agent skills — is composed
+ * from these sections, so each documented fact has exactly one home and the generated files differ
+ * only in which sections they carry.
  */
 export declare const sdkGuidanceSections: {
-    /** Opening description of what a Phoenix configurator project is. */
-    readonly projectIntro: `## Phoenix Configurator Project
-
-Declarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.`;
-    /** The three everyday `phoenix` package scripts. */
+    /**
+     * How to run the commands the skills write for pnpm through the package manager the project uses. Every skill
+     * that names a command carries it, because an agent loads each skill on its own.
+     */
+    readonly packageManager: `## Package Manager
+The project installs with its own package manager, and the commands in this skill are written for pnpm. Run them through the package manager the project uses, which the lockfile in the project root names:
+- \`pnpm-lock.yaml\`: \`pnpm phoenix <command>\`, \`pnpm install\`, \`pnpm add <package>\`
+- \`package-lock.json\`: \`npx phoenix <command>\`, \`npm install\`, \`npm install <package>\`
+- \`yarn.lock\`: \`yarn phoenix <command>\`, \`yarn install\`, \`yarn add <package>\`
+- \`bun.lock\` or \`bun.lockb\`: \`bunx phoenix <command>\`, \`bun install\`, \`bun add <package>\`
+
+Without a lockfile, use the package manager the \`packageManager\` field of \`package.json\` names, or ask the user.`;
+    /** The everyday `phoenix` commands, and the one that brings `package.json` in line with the SDK. */
     readonly buildCommands: `## Build Commands
 - \`pnpm phoenix build\` — Full production build
 - \`pnpm phoenix dev\` — Development mode with hot reload
-- \`pnpm phoenix sync\` — Sync generated files without full build`;
+- \`pnpm phoenix sync\` — Sync generated files without full build
+- \`pnpm phoenix deps\` — Add the SDK's missing peer dependencies to \`package.json\` and move out-of-range ones into the SDK's range; it installs nothing, so install after it`;
     /** Where `phoenix dev` writes its log and how to read it. */
     readonly devLogs: `## Dev Logs
 - \`pnpm phoenix dev\` writes all logs to \`.phoenix/phoenix-dev.log\`
@@ -30,8 +39,22 @@ Declarative 3D product configurator built with Phoenix SDK. Domain model defined
 - \`src/transformers/\` — Automatic state fixers (\`phx.frontend.transformerBuilder\`)
 - \`src/components/\` — ECS system components (\`phx.domain.attachComponent.withEntity()\`)
 - \`src/elements/\` — Page-level React components (\`phx.frontend.createCustomPhoenixLayoutElement()\`)
+  - \`ConfiguratorLayout\`: a layout element with this name replaces everything the built-in layout renders for a loaded configuration, in owner and read mode, finalization included. Prefer arranging the spec's layout components; write one for shell-level changes, such as moving the sidebar or adding an area the built-in layout has no place for
+    - Mount \`LayoutSlots.SharedCanvas\` (from \`@salsita-ai/sdk/configurator\`) in a positioned root covering the page; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call \`phx.frontend.useSceneSafeArea()\` and put \`containerRef\` on the element covering the whole canvas and \`safeAreaRef\` on the region the UI leaves free, with \`pointerEvents: 'none'\`, so the camera frames the scene there
+    - Sidebar moved, contents as the spec configures them: mount \`LayoutSlots.DesktopSidebar\` in a positioned container that sets its size, with \`side="start"\` on the left; \`docs/layouts/sidebar/in-a-custom-layout.mdx\` is the whole layout
+    - Your own UI: "Hooks for a Project Layout" in \`docs/phoenix/configurator-interface.mdx\` lists the hooks with what each returns (\`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx\`), \`docs/phoenix/layout-slots.mdx\` the built-in pieces you can still mount, and \`docs/layouts/custom-layout.mdx\` is a worked example. Call the hooks as \`phx.frontend.useX()\`; besides those below, these are often needed: \`usePreview()\` (\`isPreview\` while the preview start screen shows), \`useCloseAction()\` (the host's close action or \`null\`), \`useActiveViewports()\` (the container's breakpoints, \`null\` until measured, \`desktop\` above 768 px: the desktop/phone switch), \`useResolveLocalizable()\` and \`useLocalizable(text)\` (spec texts to strings), \`useIsCloningAllowed()\` (a read-mode "edit a copy" action with \`LayoutSlots.CloneToEditDialog\`)
+    - Undo and redo: \`phx.frontend.useUndoRedo()\` returns \`{ canUndo, canRedo, undo, redo }\`; disable each button from \`canUndo\`/\`canRedo\`
+    - Tabs: \`phx.frontend.useTabNavigation()\` returns \`{ source, tabs, activeTab, select }\` for the spec's \`sidebarTabs\` (of the selected entity) or \`horizontalTabs\`; render \`tabs\` (each \`{ index, label, icon, state, isActive }\`, \`icon\` a PhxIcon name) and call \`select(tab.index)\` on click. Pass \`{ source: 'sidebarTabs' }\` or \`{ source: 'horizontalTabs' }\` when the layout shows one kind only. Not \`LayoutSlots.useSidebarTabs()\`: it serves the built-in sidebar and returns no tabs while its summary shows
+    - Steps: \`phx.frontend.useStepNavigation()\` returns \`{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }\` for the spec's \`navigationSteps\`; render \`steps\` (each \`{ index, label, state, status }\`, \`status\` \`'complete' | 'active' | 'upcoming'\`), call \`next()\`/\`previous()\` for Back and Next and \`goTo(step.index)\` from a stepper. It enforces no order and no validity: enable only \`'complete'\` steps for an "earlier steps only" stepper, and to block moving on while the configuration has a problem, require \`phx.frontend.useStateValidity().severity !== 'warning'\` besides \`canGoNext\`: a change with a \`fixable\` or \`fatal\` violation is rejected, so the configuration is never invalid, and a \`warning\` is the problem that stays (it blocks finalizing too). \`useSteps\` and \`useHasSteps\` from \`@salsita-ai/sdk/configurator\` are deprecated
+    - Messages: mount \`LayoutSlots.Services\` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with \`phx.frontend.useConfiguratorMessages(onMessage)\`, not both. A failed save arrives as \`saveError\`, the next successful save as \`saveRecovery\`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (\`LayoutSlots.DesktopSnackbarsRoot\` or \`LayoutSlots.MobileSnackbarsRoot\`): errors of the built-in actions are always snackbars
+    - Finalize over the spec's \`finalizeAction\` components, each naming a handler registered with \`phx.frontend.createPhoenixHandler\`: \`phx.frontend.useFinalizeActions()\` returns \`{ actions, primary, secondary, disabled, hints }\`; render \`primary\` (and \`secondary\` in a menu or list) in a loop, each action \`{ key, label, title, icon, run, isPending, error, disabled }\`, and call \`action.run()\` on click (its promise never rejects; show \`action.error\` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, \`phx.frontend.useFinalizeAction(handler)\` in a component wrapped in \`PhoenixHandlerBoundary\` (from \`@salsita-ai/sdk/react\`) works too; \`FinalizeActions\` (from \`@salsita-ai/sdk/configurator\`) mounts the built-in buttons. \`finalizePage\` and \`finalizeButton\` are legacy
+    - Read mode and fullscreen are the layout's job, no hook enforces them (\`useUndoRedo\`, \`useFinalizeActions\` and \`useStepNavigation\` included): hide undo, redo, finalization and whatever else a viewer must not change while \`phx.frontend.useAccessService().accessInfo.viewMode\` is \`true\` (tabs are navigation, so a viewer may switch them), and remove panels while \`phx.frontend.useIsFullscreenActive()\` is set; \`phx.frontend.useSetFullscreen()\` returns its setter
+  - \`ConfigurationNotFoundPage\`: \`phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)\` replaces the "configuration not accessible" page; show a way back only when the optional \`onBack\` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page
+  - \`ConfiguratorErrorPage\`: \`phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)\` replaces the production error page; \`reason\` is \`uncaughtError\` or \`presetCreationFailed\`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: \`createCustomPhoenixLayoutElement\` with the name works too, but types the component as taking only \`children\`, so the typed props do not compile there in a strict project
+  - \`AppLoaderContent\`: \`phx.frontend.createAppLoader(({ phases }) => …)\` replaces what the loading overlay shows (each phase \`{ id, label?, progress? }\`, the list possibly empty); Phoenix keeps the overlay itself
+  - Assistant form elements: an element declared under \`assistant.formElements\` (\`description\`, \`role\`, scalar \`attributes\` beside the built-in \`label\`, a \`value\` included, \`required\`) is the default export \`phx.frontend.createAssistantFormElement('name', Component)\` of one file; the name types the component's props by its role (\`AssistantFormElementProps<'name'>\`): an option reports its answer with \`onSelect(answer)\`, an input with \`onChange(state, answer)\`; and the application does not start while a declared element has no registration or a registration no declaration
 - \`src/handlers/\` — Event & lifecycle handlers
-- \`src/webhooks/\` — Server-side webhook handlers (\`phx.webhooks.*Builder\`)
+- \`src/webhooks/\` — Server-side webhook handlers (\`phx.webhooks.*Builder\`); the webhook is the default export of \`src/webhooks/index.ts\`, which you create when the project needs its own handlers. Without it, generation continues with a built-in webhook that answers only anonymous auth; enabling \`useAuthHook\` or \`useClerk\` reports \`AUTH_WITHOUT_PROJECT_WEBHOOK\`. Add the entry with the required Clerk or custom auth handlers, or disable unintended auth settings
 - \`src/migrations/\` — Schema version migrations (v*.ts)
 - \`src/locales/\` — Locale catalogs (authored .po sources; compiled .ts, do not edit)
 - \`src/admin/\` — Admin interface (mirrors main src/ structure)
@@ -70,15 +93,16 @@ The default export must be what the folder's phx factory returns (for example \`
     /** Which components and handlers are bundled into the webhook. */
     readonly webhookMembership: `## Webhook Membership
 - User-authored components, admin components, and handlers are frontend-only by default.
-- A handler that registers \`createMapPublishedRevisionDataHandler\`, \`createMapPublishedChunkedDataHandler\`, \`createDataRowValidatorHandler\`, or \`createSheetValidatorHandler\` is included in the webhook automatically.
+- A handler that registers \`phx.domain.createAssistantSetupHandler\`, \`createMapPublishedRevisionDataHandler\`, \`createMapPublishedChunkedDataHandler\`, \`createDataRowValidatorHandler\`, or \`createSheetValidatorHandler\` is included in the webhook automatically.
+- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false; screenshot views allow descriptions. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.
 - To include another component or handler in the webhook, put \`'use webhook'\` as its first statement (leading comments are allowed).
 - A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (\`application\`, \`admin\`, \`configurator\`, \`editor\`, \`react\`, \`ui\`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.
 - Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.`;
     /** Generated files a project must not edit. */
     readonly doNotEdit: `## Do Not Edit
-- \`.phoenix/\` directory — completely regenerated on each build. The one exception is \`.phoenix/variants/\`, where the \`phoenix-variants\` skill has you write option files; a rebuild keeps it
-- \`tsconfig.json\`, \`eslint.config.js\`, \`prettier.config.js\`, \`.prettierignore\`, \`.linguirc\`, \`.nvmrc\`
-- \`src/locales/\` .ts files — compiled from .po files`;
+- \`.phoenix/\` directory — completely regenerated on each build. The one exception is \`.phoenix/variants/\`, where the \`phoenix-variants\` skill has you write option files; a rebuild keeps it. The project's TypeScript settings come from \`.phoenix/tsconfig.json\`; the root \`tsconfig.json\` is the project's and extends it. \`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; use relative imports
+- \`src/locales/\` .ts files — compiled from .po files
+- \`phoenix\` and \`phoenix-*\` folders under \`.claude/skills/\` and \`.agents/skills/\` — Phoenix rewrites its skills on every sync, removes anything else inside their folders and removes any other \`phoenix-*\` skill folder. To customise a skill, copy it to a folder whose name does not start with \`phoenix\``;
     /** When and how a deployed domain model gets a new version and a migration, with the recipe for replacing the starter. */
     readonly modelVersioning: `## Version the Domain Model Once It Is Deployed
 A deployed model version cannot change, because saved configurations depend on it. \`pnpm phoenix deploy\` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: \`model.latest\` is always the highest numbered version plus one, so a spec with only \`latest\` is v1, and \`applicationVersion\` plays no part. \`pnpm phoenix dev\` accepts every model change, so a working preview does not show that the deploy will pass.

package/dist/application-spec/generate-application/code/templates/skills/sdk-content.js

@@ -1,12 +1,10 @@
-export const sdkGuidanceSections={projectIntro:`## Phoenix Configurator Project
-
-Declarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.`,buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/actions/` — Domain operations declared under `actions:` in the spec (`phx.domain.implementActions()`), run by controls and exposed to the assistant\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT, except the option files in `.phoenix/variants/`)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Actions = named domain operations (`actions:` in YAML with `params` and `result` schemas), implemented in src/actions/, prepared through `actionSystem.prepareAction()` and exposed as assistant mutations through `assistant.actions`\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
+export const sdkGuidanceSections={packageManager:"## Package Manager\nThe project installs with its own package manager, and the commands in this skill are written for pnpm. Run them through the package manager the project uses, which the lockfile in the project root names:\n- `pnpm-lock.yaml`: `pnpm phoenix <command>`, `pnpm install`, `pnpm add <package>`\n- `package-lock.json`: `npx phoenix <command>`, `npm install`, `npm install <package>`\n- `yarn.lock`: `yarn phoenix <command>`, `yarn install`, `yarn add <package>`\n- `bun.lock` or `bun.lockb`: `bunx phoenix <command>`, `bun install`, `bun add <package>`\n\nWithout a lockfile, use the package manager the `packageManager` field of `package.json` names, or ask the user.",buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build\n- `pnpm phoenix deps` — Add the SDK's missing peer dependencies to `package.json` and move out-of-range ones into the SDK's range; it installs nothing, so install after it",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/actions/` — Domain operations declared under `actions:` in the spec (`phx.domain.implementActions()`), run by controls and exposed to the assistant\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n  - `ConfiguratorLayout`: a layout element with this name replaces everything the built-in layout renders for a loaded configuration, in owner and read mode, finalization included. Prefer arranging the spec's layout components; write one for shell-level changes, such as moving the sidebar or adding an area the built-in layout has no place for\n    - Mount `LayoutSlots.SharedCanvas` (from `@salsita-ai/sdk/configurator`) in a positioned root covering the page; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call `phx.frontend.useSceneSafeArea()` and put `containerRef` on the element covering the whole canvas and `safeAreaRef` on the region the UI leaves free, with `pointerEvents: 'none'`, so the camera frames the scene there\n    - Sidebar moved, contents as the spec configures them: mount `LayoutSlots.DesktopSidebar` in a positioned container that sets its size, with `side=\"start\"` on the left; `docs/layouts/sidebar/in-a-custom-layout.mdx` is the whole layout\n    - Your own UI: \"Hooks for a Project Layout\" in `docs/phoenix/configurator-interface.mdx` lists the hooks with what each returns (`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx`), `docs/phoenix/layout-slots.mdx` the built-in pieces you can still mount, and `docs/layouts/custom-layout.mdx` is a worked example. Call the hooks as `phx.frontend.useX()`; besides those below, these are often needed: `usePreview()` (`isPreview` while the preview start screen shows), `useCloseAction()` (the host's close action or `null`), `useActiveViewports()` (the container's breakpoints, `null` until measured, `desktop` above 768 px: the desktop/phone switch), `useResolveLocalizable()` and `useLocalizable(text)` (spec texts to strings), `useIsCloningAllowed()` (a read-mode \"edit a copy\" action with `LayoutSlots.CloneToEditDialog`)\n    - Undo and redo: `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`; disable each button from `canUndo`/`canRedo`\n    - Tabs: `phx.frontend.useTabNavigation()` returns `{ source, tabs, activeTab, select }` for the spec's `sidebarTabs` (of the selected entity) or `horizontalTabs`; render `tabs` (each `{ index, label, icon, state, isActive }`, `icon` a PhxIcon name) and call `select(tab.index)` on click. Pass `{ source: 'sidebarTabs' }` or `{ source: 'horizontalTabs' }` when the layout shows one kind only. Not `LayoutSlots.useSidebarTabs()`: it serves the built-in sidebar and returns no tabs while its summary shows\n    - Steps: `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`; render `steps` (each `{ index, label, state, status }`, `status` `'complete' | 'active' | 'upcoming'`), call `next()`/`previous()` for Back and Next and `goTo(step.index)` from a stepper. It enforces no order and no validity: enable only `'complete'` steps for an \"earlier steps only\" stepper, and to block moving on while the configuration has a problem, require `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`: a change with a `fixable` or `fatal` violation is rejected, so the configuration is never invalid, and a `warning` is the problem that stays (it blocks finalizing too). `useSteps` and `useHasSteps` from `@salsita-ai/sdk/configurator` are deprecated\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. A failed save arrives as `saveError`, the next successful save as `saveRecovery`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): errors of the built-in actions are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`; render `primary` (and `secondary` in a menu or list) in a loop, each action `{ key, label, title, icon, run, isPending, error, disabled }`, and call `action.run()` on click (its promise never rejects; show `action.error` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, `phx.frontend.useFinalizeAction(handler)` in a component wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`) works too; `FinalizeActions` (from `@salsita-ai/sdk/configurator`) mounts the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them (`useUndoRedo`, `useFinalizeActions` and `useStepNavigation` included): hide undo, redo, finalization and whatever else a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true` (tabs are navigation, so a viewer may switch them), and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n  - `ConfigurationNotFoundPage`: `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => …)` replaces the \"configuration not accessible\" page; show a way back only when the optional `onBack` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page\n  - `ConfiguratorErrorPage`: `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => …)` replaces the production error page; `reason` is `uncaughtError` or `presetCreationFailed`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: `createCustomPhoenixLayoutElement` with the name works too, but types the component as taking only `children`, so the typed props do not compile there in a strict project\n  - `AppLoaderContent`: `phx.frontend.createAppLoader(({ phases }) => …)` replaces what the loading overlay shows (each phase `{ id, label?, progress? }`, the list possibly empty); Phoenix keeps the overlay itself\n  - Assistant form elements: an element declared under `assistant.formElements` (`description`, `role`, scalar `attributes` beside the built-in `label`, a `value` included, `required`) is the default export `phx.frontend.createAssistantFormElement('name', Component)` of one file; the name types the component's props by its role (`AssistantFormElementProps<'name'>`): an option reports its answer with `onSelect(answer)`, an input with `onChange(state, answer)`; and the application does not start while a declared element has no registration or a registration no declaration\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`); the webhook is the default export of `src/webhooks/index.ts`, which you create when the project needs its own handlers. Without it, generation continues with a built-in webhook that answers only anonymous auth; enabling `useAuthHook` or `useClerk` reports `AUTH_WITHOUT_PROJECT_WEBHOOK`. Add the entry with the required Clerk or custom auth handlers, or disable unintended auth settings\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT, except the option files in `.phoenix/variants/`)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Actions = named domain operations (`actions:` in YAML with `params` and `result` schemas), implemented in src/actions/, prepared through `actionSystem.prepareAction()` and exposed as assistant mutations through `assistant.actions`\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
 - Components: PascalCase (.tsx)
 - Utilities: kebab-case (.ts)
 - Expressions: entity-name.ts
 - Migrations: v*.ts (sequential)
 - Specs: kebab-case.yaml
-- Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:'## Export Rules\nAll files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/elements/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\nThe default export must be what the folder\'s phx factory returns (for example `phx.frontend.createCustomPhoenixLayoutElement()` in src/elements/). Any other value, such as a plain React component, stops the application at start with an "Invalid default export in <file>" error. Put plain components and helpers in an underscore folder.',webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build. The one exception is `.phoenix/variants/`, where the `phoenix-variants` skill has you write option files; a rebuild keeps it\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files — compiled from .po files",modelVersioning:"## Version the Domain Model Once It Is Deployed\nA deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\nTo change a model that has been deployed as v<N>:\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n**Replacing the starter.** When the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` before writing any other migration.",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
+- Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:'## Export Rules\nAll files in src/expressions/, src/actions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/elements/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\nThe default export must be what the folder\'s phx factory returns (for example `phx.frontend.createCustomPhoenixLayoutElement()` in src/elements/). Any other value, such as a plain React component, stops the application at start with an "Invalid default export in <file>" error. Put plain components and helpers in an underscore folder.',webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `phx.domain.createAssistantSetupHandler`, `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- An assistant setup handler receives the declaration-shaped whitelist and { role, sessionData, access }. Keep the exact entity/alias split from YAML; inherited fields and expanded member entries are absent. Narrow original declarations, then the SDK expands them. Use project-defined role/session data for per-user customization. Keep the handler synchronous, pure and deterministic. The handler runs in the browser and webhook. Return null to disable assistant execution, or omit whitelist entries to restrict them. Button and panel visibility use spec presence; project developers own dynamic UI filtering through normal layout mechanics such as $filter. Leaves expose optional descriptions; writable options allow only validate: true and allowDryRuns: false; recipe groups allow descriptions and allowDryRuns: false; screenshot views allow descriptions. Deletable entries are {}. Names, component bindings, hints and types are internal. Omitted overrides retain baseline values. Existing entity, enhanced-entity and action types constrain the handler; no separate generated manifest types. Browser GraphQL, tools and change recording use the session-derived manifest; rejected setup fails closed. UI reads the pure spec selector. Omitted server instructions or AI fields preserve the baseline. An empty server instructions string clears it.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build. The one exception is `.phoenix/variants/`, where the `phoenix-variants` skill has you write option files; a rebuild keeps it. The project's TypeScript settings come from `.phoenix/tsconfig.json`; the root `tsconfig.json` is the project's and extends it. `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; use relative imports\n- `src/locales/` .ts files — compiled from .po files\n- `phoenix` and `phoenix-*` folders under `.claude/skills/` and `.agents/skills/` — Phoenix rewrites its skills on every sync, removes anything else inside their folders and removes any other `phoenix-*` skill folder. To customise a skill, copy it to a folder whose name does not start with `phoenix`",modelVersioning:"## Version the Domain Model Once It Is Deployed\nA deployed model version cannot change, because saved configurations depend on it. `pnpm phoenix deploy` is refused, before anything is uploaded, when the model differs from the one already deployed under the same version. The version is not written anywhere: `model.latest` is always the highest numbered version plus one, so a spec with only `latest` is v1, and `applicationVersion` plays no part. `pnpm phoenix dev` accepts every model change, so a working preview does not show that the deploy will pass.\n\nTo change a model that has been deployed as v<N>:\n1. Keep the deployed model, unchanged, as `model.v<N>` in the spec. A file of its own, such as `spec/model-v<N>.yaml`, keeps `latest` readable.\n2. Make the change in `model.latest`, which is now v<N+1>.\n3. Add `src/migrations/v<N+1>.ts` exporting `migrateToV<N+1>`. It receives the saved entities of v<N> and returns entities that are valid in v<N+1>; `ModelV<N>` and `ModelV<N+1>` are generated global namespaces.\n\nThe admin model is versioned on its own, under `src/admin/migrations/`, with its types in `AdminV<N>`.\n\n**Replacing the starter.** When the first deployment of the workspace was the starter, its `Box` model is v1 in production. When the real model replaces it, keep the starter's model as `model.v1` and define the real model in `latest`. Configurations saved from the starter are not worth converting, so the migration returns the starting state of the new model, the `initialDomainEntities` of its preset, and drops the boxes:\n```typescript\n// src/migrations/v2.ts\nimport type { Migration } from '@salsita-ai/sdk/domain'\n\nexport const migrateToV2: Migration<ModelV1.AnyDomainEntity, ModelV2.AnyDomainEntity> = () => [\n  // the entities of the new model's preset\n]\n```\nAn entity of a type the new version no longer has must not stay in the returned state. An entity id starts with its type (`Box-1`), so an entity that keeps its data under a new type name needs a new id and every relation pointing at it rewritten. Read `docs/phoenix/migrations.mdx` before writing any other migration.",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
 
 Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
 

package/dist/application-spec/generate-application/code/templates/spec-code/collect-spec-code.d.ts

@@ -0,0 +1,58 @@
+import type { ComponentEntry, Expressions } from '../../../../parse-application-files/index.js';
+import { type SpecCodeId } from '../../../runtime-spec/index.js';
+/**
+ * Where a value sits inside its target: object keys, and `0` for any item of an array (the
+ * generated type reads the array's item type). An empty path is the target itself.
+ */
+export type SpecCodePath = ReadonlyArray<string | number>;
+/**
+ * What one piece of YAML code produces, which the generated closure is typed by.
+ *
+ * - `expression`: the value of the value expression `name` of `owner`, at each of `paths`.
+ * - `component`: the state of the component `componentName`, at each of `paths` (one per prop the
+ *   code fills).
+ * - `filter`: the value of the filter criterion `criterion`.
+ *
+ * A `$eval` that appears more than once in one value is one dependency of its plan, so it has one
+ * closure, which must fit every place it fills.
+ */
+export type SpecCodeTarget = {
+    readonly kind: 'expression';
+    readonly name: string;
+    readonly paths: readonly SpecCodePath[];
+} | {
+    readonly kind: 'component';
+    readonly componentName: string;
+    readonly paths: readonly SpecCodePath[];
+} | {
+    readonly kind: 'filter';
+    readonly criterion: string;
+};
+/** One piece of code written in YAML, as the generated code module holds it. */
+export interface SpecCodeEntry {
+    readonly id: SpecCodeId;
+    /** The entity or alias the code runs on: `self` is its `$` view. */
+    readonly owner: string;
+    readonly code: string;
+    /**
+     * Whether the code reads `self`. A closure that does not gets no parameter, because the projects'
+     * `noUnusedParameters` would reject an unused `self`.
+     */
+    readonly usesSelf: boolean;
+    readonly target: SpecCodeTarget;
+}
+/** The sections of one domain (configurator or admin) that hold code written in YAML. */
+export interface SpecCodeDomain {
+    readonly expressions: Expressions;
+    readonly components: readonly ComponentEntry[];
+}
+/**
+ * Lists every piece of code written in YAML in one domain: the `$eval` of value expressions
+ * (constants share the plan of their expression), of component props and of filter criteria,
+ * including the filters the SDK adds to the admin pages. Each comes with its id, the entity or alias
+ * it runs on and the target that types its closure.
+ *
+ * Throws when one id names two different pieces of code: ids are built from names the parser keeps
+ * unique, so that is a bug.
+ */
+export declare const collectSpecCode: (domain: SpecCodeDomain) => readonly SpecCodeEntry[];

package/dist/application-spec/generate-application/code/templates/spec-code/collect-spec-code.js

@@ -0,0 +1 @@
+import{FILTER_CRITERION_KEYS as e}from"../../../../core/index.js";import{evalCodeUsesSelf as t}from"../../../../enhanced-json/eval-code-uses-self.js";import{specCodeComponentKey as n,specCodeEvalIds as i,specCodeExpressionKey as r,specCodeFilterId as o}from"../../../runtime-spec/index.js";let l=(e,t,n)=>{if("slot"===e.kind){let i=n.get(e.depIndex)??[];i.push(t),n.set(e.depIndex,i);return}if("array"===e.kind){for(let i of e.items)l(i,[...t,0],n);return}if("object"===e.kind)for(let[i,r]of e.entries)l(r,[...t,i],n)},a=(e,n,r,o)=>{let a=new Map;l(e.template,[],a);let s=i(e,n);return e.deps.flatMap((e,n)=>{let i=s[n];return"eval"!==e.kind||void 0===i?[]:[{id:i,owner:r,code:e.code,usesSelf:t(e.code),target:o(a.get(n)??[])}]})},s=i=>{let r,l=String(i.typeOrAlias),s=n(l,String(i.instanceName),i.componentName),d=(r=String(i.typeOrAlias),i.implementation.filters.items.flatMap((n,i)=>"gradual"!==n.kind?[]:e.flatMap(e=>{let l=n[e];return l?.kind!=="eval"?[]:[{id:o(s,i,e,l.code),owner:r,code:l.code,usesSelf:t(l.code),target:{kind:"filter",criterion:e}}]})));if("userBound"!==i.implementation.kind)return d;let{componentName:p}=i;return[...a(i.implementation.plan,s,l,e=>({kind:"component",componentName:p,paths:e})),...d]},d=(e,t)=>JSON.stringify(e)===JSON.stringify(t);export const collectSpecCode=e=>{let t=new Map;for(let n of[...[...e.expressions.expressions].flatMap(([e,t])=>[...t.values()].flatMap(t=>{if("value"!==t.implementation.kind)return[];let n=String(t.name),i=r(String(e),n);return a(t.implementation.plan,i,String(e),e=>({kind:"expression",name:n,paths:e}))})),...e.components.flatMap(s)]){let e=t.get(n.id);if(void 0===e)t.set(n.id,n);else if(!d(e,n))throw Error(`Two pieces of YAML code share the spec code id "${n.id}". This is a bug in the application-spec generator.`)}return[...t.values()]};

package/dist/application-spec/generate-application/code/templates/spec-code/index.d.ts

@@ -0,0 +1,2 @@
+export { generateApplicationSpecCodeFile } from './spec-code.js';
+export { collectSpecCode } from './collect-spec-code.js';

package/dist/application-spec/generate-application/code/templates/spec-code/index.js

@@ -0,0 +1 @@
+export{generateApplicationSpecCodeFile}from"./spec-code.js";export{collectSpecCode}from"./collect-spec-code.js";

package/dist/application-spec/generate-application/code/templates/spec-code/spec-code.d.ts

@@ -0,0 +1,18 @@
+import type { ApplicationTypeImportRegistrar } from '../../common/index.js';
+import { type SpecCodeDomain } from './collect-spec-code.js';
+/** The two domains of a parsed spec whose YAML code the generated module holds. */
+export interface SpecCodeSpec {
+    readonly configurator: SpecCodeDomain;
+    readonly admin: SpecCodeDomain;
+}
+/**
+ * Generates `.phoenix/spec-code.ts`: every piece of code written in YAML (`$eval` in value
+ * expressions, component props and filter criteria) as a closure, keyed by its spec code id, one
+ * map per domain. Each closure is typed by what it produces (the expression's type, the component
+ * prop's type, the filter criterion's type) and by the entity it runs on, so `phoenix check
+ * --types` checks the code as it checks generated domain code.
+ *
+ * Nothing imports the file yet; the runtime will look code up in it by id instead of compiling the
+ * text.
+ */
+export declare const generateApplicationSpecCodeFile: (spec: SpecCodeSpec, registerApplicationTypeImports?: ApplicationTypeImportRegistrar) => string;

package/dist/application-spec/generate-application/code/templates/spec-code/spec-code.js

@@ -0,0 +1,41 @@
+import{CodeImports as e,autoHeader as t,skipApplicationTypeImports as n}from"../../common/index.js";import{collectSpecCode as r}from"./collect-spec-code.js";let o="@salsita-ai/sdk/domain",s=`/**
+ * The type at one key of TYPE, or the item type of an array for a numeric key, taken from every
+ * member of a union that has it. \`unknown\` when no member has it, so that a type the path cannot
+ * follow loses the check instead of rejecting valid code.
+ */
+type SpecCodeMember<TYPE, KEY> = TYPE extends readonly (infer ITEM)[]
+  ? KEY extends number
+    ? ITEM
+    : never
+  : TYPE extends object
+    ? KEY extends keyof TYPE
+      ? TYPE[KEY]
+      : never
+    : never
+type SpecCodeAt<TYPE, KEY> = [SpecCodeMember<TYPE, KEY>] extends [never] ? unknown : SpecCodeMember<TYPE, KEY>`,i=`/** The value a component filter criterion yields, as \`withGradualFilter\` takes it: arrays read-only. */
+type SpecCodeFilterCriterion<KEY extends keyof ComponentSystemFilterProps> =
+  | ([Required<ComponentSystemFilterProps>[KEY]] extends [ReadonlyArray<infer ITEM>]
+      ? readonly ITEM[]
+      : Required<ComponentSystemFilterProps>[KEY])
+  | undefined`,p=`/**
+ * Types one closure: \`self\` is the entity it runs on, and what it returns must fit TARGET. The
+ * result is inferred as a constant and then checked against TARGET, as the dependencies of
+ * \`memoEval\` are in generated domain code.
+ */
+const code =
+  <SELF, TARGET>() =>
+  <const RESULT extends TARGET>(closure: (self: SELF) => RESULT): ((self: SELF) => RESULT) =>
+    closure`,a=(e,t,n)=>{if(0===t.length)return"unknown";let r=t.map(t=>(t.length>0&&(n.usesAt=!0),t.reduce((e,t)=>`SpecCodeAt<${e}, ${"number"==typeof t?"number":JSON.stringify(t)}>`,e)));return 1===r.length?r[0]:r.map(e=>`(${e})`).join(" & ")},d=(e,t,n)=>0===e.length?"{}":`{
+${e.map(e=>{let r,s,i;return t.registerOwnerTypes([`$${e.owner}`]),r=`${t.typePrefix}$${e.owner}`,s=((e,t,n,r)=>{if("filter"===e.kind)return r.usesFilter=!0,r.imports.addTypeImport(o,"ComponentSystemFilterProps"),`SpecCodeFilterCriterion<'${e.criterion}'>`;if("component"===e.kind){let t=`${e.componentName}Component`;return r.imports.addTypeImport(o,"StateOfComponent"),r.imports.addTypeImport(o,t),a(`StateOfComponent<typeof ${t}>`,e.paths,r)}return n.registerOwnerTypes([`${t}Expressions`]),a(`${n.typePrefix}${t}Expressions['${e.name}']`,e.paths,r)})(e.target,e.owner,t,n),i=e.usesSelf?`self => (${e.code}
+)`:`() => (${e.code}
+)`,`    ${JSON.stringify(e.id)}: code<${r}, ${s}>()(${i}),`}).join("\n")}
+  }`;export const generateApplicationSpecCodeFile=(o,a=n)=>{let m=new e,c={imports:m,usesAt:!1,usesFilter:!1},l=r(o.configurator),y=r(o.admin),f=d(l,{typePrefix:"",registerOwnerTypes:e=>a(m,e)},c),u=d(y,{typePrefix:"Admin.",registerOwnerTypes:()=>a(m,["Admin"])},c),E=[...c.usesAt?[s]:[],...c.usesFilter?[i]:[],...l.length+y.length>0?[p]:[]];return`${t("spec-code.ts","Code written in YAML ($eval in expressions, component props and filters) as typed closures, keyed by spec code id.")}
+${m.toString()}
+
+${E.map(e=>`${e}
+
+`).join("")}export const specCode = {
+  configurator: ${f},
+  admin: ${u},
+}
+`};

package/dist/application-spec/generate-application/code/templates/spec-messages/index.d.ts

@@ -0,0 +1 @@
+export { generateApplicationSpecMessagesFile } from './spec-messages.js';

package/dist/application-spec/generate-application/code/templates/spec-messages/index.js

@@ -0,0 +1 @@
+export{generateApplicationSpecMessagesFile}from"./spec-messages.js";

package/dist/application-spec/generate-application/code/templates/spec-messages/spec-messages.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentEntry, Defaults, Expressions, Invariants } from '../../../../parse-application-files/index.js';
+/** The sections of one domain whose `$msg` texts generated domain code turns into `msg` calls. */
+export interface SpecMessagesDomain {
+    readonly expressions: Expressions;
+    readonly components: readonly ComponentEntry[];
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+}
+/** The two domains of a parsed spec whose texts the generated messages file holds. */
+export interface SpecMessagesSpec {
+    readonly configurator: SpecMessagesDomain;
+    readonly admin: SpecMessagesDomain;
+}
+/**
+ * Generates `.phoenix/spec-messages.ts`: one `msg` call for each distinct `$msg` text of the spec
+ * that generated domain code turns into a `msg` call, with the same message id (`$msgId`, or the id
+ * Lingui generates from the text). Lingui extracts the project's catalogues from `.phoenix`, so the
+ * YAML texts reach them through this file. Nothing imports it.
+ */
+export declare const generateApplicationSpecMessagesFile: (spec: SpecMessagesSpec) => string;

package/dist/application-spec/generate-application/code/templates/spec-messages/spec-messages.js

@@ -0,0 +1,6 @@
+import{isMsgMarker as e,stringifyMsgMacroCode as t}from"../../../../core/index.js";import{CodeImports as s,autoHeader as o}from"../../common/index.js";let n=(e,t)=>{"msg"===e.kind?t.push(e.marker):"array"===e.kind?e.items.forEach(e=>n(e,t)):"object"===e.kind&&e.entries.forEach(([,e])=>n(e,t))},a=(t,s)=>{e(t)?s.push(t):Array.isArray(t)?t.forEach(e=>a(e,s)):"object"==typeof t&&null!==t&&Object.values(t).forEach(e=>a(e,s))},r=(e,t)=>{for(let s of e.expressions.expressions.values())for(let e of s.values())"value"===e.implementation.kind&&n(e.implementation.plan.template,t);for(let s of e.components)"userBound"===s.implementation.kind&&n(s.implementation.plan.template,t);for(let s of Object.values(e.invariants.entries))for(let e of Object.values(s))"static"===e.kind&&"string"!=typeof e.message&&t.push(e.message);a(e.defaults.entries,t)};export const generateApplicationSpecMessagesFile=e=>{let n=[];r(e.configurator,n),r(e.admin,n);let a=[...new Set(n.map(t))],i=new s;return a.length>0&&i.addImport("@lingui/core/macro","msg"),`${o("spec-messages.ts","The texts of the spec as msg calls, for Lingui extraction.")}
+${i.toString()}
+
+export const specMessages = [${a.map(e=>`
+  ${e},`).join("")}${a.length>0?"\n":""}]
+`};

package/dist/application-spec/generate-application/code/templates/story/phx-module.d.ts

@@ -1,7 +1,13 @@
+import type { ApplicationSpec } from '../../../../parse-application-files/index.js';
 /**
  * Emits the story's `phx` module.
  *
  * Stories bind `phx` as a module export rather than through `globalThis`, so several stories can
- * run side by side on one Storybook page without sharing configurator state.
+ * run side by side on one Storybook page without sharing configurator state. Its type is stated from
+ * SDK types and the story's generated application types, as `globals.d.ts` states the global one.
+ *
+ * Each member of `phx.applicationTypes` is typed as a local declared constant, so an editor shows the
+ * type itself (`SchemaOfObject<never>` for data the spec leaves out), as it did when the members were
+ * the generated values, and not the alias as written.
  */
-export declare const generateApplicationSpecStoryPhxModule: () => string;
+export declare const generateApplicationSpecStoryPhxModule: (spec: ApplicationSpec) => string;

package/dist/application-spec/generate-application/code/templates/story/phx-module.js

@@ -1,9 +1,21 @@
-export const generateApplicationSpecStoryPhxModule=()=>`import { configuratorInterface } from './configurator-globals.js'
+import{CodeImports as a}from"../../common/index.js";import{generatePhxTypes as t}from"../global-definition/index.js";let e=[["ApplicationVersion","string"],["PublishedDataHash","string"],...["PublishedData","SessionData","FrontendData","BackendData","FinalizeData","PrefetchedFinalizeData","FinalizeResult","CallbackData"].map(a=>[a,`SchemaOfObject<${a}>`]),...["NavigationState","ViewState","ToolState","ExportState","AdminNavigationState"].map(a=>[a,`EnumLike<${a}>`])];export const generateApplicationSpecStoryPhxModule=o=>{let i=new a,n=t(o,i);for(let a of(i.addTypeImport("@salsita-ai/sdk/domain","SchemaOfObject"),n.applicationTypeNames))i.addTypeImport("./application-types.js",a);let p=e.map(([a,t])=>`declare const phx${a}: ${t}`),r=e.map(([a])=>`    ${a}: typeof phx${a}`);return`${i.toTypeOnlyString()}
+
+import { configuratorInterface } from './configurator-globals.js'
 import { phxApplicationTypes, phxDomain } from './domain-spec.js'
 
-export const phx = {
+${n.declarations}
+
+${p.join("\n")}
+
+export const phx: {
+  domain: ${n.domainType.replaceAll("\n","\n  ")}
+  frontend: ${n.configuratorInterfaceType}
+  applicationTypes: {
+${r.join("\n")}
+  }
+} = {
   domain: phxDomain,
   frontend: configuratorInterface,
   applicationTypes: phxApplicationTypes,
 }
-`;
+`};

package/dist/application-spec/generate-application/code/templates/story/wrapper.d.ts

@@ -7,5 +7,8 @@ import type { MockTemplateDefinition } from '../../../../mock-template-definitio
  * mode change has to arrive as a fresh mount. The Storybook plugin achieves that by reloading the
  * preview whenever the story's marker appears, changes, or disappears. In a production Storybook
  * build the same module always reports `active === false`, so deployed stories stay local-mode.
+ *
+ * `ExampleApp` takes an optional `mockTemplate` key, so a story can pin the mock template it opens
+ * (`args: { mockTemplate: 'read' }`); the editor applies it on mount without storing it.
  */
 export declare const generateApplicationSpecStoryWrapper: (storyFolderName: string, mockTemplates: readonly MockTemplateDefinition[]) => string;

package/dist/application-spec/generate-application/code/templates/story/wrapper.js

@@ -14,13 +14,14 @@ const config = configuratorConfig.withWebComponentTag(tagName).buildConfig()
 
 mountConfiguratorApplication(config)
 
-export const ExampleApp = () => (
+export const ExampleApp = ({ mockTemplate }: { readonly mockTemplate?: string }) => (
   <Editor
     localMode={!active}
     wsUrl={wsUrl}
     initialRawProjectFiles={rawProjectFiles}
     mockTemplates={mockTemplates}
     autoApplyTemplate
+    initialTemplateKey={mockTemplate}
     tagName={tagName}
     enableAdmin={false}
   />

package/dist/application-spec/generate-application/code/templates/tsconfig.d.ts

@@ -1 +1,6 @@
+/**
+ * The project's TypeScript settings, generated to `.phoenix/tsconfig.json` and rewritten whenever they
+ * differ. Paths are relative to `.phoenix/`. The project's root `tsconfig.json` extends this file, and
+ * `phoenix check` uses it directly when the project has no root `tsconfig.json`.
+ */
 export declare const generateApplicationSpecTsconfig: () => string;

package/dist/application-spec/generate-application/code/templates/tsconfig.js

@@ -31,6 +31,6 @@ export const generateApplicationSpecTsconfig=()=>`{
 
     "paths": {}
   },
-  "include": ["src", ".phoenix", "prettier.config.js", "eslint.config.js", "./.phoenix/globals.d.ts"]
+  "include": ["../src", ".", "../prettier.config.js", "../eslint.config.js", "./globals.d.ts"]
 }
 `;

package/dist/application-spec/generate-application/code/templates/webhook-index.d.ts

@@ -1 +1,6 @@
-export declare const generateApplicationSpecWebhookIndex: () => string;
+/** Where the generated webhook entry takes its handler from. */
+export interface WebhookIndexOptions {
+    /** Whether the project has `src/webhooks/index.ts`; without it the entry holds the built-in webhook. */
+    readonly hasWebhookEntry: boolean;
+}
+export declare const generateApplicationSpecWebhookIndex: ({ hasWebhookEntry }: WebhookIndexOptions) => string;

package/dist/application-spec/generate-application/code/templates/webhook-index.js

@@ -1,7 +1,16 @@
-import{autoHeader as e}from"../common/file-headers.js";export const generateApplicationSpecWebhookIndex=()=>`${e("webhook.ts","Webhook entry point — imports builders (sets globalThis.phx.webhooks) then re-exports user handler.")}
+import{autoHeader as e}from"../common/file-headers.js";export const generateApplicationSpecWebhookIndex=({hasWebhookEntry:o})=>o?`${e("webhook.ts","Webhook entry point — imports builders (sets globalThis.phx.webhooks) then re-exports user handler.")}
 export * as builders from './webhook-builders.js'
 
 import implementation from '../src/webhooks/index.js'
 
 export const handler = implementation
+`:`${e("webhook.ts","Webhook entry point — imports builders (sets globalThis.phx.webhooks) then exports the built-in handler, because the project has no src/webhooks/index.ts.")}
+export * as builders from './webhook-builders.js'
+
+// A webhook needs at least one handler; anonymous auth stays inert until spec/application.yaml sets useAuthHook
+const authHandler = phx.webhooks.authHandlerBuilder
+  .withAnonymousHandler(async () => ({ success: true, data: {}, role: 'anonymous' }))
+  .build()
+
+export const handler = phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
 `;

package/dist/application-spec/generate-application/code/templates/webhooks-config.js

@@ -1,6 +1,5 @@
-import{generateEnvReader as e}from"../common/env-reader.js";import{autoHeader as r}from"../common/file-headers.js";let t={IS_DEV:{type:"bool",default:!1,devDefault:!0},ASSISTANT_STRICT_THREADS:{type:"bool",default:!1},AWS_S3_PUBLIC_RESOURCES_BUCKET:{type:"str",required:!0},AWS_S3_RESOURCES_REGION:{type:"str",required:!0},DEPLOYMENT_RESOURCES_PATH:{type:"str",default:"deployment-resources"}},o={CLERK_API_KEY:{type:"str",required:!0},FRONTEND_URL:{type:"str",required:!0},JWT_SECRET_BASE64:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_ID:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_SECRET:{type:"str",required:!0},OAUTH_PROVIDER_BASE_URL:{type:"str",required:!0},RESOURCES_URL:{type:"str",required:!0}};export const generateApplicationSpecWebhooksConfig=i=>{let n=i.infra.env?.webhook??{},R=i.appMetadata.useClerk?o:{},{imports:E,config:p}=e({...t,...R,...n}),_=E.length>0?`import { ${E.join(", ")} } from 'envalid'
-`:"";return`${r("webhooks.config.ts","Runtime environment config for the webhook server.")}
-${_}import { createEnvReader } from '@salsita-ai/sdk/common/env'
+import{generateEnvReader as e}from"../common/env-reader.js";import{autoHeader as r}from"../common/file-headers.js";let t={IS_DEV:{type:"bool",default:!1,devDefault:!0},ASSISTANT_STRICT_THREADS:{type:"bool",default:!1},AWS_S3_PUBLIC_RESOURCES_BUCKET:{type:"str",required:!0},AWS_S3_RESOURCES_REGION:{type:"str",required:!0},DEPLOYMENT_RESOURCES_PATH:{type:"str",default:"deployment-resources"}},o={CLERK_API_KEY:{type:"str",required:!0},FRONTEND_URL:{type:"str",required:!0},JWT_SECRET_BASE64:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_ID:{type:"str",required:!0},OAUTH_PROVIDER_CLIENT_SECRET:{type:"str",required:!0},OAUTH_PROVIDER_BASE_URL:{type:"str",required:!0},RESOURCES_URL:{type:"str",required:!0}};export const generateApplicationSpecWebhooksConfig=i=>{let n=i.infra.env?.webhook??{},R=i.appMetadata.useClerk?o:{},{imports:E,config:p}=e({...t,...R,...n}),_=[...E,"createEnvReader"].sort();return`${r("webhooks.config.ts","Runtime environment config for the webhook server.")}
+import { ${_.join(", ")} } from '@salsita-ai/sdk/common/env'
 
 const readRuntimeConfig = createEnvReader(${p})
 

package/dist/application-spec/generate-application/implementations/phx-application-types.d.ts

@@ -0,0 +1,25 @@
+import { type EnumLike } from '#package/domain';
+import type { RuntimeSpec } from '../runtime-spec/index.js';
+/**
+ * The value of `phx.applicationTypes`: the application's version and published data hash, the JSON
+ * schemas of its data (`undefined` for data the spec leaves out), and its state enums.
+ */
+export interface PhxApplicationTypes {
+    readonly ApplicationVersion: string;
+    readonly PublishedDataHash: string;
+    readonly PublishedData: unknown;
+    readonly SessionData: unknown;
+    readonly FrontendData: unknown;
+    readonly BackendData: unknown;
+    readonly FinalizeData: unknown;
+    readonly PrefetchedFinalizeData: unknown;
+    readonly FinalizeResult: unknown;
+    readonly CallbackData: unknown;
+    readonly NavigationState: EnumLike<string>;
+    readonly ViewState: EnumLike<string>;
+    readonly ToolState: EnumLike<string>;
+    readonly ExportState: EnumLike<string>;
+    readonly AdminNavigationState: EnumLike<string>;
+}
+/** Builds `phx.applicationTypes` from the spec, with the values generated `domain-spec.ts` writes. */
+export declare const createPhxApplicationTypes: (spec: RuntimeSpec) => PhxApplicationTypes;

package/dist/application-spec/generate-application/implementations/phx-application-types.js

@@ -0,0 +1 @@
+import{EnumReflection as a}from"#package/domain";let t=(t,e)=>new a(t,{enum:[...e]});export const createPhxApplicationTypes=a=>{let{dataSchemas:e,states:i}=a.configurator;return{ApplicationVersion:a.appMetadata.applicationVersion,PublishedDataHash:e.publishedDataHash,PublishedData:e.publishedData.runtimeSchema,SessionData:e.sessionData.runtimeSchema,FrontendData:e.frontendData.runtimeSchema,BackendData:e.backendData?.runtimeSchema,FinalizeData:e.finalizeData.runtimeSchema,PrefetchedFinalizeData:e.prefetchedFinalizeData.runtimeSchema,FinalizeResult:e.finalizeResult.runtimeSchema,CallbackData:e.callbackData.runtimeSchema,NavigationState:t("NavigationState",i.navigationStates),ViewState:t("ViewState",i.viewStates),ToolState:t("ToolState",i.toolStates),ExportState:t("ExportState",i.exportStates),AdminNavigationState:t("AdminNavigationState",a.admin.states.navigationStates)}};