@salsita-ai/sdk 0.50.0-develop.9440e83ee3 → 0.50.0-develop.95b896fd8c

package/dist/domain/spec/model/names/index.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/model/names/instance-name.d.ts

@@ -0,0 +1,7 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Branded component instance name.
+ * User-declared names must start with a letter (e.g. "default", "body", "main").
+ * SDK-derived names may include `$` prefix and `.` separators (e.g. "$top", "Table.$top").
+ */
+export type InstanceName = Branded<'InstanceName', string>;

package/dist/domain/spec/model/names/instance-name.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/model/names/invariant-name.d.ts

@@ -0,0 +1,3 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/** A camelCase identifier for an invariant implementation declared in YAML. */
+export type InvariantName = Branded<'InvariantName', string>;

package/dist/domain/spec/model/names/invariant-name.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/model/names/shape-property-name.d.ts

@@ -0,0 +1,11 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Branded shape property name — the key under which an entity shape (or
+ * alias shape) declares a field, and the key under which `defaults:` attaches
+ * initial values. Must match /^[a-z]\w*$/: start with a lowercase letter,
+ * then word characters (letters, digits, underscore).
+ *
+ * Examples: `height`, `positionX`, `hoodId`. Rejected: `Height`, `$height`,
+ * `3D`, `height-px`.
+ */
+export type ShapePropertyName = Branded<'ShapePropertyName', string>;

package/dist/domain/spec/model/names/shape-property-name.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/model/names/violation-type-name.d.ts

@@ -0,0 +1,3 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/** A stable violation discriminator returned by an invariant. */
+export type ViolationTypeName = Branded<'ViolationTypeName', string>;

package/dist/domain/spec/model/names/violation-type-name.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/model/presets.d.ts

@@ -0,0 +1,30 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * A single entity within a preset — id, type, and shape properties.
+ * Properties are validated against the entity's schema from ConfigurationSchema.
+ */
+export type PresetEntity = Branded<'PresetEntity', {
+    readonly id: string;
+    readonly type: string;
+    readonly properties: Readonly<Record<string, unknown>>;
+}>;
+/**
+ * A single parsed preset — the root entity type, initial entities, and optional metadata.
+ * Represents one initial configuration state for a configurator deployment. `application-spec`
+ * exports it as `Preset`.
+ */
+export type SpecPreset = Branded<'Preset', {
+    readonly rootEntityType: string;
+    readonly initialDomainEntities: readonly PresetEntity[];
+    readonly name?: string;
+    readonly description?: string;
+    readonly img?: string;
+    readonly imgAlt?: string;
+    readonly detailTitle?: string;
+    readonly detailDescription?: string;
+    readonly tags?: readonly string[];
+}>;
+/** All parsed presets for a parsed configurator or admin model. */
+export type Presets = Branded<'Presets', {
+    readonly presets: readonly SpecPreset[];
+}>;

package/dist/domain/spec/model/presets.js

@@ -0,0 +1 @@
+export{};

package/dist/editor/domain-editors/DomainSpecContext.js

@@ -1 +1 @@
-import{jsx as e}from"react/jsx-runtime";import r from"lodash-es/debounce.js";import t from"promise-queue";import{createContext as o,useCallback as n,useContext as i,useEffect as s,useMemo as a,useRef as c,useState as m}from"react";import{match as l}from"ts-pattern";import{ApplicationRuntime as p,BinaryFile as u,RawProjectFiles as d,RuntimeReferenceStore as g,TextFile as f,buildPhoenixDefinitions as S,isConfiguratorModelSchemaCompatible as v,isTextFile as y,parseApplicationFiles as E}from"#package/application-spec";import{findActionImplementationConflicts as h,getAllPhxDefinitions as x}from"#package/domain";import{useApplicationRuntime as A,useMountGuard as C}from"#package/react-sdk";import{useEditorConnection as D}from"../services/EditorConnectionContext.js";import{trpc as I}from"../services/trpc.js";import{applyRuntimeReset as N,applySpecUpdate as w,prepareRuntimeRefresh as P,prepareRuntimeReset as _}from"./apply-spec-update.js";import{useDiagnostics as R}from"./use-diagnostics.js";import{useImplementationFiles as j}from"./use-implementation-files.js";import{getWasmSwcParsers as L}from"./wasm-swc-parsers.js";let k=o(null),T={debug:e=>console.debug(e)},M=e=>e instanceof Error?e.message:String(e);export const DomainSpecProvider=o=>{let{children:i,domainSpec:O,initialRawProjectFiles:b}=o,[$,F]=m(a(()=>O?[{fileName:"domain.yaml",content:O}]:b?b.files.filter(y).map(e=>({fileName:e.name,content:e.content})):[],[O,b])),[z,H]=m(null),q=a(()=>new g,[]),G=a(()=>S(x()),[]),U=c(null),Q=A(),{getImplementationFiles:B}=j(),{diagnostics:V,unreadDiagnosticCount:X,setDiagnostics:Y,pushDiagnostic:Z,clearDiagnostics:J,markDiagnosticsRead:K}=R(),W=a(()=>new t(1,1/0),[]),ee=c(0),er=c(null),{mutateAsync:et}=I.requestSpecFiles.useMutation(),{mutateAsync:eo}=I.save.useMutation(),en=C(),{localMode:ei,connectionStatus:es}=D(),{data:ea}=I.getEditorConfig.useQuery(void 0,{enabled:!ei&&"connected"===es}),ec=ei||ea?.specSync===!0,em=$.length>0?$:void 0,el=a(()=>$.map(e=>e.fileName),[$]),ep=a(()=>r(async e=>{if(!ei&&"connected"===es&&0!==e.length)try{await eo(e.map(e=>({fileName:e.fileName,content:e.content})))}catch(e){console.error("[DomainSpecContext] Failed to save files to disk:",e)}},1e3),[ei,es,eo]);s(()=>()=>{ep.cancel()},[ep]);let eu=n(()=>{H(null)},[]),ed=n(async(e,r)=>{F(t=>{let o=t.find(r=>r.fileName===e)?t.map(t=>t.fileName===e?{...t,content:r}:t):[...t,{fileName:e,content:r}];return ep(o),o})},[ep]),eg=n(async(e,r)=>{let t,o,n=()=>en()&&ee.current===r;if(!n())return;let i=d(e.rawProjectFiles.files.map(e=>l(e).with({kind:"text"},e=>f(e.name,e.content)).with({kind:"binary"},e=>u(e.name)).exhaustive()));F(i.files.filter(y).map(e=>({fileName:e.name,content:e.content})));try{t=await L()}catch(e){if(!n())return;Y([{code:"MODULE_ANALYZER_UNAVAILABLE",message:`The editor's module analyzer failed to load: ${e instanceof Error?e.message:String(e)}`,severity:"error",source:"spec",path:[]}]);return}if(!n())return;let s=E({rawProjectFiles:i,phxDefinitions:G},{analyzer:t.analyzer,evalExpressionParser:t.evalExpressionParser,referenceStore:q,logger:T});if(console.info(`[DomainSpecContext] Spec parsed: ${s.ok?"ok":"error"}, ${s.diagnostics.length} diagnostics`),!s.ok)return void Y([...s.errors,...s.diagnostics].map(e=>({...e,source:"spec"})));J();let{applicationSpec:a}=s.value,c=await B({application:s.value,projectRoot:e.projectRoot});if(!n())return;if(c.errors.length>0)return void Y(c.errors.map(e=>({code:e.code,message:e.message,severity:"error",source:"reload",path:[]})));let m=h([...a.configurator.actions.values()].map(e=>String(e.name)),c.actionImplementations??Q.getState().spec.configurator.actionImplementations);if(m.extra.length>0&&console.error(`[DomainSpecContext] Action implementations without a declaration: ${m.extra.join(", ")}`),m.missing.length>0){let e=`Missing action implementations: ${m.missing.join(", ")}. Add each to a default export of phx.domain.implementActions({ ... }) in src/actions/.`;console.error(`[DomainSpecContext] ${e}`),Z({code:"MISSING_ACTION_IMPLEMENTATIONS",message:e,severity:"error",source:"runtime"});return}let g=p(a,q,c.implementations,c.importedTransformers,c.invariantImplementations,c.adminImplementations);if(!g.ok){let e=`Missing expression implementations: ${g.missingExpressions.map(e=>`${e.entityType}.${e.exprName}`).join(", ")}`;console.error(`[DomainSpecContext] ${e}`),Z({code:"MISSING_EXPRESSION_IMPLEMENTATIONS",message:e,severity:"error",source:"runtime"});return}let{runtime:S}=g,x=null===U.current||v(U.current.configurator,a.configurator),A=Q.selectors.environment.getPersistenceConfig();if(!x){let e;if("server"===A.type)return void Z({code:"HOT_RELOAD_MODEL_CHANGE_REQUIRES_RESTART",message:"Domain model changes require an application restart and were not applied.",severity:"error",source:"runtime"});if(!Q.selectors.domainContext.configurator.getInitializationState().isCurrent)return void Q.selectors.domainServices.getLogger().debug("[DomainSpecContext] Skipping the model reset because no configurator session is initialized; the change applies once a session loads under the new spec.");try{e=_({runtime:S,implementationFiles:c,previousSpec:Q.getState().spec})}catch(e){Z({code:"HOT_RELOAD_PREPARE_FAILED",message:M(e),severity:"error",source:"runtime"});return}for(let r of(Q.selectors.domainServices.getLogger().debug("[DomainSpecContext] Reseeding the reset session directly from the spec preset; onPresetLoadedHandler and ProductSelected analytics are intentionally skipped."),N(Q,e,Q.selectors.domainApplicationContext.configurator.getConfigurationPersistSystem().revisionId$.value),U.current=a,e.implementationErrors))Z({code:r.code,message:r.message,severity:"error",source:"runtime"});return}try{o=P({runtime:S,implementationFiles:c,previousSpec:Q.getState().spec})}catch(e){Z({code:"HOT_RELOAD_PREPARE_FAILED",message:M(e),severity:"error",source:"runtime"});return}if(n())for(let e of(w(Q,o),U.current=a,o.implementationErrors))Z({code:e.code,message:e.message,severity:"error",source:"runtime"})},[Q,B,en,G,Z,q,Y,J]),ef=c(null),eS=n(e=>{let r=ee.current+1;ee.current=r,er.current={data:e,generation:r},W.add(async()=>{let e=er.current;e&&e.data!==ef.current&&(er.current=null,ef.current=e.data,await eg(e.data,e.generation))})},[eg,W]);I.onSpecChange.useSubscription(void 0,{enabled:!ei&&ec,onData:eS}),s(()=>{!ei&&ec&&et().catch(()=>{console.warn("[DomainSpecContext] Failed to request spec files")})},[et,ei,ec]);let ev=a(()=>({files:em,fileNames:el,updateFile:ed,parsing:!1,parseError:z,clearParseError:eu,diagnostics:V,clearDiagnostics:J,unreadDiagnosticCount:X,markDiagnosticsRead:K}),[em,el,ed,z,eu,V,J,X,K]);return e(k.Provider,{value:ev,children:i})};export const useDomainSpecContext=()=>{let e=i(k);if(null===e)throw Error("useDomainSpecContext must be used within DomainSpecProvider");return e};
+import{jsx as e}from"react/jsx-runtime";import r from"lodash-es/debounce.js";import t from"promise-queue";import{createContext as o,useCallback as n,useContext as i,useEffect as s,useMemo as a,useRef as c,useState as l}from"react";import{match as m}from"ts-pattern";import{ApplicationRuntime as u,BinaryFile as p,RawProjectFiles as d,RuntimeReferenceStore as g,TextFile as f,buildPhoenixDefinitions as v,isConfiguratorModelSchemaCompatible as S,isTextFile as h,parseApplicationFiles as y}from"#package/application-spec";import{createImplementationErrorCollector as E,findActionImplementationConflicts as x,getAllPhxDefinitions as A}from"#package/domain";import{useApplicationRuntime as C,useMountGuard as D}from"#package/react-sdk";import{useEditorConnection as w}from"../services/EditorConnectionContext.js";import{trpc as N}from"../services/trpc.js";import{applyRuntimeReset as P,applySpecUpdate as R,prepareRuntimeRefresh as _,prepareRuntimeReset as j}from"./apply-spec-update.js";import{useDiagnostics as I}from"./use-diagnostics.js";import{useImplementationFiles as L}from"./use-implementation-files.js";import{getWasmSwcParsers as k}from"./wasm-swc-parsers.js";let b=o(null),M={debug:e=>console.debug(e)},O=e=>e instanceof Error?e.message:String(e);export const DomainSpecProvider=o=>{let{children:i,domainSpec:T,initialRawProjectFiles:$}=o,[F,z]=l(a(()=>T?[{fileName:"domain.yaml",content:T}]:$?$.files.filter(h).map(e=>({fileName:e.name,content:e.content})):[],[T,$])),[H,q]=l(null),U=a(()=>new g,[]),G=a(()=>v(A()),[]),Q=c(null),B=C(),{getImplementationFiles:V}=L(),{diagnostics:Y,unreadDiagnosticCount:Z,setDiagnostics:J,pushDiagnostic:K,clearDiagnostics:W,markDiagnosticsRead:X}=I(),ee=a(()=>new t(1,1/0),[]),er=c(0),et=c(null),{mutateAsync:eo}=N.requestSpecFiles.useMutation(),{mutateAsync:en}=N.save.useMutation(),ei=D(),{localMode:es,connectionStatus:ea}=w(),{data:ec}=N.getEditorConfig.useQuery(void 0,{enabled:!es&&"connected"===ea}),el=es||ec?.specSync===!0,em=F.length>0?F:void 0,eu=a(()=>F.map(e=>e.fileName),[F]),ep=a(()=>r(async e=>{if(!es&&"connected"===ea&&0!==e.length)try{await en(e.map(e=>({fileName:e.fileName,content:e.content})))}catch(e){console.error("[DomainSpecContext] Failed to save files to disk:",e)}},1e3),[es,ea,en]);s(()=>()=>{ep.cancel()},[ep]);let ed=n(()=>{q(null)},[]),eg=n(async(e,r)=>{z(t=>{let o=t.find(r=>r.fileName===e)?t.map(t=>t.fileName===e?{...t,content:r}:t):[...t,{fileName:e,content:r}];return ep(o),o})},[ep]),ef=n(async(e,r)=>{let t,o,n=()=>ei()&&er.current===r;if(!n())return;let i=d(e.rawProjectFiles.files.map(e=>m(e).with({kind:"text"},e=>f(e.name,e.content)).with({kind:"binary"},e=>p(e.name)).exhaustive()));z(i.files.filter(h).map(e=>({fileName:e.name,content:e.content})));try{t=await k()}catch(e){if(!n())return;J([{code:"MODULE_ANALYZER_UNAVAILABLE",message:`The editor's module analyzer failed to load: ${e instanceof Error?e.message:String(e)}`,severity:"error",source:"spec",path:[]}]);return}if(!n())return;let s=y({rawProjectFiles:i,phxDefinitions:G},{analyzer:t.analyzer,evalExpressionParser:t.evalExpressionParser,referenceStore:U,logger:M});if(console.info(`[DomainSpecContext] Spec parsed: ${s.ok?"ok":"error"}, ${s.diagnostics.length} diagnostics`),!s.ok)return void J([...s.errors,...s.diagnostics].map(e=>({...e,source:"spec"})));W();let{applicationSpec:a}=s.value,c=await V({application:s.value,projectRoot:e.projectRoot});if(!n())return;if(c.errors.length>0)return void J(c.errors.map(e=>({code:e.code,message:e.message,severity:"error",source:"reload",path:[]})));let l=x([...a.configurator.actions.values()].map(e=>String(e.name)),c.actionImplementations??B.getState().spec.configurator.actionImplementations);if(l.extra.length>0&&console.error(`[DomainSpecContext] Action implementations without a declaration: ${l.extra.join(", ")}`),l.missing.length>0){let e=`Missing action implementations: ${l.missing.join(", ")}. Add each to a default export of phx.domain.implementActions({ ... }) in src/actions/.`;console.error(`[DomainSpecContext] ${e}`),K({code:"MISSING_ACTION_IMPLEMENTATIONS",message:e,severity:"error",source:"runtime"});return}let g=E(),v=u(a,U,c.expressionModules,c.importedTransformers,c.invariantImplementations,c.adminExpressionModules,void 0,void 0,void 0,g);for(let e of g.recorded())console.error(`[DomainSpecContext] ${e.message}`),K({code:e.code,message:e.message,severity:"error",source:"runtime"});if(!v.ok)return void U.clear();let{runtime:A}=v,C=null===Q.current||S(Q.current.configurator,a.configurator),D=B.selectors.environment.getPersistenceConfig();if(!C){let e;if("server"===D.type)return void K({code:"HOT_RELOAD_MODEL_CHANGE_REQUIRES_RESTART",message:"Domain model changes require an application restart and were not applied.",severity:"error",source:"runtime"});if(!B.selectors.domainContext.configurator.getInitializationState().isCurrent)return void B.selectors.domainServices.getLogger().debug("[DomainSpecContext] Skipping the model reset because no configurator session is initialized; the change applies once a session loads under the new spec.");try{e=j({runtime:A,implementationFiles:c,previousSpec:B.getState().spec})}catch(e){K({code:"HOT_RELOAD_PREPARE_FAILED",message:O(e),severity:"error",source:"runtime"});return}for(let r of(B.selectors.domainServices.getLogger().debug("[DomainSpecContext] Reseeding the reset session directly from the spec preset; onPresetLoadedHandler and ProductSelected analytics are intentionally skipped."),P(B,e,B.selectors.domainApplicationContext.configurator.getConfigurationPersistSystem().revisionId$.value),Q.current=a,e.implementationErrors))K({code:r.code,message:r.message,severity:"error",source:"runtime"});return}try{o=_({runtime:A,implementationFiles:c,previousSpec:B.getState().spec})}catch(e){K({code:"HOT_RELOAD_PREPARE_FAILED",message:O(e),severity:"error",source:"runtime"});return}if(n())for(let e of(R(B,o),Q.current=a,o.implementationErrors))K({code:e.code,message:e.message,severity:"error",source:"runtime"})},[B,V,ei,G,K,U,J,W]),ev=c(null),eS=n(e=>{let r=er.current+1;er.current=r,et.current={data:e,generation:r},ee.add(async()=>{let e=et.current;e&&e.data!==ev.current&&(et.current=null,ev.current=e.data,await ef(e.data,e.generation))})},[ef,ee]);N.onSpecChange.useSubscription(void 0,{enabled:!es&&el,onData:eS}),s(()=>{!es&&el&&eo().catch(()=>{console.warn("[DomainSpecContext] Failed to request spec files")})},[eo,es,el]);let eh=a(()=>({files:em,fileNames:eu,updateFile:eg,parsing:!1,parseError:H,clearParseError:ed,diagnostics:Y,clearDiagnostics:W,unreadDiagnosticCount:Z,markDiagnosticsRead:X}),[em,eu,eg,H,ed,Y,W,Z,X]);return e(b.Provider,{value:eh,children:i})};export const useDomainSpecContext=()=>{let e=i(b);if(null===e)throw Error("useDomainSpecContext must be used within DomainSpecProvider");return e};

package/dist/editor/domain-editors/apply-spec-update.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationRuntime as GeneratedApplicationRuntime } from '#package/application-spec';
+import { type ApplicationRuntime as GeneratedApplicationRuntime } from '#package/application-spec';
 import { type ImplementationError, type ApplicationSpec as RuntimeApplicationSpec } from '#package/domain';
 import type { ApplicationRuntime } from '#package/react-sdk';
 import type { ImplementationFiles } from './use-implementation-files.js';
@@ -23,6 +23,7 @@ export interface PrepareRuntimeRefreshInput {
     readonly implementationFiles: ImplementationFiles;
     readonly previousSpec: RuntimeApplicationSpec;
 }
+/** Refreshes the configurator sections of the live spec while the model's schema stays. */
 export declare const prepareRuntimeRefresh: (input: PrepareRuntimeRefreshInput) => PreparedRuntimeRefresh;
 /** Rebuilds every model-owned configurator field for an incompatible schema replacement. */
 export declare const prepareRuntimeReset: (input: PrepareRuntimeRefreshInput) => PreparedRuntimeReset;

package/dist/editor/domain-editors/apply-spec-update.js

@@ -1 +1 @@
-import{findAssistantFormElementErrors as e,resolveImportedTransformers as t}from"#package/domain";import{getPhoenixThemes as n}from"#package/ui-sdk";import{getCustomComponentOptics as s}from"./use-implementation-files.js";let o=e=>{var o;let i,a,{runtime:r,implementationFiles:m,previousSpec:c}=e,p=r.configurator,l=c.configurator,u=m.handlers?.handlers??l.handlers,f=m.handlers?((e,t,n)=>{let s={};for(let o of e)s[o.name]=t?.[o.name]??n?.[o.name]??o.name;return s})(u,m.handlers.nameHashes,l.handlerHashes):l.handlerHashes,d=m.elements?.elements??l.elements,h=m.elements?((e,t,n)=>{let s={},o=0;for(let i of e)if("assistantFormElement"!==i.type)if("entity"===i.type||"layout"===i.type)s[i.name]=t?.[i.name]??n?.[i.name]??i.name;else{let e=`icon:${o}`;s[e]=t?.[e]??n?.[e]??`${e}:${i.elements.length}`,o+=1}return s})(d,m.elements.nameHashes,l.elementHashes):l.elementHashes,g=null!==m.customComponentOptics,R=p.componentOptics.changed||g?[...p.componentOptics.optics.map(e=>e.optic),...m.customComponentOptics??s(l.componentOptics)]:l.componentOptics,x=p.transformersRuntime.changed?e=>t(p.transformersRuntime.importedTransformers,p.transformersRuntime.specTransformers,e):l.createTransformers;return{presets:p.presetRuntime.changed?p.presetRuntime.presets:l.presets,theme:p.themeRuntime.changed?(o=p.themeRuntime,i=n(),a=Object.entries(i).find(([e])=>e===o.preset)?.[1]??{},Object.keys(o.options).length>0?{...a,...o.options}:a):l.theme,assistant:p.assistantRuntime.changed?p.assistantRuntime.assistant:l.assistant,navigationStates:p.statesRuntime.changed?p.statesRuntime.navigationStates:l.navigationStates,viewStates:p.statesRuntime.changed?p.statesRuntime.viewStates:l.viewStates,toolStates:p.statesRuntime.changed?p.statesRuntime.toolStates:l.toolStates,exportStates:p.statesRuntime.changed?p.statesRuntime.exportStates:l.exportStates,componentOptics:R,createTransformers:x,handlers:u,handlerHashes:f,elements:d,elementHashes:h}},i=({assistant:t,elements:n})=>e(t?.formElements??[],n);export const prepareRuntimeRefresh=e=>{let{runtime:t,previousSpec:n}=e,s=n.configurator,a=o(e),r=t.configurator.expressionRuntime.changed?t.configurator.expressionRuntime.merged:s.expressions,m=t.configurator.actionsRuntime.changed?t.configurator.actionsRuntime.definitions:s.actions,c=e.implementationFiles.actionImplementations??s.actionImplementations;return{nextSpec:{...n,configurator:{...s,...a,expressions:r,actions:m,actionImplementations:c}},implementationErrors:i(a)}};export const prepareRuntimeReset=e=>{let{runtime:t,previousSpec:n}=e,s=n.configurator,a=o(e),r=t.configurator.expressionRuntime.merged,m=t.configurator.actionsRuntime.definitions,c=e.implementationFiles.actionImplementations??s.actionImplementations,p=t.configurator.modelRuntime.domainBuilder.withExpressions(r).withActions(Object.values(m)).withActionImplementations(c).build(),l=a.presets[0];if(void 0===l)throw Error("Cannot reset the configurator after a model change because the application spec has no presets.");return{firstPreset:l,nextSpec:{...n,configurator:{...s,...a,modelVersion:p.context.modelVersion,factory:p,aliasMap:p.context.aliasMap,entityReflections:p.context.entityReflections,$entityReflections:p.context.$entityReflections,expressions:r,actions:m,actionImplementations:c,allowedRootEntityTypes:p.context.allowedRootEntityTypes,migrate:p.context.migrate}},implementationErrors:i(a)}};let a=(e,t)=>{e.actions.spec.updateSpec(t)};export const applyRuntimeRefresh=(e,t)=>a(e,t.nextSpec);export const applyRuntimeReset=(e,t,n)=>{a(e,t.nextSpec),e.actions.loadedData.completeConfiguratorLoad({initialRevisionId:n,initialEntities:t.firstPreset.initialDomainEntities,modelVersion:t.nextSpec.configurator.modelVersion,rootEntityType:t.firstPreset.rootEntityType,schemaIdentity:t.nextSpec.configurator.factory})};export const applySpecUpdate=(e,t)=>a(e,t.nextSpec);
+import{applicationSpecSlice as e}from"#package/application-spec";import{findAssistantFormElementErrors as t}from"#package/domain";import{getPhoenixThemes as o}from"#package/ui-sdk";let n=e=>({handlers:e.handlers,elements:e.elements,customComponentOptics:e.customComponentOptics,actionImplementations:e.actionImplementations}),r=({configurator:e})=>t(e.assistant?.formElements??[],e.elements);export const prepareRuntimeRefresh=t=>{let i=e({runtime:t.runtime,modules:n(t.implementationFiles),themePresets:o(),previous:t.previousSpec,model:"keep"});return{nextSpec:i,implementationErrors:r(i)}};export const prepareRuntimeReset=t=>{let i=e({runtime:t.runtime,modules:n(t.implementationFiles),themePresets:o(),previous:t.previousSpec,model:"rebuild"}),s=i.configurator.presets[0];if(void 0===s)throw Error("Cannot reset the configurator after a model change because the application spec has no presets.");return{firstPreset:s,nextSpec:i,implementationErrors:r(i)}};let i=(e,t)=>{e.actions.spec.updateSpec(t)};export const applyRuntimeRefresh=(e,t)=>i(e,t.nextSpec);export const applyRuntimeReset=(e,t,o)=>{i(e,t.nextSpec),e.actions.loadedData.completeConfiguratorLoad({initialRevisionId:o,initialEntities:t.firstPreset.initialDomainEntities,modelVersion:t.nextSpec.configurator.modelVersion,rootEntityType:t.firstPreset.rootEntityType,schemaIdentity:t.nextSpec.configurator.factory})};export const applySpecUpdate=(e,t)=>i(e,t.nextSpec);

package/dist/editor/domain-editors/use-implementation-files.d.ts

@@ -1,4 +1,4 @@
-import type { Application, ExpressionImplementations, InvariantImplementations } from '#package/application-spec';
+import type { Application, InvariantImplementations } from '#package/application-spec';
 import { type AnyActionImplementations, type DomainComponentOptic, type DomainEntity, type ElementRegistration, type HandlerRegistration, type ImportedTransformer, type ProjectModule, type SystemComponentTypeConstraint } from '#package/domain';
 type RuntimeData = Record<string, unknown>;
 type RuntimeEntity = DomainEntity<string>;
@@ -21,15 +21,17 @@ export interface ReloadError {
 /**
  * The freshly reloaded (or cached) implementation files needed to build an `ApplicationRuntime`.
  *
- * `implementations`, `adminImplementations`, `invariantImplementations`, `importedTransformers` and `customComponentOptics` always contain the latest
+ * `expressionModules` and `adminExpressionModules` are the expression files as imported, unchecked:
+ * `ApplicationRuntime` checks and merges them with the aliases of the spec being edited.
+ * `expressionModules`, `adminExpressionModules`, `invariantImplementations`, `importedTransformers` and `customComponentOptics` always contain the latest
  * successfully loaded values. So does `actionImplementations`, which is `null` only until the first successful load: a round
  * that loaded them may be dropped before it is applied, and the next round must still carry them.
  * `handlers`/`elements` are `null` when their category did not change this round.
  */
 export interface ImplementationFiles {
-    readonly implementations: ExpressionImplementations;
+    readonly expressionModules: readonly ProjectModule[];
     readonly actionImplementations: AnyActionImplementations | null;
-    readonly adminImplementations?: ExpressionImplementations;
+    readonly adminExpressionModules?: readonly ProjectModule[];
     readonly invariantImplementations: InvariantImplementations;
     readonly importedTransformers: readonly ImportedTransformer[];
     readonly customComponentOptics: readonly ReloadedComponentOptic[] | null;
@@ -41,17 +43,7 @@ export interface GetImplementationFilesProps {
     readonly application: Application;
     readonly projectRoot: string;
 }
-type ResolvedExpressions = ExpressionImplementations;
-/**
- * Validates the expression modules through the resolver the domain builder uses, then expands their
- * aliases. The expansion stays here because the editor rebuilds expressions against the alias map of
- * the spec being edited, where the built app's domain builder holds its own.
- */
-export declare const mergeExpressionModules: (modules: readonly ProjectModule[], aliasMap: Record<string, readonly string[]>) => ResolvedExpressions;
 export declare const mergeComponentOptics: <ComponentOptic>(generatedComponentOptics: readonly ComponentOptic[], customComponentOptics: readonly ComponentOptic[]) => readonly ComponentOptic[];
-export declare const getCustomComponentOptics: <ComponentOptic extends {
-    readonly generated?: boolean;
-}>(componentOptics: readonly ComponentOptic[]) => readonly ComponentOptic[];
 /**
  * Owns the should-reload gating and cross-update caching for project implementation files
  * (expressions, actions, invariants, components, transformers, handlers, elements). Returns `getImplementationFiles`,

package/dist/editor/domain-editors/use-implementation-files.js

@@ -1 +1 @@
-import{useCallback as e,useRef as n}from"react";import{expandAlias as t,resolveActionModules as a,resolveComponentOpticModules as r,resolveElementModule as o,resolveExpressionModules as s,resolveHandlerModule as i,resolveInvariantModules as l,resolveTransformerModule as m}from"#package/domain";import{importImplementationFile as c}from"./import-implementation-file.js";let p=e=>e instanceof Error?e.message:String(e),f=async(e,n)=>{let t=Date.now();return Promise.all(e.map(async e=>({origin:e,exports:await c(`/@fs/${n}/${e}?t=${t}`)})))},d=async(e,n)=>a(await f(e,n));export const mergeExpressionModules=(e,n)=>{let a={};for(let{expressions:t}of s(e,n))for(let[e,n]of Object.entries(t))a[e]={...a[e],...n};let r={};for(let[e,o]of Object.entries(a))for(let a of t(n,e)){let n=r[a]??{};for(let[t,a]of Object.entries(o))n[t]={...a,origin:{name:t,typeOrAlias:e}};r[a]=n}return r};export const mergeComponentOptics=(e,n)=>e.concat(n);export const getCustomComponentOptics=e=>e.filter(e=>!0!==e.generated);let u=async(e,n,t)=>mergeExpressionModules(await f(e,t),n),g=async(e,n)=>r(await f(e,n)),h=async(e,n)=>l(await f(e,n)),E=async(e,n)=>(await f(e,n)).map(m),F=async(e,n)=>(await f(e,n)).map(e=>({filePath:e.origin,registrations:i(e)})),w=async(e,n)=>(await f(e,n)).map(e=>({filePath:e.origin,registrations:o(e)}));export const useImplementationFiles=()=>{let t=n({}),a=n(null),r=n({}),o=n(0),s=n(null),i=n({}),l=n(null),m=n(null),c=n(null),f=n([]),I=n(null),y=n(null),O=n(new Map),A=n(new Map);return{getImplementationFiles:e(async e=>{let{application:n,projectRoot:R}=e,C=++o.current,{applicationSpec:D,categorizedFiles:L}=n,S=[],x=t.current,M=r.current,_=i.current,$=c.current,b=f.current,v=L.expressionsChanged,N=L.actionsChanged,j=L.componentsChanged,P=L.transformersChanged,H=L.handlersChanged,T=L.elementsChanged,k=Object.fromEntries(L.invariants.map(e=>[e.file.name,e.depHash])),J=l.current,X=JSON.stringify(D.configurator.invariants.entries),V=null===J||m.current!==X||Object.keys(J).length!==L.invariants.length||L.invariants.some(e=>J[e.file.name]!==e.depHash);if(console.info(`[useImplementationFiles] Changed: spec=${L.specChanged}, expressions=${L.expressionsChanged}, actions=${L.actionsChanged}, adminExpressions=${L.adminExpressionsChanged}, transformers=${L.transformersChanged}, handlers=${L.handlersChanged}, elements=${L.elementsChanged}`),v){console.info("[useImplementationFiles] Reloading expression implementations");try{let e=Object.fromEntries(D.configurator.latestModel.aliases);t.current=x=await u(L.expressions.map(e=>e.file.name),e,R)}catch(e){console.warn("[useImplementationFiles] Failed to reload expressions:",e),S.push({code:"RELOAD_EXPRESSIONS_FAILED",message:p(e)})}}let q=a.current;if(N){console.info("[useImplementationFiles] Reloading action implementations");try{a.current=q=await d(L.actions.map(e=>e.file.name),R)}catch(e){console.warn("[useImplementationFiles] Failed to reload actions:",e),S.push({code:"RELOAD_ACTIONS_FAILED",message:p(e)})}}let z=JSON.stringify({projectRoot:R,files:L.adminExpressions.map(e=>[e.file.name,e.depHash]),aliases:[...D.admin.latestModel.aliases]});if(C===o.current&&s.current!==z)try{M=await u(L.adminExpressions.map(e=>e.file.name),Object.fromEntries(D.admin.latestModel.aliases),R),C===o.current&&(r.current=M,s.current=z)}catch(e){S.push({code:"RELOAD_ADMIN_EXPRESSIONS_FAILED",message:p(e)})}if(j){console.info("[useImplementationFiles] Reloading component optics");try{c.current=$=await g(L.components.map(e=>e.file.name),R)}catch(e){console.warn("[useImplementationFiles] Failed to reload components:",e),S.push({code:"RELOAD_COMPONENTS_FAILED",message:p(e)})}}if(V){console.info("[useImplementationFiles] Reloading invariant implementations");try{i.current=_=await h(L.invariants.map(e=>e.file.name),R),l.current=k,m.current=X}catch(e){console.warn("[useImplementationFiles] Failed to reload invariants:",e),S.push({code:"RELOAD_INVARIANTS_FAILED",message:p(e)})}}if(P){console.info("[useImplementationFiles] Reloading transformer implementations");try{f.current=b=await E(L.transformers.map(e=>e.file.name),R)}catch(e){console.warn("[useImplementationFiles] Failed to reload transformers:",e),S.push({code:"RELOAD_TRANSFORMERS_FAILED",message:p(e)})}}let B=null;if(H){console.info("[useImplementationFiles] Reloading handler implementations");try{let e=Object.fromEntries(L.handlers.map(e=>[e.file.name,e.depHash])),n=I.current,t=t=>null===n||n[t]!==e[t],a=A.current,r=L.handlers.map(e=>e.file.name),o=r.filter(e=>t(e)||!a.has(e)),s=await F(o,R),i=new Map(s.map(e=>[e.filePath,e])),l=r.map(e=>{let n=i.get(e)??a.get(e);if(!n)throw Error(`Handler file "${e}" was neither re-imported nor cached from a previous round. This is a hot-reload bookkeeping bug — reload the editor page to recover.`);return n}),m=l.flatMap(e=>e.registrations),c={};for(let{filePath:n,registrations:a}of l){let r=t(n)?e[n]:void 0;if(r)for(let e of a)c[e.name]=r}console.info(`[useImplementationFiles] Staged handlers for registry (${m.length} total)`),B={handlers:m,nameHashes:c},A.current=new Map(l.map(e=>[e.filePath,e])),I.current=e}catch(e){console.warn("[useImplementationFiles] Failed to reload handlers:",e),S.push({code:"RELOAD_HANDLERS_FAILED",message:p(e)})}}let G=null;if(T){console.info("[useImplementationFiles] Reloading element implementations");try{let e=Object.fromEntries(L.elements.map(e=>[e.file.name,e.depHash])),n=y.current,t=t=>null===n||n[t]!==e[t],a=O.current,r=L.elements.map(e=>e.file.name),o=r.filter(e=>t(e)||!a.has(e)),s=await w(o,R),i=new Map(s.map(e=>[e.filePath,e])),l=r.map(e=>{let n=i.get(e)??a.get(e);if(!n)throw Error(`Element file "${e}" was neither re-imported nor cached from a previous round. This is a hot-reload bookkeeping bug — reload the editor page to recover.`);return n}),m=l.flatMap(e=>e.registrations),c={},p=0;for(let{filePath:n,registrations:a}of l){let r=t(n)?e[n]:void 0;for(let e of a)if("assistantFormElement"!==e.type){if("entity"===e.type||"layout"===e.type){r&&(c[e.name]=r);continue}r&&(c[`icon:${p}`]=r),p+=1}}console.info(`[useImplementationFiles] Staged elements for registry (${m.length} total)`),G={elements:m,nameHashes:c},O.current=new Map(l.map(e=>[e.filePath,e])),y.current=e}catch(e){console.warn("[useImplementationFiles] Failed to reload elements:",e),S.push({code:"RELOAD_ELEMENTS_FAILED",message:p(e)})}}return{implementations:x,actionImplementations:q,adminImplementations:M,invariantImplementations:_,importedTransformers:b,customComponentOptics:$,handlers:B,elements:G,errors:S}},[])}};
+import{useCallback as e,useRef as n}from"react";import{resolveActionModules as t,resolveComponentOpticModules as a,resolveElementModule as r,resolveHandlerModule as o,resolveInvariantModules as i,resolveTransformerModule as s}from"#package/domain";import{importImplementationFile as l}from"./import-implementation-file.js";let m=e=>e instanceof Error?e.message:String(e),c=async(e,n)=>{let t=Date.now();return Promise.all(e.map(async e=>({origin:e,exports:await l(`/@fs/${n}/${e}?t=${t}`)})))},p=async(e,n)=>t(await c(e,n));export const mergeComponentOptics=(e,n)=>e.concat(n);let u=async(e,n)=>a(await c(e,n)),d=async(e,n)=>i(await c(e,n)),f=async(e,n)=>(await c(e,n)).map(s),h=async(e,n)=>(await c(e,n)).map(e=>({filePath:e.origin,registrations:o(e)})),g=async(e,n)=>(await c(e,n)).map(e=>({filePath:e.origin,registrations:r(e)}));export const useImplementationFiles=()=>{let t=n([]),a=n(null),r=n([]),o=n(0),i=n(null),s=n({}),l=n(null),E=n(null),F=n(null),w=n([]),I=n(null),y=n(null),A=n(new Map),R=n(new Map);return{getImplementationFiles:e(async e=>{let{application:n,projectRoot:O}=e,D=++o.current,{applicationSpec:L,categorizedFiles:S}=n,C=[],_=t.current,$=r.current,v=s.current,x=F.current,N=w.current,M=S.expressionsChanged,P=S.actionsChanged,b=S.componentsChanged,H=S.transformersChanged,T=S.handlersChanged,k=S.elementsChanged,j=Object.fromEntries(S.invariants.map(e=>[e.file.name,e.depHash])),J=l.current,X=JSON.stringify(L.configurator.invariants.entries),V=null===J||E.current!==X||Object.keys(J).length!==S.invariants.length||S.invariants.some(e=>J[e.file.name]!==e.depHash);if(console.info(`[useImplementationFiles] Changed: spec=${S.specChanged}, expressions=${S.expressionsChanged}, actions=${S.actionsChanged}, adminExpressions=${S.adminExpressionsChanged}, transformers=${S.transformersChanged}, handlers=${S.handlersChanged}, elements=${S.elementsChanged}`),M){console.info("[useImplementationFiles] Reloading expression implementations");try{t.current=_=await c(S.expressions.map(e=>e.file.name),O)}catch(e){console.warn("[useImplementationFiles] Failed to reload expressions:",e),C.push({code:"RELOAD_EXPRESSIONS_FAILED",message:m(e)})}}let q=a.current;if(P){console.info("[useImplementationFiles] Reloading action implementations");try{a.current=q=await p(S.actions.map(e=>e.file.name),O)}catch(e){console.warn("[useImplementationFiles] Failed to reload actions:",e),C.push({code:"RELOAD_ACTIONS_FAILED",message:m(e)})}}let z=JSON.stringify({projectRoot:O,files:S.adminExpressions.map(e=>[e.file.name,e.depHash])});if(D===o.current&&i.current!==z)try{$=await c(S.adminExpressions.map(e=>e.file.name),O),D===o.current&&(r.current=$,i.current=z)}catch(e){C.push({code:"RELOAD_ADMIN_EXPRESSIONS_FAILED",message:m(e)})}if(b){console.info("[useImplementationFiles] Reloading component optics");try{F.current=x=await u(S.components.map(e=>e.file.name),O)}catch(e){console.warn("[useImplementationFiles] Failed to reload components:",e),C.push({code:"RELOAD_COMPONENTS_FAILED",message:m(e)})}}if(V){console.info("[useImplementationFiles] Reloading invariant implementations");try{s.current=v=await d(S.invariants.map(e=>e.file.name),O),l.current=j,E.current=X}catch(e){console.warn("[useImplementationFiles] Failed to reload invariants:",e),C.push({code:"RELOAD_INVARIANTS_FAILED",message:m(e)})}}if(H){console.info("[useImplementationFiles] Reloading transformer implementations");try{w.current=N=await f(S.transformers.map(e=>e.file.name),O)}catch(e){console.warn("[useImplementationFiles] Failed to reload transformers:",e),C.push({code:"RELOAD_TRANSFORMERS_FAILED",message:m(e)})}}let B=null;if(T){console.info("[useImplementationFiles] Reloading handler implementations");try{let e=Object.fromEntries(S.handlers.map(e=>[e.file.name,e.depHash])),n=I.current,t=t=>null===n||n[t]!==e[t],a=R.current,r=S.handlers.map(e=>e.file.name),o=r.filter(e=>t(e)||!a.has(e)),i=await h(o,O),s=new Map(i.map(e=>[e.filePath,e])),l=r.map(e=>{let n=s.get(e)??a.get(e);if(!n)throw Error(`Handler file "${e}" was neither re-imported nor cached from a previous round. This is a hot-reload bookkeeping bug — reload the editor page to recover.`);return n}),m=l.flatMap(e=>e.registrations),c={};for(let{filePath:n,registrations:a}of l){let r=t(n)?e[n]:void 0;if(r)for(let e of a)c[e.name]=r}console.info(`[useImplementationFiles] Staged handlers for registry (${m.length} total)`),B={handlers:m,nameHashes:c},R.current=new Map(l.map(e=>[e.filePath,e])),I.current=e}catch(e){console.warn("[useImplementationFiles] Failed to reload handlers:",e),C.push({code:"RELOAD_HANDLERS_FAILED",message:m(e)})}}let G=null;if(k){console.info("[useImplementationFiles] Reloading element implementations");try{let e=Object.fromEntries(S.elements.map(e=>[e.file.name,e.depHash])),n=y.current,t=t=>null===n||n[t]!==e[t],a=A.current,r=S.elements.map(e=>e.file.name),o=r.filter(e=>t(e)||!a.has(e)),i=await g(o,O),s=new Map(i.map(e=>[e.filePath,e])),l=r.map(e=>{let n=s.get(e)??a.get(e);if(!n)throw Error(`Element file "${e}" was neither re-imported nor cached from a previous round. This is a hot-reload bookkeeping bug — reload the editor page to recover.`);return n}),m=l.flatMap(e=>e.registrations),c={},p=0;for(let{filePath:n,registrations:a}of l){let r=t(n)?e[n]:void 0;for(let e of a)if("assistantFormElement"!==e.type){if("entity"===e.type||"layout"===e.type){r&&(c[e.name]=r);continue}r&&(c[`icon:${p}`]=r),p+=1}}console.info(`[useImplementationFiles] Staged elements for registry (${m.length} total)`),G={elements:m,nameHashes:c},A.current=new Map(l.map(e=>[e.filePath,e])),y.current=e}catch(e){console.warn("[useImplementationFiles] Failed to reload elements:",e),C.push({code:"RELOAD_ELEMENTS_FAILED",message:m(e)})}}return{expressionModules:_,actionImplementations:q,adminExpressionModules:$,invariantImplementations:v,importedTransformers:N,customComponentOptics:x,handlers:B,elements:G,errors:C}},[])}};

package/dist/editor/graphql/GraphQLPanel.js

@@ -1 +1 @@
-import{jsx as e,jsxs as t}from"react/jsx-runtime";import o from"@monaco-editor/react";import{Box as r,Checkbox as i,FormControlLabel as a,Stack as n,Typography as s}from"@mui/material";import{useState as l}from"react";import{EditorButton as m}from"../common/EditorButton.js";import{jsonEditorOptions as d}from"../common/monaco-config.js";import{useOptionalConfigurator as c,useOptionalDomain as p}from"../hooks/use-optional-runtime.js";import{splitOperations as u}from"./split-operations.js";let h={fontSize:"12px",fontWeight:600,color:"text.secondary"};export const GraphQLPanel=()=>{let f=c()?.graphQLSystem,g=p()?.storeSystem,[x,y]=l("query { root { id type } }"),[b,v]=l(""),[S,k]=l(!1),[j,N]=l(null),[C,w]=l(null),[z,J]=l(!1),O=async()=>{let e=u(x),t=(e=>{if(""===e.trim())return{ok:!0,variables:void 0};try{let t=JSON.parse(e);return"object"!=typeof t||null===t||Array.isArray(t)?{ok:!1,message:"Variables must be a JSON object. Wrap them in {} or clear the field."}:{ok:!0,variables:t}}catch(e){return{ok:!1,message:`Variables are not valid JSON: ${e instanceof Error?e.message:String(e)}. Fix the JSON or clear the field.`}}})(b);if(f){if(w(null),!e.ok)return void N(e.message);if(!t.ok)return void N(t.message);if(S&&!g?.isInitialized)return void N("The configuration is not loaded yet, so there is no state to run against. Run again once the configurator has finished loading.");J(!0);try{let o=e.operations.map(e=>({...e,variables:t.variables})),r=S&&g?await f.prepare(g.stateSlices.committed.value.state,o):void 0,{results:i,committed:a,message:n,sideEffects:s}=r?{results:r.map(({result:e})=>e),committed:!1,message:"Dry run: nothing was committed.",sideEffects:f.readSideEffects(r)}:await f.execute(o),l=i.map((t,o)=>({operationName:e.operations[o]?.operationName??null,...t}));N(JSON.stringify(s.length>0?{results:l,sideEffects:s}:l,null,2)),w(a?"Committed as one undo step.":n??"Nothing was committed.")}finally{J(!1)}}};return t(n,{direction:"column",spacing:1.5,sx:{px:1.5,py:1},children:[e(s,{variant:"subtitle2",sx:h,children:"Query"}),e(r,{component:"div",sx:{height:160,border:"1px solid #dee2e6"},children:e(o,{language:"graphql",value:x,onChange:e=>y(e??""),options:d})}),e(s,{variant:"subtitle2",sx:h,children:"Variables (JSON)"}),e(r,{component:"div",sx:{height:80,border:"1px solid #dee2e6"},children:e(o,{language:"json",value:b,onChange:e=>v(e??""),options:d})}),e(a,{control:e(i,{size:"small",checked:S,onChange:e=>{k(e.target.checked)},sx:{p:.5}}),label:"Dry run",sx:{ml:-.5,mr:0,"& .MuiFormControlLabel-label":{fontSize:"12px",color:"#212529"}}}),e(m,{fullWidth:!0,disabled:!f||z,onClick:()=>void O(),children:f?"Run":"Configurator is not ready"}),null!==C&&e(s,{"data-testid":"graphql-status",sx:{fontSize:"12px",color:"text.secondary"},children:C}),null!==j&&e(r,{component:"pre","data-testid":"graphql-result",sx:{m:0,p:1,fontSize:"12px",backgroundColor:"#f8f9fa",overflow:"auto",whiteSpace:"pre-wrap"},children:j})]})};
+import{jsx as e,jsxs as t}from"react/jsx-runtime";import o from"@monaco-editor/react";import{Box as r,Checkbox as i,FormControlLabel as a,Stack as n,Typography as s}from"@mui/material";import{useState as l}from"react";import{EditorButton as m}from"../common/EditorButton.js";import{jsonEditorOptions as d}from"../common/monaco-config.js";import{useOptionalConfigurator as c,useOptionalDomain as p}from"../hooks/use-optional-runtime.js";import{splitOperations as u}from"./split-operations.js";let h={fontSize:"12px",fontWeight:600,color:"text.secondary"};export const GraphQLPanel=()=>{let g=c()?.graphQLSystem,f=p()?.storeSystem,[x,v]=l("query { root { id type } }"),[y,b]=l(""),[S,k]=l(!1),[j,N]=l(null),[w,C]=l(null),[z,J]=l(!1),O=async()=>{let e=u(x),t=(e=>{if(""===e.trim())return{ok:!0,variables:void 0};try{let t=JSON.parse(e);return"object"!=typeof t||null===t||Array.isArray(t)?{ok:!1,message:"Variables must be a JSON object. Wrap them in {} or clear the field."}:{ok:!0,variables:t}}catch(e){return{ok:!1,message:`Variables are not valid JSON: ${e instanceof Error?e.message:String(e)}. Fix the JSON or clear the field.`}}})(y);if(g){if(C(null),!e.ok)return void N(e.message);if(!t.ok)return void N(t.message);if(S&&!f?.isInitialized)return void N("The configuration is not loaded yet, so there is no state to run against. Run again once the configurator has finished loading.");J(!0);try{let o=e.operations.map(e=>({...e,variables:t.variables})),r=S?f?.stateSlices.committed.value.state:void 0,i=r?await g.prepare(r,o):void 0,{results:a,committed:n,message:s,sideEffects:l,warnings:m}=i&&r?{results:i.map(({result:e})=>e),committed:!1,message:"Dry run: nothing was committed.",sideEffects:g.readSideEffects(i),warnings:g.readWarnings(r,i)}:await g.execute(o),d=a.map((t,o)=>({operationName:e.operations[o]?.operationName??null,...t}));N(JSON.stringify(l.length>0||m.length>0?{results:d,...l.length>0?{sideEffects:l}:{},...m.length>0?{warnings:m}:{}}:d,null,2)),C(n?"Committed as one undo step.":s??"Nothing was committed.")}finally{J(!1)}}};return t(n,{direction:"column",spacing:1.5,sx:{px:1.5,py:1},children:[e(s,{variant:"subtitle2",sx:h,children:"Query"}),e(r,{component:"div",sx:{height:160,border:"1px solid #dee2e6"},children:e(o,{language:"graphql",value:x,onChange:e=>v(e??""),options:d})}),e(s,{variant:"subtitle2",sx:h,children:"Variables (JSON)"}),e(r,{component:"div",sx:{height:80,border:"1px solid #dee2e6"},children:e(o,{language:"json",value:y,onChange:e=>b(e??""),options:d})}),e(a,{control:e(i,{size:"small",checked:S,onChange:e=>{k(e.target.checked)},sx:{p:.5}}),label:"Dry run",sx:{ml:-.5,mr:0,"& .MuiFormControlLabel-label":{fontSize:"12px",color:"#212529"}}}),e(m,{fullWidth:!0,disabled:!g||z,onClick:()=>void O(),children:g?"Run":"Configurator is not ready"}),null!==w&&e(s,{"data-testid":"graphql-status",sx:{fontSize:"12px",color:"text.secondary"},children:w}),null!==j&&e(r,{component:"pre","data-testid":"graphql-result",sx:{m:0,p:1,fontSize:"12px",backgroundColor:"#f8f9fa",overflow:"auto",whiteSpace:"pre-wrap"},children:j})]})};

package/dist/legacy/domain-cli/utils/cache.d.ts

@@ -1,3 +1,3 @@
-export declare const cacheVersion = 772;
+export declare const cacheVersion = 773;
 export declare const needsRebuild: (fileContents: string[], outputDirectory: string) => Promise<boolean>;
 export declare const writeCacheInfo: (fileContents: string[], outputDirectory: string) => Promise<void>;

package/dist/legacy/domain-cli/utils/cache.js

@@ -1 +1 @@
-import{createHash as e}from"crypto";import{existsSync as r}from"fs";import{readFile as t}from"fs/promises";import{isEqualArray as o}from"@salsita-ai/common/utils";import{writeFormatted as i}from"../gen/write-formatted.js";export const cacheVersion=772;let s=r=>({version:772,files:r.map(r=>e("md5").update(r).digest("base64")).sort()});export const needsRebuild=async(e,i)=>{let a=`${i}/cache.json`;if(!r(a))return!0;try{let r=JSON.parse(await t(a,"utf-8")),i=s(e);return 772!==r.version||!o(r.files,i.files)}catch(e){return console.error("Failed to read cache file, forcing rebuild",e),!0}};export const writeCacheInfo=async(e,r)=>{let t=`${r}/cache.json`,o=s(e);await i(t,JSON.stringify(o,null,2))};
+import{createHash as e}from"crypto";import{existsSync as r}from"fs";import{readFile as t}from"fs/promises";import{isEqualArray as o}from"@salsita-ai/common/utils";import{writeFormatted as i}from"../gen/write-formatted.js";export const cacheVersion=773;let s=r=>({version:773,files:r.map(r=>e("md5").update(r).digest("base64")).sort()});export const needsRebuild=async(e,i)=>{let a=`${i}/cache.json`;if(!r(a))return!0;try{let r=JSON.parse(await t(a,"utf-8")),i=s(e);return 773!==r.version||!o(r.files,i.files)}catch(e){return console.error("Failed to read cache file, forcing rebuild",e),!0}};export const writeCacheInfo=async(e,r)=>{let t=`${r}/cache.json`,o=s(e);await i(t,JSON.stringify(o,null,2))};

package/dist/legacy/domain-spec/spec/domain-spec.js

@@ -1 +1 @@
-import{dereference as e}from"@apidevtools/json-schema-ref-parser";import t from"lodash-es/cloneDeep.js";import r from"lodash-es/isEqual.js";import{P as i,match as n}from"ts-pattern";import{ComponentSystemFilterSchema as o,availableSystemComponents as a,getAllPhxDefinitions as s,getExtendedSchemaValidator as d}from"#package/domain";import{domainSpecTemplate as f,requiredSpecs as p}from"./domain-spec-template.js";let m={anyOf:[{$ref:"#/definitions/Read"},{$ref:"#/definitions/ImportRef"},{$ref:"#/definitions/CodeRef"},{$ref:"#/definitions/DataRef"},{$ref:"#/definitions/Eval"}]},c={anyOf:[{$ref:"#/definitions/ReadWrite"},{$ref:"#/definitions/ImportRef"},{$ref:"#/definitions/CodeRef"}]},l=[{readName:"EnhancedStringRead",readWriteName:"EnhancedStringReadWrite",schema:{type:"string"}},{readName:"EnhancedNumberRead",readWriteName:"EnhancedNumberReadWrite",schema:{type:"number"}},{readName:"EnhancedBooleanRead",readWriteName:"EnhancedBooleanReadWrite",schema:{type:"boolean"}}],h=(e,t)=>({anyOf:[$(e,[]),t?{$ref:"#/definitions/ReadWriteEnhancement"}:{$ref:"#/definitions/ReadEnhancement"}]}),y=(e,t)=>{let i=l.find(t=>r(e,t.schema));return i?{$ref:`#/definitions/${t?i.readWriteName:i.readName}`}:h(e,t)},$=(e,t)=>({...e,...n(e).with({type:"object",properties:i.not(i.nullish).select()},e=>({properties:Object.fromEntries(Object.entries(e).map(([e,r])=>[e,y(r,t.includes(e))]))})).with({type:"object",additionalProperties:i.not(i.nullish.or(i.boolean)).select()},e=>({additionalProperties:y(e,!1)})).with({type:"object",patternProperties:i.not(i.nullish).select()},e=>({patternProperties:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,y(t,!1)]))})).with({type:"array",items:i.not(i.nullish).select()},e=>({items:$(e,[])})).with({anyOf:i.array().select()},e=>({anyOf:e.map(e=>$(e,[]))})).with({oneOf:i.array().select()},e=>({oneOf:e.map(e=>$(e,[]))})).otherwise(()=>({}))}),u={anyOf:[...$(o,[]).anyOf,{$ref:"#/definitions/Read"}]},j=Object.fromEntries(l.flatMap(e=>[[e.readName,h(e.schema,!1)],[e.readWriteName,h(e.schema,!0)]])),b=e=>{let{definitions:t,...r}=$(e.schema,e.writableKeys);return{type:"object",additionalProperties:{anyOf:[{...r,properties:{...r.properties,$filter:{$ref:"#/definitions/ComponentSystemFilter"}}},{type:"object",properties:{$read:{type:"string",pattern:"^\\$?[a-z]\\w*$"},$filter:{$ref:"#/definitions/ComponentSystemFilter"}},required:["$read"],additionalProperties:!1}]}}},O=e=>{let t=a.find(t=>t.name===e);if(!t)throw Error(`Component ${e} not found!`);return b(t)},E=e=>{for(let t of Object.values(e))for(let[e,r]of Object.entries(t)){let t={...O(e).additionalProperties,definitions:{...f.definitions,...s(),...j,ComponentSystemFilter:u,ReadEnhancement:m,ReadWriteEnhancement:c}},i=d().compile(t);for(let[t,n]of Object.entries(r))if(!i(n))throw Error(`Component validation failed ${e} ${t}, ${JSON.stringify(i.errors,null,2)}`)}};export const getDomainSpec=(e=!0)=>t({$comment:"This schema is generated from the domain-spec-template.json file, do not modify it directly.",...f,properties:{...f.properties,components:{type:"object",patternProperties:{"^[A-Z]\\w*$":{type:"object",properties:e?Object.fromEntries(a.map(e=>{let t=b(e);return[e.name,t]})):{},additionalProperties:!e}},additionalProperties:!1}},definitions:{...f.definitions,...s(),...j,ComponentSystemFilter:u,ReadEnhancement:m,ReadWriteEnhancement:c}});let R=getDomainSpec(!1),w=d().compile(R),g=d().compile({...R,$id:"https://salsita.ai/phoenix/schemas/domain-spec.json!complete",required:[...p]});export const getValidatePartialSpecification=()=>e=>{let t=w(e);return(E(e.components??{}),t)?{success:!0,value:e}:{success:!1,errors:w.errors}};export const getValidateMergedSpecification=()=>e=>{let t=g(e);return(E(e.components??{}),t)?{success:!0,value:e}:{success:!1,errors:g.errors}};export const dereferenceDomainSpec=async r=>{var i;let n,o;return r.definitions={...t(s()),...r.definitions??{}},i=e=>{"object"==typeof e&&null!==e&&"$ref"in e&&"string"==typeof e.$ref&&(e.$ref=e.$ref.replace("https://salsita.ai/phoenix/schemas/types.json#","#"))},n=new Set,(o=e=>{if(!n.has(e)){if(n.add(e),i(e),Array.isArray(e))for(let t of e)o(t);else if("object"==typeof e&&null!==e)for(let t of Object.values(e))o(t)}})(r),await e(r,{resolve:{http:!1,file:!1,common:{order:2}}}),delete r.definitions,r};
+import{dereference as e}from"@apidevtools/json-schema-ref-parser";import t from"lodash-es/cloneDeep.js";import r from"lodash-es/isEqual.js";import{P as i,match as n}from"ts-pattern";import{ComponentSystemFilterSchema as o,availableSystemComponents as a,getAllPhxDefinitions as s,getExtendedSchemaValidator as f}from"#package/domain";import{domainSpecTemplate as p,requiredSpecs as d}from"./domain-spec-template.js";let l={anyOf:[{$ref:"#/definitions/Read"},{$ref:"#/definitions/ImportRef"},{$ref:"#/definitions/CodeRef"},{$ref:"#/definitions/DataRef"},{$ref:"#/definitions/Eval"}]},m={anyOf:[{$ref:"#/definitions/ReadWrite"},{$ref:"#/definitions/ImportRef"},{$ref:"#/definitions/CodeRef"}]},c=[{readName:"EnhancedStringRead",readWriteName:"EnhancedStringReadWrite",schema:{type:"string"}},{readName:"EnhancedNumberRead",readWriteName:"EnhancedNumberReadWrite",schema:{type:"number"}},{readName:"EnhancedBooleanRead",readWriteName:"EnhancedBooleanReadWrite",schema:{type:"boolean"}}],h=(e,t)=>({anyOf:[$(e,[]),t?{$ref:"#/definitions/ReadWriteEnhancement"}:{$ref:"#/definitions/ReadEnhancement"}]}),y=(e,t)=>{let i=c.find(t=>r(e,t.schema));return i?{$ref:`#/definitions/${t?i.readWriteName:i.readName}`}:h(e,t)},$=(e,t)=>({...e,...n(e).with({type:"object",properties:i.not(i.nullish).select()},e=>({properties:Object.fromEntries(Object.entries(e).map(([e,r])=>[e,y(r,t.includes(e))]))})).with({type:"object",additionalProperties:i.not(i.nullish.or(i.boolean)).select()},e=>({additionalProperties:y(e,!1)})).with({type:"object",patternProperties:i.not(i.nullish).select()},e=>({patternProperties:Object.fromEntries(Object.entries(e).map(([e,t])=>[e,y(t,!1)]))})).with({type:"array",items:i.not(i.nullish).select()},e=>({items:$(e,[])})).with({anyOf:i.array().select()},e=>({anyOf:e.map(e=>$(e,[]))})).with({oneOf:i.array().select()},e=>({oneOf:e.map(e=>$(e,[]))})).otherwise(()=>({}))}),u={anyOf:[...$(o,[]).anyOf,{$ref:"#/definitions/Read"}]},j=Object.fromEntries(c.flatMap(e=>[[e.readName,h(e.schema,!1)],[e.readWriteName,h(e.schema,!0)]])),b=e=>{let{definitions:t,...r}=$(e.schema,e.writableKeys);return{type:"object",additionalProperties:{anyOf:[{...r,properties:{...r.properties,$filter:{$ref:"#/definitions/ComponentSystemFilter"}}},{type:"object",properties:{$read:{type:"string",pattern:"^\\$?[a-z]\\w*$"},$filter:{$ref:"#/definitions/ComponentSystemFilter"}},required:["$read"],additionalProperties:!1}]}}},O=new Map,E=e=>{let t=`${globalThis.PHX_SCHEMA_VALIDATOR??"ajv"}:${e}`,r=O.get(t);if(r)return r;let i={...(e=>{let t=a.find(t=>t.name===e);if(!t)throw Error(`Component ${e} not found!`);return b(t)})(e).additionalProperties,definitions:{...p.definitions,...s(),...j,ComponentSystemFilter:u,ReadEnhancement:l,ReadWriteEnhancement:m}},n=f().compile(i);return O.set(t,n),n},R=e=>{for(let t of Object.values(e))for(let[e,r]of Object.entries(t)){let t=E(e);for(let[i,n]of Object.entries(r))if(!t(n))throw Error(`Component validation failed ${e} ${i}, ${JSON.stringify(t.errors,null,2)}`)}};export const getDomainSpec=(e=!0)=>t({$comment:"This schema is generated from the domain-spec-template.json file, do not modify it directly.",...p,properties:{...p.properties,components:{type:"object",patternProperties:{"^[A-Z]\\w*$":{type:"object",properties:e?Object.fromEntries(a.map(e=>{let t=b(e);return[e.name,t]})):{},additionalProperties:!e}},additionalProperties:!1}},definitions:{...p.definitions,...s(),...j,ComponentSystemFilter:u,ReadEnhancement:l,ReadWriteEnhancement:m}});let g=getDomainSpec(!1),w=f().compile(g),S=f().compile({...g,$id:"https://salsita.ai/phoenix/schemas/domain-spec.json!complete",required:[...d]});export const getValidatePartialSpecification=()=>e=>{let t=w(e);return(R(e.components??{}),t)?{success:!0,value:e}:{success:!1,errors:w.errors}};export const getValidateMergedSpecification=()=>e=>{let t=S(e);return(R(e.components??{}),t)?{success:!0,value:e}:{success:!1,errors:S.errors}};export const dereferenceDomainSpec=async r=>{var i;let n,o;return r.definitions={...t(s()),...r.definitions??{}},i=e=>{"object"==typeof e&&null!==e&&"$ref"in e&&"string"==typeof e.$ref&&(e.$ref=e.$ref.replace("https://salsita.ai/phoenix/schemas/types.json#","#"))},n=new Set,(o=e=>{if(!n.has(e)){if(n.add(e),i(e),Array.isArray(e))for(let t of e)o(t);else if("object"==typeof e&&null!==e)for(let t of Object.values(e))o(t)}})(r),await e(r,{resolve:{http:!1,file:!1,common:{order:2}}}),delete r.definitions,r};

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  - `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";
+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; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call `phx.frontend.useSceneSafeArea()` and put `containerRef` on the element covering the whole canvas and `safeAreaRef` on the region the UI leaves free, with `pointerEvents: 'none'`, so the camera frames the scene there\n    - Sidebar moved, contents as the spec configures them: mount `LayoutSlots.DesktopSidebar` in a positioned container that sets its size, with `side=\"start\"` on the left; `docs/layouts/sidebar/in-a-custom-layout.mdx` is the whole layout\n    - Your own UI: \"Hooks for a Project Layout\" in `docs/phoenix/configurator-interface.mdx` lists the hooks with what each returns (`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx`), `docs/phoenix/layout-slots.mdx` the built-in pieces you can still mount, and `docs/layouts/custom-layout.mdx` is a worked example. Call the hooks as `phx.frontend.useX()`; besides those below, these are often needed: `usePreview()` (`isPreview` while the preview start screen shows), `useCloseAction()` (the host's close action or `null`), `useActiveViewports()` (the container's breakpoints, `null` until measured, `desktop` above 768 px: the desktop/phone switch), `useResolveLocalizable()` and `useLocalizable(text)` (spec texts to strings), `useIsCloningAllowed()` (a read-mode \"edit a copy\" action with `LayoutSlots.CloneToEditDialog`)\n    - Undo and redo: `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`; disable each button from `canUndo`/`canRedo`\n    - Tabs: `phx.frontend.useTabNavigation()` returns `{ source, tabs, activeTab, select }` for the spec's `sidebarTabs` (of the selected entity) or `horizontalTabs`; render `tabs` (each `{ index, label, icon, state, isActive }`, `icon` a PhxIcon name) and call `select(tab.index)` on click. Pass `{ source: 'sidebarTabs' }` or `{ source: 'horizontalTabs' }` when the layout shows one kind only. Not `LayoutSlots.useSidebarTabs()`: it serves the built-in sidebar and returns no tabs while its summary shows\n    - Steps: `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`; render `steps` (each `{ index, label, state, status }`, `status` `'complete' | 'active' | 'upcoming'`), call `next()`/`previous()` for Back and Next and `goTo(step.index)` from a stepper. It enforces no order and no validity: enable only `'complete'` steps for an \"earlier steps only\" stepper, and to block moving on while the configuration has a problem, require `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`: a change with a `fixable` or `fatal` violation is rejected, so the configuration is never invalid, and a `warning` is the problem that stays (it blocks finalizing too). `useSteps` and `useHasSteps` from `@salsita-ai/sdk/configurator` are deprecated\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. A failed save arrives as `saveError`, the next successful save as `saveRecovery`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): errors of the built-in actions are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`; render `primary` (and `secondary` in a menu or list) in a loop, each action `{ key, label, title, icon, run, isPending, error, disabled }`, and call `action.run()` on click (its promise never rejects; show `action.error` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, `phx.frontend.useFinalizeAction(handler)` in a component wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`) works too; `FinalizeActions` (from `@salsita-ai/sdk/configurator`) mounts the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them (`useUndoRedo`, `useFinalizeActions` and `useStepNavigation` included): hide undo, redo, finalization and whatever else a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true` (tabs are navigation, so a viewer may switch them), and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n  - `ConfigurationNotFoundPage`: `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => \u2026)` replaces the \"configuration not accessible\" page; show a way back only when the optional `onBack` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page\n  - `ConfiguratorErrorPage`: `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => \u2026)` replaces the production error page; `reason` is `uncaughtError` or `presetCreationFailed`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: `createCustomPhoenixLayoutElement` with the name works too, but types the component as taking only `children`, so the typed props do not compile there in a strict project\n  - `AppLoaderContent`: `phx.frontend.createAppLoader(({ phases }) => \u2026)` replaces what the loading overlay shows (each phase `{ id, label?, progress? }`, the list possibly empty); Phoenix keeps the overlay itself\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  - `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";
+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; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call `phx.frontend.useSceneSafeArea()` and put `containerRef` on the element covering the whole canvas and `safeAreaRef` on the region the UI leaves free, with `pointerEvents: 'none'`, so the camera frames the scene there\n    - Sidebar moved, contents as the spec configures them: mount `LayoutSlots.DesktopSidebar` in a positioned container that sets its size, with `side=\"start\"` on the left; `docs/layouts/sidebar/in-a-custom-layout.mdx` is the whole layout\n    - Your own UI: \"Hooks for a Project Layout\" in `docs/phoenix/configurator-interface.mdx` lists the hooks with what each returns (`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx`), `docs/phoenix/layout-slots.mdx` the built-in pieces you can still mount, and `docs/layouts/custom-layout.mdx` is a worked example. Call the hooks as `phx.frontend.useX()`; besides those below, these are often needed: `usePreview()` (`isPreview` while the preview start screen shows), `useCloseAction()` (the host's close action or `null`), `useActiveViewports()` (the container's breakpoints, `null` until measured, `desktop` above 768 px: the desktop/phone switch), `useResolveLocalizable()` and `useLocalizable(text)` (spec texts to strings), `useIsCloningAllowed()` (a read-mode \"edit a copy\" action with `LayoutSlots.CloneToEditDialog`)\n    - Undo and redo: `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`; disable each button from `canUndo`/`canRedo`\n    - Tabs: `phx.frontend.useTabNavigation()` returns `{ source, tabs, activeTab, select }` for the spec's `sidebarTabs` (of the selected entity) or `horizontalTabs`; render `tabs` (each `{ index, label, icon, state, isActive }`, `icon` a PhxIcon name) and call `select(tab.index)` on click. Pass `{ source: 'sidebarTabs' }` or `{ source: 'horizontalTabs' }` when the layout shows one kind only. Not `LayoutSlots.useSidebarTabs()`: it serves the built-in sidebar and returns no tabs while its summary shows\n    - Steps: `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`; render `steps` (each `{ index, label, state, status }`, `status` `'complete' | 'active' | 'upcoming'`), call `next()`/`previous()` for Back and Next and `goTo(step.index)` from a stepper. It enforces no order and no validity: enable only `'complete'` steps for an \"earlier steps only\" stepper, and to block moving on while the configuration has a problem, require `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`: a change with a `fixable` or `fatal` violation is rejected, so the configuration is never invalid, and a `warning` is the problem that stays (it blocks finalizing too). `useSteps` and `useHasSteps` from `@salsita-ai/sdk/configurator` are deprecated\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. A failed save arrives as `saveError`, the next successful save as `saveRecovery`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): errors of the built-in actions are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`; render `primary` (and `secondary` in a menu or list) in a loop, each action `{ key, label, title, icon, run, isPending, error, disabled }`, and call `action.run()` on click (its promise never rejects; show `action.error` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, `phx.frontend.useFinalizeAction(handler)` in a component wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`) works too; `FinalizeActions` (from `@salsita-ai/sdk/configurator`) mounts the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them (`useUndoRedo`, `useFinalizeActions` and `useStepNavigation` included): hide undo, redo, finalization and whatever else a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true` (tabs are navigation, so a viewer may switch them), and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n  - `ConfigurationNotFoundPage`: `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => \u2026)` replaces the \"configuration not accessible\" page; show a way back only when the optional `onBack` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page\n  - `ConfiguratorErrorPage`: `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => \u2026)` replaces the production error page; `reason` is `uncaughtError` or `presetCreationFailed`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: `createCustomPhoenixLayoutElement` with the name works too, but types the component as taking only `children`, so the typed props do not compile there in a strict project\n  - `AppLoaderContent`: `phx.frontend.createAppLoader(({ phases }) => \u2026)` replaces what the loading overlay shows (each phase `{ id, label?, progress? }`, the list possibly empty); Phoenix keeps the overlay itself\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  - `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]";
+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; put the UI above it, positioned and after it in the markup. With the canvas mounted the app loader waits until the scene has loaded; a layout without a canvas is not held by the loader. Call `phx.frontend.useSceneSafeArea()` and put `containerRef` on the element covering the whole canvas and `safeAreaRef` on the region the UI leaves free, with `pointerEvents: 'none'`, so the camera frames the scene there\n    - Sidebar moved, contents as the spec configures them: mount `LayoutSlots.DesktopSidebar` in a positioned container that sets its size, with `side=\"start\"` on the left; `docs/layouts/sidebar/in-a-custom-layout.mdx` is the whole layout\n    - Your own UI: \"Hooks for a Project Layout\" in `docs/phoenix/configurator-interface.mdx` lists the hooks with what each returns (`pnpm phoenix docs -r docs/phoenix/configurator-interface.mdx`), `docs/phoenix/layout-slots.mdx` the built-in pieces you can still mount, and `docs/layouts/custom-layout.mdx` is a worked example. Call the hooks as `phx.frontend.useX()`; besides those below, these are often needed: `usePreview()` (`isPreview` while the preview start screen shows), `useCloseAction()` (the host's close action or `null`), `useActiveViewports()` (the container's breakpoints, `null` until measured, `desktop` above 768 px: the desktop/phone switch), `useResolveLocalizable()` and `useLocalizable(text)` (spec texts to strings), `useIsCloningAllowed()` (a read-mode \"edit a copy\" action with `LayoutSlots.CloneToEditDialog`)\n    - Undo and redo: `phx.frontend.useUndoRedo()` returns `{ canUndo, canRedo, undo, redo }`; disable each button from `canUndo`/`canRedo`\n    - Tabs: `phx.frontend.useTabNavigation()` returns `{ source, tabs, activeTab, select }` for the spec's `sidebarTabs` (of the selected entity) or `horizontalTabs`; render `tabs` (each `{ index, label, icon, state, isActive }`, `icon` a PhxIcon name) and call `select(tab.index)` on click. Pass `{ source: 'sidebarTabs' }` or `{ source: 'horizontalTabs' }` when the layout shows one kind only. Not `LayoutSlots.useSidebarTabs()`: it serves the built-in sidebar and returns no tabs while its summary shows\n    - Steps: `phx.frontend.useStepNavigation()` returns `{ steps, activeStep, activeIndex, isFirst, isLast, canGoNext, canGoPrevious, next, previous, goTo }` for the spec's `navigationSteps`; render `steps` (each `{ index, label, state, status }`, `status` `'complete' | 'active' | 'upcoming'`), call `next()`/`previous()` for Back and Next and `goTo(step.index)` from a stepper. It enforces no order and no validity: enable only `'complete'` steps for an \"earlier steps only\" stepper, and to block moving on while the configuration has a problem, require `phx.frontend.useStateValidity().severity !== 'warning'` besides `canGoNext`: a change with a `fixable` or `fatal` violation is rejected, so the configuration is never invalid, and a `warning` is the problem that stays (it blocks finalizing too). `useSteps` and `useHasSteps` from `@salsita-ai/sdk/configurator` are deprecated\n    - Messages: mount `LayoutSlots.Services` for the built-in snackbars, or show violations, side-effect hints, errors and failed saves yourself with `phx.frontend.useConfiguratorMessages(onMessage)`, not both. A failed save arrives as `saveError`, the next successful save as `saveRecovery`; a layout that mounts neither shows no sign of a failed save. Either way mount a snackbar root (`LayoutSlots.DesktopSnackbarsRoot` or `LayoutSlots.MobileSnackbarsRoot`): errors of the built-in actions are always snackbars\n    - Finalize over the spec's `finalizeAction` components, each naming a handler registered with `phx.frontend.createPhoenixHandler`: `phx.frontend.useFinalizeActions()` returns `{ actions, primary, secondary, disabled, hints }`; render `primary` (and `secondary` in a menu or list) in a loop, each action `{ key, label, title, icon, run, isPending, error, disabled }`, and call `action.run()` on click (its promise never rejects; show `action.error` on failure). The configurator runs the handlers itself, outside the layout, so a handler must not rely on a provider the layout adds. For one known handler, `phx.frontend.useFinalizeAction(handler)` in a component wrapped in `PhoenixHandlerBoundary` (from `@salsita-ai/sdk/react`) works too; `FinalizeActions` (from `@salsita-ai/sdk/configurator`) mounts the built-in buttons. `finalizePage` and `finalizeButton` are legacy\n    - Read mode and fullscreen are the layout's job, no hook enforces them (`useUndoRedo`, `useFinalizeActions` and `useStepNavigation` included): hide undo, redo, finalization and whatever else a viewer must not change while `phx.frontend.useAccessService().accessInfo.viewMode` is `true` (tabs are navigation, so a viewer may switch them), and remove panels while `phx.frontend.useIsFullscreenActive()` is set; `phx.frontend.useSetFullscreen()` returns its setter\n  - `ConfigurationNotFoundPage`: `phx.frontend.createConfigurationNotFoundPage(({ onBack }) => \u2026)` replaces the \"configuration not accessible\" page; show a way back only when the optional `onBack` is set. The not-authenticated page's default renders it too; only the admin's not-authorized page keeps the built-in page\n  - `ConfiguratorErrorPage`: `phx.frontend.createConfiguratorErrorPage(({ reason, onRetry }) => \u2026)` replaces the production error page; `reason` is `uncaughtError` or `presetCreationFailed`. A page that throws falls back to the built-in one, and development keeps the detailed error pages, so the project page shows only in a production build. Register both pages with these helpers: `createCustomPhoenixLayoutElement` with the name works too, but types the component as taking only `children`, so the typed props do not compile there in a strict project\n  - `AppLoaderContent`: `phx.frontend.createAppLoader(({ phases }) => \u2026)` replaces what the loading overlay shows (each phase `{ id, label?, progress? }`, the list possibly empty); Phoenix keeps the overlay itself\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]";