@salsita-ai/sdk 0.50.0-develop.f6390cb584 → 0.50.0-develop.fbe43b9a2d

package/dist/configurator/ui/assistant/form/{form-registry.d.ts → registry/form-registry.d.ts}

@@ -1,11 +1,11 @@
-import type { AssistantFormAttribute, PhxValidateFunction, SchemaValidator } from '#package/domain';
+import { type AssistantFormAttribute, type PhxValidateFunction, type SchemaValidator } from '#package/domain';
 import type { FormElementDefinition } from './form-element-definition.js';
 /** A declared attribute of a form element with the validator of its coerced value. */
 export interface RegisteredFormAttribute {
     readonly attribute: AssistantFormAttribute;
     readonly validate: PhxValidateFunction;
 }
-/** A form element with its declared attributes, the built-in `label` and `value` included. */
+/** A form element with its declared attributes, the built-in `label` included. */
 export interface RegisteredFormElement {
     readonly definition: FormElementDefinition;
     readonly attributes: ReadonlyMap<string, RegisteredFormAttribute>;

package/dist/configurator/ui/assistant/form/registry/form-registry.js

@@ -0,0 +1 @@
+import{ASSISTANT_FORM_NAME_PATTERN as e,isHtmlElementName as t}from"#package/domain";let r={type:"string"},n=e=>Object.entries({label:r,...e.attributes}),o=(e,t)=>{let r=e.get(t);if(r?.definition.role!==t)throw Error(`The form registry has no "${t}" element with the role "${t}". Forms wrap implicit content in it. Register the built-in "${t}".`);return r};export const createFormRegistry=(r,{schemaValidator:a})=>{let i=new Map;for(let o of r){if(!e.test(o.name)||t(o.name))throw Error(`The form element "${o.name}" cannot be registered: its name must be lowercase and must not be an HTML element name, so form markup is never read as HTML. Rename the element.`);if(i.has(o.name))throw Error(`The form element "${o.name}" is registered twice. Each tag names one element. Remove or rename one of them.`);let r=new Map(n(o).map(([e,t])=>[e,{attribute:t,validate:a.compile(t)}]));i.set(o.name,{definition:o,attributes:r})}return{group:o(i,"group"),choice:o(i,"choice"),choices:o(i,"choices"),get:e=>i.get(e)}};

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

@@ -0,0 +1,6 @@
+export { BUILT_IN_FORM_ELEMENTS } from './built-in-form-elements.js';
+export type { AssistantFormElementRoleProps, AssistantFormElementType, CreateAssistantFormElement, } from './create-assistant-form-element.js';
+export { createAssistantFormElementFactory } from './create-assistant-form-element.js';
+export { type FormElementDefinition, createFormElementDefinition } from './form-element-definition.js';
+export { type FormRegistry, type FormRegistryContext, type RegisteredFormAttribute, type RegisteredFormElement, createFormRegistry, } from './form-registry.js';
+export { useFormRegistry } from './use-form-registry.js';

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

@@ -0,0 +1 @@
+export{BUILT_IN_FORM_ELEMENTS}from"./built-in-form-elements.js";export{createAssistantFormElementFactory}from"./create-assistant-form-element.js";export{createFormElementDefinition}from"./form-element-definition.js";export{createFormRegistry}from"./form-registry.js";export{useFormRegistry}from"./use-form-registry.js";

package/dist/configurator/ui/assistant/form/registry/use-form-registry.d.ts

@@ -0,0 +1,8 @@
+import { type FormRegistry } from './form-registry.js';
+/**
+ * The registry the application's forms are read with. It is built when a form renders rather than
+ * when the bundle loads, since compiling validators then would break a configurator on a page whose
+ * CSP forbids eval, even one without an assistant; and rebuilt when the YAML or a component
+ * changes, so hot reload reaches the forms.
+ */
+export declare const useFormRegistry: () => FormRegistry;

package/dist/configurator/ui/assistant/form/registry/use-form-registry.js

@@ -0,0 +1 @@
+import{useMemo as r}from"react";import{extendedSchemaValidator as e}from"#package/domain";import{usePhoenixElementSlots as t,useSpecAssistant as m}from"#package/react-sdk";import{BUILT_IN_FORM_ELEMENTS as o}from"./built-in-form-elements.js";import{createFormElementDefinition as i}from"./form-element-definition.js";import{createFormRegistry as a}from"./form-registry.js";let f=[];export const useFormRegistry=()=>{let n=m()?.formElements??f,{assistantFormElements:s}=t();return r(()=>a([...o,...n.flatMap(r=>{let e=Object.entries(s).find(([e])=>e===r.name)?.[1];return e?[i(r,e)]:[]})],{schemaValidator:e}),[n,s])};

package/dist/configurator/ui/assistant/form-elements/FormCard.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
+import type { FormOptionProps } from './form-element-props.js';
+type FormCardProps = FormOptionProps<AssistantBuiltInFormElementAttributes<'card'>>;
+/**
+ * A `card`: a tile with its picture on top, then its label and description, outlined and checked
+ * while it is picked. A picture that is not a resource path or fails to load is left out.
+ */
+export declare const FormCard: ({ attributes, label, disabled, selected, onSelect }: FormCardProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormCard.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as r}from"react/jsx-runtime";import{styled as i}from"@mui/material";import{useCallback as o,useState as t}from"react";import{PhxIcon as a}from"#package/ui-sdk";import{useResourceImageUrl as n}from"../resource-image/index.js";import{AssistantPanelName as d}from"../theme.js";let l=i("button",{name:d,slot:"formCard"})(({theme:{palette:e,shape:r,spacing:i}})=>({alignContent:"start",background:e.background.paper,border:`1px solid ${e.divider}`,borderRadius:r.borderRadius,color:e.text.primary,cursor:"pointer",display:"grid",flex:"1 1 140px",font:"inherit",gap:i(.25),margin:0,maxInlineSize:220,padding:i(.75),position:"relative",textAlign:"start","&:hover:not(:disabled)":{background:e.action.hover},"&:focus-visible":{outline:`2px solid ${e.primary.main}`,outlineOffset:1},"&:disabled":{color:e.text.disabled,cursor:"default"},'&[aria-pressed="true"]':{borderColor:e.primary.main,boxShadow:`inset 0 0 0 1px ${e.primary.main}`}})),s=i("img",{name:d,slot:"formCardImage"})(({theme:{shape:e,spacing:r}})=>({aspectRatio:"4 / 3",borderRadius:e.borderRadius,display:"block",inlineSize:"100%",marginBlockEnd:r(.5),objectFit:"contain"})),m=i("span",{name:d,slot:"formCardLabel"})(({theme:{typography:e}})=>({...e.body2,fontWeight:e.fontWeightMedium})),p=i("span",{name:d,slot:"formCardDescription"})(({theme:{palette:e,typography:r}})=>({...r.caption,color:e.text.secondary})),c=i("span",{name:d,slot:"formCardCheck"})(({theme:{palette:e,spacing:r}})=>({alignItems:"center",background:e.primary.main,borderRadius:"50%",color:e.primary.contrastText,display:"flex",fontSize:14,insetBlockStart:r(.5),insetInlineEnd:r(.5),justifyContent:"center",padding:2,position:"absolute"}));export const FormCard=({attributes:i,label:d,disabled:u,selected:b,onSelect:f})=>{let{value:g,image:h}=i,x=[d,g].find(Boolean),y=""===i.description?void 0:i.description,k=n()(h),[C,j]=t(),v=o(()=>{j(k)},[k]);return r(l,{type:"button","aria-label":null==x&&null==y?h:void 0,disabled:u,"aria-pressed":b,onClick:()=>f([g,d,y,h].find(Boolean)??""),children:[null!=k&&k!==C&&e(s,{src:k,alt:"",loading:"lazy",onError:v}),null!=x&&e(m,{children:x}),null!=y&&e(p,{children:y}),b&&e(c,{"aria-hidden":!0,children:e(a,{name:"Check",fontSize:"inherit"})})]})};

package/dist/configurator/ui/assistant/form-elements/FormConfirm.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
+import type { FormInputProps } from './form-element-props.js';
+type FormConfirmProps = FormInputProps<boolean, AssistantBuiltInFormElementAttributes<'confirm'>>;
+/**
+ * A `confirm`: a yes or no question as ✓ and ✗ buttons. Its state is the pick, and it answers with
+ * the user's own words for yes and no, as the answer is their own message.
+ */
+export declare const FormConfirm: ({ label, disabled, state, onChange }: FormConfirmProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormConfirm.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as r}from"react/jsx-runtime";import{alpha as i,styled as a}from"@mui/material";import{useLocalizable as o}from"#package/react-sdk";import{PhxIcon as t}from"#package/ui-sdk";import{AssistantPanelName as n}from"../theme.js";let s={id:"sdk.assistant.form.confirm.yes",message:"Yes"},l={id:"sdk.assistant.form.confirm.no",message:"No"},d=a("div",{name:n,slot:"formConfirm"})(({theme:{palette:e,spacing:r,typography:i}})=>({...i.caption,color:e.text.secondary,display:"grid",gap:r(.75)})),m=a("div",{name:n,slot:"formConfirmButtons"})(({theme:{spacing:e}})=>({display:"flex",gap:e(.75)})),c=a("button",{name:n,slot:"formConfirmButton"})(({theme:{palette:e,spacing:r}})=>({alignItems:"center",background:e.background.paper,border:`1px solid ${e.divider}`,borderRadius:"calc(infinity * 1px)",color:e.text.primary,cursor:"pointer",display:"inline-flex",justifyContent:"center",margin:0,paddingBlock:r(.5),paddingInline:r(1.5),"&:hover:not(:disabled)":{background:e.action.hover},"&:focus-visible":{outline:`2px solid ${e.primary.main}`,outlineOffset:1},"&:disabled":{color:e.text.disabled,cursor:"default"},'&[aria-pressed="true"]':{background:i(e.primary.main,e.action.selectedOpacity),borderColor:e.primary.main}}));export const FormConfirm=({label:i,disabled:a,state:n,onChange:p})=>{let f=o(s),u=o(l);return r(d,{role:"group","aria-label":i,children:[null!=i&&e("span",{"aria-hidden":!0,children:i}),r(m,{children:[e(c,{type:"button","aria-label":f,title:f,disabled:a,"aria-pressed":!0===n,onClick:()=>p(!0,f),children:e(t,{name:"Check",fontSize:"small"})}),e(c,{type:"button","aria-label":u,title:u,disabled:a,"aria-pressed":!1===n,onClick:()=>p(!1,u),children:e(t,{name:"X",fontSize:"small"})})]})]})};

package/dist/configurator/ui/assistant/form-elements/FormGroup.d.ts

@@ -1,3 +1,6 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
 import type { FormContainerProps } from './form-element-props.js';
+type FormGroupProps = FormContainerProps<AssistantBuiltInFormElementAttributes<'group'>>;
 /** A `group`: its children stacked under its label, which heads them. */
-export declare const FormGroup: ({ label, children }: FormContainerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FormGroup: ({ label, children }: FormGroupProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormNumber.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
+import type { FormInputProps } from './form-element-props.js';
+type FormNumberProps = FormInputProps<number, AssistantBuiltInFormElementAttributes<'number'>>;
+/**
+ * A `number`: a field with its unit, and a slider beside it when both `min` and `max` are given. It
+ * stays unanswered until the user enters a number, even while the slider rests at `min`.
+ */
+export declare const FormNumber: ({ attributes: { value, min, max, step, unit }, label, disabled, state, onChange, }: FormNumberProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormNumber.js

@@ -0,0 +1 @@
+import{jsx as r,jsxs as i}from"react/jsx-runtime";import{Trans as e}from"@lingui/react";import{styled as o}from"@mui/material";import{useCallback as t,useEffect as a}from"react";import{NumericalInput as m}from"#package/ui-sdk";import{AssistantPanelName as n}from"../theme.js";import{clampFormNumber as s}from"./clamp-form-number.js";let l=o("div",{name:n,slot:"formNumber"})(({theme:{palette:r,spacing:i,typography:e}})=>({alignSelf:"stretch",color:r.text.secondary,display:"grid",gap:i(.5),...e.caption})),d=(r,i)=>i?`${r} ${i}`:String(r),u=r=>""===r.trim()?null:Number(r);export const FormNumber=({attributes:{value:o,min:n,max:p,step:v,unit:c},label:f,disabled:g,state:b,onChange:h})=>{let x=void 0===o?void 0:s(o,{min:n,max:p}),j=b??x;a(()=>{void 0===b&&void 0!==x&&h(x,d(x,c))},[b,x,c,h]);let N=t(r=>h(r,d(r,c)),[h,c]),S=t(()=>{if(void 0===j)return;let r=s(j,{min:n,max:p});r!==j&&N(r)},[j,n,p,N]),k=t(r=>void 0===j?"":String(r),[j]);return i(l,{role:"group","aria-label":f,children:[null!=f&&r("span",{"aria-hidden":!0,children:f}),r(m,{value:j??n??0,min:n,max:p,unit:c,size:"small",disabled:g,withSlider:void 0!==n&&void 0!==p,sliderProps:void 0===v?void 0:{step:v},inputFieldProps:{parseValue:u,formatValue:k,invalidNumberErrorMessage:r(e,{id:"sdk.assistant.form.number.invalid",message:"Enter a number."})},onChange:N,onChanged:S})]})};

package/dist/configurator/ui/assistant/form-elements/FormOptions.d.ts

@@ -1,3 +1,6 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
 import type { FormContainerProps } from './form-element-props.js';
+type FormOptionsProps = FormContainerProps<AssistantBuiltInFormElementAttributes<'choice' | 'choices'>>;
 /** A `choice` or `choices`: its options in a wrapping row under its label. */
-export declare const FormOptions: ({ label, children }: FormContainerProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FormOptions: ({ label, children }: FormOptionsProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormReply.d.ts

@@ -1,3 +1,6 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
 import type { FormOptionProps } from './form-element-props.js';
+type FormReplyProps = FormOptionProps<AssistantBuiltInFormElementAttributes<'reply'>>;
 /** A `reply`: a short answer as a small pill, marked while it is picked. */
-export declare const FormReply: ({ label, disabled, selected, onSelect }: FormOptionProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FormReply: ({ attributes, label, disabled, selected, onSelect }: FormReplyProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormReply.js

@@ -1 +1 @@
-import{jsx as r}from"react/jsx-runtime";import{alpha as e,styled as i}from"@mui/material";import{AssistantPanelName as o}from"../theme.js";let t=i("button",{name:o,slot:"formReply"})(({theme:{palette:r,spacing:i,typography:o}})=>({...o.body2,background:r.background.paper,border:`1px solid ${r.divider}`,borderRadius:"calc(infinity * 1px)",color:r.text.primary,cursor:"pointer",margin:0,paddingBlock:i(.25),paddingInline:i(1.25),textAlign:"start","&:hover:not(:disabled)":{background:r.action.hover},"&:focus-visible":{outline:`2px solid ${r.primary.main}`,outlineOffset:1},"&:disabled":{color:r.text.disabled,cursor:"default"},'&[aria-pressed="true"]':{background:e(r.primary.main,r.action.selectedOpacity),borderColor:r.primary.main}}));export const FormReply=({label:e,disabled:i,selected:o,onSelect:a})=>r(t,{type:"button",disabled:i,"aria-pressed":o,onClick:a,children:e});
+import{jsx as r}from"react/jsx-runtime";import{alpha as e,styled as o}from"@mui/material";import{AssistantPanelName as i}from"../theme.js";let a=o("button",{name:i,slot:"formReply"})(({theme:{palette:r,spacing:o,typography:i}})=>({...i.body2,background:r.background.paper,border:`1px solid ${r.divider}`,borderRadius:"calc(infinity * 1px)",color:r.text.primary,cursor:"pointer",margin:0,paddingBlock:o(.25),paddingInline:o(1.25),textAlign:"start","&:hover:not(:disabled)":{background:r.action.hover},"&:focus-visible":{outline:`2px solid ${r.primary.main}`,outlineOffset:1},"&:disabled":{color:r.text.disabled,cursor:"default"},'&[aria-pressed="true"]':{background:e(r.primary.main,r.action.selectedOpacity),borderColor:r.primary.main}}));export const FormReply=({attributes:e,label:o,disabled:i,selected:t,onSelect:d})=>r(a,{type:"button",disabled:i,"aria-pressed":t,onClick:()=>d([e.value,o].find(Boolean)??""),children:o});

package/dist/configurator/ui/assistant/form-elements/FormSwatch.d.ts

@@ -0,0 +1,10 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
+import type { FormOptionProps } from './form-element-props.js';
+type FormSwatchProps = FormOptionProps<AssistantBuiltInFormElementAttributes<'swatch'>>;
+/**
+ * A `swatch`: a small square filled with its color or covered by its picture, its label in a
+ * tooltip, ringed and checked while it is picked. A picture that is not a resource path or fails to
+ * load leaves the color, or a neutral tile.
+ */
+export declare const FormSwatch: ({ attributes, label, disabled, selected, onSelect }: FormSwatchProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormSwatch.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as i}from"react/jsx-runtime";import{Tooltip as r,styled as o}from"@mui/material";import{useCallback as a,useState as t}from"react";import{PhxIcon as n}from"#package/ui-sdk";import{useResourceImageUrl as l}from"../resource-image/index.js";import{AssistantPanelName as s}from"../theme.js";let d=o("button",{name:s,slot:"formSwatch"})(({theme:{palette:e,shape:i}})=>({background:e.action.hover,blockSize:36,border:`1px solid ${e.divider}`,borderRadius:i.borderRadius,cursor:"pointer",flex:"none",inlineSize:36,margin:0,overflow:"hidden",padding:0,position:"relative","&:focus-visible":{outline:`2px solid ${e.primary.main}`,outlineOffset:3},"&:disabled":{cursor:"default",opacity:e.action.disabledOpacity},'&[aria-pressed="true"]':{boxShadow:`0 0 0 2px ${e.background.paper}, 0 0 0 4px ${e.primary.main}`}})),m=o("img",{name:s,slot:"formSwatchImage"})({blockSize:"100%",display:"block",inlineSize:"100%",objectFit:"cover"}),c=o("span",{name:s,slot:"formSwatchCheck"})(({theme:{palette:e}})=>({alignItems:"center",background:e.primary.main,borderRadius:"50%",color:e.primary.contrastText,display:"flex",fontSize:14,inset:"50% auto auto 50%",justifyContent:"center",padding:2,position:"absolute",transform:"translate(-50%, -50%)"})),p=o("span")({display:"inline-flex"});export const FormSwatch=({attributes:o,label:s,disabled:u,selected:f,onSelect:b})=>{let{value:h,color:x,image:g}=o,y=l()(g),[k,S]=t(),j=[s,h,x,g].find(Boolean),v=a(()=>{S(y)},[y]);return e(r,{title:j??"",placement:"top",children:e(p,{children:i(d,{type:"button","aria-label":j,disabled:u,"aria-pressed":f,onClick:()=>b([h,s,x,g].find(Boolean)??""),style:null==x?void 0:{background:x},children:[null!=y&&y!==k&&e(m,{src:y,alt:"",loading:"lazy",onError:v}),f&&e(c,{"aria-hidden":!0,children:e(n,{name:"Check",fontSize:"inherit"})})]})})})};

package/dist/configurator/ui/assistant/form-elements/FormText.d.ts

@@ -1,3 +1,6 @@
+import type { AssistantBuiltInFormElementAttributes } from '#package/domain';
 import type { FormInputProps } from './form-element-props.js';
+type FormTextProps = FormInputProps<string, AssistantBuiltInFormElementAttributes<'text'>>;
 /** A `text`: a single line the user types, with its label above it. */
-export declare const FormText: ({ attributes, label, value, disabled, state, onChange }: FormInputProps) => import("react/jsx-runtime").JSX.Element;
+export declare const FormText: ({ attributes: { value, placeholder }, label, disabled, state, onChange }: FormTextProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/form-elements/FormText.js

@@ -1 +1 @@
-import{jsx as e,jsxs as r}from"react/jsx-runtime";import{InputBase as t,styled as o}from"@mui/material";import{useCallback as i}from"react";import{AssistantPanelName as a}from"../theme.js";let d=o("label",{name:a,slot:"formText"})(({theme:{palette:e,spacing:r,typography:t}})=>({alignSelf:"stretch",color:e.text.secondary,display:"grid",gap:r(.5),...t.caption})),m=o(t,{name:a,slot:"formTextInput"})(({theme:{palette:e,spacing:r,typography:t}})=>({...t.body2,border:`1px solid ${e.divider}`,borderRadius:12,color:e.text.primary,paddingBlock:r(.75),paddingInline:r(1.5),"&.Mui-focused":{borderColor:e.primary.main},"& .MuiInputBase-input":{padding:0}}));export const FormText=({attributes:t,label:o,value:a,disabled:l,state:n,onChange:p})=>{let{placeholder:s}=t;return r(d,{children:[o,e(m,{value:"string"==typeof n?n:a??"",placeholder:"string"==typeof s?s:void 0,disabled:l,onChange:i(e=>{let r=e.target.value;p(r,""===r.trim()?void 0:r.trim())},[p])})]})};
+import{jsx as e,jsxs as r}from"react/jsx-runtime";import{InputBase as t,styled as o}from"@mui/material";import{useCallback as i,useEffect as a}from"react";import{AssistantPanelName as d}from"../theme.js";let m=o("label",{name:d,slot:"formText"})(({theme:{palette:e,spacing:r,typography:t}})=>({alignSelf:"stretch",color:e.text.secondary,display:"grid",gap:r(.5),...t.caption})),l=e=>""===e.trim()?void 0:e.trim(),n=o(t,{name:d,slot:"formTextInput"})(({theme:{palette:e,spacing:r,typography:t}})=>({...t.body2,border:`1px solid ${e.divider}`,borderRadius:12,color:e.text.primary,paddingBlock:r(.75),paddingInline:r(1.5),"&.Mui-focused":{borderColor:e.primary.main},"& .MuiInputBase-input":{padding:0}}));export const FormText=({attributes:{value:t,placeholder:o},label:d,disabled:s,state:p,onChange:c})=>(a(()=>{void 0===p&&void 0!==t&&""!==t&&c(t,l(t))},[p,t,c]),r(m,{children:[d,e(n,{value:p??t??"",placeholder:o,disabled:s,onChange:i(e=>{let r=e.target.value;c(r,l(r))},[c])})]}));

package/dist/configurator/ui/assistant/form-elements/clamp-form-number.d.ts

@@ -0,0 +1,10 @@
+/** The limits a `number` keeps its value within, from its attributes. */
+export interface FormNumberLimits {
+    readonly min?: number;
+    readonly max?: number;
+}
+/**
+ * The value a `number` settles on once the user leaves the field: within `min` and `max`. The
+ * `step` is left out: it moves the slider, and a typed value between steps stays as typed.
+ */
+export declare const clampFormNumber: (value: number, { min, max }: FormNumberLimits) => number;

package/dist/configurator/ui/assistant/form-elements/clamp-form-number.js

@@ -0,0 +1 @@
+export const clampFormNumber=(m,{min:a,max:t})=>Math.min(t??1/0,Math.max(a??-1/0,m));

package/dist/configurator/ui/assistant/form-elements/form-element-props.d.ts

@@ -1,34 +1,38 @@
 import type { ReactNode } from 'react';
-/** Validated and coerced attributes of an element, without the built-in `label` and `value`. */
+/** Validated and coerced attributes of an element, without the built-in `label`: what any element gets. */
 export type FormElementAttributes = Readonly<Record<string, unknown>>;
 /** Props of a `group`, `choice` or `choices` element: it lays out the children the form renders for it. */
-export interface FormContainerProps {
-    readonly attributes: FormElementAttributes;
+export interface FormContainerProps<ATTRIBUTES = FormElementAttributes> {
+    readonly attributes: ATTRIBUTES;
     readonly label?: string;
     readonly disabled: boolean;
     readonly children: ReactNode;
 }
 /**
- * Props of an option. Its container decides what a pick does: in a `choice` it replaces the
- * previous pick, in a `choices` it toggles, and in a form that asks one question it sends at once.
+ * Props of an option. It reports what it answers with when the user picks it, as an input reports
+ * its answer: by convention its `value` attribute, or else its label. Its container decides what a
+ * pick does: in a `choice` it replaces the previous pick, in a `choices` it toggles, and in a form
+ * that asks one question it sends at once. An empty answer counts as unanswered.
  */
-export interface FormOptionProps {
-    readonly attributes: FormElementAttributes;
+export interface FormOptionProps<ATTRIBUTES = FormElementAttributes> {
+    readonly attributes: ATTRIBUTES;
     readonly label?: string;
     readonly disabled: boolean;
     readonly selected: boolean;
-    onSelect(): void;
+    onSelect(answer: string): void;
 }
 /**
- * Props of an input. Its state is its own: the form stores it and hands it back. `answer` is the
- * text the answer shows for it, or `undefined` while there is none.
+ * Props of an input. Its state is its own: the form stores what it reports and hands it back.
+ * `answer` is the text the answer shows for it, or `undefined` while there is none. An input that
+ * starts with a `value` attribute reports its starting answer when it mounts, since an input that
+ * never reports is unanswered and only the input knows how its value reads in the answer, such as
+ * a number with its unit. A quick input, which a lone form sends on its first report, reports only
+ * what the user did.
  */
-export interface FormInputProps {
-    readonly attributes: FormElementAttributes;
+export interface FormInputProps<STATE = unknown, ATTRIBUTES = FormElementAttributes> {
+    readonly attributes: ATTRIBUTES;
     readonly label?: string;
-    /** What the field starts with. */
-    readonly value?: string;
     readonly disabled: boolean;
-    readonly state: unknown;
-    onChange(state: unknown, answer: string | undefined): void;
+    readonly state: STATE | undefined;
+    onChange(state: STATE, answer: string | undefined): void;
 }

package/dist/configurator/ui/assistant/form-elements/index.d.ts

@@ -1,5 +1,9 @@
 export type { FormContainerProps, FormElementAttributes, FormInputProps, FormOptionProps, } from './form-element-props.js';
+export { FormCard } from './FormCard.js';
+export { FormConfirm } from './FormConfirm.js';
 export { FormGroup } from './FormGroup.js';
 export { FormOptions } from './FormOptions.js';
+export { FormNumber } from './FormNumber.js';
 export { FormReply } from './FormReply.js';
+export { FormSwatch } from './FormSwatch.js';
 export { FormText } from './FormText.js';

package/dist/configurator/ui/assistant/form-elements/index.js

@@ -1 +1 @@
-export{FormGroup}from"./FormGroup.js";export{FormOptions}from"./FormOptions.js";export{FormReply}from"./FormReply.js";export{FormText}from"./FormText.js";
+export{FormCard}from"./FormCard.js";export{FormConfirm}from"./FormConfirm.js";export{FormGroup}from"./FormGroup.js";export{FormOptions}from"./FormOptions.js";export{FormNumber}from"./FormNumber.js";export{FormReply}from"./FormReply.js";export{FormSwatch}from"./FormSwatch.js";export{FormText}from"./FormText.js";

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

@@ -1,2 +1,5 @@
 export { AssistantPanel, ASSISTANT_PANEL_SLOT } from './AssistantPanel.js';
 export { useIsAssistantPanelOpen } from './use-is-assistant-panel-open.js';
+export type { AssistantFormElementRoleProps, AssistantFormElementType, CreateAssistantFormElement, } from './form/index.js';
+export { createAssistantFormElementFactory } from './form/index.js';
+export type { FormContainerProps, FormInputProps, FormOptionProps } from './form-elements/index.js';

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

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

package/dist/configurator/ui/assistant/resource-image/index.d.ts

@@ -1,3 +1,3 @@
 export { AssistantImage } from './AssistantImage.js';
-export { RESOURCE_PATH_PATTERN, isResourcePath } from './resource-path.js';
+export { isResourcePath } from './resource-path.js';
 export { useResourceImageUrl } from './use-resource-image-url.js';

package/dist/configurator/ui/assistant/resource-image/index.js

@@ -1 +1 @@
-export{AssistantImage}from"./AssistantImage.js";export{RESOURCE_PATH_PATTERN,isResourcePath}from"./resource-path.js";export{useResourceImageUrl}from"./use-resource-image-url.js";
+export{AssistantImage}from"./AssistantImage.js";export{isResourcePath}from"./resource-path.js";export{useResourceImageUrl}from"./use-resource-image-url.js";

package/dist/configurator/ui/assistant/resource-image/resource-path.d.ts

@@ -1,11 +1,2 @@
-/**
- * A path into the project's resources, the kind stored on `imageUrl` fields: no scheme and no host,
- * so resolving it never leaves the resources origin. A backslash, a control character or leading
- * whitespace is refused too, because the URL parser reads a backslash as a slash and strips the
- * others, which would turn `\\host` or ` //host` into an address on another host.
- *
- * Written as a JSON Schema `pattern`, so attribute schemas can apply the same rule.
- */
-export declare const RESOURCE_PATH_PATTERN: string;
 /** True when the image source the model wrote may be requested: a path into the project's resources. */
 export declare const isResourcePath: (src: string | undefined) => src is string;

package/dist/configurator/ui/assistant/resource-image/resource-path.js

@@ -1 +1 @@
-export const RESOURCE_PATH_PATTERN=String.raw`^(?![a-zA-Z][a-zA-Z0-9+.-]*:)(?!//)[^\s\\\x00-\x1f][^\\\x00-\x1f]*$`;let t=RegExp(RESOURCE_PATH_PATTERN,"u");export const isResourcePath=R=>null!=R&&t.test(R);
+import{ASSISTANT_RESOURCE_PATH_PATTERN as e}from"#package/domain";let t=RegExp(e,"u");export const isResourcePath=e=>null!=e&&t.test(e);

package/dist/configurator/ui/assistant/screenshots/ScreenshotThumbnails.d.ts

@@ -0,0 +1,9 @@
+import type { AssistantToolScreenshot } from './tool-screenshots.js';
+interface ScreenshotThumbnailsProps {
+    readonly screenshots: readonly AssistantToolScreenshot[];
+    /** Called once a picture has loaded, which changes the size of the popover. */
+    readonly onImageLoad: () => void;
+}
+/** The pictures of a tool call's screenshots, each captioned by its view and entity id. */
+export declare const ScreenshotThumbnails: ({ screenshots, onImageLoad }: ScreenshotThumbnailsProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/configurator/ui/assistant/screenshots/ScreenshotThumbnails.js

@@ -0,0 +1 @@
+import{jsx as e,jsxs as i}from"react/jsx-runtime";import{styled as r}from"@mui/material";import{AssistantPanelName as o}from"../theme.js";let a=r("span",{name:o,slot:"screenshots"})(({theme:{palette:e,shape:i,shadows:r,spacing:o,typography:a}})=>({...a.caption,background:e.background.paper,borderRadius:i.borderRadius,boxShadow:r[4],color:e.text.secondary,display:"grid",gap:o(1.5),gridTemplateColumns:"repeat(auto-fill, minmax(140px, 1fr))",inlineSize:"min(80vw, 480px)",padding:o(1.5)})),n=r("span")(({theme:{spacing:e}})=>({display:"flex",flexDirection:"column",gap:e(.5),minInlineSize:0})),t=r("img")(({theme:{palette:e,shape:i}})=>({blockSize:"auto",borderRadius:i.borderRadius/2,boxShadow:`inset 0 0 0 1px ${e.divider}`,inlineSize:"100%"})),s=r("span")({overflow:"hidden",textOverflow:"ellipsis",whiteSpace:"nowrap"});export const ScreenshotThumbnails=({screenshots:r,onImageLoad:o})=>e(a,{children:r.map(({label:r,entityId:a,view:d,src:l})=>i(n,{children:[e(t,{src:l,alt:"",onLoad:o}),i(s,{title:r,children:[d," \xb7 ",a]})]},r))});

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

@@ -0,0 +1,2 @@
+export { ScreenshotThumbnails } from './ScreenshotThumbnails.js';
+export { type AssistantToolScreenshot, readToolScreenshots } from './tool-screenshots.js';

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

@@ -0,0 +1 @@
+export{ScreenshotThumbnails}from"./ScreenshotThumbnails.js";export{readToolScreenshots}from"./tool-screenshots.js";

package/dist/configurator/ui/assistant/screenshots/tool-screenshots.d.ts

@@ -0,0 +1,14 @@
+/** A screenshot a `query` or `apply` call took, as the panel shows it. */
+export interface AssistantToolScreenshot {
+    /** The label the call's `image` field returned, such as `Cabinet-2/doorLayout#2`. */
+    readonly label: string;
+    readonly entityId: string;
+    readonly view: string;
+    /** The picture as a data URL. */
+    readonly src: string;
+}
+/**
+ * The screenshots of a tool result: the image parts that follow the result's JSON, each after the
+ * text part with its label. A result without them, such as plain JSON or an error, has none.
+ */
+export declare const readToolScreenshots: (result: unknown) => readonly AssistantToolScreenshot[];

package/dist/configurator/ui/assistant/screenshots/tool-screenshots.js

@@ -0,0 +1 @@
+import{z as e}from"zod";let t=e.object({type:e.literal("text"),content:e.string()}),a=e.object({type:e.literal("image"),source:e.object({type:e.literal("data"),value:e.string(),mimeType:e.string()})}),s=/^([^/]+)\/([^#]+)(?:#\d+)?$/;export const readToolScreenshots=e=>Array.isArray(e)?e.slice(1).flatMap((e,r,c)=>{let l=a.safeParse(e),o=t.safeParse(c[r-1]),n=o.success?s.exec(o.data.content):null;if(!l.success||!o.success||!n?.[1]||!n[2])return[];let{value:i,mimeType:d}=l.data.source;return[{label:o.data.content,entityId:n[1],view:n[2],src:`data:${d};base64,${i}`}]}):[];

package/dist/configurator/ui/assistant/streamed-markdown.d.ts

@@ -2,7 +2,7 @@
 export declare const hasOpenFence: (text: string) => boolean;
 /**
  * Makes the Markdown of a reply that is still streaming renderable as it stands, so half-written
- * markup does not flash as raw characters: an open code fence is closed, an inline code span, a link
- * or a table header the model has not finished is held back, and open bold text is closed.
+ * markup does not flash as raw characters: an open code fence is closed, an inline code span, a link,
+ * an alert marker or a table header the model has not finished is held back, and open bold text is closed.
  */
 export declare const completeStreamedMarkdown: (text: string) => string;

package/dist/configurator/ui/assistant/streamed-markdown.js

@@ -1,2 +1,2 @@
-let e=(e,t)=>e.split(t).length-1,t=/^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/;export const hasOpenFence=t=>e(t,"```")%2==1;export const completeStreamedMarkdown=n=>{if(hasOpenFence(n))return`${n}
-\`\`\``;let l=n.lastIndexOf("```"),s=-1===l?"":n.slice(0,l+3),r=n.slice(s.length),c=(e=>{let n=e.split("\n"),l=n.length;for(;l>0&&n[l-1]?.trimStart().startsWith("|");)l-=1;let s=n.slice(l),r=s[1],c=null!=r&&s.length>2&&t.test(r);return 0===s.length||c?e:n.slice(0,l).join("\n")})((e(r,"`")%2==1?r.slice(0,r.lastIndexOf("`")):r).replace(/!?\[([^\]\n]*)\](?:\([^)\n]*)?$/,"$1").replace(/!?\[[^\]\n]*$/,"")),i=e(c,"**")%2==1?`${c}**`:c;return`${s}${i}`};
+let e=(e,t)=>e.split(t).length-1,t=/^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/,l=/(^|\n) {0,3}>[ \t]*\[![a-z]*$/i,n=/(^|\n) {0,3}>[ \t]*\[![a-z]+\][ \t]*$/i;export const hasOpenFence=t=>e(t,"```")%2==1;export const completeStreamedMarkdown=s=>{var r;let a;if(hasOpenFence(s))return`${s}
+\`\`\``;let i=s.lastIndexOf("```"),c=-1===i?"":s.slice(0,i+3),{head:$,marker:h}=(r=s.slice(c.length),null==(a=n.exec(r))?{head:r.replace(l,"$1"),marker:""}:{head:r.slice(0,a.index),marker:r.slice(a.index)}),p=(e=>{let l=e.split("\n"),n=l.length;for(;n>0&&l[n-1]?.trimStart().startsWith("|");)n-=1;let s=l.slice(n),r=s[1],a=null!=r&&s.length>2&&t.test(r);return 0===s.length||a?e:l.slice(0,n).join("\n")})((e($,"`")%2==1?$.slice(0,$.lastIndexOf("`")):$).replace(/!?\[([^\]\n]*)\](?:\([^)\n]*)?$/,"$1").replace(/!?\[[^\]\n]*$/,"")),d=e(p,"**")%2==1?`${p}**`:p;return`${c}${d}${h}`};

package/dist/configurator/ui/assistant/tool-chip.js

@@ -1 +1 @@
-import{Kind as e,parse as t}from"graphql";import{z as n}from"zod";import{ASSISTANT_TOOL_ERROR_CODES as r,AssistantToolError as a,applyTool as i,queryTool as o}from"@salsita-ai/contracts/assistant";let l=n.object({operations:n.array(n.object({query:n.string(),operationName:n.string().nullish()}))}),s=n.object({results:n.array(n.object({errors:n.array(n.unknown()).optional()})),committed:n.boolean()});export const describeToolCall=n=>{let d=(({name:n,input:r})=>{let a,s=(a=l.safeParse(r)).success?a.data.operations.flatMap(({query:n,operationName:r})=>r??(n=>{try{let r=t(n).definitions.find(t=>t.kind===e.OPERATION_DEFINITION);return r?.kind===e.OPERATION_DEFINITION?r.name?.value:void 0}catch{return}})(n)??[]):[];return s.length>0?{kind:"text",text:s.join(", ")}:n===i.name?{kind:"updateDesign"}:n===o.name?{kind:"readDesign"}:{kind:"text",text:n}})(n);if(null==n.result&&null==n.error)return{label:d,state:n.isReplyRunning?"running":"done",errorCode:void 0};let u=(e=>{let t=a.safeParse(e);if(t.success)return r.find(e=>e===t.data.code)})(n.result);return{label:d,state:(({name:e,result:t,error:n},r)=>{if(null!=n||null!=r)return e===o.name?"flawed":"failed";if(e!==i.name&&e!==o.name)return"done";let a=s.safeParse(t);if(!a.success)return e===o.name?"flawed":"failed";let{results:l,committed:d}=a.data;return e===i.name?d?"done":"failed":l.some(({errors:e})=>(e?.length??0)>0)||0===l.length?"flawed":"done"})(n,u),errorCode:u}};
+import{Kind as e,parse as t}from"graphql";import{z as n}from"zod";import{ASSISTANT_TOOL_ERROR_CODES as r,AssistantToolError as a,applyTool as s,queryTool as o}from"@salsita-ai/contracts/assistant";let i=n.object({operations:n.array(n.object({query:n.string(),operationName:n.string().nullish()}))}),l=n.object({results:n.array(n.object({errors:n.array(n.unknown()).optional()})),committed:n.boolean()}),u=n.tuple([n.object({type:n.literal("text"),content:n.string()})]).rest(n.unknown());export const describeToolCall=n=>{let d=(({name:n,input:r})=>{let a,l=(a=i.safeParse(r)).success?a.data.operations.flatMap(({query:n,operationName:r})=>r??(n=>{try{let r=t(n).definitions.find(t=>t.kind===e.OPERATION_DEFINITION);return r?.kind===e.OPERATION_DEFINITION?r.name?.value:void 0}catch{return}})(n)??[]):[];return l.length>0?{kind:"text",text:l.join(", ")}:n===s.name?{kind:"updateDesign"}:n===o.name?{kind:"readDesign"}:{kind:"text",text:n}})(n);if(null==n.result&&null==n.error)return{label:d,state:n.isReplyRunning?"running":"done",errorCode:void 0};let c=(e=>{let t=a.safeParse(e);if(t.success)return r.find(e=>e===t.data.code)})(n.result);return{label:d,state:(({name:e,result:t,error:n},r)=>{if(null!=n||null!=r)return e===o.name?"flawed":"failed";if(e!==s.name&&e!==o.name)return"done";let a=l.safeParse((e=>{let t=u.safeParse(e);if(!t.success)return e;try{return JSON.parse(t.data[0].content)}catch{return e}})(t));if(!a.success)return e===o.name?"flawed":"failed";let{results:i,committed:d}=a.data;return e===s.name?d?"done":"failed":i.some(({errors:e})=>(e?.length??0)>0)||0===i.length?"flawed":"done"})(n,c),errorCode:c}};

package/dist/configurator/ui/configurator-layout/universal/ExportingOverlay.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Covers the configurator while an export runs, which keeps it inert: a press anywhere shows for a
+ * moment why nothing responds, instead of a configurator that silently ignores the user.
+ */
+export declare const ExportingOverlay: () => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+import{jsx as e}from"react/jsx-runtime";import{Trans as r}from"@lingui/react";import{styled as t}from"@mui/material";import{useCallback as o,useEffect as i,useState as a}from"react";let n=t("div",{name:"PhxExportingOverlay",slot:"root"})(({theme:{zIndex:e}})=>({alignItems:"center",cursor:"wait",display:"flex",inset:0,justifyContent:"center",position:"absolute",zIndex:e.modal+1})),l=t("div",{name:"PhxExportingOverlay",slot:"message"})(({theme:{palette:e,shape:r,shadows:t,spacing:o,typography:i}})=>({...i.body2,background:e.background.paper,borderRadius:r.borderRadius,boxShadow:t[4],color:e.text.primary,padding:o(1,2)}));export const ExportingOverlay=()=>{let[t,s]=a(null),m=o(()=>s(Date.now()),[]);return i(()=>{if(null===t)return;let e=setTimeout(()=>s(null),2e3);return()=>clearTimeout(e)},[t]),e(n,{onPointerDown:m,children:null!==t&&e(l,{role:"status",children:e(r,{id:"sdk.layout.exporting.message",message:"Configurator is exporting… please wait"})})})};

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

@@ -1 +1 @@
-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,{})]})};
+import{jsx as t,jsxs as e,Fragment as r}from"react/jsx-runtime";import{styled as o}from"@mui/material";import{useEffect as i}from"react";import{useEagerObservableValue as m}from"#package/react-sdk";import{useResponsive as n}from"#package/ui-sdk";import{useConfigurator as a}from"../../../application-runtime/index.js";import{LayoutSlots as s}from"../slots/index.js";import{DesktopLayout as c}from"./DesktopLayout.js";import{ExportingOverlay as p}from"./ExportingOverlay.js";import{MobileLayout as d}from"./MobileLayout.js";let l=o("div")({display:"contents"});export const Layout=()=>{let{isDesktop:o}=n(),{exportSystem:u}=a(),f=m(u.exporting$);return i(()=>{if(!f)return;let t=document.activeElement;return()=>{t instanceof HTMLElement&&t.isConnected&&document.activeElement===document.body&&t.focus()}},[f]),e(r,{children:[e(l,{...{inert:f?"":void 0},children:[t(s.Services,{}),t(s.SharedCanvas,{}),o?t(c,{}):t(d,{})]}),f&&t(p,{})]})};

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

@@ -4,3 +4,4 @@ export * from './phoenix-layout-elements/index.js';
 export * from './preset-layout/index.js';
 export * as Legacy from './legacy/index.js';
 export * from './ConfiguratorEncapsulatedTheme.js';
+export { type AssistantFormElementRoleProps, type AssistantFormElementType, type CreateAssistantFormElement, type FormContainerProps, type FormInputProps, type FormOptionProps, createAssistantFormElementFactory, } from './assistant/index.js';

package/dist/configurator/ui/index.js

@@ -1 +1 @@
-export*from"./configurator-layout/index.js";export*from"./phoenix-entity-elements/index.js";export*from"./phoenix-layout-elements/index.js";export*from"./preset-layout/index.js";export*as Legacy from"./legacy/index.js";export*from"./ConfiguratorEncapsulatedTheme.js";
+export*from"./configurator-layout/index.js";export*from"./phoenix-entity-elements/index.js";export*from"./phoenix-layout-elements/index.js";export*from"./preset-layout/index.js";export*as Legacy from"./legacy/index.js";export*from"./ConfiguratorEncapsulatedTheme.js";export{createAssistantFormElementFactory}from"./assistant/index.js";

package/dist/docs/complex-use-cases/focus-mode.mdx

@@ -69,6 +69,8 @@ components:
 
 The toolMenuFab is scene HTML rendered at the entity's position in the 3D scene. It supports positioning properties (`offsetX`, `offsetY`, `offsetZ`) and appearance properties like opacity and visibility.
 
+The FAB and its menu are the entity element `ToolMenuFab`. A project replaces them by registering its own with `phx.frontend.createToolMenuFab`, which receives the `options` and `onSelectTool(toolState)`. See [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls).
+
 ### Step 3: Add exitToolModeFab component
 
 The `exitToolModeFab` component renders a button in the call to action layout slot, providing a clear way to exit the current tool mode. This appears in the UI chrome, not in the scene:

package/dist/docs/fabs/basic.mdx

@@ -131,6 +131,10 @@ components:
           - non-existent
 ```
 
+### Your own FABs
+
+The FABs are the entity elements `DeleteEntityFab` and `AddEntityFab`. A project replaces their look by registering its own with `phx.frontend.createDeleteEntityFab` or `phx.frontend.createAddEntityFab`; the spec's settings and positions above still apply. The delete FAB's replacement gets `onDelete`, `disabled` and `disabledHint`; the add FAB's reads its recipes with `phx.frontend.useGroupedRecipeOptions`. See [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls).
+
 ## Example
 
 Here you can see the live example!

package/dist/docs/index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-10-16T09:06:42.377Z",
+  "generatedAt": "2026-10-17T06:40:12.837Z",
   "categories": [
     {
       "name": "Phoenix",
@@ -881,6 +881,67 @@
           ],
           "subcategories": []
         },
+        {
+          "name": "Gallery",
+          "docs": [
+            {
+              "title": "Ardent Compressor",
+              "description": "Quote an engineered product from a form, with no 3D model at all. An industrial compressor maker, Ardent Air, lets plant engineers size a rotary screw compressor and ask for a firm quote. The...",
+              "path": "docs/layouts/gallery/ardent-compressor.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Ardent Compressor"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Fenwick Window",
+              "description": "Show a made-to-measure product as the drawing a workshop would build it from. A joinery, Fenwick & Lowe, sells timber casement windows to order: the customer sets the overall size, the panes across,...",
+              "path": "docs/layouts/gallery/fenwick-window.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Fenwick Window"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Ferrule Bar Station",
+              "description": "Let a bar designer lay out a commercial bartender station and hand the result straight to the workshop. A fictional maker, Ferrule Barworks, sells stainless underbar stations built from modules: ice...",
+              "path": "docs/layouts/gallery/ferrule-bar-station.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Ferrule Bar Station"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Kestrel Kettle",
+              "description": "Sell a small product from one calm page that looks like the shop's own. A specialty-coffee shop, Aldermoor Coffee, sells its Kestrel pour-over kettle in three finishes, two handle woods and with or...",
+              "path": "docs/layouts/gallery/kestrel-kettle.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Kestrel Kettle"
+              ],
+              "source": "storybook-example"
+            },
+            {
+              "title": "Sunfold Solar",
+              "description": "Help a household decide on a system by showing what it would do for them. A solar installer, Sunfold, lets a homeowner plan panels and a battery for their roof: the roof's area and direction, the...",
+              "path": "docs/layouts/gallery/sunfold-solar.mdx",
+              "category": [
+                "Layouts",
+                "Gallery",
+                "Sunfold Solar"
+              ],
+              "source": "storybook-example"
+            }
+          ],
+          "subcategories": []
+        },
         {
           "name": "Header",
           "docs": [

package/dist/docs/layouts/custom-layout.mdx

@@ -1032,6 +1032,8 @@ export default phx.frontend.createCustomPhoenixEntityElement('EdgeFinishHotspot'
 
 [Html Hotspots](?path=/docs/controls-scene-html-hotspots--docs) describes the component and its other properties.
 
+The SDK's own controls on the product, such as `sceneEntityAddFab` and `sceneEntitySelectHotspot`, keep the SDK's look in a project layout too. Each is rendered through an entity element of its own name, so a project gives it the brand's look by registering that name, for example with `phx.frontend.createAddEntityFab`; see [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls). `htmlHotspot` is for a control the SDK has none of, like this one.
+
 ## Control the scene
 
 The four finishes differ by a few millimetres on a table two metres long, so from the default distance the difference is hard to judge. The layout offers two views, **Whole table** and **Edge close-up**, a close and low look at a corner of the top, and a **Reset view** button that brings back the framing after the customer has orbited, panned or zoomed.
@@ -1268,7 +1270,7 @@ The same layout in a frame 390 pixels wide, as on a phone. Opened on its own fro
 A project layout has only what it renders. This one leaves out the following, each of which a product may need. [Layout Slots](?path=/docs/phoenix-layout-slots--docs) describes every `LayoutSlots` member named here.
 
 - **Messages that stay snackbars.** The toast shows violations, side effects, errors and failed saves, and the finalize button shows its own error. Two kinds of message stay snackbars. An error of a built-in action, such as one from `LayoutSlots.DesktopToolbar`, renders into `LayoutSlots.DesktopSnackbarsRoot`; this layout mounts neither, and a layout that mounts such an action mounts the root too, or the snackbar appears outside the configurator. A failure to start from a preset appears on the preset screen, before this layout mounts; a project replaces that screen with `phx.frontend.createPresetUi`, see [Configurator Interface → Preset UI](?path=/docs/phoenix-configurator-interface--docs#preset-ui).
-- **Toolbar actions.** Undo and redo, measurements, sharing and language switching are not offered. A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons: `phx.frontend.useUndoRedo()`, `useMeasurements()`, `useShareLinks()` and `useLocaleSwitch()` serve single actions, pushing the same analytics events as the built-in buttons; see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
+- **Toolbar actions.** Undo and redo, measurements, sharing and language switching are not offered. A layout can mount `LayoutSlots.DesktopToolbar` for the toolbar the spec configures, or build its own buttons: `phx.frontend.useToolbarActions()` returns the spec's toolbar as runnable entries, and `phx.frontend.useUndoRedo()`, `useMeasurements()`, `useShareLinks()` and `useLocaleSwitch()` serve single actions, pushing the same analytics events as the built-in buttons; see [Configurator Interface → Hooks for a Project Layout](?path=/docs/phoenix-configurator-interface--docs#hooks-for-a-project-layout).
 - **The spec's view controls, tool controls and leaving a tool mode.** A spec can configure view controls and tool controls, and a tool mode has a button that leaves it. The built-in layout places them with `LayoutSlots.DesktopViewControls`, `LayoutSlots.DesktopToolControls` and `LayoutSlots.DesktopCallToAction`; this layout mounts none of them, so the spec's `viewControls` and `toolControls` do not appear. Its views come from its own buttons instead, see [Control the scene](#control-the-scene), and it has no tool modes.
 - **A project's layout dialog.** A dialog the project registers with `phx.frontend.createLayoutDialog` is shown by `LayoutDialog`, which the built-in layout mounts. This layout does not; a layout that needs the dialog mounts `LayoutDialog` from `@salsita-ai/sdk/configurator`.
 - **Selection.** The table has no parts to select. A product with selectable parts reads `phx.frontend.useSelectedDomainEntityId()` and shows the controls of the selected part.