@salsita-ai/sdk 0.50.0-develop.da8d27f5d7 → 0.50.0-develop.db8514eccf

package/dist/react-sdk/application-runtime/runtime/create-application-runtime.d.ts

@@ -404,6 +404,8 @@ export declare function createApplicationRuntimeSlices<State extends Application
                 getActiveConfigurationId: () => string;
                 getFactory: () => import("#package/domain").AnyDomainFactory;
                 getDomainExpressions: () => import("#package/domain").AnyExpressions;
+                getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
+                getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
                 getModelVersion: () => number;
                 getAliasMap: () => import("#package/domain").AnyAliasMap;
                 getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -444,6 +446,7 @@ export declare function createApplicationRuntimeSlices<State extends Application
                 getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
                 getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
                 getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
+                getActionSystem: () => import("#package/domain").AnyActionSystem;
                 getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
                 getExpressionContext: () => import("#package/domain").AnyExpressionContext;
                 getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -510,6 +513,8 @@ export declare function createApplicationRuntimeSlices<State extends Application
                 getActiveConfigurationId: () => string;
                 getFactory: () => import("#package/domain").AnyDomainFactory;
                 getDomainExpressions: () => import("#package/domain").AnyExpressions;
+                getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
+                getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
                 getModelVersion: () => number;
                 getAliasMap: () => import("#package/domain").AnyAliasMap;
                 getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -550,6 +555,7 @@ export declare function createApplicationRuntimeSlices<State extends Application
                 getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
                 getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
                 getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
+                getActionSystem: () => import("#package/domain").AnyActionSystem;
                 getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
                 getExpressionContext: () => import("#package/domain").AnyExpressionContext;
                 getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -1058,6 +1064,8 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
                 getActiveConfigurationId: () => string;
                 getFactory: () => import("#package/domain").AnyDomainFactory;
                 getDomainExpressions: () => import("#package/domain").AnyExpressions;
+                getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
+                getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
                 getModelVersion: () => number;
                 getAliasMap: () => import("#package/domain").AnyAliasMap;
                 getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -1098,6 +1106,7 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
                 getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
                 getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
                 getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
+                getActionSystem: () => import("#package/domain").AnyActionSystem;
                 getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
                 getExpressionContext: () => import("#package/domain").AnyExpressionContext;
                 getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;
@@ -1164,6 +1173,8 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
                 getActiveConfigurationId: () => string;
                 getFactory: () => import("#package/domain").AnyDomainFactory;
                 getDomainExpressions: () => import("#package/domain").AnyExpressions;
+                getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
+                getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
                 getModelVersion: () => number;
                 getAliasMap: () => import("#package/domain").AnyAliasMap;
                 getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -1204,6 +1215,7 @@ declare const createApplicationRuntimeImpl: <EXTENSIONS extends readonly AnyAppl
                 getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
                 getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
                 getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
+                getActionSystem: () => import("#package/domain").AnyActionSystem;
                 getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
                 getExpressionContext: () => import("#package/domain").AnyExpressionContext;
                 getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;

package/dist/react-sdk/domain-context/common-hooks/use-domain-context.d.ts

@@ -60,6 +60,8 @@ export declare const useDomainContextSelectors: () => {
     getActiveConfigurationId: () => string;
     getFactory: () => import("#package/domain").AnyDomainFactory;
     getDomainExpressions: () => import("#package/domain").AnyExpressions;
+    getActionDefinitions: () => Readonly<Record<string, import("#package/domain").ActionDefinition>>;
+    getActionImplementations: () => Readonly<Record<string, import("#package/domain").AnyActionImplementation>>;
     getModelVersion: () => number;
     getAliasMap: () => import("#package/domain").AnyAliasMap;
     getAllowedRootEntityTypes: () => import("#package/domain").AnyAllowedRootEntityTypes;
@@ -100,6 +102,7 @@ export declare const useDomainContextSelectors: () => {
     getNavigationSystem: () => import("../../../domain/domain-context/navigation-system/navigation-system.js").AnyNavigationSystem;
     getUndoSystem: () => import("../../../domain/domain-context/undo-system.js").AnyUndoSystem;
     getRecipeCookerSystem: () => import("#package/domain").AnyRecipeCookerSystem;
+    getActionSystem: () => import("#package/domain").AnyActionSystem;
     getBlenderProjections: () => import("#package/domain").AnyBlenderProjections;
     getExpressionContext: () => import("#package/domain").AnyExpressionContext;
     getDomainSystems: () => import("#package/domain").AnyDomainContextSystems;

package/dist/ui-sdk/common/use-viewport-size.d.ts

@@ -13,8 +13,11 @@ export declare const getViewportSize: () => Size;
  * Returns the viewport size. This can also be used as a dependency in a
  * useEffect to trigger an update when the browser resizes.
  *
+ * @param subscriptionActive if `false`, the viewport is neither measured nor followed, and the size
+ * returned is the last one measured, if any (useful for optimization)
+ *
  * @see https://martijnhols.nl/gists/how-to-get-document-height-ios-safari-osk
  * @todo: investigate if this can use `viewport$`
  */
-export declare const useViewportSize: () => Size | undefined;
+export declare const useViewportSize: (subscriptionActive?: boolean) => Size | undefined;
 export {};

package/dist/ui-sdk/common/use-viewport-size.js

@@ -1 +1 @@
-import{useCallback as e,useEffect as i,useLayoutEffect as t,useState as n}from"react";let o="u">typeof window?t:()=>{};export const getViewportSize=()=>window.visualViewport?[window.visualViewport.width,window.visualViewport.height]:[window.innerWidth,window.innerHeight];export const useViewportSize=()=>{let[t,r]=n(),w=e(()=>{let e=getViewportSize();r(i=>i&&i[0]===e[0]&&i[1]===e[1]?i:e)},[]);return o(w,[w]),i(()=>{let e=()=>{w(),setTimeout(w,1e3)};return window.addEventListener("resize",e),window.addEventListener("orientationchange",e),window.visualViewport?.addEventListener("resize",e),()=>{window.removeEventListener("resize",e),window.removeEventListener("orientationchange",e),window.visualViewport?.removeEventListener("resize",e)}},[w]),t};
+import{useCallback as e,useEffect as i,useLayoutEffect as t,useState as n}from"react";let r="u">typeof window?t:()=>{};export const getViewportSize=()=>window.visualViewport?[window.visualViewport.width,window.visualViewport.height]:[window.innerWidth,window.innerHeight];export const useViewportSize=(t=!0)=>{let[o,w]=n(),d=e(()=>{let e=getViewportSize();w(i=>i&&i[0]===e[0]&&i[1]===e[1]?i:e)},[]);return r(()=>{t&&d()},[t,d]),i(()=>{if(!t)return;let e=()=>{d(),setTimeout(d,1e3)};return window.addEventListener("resize",e),window.addEventListener("orientationchange",e),window.visualViewport?.addEventListener("resize",e),()=>{window.removeEventListener("resize",e),window.removeEventListener("orientationchange",e),window.visualViewport?.removeEventListener("resize",e)}},[t,d]),o};

package/dist/ui-sdk/components/mobile-controls/index.d.ts

@@ -1 +1 @@
-export { MobileControls, type MobileControlsLayoutProps, type MobileControlsThemeableProps } from './MobileControls.js';
+export { MobileControls, type MobileControlsLayoutProps, type MobileControlsThemeableProps, type ViewOnlyModeProps, } from './MobileControls.js';

package/dist/ui-sdk/theme/types.d.ts

@@ -44,6 +44,7 @@ declare module '@mui/material/styles' {
         PhxChat: 'root';
         PhxChatFooter: 'root' | 'formLayout' | 'input';
         PhxChatMessage: 'base' | 'assistant' | 'user' | 'widget' | 'error' | 'helper';
+        PhxAssistantPanel: 'root' | 'header' | 'title' | 'closeButton' | 'thread' | 'greeting' | 'messages' | 'userMessage' | 'assistantMessage' | 'chips' | 'activity' | 'activityIcon' | 'chip' | 'status' | 'notice' | 'newReplyButton' | 'composer' | 'inputFrame' | 'input' | 'sendButton' | 'stopButton' | 'hint';
         PhxTopNavigation: 'root' | 'stepper' | 'step';
         PhxListSelector: 'root';
         PhxListSelectorItem: 'root' | 'radio' | 'title' | 'description' | 'formControlLabel';
@@ -109,6 +110,9 @@ declare module '@mui/material/styles' {
         PhxChatMessage?: {
             styleOverrides?: ComponentsOverrides<Theme>['PhxChatMessage'];
         };
+        PhxAssistantPanel?: {
+            styleOverrides?: ComponentsOverrides<Theme>['PhxAssistantPanel'];
+        };
         PhxPreviewLayout?: {
             styleOverrides?: ComponentsOverrides<Theme>['PhxPreviewLayout'];
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salsita-ai/sdk",
-  "version": "0.50.0-develop.da8d27f5d7",
+  "version": "0.50.0-develop.db8514eccf",
   "description": "TypeScript SDK and CLI for building, running, and deploying Phoenix configurator applications.",
   "keywords": [
     "salsita",
@@ -149,10 +149,6 @@
       "import": "./dist/extras/ai-preview/index.js",
       "types": "./dist/extras/ai-preview/index.d.ts"
     },
-    "./extras/assistant": {
-      "import": "./dist/extras/assistant/index.js",
-      "types": "./dist/extras/assistant/index.d.ts"
-    },
     "./common/utils": {
       "import": "./dist/common/utils.js",
       "types": "./dist/common/utils.d.ts"
@@ -225,7 +221,7 @@
     "@swc/core": "1.15.40",
     "@swc/wasm-web": "1.15.40",
     "@tanstack/ai": "0.64.0",
-    "@tanstack/ai-react": "0.29.4",
+    "@tanstack/ai-client": "0.36.1",
     "@trpc/client": "11.17.0",
     "@trpc/react-query": "11.17.0",
     "@trpc/server": "11.17.0",
@@ -275,6 +271,7 @@
     "react-json-tree": "0.20.0",
     "react-markdown": "9.0.1",
     "remark": "15.0.1",
+    "remark-gfm": "4.0.0",
     "rxjs": "7.8.2",
     "semver": "7.6.3",
     "spark-md5": "3.0.2",
@@ -295,8 +292,8 @@
     "yaml": "2.9.0",
     "yargs": "17.7.2",
     "zod": "3.25.76",
-    "@salsita-ai/common": "0.50.0-develop.da8d27f5d7",
-    "@salsita-ai/contracts": "0.50.0-develop.da8d27f5d7"
+    "@salsita-ai/common": "0.50.0-develop.db8514eccf",
+    "@salsita-ai/contracts": "0.50.0-develop.db8514eccf"
   },
   "devDependencies": {
     "@clerk/clerk-react": "5.61.8",

package/schema/domain-spec.json

@@ -18586,6 +18586,30 @@
           "required": ["kind"],
           "additionalProperties": false
         },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["assistantToolbarButton"]
+            },
+            "props": {
+              "type": "object",
+              "properties": {
+                "showTitle": {
+                  "type": "boolean"
+                },
+                "icon": {
+                  "type": "string"
+                }
+              },
+              "required": [],
+              "additionalProperties": false
+            }
+          },
+          "required": ["kind"],
+          "additionalProperties": false
+        },
         {
           "type": "object",
           "properties": {

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

@@ -1,2 +0,0 @@
-import{sdkGuidanceSections as e}from"./common/sdk-content.js";export const generateAgentsMd=()=>`${[e.projectIntro,e.buildCommands,e.doNotEdit,"Phoenix SDK guidance lives in the `phoenix`, `phoenix-cli`, `phoenix-create-configurator`, `phoenix-feedback` and `phoenix-review` skills under `.claude/skills/` and `.agents/skills/`. Phoenix rewrites them on every sync, removes anything else inside their folders and removes other `phoenix`-prefixed skill folders, so to customise a skill, copy it to a folder whose name does not start with `phoenix`."].join("\n\n")}
-`;

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

@@ -1,67 +0,0 @@
-export const sdkGuidanceSections={projectIntro:`## Phoenix Configurator Project
-
-Declarative 3D product configurator built with Phoenix SDK. Domain model defined in YAML, custom logic in TypeScript.`,buildCommands:"## Build Commands\n- `pnpm phoenix build` — Full production build\n- `pnpm phoenix dev` — Development mode with hot reload\n- `pnpm phoenix sync` — Sync generated files without full build",devLogs:"## Dev Logs\n- `pnpm phoenix dev` writes all logs to `.phoenix/phoenix-dev.log`\n- Contains: spec parse errors, build errors, browser runtime errors, file watcher events\n- After making changes, always check the log for errors: `tail -50 .phoenix/phoenix-dev.log` or `grep ERROR .phoenix/phoenix-dev.log`\n- Rotated automatically at 10MB (`.log.1`, `.log.2` are older rotations)",projectStructure:"## Project Structure\n- `spec/` — Domain YAML specs (entities, relations, expressions, invariants, components, application config)\n- `src/expressions/` — Computed/derived entity properties (`phx.domain.implementCustomExpressions()`)\n- `src/invariants/` — Business rule constraints (`phx.domain.implementCustomInvariants()`)\n- `src/transformers/` — Automatic state fixers (`phx.frontend.transformerBuilder`)\n- `src/components/` — ECS system components (`phx.domain.attachComponent.withEntity()`)\n- `src/elements/` — Page-level React components (`phx.frontend.createCustomPhoenixLayoutElement()`)\n- `src/handlers/` — Event & lifecycle handlers\n- `src/webhooks/` — Server-side webhook handlers (`phx.webhooks.*Builder`)\n- `src/migrations/` — Schema version migrations (v*.ts)\n- `src/locales/` — Locale catalogs (authored .po sources; compiled .ts, do not edit)\n- `src/admin/` — Admin interface (mirrors main src/ structure)\n- `src/_shared/` — Shared utilities (NOT auto-imported, requires explicit imports)\n- `.phoenix/` — Auto-generated files (DO NOT EDIT)\n- `public/` — Static assets (3D models, textures, images, HDRI maps, fonts)\n- `assets/` — Uploadable resources (PDF templates, email assets)",architecturePrinciples:"## Architecture Principles\n- YAML-first: 99% of configuration in spec/*.yaml, custom code is last resort\n- ECS pattern: entities (domain objects) + components (behavior/UI) + systems (SDK runtime)\n- Reactive state: immutable domain state flows through RxJS pipelines\n- Data binding: `$read` (read-only), `$write` (write-only), `$bind` (bidirectional) connect components to domain\n- memoEval: all component implementations must use memoEval for stable object references",keyPatterns:"## Key Patterns\n- Expressions = computed properties on entities (prefix: `$`), implemented per-entity in src/expressions/\n- Invariants = validation rules returning violations, static or dynamic\n- Transformers = auto-fixers maintaining consistency after state changes\n- Components defined in YAML with `$read`/`$bind` bindings, or custom in src/components/ using attachComponent builder\n- Webhooks = server-side finalization tasks (PDF, email, CSV, image rendering)\n- Filters = contextual component activation via navigationStates, viewStates, modes, selectedEntityIds",fileConventions:`## File Conventions
-- Components: PascalCase (.tsx)
-- Utilities: kebab-case (.ts)
-- Expressions: entity-name.ts
-- Migrations: v*.ts (sequential)
-- Specs: kebab-case.yaml
-- Underscore folders (_shared/, _utils/) are NOT auto-imported`,exportRules:`## Export Rules
-All 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.`,webhookMembership:"## Webhook Membership\n- User-authored components, admin components, and handlers are frontend-only by default.\n- A handler that registers `createMapPublishedRevisionDataHandler`, `createMapPublishedChunkedDataHandler`, `createDataRowValidatorHandler`, or `createSheetValidatorHandler` is included in the webhook automatically.\n- To include another component or handler in the webhook, put `'use webhook'` as its first statement (leading comments are allowed).\n- A webhook-included file and its runtime local-import closure must not import browser SDK entrypoints (`application`, `admin`, `configurator`, `editor`, `react`, `ui`) or style/font/image assets. Spec parsing reports the unsafe import and inclusion reason as a diagnostic.\n- Keep browser rendering in an unpinned file. Move shared server-safe logic into a separate module when both frontend and webhook code need it.",doNotEdit:"## Do Not Edit\n- `.phoenix/` directory — completely regenerated on each build\n- `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`, `.linguirc`, `.nvmrc`\n- `src/locales/` .ts files — compiled from .po files",sdkDocumentation:'## SDK Documentation\n\nAlways search SDK docs for relevant examples before implementing Phoenix features.\n\n### Commands\n- `pnpm phoenix docs` — Full documentation index with descriptions\n- `pnpm phoenix docs -s <term>` — Search all doc content and metadata (case-insensitive)\n- `pnpm phoenix docs --dir` — Print the absolute docs directory for grep or ripgrep\n- `pnpm phoenix docs -r <path>` — Read specific doc (raw text to stdout)\n- `pnpm phoenix docs -c <category>` — List docs in a category\n- `pnpm phoenix docs -l` — List all doc paths with titles\n\n### Key Docs\n- `docs/phoenix/getting-started.mdx` — Setup, prerequisites, first project\n- `docs/phoenix/quickstart.mdx` — End-to-end tutorial building a configurator\n- `docs/phoenix/domain-model.mdx` — Entities, attributes, relations, specs\n- `docs/phoenix/components.mdx` — ECS pattern, YAML components, custom components\n- `docs/phoenix/project-structure.mdx` — Files, folders, conventions\n- `docs/phoenix/best-practices.mdx` — YAML-first, code patterns, common pitfalls\n- `docs/phoenix/state-management.mdx` — Reactive state, RxJS pipelines, data flow\n- `docs/phoenix/expression-context.mdx` — Expression API, context object, helpers\n- `docs/phoenix/webhooks.mdx` — Server-side finalization workflows\n- `docs/phoenix/finalization.mdx` — Finalization system, PDF/email/CSV generation\n- `docs/phoenix/migrations.mdx` — Schema versioning, migration files\n\n### Agent Workflow\n1. Find relevant docs by content: `pnpm phoenix docs -s \'camera\'`\n2. Read matching doc: `pnpm phoenix docs -r docs/3d-scene/cameras/transitions.mdx`\n3. Search within a doc: `pnpm phoenix docs -r <path> | grep "example"`\n4. Search titles only as a fallback: `pnpm phoenix docs -l | grep "camera"`\n5. Search generated files directly when needed: `grep -rn "camera" "$(pnpm phoenix docs --dir)"`\n6. Browse a topic area: `pnpm phoenix docs -c "Layouts"`',assetInspection:"## 3D Asset Inspection\n\nRun `pnpm phoenix inspect:assets` to discover all glTF/GLB files in `public/` and get a summary table. Use `--file <path>` for detailed single-file inspection.\n\n**When to use:** before writing YAML/code that references objectName, materialsToOverride, morphTargetInfluences, or object positioning.\n\n**What it shows per node:**\n- Name, type (Mesh/Light/Camera/Empty), children\n- Transform: `pos=`, `rot=`, `scale=` (only non-default values shown)\n- Per-node morph targets: `morphs=Width,Height`\n- Bounding box: `bounds=WxHxD` (width x height x depth in meters)\n- Origin placement: `origin=center`, `bottom-center`, `top-center`, `bottom-corner`, etc. with numerical offset\n\n**Use cases:**\n- Find exact node names for `objectName` in scene entity components\n- Find material names for `materialsToOverride`\n- Find morph target names for `morphTargetInfluences`\n- Check model dimensions (bounds) for positioning, dimension indicators, or invariants\n- Check origin placement to understand how models anchor (center vs bottom-center)\n- Use `--json` for programmatic access to all data\n\n**Flags:** `--objects`, `--materials`, `--morphs`, `--animations`, `--json`",screenshotCli:"## Screenshot CLI\n\nCapture 3D canvas screenshots from a running dev server via `pnpm phoenix screenshot`.\n\n**Prerequisites:**\n1. `phoenix dev` must be running (starts the WebSocket server on port 3020)\n2. Configurator must be open in a browser (the browser does the actual rendering)\n\n**Options:**\n- `--output, -o` — Output file path (default: `./screenshot.png`)\n- `--width, -w` — Width in pixels (default: 1920)\n- `--height` — Height in pixels (default: 1080)\n- `--format, -f` — Image format: PNG or JPEG (default: PNG)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example workflow:**\n1. Start dev server: `pnpm phoenix dev`\n2. Open configurator in browser (or via Playwright MCP)\n3. Take screenshot: `pnpm phoenix screenshot -o ./render.png -w 2560 --height 1440`\n\n**Use cases:** visual regression testing, generating product images, debugging 3D renders",inspectState:"## Inspect: State\n\nGet the current editor runtime state as JSON via `pnpm phoenix inspect:state`.\n\n**Prerequisites:** same as screenshot (dev server running + browser open)\n\n**Options:**\n- `--output, -o` — Output file path (prints to stdout if omitted)\n- `--sections, -s` — Comma-separated: entities, navigation, validation (default: all)\n- `--pretty` — Pretty-print JSON (default: true)\n- `--port` — WebSocket server port (default: 3020)\n\n**Example:** `pnpm phoenix inspect:state -o ./state.json -s entities,navigation`\n\n**Lifecycle status:** Always included in response. Shows which systems are ready:\n- `domainLoaded` — domain data loaded\n- `domainContextReady` — domain context initialized (entities available)\n- `configuratorReady` — 3D configurator initialized\n- `sessionAuthenticated` — session service active\n- `editorMode` — editor mode enabled\n\n**Tips:** Use `--sections` to limit payload size. Pipe through `head`/`tail` for partial output (e.g., `pnpm phoenix inspect:state | head -50`).\n\n**Use cases:** AI agent context, debugging entity state, inspecting navigation/validation",inspectData:`## Inspect: Data
-
-Get the current editor context data as JSON via \`pnpm phoenix inspect:data\`.
-
-**Prerequisites:** same as screenshot (dev server running + browser open)
-
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
-
-**Returns:** publishedData, frontendData, backendData, sessionData, accessData, webComponentProperties
-
-**Example:** \`pnpm phoenix inspect:data -o ./data.json\`
-
-**Tips:** Pipe through \`head\`/\`tail\` for partial output (e.g., \`pnpm phoenix inspect:data | head -30\`).
-
-**Use cases:** AI agent context, debugging published/session/access data`,inspectScene:`## Inspect: Scene
-
-Get the current Three.js scene graph as JSON via \`pnpm phoenix inspect:scene\`.
-
-**Prerequisites:** same as screenshot (dev server running + browser open)
-
-**Options:**
-- \`--output, -o\` — Output file path (prints to stdout if omitted)
-- \`--pretty\` — Pretty-print JSON (default: true)
-- \`--port\` — WebSocket server port (default: 3020)
-
-**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.
-
-**Example:** \`pnpm phoenix inspect:scene -o ./scene.json\`
-
-**Tips:** Scene graphs can be large. Pipe through \`head\`/\`tail\` for partial output.
-
-**Use cases:** AI agent context, debugging 3D scene layout, inspecting materials and lighting`,playwrightMcpSetup:`## Playwright MCP Setup (for AI agents)
-
-To interact with the 3D configurator in a browser, Playwright MCP needs GPU-enabled flags for WebGL rendering. Add to \`~/.claude/.mcp.json\`:
-
-\`\`\`json
-{
-  "mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": [
-        "@playwright/mcp@latest",
-        "--headed",
-        "--launch-options",
-        "{\\"args\\":[\\"--use-gl=swiftshader\\",\\"--enable-webgl\\",\\"--ignore-gpu-blocklist\\"]}"
-      ]
-    }
-  }
-}
-\`\`\`
-
-Key flags:
-- \`--headed\` — visible browser (required for GPU rendering)
-- \`--use-gl=swiftshader\` — software GPU fallback for environments without a physical GPU
-- \`--enable-webgl\` + \`--ignore-gpu-blocklist\` — ensure WebGL is available`};

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

@@ -1 +0,0 @@
-import{renderAgentSkill as n}from"./common/agent-skill.js";import{sdkGuidanceSections as e}from"./common/sdk-content.js";export const generatePhoenixCliSkill=()=>n({name:"phoenix-cli",description:"Phoenix CLI tooling for building and inspecting this configurator, covering build, dev and sync commands, dev logs, glTF asset inspection, screenshots, runtime state, data and scene inspection, and Playwright MCP setup. Use when building, debugging build or runtime errors, checking 3D assets, or inspecting the running configurator.",sections:[e.buildCommands,e.devLogs,e.assetInspection,e.screenshotCli,e.inspectState,e.inspectData,e.inspectScene,e.playwrightMcpSetup]});

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

@@ -1,31 +0,0 @@
-import{renderAgentSkill as e}from"./common/agent-skill.js";let t=`## When to Raise Feedback
-Draft feedback for the Phoenix team when one of these happens while you work in this project:
-- **Bug** — the SDK, the \`phoenix\` CLI or generated code crashes, produces wrong output or behaves differently from its documentation, and the cause is not in this project's own code.
-- **Misleading guidance** — a doc page, a Phoenix skill or an error message sent you the wrong way, or did not say what you needed.
-- **Missing feature** — something the SDK does not support forced a workaround, or a routine task took far more steps than it should.
-
-Do not draft feedback for problems in this project's own specs or code, for a suspicion you have not checked, or twice for the same problem. Write one draft per distinct problem.`,o=`## Ask Before You Send
-Never send feedback on your own. Show the user a draft and send it only after they approve it.
-
-When to ask is your judgement:
-- **Right away** — the problem is crucial: it blocks the task or forces a workaround the user should know about now. Interrupt the work, show the draft, and continue once the user has answered.
-- **At the end of the task** — everything else. Collect the details while you work and show all drafts together in your final message.
-- **When the user asks** you to send feedback — draft it and show it before sending.
-
-The draft is exactly what would be sent: the type, the message, the project if you name one with \`--projectSlug\`, and the contact if the user gave one. Send it unchanged after a yes; if the user edits it, send their version. If they decline, drop it and do not raise that problem again.`,a=`## Ask for a Rating After a Deploy
-When \`phoenix deploy\` reports that the configurator is live, tell the user the live URL first, then ask them to rate building with Phoenix so far:
-- Ask for a score from 0 to 10, where 10 is the best, and one optional sentence on what would have made it better. Say in the same question that the answer is sent to the Phoenix team as feedback.
-- Ask once per conversation, after the first deploy that goes live. Do not ask again after later deploys, and do not ask after a deploy that failed.
-- Never choose or guess the score yourself. If the user skips the question or declines, send nothing and do not ask again.
-
-A rating is feedback like any other, so the rules of this skill apply. Write the comment from the user's words, and take out anything the last section forbids: replace this project's product, customer and people names with generic words. Then show the user the three lines below exactly as they would be sent and send them only after a yes; if they edit the text, send their version. Use \`none\` when they gave no comment:
-\`\`\`bash
-pnpm phoenix feedback 'Rating: <score>/10
-Comment: <their comment, or none>
-Stage: after a deploy' --type other --agent '<your agent name>'
-\`\`\`
-Keep the three labels and their order, so the ratings can be read out of the feedback list. A rating is not a bug report: when the comment names a concrete problem, offer to draft it as its own feedback as the sections above describe.`,n=`## What Never Goes Into Feedback
-The message leaves this project and is read by the Phoenix team. Never include:
-- secrets: API tokens, keys, passwords or \`.env\` values;
-- customer or end-user data, or personal data such as names and email addresses, other than a contact the user asked you to add;
-- this project's source code, specs or business rules. Describe the shape of the problem in words, or reduce it to a generic example that contains nothing of the project.`;export const generatePhoenixFeedbackSkill=()=>e({name:"phoenix-feedback",description:"Drafting feedback about the Phoenix SDK, CLI, documentation or Studio for the Phoenix team and sending it with the phoenix feedback command once the user approves the draft, covering when to raise it, how to write it, the rating asked for after a deploy and what must never be included. Use when the SDK or CLI misbehaves, a doc or skill misled you, a missing feature forced a workaround, the user asks to send feedback, or phoenix deploy has just gone live and the user should be asked to rate the experience from 0 to 10.",sections:[t,o,"## How to Send It\n```bash\npnpm phoenix feedback '<message>' --type bug --agent '<your agent name>'\n```\n- Put the message in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside the message as `'\\''`; in PowerShell, double it instead.\n- `--type` is `bug`, `idea` or `other` (default `other`). Use `idea` for a missing feature or an improvement.\n- `--agent` names you, the coding agent, so the team can tell agent feedback from a person's.\n- `--contact '<email>'` only when the user wants a reply and gave you the contact to use.\n- The workspace, user, SDK version and the spec's `project` are attached automatically. `--projectSlug <slug>` names another project of the workspace.\n- A message holds at most 5000 characters.\n\nWrite the message for someone who cannot see this project: what you ran or called, what you expected, what happened instead with the error text, and the workaround if you found one. Before quoting an error, replace this project's names, file paths and values in it with generic placeholders, as the list below requires.\n\nThe command needs `phoenix login`. If it answers that you are not signed in, tell the user once and continue; do not sign in yourself, because the sign-in is approved in a browser.\n\nAfter sending, confirm it to the user in one line.",a,n]});

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

@@ -1 +0,0 @@
-import{renderAgentSkill as e}from"./common/agent-skill.js";import{sdkGuidanceSections as t}from"./common/sdk-content.js";export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixSkill=({checkLatestCanary:n})=>e({name:"phoenix",description:`Phoenix SDK project conventions, covering project structure, architecture principles, key patterns, file and export rules, webhook membership, showing the user the dev preview and the build of a deploy, and how to search the SDK documentation${n?", and the internal-beta check for the latest canary SDK build":""}. Use before writing or changing specs or source code in this Phoenix configurator project.`,sections:[...n?["## Stay on the Latest Canary\nDuring the internal beta this project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before you change anything, compare the installed version with the newest canary:\n```bash\npnpm list @salsita-ai/sdk --depth 0\nnpm view @salsita-ai/sdk@canary version\n```\nWhen they differ, tell the user which version you are moving to, then update the project and regenerate its files:\n```bash\npnpm add @salsita-ai/sdk@canary\npnpm phoenix sync\n```\n`sync` rewrites the Phoenix skills, so read the ones you use again after it. When the user runs a globally installed `phoenix`, update that too with `npm install -g @salsita-ai/sdk@canary`. If the project no longer builds after the update, stop and tell the user; the `phoenix-feedback` skill covers reporting it."]:[],t.projectStructure,t.architecturePrinciples,t.keyPatterns,t.fileConventions,t.exportRules,t.webhookMembership,t.doNotEdit,"## Show the Preview While You Work\nThe user should see the configurator change as you build it. Before your first change in a conversation, make sure `pnpm phoenix dev` is running (start it in the background when it is not) and open the address it prints as `Preview: <url>` (also written to `.phoenix/phoenix-dev.log`) in the user's browser: `open '<url>'` on macOS, `xdg-open '<url>'` on Linux, `Start-Process '<url>'` in PowerShell, `start \"\" \"<url>\"` in cmd. Keep the quotes, the shell would otherwise read a `?` in the address as a pattern. The log keeps the lines of earlier runs, so when you have just started dev, wait for the `Preview:` line written after your start and use the last one. Open it once; the preview reloads on every change, so tell the user to keep that tab open instead of opening it again.","## Show the Build After a Deploy\n`pnpm phoenix deploy` starts a build on the server and waits for it to go live. Right after `Build <id> started` it prints `Follow the build in Studio: <url>`. Run the deploy so that you can read its output while it runs, and open that link in the user's browser, quoted as above, as soon as it appears, so they can follow the build they just triggered. When the line is missing, the sign-in is older than the link: tell the user the build is listed under Deployments in Studio, and that `pnpm phoenix login <workspace>` brings the link back.","## Code Review\nUse the `phoenix-review` skill to review code changes before committing.",t.sdkDocumentation]});

package/dist/configurator/assistant/browser-details.js

@@ -1 +0,0 @@
-import{browserDetailsTool as e}from"@salsita-ai/contracts/assistant";let t=e=>{let t=[];for(let i=0;i<e.length;i+=64)t.push(e.slice(i,i+64));return t};export const browserDetailsClientTool=e.client(()=>{let e=(()=>{let e=[`User agent: ${navigator.userAgent}`,`Viewport: ${window.innerWidth} x ${window.innerHeight} px`,`Screen: ${window.screen.width} x ${window.screen.height} px`,`Device pixel ratio: ${window.devicePixelRatio}`,`Language: ${navigator.language}`,`Time zone: ${Intl.DateTimeFormat().resolvedOptions().timeZone}`].flatMap(t),i=document.createElement("canvas");i.width=720,i.height=48+26*e.length;let n=i.getContext("2d");if(!n)throw Error("The browser details capture failed because the canvas has no 2D context. Retry in another browser.");return n.fillStyle="#ffffff",n.fillRect(0,0,i.width,i.height),n.fillStyle="#111111",n.font="16px monospace",n.textBaseline="top",e.forEach((e,t)=>n.fillText(e,24,24+26*t)),i.toDataURL("image/png")})();return[{type:"image",source:{type:"data",value:e.slice(e.indexOf(",")+1),mimeType:"image/png"}}]});

package/dist/configurator/assistant/graphql-tools.js

@@ -1 +0,0 @@
-import{AssistantGraphQLToolInput as e,applyTool as t,queryTool as o}from"@salsita-ai/contracts/assistant";let a=e=>({results:[],committed:!1,message:e}),s=e=>JSON.parse(JSON.stringify(e)),i=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:a(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const queryClientTool=o.client(async(e,{context:t})=>{let o=i(e);return o.ok?t.storeSystem.isInitialized?s({results:(await t.graphQLSystem.prepare(t.storeSystem.stateSlices.committed.value.state,o.operations)).map(({result:e})=>e),committed:!1}):a("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading."):o.refusal});export const applyClientTool=t.client(async(e,{context:t})=>{if("owner"!==t.getActiveMode())return a("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it.");let o=i(e);return o.ok?s(await t.graphQLSystem.execute(o.operations)):o.refusal});

package/dist/configurator/assistant/index.d.ts

@@ -1 +0,0 @@
-export { useAssistantChat, type AssistantChatState } from './use-assistant-chat.js';

package/dist/configurator/assistant/index.js

@@ -1 +0,0 @@
-export{useAssistantChat}from"./use-assistant-chat.js";

package/dist/configurator/assistant/use-assistant-chat.d.ts

@@ -1,20 +0,0 @@
-import { type UIMessage } from '@tanstack/ai-react';
-/** Experimental assistant chat state and actions of the current configuration. */
-export interface AssistantChatState {
-    /** The thread as painted: hydrated from the server, then streamed. */
-    readonly messages: ReadonlyArray<UIMessage>;
-    /** True while a reply streams or a browser tool runs. */
-    readonly isLoading: boolean;
-    readonly error: Error | undefined;
-    /** Sends a user message stamped with its send time. */
-    readonly send: (content: string) => Promise<void>;
-    /** Stops the current reply in the browser and on the server. */
-    readonly stop: () => Promise<void>;
-}
-/**
- * Experimental: the conversational assistant of the current configuration. The server owns the
- * thread — the chat hydrates from it on mount and rejoins a reply still streaming — so the hook
- * keeps nothing in browser storage. Each message carries its send time for the model. The model's
- * `query` and `apply` calls run here, in the browser, against the configurator this hook is rendered in.
- */
-export declare const useAssistantChat: () => AssistantChatState;

package/dist/configurator/assistant/use-assistant-chat.js

@@ -1 +0,0 @@
-import{fetchServerSentEvents as t,useChat as e}from"@tanstack/ai-react";import{useCallback as a,useMemo as r}from"react";import{useAuthorizedClient as s,useConfigurationId as n,useDomain as o}from"#package/react-sdk";import{useConfigurator as i}from"../application-runtime/index.js";import{browserDetailsClientTool as c}from"./browser-details.js";import{applyClientTool as p,queryClientTool as l}from"./graphql-tools.js";let m=[c,l,p];export const useAssistantChat=()=>{let c=n(),p=s(),l=r(()=>p.getAssistantChatConnection(c),[p,c]),d=r(()=>{let e=async()=>({headers:await l.headers()}),a=t(l.url,e),r=t(`${l.url}/runs`,e);return{...a,joinRun:r.joinRun}},[l]),{graphQLSystem:u}=i(),{storeSystem:h,domainContextSelectors:f}=o(),{getActiveMode:w}=f,{messages:g,isLoading:j,error:y,sendMessage:C,stop:S,runId:$}=e({threadId:`assistant:${c}`,connection:d,persistence:!0,history:{pageSize:50},tools:m,context:r(()=>({graphQLSystem:u,storeSystem:h,getActiveMode:w}),[u,h,w])});return{messages:g,isLoading:j,error:y,send:a(async t=>{let e={sentAt:new Date().toISOString()};await C({content:t,metadata:e})},[C]),stop:a(async()=>{S(),null!=$&&await fetch(`${l.url}/runs/${encodeURIComponent($)}/cancel`,{method:"POST",headers:await l.headers()})},[l,$,S])}};

package/dist/extras/assistant/AssistantChat.d.ts

@@ -1,6 +0,0 @@
-/**
- * Experimental, unstyled assistant chat for the current configuration: streamed replies, reasoning
- * summaries, tool calls with their payloads, a pending indicator and a stop button. It renders
- * nothing, and contacts no server, when the application spec has no `assistant` section.
- */
-export declare const AssistantChat: () => import("react/jsx-runtime").JSX.Element | null;

package/dist/extras/assistant/AssistantChat.js

@@ -1 +0,0 @@
-import{jsx as e,jsxs as t}from"react/jsx-runtime";import{Alert as r,Box as a,Button as i,LinearProgress as n,Stack as o,TextField as l,Typography as s}from"@mui/material";import{useState as c}from"react";import{useAssistantChat as p}from"#package/configurator";import{useSpecAssistant as m}from"#package/react-sdk";let d=({part:t})=>{switch(t.type){case"text":return e(s,{sx:{whiteSpace:"pre-wrap"},children:t.content});case"thinking":return e(s,{variant:"body2",color:"text.secondary",sx:{fontStyle:"italic",whiteSpace:"pre-wrap"},children:t.content});case"tool-call":return e(s,{variant:"caption",component:"pre",sx:{m:0,whiteSpace:"pre-wrap"},children:`${t.name}(${JSON.stringify(t.input??t.arguments)}) \xb7 ${t.state}`});case"tool-result":{let r=(e=>{if("string"!=typeof e){for(let t of e)if("image"===t.type&&"data"===t.source.type)return`data:${t.source.mimeType};base64,${t.source.value}`}})(t.content);return r?e(a,{component:"img",src:r,alt:"Tool result",sx:{maxWidth:"100%",border:1}}):e(s,{variant:"caption",children:`Tool result \xb7 ${t.state}`})}default:return null}},u=()=>{let{messages:m,send:u,stop:h,isLoading:f,error:x}=p(),[g,v]=c("");return t(o,{spacing:1.5,sx:{p:2},children:[m.map(r=>t(a,{component:"div",sx:{alignSelf:"user"===r.role?"flex-end":"flex-start",maxWidth:"85%"},children:[e(s,{variant:"overline",children:r.role}),r.parts.map((t,r)=>e(d,{part:t},r))]},r.id)),f&&e(n,{"aria-label":"Assistant is responding"}),x&&e(r,{severity:"warning",children:x.message}),e("form",{onSubmit:e=>{e.preventDefault();let t=g.trim();t&&(v(""),u(t))},children:t(o,{direction:"row",spacing:1,children:[e(l,{size:"small",fullWidth:!0,placeholder:"Ask the assistant…",value:g,onChange:e=>v(e.target.value)}),f?e(i,{onClick:()=>void h(),children:"Stop"}):e(i,{type:"submit",variant:"contained",disabled:!g.trim(),children:"Send"})]})})]})};export const AssistantChat=()=>m()?e(u,{}):null;

package/dist/extras/assistant/index.d.ts

@@ -1 +0,0 @@
-export { AssistantChat } from './AssistantChat.js';

package/dist/extras/assistant/index.js

@@ -1 +0,0 @@
-export{AssistantChat}from"./AssistantChat.js";