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

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/agents/claude-md.d.ts

@@ -1,2 +1,2 @@
 export declare const mergeClaudeMdContent: (existingContent: string | undefined) => string;
-export declare const claudeMdFile = "[PHOENIX-SDK-START]\n## Phoenix Configurator Project\n\nDeclarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.\n\n## Build Commands\n- `pnpm phoenix build` \u2014 Full production build\n- `pnpm phoenix dev` \u2014 Development mode with hot reload\n- `pnpm phoenix sync` \u2014 Sync generated files without full build\n\n## 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)\n\n## Project Structure\n- `spec/` \u2014 Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` \u2014 Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` \u2014 Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` \u2014 Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` \u2014 ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` \u2014 Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` \u2014 Event & lifecycle handlers\n- `src/webhooks/` \u2014 Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` \u2014 Schema version migrations (v*.ts)\n- `src/locales/` \u2014 Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` \u2014 Admin interface (mirrors main src/ structure)\n- `src/_shared/` \u2014 Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` \u2014 Auto-generated files (DO NOT EDIT)\n- `public/` \u2014 Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` \u2014 Uploadable resources (PDF templates, email assets)\n\n## 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\n\n## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\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\n\n## File Conventions\n- Components: PascalCase (.tsx)\n- Utilities: kebab-case (.ts)\n- Expressions: entity-name.ts\n- Migrations: v*.ts (sequential)\n- Specs: kebab-case.yaml\n- Underscore folders (_shared/, _utils/) are NOT auto-imported\n\n## Export Rules\nAll files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\n\n## 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.\n\n## Do Not Edit\n- `.phoenix/` directory \u2014 completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files \u2014 compiled from .po files\n\n## Code Review\nUse `/review` command to review code changes before committing.\n\n## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` \u2014 Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` \u2014 Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` \u2014 Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` \u2014 Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` \u2014 List docs in a category\n- `pnpm phoenix docs -l` \u2014 List all doc paths with titles\n\n### 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`\n\n### 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` \u2014 Output file path (default: `./screenshot.png`)\n- `--width, -w` \u2014 Width in pixels (default: 1920)\n- `--height` \u2014 Height in pixels (default: 1080)\n- `--format, -f` \u2014 Image format: PNG or JPEG (default: PNG)\n- `--port` \u2014 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\n\n### 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` \u2014 Output file path (prints to stdout if omitted)\n- `--sections, -s` \u2014 Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 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` \u2014 domain data loaded\n- `domainContextReady` \u2014 domain context initialized (entities available)\n- `configuratorReady` \u2014 3D configurator initialized\n- `sessionAuthenticated` \u2014 session service active\n- `editorMode` \u2014 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\n\n### Inspect: Data\n\nGet the current editor context data as JSON via `pnpm phoenix inspect:data`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties\n\n**Example:** `pnpm phoenix inspect:data -o ./data.json`\n\n**Tips:** Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:data | head -30`).\n\n**Use cases:** AI agent context, debugging published/session/access data\n\n### Inspect: Scene\n\nGet the current Three.js scene graph as JSON via `pnpm phoenix inspect:scene`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.\n\n**Example:** `pnpm phoenix inspect:scene -o ./scene.json`\n\n**Tips:** Scene graphs can be large. Pipe through `head`/`tail` for partial output.\n\n**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` \u2014 Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` \u2014 End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` \u2014 Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` \u2014 ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` \u2014 Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` \u2014 YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` \u2014 Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` \u2014 Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` \u2014 Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` \u2014 Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` \u2014 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\"`\n\n### Playwright MCP Setup (for AI agents)\n\nTo interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@playwright/mcp@latest\",\n        \"--headed\",\n        \"--launch-options\",\n        \"{\\\"args\\\":[\\\"--use-gl=swiftshader\\\",\\\"--enable-webgl\\\",\\\"--ignore-gpu-blocklist\\\"]}\"\n      ]\n    }\n  }\n}\n```\n\nKey flags:\n- `--headed` \u2014 visible browser (required for GPU rendering)\n- `--use-gl=swiftshader` \u2014 software GPU fallback for environments without a physical GPU\n- `--enable-webgl` + `--ignore-gpu-blocklist` \u2014 ensure WebGL is available\n[PHOENIX-SDK-END]\n";
+export declare const claudeMdFile = "[PHOENIX-SDK-START]\n## Phoenix Configurator Project\n\nDeclarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.\n\n## Build Commands\n- `pnpm phoenix build` \u2014 Full production build\n- `pnpm phoenix dev` \u2014 Development mode with hot reload\n- `pnpm phoenix sync` \u2014 Sync generated files without full build\n\n## 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)\n\n## Project Structure\n- `spec/` \u2014 Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` \u2014 Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` \u2014 Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` \u2014 Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` \u2014 ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` \u2014 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, or the app loader stays on screen; put the UI above it, positioned and after it in the markup. Call `useSceneSafeArea()` (same import) 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\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints and errors yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): save and built-in action errors are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: run each with `phx.frontend.useFinalizeAction(handler)` in a component of its own wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`), or mount `FinalizeActions` (from `@salsita-ai/sdk/configurator`) for the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them: hide what a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true`, and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n- `src/handlers/` \u2014 Event & lifecycle handlers\n- `src/webhooks/` \u2014 Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` \u2014 Schema version migrations (v*.ts)\n- `src/locales/` \u2014 Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` \u2014 Admin interface (mirrors main src/ structure)\n- `src/_shared/` \u2014 Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` \u2014 Auto-generated files (DO NOT EDIT)\n- `public/` \u2014 Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` \u2014 Uploadable resources (PDF templates, email assets)\n\n## 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\n\n## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\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\n\n## File Conventions\n- Components: PascalCase (.tsx)\n- Utilities: kebab-case (.ts)\n- Expressions: entity-name.ts\n- Migrations: v*.ts (sequential)\n- Specs: kebab-case.yaml\n- Underscore folders (_shared/, _utils/) are NOT auto-imported\n\n## Export Rules\nAll files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\n\n## 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.\n\n## Do Not Edit\n- `.phoenix/` directory \u2014 completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files \u2014 compiled from .po files\n\n## Code Review\nUse `/review` command to review code changes before committing.\n\n## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` \u2014 Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` \u2014 Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` \u2014 Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` \u2014 Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` \u2014 List docs in a category\n- `pnpm phoenix docs -l` \u2014 List all doc paths with titles\n\n### 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`\n\n### 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` \u2014 Output file path (default: `./screenshot.png`)\n- `--width, -w` \u2014 Width in pixels (default: 1920)\n- `--height` \u2014 Height in pixels (default: 1080)\n- `--format, -f` \u2014 Image format: PNG or JPEG (default: PNG)\n- `--port` \u2014 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\n\n### 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` \u2014 Output file path (prints to stdout if omitted)\n- `--sections, -s` \u2014 Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 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` \u2014 domain data loaded\n- `domainContextReady` \u2014 domain context initialized (entities available)\n- `configuratorReady` \u2014 3D configurator initialized\n- `sessionAuthenticated` \u2014 session service active\n- `editorMode` \u2014 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\n\n### Inspect: Data\n\nGet the current editor context data as JSON via `pnpm phoenix inspect:data`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties\n\n**Example:** `pnpm phoenix inspect:data -o ./data.json`\n\n**Tips:** Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:data | head -30`).\n\n**Use cases:** AI agent context, debugging published/session/access data\n\n### Inspect: Scene\n\nGet the current Three.js scene graph as JSON via `pnpm phoenix inspect:scene`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.\n\n**Example:** `pnpm phoenix inspect:scene -o ./scene.json`\n\n**Tips:** Scene graphs can be large. Pipe through `head`/`tail` for partial output.\n\n**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` \u2014 Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` \u2014 End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` \u2014 Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` \u2014 ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` \u2014 Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` \u2014 YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` \u2014 Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` \u2014 Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` \u2014 Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` \u2014 Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` \u2014 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\"`\n\n### Playwright MCP Setup (for AI agents)\n\nTo interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@playwright/mcp@latest\",\n        \"--headed\",\n        \"--launch-options\",\n        \"{\\\"args\\\":[\\\"--use-gl=swiftshader\\\",\\\"--enable-webgl\\\",\\\"--ignore-gpu-blocklist\\\"]}\"\n      ]\n    }\n  }\n}\n```\n\nKey flags:\n- `--headed` \u2014 visible browser (required for GPU rendering)\n- `--use-gl=swiftshader` \u2014 software GPU fallback for environments without a physical GPU\n- `--enable-webgl` + `--ignore-gpu-blocklist` \u2014 ensure WebGL is available\n[PHOENIX-SDK-END]\n";

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/agents/cursor-rules.d.ts

@@ -1,2 +1,2 @@
 export declare const mergeCursorRulesContent: (existingContent: string | undefined) => string;
-export declare const cursorRulesFile = "---\ndescription: Phoenix SDK project rules\nglobs:\nalwaysApply: true\n---\n\n[PHOENIX-SDK-START]\n## Phoenix Configurator Project\n\nDeclarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.\n\n## Build Commands\n- `pnpm phoenix build` \u2014 Full production build\n- `pnpm phoenix dev` \u2014 Development mode with hot reload\n- `pnpm phoenix sync` \u2014 Sync generated files without full build\n\n## 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)\n\n## Project Structure\n- `spec/` \u2014 Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` \u2014 Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` \u2014 Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` \u2014 Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` \u2014 ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` \u2014 Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` \u2014 Event & lifecycle handlers\n- `src/webhooks/` \u2014 Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` \u2014 Schema version migrations (v*.ts)\n- `src/locales/` \u2014 Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` \u2014 Admin interface (mirrors main src/ structure)\n- `src/_shared/` \u2014 Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` \u2014 Auto-generated files (DO NOT EDIT)\n- `public/` \u2014 Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` \u2014 Uploadable resources (PDF templates, email assets)\n\n## 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\n\n## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\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\n\n## File Conventions\n- Components: PascalCase (.tsx)\n- Utilities: kebab-case (.ts)\n- Expressions: entity-name.ts\n- Migrations: v*.ts (sequential)\n- Specs: kebab-case.yaml\n- Underscore folders (_shared/, _utils/) are NOT auto-imported\n\n## Export Rules\nAll files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\n\n## 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.\n\n## Do Not Edit\n- `.phoenix/` directory \u2014 completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files \u2014 compiled from .po files\n\n## Code Review\nUse `/review` command to review code changes before committing.\n\n## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` \u2014 Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` \u2014 Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` \u2014 Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` \u2014 Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` \u2014 List docs in a category\n- `pnpm phoenix docs -l` \u2014 List all doc paths with titles\n\n### 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`\n\n### 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` \u2014 Output file path (default: `./screenshot.png`)\n- `--width, -w` \u2014 Width in pixels (default: 1920)\n- `--height` \u2014 Height in pixels (default: 1080)\n- `--format, -f` \u2014 Image format: PNG or JPEG (default: PNG)\n- `--port` \u2014 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\n\n### 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` \u2014 Output file path (prints to stdout if omitted)\n- `--sections, -s` \u2014 Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 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` \u2014 domain data loaded\n- `domainContextReady` \u2014 domain context initialized (entities available)\n- `configuratorReady` \u2014 3D configurator initialized\n- `sessionAuthenticated` \u2014 session service active\n- `editorMode` \u2014 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\n\n### Inspect: Data\n\nGet the current editor context data as JSON via `pnpm phoenix inspect:data`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties\n\n**Example:** `pnpm phoenix inspect:data -o ./data.json`\n\n**Tips:** Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:data | head -30`).\n\n**Use cases:** AI agent context, debugging published/session/access data\n\n### Inspect: Scene\n\nGet the current Three.js scene graph as JSON via `pnpm phoenix inspect:scene`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.\n\n**Example:** `pnpm phoenix inspect:scene -o ./scene.json`\n\n**Tips:** Scene graphs can be large. Pipe through `head`/`tail` for partial output.\n\n**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` \u2014 Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` \u2014 End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` \u2014 Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` \u2014 ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` \u2014 Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` \u2014 YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` \u2014 Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` \u2014 Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` \u2014 Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` \u2014 Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` \u2014 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\"`\n\n### Playwright MCP Setup (for AI agents)\n\nTo interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@playwright/mcp@latest\",\n        \"--headed\",\n        \"--launch-options\",\n        \"{\\\"args\\\":[\\\"--use-gl=swiftshader\\\",\\\"--enable-webgl\\\",\\\"--ignore-gpu-blocklist\\\"]}\"\n      ]\n    }\n  }\n}\n```\n\nKey flags:\n- `--headed` \u2014 visible browser (required for GPU rendering)\n- `--use-gl=swiftshader` \u2014 software GPU fallback for environments without a physical GPU\n- `--enable-webgl` + `--ignore-gpu-blocklist` \u2014 ensure WebGL is available\n[PHOENIX-SDK-END]\n";
+export declare const cursorRulesFile = "---\ndescription: Phoenix SDK project rules\nglobs:\nalwaysApply: true\n---\n\n[PHOENIX-SDK-START]\n## Phoenix Configurator Project\n\nDeclarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.\n\n## Build Commands\n- `pnpm phoenix build` \u2014 Full production build\n- `pnpm phoenix dev` \u2014 Development mode with hot reload\n- `pnpm phoenix sync` \u2014 Sync generated files without full build\n\n## 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)\n\n## Project Structure\n- `spec/` \u2014 Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` \u2014 Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` \u2014 Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` \u2014 Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` \u2014 ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` \u2014 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, or the app loader stays on screen; put the UI above it, positioned and after it in the markup. Call `useSceneSafeArea()` (same import) 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\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints and errors yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): save and built-in action errors are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: run each with `phx.frontend.useFinalizeAction(handler)` in a component of its own wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`), or mount `FinalizeActions` (from `@salsita-ai/sdk/configurator`) for the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them: hide what a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true`, and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n- `src/handlers/` \u2014 Event & lifecycle handlers\n- `src/webhooks/` \u2014 Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` \u2014 Schema version migrations (v*.ts)\n- `src/locales/` \u2014 Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` \u2014 Admin interface (mirrors main src/ structure)\n- `src/_shared/` \u2014 Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` \u2014 Auto-generated files (DO NOT EDIT)\n- `public/` \u2014 Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` \u2014 Uploadable resources (PDF templates, email assets)\n\n## 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\n\n## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\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\n\n## File Conventions\n- Components: PascalCase (.tsx)\n- Utilities: kebab-case (.ts)\n- Expressions: entity-name.ts\n- Migrations: v*.ts (sequential)\n- Specs: kebab-case.yaml\n- Underscore folders (_shared/, _utils/) are NOT auto-imported\n\n## Export Rules\nAll files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\n\n## 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.\n\n## Do Not Edit\n- `.phoenix/` directory \u2014 completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files \u2014 compiled from .po files\n\n## Code Review\nUse `/review` command to review code changes before committing.\n\n## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` \u2014 Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` \u2014 Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` \u2014 Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` \u2014 Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` \u2014 List docs in a category\n- `pnpm phoenix docs -l` \u2014 List all doc paths with titles\n\n### 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`\n\n### 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` \u2014 Output file path (default: `./screenshot.png`)\n- `--width, -w` \u2014 Width in pixels (default: 1920)\n- `--height` \u2014 Height in pixels (default: 1080)\n- `--format, -f` \u2014 Image format: PNG or JPEG (default: PNG)\n- `--port` \u2014 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\n\n### 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` \u2014 Output file path (prints to stdout if omitted)\n- `--sections, -s` \u2014 Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 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` \u2014 domain data loaded\n- `domainContextReady` \u2014 domain context initialized (entities available)\n- `configuratorReady` \u2014 3D configurator initialized\n- `sessionAuthenticated` \u2014 session service active\n- `editorMode` \u2014 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\n\n### Inspect: Data\n\nGet the current editor context data as JSON via `pnpm phoenix inspect:data`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties\n\n**Example:** `pnpm phoenix inspect:data -o ./data.json`\n\n**Tips:** Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:data | head -30`).\n\n**Use cases:** AI agent context, debugging published/session/access data\n\n### Inspect: Scene\n\nGet the current Three.js scene graph as JSON via `pnpm phoenix inspect:scene`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.\n\n**Example:** `pnpm phoenix inspect:scene -o ./scene.json`\n\n**Tips:** Scene graphs can be large. Pipe through `head`/`tail` for partial output.\n\n**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` \u2014 Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` \u2014 End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` \u2014 Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` \u2014 ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` \u2014 Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` \u2014 YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` \u2014 Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` \u2014 Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` \u2014 Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` \u2014 Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` \u2014 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\"`\n\n### Playwright MCP Setup (for AI agents)\n\nTo interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@playwright/mcp@latest\",\n        \"--headed\",\n        \"--launch-options\",\n        \"{\\\"args\\\":[\\\"--use-gl=swiftshader\\\",\\\"--enable-webgl\\\",\\\"--ignore-gpu-blocklist\\\"]}\"\n      ]\n    }\n  }\n}\n```\n\nKey flags:\n- `--headed` \u2014 visible browser (required for GPU rendering)\n- `--use-gl=swiftshader` \u2014 software GPU fallback for environments without a physical GPU\n- `--enable-webgl` + `--ignore-gpu-blocklist` \u2014 ensure WebGL is available\n[PHOENIX-SDK-END]\n";

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/agents/shared-sdk-content.d.ts

@@ -1 +1 @@
-export declare const sdkContent = "[PHOENIX-SDK-START]\n## Phoenix Configurator Project\n\nDeclarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.\n\n## Build Commands\n- `pnpm phoenix build` \u2014 Full production build\n- `pnpm phoenix dev` \u2014 Development mode with hot reload\n- `pnpm phoenix sync` \u2014 Sync generated files without full build\n\n## 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)\n\n## Project Structure\n- `spec/` \u2014 Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` \u2014 Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` \u2014 Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` \u2014 Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` \u2014 ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` \u2014 Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` \u2014 Event & lifecycle handlers\n- `src/webhooks/` \u2014 Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` \u2014 Schema version migrations (v*.ts)\n- `src/locales/` \u2014 Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` \u2014 Admin interface (mirrors main src/ structure)\n- `src/_shared/` \u2014 Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` \u2014 Auto-generated files (DO NOT EDIT)\n- `public/` \u2014 Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` \u2014 Uploadable resources (PDF templates, email assets)\n\n## 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\n\n## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\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\n\n## File Conventions\n- Components: PascalCase (.tsx)\n- Utilities: kebab-case (.ts)\n- Expressions: entity-name.ts\n- Migrations: v*.ts (sequential)\n- Specs: kebab-case.yaml\n- Underscore folders (_shared/, _utils/) are NOT auto-imported\n\n## Export Rules\nAll files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\n\n## 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.\n\n## Do Not Edit\n- `.phoenix/` directory \u2014 completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files \u2014 compiled from .po files\n\n## Code Review\nUse `/review` command to review code changes before committing.\n\n## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` \u2014 Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` \u2014 Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` \u2014 Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` \u2014 Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` \u2014 List docs in a category\n- `pnpm phoenix docs -l` \u2014 List all doc paths with titles\n\n### 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`\n\n### 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` \u2014 Output file path (default: `./screenshot.png`)\n- `--width, -w` \u2014 Width in pixels (default: 1920)\n- `--height` \u2014 Height in pixels (default: 1080)\n- `--format, -f` \u2014 Image format: PNG or JPEG (default: PNG)\n- `--port` \u2014 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\n\n### 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` \u2014 Output file path (prints to stdout if omitted)\n- `--sections, -s` \u2014 Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 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` \u2014 domain data loaded\n- `domainContextReady` \u2014 domain context initialized (entities available)\n- `configuratorReady` \u2014 3D configurator initialized\n- `sessionAuthenticated` \u2014 session service active\n- `editorMode` \u2014 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\n\n### Inspect: Data\n\nGet the current editor context data as JSON via `pnpm phoenix inspect:data`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties\n\n**Example:** `pnpm phoenix inspect:data -o ./data.json`\n\n**Tips:** Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:data | head -30`).\n\n**Use cases:** AI agent context, debugging published/session/access data\n\n### Inspect: Scene\n\nGet the current Three.js scene graph as JSON via `pnpm phoenix inspect:scene`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.\n\n**Example:** `pnpm phoenix inspect:scene -o ./scene.json`\n\n**Tips:** Scene graphs can be large. Pipe through `head`/`tail` for partial output.\n\n**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` \u2014 Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` \u2014 End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` \u2014 Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` \u2014 ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` \u2014 Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` \u2014 YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` \u2014 Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` \u2014 Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` \u2014 Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` \u2014 Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` \u2014 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\"`\n\n### Playwright MCP Setup (for AI agents)\n\nTo interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@playwright/mcp@latest\",\n        \"--headed\",\n        \"--launch-options\",\n        \"{\\\"args\\\":[\\\"--use-gl=swiftshader\\\",\\\"--enable-webgl\\\",\\\"--ignore-gpu-blocklist\\\"]}\"\n      ]\n    }\n  }\n}\n```\n\nKey flags:\n- `--headed` \u2014 visible browser (required for GPU rendering)\n- `--use-gl=swiftshader` \u2014 software GPU fallback for environments without a physical GPU\n- `--enable-webgl` + `--ignore-gpu-blocklist` \u2014 ensure WebGL is available\n[PHOENIX-SDK-END]";
+export declare const sdkContent = "[PHOENIX-SDK-START]\n## Phoenix Configurator Project\n\nDeclarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.\n\n## Build Commands\n- `pnpm phoenix build` \u2014 Full production build\n- `pnpm phoenix dev` \u2014 Development mode with hot reload\n- `pnpm phoenix sync` \u2014 Sync generated files without full build\n\n## 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)\n\n## Project Structure\n- `spec/` \u2014 Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` \u2014 Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` \u2014 Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` \u2014 Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` \u2014 ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` \u2014 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, or the app loader stays on screen; put the UI above it, positioned and after it in the markup. Call `useSceneSafeArea()` (same import) 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\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints and errors yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): save and built-in action errors are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: run each with `phx.frontend.useFinalizeAction(handler)` in a component of its own wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`), or mount `FinalizeActions` (from `@salsita-ai/sdk/configurator`) for the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them: hide what a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true`, and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n- `src/handlers/` \u2014 Event & lifecycle handlers\n- `src/webhooks/` \u2014 Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` \u2014 Schema version migrations (v*.ts)\n- `src/locales/` \u2014 Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` \u2014 Admin interface (mirrors main src/ structure)\n- `src/_shared/` \u2014 Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` \u2014 Auto-generated files (DO NOT EDIT)\n- `public/` \u2014 Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` \u2014 Uploadable resources (PDF templates, email assets)\n\n## 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\n\n## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\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\n\n## File Conventions\n- Components: PascalCase (.tsx)\n- Utilities: kebab-case (.ts)\n- Expressions: entity-name.ts\n- Migrations: v*.ts (sequential)\n- Specs: kebab-case.yaml\n- Underscore folders (_shared/, _utils/) are NOT auto-imported\n\n## Export Rules\nAll files in src/expressions/, src/invariants/, src/transformers/, src/components/, src/handlers/, src/webhooks/ MUST use default exports. Can be a single item or an array. Named exports are ignored by the SDK auto-import system.\n\n## 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.\n\n## Do Not Edit\n- `.phoenix/` directory \u2014 completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files \u2014 compiled from .po files\n\n## Code Review\nUse `/review` command to review code changes before committing.\n\n## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` \u2014 Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` \u2014 Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` \u2014 Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` \u2014 Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` \u2014 List docs in a category\n- `pnpm phoenix docs -l` \u2014 List all doc paths with titles\n\n### 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`\n\n### 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` \u2014 Output file path (default: `./screenshot.png`)\n- `--width, -w` \u2014 Width in pixels (default: 1920)\n- `--height` \u2014 Height in pixels (default: 1080)\n- `--format, -f` \u2014 Image format: PNG or JPEG (default: PNG)\n- `--port` \u2014 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\n\n### 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` \u2014 Output file path (prints to stdout if omitted)\n- `--sections, -s` \u2014 Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 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` \u2014 domain data loaded\n- `domainContextReady` \u2014 domain context initialized (entities available)\n- `configuratorReady` \u2014 3D configurator initialized\n- `sessionAuthenticated` \u2014 session service active\n- `editorMode` \u2014 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\n\n### Inspect: Data\n\nGet the current editor context data as JSON via `pnpm phoenix inspect:data`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties\n\n**Example:** `pnpm phoenix inspect:data -o ./data.json`\n\n**Tips:** Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:data | head -30`).\n\n**Use cases:** AI agent context, debugging published/session/access data\n\n### Inspect: Scene\n\nGet the current Three.js scene graph as JSON via `pnpm phoenix inspect:scene`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` \u2014 Output file path (prints to stdout if omitted)\n- `--pretty` \u2014 Pretty-print JSON (default: true)\n- `--port` \u2014 WebSocket server port (default: 3020)\n\n**Returns:** Recursive scene tree with per-node: name, type, visible, position, rotation, scale, userData (entityId), and for meshes: geometry name, bounding box, material properties (color, metalness, roughness, opacity, textures), morph target influences. Lights include color, intensity, and type-specific properties.\n\n**Example:** `pnpm phoenix inspect:scene -o ./scene.json`\n\n**Tips:** Scene graphs can be large. Pipe through `head`/`tail` for partial output.\n\n**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` \u2014 Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` \u2014 End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` \u2014 Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` \u2014 ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` \u2014 Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` \u2014 YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` \u2014 Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` \u2014 Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` \u2014 Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` \u2014 Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` \u2014 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\"`\n\n### Playwright MCP Setup (for AI agents)\n\nTo interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to `~/.claude/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@playwright/mcp@latest\",\n        \"--headed\",\n        \"--launch-options\",\n        \"{\\\"args\\\":[\\\"--use-gl=swiftshader\\\",\\\"--enable-webgl\\\",\\\"--ignore-gpu-blocklist\\\"]}\"\n      ]\n    }\n  }\n}\n```\n\nKey flags:\n- `--headed` \u2014 visible browser (required for GPU rendering)\n- `--use-gl=swiftshader` \u2014 software GPU fallback for environments without a physical GPU\n- `--enable-webgl` + `--ignore-gpu-blocklist` \u2014 ensure WebGL is available\n[PHOENIX-SDK-END]";

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/agents/shared-sdk-content.js

@@ -21,6 +21,13 @@ 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, or the app loader stays on screen; put the UI above it, positioned and after it in the markup. Call \`useSceneSafeArea()\` (same import) 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
+    - Messages: mount \`LayoutSlots.Services\` for the built-in snackbars, or show violations, side-effect hints and errors yourself with \`phx.frontend.useConfiguratorMessages(onMessage)\`, not both. Either way mount a snackbar root (\`LayoutSlots.DesktopSnackbarsRoot\` or \`LayoutSlots.MobileSnackbarsRoot\`): save and built-in action errors are always snackbars
+    - Finalize over the spec's \`finalizeAction\` components, each naming a handler registered with \`phx.frontend.createPhoenixHandler\`: run each with \`phx.frontend.useFinalizeAction(handler)\` in a component of its own wrapped in \`PhoenixHandlerBoundary\` (from \`@salsita-ai/sdk/react\`), or mount \`FinalizeActions\` (from \`@salsita-ai/sdk/configurator\`) for the built-in buttons. \`finalizePage\` and \`finalizeButton\` are legacy
+    - Read mode and fullscreen are the layout's job, no hook enforces them: hide what a viewer must not change while \`phx.frontend.useAccessService().accessInfo.viewMode\` is \`true\`, and remove panels while \`phx.frontend.useIsFullscreenActive()\` is set; \`phx.frontend.useSetFullscreen()\` returns its setter
 - \`src/handlers/\` — Event & lifecycle handlers
 - \`src/webhooks/\` — Server-side webhook handlers (\`phx.webhooks.*Builder\`)
 - \`src/migrations/\` — Schema version migrations (v*.ts)

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/domain-index.js

@@ -2,39 +2,39 @@ import{fileHeader as n}from"./file-header.js";import{generateImports as i,getImp
   ${n.join(",\n  ")}
 )`,a=(n,i)=>{if(0===n.length)return"{}";let o=n.map((n,o)=>{let t=e(n);return null===t?null:`  ${t}: ${i[o]}`}).filter(n=>null!==n);return 0===o.length?"{}":`{
 ${o.join(",\n")}
-}`};export const generateIndexDomainFile=(s={})=>{let{includeMigrations:r=!0,includeI18n:m=!0,expressionsFiles:d=[],invariantsFiles:l=[],adminExpressionsFiles:p=[],adminInvariantsFiles:c=[],migrationsFiles:u=[],adminMigrationsFiles:g=[]}=s,x=(n,i)=>`${i?"adminMigrateToV":"migrateToV"}${e(n)}`,$=u.map(n=>{let i=e(n),o=n.replace(/\.ts$/,""),t=`../src/${o}.js`;return`import { migrateToV${i} } from '${t}'`}).join("\n"),f=g.map(n=>{let i=e(n),o=n.replace(/\.ts$/,""),t=`../src/${o}.js`;return`import { migrateToV${i} as adminMigrateToV${i} } from '${t}'`}).join("\n"),h=u.map(n=>x(n,!1)),A=g.map(n=>x(n,!0)),E=u.length>0,j=g.length>0,y=i(d,"expressions"),D=i(l,"invariants"),V=i(p,"adminExpressions"),v=i(c,"adminInvariants"),M=o(d,"expressions"),B=o(l,"invariants"),I=o(p,"adminExpressions"),F=o(c,"adminInvariants"),w=t(B),b=t(M),R=t(F),T=t(I),C=[y,D,V,v].filter(Boolean).join("\n"),P=[$,f].filter(Boolean).join("\n"),S=d.length>1||l.length>1||p.length>1||c.length>1,k=a(u,h),q=a(g,A),z=E?`
+}`};export const generateIndexDomainFile=(s={})=>{let{includeMigrations:r=!0,includeI18n:m=!0,expressionsFiles:d=[],invariantsFiles:l=[],adminExpressionsFiles:p=[],adminInvariantsFiles:c=[],migrationsFiles:x=[],adminMigrationsFiles:g=[]}=s,u=(n,i)=>`${i?"adminMigrateToV":"migrateToV"}${e(n)}`,$=x.map(n=>{let i=e(n),o=n.replace(/\.ts$/,""),t=`../src/${o}.js`;return`import { migrateToV${i} } from '${t}'`}).join("\n"),A=g.map(n=>{let i=e(n),o=n.replace(/\.ts$/,""),t=`../src/${o}.js`;return`import { migrateToV${i} as adminMigrateToV${i} } from '${t}'`}).join("\n"),h=x.map(n=>u(n,!1)),f=g.map(n=>u(n,!0)),E=x.length>0,j=g.length>0,y=i(d,"expressions"),D=i(l,"invariants"),V=i(p,"adminExpressions"),M=i(c,"adminInvariants"),F=o(d,"expressions"),I=o(l,"invariants"),v=o(p,"adminExpressions"),w=o(c,"adminInvariants"),B=t(I),R=t(F),b=t(w),T=t(v),C=[y,D,V,M].filter(Boolean).join("\n"),P=[$,A].filter(Boolean).join("\n"),S=d.length>1||l.length>1||p.length>1||c.length>1,k=a(x,h),q=a(g,f),z=E?`
 const migrations = ${k}
 
-const migrate = MigrateFunctionBuilder.fromVersions(modelVersions).to(modelVersion).using(migrations).build()`:"",G=j?`
+const migrate = createMigrateFunction(modelVersions, modelVersion, migrations)`:"",G=j?`
 const adminMigrations = ${q}
 
-const migrateAdmin = MigrateFunctionBuilder.fromVersions(adminModelVersions).to(adminModelVersion).using(adminMigrations).build()`:"";return`${n}
+const migrateAdmin = createMigrateFunction(adminModelVersions, adminModelVersion, adminMigrations)`:"";return`${n}
 ${S?"import merge from 'lodash-es/merge.js'\n":""}
-import { type AliasedExpressions${r&&(E||j)?", MigrateFunctionBuilder":""} } from '@salsita-ai/sdk/domain'
+import { type AliasedExpressions${r&&(E||j)?", createMigrateFunction":""}, createViolationExpressions } from '@salsita-ai/sdk/domain'
 
 ${m?"import { createI18n } from './i18n.js'":""}
-import { adminDomainBuilder, adminInvariantBuilder } from './domain/admin-implementation.js'
+import { adminDomainBuilder, commonAdminInvariants } from './domain/admin-implementation.js'
 import type {
   Aliases as AdminAliases,
   AnyDomainEntity as AdminAnyDomainEntity,
   RootEntity as AdminRootEntity,
 } from './domain/admin-model/index.js'
-${j?"import { modelVersion as adminModelVersion, modelVersions as adminModelVersions } from './domain/admin-model/index.js'\n":""}
+import { aliases as adminAliases${j?", modelVersion as adminModelVersion, modelVersions as adminModelVersions":""} } from './domain/admin-model/index.js'
 import type { FrontendData, PublishedData, SessionData } from './domain/application-types.js'
 import {
   generatedConfiguratorBuilder,
 } from './domain/configurator-builder.js'
-import { domainBuilder, invariantBuilder } from './domain/implementation.js'
+import { domainBuilder } from './domain/implementation.js'
 import type { Aliases, AnyDomainEntity, RootEntity } from './domain/model/index.js'
-${E?"import { modelVersion, modelVersions } from './domain/model/index.js'\n":""}
+import { aliases${E?", modelVersion, modelVersions":""} } from './domain/model/index.js'
 ${C?`
 ${C}`:""}
 ${P?`
 ${P}`:""}${z}${G}
 
-const customInvariants = ${w}
+const customInvariants = ${B}
 
-const violationExpressions = invariantBuilder.withInvariants(customInvariants).buildViolationExpressions()
+const violationExpressions = createViolationExpressions(aliases, [{ origin: '.phoenix/domain.ts', exports: customInvariants }])
 
 const customExpressions: AliasedExpressions<
   AnyDomainEntity,
@@ -43,18 +43,20 @@ const customExpressions: AliasedExpressions<
   SessionData,
   FrontendData,
   Aliases
-> = ${b}
+> = ${R}
 
 const domainFactory = domainBuilder
   .withExpressions(violationExpressions)
   .withExpressions(customExpressions)${r&&E?"\n  .withMigrate(migrate)":""}
   .build()
 
-const customAdminInvariants = ${R}
+const customAdminInvariants = ${b}
 
-const adminViolationExpressions = adminInvariantBuilder
-  .withInvariants(customAdminInvariants)
-  .buildViolationExpressions()
+const adminViolationExpressions = createViolationExpressions(
+  adminAliases,
+  [{ origin: '.phoenix/domain.ts', exports: customAdminInvariants }],
+  commonAdminInvariants
+)
 
 const customAdminExpressions: AliasedExpressions<
   AdminAnyDomainEntity,

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/frontend-admin.js

@@ -1,8 +1,7 @@
-import{fileHeader as e}from"./file-header.js";import{defaultEnvsCode as n,generateImports as i,generateModuleEntries as t,generateModuleList as o,generateThemeCode as a,generateTransformerMap as m,generateTransformerRegistration as r,generateTransformerTypeImports as s}from"./generator-shared.js";export const generateFrontendAdminFile=(p=[],d=[],c=[],l=[],$=[],f=[],g=[],h,u,A)=>{let F=i(p,"components"),S=o(t(p,"components")),C=i(d,"adminComponents"),j=o(t(d,"adminComponents")),w=i($,"handlers"),P=o(t($,"handlers")),I=i(f,"elements"),b=i(g,"adminElements"),x=o([...t(f,"elements"),...t(g,"adminElements")]),E=m(c,l),k=r(l),y=a(h,u),B=s(l.length>0),O=A?`
-import { createAdminPagesFromSpec } from '@salsita-ai/sdk/admin'
-import { $adminPagesSpec, $dataSpec } from './domain/application-types.js'`:"",H=A?`
+import{fileHeader as e}from"./file-header.js";import{defaultEnvsCode as n,generateImports as i,generateModuleEntries as t,generateModuleList as o,generateThemeCode as a,generateTransformerMap as m,generateTransformerRegistration as r,generateTransformerTypeImports as s}from"./generator-shared.js";export const generateFrontendAdminFile=(p=[],d=[],c=[],l=[],$=[],f=[],g=[],u,h,A)=>{let F=i(p,"components"),S=o(t(p,"components")),w=i(d,"adminComponents"),C=o(t(d,"adminComponents")),j=i($,"handlers"),E=o(t($,"handlers")),P=i(f,"elements"),I=i(g,"adminElements"),b=o([...t(f,"elements"),...t(g,"adminElements")]),x=m(c,l),k=r(l),y=a(u,h),B=s(l.length>0),O=A?`
+import { $adminPagesSpec, $dataSpec } from './domain/application-types.js'`:"",D=A?`
 const { components: specAdminComponents, pages: specAdminPages } = createAdminPagesFromSpec($adminPagesSpec, $dataSpec)
-`:"",q=A?`[{ origin: '.phoenix/domain/application-types.ts', exports: specAdminComponents }, ...${j}]`:j;return`// prettier-ignore-file
+`:"",H=A?`[{ origin: '.phoenix/domain/application-types.ts', exports: specAdminComponents }, ...${C}]`:C;return`// prettier-ignore-file
 
 ${e}
 ${B?`${B}
@@ -11,23 +10,25 @@ import * as interfaceFile from './configurator-interface.js'
 import * as adminInterfaceFile from './admin-interface.js'
 
 import { mountStandaloneAdminApplication } from '@salsita-ai/sdk/application'
+import { ${A?"createAdminPagesFromSpec, ":""}defaultAdminElements } from '@salsita-ai/sdk/admin'
 
 import { configuratorBuilder } from './domain.js'${O}
 ${F?`
-${F}`:""}${C?`
-${C}`:""}${w?`
-${w}`:""}${I?`
-${I}`:""}${b?`
-${b}`:""}${y.imports?`
-${y.imports}`:""}${E}
-${H}
+${F}`:""}${w?`
+${w}`:""}${j?`
+${j}`:""}${P?`
+${P}`:""}${I?`
+${I}`:""}${y.imports?`
+${y.imports}`:""}${x}
+${D}
 let builder = configuratorBuilder
   .withInterface(interfaceFile)
   .withInterface(adminInterfaceFile)
   .withComponentOptics(${S})
-  .withAdminComponentOptics(${q})
-  .withHandlers(${P})
-  .withElements(${x})
+  .withAdminComponentOptics(${H})
+  .withHandlers(${E})
+  .withDefaultElements(defaultAdminElements)
+  .withElements(${b})
 ${n}${y.code?`
 ${y.code}`:""}
 

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/frontend-configurator.js

@@ -1,23 +1,25 @@
-import{fileHeader as o}from"./file-header.js";import{defaultEnvsCode as e,generateImports as r,generateModuleEntries as t,generateModuleList as i,generateThemeCode as n,generateTransformerMap as a,generateTransformerRegistration as s,generateTransformerTypeImports as c}from"./generator-shared.js";export const generateFrontendConfiguratorFile=(l=[],$=[],f=[],m=[],p=[],d,g,u=!0,h=!1)=>{let C=r(l,"components"),j=i(t(l,"components")),w=r(m,"handlers"),F=i(t(m,"handlers")),b=r(p,"elements"),x=i(t(p,"elements")),A=a($,f),B=s(f),k=n(d,g),E=c(f.length>0);return`// prettier-ignore-file
-${o}
-${h?"":"import { mountConfiguratorApplication } from '@salsita-ai/sdk/application'\n"}${E?`${E}
+import{fileHeader as t}from"./file-header.js";import{defaultEnvsCode as e,generateImports as o,generateModuleEntries as r,generateModuleList as i,generateThemeCode as n,generateTransformerMap as a,generateTransformerRegistration as s,generateTransformerTypeImports as l}from"./generator-shared.js";export const generateFrontendConfiguratorFile=(f=[],m=[],c=[],$=[],p=[],u,d,g=!0,h=!1)=>{let C=o(f,"components"),w=i(r(f,"components")),j=o($,"handlers"),E=i(r($,"handlers")),F=o(p,"elements"),b=i(r(p,"elements")),k=a(m,c),x=s(c),A=n(u,d),B=l(c.length>0);return`// prettier-ignore-file
+${t}
+${h?"":"import { mountConfiguratorApplication } from '@salsita-ai/sdk/application'\n"}import { defaultConfiguratorElements } from '@salsita-ai/sdk/configurator'
+${B?`${B}
 `:""}
 import * as interfaceFile from './configurator-interface.js'
 
 import { configuratorBuilder } from './domain.js'
 ${C?`
-${C}`:""}${w?`
-${w}`:""}${b?`
-${b}`:""}${k.imports?`
-${k.imports}`:""}${A}
+${C}`:""}${j?`
+${j}`:""}${F?`
+${F}`:""}${A.imports?`
+${A.imports}`:""}${k}
 
 const builder = configuratorBuilder
   .withInterface(interfaceFile)
-  .withComponentOptics(${j})
-  .withHandlers(${F})
-  .withElements(${x})
-${u?e:""}${k.code?`
-${k.code}`:""}${B}
+  .withComponentOptics(${w})
+  .withHandlers(${E})
+  .withDefaultElements(defaultConfiguratorElements)
+  .withElements(${b})
+${g?e:""}${A.code?`
+${A.code}`:""}${x}
 
 
 ${h?"export const config = ":"const config = "}builder.buildConfig()

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/frontend-embedded-admin.js

@@ -1,34 +1,35 @@
-import{fileHeader as e}from"./file-header.js";import{defaultEnvsCode as i,generateImports as n,generateModuleEntries as t,generateModuleList as o,generateThemeCode as m,generateTransformerMap as a,generateTransformerRegistration as r,generateTransformerTypeImports as s}from"./generator-shared.js";export const getFrontendEmbeddedAdminFile=(d,p,c=[],$=[],l=[],f=[],g=[],u=[],h=[],A,F,C)=>{let b=n(c,"components"),j=o(t(c,"components")),w=n($,"adminComponents"),E=o(t($,"adminComponents")),S=n(g,"handlers"),P=o(t(g,"handlers")),x=n(u,"elements"),I=n(h,"adminElements"),k=o([...t(u,"elements"),...t(h,"adminElements")]),y=a(l,f),B=r(f),O=m(A,F),H=s(f.length>0),q=C?`
-import { createAdminPagesFromSpec } from '@salsita-ai/sdk/admin'
-import { $adminPagesSpec, $dataSpec } from './domain/application-types.js'`:"",v=C?`
+import{fileHeader as e}from"./file-header.js";import{defaultEnvsCode as n,generateImports as i,generateModuleEntries as t,generateModuleList as o,generateThemeCode as m,generateTransformerMap as a,generateTransformerRegistration as r,generateTransformerTypeImports as s}from"./generator-shared.js";export const getFrontendEmbeddedAdminFile=(d,p,c=[],l=[],$=[],f=[],g=[],u=[],h=[],A,E,F)=>{let w=i(c,"components"),C=o(t(c,"components")),b=i(l,"adminComponents"),j=o(t(l,"adminComponents")),S=i(g,"handlers"),P=o(t(g,"handlers")),x=i(u,"elements"),I=i(h,"adminElements"),k=o([...t(u,"elements"),...t(h,"adminElements")]),y=a($,f),B=r(f),O=m(A,E),D=s(f.length>0),H=F?`
+import { $adminPagesSpec, $dataSpec } from './domain/application-types.js'`:"",q=F?`
 const { components: specAdminComponents, pages: specAdminPages } = createAdminPagesFromSpec($adminPagesSpec, $dataSpec)
-`:"",z=C?`[{ origin: '.phoenix/domain/application-types.ts', exports: specAdminComponents }, ...${E}]`:E;return`// prettier-ignore-file
+`:"",v=F?`[{ origin: '.phoenix/domain/application-types.ts', exports: specAdminComponents }, ...${j}]`:j;return`// prettier-ignore-file
 
 ${e}
-${H?`${H}
+${D?`${D}
 `:""}
 import * as interfaceFile from './configurator-interface.js'
 import * as adminInterfaceFile from './admin-interface.js'
 
 import { mountEmbeddedAdminApplication } from '@salsita-ai/sdk/application'
+import { ${F?"createAdminPagesFromSpec, ":""}defaultAdminElements } from '@salsita-ai/sdk/admin'
 
-import { configuratorBuilder } from './domain.js'${q}
-${b?`
-${b}`:""}${w?`
-${w}`:""}${S?`
+import { configuratorBuilder } from './domain.js'${H}
+${w?`
+${w}`:""}${b?`
+${b}`:""}${S?`
 ${S}`:""}${x?`
 ${x}`:""}${I?`
 ${I}`:""}${O.imports?`
 ${O.imports}`:""}${y}
-${v}
+${q}
 let builder = configuratorBuilder
   .withInterface(interfaceFile)
   .withInterface(adminInterfaceFile)
-  .withComponentOptics(${j})
-  .withAdminComponentOptics(${z})
+  .withComponentOptics(${C})
+  .withAdminComponentOptics(${v})
   .withHandlers(${P})
+  .withDefaultElements(defaultAdminElements)
   .withElements(${k})
-${i}${O.code?`
+${n}${O.code?`
 ${O.code}`:""}
 
 ${B}

package/dist/legacy/phoenix-cli/project-gen/generators/file-templates/frontend-embedded-configurator.js

@@ -1,34 +1,36 @@
-import{fileHeader as e}from"./file-header.js";import{defaultEnvsCode as o,generateImports as t,generateModuleEntries as r,generateModuleList as i,generateThemeCode as n,generateTransformerMap as a,generateTransformerRegistration as d,generateTransformerTypeImports as m}from"./generator-shared.js";export const getFrontendEmbeddedConfiguratorFile=(s,l,f=[],$=[],c=[],p=[],u=[],g,h)=>{let b=t(f,"components"),C=i(r(f,"components")),j=t(p,"handlers"),w=i(r(p,"handlers")),E=t(u,"elements"),F=i(r(u,"elements")),x=a($,c),A=d(c),B=n(g,h),k=m(c.length>0);return`// prettier-ignore-file
+import{fileHeader as e}from"./file-header.js";import{defaultEnvsCode as t,generateImports as o,generateModuleEntries as r,generateModuleList as i,generateThemeCode as n,generateTransformerMap as a,generateTransformerRegistration as l,generateTransformerTypeImports as s}from"./generator-shared.js";export const getFrontendEmbeddedConfiguratorFile=(f,m,d=[],u=[],c=[],$=[],p=[],g,h)=>{let C=o(d,"components"),E=i(r(d,"components")),b=o($,"handlers"),w=i(r($,"handlers")),j=o(p,"elements"),F=i(r(p,"elements")),k=a(u,c),x=l(c),A=n(g,h),B=s(c.length>0);return`// prettier-ignore-file
 
 ${e}
-${k?`${k}
+${B?`${B}
 `:""}
 import * as interfaceFile from './configurator-interface.js'
 
 import { mountEmbeddedConfiguratorApplication } from '@salsita-ai/sdk/application'
+import { defaultConfiguratorElements } from '@salsita-ai/sdk/configurator'
 
 import { configuratorBuilder } from './domain.js'
-${b?`
+${C?`
+${C}`:""}${b?`
 ${b}`:""}${j?`
-${j}`:""}${E?`
-${E}`:""}${B.imports?`
-${B.imports}`:""}${x}
+${j}`:""}${A.imports?`
+${A.imports}`:""}${k}
 
 const builder = configuratorBuilder
   .withInterface(interfaceFile)
-  .withComponentOptics(${C})
+  .withComponentOptics(${E})
   .withHandlers(${w})
+  .withDefaultElements(defaultConfiguratorElements)
   .withElements(${F})
-${o}${B.code?`
-${B.code}`:""}${A}
+${t}${A.code?`
+${A.code}`:""}${x}
 
 
 const config = builder.buildConfig()
 
 export default {
   mount: () => {
-    mountEmbeddedConfiguratorApplication(config, '${s}', '${l}')
-    return 'salsita-configurator-${s}-${l}'
+    mountEmbeddedConfiguratorApplication(config, '${f}', '${m}')
+    return 'salsita-configurator-${f}-${m}'
   },
   config,
 }

package/dist/phoenix/application-spec/application-spec-builder.d.ts

@@ -7,8 +7,6 @@ interface ApplicationSpecBuilderConfig {
     readonly projectSlug: string;
     readonly environmentSlug: string;
     readonly cliUseWorkspace?: boolean;
-    readonly name?: string;
-    readonly description?: string;
     readonly enableEditor: boolean;
     readonly inlineTemplates: boolean;
 }

package/dist/phoenix/application-spec/application-spec-builder.js

@@ -1 +1 @@
-import{existsSync as e,lstatSync as i,readFileSync as t,readdirSync as r,rmSync as o,unlinkSync as s}from"fs";import{join as n}from"path";import{format as a}from"prettier";import{prettierrc as l}from"@salsita-ai/common/prettier";import{GeneratedApplication as c,GeneratedApplicationFile as p,RuntimeReferenceStore as g,buildPhoenixDefinitions as f,createContentDiffTracker as h,generateApplicationCode as m,parseApplicationFiles as d}from"#package/application-spec";import{getAllPhxDefinitions as u}from"#package/domain";import{compileWithSwc as S}from"../services/swc.js";import{syncChangedFiles as b}from"../utils/index.js";import{readApplicationFiles as w}from"./application-spec-file-reader.js";import{cleanStaleAgentSkills as j,removeProjectFiles as v}from"./clean-project-files.js";import{swcEvalExpressionParser as D,swcModuleAnalyzer as F}from"./swc-module-analyzer.js";let x=".phoenix",y=`${x}/`,P=async e=>{if(e.binary||!1===e.format)return e;try{let i=await a(e.content,{...l,filepath:e.path});return p(e.path,i,{binary:e.binary,format:e.format})}catch{return e}},k=async e=>{let[i,t,r]=await Promise.all([Promise.all(e.generatedProjectFiles.map(P)),Promise.all(e.initialProjectFiles.map(P)),Promise.all(e.prettierFiles.map(P))]);return c({files:e.files,generatedProjectFiles:i,initialProjectFiles:t,prettierFiles:r,removedProjectFiles:e.removedProjectFiles})};export class ApplicationSpecBuilder{contentDiff;referenceStore;config;logger;phxDefinitions;constructor(e){this.config=e,this.logger=e.logger,this.referenceStore=new g,this.contentDiff=h({readDiskContent:this.readDiskContent}),this.phxDefinitions=f(u())}async build(e){let i=e?.parsingContext,t=e?.compile??!0;e?.force&&this.referenceStore.clear();let r=i?.startSpan("readFiles","build","application-spec-builder.ts"),o=e?.rawProjectFiles??await w({envs:{}});r?.();let s=d({rawProjectFiles:o,phxDefinitions:this.phxDefinitions},{analyzer:F,evalExpressionParser:D,referenceStore:this.referenceStore,logger:this.logger,parsingContext:i});if(!s.ok)return{ok:!1,rawProjectFiles:o,errors:s.errors,diagnostics:s.diagnostics,metrics:s.metrics,counts:s.counts};let{applicationSpec:n,categorizedFiles:a,rawMockTemplates:l}=s.value,c=i?.startSpan("generateCode","build","application-spec-builder.ts"),p=m({applicationSpec:n,categorizedFiles:a,phxDefinitions:this.phxDefinitions,sdkVersion:this.config.sdkVersion,cliUseWorkspace:this.config.cliUseWorkspace,name:this.config.name,description:this.config.description,projectSlug:this.config.projectSlug,environmentSlug:this.config.environmentSlug,enableEditor:this.config.enableEditor,inlineTemplates:this.config.inlineTemplates,rawMockTemplates:l});c?.();let g=i?.startSpan("cleanStaleFiles","build","application-spec-builder.ts"),f=new Set(p.files.map(e=>e.path));this.cleanStaleGeneratedFiles(f),v(p.removedProjectFiles,{logger:this.logger}),j(new Set(p.generatedProjectFiles.map(e=>e.path)),{logger:this.logger}),g?.();let h=i?.startSpan("contentDiff","build","application-spec-builder.ts"),u=await k(p),S=this.contentDiff.getChangedApplicationFiles(u,{generatedFilesPathPrefix:y,force:e?.force}),x=S.changedGeneratedFiles;h?.(),x.length>0?this.logger.info(`  ${x.length}/${p.files.length} generated files changed`):this.logger.info("  No generated files changed");let P=S.filesToWrite.length-x.length;P>0&&this.logger.info(`  ${P} project files changed`);let C=i?.startSpan("writeFiles","build","application-spec-builder.ts");return await b(S.filesToWrite,{logger:this.logger,skipChecksum:!0}),C?.(),t&&await this.compile(i),{ok:!0,application:s.value,changedFiles:x,diagnostics:s.diagnostics,metrics:s.metrics,counts:s.counts}}async compile(e){let i=e?.startSpan("swcCompile(src)","build","application-spec-builder.ts");await S({sourceDir:"src",outDir:`./${x}/.swc/src`},{logger:this.logger}),i?.();let t=e?.startSpan("swcCompile(.phoenix)","build","application-spec-builder.ts");await S({sourceDir:x,outDir:`./${x}/.swc/${x}`},{logger:this.logger}),t?.()}readDiskContent=i=>{try{if(e(i))return t(i,"utf-8")}catch{}};cleanStaleGeneratedFiles(t){let a=new Set(["public",".swc","dist","phoenix-dev.log","phoenix-dev.log.1","phoenix-dev.log.2","variants","variant-recovery.json"]);try{if(!e(x))return;for(let e of r(x)){if(a.has(e)||t.has(e))continue;let r=n(x,e);try{let e=i(r);if(e.isSymbolicLink())continue;e.isDirectory()?o(r,{recursive:!0}):s(r),this.logger.debug(`  Removed stale: ${r}`)}catch{}}}catch{}}}
+import{existsSync as e,lstatSync as t,readFileSync as i,readdirSync as r,rmSync as s,unlinkSync as n}from"fs";import{join as o}from"path";import{format as a,resolveConfig as l}from"prettier";import{prettierrc as c}from"@salsita-ai/common/prettier";import{GeneratedApplication as p,GeneratedApplicationFile as g,RuntimeReferenceStore as d,buildPhoenixDefinitions as h,createContentDiffTracker as f,generateApplicationCode as m,isTextFile as u,parseApplicationFiles as k}from"#package/application-spec";import{getAllPhxDefinitions as S}from"#package/domain";import{findSdkPeerMismatches as b}from"../commands/deps/index.js";import{compileWithSwc as j}from"../services/swc.js";import{findPackageManagerCommands as w,isInsideGitRepository as v,syncChangedFiles as y}from"../utils/index.js";import{readApplicationFiles as x}from"./application-spec-file-reader.js";import{cleanStaleAgentSkills as $,removeProjectFiles as F}from"./clean-project-files.js";import{swcEvalExpressionParser as D,swcModuleAnalyzer as P}from"./swc-module-analyzer.js";let C=".phoenix",E=`${C}/`,T="@salsita-ai/sdk",A=e=>({code:"SDK_PEER_MISMATCH",message:e,severity:"error",path:[]}),N=async e=>{try{return await l(e)??c}catch{return c}},V=async e=>{if(e.binary||!1===e.format)return e;try{let t=await a(e.content,{...await N(e.path),filepath:e.path});return g(e.path,t,{binary:e.binary,format:!1})}catch{return g(e.path,e.content,{binary:e.binary,format:!1})}},_=async e=>{let[t,i]=await Promise.all([Promise.all(e.generatedProjectFiles.map(V)),Promise.all(e.initialProjectFiles.map(V))]);return p({files:e.files,generatedProjectFiles:t,initialProjectFiles:i,removedProjectFiles:e.removedProjectFiles})};export class ApplicationSpecBuilder{contentDiff;referenceStore;config;logger;phxDefinitions;constructor(e){this.config=e,this.logger=e.logger,this.referenceStore=new d,this.contentDiff=f({readDiskContent:this.readDiskContent}),this.phxDefinitions=h(S())}async build(e){let t=e?.parsingContext,i=e?.compile??!0;e?.force&&this.referenceStore.clear();let r=t?.startSpan("readFiles","build","application-spec-builder.ts"),s=e?.rawProjectFiles??await x({envs:{}});r?.();let n=k({rawProjectFiles:s,phxDefinitions:this.phxDefinitions},{analyzer:P,evalExpressionParser:D,referenceStore:this.referenceStore,logger:this.logger,parsingContext:t});if(!n.ok)return{ok:!1,rawProjectFiles:s,errors:n.errors,diagnostics:n.diagnostics,metrics:n.metrics,counts:n.counts};let{applicationSpec:o,categorizedFiles:a,rawMockTemplates:l}=n.value,c=(e=>{let t,i,r=e.rawFiles.files.filter(u).find(e=>"package.json"===e.name),s={};try{s=void 0===r?{}:JSON.parse(r.content)}catch(e){return A(`package.json is not valid JSON (${e instanceof Error?e.message:String(e)}), so the build cannot check that it declares the packages ${T} needs. Fix the file and run the command again.`)}if(!("object"==typeof(t=s)&&null!==t&&!Array.isArray(t)))return A(`package.json is not a JSON object, so the build cannot check that it declares the packages ${T} needs. Fix the file and run the command again.`);let n=b({packageJson:s,useClerk:e.useClerk});if(0===n.length)return;let o=n.map(({peer:e,found:t})=>void 0===t?`  ${e.name}: needs ${e.range}, missing`:`  ${e.name}: needs ${e.range}, found ${t.specifier} in ${t.field}`);return A([`package.json does not declare the packages ${T} ${e.sdkVersion} needs next to it at versions it supports:`,...o,`The SDK's code imports these packages from the project's install. ${void 0===(i=w(process.env.npm_config_user_agent))?"Run `phoenix deps` through your package manager, then install the dependencies, and run this command again.":`Run \`${i.phoenix("deps")}\`, then \`${i.install}\`, and run this command again.`}`].join("\n"))})({rawFiles:s,useClerk:o.appMetadata.useClerk,sdkVersion:this.config.sdkVersion});if(void 0!==c)return{ok:!1,rawProjectFiles:s,errors:[c],diagnostics:n.diagnostics,metrics:n.metrics,counts:n.counts};let p=t?.startSpan("generateCode","build","application-spec-builder.ts"),g=v(process.cwd());g||this.logger.debug("  Not inside a git repository, .gitignore is not written");let d=m({applicationSpec:o,categorizedFiles:a,phxDefinitions:this.phxDefinitions,sdkVersion:this.config.sdkVersion,projectInGitRepository:g,cliUseWorkspace:this.config.cliUseWorkspace,projectSlug:this.config.projectSlug,environmentSlug:this.config.environmentSlug,enableEditor:this.config.enableEditor,inlineTemplates:this.config.inlineTemplates,rawMockTemplates:l});p?.();let h=t?.startSpan("cleanStaleFiles","build","application-spec-builder.ts"),f=new Set(d.files.map(e=>e.path));this.cleanStaleGeneratedFiles(f),F(d.removedProjectFiles,{logger:this.logger}),$(new Set(d.generatedProjectFiles.map(e=>e.path)),{logger:this.logger}),h?.();let S=t?.startSpan("contentDiff","build","application-spec-builder.ts"),j=await _(d),C=this.contentDiff.getChangedApplicationFiles(j,{generatedFilesPathPrefix:E,force:e?.force}),N=C.changedGeneratedFiles;S?.(),N.length>0?this.logger.info(`  ${N.length}/${d.files.length} generated files changed`):this.logger.info("  No generated files changed");let V=C.filesToWrite.length-N.length;V>0&&this.logger.info(`  ${V} project files changed`);let R=t?.startSpan("writeFiles","build","application-spec-builder.ts");return await y(C.filesToWrite,{logger:this.logger,skipChecksum:!0}),R?.(),i&&await this.compile(t),{ok:!0,application:n.value,changedFiles:N,diagnostics:n.diagnostics,metrics:n.metrics,counts:n.counts}}async compile(e){let t=e?.startSpan("swcCompile(src)","build","application-spec-builder.ts");await j({sourceDir:"src",outDir:`./${C}/.swc/src`},{logger:this.logger}),t?.();let i=e?.startSpan("swcCompile(.phoenix)","build","application-spec-builder.ts");await j({sourceDir:C,outDir:`./${C}/.swc/${C}`},{logger:this.logger}),i?.()}readDiskContent=t=>{try{if(e(t))return i(t,"utf-8")}catch{}};cleanStaleGeneratedFiles(i){let a=new Set(["public",".swc","dist","phoenix-dev.log","phoenix-dev.log.1","phoenix-dev.log.2","variants","variant-recovery.json",".env.generated"]);try{if(!e(C))return;for(let e of r(C)){if(a.has(e)||i.has(e))continue;let r=o(C,e);try{let e=t(r);if(e.isSymbolicLink())continue;e.isDirectory()?s(r,{recursive:!0}):n(r),this.logger.debug(`  Removed stale: ${r}`)}catch{}}}catch{}}}

package/dist/phoenix/application-spec/generate-application-spec-project.d.ts

@@ -4,8 +4,6 @@ interface GenerateProjectOptions {
     readonly projectSlug: string;
     readonly environmentSlug: string;
     readonly cliUseWorkspace?: boolean;
-    readonly name?: string;
-    readonly description?: string;
     readonly enableEditor?: boolean;
     readonly inlineTemplates?: boolean;
     readonly withLingui?: boolean;

package/dist/phoenix/application-spec/generate-application-spec-project.js

@@ -1,2 +1,2 @@
-import{symlink as e}from"fs/promises";import{ParseContext as i}from"#package/application-spec";import{extractAndCompileLingui as t}from"../services/lingui.js";import{compileWithSwc as p}from"../services/swc.js";import{exists as a}from"../utils/index.js";import{ApplicationSpecBuilder as s}from"./application-spec-builder.js";import{formatMetrics as r}from"./metrics/index.js";import{syncTemplateFiles as n}from"./template-files.js";let o=".phoenix",c=async(e,i)=>{let t=i.startSpan("swcCompile(src)","sync","generate-application-spec-project.ts");await p({sourceDir:"src",outDir:`./${o}/.swc/src`},{logger:e}),t();let a=i.startSpan("swcCompile(.phoenix)","sync","generate-application-spec-project.ts");await p({sourceDir:o,outDir:`./${o}/.swc/${o}`},{logger:e}),a()};export const generateApplicationSpecProject=async p=>{let{withLingui:o=!0,force:l=!1,analyze:m=!1}=p,u=p.logger;u.info("Using application-spec pipeline");let g=new i,j=g.startSpan("sync","generateApplicationSpecProject","generate-application-spec-project.ts"),w=g.startSpan("build","sync","application-spec-builder.ts"),d=new s({logger:u,sdkVersion:p.sdkVersion,projectSlug:p.projectSlug,environmentSlug:p.environmentSlug,cliUseWorkspace:p.cliUseWorkspace,name:p.name,description:p.description,enableEditor:p.enableEditor??!0,inlineTemplates:p.inlineTemplates??!1}),S=await d.build({force:l,parsingContext:g,compile:!1});if(w(),!S.ok)throw Error(`Failed to parse application spec:
-${S.errors.map(e=>`  [${e.code}] ${e.message}`).join("\n")}`);let f=g.startSpan("symlink","sync","generate-application-spec-project.ts");await a("./.phoenix/public")||await e("../public","./.phoenix/public");let b=await n();if(f(),o){let e=g.startSpan("lingui","sync","generate-application-spec-project.ts");await t({logger:u}),e()}return await c(u,g),j(),m&&r(g.metrics,g.counts,u),{templateFiles:b,applicationSpec:S.application.applicationSpec}};
+import{symlink as e}from"fs/promises";import{ParseContext as i}from"#package/application-spec";import{extractAndCompileLingui as t}from"../services/lingui.js";import{compileWithSwc as p}from"../services/swc.js";import{exists as a}from"../utils/index.js";import{ApplicationSpecBuilder as r}from"./application-spec-builder.js";import{formatMetrics as s}from"./metrics/index.js";import{syncTemplateFiles as o}from"./template-files.js";let c=".phoenix",n=async(e,i)=>{let t=i.startSpan("swcCompile(src)","sync","generate-application-spec-project.ts");await p({sourceDir:"src",outDir:`./${c}/.swc/src`},{logger:e}),t();let a=i.startSpan("swcCompile(.phoenix)","sync","generate-application-spec-project.ts");await p({sourceDir:c,outDir:`./${c}/.swc/${c}`},{logger:e}),a()};export const generateApplicationSpecProject=async p=>{let{withLingui:c=!0,force:l=!1,analyze:m=!1}=p,u=p.logger;u.info("Using application-spec pipeline");let g=new i,j=g.startSpan("sync","generateApplicationSpecProject","generate-application-spec-project.ts"),w=g.startSpan("build","sync","application-spec-builder.ts"),f=new r({logger:u,sdkVersion:p.sdkVersion,projectSlug:p.projectSlug,environmentSlug:p.environmentSlug,cliUseWorkspace:p.cliUseWorkspace,enableEditor:p.enableEditor??!0,inlineTemplates:p.inlineTemplates??!1}),S=await f.build({force:l,parsingContext:g,compile:!1});if(w(),!S.ok)throw Error(`Failed to build the project files:
+${S.errors.map(e=>`  [${e.code}] ${e.message}`).join("\n")}`);let d=g.startSpan("symlink","sync","generate-application-spec-project.ts");await a("./.phoenix/public")||await e("../public","./.phoenix/public");let b=await o();if(d(),c){let e=g.startSpan("lingui","sync","generate-application-spec-project.ts");await t({logger:u}),e()}return await n(u,g),j(),m&&s(g.metrics,g.counts,u),{templateFiles:b,applicationSpec:S.application.applicationSpec}};

package/dist/phoenix/application-spec/generate-application-spec-story.js

@@ -1,2 +1,2 @@
-import{readFile as e}from"node:fs/promises";import{basename as o,join as r}from"node:path";import{GeneratedApplicationFile as a,RuntimeReferenceStore as i,buildPhoenixDefinitions as t,generateApplicationSpecStoryFiles as n,getStoryTextFiles as p,parseApplicationFiles as s}from"#package/application-spec";import{getAllPhxDefinitions as m}from"#package/domain";import{exists as c,runCommand as g,syncChangedFiles as l,toPascalCase as d}from"../utils/index.js";import{readApplicationFiles as f}from"./application-spec-file-reader.js";import{generateStoryMdxContent as u}from"./story-mdx.js";import{swcEvalExpressionParser as w,swcModuleAnalyzer as x}from"./swc-module-analyzer.js";export const generateApplicationSpecStory=async(y,j)=>{let v=await f({projectRoot:y,envs:{}}),b=p(v),h=t(m()),E=s({rawProjectFiles:v,phxDefinitions:h},{analyzer:x,evalExpressionParser:w,referenceStore:new i,logger:j.logger});if(!E.ok)throw Error(`Cannot build application-spec story because the project spec is invalid. Fix these diagnostics and rebuild:
-${E.errors.map(e=>`  [${e.code}] ${e.message}`).join("\n")}`);let S=o(y),$=d(S),k=n({application:E.value,phxDefinitions:h,rawProjectFiles:v,storyFolderName:S,storyName:$}).map(e=>a(r(y,e.path),e.content,{binary:e.binary,format:e.format})),C=r(y,`${$}.mdx`),L=await c(C)?await e(C,"utf-8"):void 0,q=a(C,u({existingMdx:L,storyName:$,textFiles:b}));await l([...k,q],{logger:j.logger}),await g({command:"npx ",args:["lingui","extract"],description:"Extracting i18n messages",quiet:!0,cwd:y,extraEnv:{LC_ALL:"en_US.UTF-8"}},{logger:j.logger}),await g({command:"npx ",args:["lingui","compile"],description:"Compiling i18n messages",quiet:!0,cwd:y},{logger:j.logger})};
+import{readFile as e}from"node:fs/promises";import{basename as i,join as a}from"node:path";import{GeneratedApplicationFile as o,RuntimeReferenceStore as r,buildPhoenixDefinitions as t,generateApplicationSpecStoryFiles as n,getStoryTextFiles as p,parseApplicationFiles as s}from"#package/application-spec";import{getAllPhxDefinitions as l}from"#package/domain";import{exists as m,runSdkTool as c,syncChangedFiles as g,toPascalCase as d}from"../utils/index.js";import{readApplicationFiles as f}from"./application-spec-file-reader.js";import{generateStoryMdxContent as u}from"./story-mdx.js";import{swcEvalExpressionParser as w,swcModuleAnalyzer as x}from"./swc-module-analyzer.js";export const generateApplicationSpecStory=async(y,b)=>{let j=await f({projectRoot:y,envs:{}}),v=p(j),h=t(l()),k=s({rawProjectFiles:j,phxDefinitions:h},{analyzer:x,evalExpressionParser:w,referenceStore:new r,logger:b.logger});if(!k.ok)throw Error(`Cannot build application-spec story because the project spec is invalid. Fix these diagnostics and rebuild:
+${k.errors.map(e=>`  [${e.code}] ${e.message}`).join("\n")}`);let E=i(y),N=d(E),S=n({application:k.value,phxDefinitions:h,rawProjectFiles:j,storyFolderName:E,storyName:N}).map(e=>o(a(y,e.path),e.content,{binary:e.binary,format:e.format})),$=a(y,`${N}.mdx`),C=await m($)?await e($,"utf-8"):void 0,L=o($,u({existingMdx:C,storyName:N,textFiles:v}));await g([...S,L],{logger:b.logger}),await c({tool:{packageName:"@lingui/cli",binName:"lingui"},args:["extract"],description:"Extracting i18n messages",quiet:!0,cwd:y,extraEnv:{LC_ALL:"en_US.UTF-8"}},{logger:b.logger}),await c({tool:{packageName:"@lingui/cli",binName:"lingui"},args:["compile"],description:"Compiling i18n messages",quiet:!0,cwd:y},{logger:b.logger})};