@salsita-ai/sdk 0.50.0-develop.be40f0cee8 → 0.50.0-develop.bfba230ad7

package/dist/configurator/scene/scene-analytics/scene-analytics.d.ts

@@ -1,5 +1,5 @@
-declare const PerspectiveCameraDragEvent: () => import("../../../domain/domain-context/analytics-system/analytics-contracts").UserActionEvent;
-declare const OrthographicCameraDragEvent: () => import("../../../domain/domain-context/analytics-system/analytics-contracts").UserActionEvent;
+declare const PerspectiveCameraDragEvent: () => import("#package/domain").UserActionEvent;
+declare const OrthographicCameraDragEvent: () => import("#package/domain").UserActionEvent;
 export declare const SceneAnalyticsFactory: {
     PerspectiveCameraDragEvent: typeof PerspectiveCameraDragEvent;
     OrthographicCameraDragEvent: typeof OrthographicCameraDragEvent;

package/dist/configurator/ui/assistant/AssistantComposer.d.ts

@@ -1,11 +1,6 @@
-import type { AssistantChatState } from '../../assistant/index.js';
-export interface AssistantComposerProps {
-    readonly chat: AssistantChatState | undefined;
-    readonly onFocusChange: (isFocused: boolean) => void;
-}
 /**
  * The message input of the panel. Enter sends and Shift+Enter adds a line. While a reply runs the
  * send control is a Stop control and the input stays editable, so the next message can be written.
  * A thread this session may not continue disables the input and says why.
  */
-export declare const AssistantComposer: ({ chat, onFocusChange }: AssistantComposerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AssistantComposer: () => import("react/jsx-runtime").JSX.Element;

package/dist/configurator/ui/assistant/AssistantComposer.js

@@ -1 +1 @@
-import{jsx as e,jsxs as a}from"react/jsx-runtime";import{Trans as r}from"@lingui/react";import{IconButton as o,InputBase as i,Tooltip as t,styled as n}from"@mui/material";import{useCallback as s,useRef as d,useState as l}from"react";import{useLocalizable as m}from"#package/react-sdk";import{PhxIcon as c,useResponsive as p}from"#package/ui-sdk";import{AssistantPanelName as u}from"./theme.js";let b={id:"sdk.assistant.composer.placeholder",message:"Ask or tell me what to change…"},g={id:"sdk.assistant.composer.send.label",message:"Send"},h={id:"sdk.assistant.composer.stop.label",message:"Stop"},k=n("form",{name:u,slot:"composer"})(({theme:{palette:e,spacing:a}})=>({borderBlockStart:`1px solid ${e.divider}`,display:"grid",gap:a(.75),paddingBlock:a(1.25),paddingInline:`var(--phx-sidebar-padding, ${a(2)})`})),f=n("div",{name:u,slot:"inputFrame"})(({theme:{palette:e,spacing:a}})=>({alignItems:"flex-end",border:`1px solid ${e.divider}`,borderRadius:12,display:"flex",gap:a(1),paddingBlock:a(.5),paddingInline:`${a(1.5)} ${a(.5)}`,"&:focus-within":{borderColor:e.primary.main},"&:has(textarea:disabled)":{background:e.action.disabledBackground}})),x=n(i,{name:u,slot:"input"})(({theme:{spacing:e,typography:a}})=>({...a.body2,flex:1,paddingBlock:e(.75)})),v=n(o,{name:u,slot:"sendButton"})(({theme:{palette:e}})=>({background:e.primary.main,borderRadius:8,color:e.primary.contrastText,"&:hover":{background:e.primary.dark},"&.Mui-disabled":{background:e.action.disabledBackground,color:e.action.disabled}})),y=n(o,{name:u,slot:"stopButton"})(({theme:{palette:e}})=>({background:e.text.primary,borderRadius:8,color:e.background.paper,"&:hover":{background:e.text.secondary}})),B=n("span")({background:"currentColor",blockSize:10,borderRadius:2,inlineSize:10,margin:5}),C=n("div",{name:u,slot:"hint"})(({theme:{palette:e,typography:a}})=>({...a.caption,color:e.text.secondary}));export const AssistantComposer=({chat:o,onFocusChange:i})=>{let[n,u]=l(""),R=d(null),{isDesktop:S}=p(),w=m(b),z=m(g),$=m(h),j=o?.isLoading??!1,I=o?.isContinuable??!0,A=n.trim(),D=null!=o&&I&&!j&&A.length>0,P=s(()=>{o&&D&&(u(""),o.send(A),S||R.current?.blur())},[D,o,A,S]),T=s(e=>{e.preventDefault(),P()},[P]),E=s(e=>{"Enter"!==e.key||e.shiftKey||e.nativeEvent.isComposing||(e.preventDefault(),P())},[P]),F=s(()=>{o?.stop()},[o]);return a(k,{onSubmit:T,children:[!I&&e(C,{role:"status",children:e(r,{id:"sdk.assistant.composer.notContinuable",message:"This conversation can be read here, but it can no longer be continued."})}),a(f,{children:[e(x,{multiline:!0,maxRows:6,placeholder:w,value:n,disabled:!I,inputRef:R,onChange:e=>u(e.target.value),onKeyDown:E,onFocus:()=>i(!0),onBlur:()=>i(!1),inputProps:{"aria-label":w}}),j?e(t,{title:$,placement:"top",children:e(y,{size:"small","aria-label":$,onClick:F,children:e(B,{})})}):e(t,{title:z,placement:"top",children:e("span",{children:e(v,{type:"submit",size:"small","aria-label":z,disabled:!D,children:e(c,{name:"PaperPlaneRightBold",fontSize:"small"})})})})]}),e(C,{children:e(r,{id:"sdk.assistant.composer.disclaimer",message:"AI can be wrong. Check the result."})})]})};
+import{jsx as e,jsxs as a}from"react/jsx-runtime";import{Trans as i}from"@lingui/react";import{IconButton as o,InputBase as r,Tooltip as t,styled as n}from"@mui/material";import{useCallback as s,useRef as d,useState as l}from"react";import{useEagerObservableSelector as m,useLocalizable as c}from"#package/react-sdk";import{PhxIcon as p,useResponsive as u}from"#package/ui-sdk";import{useConfigurator as b}from"../../application-runtime/index.js";import{AssistantPanelName as g}from"./theme.js";let h={id:"sdk.assistant.composer.placeholder",message:"Ask or tell me what to change…"},k={id:"sdk.assistant.composer.send.label",message:"Send"},f={id:"sdk.assistant.composer.stop.label",message:"Stop"},x=n("form",{name:g,slot:"composer"})(({theme:{palette:e,spacing:a}})=>({borderBlockStart:`1px solid ${e.divider}`,display:"grid",gap:a(.75),paddingBlock:a(1.25),paddingInline:`var(--phx-sidebar-padding, ${a(2)})`})),y=n("div",{name:g,slot:"inputFrame"})(({theme:{palette:e,spacing:a}})=>({alignItems:"flex-end",border:`1px solid ${e.divider}`,borderRadius:12,display:"flex",gap:a(1),paddingBlock:a(.5),paddingInline:`${a(1.5)} ${a(.5)}`,"&:focus-within":{borderColor:e.primary.main},"&:has(textarea:disabled)":{background:e.action.disabledBackground}})),v=n(r,{name:g,slot:"input"})(({theme:{spacing:e,typography:a}})=>({...a.body2,flex:1,paddingBlock:e(.75)})),B=n(o,{name:g,slot:"sendButton"})(({theme:{palette:e}})=>({background:e.primary.main,borderRadius:8,color:e.primary.contrastText,"&:hover":{background:e.primary.dark},"&.Mui-disabled":{background:e.action.disabledBackground,color:e.action.disabled}})),C=n(o,{name:g,slot:"stopButton"})(({theme:{palette:e}})=>({background:e.text.primary,borderRadius:8,color:e.background.paper,"&:hover":{background:e.text.secondary}})),R=n("span")({background:"currentColor",blockSize:10,borderRadius:2,inlineSize:10,margin:5}),S=n("div",{name:g,slot:"hint"})(({theme:{palette:e,typography:a}})=>({...a.caption,color:e.text.secondary}));export const AssistantComposer=()=>{let{assistantSystem:o}=b(),[r,n]=l(""),g=d(null),{isDesktop:I}=u(),$=c(h),j=c(k),w=c(f),{isReplying:z,isContinuable:F}=m(o.chat$,e=>({isReplying:e.isLoading,isContinuable:e.isContinuable}),[]),A=r.trim(),D=F&&!z&&A.length>0,P=s(()=>{D&&(n(""),o.send(A),I||g.current?.blur())},[o,D,A,I]),T=s(e=>{e.preventDefault(),P()},[P]),E=s(e=>{"Enter"!==e.key||e.shiftKey||e.nativeEvent.isComposing||(e.preventDefault(),P())},[P]),K=s(()=>{o.stop()},[o]);return a(x,{onSubmit:T,children:[!F&&e(S,{role:"status",children:e(i,{id:"sdk.assistant.composer.notContinuable",message:"This conversation can be read here, but it can no longer be continued."})}),a(y,{children:[e(v,{multiline:!0,maxRows:6,placeholder:$,value:r,disabled:!F,inputRef:g,onChange:e=>n(e.target.value),onKeyDown:E,onFocus:()=>o.setInputFocused(!0),onBlur:()=>o.setInputFocused(!1),inputProps:{"aria-label":$}}),z?e(t,{title:w,placement:"top",children:e(C,{size:"small","aria-label":w,onClick:K,children:e(R,{})})}):e(t,{title:j,placement:"top",children:e("span",{children:e(B,{type:"submit",size:"small","aria-label":j,disabled:!D,children:e(p,{name:"PaperPlaneRightBold",fontSize:"small"})})})})]}),e(S,{children:e(i,{id:"sdk.assistant.composer.disclaimer",message:"AI can be wrong. Check the result."})})]})};

package/dist/configurator/ui/assistant/AssistantPanel.js

@@ -1 +1 @@
-import{jsx as e,jsxs as t}from"react/jsx-runtime";import{IconButton as a,Tooltip as s,Typography as n,styled as r}from"@mui/material";import{useCallback as o}from"react";import{useLocalizable as i}from"#package/react-sdk";import{PhxIcon as l}from"#package/ui-sdk";import{AssistantComposer as d}from"./AssistantComposer.js";import{useAssistantPanel as m,useAssistantPanelConversation as p}from"./AssistantPanelProvider.js";import{AssistantThread as c}from"./AssistantThread.js";import{AssistantPanelName as h}from"./theme.js";let u={id:"sdk.assistant.panel.title",message:"Assistant"},g={id:"sdk.assistant.panel.close.label",message:"Close assistant"};export const ASSISTANT_PANEL_SLOT="slot[assistant]";let b=r("section",{name:h,slot:"root"})(({theme:{palette:e}})=>({background:`var(--phx-sidebar-background, ${e.background.paper})`,border:"var(--phx-sidebar-border, 0)",borderRadius:"inherit",display:"grid",gridTemplateColumns:"minmax(0, 1fr)",gridTemplateRows:"min-content minmax(0, 1fr) min-content",inset:0,overflow:"hidden",position:"absolute",zIndex:1})),f=r("header",{name:h,slot:"header"})(({theme:{palette:e,spacing:t}})=>({alignItems:"center",borderBlockEnd:`1px solid ${e.divider}`,display:"flex",gap:t(1),justifyContent:"space-between",paddingBlock:t(1),paddingInline:`var(--phx-sidebar-padding, ${t(2)}) ${t(1)}`})),x=r(n,{name:h,slot:"title"})({fontWeight:600}),k=r(a,{name:h,slot:"closeButton"})({}),j=e=>{e.target instanceof Element&&e.target.closest("button")&&e.preventDefault()};export const AssistantPanel=()=>{let a=m(),n=p(),r=i(u),h=i(g),v=a?.setOpen,A=o(()=>{v?.(!1)},[v]);return a?.open&&n?t(b,{"data-sidebar":"slot[assistant]","aria-label":r,onMouseDown:j,children:[t(f,{children:[e(x,{variant:"subtitle1",component:"h2",children:r}),e(s,{title:h,placement:"top",children:e(k,{size:"small","aria-label":h,onClick:A,children:e(l,{name:"X"})})})]}),e(c,{chat:n.chat,onRetry:n.reloadThread}),e(d,{chat:n.chat,onFocusChange:a.setInputFocused})]}):null};
+import{jsx as e,jsxs as t}from"react/jsx-runtime";import{IconButton as s,Tooltip as a,Typography as i,styled as n}from"@mui/material";import{useCallback as r}from"react";import{useLocalizable as o}from"#package/react-sdk";import{PhxIcon as l}from"#package/ui-sdk";import{useConfigurator as m}from"../../application-runtime/index.js";import{AssistantComposer as d}from"./AssistantComposer.js";import{AssistantThread as p}from"./AssistantThread.js";import{AssistantPanelName as c}from"./theme.js";import{useIsAssistantPanelOpen as u}from"./use-is-assistant-panel-open.js";let b={id:"sdk.assistant.panel.title",message:"Assistant"},f={id:"sdk.assistant.panel.close.label",message:"Close assistant"};export const ASSISTANT_PANEL_SLOT="slot[assistant]";let g=n("section",{name:c,slot:"root"})(({theme:{palette:e}})=>({background:`var(--phx-sidebar-background, ${e.background.paper})`,border:"var(--phx-sidebar-border, 0)",borderRadius:"inherit",display:"grid",gridTemplateColumns:"minmax(0, 1fr)",gridTemplateRows:"min-content minmax(0, 1fr) min-content",inset:0,overflow:"hidden",position:"absolute",zIndex:1})),h=n("header",{name:c,slot:"header"})(({theme:{palette:e,spacing:t}})=>({alignItems:"center",borderBlockEnd:`1px solid ${e.divider}`,display:"flex",gap:t(1),justifyContent:"space-between",paddingBlock:t(1),paddingInline:`var(--phx-sidebar-padding, ${t(2)}) ${t(1)}`})),x=n(i,{name:c,slot:"title"})({fontWeight:600}),k=n(s,{name:c,slot:"closeButton"})({}),j=e=>{e.target instanceof Element&&e.target.closest("button")&&e.preventDefault()};export const AssistantPanel=()=>{let{assistantSystem:s}=m(),i=u(),n=o(b),c=o(f),v=r(()=>{s.setOpen(!1)},[s]);return i?t(g,{"data-sidebar":"slot[assistant]","aria-label":n,onMouseDown:j,children:[t(h,{children:[e(x,{variant:"subtitle1",component:"h2",children:n}),e(a,{title:c,placement:"top",children:e(k,{size:"small","aria-label":c,onClick:v,children:e(l,{name:"X"})})})]}),e(p,{}),e(d,{})]}):null};

package/dist/configurator/ui/assistant/AssistantThread.d.ts

@@ -1,11 +1,6 @@
-import type { AssistantChatState } from '../../assistant/index.js';
-export interface AssistantThreadProps {
-    readonly chat: AssistantChatState | undefined;
-    readonly onRetry: () => void;
-}
 /**
  * The conversation: user bubbles, assistant Markdown, tool chips, and what the panel
  * has to say itself, which is a greeting for an empty thread, a "Thinking…" line and a failure with
  * its way out. It follows a streaming reply until the user scrolls up.
  */
-export declare const AssistantThread: ({ chat, onRetry }: AssistantThreadProps) => import("react/jsx-runtime").JSX.Element;
+export declare const AssistantThread: () => import("react/jsx-runtime").JSX.Element;

package/dist/configurator/ui/assistant/AssistantThread.js

@@ -1 +1 @@
-import{jsx as e,jsxs as i}from"react/jsx-runtime";import{Trans as a}from"@lingui/react";import{Button as s,styled as t}from"@mui/material";import{useMemo as n}from"react";import{match as r}from"ts-pattern";import{PhxIcon as o}from"#package/ui-sdk";import{AssistantToolChips as l}from"./AssistantChips.js";import{AssistantMarkdown as d}from"./AssistantMarkdown.js";import{describeAssistantFailure as m}from"./assistant-failure.js";import{AssistantPanelName as p}from"./theme.js";import{buildThreadView as h}from"./thread-items.js";import{useFollowStream as c}from"./use-follow-stream.js";let g=t("div",{name:p,slot:"thread"})({display:"grid",position:"relative"}),u=t("div",{name:p,slot:"messages"})(({theme:{spacing:e,typography:i}})=>({...i.body2,display:"flex",flexDirection:"column",gap:e(1.5),overflowY:"auto",overscrollBehavior:"contain",paddingBlock:e(2),paddingInline:`var(--phx-sidebar-padding, ${e(2)})`,"& > :first-child":{marginBlockStart:"auto"}})),f=t("div",{name:p,slot:"userMessage"})(({theme:{palette:e,spacing:i}})=>({alignSelf:"flex-end",background:`hsl(from ${e.primary.main} h s l / 12%)`,borderRadius:"14px 14px 4px 14px",maxInlineSize:"85%",overflowWrap:"anywhere",paddingBlock:i(1),paddingInline:i(1.5),whiteSpace:"pre-wrap"})),k=t("div",{name:p,slot:"greeting"})({}),v=t("div",{name:p,slot:"status"})(({theme:{palette:e,typography:i}})=>({...i.caption,color:e.text.secondary})),w=t("div",{name:p,slot:"notice"})(({theme:{palette:e,shape:i,spacing:a}})=>({alignItems:"center",background:e.action.hover,borderRadius:i.borderRadius,display:"flex",flexWrap:"wrap",gap:a(1),justifyContent:"space-between",paddingBlock:a(1),paddingInline:a(1.5)})),b=t(s,{name:p,slot:"newReplyButton"})(({theme:{palette:e,spacing:i}})=>({background:e.text.primary,borderRadius:"calc(infinity * 1px)",color:e.background.paper,insetBlockEnd:i(1),insetInlineStart:"50%",position:"absolute",translate:"-50% 0","&:hover":{background:e.text.secondary}})),x=({item:i,isActive:a})=>r(i).with({kind:"user"},({text:i})=>e(f,{children:i})).with({kind:"text"},({markdown:i,isStreaming:a})=>e(d,{markdown:i,isStreaming:a})).with({kind:"tools"},({tools:i})=>e(l,{tools:i,isActive:a})).exhaustive();export const AssistantThread=({chat:t,onRetry:l})=>{let d=t?.messages,p=t?.isLoading??!1,{items:f,isThinking:y}=n(()=>h(d??[],p),[d,p]),j=n(()=>f.filter(({kind:e})=>"user"===e).length,[f]),I=t?.error?m(t.failedStatus):void 0,{scrollerRef:S,hasUnseenContent:T,handleScroll:A,scrollToEnd:B}=c(n(()=>({messages:d,isThinking:y,failure:I?.kind}),[d,y,I?.kind]),j);return i(g,{children:[i(u,{ref:S,onScroll:A,role:"log","aria-live":"polite",children:[t?.isLoaded===!0&&0===f.length&&!p&&!I&&e(k,{children:e(a,{id:"sdk.assistant.thread.greeting",message:"Hi. I can answer questions about this design and change it with you. Tell me what you need."})}),f.map(i=>e(x,{item:i,isActive:p&&i===f.at(-1)},i.id)),y&&e(v,{children:e(a,{id:"sdk.assistant.thread.thinking",message:"Thinking…"})}),I&&i(w,{role:"alert",children:[e("span",{children:r(I.kind).with("notAvailable",()=>e(a,{id:"sdk.assistant.failure.notAvailable",message:"The assistant is not available here."})).with("busy",()=>e(a,{id:"sdk.assistant.failure.busy",message:"The assistant is still working on an earlier message."})).with("unavailable",()=>e(a,{id:"sdk.assistant.failure.unavailable",message:"The assistant is unavailable right now."})).exhaustive()}),I.canRetry&&e(s,{size:"small",variant:"outlined",color:"inherit",onClick:l,children:e(a,{id:"sdk.assistant.failure.retry.label",message:"Try again"})})]})]}),T&&e(b,{size:"small",onClick:B,endIcon:e(o,{name:"CaretDown"}),children:e(a,{id:"sdk.assistant.thread.newReply.label",message:"New reply"})})]})};
+import{jsx as e,jsxs as i}from"react/jsx-runtime";import{Trans as a}from"@lingui/react";import{Button as t,styled as s}from"@mui/material";import{useMemo as r}from"react";import{match as n}from"ts-pattern";import{useEagerObservableValue as o}from"#package/react-sdk";import{PhxIcon as l}from"#package/ui-sdk";import{useConfigurator as d}from"../../application-runtime/index.js";import{AssistantToolChips as m}from"./AssistantChips.js";import{AssistantMarkdown as p}from"./AssistantMarkdown.js";import{describeAssistantFailure as c}from"./assistant-failure.js";import{AssistantPanelName as h}from"./theme.js";import{buildThreadView as g}from"./thread-items.js";import{useFollowStream as u}from"./use-follow-stream.js";let f=s("div",{name:h,slot:"thread"})({display:"grid",position:"relative"}),k=s("div",{name:h,slot:"messages"})(({theme:{spacing:e,typography:i}})=>({...i.body2,display:"flex",flexDirection:"column",gap:e(1.5),overflowY:"auto",overscrollBehavior:"contain",paddingBlock:e(2),paddingInline:`var(--phx-sidebar-padding, ${e(2)})`,"& > :first-child":{marginBlockStart:"auto"}})),v=s("div",{name:h,slot:"userMessage"})(({theme:{palette:e,spacing:i}})=>({alignSelf:"flex-end",background:`hsl(from ${e.primary.main} h s l / 12%)`,borderRadius:"14px 14px 4px 14px",maxInlineSize:"85%",overflowWrap:"anywhere",paddingBlock:i(1),paddingInline:i(1.5),whiteSpace:"pre-wrap"})),w=s("div",{name:h,slot:"greeting"})({}),b=s("div",{name:h,slot:"status"})(({theme:{palette:e,typography:i}})=>({...i.caption,color:e.text.secondary})),x=s("div",{name:h,slot:"notice"})(({theme:{palette:e,shape:i,spacing:a}})=>({alignItems:"center",background:e.action.hover,borderRadius:i.borderRadius,display:"flex",flexWrap:"wrap",gap:a(1),justifyContent:"space-between",paddingBlock:a(1),paddingInline:a(1.5)})),y=s(t,{name:h,slot:"newReplyButton"})(({theme:{palette:e,spacing:i}})=>({background:e.text.primary,borderRadius:"calc(infinity * 1px)",color:e.background.paper,insetBlockEnd:i(1),insetInlineStart:"50%",position:"absolute",translate:"-50% 0","&:hover":{background:e.text.secondary}})),j=({item:i,isActive:a})=>n(i).with({kind:"user"},({text:i})=>e(v,{children:i})).with({kind:"text"},({markdown:i,isStreaming:a})=>e(p,{markdown:i,isStreaming:a})).with({kind:"tools"},({tools:i})=>e(m,{tools:i,isActive:a})).exhaustive();export const AssistantThread=()=>{let{assistantSystem:s}=d(),m=o(s.chat$),{messages:p,isLoading:h}=m,{items:v,isThinking:T}=r(()=>g(p,h),[p,h]),I=r(()=>v.filter(({kind:e})=>"user"===e).length,[v]),S=m.error?c(m.failedStatus):void 0,{scrollerRef:A,hasUnseenContent:B,handleScroll:R,scrollToEnd:C}=u(r(()=>({messages:p,isThinking:T,failure:S?.kind}),[p,T,S?.kind]),I);return i(f,{children:[i(k,{ref:A,onScroll:R,role:"log","aria-live":"polite",children:[m.isLoaded&&0===v.length&&!h&&!S&&e(w,{children:e(a,{id:"sdk.assistant.thread.greeting",message:"Hi. I can answer questions about this design and change it with you. Tell me what you need."})}),v.map(i=>e(j,{item:i,isActive:h&&i===v.at(-1)},i.id)),T&&e(b,{children:e(a,{id:"sdk.assistant.thread.thinking",message:"Thinking…"})}),S&&i(x,{role:"alert",children:[e("span",{children:n(S.kind).with("notAvailable",()=>e(a,{id:"sdk.assistant.failure.notAvailable",message:"The assistant is not available here."})).with("busy",()=>e(a,{id:"sdk.assistant.failure.busy",message:"The assistant is still working on an earlier message."})).with("unavailable",()=>e(a,{id:"sdk.assistant.failure.unavailable",message:"The assistant is unavailable right now."})).exhaustive()}),S.canRetry&&e(t,{size:"small",variant:"outlined",color:"inherit",onClick:s.reloadThread,children:e(a,{id:"sdk.assistant.failure.retry.label",message:"Try again"})})]})]}),B&&e(y,{size:"small",onClick:C,endIcon:e(l,{name:"CaretDown"}),children:e(a,{id:"sdk.assistant.thread.newReply.label",message:"New reply"})})]})};

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

@@ -1,2 +1,2 @@
 export { AssistantPanel, ASSISTANT_PANEL_SLOT } from './AssistantPanel.js';
-export { AssistantPanelProvider, useAssistantPanel, type AssistantPanelState } from './AssistantPanelProvider.js';
+export { useIsAssistantPanelOpen } from './use-is-assistant-panel-open.js';

package/dist/configurator/ui/assistant/index.js

@@ -1 +1 @@
-export{AssistantPanel,ASSISTANT_PANEL_SLOT}from"./AssistantPanel.js";export{AssistantPanelProvider,useAssistantPanel}from"./AssistantPanelProvider.js";
+export{AssistantPanel,ASSISTANT_PANEL_SLOT}from"./AssistantPanel.js";export{useIsAssistantPanelOpen}from"./use-is-assistant-panel-open.js";

package/dist/configurator/ui/assistant/thread-items.d.ts

@@ -1,4 +1,4 @@
-import type { UIMessage } from '@tanstack/ai-react';
+import type { UIMessage } from '@tanstack/ai-client';
 import { type AssistantToolChip } from './tool-chip.js';
 /** A tool call of the thread, with what its chip shows and what a click on the chip logs. */
 export interface AssistantToolItem {

package/dist/configurator/ui/assistant/use-is-assistant-panel-open.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether the assistant panel is shown: it was opened and the application spec still has the
+ * `assistant` section, which editor hot reload can take away under an open panel.
+ */
+export declare const useIsAssistantPanelOpen: () => boolean;

package/dist/configurator/ui/assistant/use-is-assistant-panel-open.js

@@ -0,0 +1 @@
+import{useEagerObservableSelector as e,useSpecAssistant as n}from"#package/react-sdk";import{useConfigurator as t}from"../../application-runtime/index.js";export const useIsAssistantPanelOpen=()=>{let{assistantSystem:p}=t(),r=n();return e(p.panel$,e=>e.open,[])&&null!=r};

package/dist/configurator/ui/configurator-layout/universal/DesktopLayout.js

@@ -1,4 +1,4 @@
-import{jsx as a,jsxs as t,Fragment as o}from"react/jsx-runtime";import{keyframes as e,paperClasses as r,snackbarClasses as d,styled as i,useTheme as n,useThemeProps as s}from"@mui/material";import{AnimatePresence as l,motion as p}from"motion/react";import{useCallback as b,useRef as u}from"react";import{useAccessService as c,useIsFullscreenActive as m}from"#package/react-sdk";import{attrf as h,commonStyles as y,numToPx as g,useInvalidateScrollTimeline as f,useIsEmpty as x,useResponsive as k}from"#package/ui-sdk";import{usePreview as v}from"../../../configurator-context/index.js";import{ASSISTANT_PANEL_SLOT as S,AssistantPanel as E,useAssistantPanel as w}from"../../assistant/index.js";import{LayoutSlots as R}from"../slots/index.js";import{DesktopPreview as $}from"./DesktopPreview.js";import{useSceneSafeArea as B}from"./use-scene-safe-area.js";let C="PhxDesktopSidebar",D="minimalist",T="split",I="visible",A="hidden",P="assistant",F={Root:i("div",{name:C,slot:"root",shouldForwardProp:a=>"ownerState"!==a})(({ownerState:a})=>[`
+import{jsx as a,jsxs as t,Fragment as o}from"react/jsx-runtime";import{keyframes as e,paperClasses as r,snackbarClasses as d,styled as i,useTheme as n,useThemeProps as s}from"@mui/material";import{AnimatePresence as l,motion as p}from"motion/react";import{useCallback as b,useRef as u}from"react";import{useAccessService as c,useIsFullscreenActive as m}from"#package/react-sdk";import{attrf as h,commonStyles as y,numToPx as g,useInvalidateScrollTimeline as f,useIsEmpty as x,useResponsive as k}from"#package/ui-sdk";import{usePreview as v}from"../../../configurator-context/index.js";import{ASSISTANT_PANEL_SLOT as S,AssistantPanel as E,useIsAssistantPanelOpen as w}from"../../assistant/index.js";import{LayoutSlots as R}from"../slots/index.js";import{DesktopPreview as $}from"./DesktopPreview.js";import{useSceneSafeArea as B}from"./use-scene-safe-area.js";let C="PhxDesktopSidebar",D="minimalist",T="split",I="visible",A="hidden",P="assistant",F={Root:i("div",{name:C,slot:"root",shouldForwardProp:a=>"ownerState"!==a})(({ownerState:a})=>[`
       --phx-sidebar-background: ${a.background};
       --phx-sidebar-border: ${a.border};
       --phx-sidebar-filter: ${a.filter};
@@ -46,4 +46,4 @@ import{jsx as a,jsxs as t,Fragment as o}from"react/jsx-runtime";import{keyframes
       180deg,
       hsl(from black h s l / 12%),
       hsl(from black h s l / 0%) 8px
-    )`}=s({props:{},name:C}),{hasMiniSidebar:N,hasSplitSidebar:V}=R.useSidebarContent(),X=w()?.open??!1,{accessInfo:G}=c(),J=m(),{isPreview:K,isHidden:O}=v(),Q=!O&&!K,U=!J,{setCanvasPadding:Y,setAnimating:Z}=k(),{containerRef:_,safeAreaRef:aa,update:at}=B(Y,N&&!X,Q),ao=b(()=>{Z(!0)},[Z]),ae=b(()=>{Z(!1),at()},[Z,at]),ar=Q&&U,ad=x(e,{disabled:!ar}),ai=x(r,{disabled:!ar});f(r,{disabled:!ar});let an={background:g,border:S,borderRadius:L,filter:W,isHeaderEmpty:ad,isContentEmpty:ai,padding:q,scrollableIndicatorBackground:M,width:y};return a(o,{children:t(l,{mode:"wait",children:[!O&&K&&a($,{},"preview-layout"),Q&&t(z,{layoutId:"ui-layout",layout:!0,ownerState:{sidebarWidth:y},"data-layout":h({state:{initial:!J,fullscreen:J}}),onLayoutAnimationStart:ao,onLayoutAnimationComplete:ae,children:[a(H,{ref:_}),a("header",{"data-layout":"slot[header]",children:a(R.DesktopHeader,{})}),t("main",{"data-layout":"slot[body]",children:[a("div",{"data-layout":"slot[body.top] interactive",children:a(R.DesktopCallToAction,{})}),a("div",{ref:aa,"data-layout":"slot[body.safeSceneArea]"}),t("div",{"data-layout":"slot[body.bottom] interactive",children:[a("div",{"data-layout":"slot[body.toolbar]",children:a(R.DesktopToolbar,{})}),a("div",{"data-layout":"slot[body.toolControls]",children:!J&&a(R.DesktopToolControls,{})}),a("div",{"data-layout":"slot[body.viewControls]",children:a(R.DesktopViewControls,{})}),a("div",{"data-layout":"slot[body.logo]",children:a(R.DesktopPoweredBy,{})}),a("div",{"data-layout":"slot[body.sideEffects]",children:a(R.DesktopSnackbarsRoot,{})})]})]}),a("aside",{"data-layout":"slot[sidebar]",children:t(F.Root,{ownerState:an,"data-sidebar":h({variant:{[`${D}`]:N,[`${T}`]:V},state:{[`${I}`]:U,[`${A}`]:!U,[`${P}`]:X}}),inert:U?void 0:"",children:[a(F.Tabs,{ownerState:an,"data-sidebar":"slot[tabs]",children:a(R.DesktopSidebarTabs,{})}),a(F.Header,{ref:e,ownerState:an,"data-sidebar":"slot[header]",children:a(R.DesktopSidebarBackButton,{})}),a(F.Body,{ownerState:an,"data-sidebar":"slot[body]",children:a(F.Content,{ref:r,ownerState:an,"data-sidebar":"slot[content]",children:a(R.DesktopSidebarContent,{})})}),a(F.Footer,{ownerState:an,"data-sidebar":"slot[footer]",children:a(R.DesktopSidebarFooter,{})}),a(E,{})]})}),t("footer",{"data-layout":"slot[footer] interactive",children:[G.viewMode&&!J&&a(R.DesktopReadonlyBanner,{}),a(R.DesktopFooter,{})]})]},"interface-layout")]})})};
+    )`}=s({props:{},name:C}),{hasMiniSidebar:N,hasSplitSidebar:V}=R.useSidebarContent(),X=w(),{accessInfo:G}=c(),J=m(),{isPreview:K,isHidden:O}=v(),Q=!O&&!K,U=!J,{setCanvasPadding:Y,setAnimating:Z}=k(),{containerRef:_,safeAreaRef:aa,update:at}=B(Y,N&&!X,Q),ao=b(()=>{Z(!0)},[Z]),ae=b(()=>{Z(!1),at()},[Z,at]),ar=Q&&U,ad=x(e,{disabled:!ar}),ai=x(r,{disabled:!ar});f(r,{disabled:!ar});let an={background:g,border:S,borderRadius:L,filter:W,isHeaderEmpty:ad,isContentEmpty:ai,padding:q,scrollableIndicatorBackground:M,width:y};return a(o,{children:t(l,{mode:"wait",children:[!O&&K&&a($,{},"preview-layout"),Q&&t(z,{layoutId:"ui-layout",layout:!0,ownerState:{sidebarWidth:y},"data-layout":h({state:{initial:!J,fullscreen:J}}),onLayoutAnimationStart:ao,onLayoutAnimationComplete:ae,children:[a(H,{ref:_}),a("header",{"data-layout":"slot[header]",children:a(R.DesktopHeader,{})}),t("main",{"data-layout":"slot[body]",children:[a("div",{"data-layout":"slot[body.top] interactive",children:a(R.DesktopCallToAction,{})}),a("div",{ref:aa,"data-layout":"slot[body.safeSceneArea]"}),t("div",{"data-layout":"slot[body.bottom] interactive",children:[a("div",{"data-layout":"slot[body.toolbar]",children:a(R.DesktopToolbar,{})}),a("div",{"data-layout":"slot[body.toolControls]",children:!J&&a(R.DesktopToolControls,{})}),a("div",{"data-layout":"slot[body.viewControls]",children:a(R.DesktopViewControls,{})}),a("div",{"data-layout":"slot[body.logo]",children:a(R.DesktopPoweredBy,{})}),a("div",{"data-layout":"slot[body.sideEffects]",children:a(R.DesktopSnackbarsRoot,{})})]})]}),a("aside",{"data-layout":"slot[sidebar]",children:t(F.Root,{ownerState:an,"data-sidebar":h({variant:{[`${D}`]:N,[`${T}`]:V},state:{[`${I}`]:U,[`${A}`]:!U,[`${P}`]:X}}),inert:U?void 0:"",children:[a(F.Tabs,{ownerState:an,"data-sidebar":"slot[tabs]",children:a(R.DesktopSidebarTabs,{})}),a(F.Header,{ref:e,ownerState:an,"data-sidebar":"slot[header]",children:a(R.DesktopSidebarBackButton,{})}),a(F.Body,{ownerState:an,"data-sidebar":"slot[body]",children:a(F.Content,{ref:r,ownerState:an,"data-sidebar":"slot[content]",children:a(R.DesktopSidebarContent,{})})}),a(F.Footer,{ownerState:an,"data-sidebar":"slot[footer]",children:a(R.DesktopSidebarFooter,{})}),a(E,{})]})}),t("footer",{"data-layout":"slot[footer] interactive",children:[G.viewMode&&!J&&a(R.DesktopReadonlyBanner,{}),a(R.DesktopFooter,{})]})]},"interface-layout")]})})};

package/dist/configurator/ui/configurator-layout/universal/Layout.js

@@ -1 +1 @@
-import{jsx as r,jsxs as s,Fragment as o}from"react/jsx-runtime";import{useResponsive as t}from"#package/ui-sdk";import{AssistantPanelProvider as e}from"../../assistant/index.js";import{LayoutSlots as a}from"../slots/index.js";import{DesktopLayout as i}from"./DesktopLayout.js";import{MobileLayout as m}from"./MobileLayout.js";export const Layout=()=>{let{isDesktop:n}=t();return s(o,{children:[r(a.Services,{}),r(a.SharedCanvas,{}),r(e,{children:n?r(i,{}):r(m,{})})]})};
+import{jsx as r,jsxs as o,Fragment as s}from"react/jsx-runtime";import{useResponsive as t}from"#package/ui-sdk";import{LayoutSlots as e}from"../slots/index.js";import{DesktopLayout as a}from"./DesktopLayout.js";import{MobileLayout as m}from"./MobileLayout.js";export const Layout=()=>{let{isDesktop:i}=t();return o(s,{children:[r(e.Services,{}),r(e.SharedCanvas,{}),i?r(a,{}):r(m,{})]})};

package/dist/configurator/ui/configurator-layout/universal/MobileLayout.js

@@ -1,11 +1,11 @@
-import{jsx as t,jsxs as a,Fragment as e}from"react/jsx-runtime";import{snackbarClasses as o,styled as i,useTheme as r,useThemeProps as n}from"@mui/material";import d from"lodash/noop.js";import{AnimatePresence as s}from"motion/react";import{useRef as l}from"react";import{useAccessService as m,useIsFullscreenActive as c}from"#package/react-sdk";import{attrf as p,commonStyles as u,numToPx as b,useIsEmpty as h,useResponsive as g,useViewportSize as f}from"#package/ui-sdk";import{usePreview as y}from"../../../configurator-context/index.js";import{ASSISTANT_PANEL_SLOT as x,AssistantPanel as v,useAssistantPanel as w}from"../../assistant/index.js";import{LayoutSlots as S}from"../slots/index.js";import{MobileHeader as $}from"../slots/slots.js";import{MobilePreview as k}from"./MobilePreview.js";import{useSceneSafeArea as C}from"./use-scene-safe-area.js";let F="visible",M="hidden",T=i("div",{name:"PhxMobileHeader",slot:"root"})(({theme:{spacing:t}})=>({...u.transition.fadeInFrom,alignItems:"center",display:"flex",gap:t(1),justifyContent:"space-between",position:"relative","@container style(--inspect: on)":{background:"hsl(from tomato h s l / 50%)"},'[data-header*="slot"]':{display:"flex",gap:t(2),"& > *":{pointerEvents:"auto"}},'[data-header="slot[center]"]':{display:"grid",inset:0,placeItems:"center",position:"absolute"},[`&[data-header*="${F}"]`]:{opacity:1,transitionDuration:"200ms, 300ms",transitionTimingFunction:"linear, ease-out",translate:"0 0"},[`&[data-header*="${M}"]`]:{opacity:0,transitionDuration:"100ms, 100ms",transitionTimingFunction:"linear, ease-in",translate:"0 -60%"}})),I="visible",R="hidden",B=i("div",{name:"PhxMobileControls",slot:"root"})(({theme:{spacing:t}})=>({alignItems:"end",display:"flex",position:"relative","@container style(--inspect: on)":{background:"hsl(from tomato h s l / 50%)"},'[data-controls*="slot"]':{"& > *":{pointerEvents:"auto"}},'[data-controls="slot[toolControls]"]':{...u.transition.fadeInFrom,"&:not(:empty)":{marginInlineEnd:t(2)},"& > *":{...u.transition.fadeIn,transitionDelay:"300ms",transitionDuration:"300ms"}},'[data-controls="slot[viewControls]"]':{...u.transition.fadeInFrom,marginInlineStart:"auto"},'[data-controls="slot[toolbar]"]':{"&:not(:empty)":{marginInlineStart:t(2)}},[`&[data-controls*="${I}"]`]:{'[data-controls="slot[toolControls]"], [data-controls="slot[viewControls]"]':{opacity:1,transitionDuration:"200ms, 300ms",transitionTimingFunction:"linear, ease-out",translate:"0 0"}},[`&[data-controls*="${R}"]`]:{'[data-controls="slot[toolControls]"], [data-controls="slot[viewControls]"]':{opacity:0,transitionDuration:"100ms, 100ms",transitionTimingFunction:"linear, ease-in",translate:"0 60%"}}})),E="PhxMobileSidebar",P="visible",D="hidden",j="assistant",A={Root:i("div",{name:E,slot:"root",shouldForwardProp:t=>"ownerState"!==t})(({ownerState:t})=>[`
+import{jsx as t,jsxs as a,Fragment as e}from"react/jsx-runtime";import{snackbarClasses as o,styled as i,useTheme as r,useThemeProps as n}from"@mui/material";import d from"lodash/noop.js";import{AnimatePresence as s}from"motion/react";import{useRef as l}from"react";import{useAccessService as m,useEagerObservableSelector as c,useIsFullscreenActive as p}from"#package/react-sdk";import{attrf as u,commonStyles as b,numToPx as h,useIsEmpty as g,useResponsive as f,useViewportSize as y}from"#package/ui-sdk";import{useConfigurator as x}from"../../../application-runtime/index.js";import{usePreview as v}from"../../../configurator-context/index.js";import{ASSISTANT_PANEL_SLOT as w,AssistantPanel as S,useIsAssistantPanelOpen as $}from"../../assistant/index.js";import{LayoutSlots as k}from"../slots/index.js";import{MobileHeader as C}from"../slots/slots.js";import{MobilePreview as F}from"./MobilePreview.js";import{useSceneSafeArea as M}from"./use-scene-safe-area.js";let T="visible",I="hidden",R=i("div",{name:"PhxMobileHeader",slot:"root"})(({theme:{spacing:t}})=>({...b.transition.fadeInFrom,alignItems:"center",display:"flex",gap:t(1),justifyContent:"space-between",position:"relative","@container style(--inspect: on)":{background:"hsl(from tomato h s l / 50%)"},'[data-header*="slot"]':{display:"flex",gap:t(2),"& > *":{pointerEvents:"auto"}},'[data-header="slot[center]"]':{display:"grid",inset:0,placeItems:"center",position:"absolute"},[`&[data-header*="${T}"]`]:{opacity:1,transitionDuration:"200ms, 300ms",transitionTimingFunction:"linear, ease-out",translate:"0 0"},[`&[data-header*="${I}"]`]:{opacity:0,transitionDuration:"100ms, 100ms",transitionTimingFunction:"linear, ease-in",translate:"0 -60%"}})),B="visible",E="hidden",P=i("div",{name:"PhxMobileControls",slot:"root"})(({theme:{spacing:t}})=>({alignItems:"end",display:"flex",position:"relative","@container style(--inspect: on)":{background:"hsl(from tomato h s l / 50%)"},'[data-controls*="slot"]':{"& > *":{pointerEvents:"auto"}},'[data-controls="slot[toolControls]"]':{...b.transition.fadeInFrom,"&:not(:empty)":{marginInlineEnd:t(2)},"& > *":{...b.transition.fadeIn,transitionDelay:"300ms",transitionDuration:"300ms"}},'[data-controls="slot[viewControls]"]':{...b.transition.fadeInFrom,marginInlineStart:"auto"},'[data-controls="slot[toolbar]"]':{"&:not(:empty)":{marginInlineStart:t(2)}},[`&[data-controls*="${B}"]`]:{'[data-controls="slot[toolControls]"], [data-controls="slot[viewControls]"]':{opacity:1,transitionDuration:"200ms, 300ms",transitionTimingFunction:"linear, ease-out",translate:"0 0"}},[`&[data-controls*="${E}"]`]:{'[data-controls="slot[toolControls]"], [data-controls="slot[viewControls]"]':{opacity:0,transitionDuration:"100ms, 100ms",transitionTimingFunction:"linear, ease-in",translate:"0 60%"}}})),D="PhxMobileSidebar",j="visible",A="hidden",z="assistant",H={Root:i("div",{name:D,slot:"root",shouldForwardProp:t=>"ownerState"!==t})(({ownerState:t})=>[`
       --phx-sidebar-background: ${t.background};
       --phx-sidebar-padding: ${t.padding};
       --phx-sidebar-radius: ${t.borderRadius}px;
-    `,{...u.transition.fadeInFrom,background:"var(--phx-sidebar-background)",borderStartStartRadius:"var(--phx-sidebar-radius)",borderStartEndRadius:"var(--phx-sidebar-radius)",display:"grid",gridTemplateColumns:"minmax(0, 1fr)",gridTemplateRows:"min-content minmax(0, 1fr) min-content",position:"relative","& > *":{pointerEvents:"auto"},"@container style(--inspect: on)":{background:"hsl(from gold h s l / 50%)"},'&:has([data-sidebar*="slot[content]"])':{...t.isContentEmpty&&{"--phx-sidebar-radius":0,'[data-sidebar*="slot[header]"]':{paddingBlock:0,"& > *":{display:"none"}}}},[`&[data-sidebar*="${P}"]`]:{opacity:1,transitionDuration:"200ms, 300ms",transitionTimingFunction:"linear, ease-out",translate:"0 0"},[`&[data-sidebar*="${D}"]`]:{opacity:0,transitionDuration:"100ms, 100ms",transitionTimingFunction:"linear, ease-in",translate:"0 60%"},[`&[data-sidebar*="${j}"] > :not([data-sidebar="${x}"])`]:{visibility:"hidden"}}]),Header:i("header",{name:E,slot:"header",shouldForwardProp:t=>"ownerState"!==t})(({theme:{spacing:t}})=>({alignItems:"center",borderStartStartRadius:"inherit",borderStartEndRadius:"inherit",display:"grid",gap:t(1),gridTemplateColumns:"repeat(2, minmax(0, 1fr))",paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"var(--phx-sidebar-padding)","& > *":{...u.transition.fadeIn,transitionDelay:"100ms",transitionDuration:"300ms"},'[data-sidebar="slot[header.start]"]':{},'[data-sidebar="slot[header.end]"]':{justifySelf:"end"}})),Body:i("div",{name:E,slot:"body",shouldForwardProp:t=>"ownerState"!==t})({display:"grid",gridTemplateRows:"minmax(0, 1fr)"}),Content:i("div",{name:E,slot:"content",shouldForwardProp:t=>"ownerState"!==t})(({theme:{spacing:t}})=>({...u.layout.normalizeScrollableContainer,display:"grid",gap:t(2),gridAutoRows:"min-content",paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"var(--phx-sidebar-padding)","&:empty":{paddingBlock:0}})),Tabs:i("div",{name:E,slot:"tabs",shouldForwardProp:t=>"ownerState"!==t})(({theme:{palette:t}})=>({borderBlockStart:`1px solid ${t.divider}`,paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"calc(var(--phx-sidebar-padding) * 0.75)","&:is(:empty)":{border:0,padding:0}})),Footer:i("footer",{name:E,slot:"footer",shouldForwardProp:t=>"ownerState"!==t})(({theme:{palette:t}})=>({borderBlockStart:`1px solid ${t.divider}`,paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"var(--phx-sidebar-padding)","&:is(:empty)":{borderColor:"transparent",paddingBlock:0}}))};export const PhxMobileLayoutName="PhxMobileLayout";let z="initial",H="fullscreen",L="min(480px, 50cqb)",q=["auto","min-content","max-content","fit-content"],N=i("div",{name:"PhxMobileLayout",slot:"root",shouldForwardProp:t=>"ownerState"!==t})(({ownerState:t,theme:{spacing:a}})=>[`
+    `,{...b.transition.fadeInFrom,background:"var(--phx-sidebar-background)",borderStartStartRadius:"var(--phx-sidebar-radius)",borderStartEndRadius:"var(--phx-sidebar-radius)",display:"grid",gridTemplateColumns:"minmax(0, 1fr)",gridTemplateRows:"min-content minmax(0, 1fr) min-content",position:"relative","& > *":{pointerEvents:"auto"},"@container style(--inspect: on)":{background:"hsl(from gold h s l / 50%)"},'&:has([data-sidebar*="slot[content]"])':{...t.isContentEmpty&&{"--phx-sidebar-radius":0,'[data-sidebar*="slot[header]"]':{paddingBlock:0,"& > *":{display:"none"}}}},[`&[data-sidebar*="${j}"]`]:{opacity:1,transitionDuration:"200ms, 300ms",transitionTimingFunction:"linear, ease-out",translate:"0 0"},[`&[data-sidebar*="${A}"]`]:{opacity:0,transitionDuration:"100ms, 100ms",transitionTimingFunction:"linear, ease-in",translate:"0 60%"},[`&[data-sidebar*="${z}"] > :not([data-sidebar="${w}"])`]:{visibility:"hidden"}}]),Header:i("header",{name:D,slot:"header",shouldForwardProp:t=>"ownerState"!==t})(({theme:{spacing:t}})=>({alignItems:"center",borderStartStartRadius:"inherit",borderStartEndRadius:"inherit",display:"grid",gap:t(1),gridTemplateColumns:"repeat(2, minmax(0, 1fr))",paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"var(--phx-sidebar-padding)","& > *":{...b.transition.fadeIn,transitionDelay:"100ms",transitionDuration:"300ms"},'[data-sidebar="slot[header.start]"]':{},'[data-sidebar="slot[header.end]"]':{justifySelf:"end"}})),Body:i("div",{name:D,slot:"body",shouldForwardProp:t=>"ownerState"!==t})({display:"grid",gridTemplateRows:"minmax(0, 1fr)"}),Content:i("div",{name:D,slot:"content",shouldForwardProp:t=>"ownerState"!==t})(({theme:{spacing:t}})=>({...b.layout.normalizeScrollableContainer,display:"grid",gap:t(2),gridAutoRows:"min-content",paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"var(--phx-sidebar-padding)","&:empty":{paddingBlock:0}})),Tabs:i("div",{name:D,slot:"tabs",shouldForwardProp:t=>"ownerState"!==t})(({theme:{palette:t}})=>({borderBlockStart:`1px solid ${t.divider}`,paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"calc(var(--phx-sidebar-padding) * 0.75)","&:is(:empty)":{border:0,padding:0}})),Footer:i("footer",{name:D,slot:"footer",shouldForwardProp:t=>"ownerState"!==t})(({theme:{palette:t}})=>({borderBlockStart:`1px solid ${t.divider}`,paddingBlock:"calc(var(--phx-sidebar-padding) * 0.5)",paddingInline:"var(--phx-sidebar-padding)","&:is(:empty)":{borderColor:"transparent",paddingBlock:0}}))};export const PhxMobileLayoutName="PhxMobileLayout";let L="initial",q="fullscreen",N="min(480px, 50cqb)",V=["auto","min-content","max-content","fit-content"],G=i("div",{name:"PhxMobileLayout",slot:"root",shouldForwardProp:t=>"ownerState"!==t})(({ownerState:t,theme:{spacing:a}})=>[`
     --inspect: off;  // 🕹️ inspection mode toggle
 
-    --phx-layout-sidebar-track-size: ${b(t.sidebarHeight)};
+    --phx-layout-sidebar-track-size: ${h(t.sidebarHeight)};
     --phx-layout-gutter: ${a(2)};
   `,{display:"grid",gridTemplateColumns:`
       [full-start]
@@ -39,4 +39,4 @@ import{jsx as t,jsxs as a,Fragment as e}from"react/jsx-runtime";import{snackbarC
         [footer-end]
         var(--phx-layout-gutter)
         [full-end]
-      `},'[data-layout*="slot[body.header]"]':{gridArea:"header-start / main-start / header-end / main-end"},'[data-layout*="slot[body.footer]"]':{gridArea:"footer-start / main-start / footer-end / main-end",position:"relative"},'[data-layout*="slot[body.safeSceneArea]"]':{gridArea:"full","@container style(--inspect: on)":{background:"hsl(from lime h s l / 50%)"}},'[data-layout="slot[body.sideEffects]"]':{insetBlockEnd:`calc(100% + ${a(2)})`,position:"absolute"},'[data-layout*="slot[sidebar]"]':{display:"grid",gridArea:"sidebar-start / full-start / sidebar-end / full-end",gridTemplateColumns:"minmax(0, 1fr)",gridTemplateRows:"minmax(0, auto)"},'[data-layout*="slot[footer]"]':{gridArea:"footer-start / full-start / footer-end / full-end",zIndex:1},'&:has([data-sidebar*="slot[content]"])':{...t.isContentEmpty&&{"--phx-layout-sidebar-track-size":"min-content"}},[`&[data-layout*="${z}"]`]:{transitionDelay:"200ms",transitionDuration:"300ms"},[`&[data-layout*="${H}"]`]:{transitionDelay:"0ms",transitionDuration:"300ms"},[`&:has([data-sidebar*="${D}"])[class]`]:{"--phx-layout-sidebar-track-size":0}},null!=t.assistantFocusHeight&&{'[data-layout*="slot[sidebar]"]':{alignSelf:"start",blockSize:`min(100%, ${t.assistantFocusHeight}px)`,gridRow:"full-start / full-end",zIndex:2}}]),V=i("div")({gridArea:"1 / 1 / -1 / -1"}),G=t=>({inert:t?"":void 0});export const MobileLayout=()=>{let o=l(null),{palette:i,shape:u,spacing:b}=r(),{sidebarHeight:x=L}=n({props:{},name:"PhxMobileLayout"}),{background:J=i.background.paper,borderRadius:K=u.sidebarBorderRadius??u.borderRadius,padding:O=b(2)}=n({props:{},name:E}),{accessInfo:Q}=m(),U=c(),{isPreview:W,isHidden:X}=y(),Y=!X&&!W,Z=!U&&Y,_=!U&&Y,tt=!U,{setCanvasPadding:ta}=g(),{containerRef:te,safeAreaRef:to}=C(Y?ta:d,!1),ti=h(o,{disabled:!tt}),tr=w(),tn=tr?.open??!1,td=tn&&tt&&(tr?.isInputFocused??!1),ts=f(),tl=ti&&!tn,tm={isContentEmpty:tl,sidebarHeight:tn?q.includes(x)?L:x:x,assistantFocusHeight:td?ts?.[1]:void 0},tc={background:J,borderRadius:K,padding:O,isContentEmpty:tl};return a(e,{children:[t(s,{initial:!1,children:!X&&W&&t(k,{})}),a(N,{ownerState:tm,"data-layout":p({state:{[`${z}`]:!U,[`${H}`]:U}}),...G(!Y),children:[t(V,{ref:te}),t("div",{"data-layout":"slot[sideEffects]",children:t(S.MobileSnackbarsRoot,{})}),a("main",{"data-layout":"slot[body]",children:[t("header",{"data-layout":"slot[body.header]",children:a(T,{"data-header":p({state:{[`${F}`]:Z,[`${M}`]:!Z}}),...G(!Z),children:[t("div",{"data-header":"slot[start]",children:t($,{})}),t("div",{"data-header":"slot[center]",children:t(S.MobileCallToAction,{})}),a("div",{"data-header":"slot[end]",children:[Q.viewMode&&!U&&t(S.MobileReadonlyBanner,{}),t(S.MobileHamburgerMenu,{})]})]})}),t("div",{ref:to,"data-layout":"slot[body.safeSceneArea]"}),t("div",{"data-layout":"slot[body.footer] interactive",children:a(B,{"data-controls":p({state:{[`${I}`]:_,[`${R}`]:!_}}),children:[t("div",{"data-controls":"slot[toolControls]",...G(!_),children:t(S.MobileToolControls,{})}),t("div",{"data-controls":"slot[viewControls]",...G(!_),children:t(S.MobileViewControls,{})}),t("div",{"data-controls":"slot[toolbar]",children:Y&&t(S.MobileToolbar,{})})]})})]}),t("aside",{"data-layout":"slot[sidebar]",children:a(A.Root,{ownerState:tc,"data-sidebar":p({state:{[`${P}`]:tt,[`${D}`]:!tt,[`${j}`]:tn}}),...G(!tt),children:[a(A.Header,{ownerState:tc,"data-sidebar":"slot[header]",children:[t("div",{"data-sidebar":"slot[header.start]",children:t(S.MobileSidebarBackButton,{})}),t("div",{"data-sidebar":"slot[header.end]",children:t(S.MobilePoweredBy,{})})]}),t(A.Body,{ownerState:tc,"data-sidebar":"slot[body]",children:t(A.Content,{ref:o,ownerState:tc,"data-sidebar":"slot[content]",children:t(S.MobileSidebarContent,{})})}),t(A.Tabs,{ownerState:tc,"data-sidebar":"slot[tabs]",children:t(S.MobileTabs,{})}),t(A.Footer,{ownerState:tc,"data-sidebar":"slot[footer]",children:t(S.MobileSidebarFooter,{})}),t(v,{})]})}),t("footer",{"data-layout":"slot[footer] interactive",children:t(S.MobileFooter,{})})]})]})};
+      `},'[data-layout*="slot[body.header]"]':{gridArea:"header-start / main-start / header-end / main-end"},'[data-layout*="slot[body.footer]"]':{gridArea:"footer-start / main-start / footer-end / main-end",position:"relative"},'[data-layout*="slot[body.safeSceneArea]"]':{gridArea:"full","@container style(--inspect: on)":{background:"hsl(from lime h s l / 50%)"}},'[data-layout="slot[body.sideEffects]"]':{insetBlockEnd:`calc(100% + ${a(2)})`,position:"absolute"},'[data-layout*="slot[sidebar]"]':{display:"grid",gridArea:"sidebar-start / full-start / sidebar-end / full-end",gridTemplateColumns:"minmax(0, 1fr)",gridTemplateRows:"minmax(0, auto)"},'[data-layout*="slot[footer]"]':{gridArea:"footer-start / full-start / footer-end / full-end",zIndex:1},'&:has([data-sidebar*="slot[content]"])':{...t.isContentEmpty&&{"--phx-layout-sidebar-track-size":"min-content"}},[`&[data-layout*="${L}"]`]:{transitionDelay:"200ms",transitionDuration:"300ms"},[`&[data-layout*="${q}"]`]:{transitionDelay:"0ms",transitionDuration:"300ms"},[`&:has([data-sidebar*="${A}"])[class]`]:{"--phx-layout-sidebar-track-size":0}},null!=t.assistantFocusHeight&&{'[data-layout*="slot[sidebar]"]':{alignSelf:"start",blockSize:`min(100%, ${t.assistantFocusHeight}px)`,gridRow:"full-start / full-end",zIndex:2}}]),J=i("div")({gridArea:"1 / 1 / -1 / -1"}),K=t=>({inert:t?"":void 0});export const MobileLayout=()=>{let o=l(null),{palette:i,shape:b,spacing:h}=r(),{sidebarHeight:w=N}=n({props:{},name:"PhxMobileLayout"}),{background:O=i.background.paper,borderRadius:Q=b.sidebarBorderRadius??b.borderRadius,padding:U=h(2)}=n({props:{},name:D}),{accessInfo:W}=m(),X=p(),{isPreview:Y,isHidden:Z}=v(),_=!Z&&!Y,tt=!X&&_,ta=!X&&_,te=!X,{setCanvasPadding:to}=f(),{containerRef:ti,safeAreaRef:tr}=M(_?to:d,!1),tn=g(o,{disabled:!te}),{assistantSystem:td}=x(),ts=$(),tl=c(td.panel$,t=>t.isInputFocused,[]),tm=ts&&te&&tl,tc=y(tm),tp=tn&&!ts,tu={isContentEmpty:tp,sidebarHeight:ts?V.includes(w)?N:w:w,assistantFocusHeight:tm?tc?.[1]:void 0},tb={background:O,borderRadius:Q,padding:U,isContentEmpty:tp};return a(e,{children:[t(s,{initial:!1,children:!Z&&Y&&t(F,{})}),a(G,{ownerState:tu,"data-layout":u({state:{[`${L}`]:!X,[`${q}`]:X}}),...K(!_),children:[t(J,{ref:ti}),t("div",{"data-layout":"slot[sideEffects]",children:t(k.MobileSnackbarsRoot,{})}),a("main",{"data-layout":"slot[body]",children:[t("header",{"data-layout":"slot[body.header]",children:a(R,{"data-header":u({state:{[`${T}`]:tt,[`${I}`]:!tt}}),...K(!tt),children:[t("div",{"data-header":"slot[start]",children:t(C,{})}),t("div",{"data-header":"slot[center]",children:t(k.MobileCallToAction,{})}),a("div",{"data-header":"slot[end]",children:[W.viewMode&&!X&&t(k.MobileReadonlyBanner,{}),t(k.MobileHamburgerMenu,{})]})]})}),t("div",{ref:tr,"data-layout":"slot[body.safeSceneArea]"}),t("div",{"data-layout":"slot[body.footer] interactive",children:a(P,{"data-controls":u({state:{[`${B}`]:ta,[`${E}`]:!ta}}),children:[t("div",{"data-controls":"slot[toolControls]",...K(!ta),children:t(k.MobileToolControls,{})}),t("div",{"data-controls":"slot[viewControls]",...K(!ta),children:t(k.MobileViewControls,{})}),t("div",{"data-controls":"slot[toolbar]",children:_&&t(k.MobileToolbar,{})})]})})]}),t("aside",{"data-layout":"slot[sidebar]",children:a(H.Root,{ownerState:tb,"data-sidebar":u({state:{[`${j}`]:te,[`${A}`]:!te,[`${z}`]:ts}}),...K(!te),children:[a(H.Header,{ownerState:tb,"data-sidebar":"slot[header]",children:[t("div",{"data-sidebar":"slot[header.start]",children:t(k.MobileSidebarBackButton,{})}),t("div",{"data-sidebar":"slot[header.end]",children:t(k.MobilePoweredBy,{})})]}),t(H.Body,{ownerState:tb,"data-sidebar":"slot[body]",children:t(H.Content,{ref:o,ownerState:tb,"data-sidebar":"slot[content]",children:t(k.MobileSidebarContent,{})})}),t(H.Tabs,{ownerState:tb,"data-sidebar":"slot[tabs]",children:t(k.MobileTabs,{})}),t(H.Footer,{ownerState:tb,"data-sidebar":"slot[footer]",children:t(k.MobileSidebarFooter,{})}),t(S,{})]})}),t("footer",{"data-layout":"slot[footer] interactive",children:t(k.MobileFooter,{})})]})]})};

package/dist/configurator/ui/legacy/mobile-controls/MobileControls.d.ts

@@ -57,6 +57,6 @@ declare const ResponsiveNavigation: <VALUE extends string, ENTITY_ID extends Dom
  */
 export declare const MobileControls: {
     Navigation: typeof ResponsiveNavigation;
-    ViewOnlyMode: (inProps: import("../../../../ui-sdk/components/mobile-controls/MobileControls").ViewOnlyModeProps & import("#package/ui-sdk").MobileControlsThemeableProps) => import("react/jsx-runtime").JSX.Element;
+    ViewOnlyMode: (inProps: import("#package/ui-sdk").ViewOnlyModeProps & import("#package/ui-sdk").MobileControlsThemeableProps) => import("react/jsx-runtime").JSX.Element;
 };
 export {};

package/dist/configurator/ui/phoenix-layout-elements/AssistantToolbarButton.d.ts

@@ -1,6 +1,6 @@
 /**
- * Opens and closes the assistant panel. It renders nothing where there is no panel to open: in a
- * project without an assistant, or in a layout that does not carry the panel.
+ * Opens and closes the assistant panel. It renders nothing in a project without an assistant. A
+ * layout that lists the button is expected to carry the panel; the button does not check for it.
  */
 export declare const AssistantToolbarButton: import("react").FunctionComponent<{
     readonly showTitle?: boolean;

package/dist/configurator/ui/phoenix-layout-elements/AssistantToolbarButton.js

@@ -1 +1 @@
-import{jsx as t}from"react/jsx-runtime";import{Badge as r}from"@mui/material";import{memo as s,useCallback as a}from"react";import{assistantToolbarButtonSchema as o,createPhoenixLayoutElement as e}from"#package/domain";import{useLocalizable as i}from"#package/react-sdk";import{DesktopToolbar as n,PhxIcon as m,useResponsive as l}from"#package/ui-sdk";import{useAssistantPanel as p}from"../assistant/index.js";let c={id:"sdk.assistant.toolbarButton.label",message:"Assistant"};export const AssistantToolbarButton=e({schema:o,component:s(s=>{let{icon:o,showTitle:e=!0}=s,d=p(),u=i(c),{isPhone:k,isTablet:f}=l(),A=d?.open??!1,b=d?.setOpen,g=a(()=>{b?.(!A)},[A,b]);return d?t(n.Button,{title:u,onClick:g,showTitle:e&&!k&&!f,"aria-pressed":A,sx:{'&[aria-pressed="true"]':{backgroundColor:"action.selected"}},children:t(r,{color:"primary",variant:"dot",overlap:"circular",invisible:!d.hasUnreadReply,children:t(m,{name:o??(A?"CustomAiAssistantBold":"CustomAiAssistant")})})}):null})});
+import{jsx as t}from"react/jsx-runtime";import{Badge as r}from"@mui/material";import{memo as o,useCallback as a}from"react";import{assistantToolbarButtonSchema as i,createPhoenixLayoutElement as e}from"#package/domain";import{useEagerObservableValue as s,useLocalizable as n,useSpecAssistant as m}from"#package/react-sdk";import{DesktopToolbar as l,PhxIcon as p,useResponsive as c}from"#package/ui-sdk";import{useConfigurator as d}from"../../application-runtime/index.js";let u={id:"sdk.assistant.toolbarButton.label",message:"Assistant"};export const AssistantToolbarButton=e({schema:i,component:o(o=>{let{icon:i,showTitle:e=!0}=o,{assistantSystem:k}=d(),f=m(),{open:A,hasUnreadReply:b}=s(k.panel$),g=n(u),{isPhone:x,isTablet:h}=c(),B=a(()=>{k.setOpen(!A)},[k,A]);return f?t(l.Button,{title:g,onClick:B,showTitle:e&&!x&&!h,"aria-pressed":A,sx:{'&[aria-pressed="true"]':{backgroundColor:"action.selected"}},children:t(r,{color:"primary",variant:"dot",overlap:"circular",invisible:!b,children:t(p,{name:i??(A?"CustomAiAssistantBold":"CustomAiAssistant")})})}):null})});

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-09T15:12:45.633Z",
+  "generatedAt": "2026-10-12T13:11:59.716Z",
   "categories": [
     {
       "name": "Phoenix",

package/dist/docs/layouts/toolbar.mdx

@@ -84,7 +84,9 @@ Phoenix provides built-in toolbar buttons for common operations:
 - `assistantToolbarButton` - Open and close the built-in assistant panel. It renders only in a project whose
   application spec has an `assistant` section. `props.showTitle` defaults to `true`; the label shows on a
   desktop-sized layout only. The default toolbar includes it, in a group of its own, when the spec has an
-  `assistant` section.
+  `assistant` section. Only the universal layout carries the panel, and the button does not hide itself in a
+  layout without it. A custom layout that renders the toolbar therefore defines a `toolbar` component without the
+  button, because the default toolbar would add it.
 
 ### Mobile Toolbar Configuration
 

package/dist/docs/other-features/side-effects.mdx

@@ -102,6 +102,32 @@ configuratorBuilder
   .buildConfig()
 ```
 
+### Hints and the AI assistant
+
+In a configurator with the AI assistant, the assistant is told the same hints: they arrive as
+`sideEffects` with the result of its changes and in the dry-runs of recipes and options, so it can
+tell the user what else happened. The hints also explain what the user changed between two messages:
+every message carries a change record of the configuration, and each of its lines ends with the hint
+of the last update that touched it, or with the `updateTag` when the update has none. Set `agentHint`
+beside `hint` when the assistant needs different wording, for example with ids or values a snackbar
+would not show:
+
+```ts
+phx.frontend.updates.DomainEntityModification({
+  entityId: oldPlate.id,
+  stateDelta: { finish: validMaterial.finish },
+  updateTag: 'fix.finish',
+  hint: msg`Material finish was adjusted`,
+  agentHint: `The finish of ${oldPlate.id} was changed to ${validMaterial.finish}, the only one this material comes in.`,
+})
+```
+
+- `agentHint` is a plain string, never shown to the user and not localized.
+- `agentHint: null` keeps the wording from the assistant while the user still gets the `hint`: the
+  update is left out of `sideEffects`, and the change record explains its line by the `updateTag`. It
+  does not hide the change itself, which the assistant can always read from the configuration.
+- `agentHint` without a `hint` tells only the assistant.
+
 ## Example
 
 Here you can see the live example!

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

@@ -491,6 +491,85 @@ phoenix screenshot -o preview.png -w 1920 --height 1080
 | `--height`        | `1080`  | Image height in pixels         |
 | `--format` / `-f` | `png`   | Image format (`png` or `jpeg`) |
 
+### `phoenix variants`
+
+Show several options over the configurator and wait for your pick. It is built for coding agents: when a decision is a matter of taste, such as the edge of a table top, how glossy a finish is or where a control sits, the agent writes one file per option, you choose in the browser, and the command hands your answer back to the agent.
+
+```bash
+phoenix variants .phoenix/variants/table-edge --title 'Which edge suits the table?' --description 'Only the edge of the top differs.'
+```
+
+Every `<id>.variant.js` script or `<id>.html` page in the folder is one option, shown in file-name order. Each script edits frontend project files on top of the same captured baseline. Original is always the first choice and restores that baseline. Switching options removes the previous option's edits and applies the selected script; the editor dialog has any number of choices on the left and your already loaded configurator on the right.
+
+```js
+// .phoenix/variants/brand/blue.variant.js
+export const title = 'Blue brand'
+export const description = 'A blue primary colour with the current layout.'
+
+export default ({ read, write, remove }) => {
+  const file = 'src/handlers/theme.ts'
+  write(file, read(file).replace("main: '#E93335'", "main: '#2364aa'"))
+}
+```
+
+`read(path)` always reads the baseline. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Scripts run in the browser and collect edits; Phoenix validates and writes the batch locally. Supported files are YAML under `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants also run on the server, so a script cannot edit them.
+
+For standalone UI or branding proposals, write self-contained HTML files. Each page renders in its own iframe when selected; its `<title>` names the option and `<meta name="description" content="...">` describes it. HTML and scripts may share a set if their file names give distinct option ids.
+
+```html
+<!-- .phoenix/variants/brand/blue.html -->
+<!doctype html>
+<title>Blue studio</title>
+<meta name="description" content="A calm blue identity with generous spacing." />
+<style>
+  body {
+    margin: 0;
+    padding: 40px;
+    background: #f0f5fa;
+    color: #163b66;
+    font-family: sans-serif;
+  }
+</style>
+<h1>Made for your everyday.</h1>
+<button>Design your table</button>
+```
+
+Scripts run once per selection. The completed file batch calls the existing rebuild queue directly, without a separate file-change event stream or a watcher that reapplies the option.
+
+Use script options for controls, layout, brand, lights, visual effects, materials, positions, components, elements and transformers. Changes to the model, schemas, data or deployment settings are rejected before any files are written. Environment files, webhooks, their shared implementation dependencies, dependencies and uploaded assets cannot be overridden. Files connected through symbolic links are also excluded, so restoring the baseline preserves the original files. No server preparation or webhook rebuild runs for a variant transaction.
+
+Picking a script keeps its exact implementation in the project. Picking an HTML page returns the selected proposal for the agent to implement; the page itself changes no project source files. Choosing Original keeps the captured baseline. Users finish by confirming Original or another option. Escape stays available to the configurator, and clicking the backdrop leaves the comparison open. The agent can use `--close` to restore the baseline source files without giving an answer. Phoenix records recovery information on disk and restores interrupted previews at the next `phoenix dev` start. It never overwrites a file edited outside the preview: switching options over such an edit is refused, and when the comparison ends, or is restored at the next start, that file is left as it is with a warning in the dev log while the others are restored. Other source changes made while a comparison is open are rebuilt once it ends.
+
+Answers are held for four seconds with Undo and Send now.
+
+The command prints the outcome as JSON. After `chosen` it removes the folder:
+
+| `status`  | Meaning                                                                                                                                      |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `chosen`  | An option was picked: `choice` is its id, or `null` for Original; `label` is its name.                                                       |
+| `waiting` | The wait ran out. The preview stays open: the same command attaches to it again, and an answer given in between is returned by the next run. |
+| `closed`  | The preview was closed without an answer, by `--close` or by another set of options taking its place. The folder is kept.                    |
+
+| Flag                   | Default                       | Description                                               |
+| ---------------------- | ----------------------------- | --------------------------------------------------------- |
+| `--title` / `-t`       | `Which option do you prefer?` | Question shown above the options                          |
+| `--description` / `-d` | —                             | A line saying what differs between the options            |
+| `--timeout`            | `540`                         | Seconds to wait for the answer                            |
+| `--keep`               | `false`                       | Keep the folder after the answer                          |
+| `--close`              | `false`                       | Close the open preview without an answer; needs no folder |
+| `--port` / `-p`        | `3020`                        | Editor WebSocket port                                     |
+
+Known limits:
+
+- Variant transactions start rebuilding immediately, bypassing the normal file-watcher debounce. Hot reload still needs to parse and apply the updated implementation. There is no wait for UI or scene loading to settle; allow a visible transition to finish before judging or choosing.
+- Only one option is displayed at a time; simultaneous comparison is not supported.
+- For script options and Original, the dialog moves the existing configurator into the preview and returns it on close, preserving the loaded scene, camera and UI state. Opening the dialog starts no second application or initial loading screen. Configuration interactions still change the current configuration; restoring source files does not undo them.
+- Custom scripts are trusted project code. Their file API stages edits; scripts must not make network requests or other side effects.
+- Binary assets, CSS files, locale catalog changes, dependency changes and edits requiring a full application restart are unsupported.
+- Storybook `story-dev` has no variant previews. A project on the legacy pipeline has no variant previews; the command says so and exits.
+
+Generated projects carry the `phoenix-variants` agent skill, which tells coding agents when to offer options, how to write each kind and what to do with your answer.
+
 ## SDK Development
 
 ### `phoenix link`
@@ -603,7 +682,7 @@ SDK-builder workspaces sign the CLI in with a personal API token instead of proj
 
 Signs the CLI in to the SDK-builder workspace `<customer>`:
 
-1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
+1. Opens Studio, where you name the token and approve the sign-in (use `--no-open` to only print the link). Only a super admin of the workspace can open its Studio, so only a super admin can sign the CLI in. The page shows the workspace, your account, the computer the CLI runs on and how long the link still works. The CLI suggests the name `phoenix CLI on <computer>`; change it so you can tell your machines and agents apart later.
 2. Studio sends a one-time code back to the CLI on `127.0.0.1`.
 3. The CLI exchanges the code for a token with the name you approved, and sends the browser back to Studio, which confirms the sign-in.
 
@@ -628,7 +707,7 @@ Revokes the token on the server and removes it from the credentials file. `--reg
 
 ### `phoenix deploy`
 
-Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
+Validates the spec, adds the pnpm settings `phoenix init` writes to `pnpm-workspace.yaml` when they are missing, packs and uploads the project, starts its build on the server and follows it until the configurator is live. Before the upload the server compares the domain model with the deployed one: a model that changed under an already deployed model version is refused with the reason, and needs a new model version and a [migration](?path=/docs/phoenix-migrations--docs). Once the build starts it prints `Follow the build in Studio: <url>`, the build's page in the Studio you signed in through; a sign-in stored by an older CLI has no Studio URL, so sign in again to get the link. After `Your configurator is live at <url>` it prints one line for coding agents, which tells them to offer the run evaluation of the `phoenix-feedback` skill once you have nothing more to build; you can ignore it when you run the command yourself. `--region` or `--serverUrl` selects the server, as for `login`; `--no-wait` returns as soon as the build starts.
 
 ### `phoenix feedback [message]`
 

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

@@ -189,7 +189,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### DO NOT EDIT (Fully Auto-Generated)
 
-- **Everything in `.phoenix/`** - Completely regenerated on each build
+- **Everything in `.phoenix/`** - Completely regenerated on each build. The one exception is `.phoenix/variants/`, where a coding agent writes the option files for `phoenix variants`; a rebuild keeps it
 - `tsconfig.json`, `eslint.config.js`, `prettier.config.js`, `.prettierignore`
 - `.linguirc`, `.nvmrc`
 - `src/locales/**/*.ts` - Compiled from `.po` catalogs
@@ -198,7 +198,7 @@ type CustomMaterial = Phx['AdminModel']['CustomMaterial']
 
 ### Agent Guidance
 
-Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
+Coding agents (Claude Code, Codex, Cursor) read `AGENTS.md` and the Phoenix agent skills. `AGENTS.md` is written once with the build commands, the do-not-edit list and a pointer to the skills; after that it is yours. The `phoenix`, `phoenix-cli`, `phoenix-feedback` and `phoenix-review` skills carry the SDK conventions, CLI tooling and review checklist, and the `phoenix-create-configurator` skill walks the agent from your product documents and assets to a reviewed configurator in five stages. The `phoenix-variants` skill has the agent show you several options over the dev preview when a decision is a matter of taste, and build the one you pick. Phoenix keeps them in step with the installed SDK, including the reference files inside a skill folder. During the internal beta, a project created from a canary build of the SDK gets one more section in the `phoenix` skill: once per conversation the agent checks for a newer canary and, after telling you, updates the project's SDK and runs `phoenix sync`. Other skill folders are never touched.
 
 Projects created by earlier SDK versions had this guidance in `CLAUDE.md`, `.cursor/rules/phoenix.mdc` and `commands/review.md`. Sync removes the SDK block from the first two, keeps your own text around it, deletes a file that held nothing else, and deletes the review commands; use the `phoenix-review` skill instead of `/review`.
 
@@ -316,6 +316,7 @@ project-root/
 │   │   └── builders.ts
 │   ├── .swc/                      # SWC transpiled sources
 │   ├── .lingui/                   # Compiled i18n catalogs
+│   ├── variants/                  # Option files of `phoenix variants`, written by coding agents
 │   ├── dist/                      # Build output
 │   │   ├── frontend/              # Frontend bundles
 │   │   └── webhooks/              # Webhook bundles

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

@@ -36,7 +36,7 @@ The starter `spec/application.yaml` begins with `project: default`, which means
 pnpm phoenix login <workspace>
 ```
 
-`phoenix login` opens Studio, where you name the token and approve the sign-in. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
+`phoenix login` opens Studio, where you name the token and approve the sign-in. Only a super admin of the workspace can open Studio, so only a super admin can approve it. The CLI suggests `phoenix CLI on <computer>`; a name of your own, such as the agent and the machine, tells your tokens apart later. Studio sends a one-time code back to the CLI on `127.0.0.1`, the CLI exchanges it for a personal token and returns the browser to Studio, which confirms the sign-in. The code only works for the CLI that asked for it and expires after five minutes. **Deny** stops the waiting CLI at once and creates no token. Use `--no-open` to print the link instead of opening a browser.
 
 The CLI stores the token in `~/.phoenix/credentials.json`, readable only by you, with one entry per server. `PHOENIX_CREDENTIALS_FILE` moves the file. The token acts for you in your workspace until you revoke it. It stops working when you are removed from the workspace or banned.
 
@@ -59,7 +59,7 @@ pnpm phoenix dev
 
 Signed in, `phoenix dev` needs no `.env` and nothing set up in Studio. When it starts, it asks the server for your development environment in the project the spec names. The server creates that environment the first time and finds it again on every later run. `phoenix dev` prints the workspace, project and environment it works in, prepares a development deployment there and opens the webhook tunnel, as for any Phoenix project (see [Phoenix CLI](?path=/docs/phoenix-phoenix-cli--docs)). It then prints the address of the preview as `Preview: <url>`; the preview talks to the server the deployment was prepared on.
 
-Every user of the workspace gets their own development environment, so a teammate who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
+Every user who signs the CLI in gets their own development environment, so a teammate (a super admin of the workspace, like you) who clones the project and signs in doesn't overwrite your schema or take over your webhooks. The development environment is separate from `production`: nothing you do in `phoenix dev` changes the live configurator.
 
 `pnpm dev:local` still runs the project without any server, with state kept in the browser.
 
@@ -107,4 +107,5 @@ Coding agents working in your project use the same command, guided by the genera
 - `phoenix deploy` always deploys to the workspace's default project; it doesn't read `project` from the spec yet.
 - Only `phoenix dev` works from the sign-in. `phoenix deployment:prepare-dev` still needs the `.env` block of a Studio development environment.
 - Every deploy uploads the whole project; there are no incremental uploads.
-- Your own environment variables can't use platform names such as `LAMBDA_FUNCTION_NAME` or the `AWS_` prefix. A deploy that sets them fails before it registers.
+- Your own environment variables are set in Studio under Environment, by a super admin of the workspace, and apply from the next deploy. `phoenix dev` doesn't receive them: your development environment has its own variables. A build reads them from `process.env`; a webhook reads the ones the spec declares under `env.webhook`, through `phx.webhooksEnv` (see [Webhooks](?path=/docs/phoenix-webhooks--docs)). They can't use platform names such as `LAMBDA_FUNCTION_NAME`, the `AWS_` prefix, the identity provider settings such as `CLERK_API_KEY`, or names the CLI and the deploy tooling read themselves, such as `SERVER_URL` or `NODE_OPTIONS`; Studio refuses those names.
+- Only super admins of a workspace can open its Studio. Admins and users see a page that says so.

package/dist/domain/components/updates.d.ts

@@ -7,6 +7,8 @@ export interface ComponentModification<COMPONENT_TYPE extends SystemComponentTyp
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     writableState: WritableStateOfComponent<COMPONENT_TYPE>;
     metadata?: Record<string, unknown>;
@@ -17,6 +19,8 @@ export interface EphemeralRecordModification<COMPONENT_TYPE extends SystemCompon
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     writableState: WritableStateOfComponent<COMPONENT_TYPE>;
 }
@@ -25,6 +29,8 @@ export interface EphemeralRecordCreation<COMPONENT_TYPE extends SystemComponentT
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     initialState: StateOfComponent<COMPONENT_TYPE>;
 }
@@ -34,6 +40,8 @@ export interface EphemeralRecordDeletion<COMPONENT_TYPE extends SystemComponentT
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export type DomainEntityStateDelta<ENTITY extends DomainEntity<string>> = Partial<Omit<ENTITY, 'id' | 'type'>>;
 export interface DomainEntityModification<ENTITY extends DomainEntity<string> = DomainEntity<string>> {
@@ -41,6 +49,8 @@ export interface DomainEntityModification<ENTITY extends DomainEntity<string> =
     entityId: ENTITY['id'];
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     stateDelta: DomainEntityStateDelta<ENTITY>;
     origin?: ComponentModification<SystemComponentTypeConstraint>;
 }
@@ -55,6 +65,8 @@ export interface DomainEntityCreation<ENTITY extends DomainEntity<string>, PAREN
     collection?: string;
     parentId: PARENT['id'];
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export interface DomainEntityReplacement<ENTITY extends DomainEntity<string>> {
     kind: 'replaceDomainEntity';
@@ -63,12 +75,16 @@ export interface DomainEntityReplacement<ENTITY extends DomainEntity<string>> {
     updateTag: string;
     keepChildren: boolean;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export interface EntityDeletion<ENTITY extends DomainEntity<string>> {
     kind: 'deleteEntity';
     entityId: EntityId<ENTITY>;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export type DataUpdate<ENTITY extends DomainEntity<string>, PARENT extends DomainEntity<string>> = EphemeralRecordModification | EphemeralRecordCreation | EphemeralRecordDeletion | DomainEntityModification<ENTITY> | DomainEntityCreation<ENTITY, PARENT> | DomainEntityReplacement<ENTITY> | EntityDeletion<ENTITY>;
 export type StateUpdate<ENTITY extends DomainEntity<string>, PARENT extends DomainEntity<string>> = ComponentModification<SystemComponentTypeConstraint> | DataUpdate<ENTITY, PARENT>;

package/dist/domain/domain-context/index.d.ts

@@ -1,5 +1,5 @@
 export { type AnalyticsSystem, NoopAnalyticsSystem } from './analytics-system/analytics-system.js';
-export { type AnalyticsEvent, AnalyticsEventFactory, AnalyticsEventType, } from './analytics-system/analytics-contracts.js';
+export { type AnalyticsEvent, AnalyticsEventFactory, AnalyticsEventType, type DataLoadedEvent, type InitEvent, type NavigationEvent, type SessionAuthenticatedEvent, type SystemEvent, type UserActionEvent, } from './analytics-system/analytics-contracts.js';
 export { NavigationUpdateTag, isInitialNavigationUpdate, isNavigationUpdate, isInitialViewUpdate, isViewUpdate, isInitialSelectionUpdate, isSelectUpdate, isDeselectUpdate, isInitialFullscreenUpdate, isToggleFullscreenUpdate, isInitialDebugUpdate, isInitialViewportUpdate, isSetViewportUpdate, isInitialDragUpdate, isDragStartUpdate, isDragEndUpdate, isInitialToolUpdate, isToolUpdate, isExportUpdate, } from './navigation-system/navigation-updates.js';
 export { createAutoSelectionTransformer, NavigationSystem, type NavigationSystemContext, } from './navigation-system/navigation-system.js';
 export { createResetSelectionOnNavigationTransformer, createNavigationOnSelectionTransformer, createNavigationOnDeselectTransformer, createSelectParentOnDeselectionTransformer, createNavigationOnSelectionChangeTransformer, } from './navigation-system/selection-transformers.js';