@salsita-ai/sdk 0.50.0-develop.ca72986c39 → 0.50.0-develop.d08a6c0e83

package/dist/configurator/application-runtime/extensions/systems/export-system/export-system.js

@@ -1 +1 @@
-import{isNonNullish as t}from"@salsita-ai/common/utils";export class ExportSystem{_context;_generation=null;_frameloopPause=null;constructor(t){this._context=t}pauseFrameloop=t=>{if(this._frameloopPause?.handle===t)this._frameloopPause.holders+=1;else{let{frameloop:e,internal:o}=t.get();this._frameloopPause={handle:t,frameloop:e,priority:o.priority,holders:1},t.set(t=>({...t,frameloop:"never",internal:{...t.internal,priority:1/0}}))}let e=this._frameloopPause,o=!1;return()=>{o||(o=!0,e.holders-=1,e.holders>0||this._frameloopPause!==e||(this._frameloopPause=null,this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value===t&&t.set(t=>({...t,frameloop:e.frameloop,internal:{...t.internal,priority:e.priority}}))))}};createExportJob=(t,e,o)=>({sourceState:t,exportState:e.exportState,exportedEntityId:e.exportedEntityId,execute:o,toolState:e.toolState,viewState:e.viewState,navigationState:e.navigationState,selectedEntityId:e.selectedEntityId});runExportJobs=async e=>{let o=this._generation,i=()=>{if(!o?.active)throw Error("Export generation ended while jobs were running! The configurator context was reinitialized mid-export, so the remaining jobs would drive a state that is no longer theirs. Await the export before leaving the configuration, or discard the rejection.")};i();let a=this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value;if(!a)throw Error("Canvas is not ready");let n=this._context.domainContextSelectors.getStoreSystem().stateSlices.committed.value,r=this.pauseFrameloop(a);try{let o=[];for(let n of e){i();let e=this._context.domainContextSelectors.getStoreSystem().prepareStateEmission([this._context.domainContextSelectors.getNavigationSystem().getExportUpdate(n.exportState,n.exportedEntityId),null!=n.toolState?this._context.domainContextSelectors.getNavigationSystem().getToolUpdate(n.toolState):void 0,null!=n.viewState?this._context.domainContextSelectors.getNavigationSystem().getViewUpdate(n.viewState):void 0,null!=n.navigationState?this._context.domainContextSelectors.getNavigationSystem().getNavigationUpdate(n.navigationState):void 0,null!=n.selectedEntityId?this._context.domainContextSelectors.getNavigationSystem().getSelectUpdate(n.selectedEntityId):void 0,this._context.domainContextSelectors.getNavigationSystem().getHoverOutUpdate()].filter(t),n.sourceState,"staged");if(this._context.domainContextSelectors.getStoreSystem().emit(e),await this._context.configuratorExtensionSelectors.getCanvasSystem().waitForFlush(),i(),!e.validity.valid)throw this._context.domainServicesSelectors.getLogger().error(`Setting an export state to ${n.exportState} for entity ${n.exportedEntityId} resulted in an invalid state! Check if there isn't a transformer corrupting the state as a reaction to setting the export state.`,e),Error("Exported state is invalid!");let r=e.state,s=this._context.domainContextSelectors.getDomain().get$Entity(n.exportedEntityId,r),l=this._context.domainContextSelectors.getDomain().getRoot$Entity(r),c=await n.execute({$entity:s,$root:l,state:r,scene:a.get().scene});i(),o.push(c)}return o}finally{o?.active&&this._context.domainContextSelectors.getStoreSystem().emit(n),r()}};initialize=()=>{null!==this._generation&&(this._generation.active=!1),this._generation={active:!0}}}
+import{BehaviorSubject as t}from"rxjs";import{isNonNullish as e}from"@salsita-ai/common/utils";import{ExportBusyError as o}from"./export-busy-error.js";export class ExportSystem{_context;_generation=null;_frameloopPause=null;_queue=null;_exporting=new t(!1);exporting$=this._exporting;constructor(t){this._context=t}pauseFrameloop=t=>{if(this._frameloopPause?.handle===t)this._frameloopPause.holders+=1;else{let{frameloop:e,internal:o}=t.get();this._frameloopPause={handle:t,frameloop:e,priority:o.priority,holders:1},t.set(t=>({...t,frameloop:"never",internal:{...t.internal,priority:1/0}}))}let e=this._frameloopPause,o=!1;return()=>{o||(o=!0,e.holders-=1,e.holders>0||this._frameloopPause!==e||(this._frameloopPause=null,this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value===t&&t.set(t=>({...t,frameloop:e.frameloop,internal:{...t.internal,priority:e.priority}}))))}};createExportJob=(t,e,o)=>({sourceState:t,exportState:e.exportState,exportedEntityId:e.exportedEntityId,execute:o,toolState:e.toolState,viewState:e.viewState,navigationState:e.navigationState,selectedEntityId:e.selectedEntityId});runExportJobs=(t,e={})=>{let o=this._generation,i=(this._queue??Promise.resolve()).then(()=>this._runExportJobs(t,e,o)),a=i.catch(()=>void 0);return this._queue=a,this._exporting.value||this._exporting.next(!0),a.then(()=>{this._queue===a&&(this._queue=null,this._exporting.next(!1))}),i};_awaitSettledState=async t=>{let e=this._context.domainContextSelectors.getStoreSystem(),i=Date.now()+2e3;for(;e.hasStagedUpdates;){if(Date.now()>=i)throw new o;await new Promise(t=>setTimeout(t,200)),t()}};_runExportJobs=async(t,{awaitSettledState:o=!1},i)=>{let a=()=>{if(!i?.active)throw Error("Export generation ended while jobs were running! The configurator context was reinitialized mid-export, so the remaining jobs would drive a state that is no longer theirs. Await the export before leaving the configuration, or discard the rejection.")};a(),o&&await this._awaitSettledState(a);let n=this._context.configuratorExtensionSelectors.getCanvasSystem(),r=n.r3fHandle$.value??await n.waitForCanvas().catch(t=>{throw a(),t});a();let s=this.pauseFrameloop(r);try{let o=[];for(let i of t){a();let t=this._context.domainContextSelectors.getStoreSystem().prepareStateEmission([this._context.domainContextSelectors.getNavigationSystem().getExportUpdate(i.exportState,i.exportedEntityId),null!=i.toolState?this._context.domainContextSelectors.getNavigationSystem().getToolUpdate(i.toolState):void 0,null!=i.viewState?this._context.domainContextSelectors.getNavigationSystem().getViewUpdate(i.viewState):void 0,null!=i.navigationState?this._context.domainContextSelectors.getNavigationSystem().getNavigationUpdate(i.navigationState):void 0,null!=i.selectedEntityId?this._context.domainContextSelectors.getNavigationSystem().getSelectUpdate(i.selectedEntityId):void 0,this._context.domainContextSelectors.getNavigationSystem().getHoverOutUpdate()].filter(e),i.sourceState,"staged");if(this._context.domainContextSelectors.getStoreSystem().emit(t),await this._context.configuratorExtensionSelectors.getCanvasSystem().waitForFlush(),a(),!t.validity.valid)throw this._context.domainServicesSelectors.getLogger().error(`Setting an export state to ${i.exportState} for entity ${i.exportedEntityId} resulted in an invalid state! Check if there isn't a transformer corrupting the state as a reaction to setting the export state.`,t),Error("Exported state is invalid!");let n=t.state,s=this._context.domainContextSelectors.getDomain().get$Entity(i.exportedEntityId,n),l=this._context.domainContextSelectors.getDomain().getRoot$Entity(n),c=await i.execute({$entity:s,$root:l,state:n,scene:r.get().scene});a(),o.push(c)}return o}finally{if(i?.active){let t=this._context.domainContextSelectors.getStoreSystem();t.emit(t.stateSlices.committed.value)}s()}};initialize=()=>{null!==this._generation&&(this._generation.active=!1),this._generation={active:!0},this._queue=null,this._exporting.value&&this._exporting.next(!1)}}

package/dist/configurator/application-runtime/extensions/systems/graphql-system/close-unclosed-braces.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The agent's operation document with the closing braces it left off added at its end. Models
+ * often drop the last `}` of a nested selection, and the only error GraphQL gives for it is
+ * "Expected Name, found <EOF>", which costs the agent a round trip to fix. At the end of a
+ * document, closing braces are the only completion there is, so this cannot change what a valid
+ * document means; a brace missing in the middle nests the following fields one level deeper, which
+ * validation then rejects. Appending keeps the positions GraphQL reports for the agent's own text.
+ * A document with no unclosed brace, which covers every document that parses, or one that still
+ * does not parse with them closed is returned as it is, so GraphQL reports the agent's own syntax
+ * error and not one of the repair.
+ */
+export declare const closeUnclosedBraces: (document: string) => string;

package/dist/configurator/application-runtime/extensions/systems/graphql-system/close-unclosed-braces.js

@@ -0,0 +1 @@
+import{Lexer as r,Source as e,TokenKind as t,parse as n}from"graphql";export const closeUnclosedBraces=c=>{let a=(n=>{let c=new r(new e(n)),a=0;try{for(let r=c.advance();r.kind!==t.EOF;r=c.advance())r.kind===t.BRACE_L?a+=1:r.kind===t.BRACE_R&&(a-=1)}catch{return 0}return a})(c);if(a<=0)return c;let l=`${c}${" }".repeat(a)}`;return(r=>{try{return n(r),!0}catch{return!1}})(l)?l:c};

package/dist/configurator/application-runtime/extensions/systems/graphql-system/entity-meta.d.ts

@@ -20,6 +20,13 @@ export interface EntityMetaContext {
         readonly success: false;
         readonly errors: readonly string[];
     };
+    /**
+     * Takes a screenshot of the entity from one of its views on the state it was read on and returns
+     * the label of the image; `null` when the view does not apply to the entity there.
+     */
+    readonly takeScreenshot: (source: EntityMetaSource, view: string) => Promise<{
+        readonly image: string;
+    } | null>;
 }
 /** One reason a dry-run reports for a change that cannot be made; a violation can sit on a virtual entity. */
 interface DryRunError {
@@ -30,7 +37,8 @@ interface DryRunError {
 /**
  * The value of an entity's `meta` field: its built-ins, resolved lazily against the state the entity
  * was read on. `childRecipes` and `replaceRecipes` list the manifest's recipe groups of their kind
- * that are active on the entity there; each options edge lists the choices of its field there, or `null` when its component is not active.
+ * that are active on the entity there; each options edge lists the choices of its field there, or `null` when its component is not active;
+ * `screenshot` renders the entity there.
  */
 export declare const createEntityMeta: (source: EntityMetaSource, context: EntityMetaContext) => {
     childRecipes: () => {
@@ -85,5 +93,10 @@ export declare const createEntityMeta: (source: EntityMetaSource, context: Entit
             } | null;
         }[];
     }[];
+    screenshot: ({ view }: {
+        readonly view: string;
+    }) => Promise<{
+        readonly image: string;
+    } | null>;
 };
 export {};

package/dist/configurator/application-runtime/extensions/systems/graphql-system/entity-meta.js

@@ -1 +1 @@
-import{findAssistantFieldOptions as e,findAssistantRecipeGroups as t,modifyEntityUpdateTag as i,prepareAssistantRecipeUpdates as r,readAssistantFieldOptions as n,readAssistantRecipeGroup as o,systemUpdateFactory as s}from"#package/domain";import{readSideEffects as a}from"./side-effects.js";let d=e=>({ok:!1,root:null,changedEntities:[],deletedEntityIds:[],sideEffects:[],errors:e}),l=(e,{state:t},{recipes:i,prepareStateEmission:r,find$Entity:n})=>{let{validity:o,state:s,updates:l}=r(e,t,"committed");if(o.valid){let e=new Map(t.entities.map(e=>[e.id,e])),r=new Set(s.entities.map(e=>e.id));return{ok:!0,root:n(s.rootEntityId,s),changedEntities:s.entities.filter(t=>e.get(t.id)!==t).flatMap(e=>n(e.id,s)??[]),deletedEntityIds:t.entities.map(e=>e.id).filter(e=>!r.has(e)),sideEffects:a(l,i.resolveLocalizable),errors:[]}}return d("uncaught"===o.severity?[{type:"uncaught",entityId:null,message:o.error.message}]:o.entityViolations.filter(({violation:e})=>e.severity===o.severity).map(({entityId:e,violation:t})=>({type:t.type,entityId:e,message:void 0===t.message?null:i.resolveLocalizable(t.message)})))};export const createEntityMeta=(a,u)=>{let c=e=>()=>t(u.manifest,e,a.entity.type).flatMap(t=>{let i=o(e,t,a.entity.id,a.state,u.recipes);return i?[((e,t,i)=>{let{group:n,label:o,description:s,recipes:a}=e,{resolveLocalizable:u}=i.recipes;return{groupId:n.groupId,name:void 0===o?n.instanceName:u(o),description:n.description??(void 0===s?null:u(s)),recipes:a.map(n=>((e,t,i,n)=>{let{key:o,item:s}=e,{resolveLocalizable:a}=n.recipes;return{key:o,name:a(s.title),description:void 0===s.description?null:a(s.description),imageUrl:void 0===s.thumbnailUrl?null:a(s.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,n)=>{let{updates:o,error:s}=((e,t,{entity:i,state:n},{recipes:o})=>{try{return{updates:r(e,t,i.id,n,o),error:void 0}}catch(e){if("child"===t.target.kind)throw e;return{updates:void 0,error:e instanceof Error?e.message:String(e)}}})(e,t,i,n);return void 0===o?d([{type:"uncaught",entityId:null,message:s}]):l(o,i,n)})(e,t,i,n):null}})(n,e,t,i))}})(i,a,u)]:[]});return{...Object.fromEntries(e(u.manifest,a.entity.type).map(e=>[e.edgeName,()=>n(e,a.entity.id,a.state,u.recipes)?.map(t=>({...t,dryRun:()=>e.dryRuns?(({field:e},{value:t},r,n)=>{let{entity:o}=r,a=Object.entries(Object.entries(n.manifest.writableFields??{}).find(([e])=>e===o.type)?.[1]??{}).find(([t])=>t===e)?.[1];if(void 0===a)throw Error(`The options of "${e}" on "${o.id}" cannot be dry-run: the schema lists them, but the configurator has no writable field "${e}" on ${o.type}. This is a fault in the configurator, not in your request. Tell the user this is not available.`);let u=r.state.entities.find(e=>e.id===o.id);if(!u)throw Error(`The options of "${e}" on "${o.id}" cannot be dry-run: entity "${o.id}" does not exist. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let c={[a]:t},p=n.validateEntity({...u,...c});return p.success?l([s.DomainEntityModification({entityId:o.id,stateDelta:c,updateTag:i})],r,n):d([{type:"uncaught",entityId:o.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${o.id}" an invalid ${o.type}: ${p.errors.join("; ")}. The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(e,t,a,u):null}))??null])),childRecipes:c("child"),replaceRecipes:c("replace")}};
+import{findAssistantFieldOptions as e,findAssistantRecipeGroups as t,modifyEntityUpdateTag as i,prepareAssistantRecipeUpdates as r,readAssistantFieldOptions as n,readAssistantRecipeGroup as o,systemUpdateFactory as s}from"#package/domain";import{readSideEffects as a}from"./side-effects.js";let d=e=>({ok:!1,root:null,changedEntities:[],deletedEntityIds:[],sideEffects:[],errors:e}),l=(e,{state:t},{recipes:i,prepareStateEmission:r,find$Entity:n})=>{let{validity:o,state:s,updates:l}=r(e,t,"committed");if(o.valid){let e=new Map(t.entities.map(e=>[e.id,e])),r=new Set(s.entities.map(e=>e.id));return{ok:!0,root:n(s.rootEntityId,s),changedEntities:s.entities.filter(t=>e.get(t.id)!==t).flatMap(e=>n(e.id,s)??[]),deletedEntityIds:t.entities.map(e=>e.id).filter(e=>!r.has(e)),sideEffects:a(l,i.resolveLocalizable),errors:[]}}return d("uncaught"===o.severity?[{type:"uncaught",entityId:null,message:o.error.message}]:o.entityViolations.filter(({violation:e})=>e.severity===o.severity).map(({entityId:e,violation:t})=>({type:t.type,entityId:e,message:void 0===t.message?null:i.resolveLocalizable(t.message)})))};export const createEntityMeta=(a,u)=>{let c=e=>()=>t(u.manifest,e,a.entity.type).flatMap(t=>{let i=o(e,t,a.entity.id,a.state,u.recipes);return i?[((e,t,i)=>{let{group:n,label:o,description:s,recipes:a}=e,{resolveLocalizable:u}=i.recipes;return{groupId:n.groupId,name:void 0===o?n.instanceName:u(o),description:n.description??(void 0===s?null:u(s)),recipes:a.map(n=>((e,t,i,n)=>{let{key:o,item:s}=e,{resolveLocalizable:a}=n.recipes;return{key:o,name:a(s.title),description:void 0===s.description?null:a(s.description),imageUrl:void 0===s.thumbnailUrl?null:a(s.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,n)=>{let{updates:o,error:s}=((e,t,{entity:i,state:n},{recipes:o})=>{try{return{updates:r(e,t,i.id,n,o),error:void 0}}catch(e){if("child"===t.target.kind)throw e;return{updates:void 0,error:e instanceof Error?e.message:String(e)}}})(e,t,i,n);return void 0===o?d([{type:"uncaught",entityId:null,message:s}]):l(o,i,n)})(e,t,i,n):null}})(n,e,t,i))}})(i,a,u)]:[]});return{...Object.fromEntries(e(u.manifest,a.entity.type).map(e=>[e.edgeName,()=>n(e,a.entity.id,a.state,u.recipes)?.map(t=>({...t,dryRun:()=>e.dryRuns?(({field:e},{value:t},r,n)=>{let{entity:o}=r,a=Object.entries(Object.entries(n.manifest.writableFields??{}).find(([e])=>e===o.type)?.[1]??{}).find(([t])=>t===e)?.[1];if(void 0===a)throw Error(`The options of "${e}" on "${o.id}" cannot be dry-run: the schema lists them, but the configurator has no writable field "${e}" on ${o.type}. This is a fault in the configurator, not in your request. Tell the user this is not available.`);let u=r.state.entities.find(e=>e.id===o.id);if(!u)throw Error(`The options of "${e}" on "${o.id}" cannot be dry-run: entity "${o.id}" does not exist. It may have been deleted by an earlier operation or field. Query the current entities and use an id they return.`);let c={[a]:t},p=n.validateEntity({...u,...c});return p.success?l([s.DomainEntityModification({entityId:o.id,stateDelta:c,updateTag:i})],r,n):d([{type:"uncaught",entityId:o.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${o.id}" an invalid ${o.type}: ${p.errors.join("; ")}. The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(e,t,a,u):null}))??null])),childRecipes:c("child"),replaceRecipes:c("replace"),screenshot:({view:e})=>u.takeScreenshot(a,e)}};

package/dist/configurator/application-runtime/extensions/systems/graphql-system/graphql-system.d.ts

@@ -1,15 +1,35 @@
 import { type ExecutionResult } from 'graphql';
 import { type Localizable } from '@salsita-ai/common/utils';
-import { type $DomainEntity, type DomainContextSelectors, type DomainEntity, type DomainServicesSelectors, type DomainState, type SessionAssistantSetup, type SpecSelectors, type StateUpdateEmission } from '#package/domain';
+import { type $DomainEntity, type AgentScreenshotComponent, type ComponentSnapshot, type DomainContextSelectors, type DomainEntity, type DomainServicesSelectors, type DomainState, type InitializationGeneration, type SessionAssistantSetup, type SpecSelectors, type StateUpdateEmission } from '#package/domain';
 /** One single-operation GraphQL document with its own variables, as executed by {@link GraphQLSystem}. */
 export interface GraphQLOperation {
     readonly document: string;
     readonly variables?: Readonly<Record<string, unknown>>;
     readonly operationName?: string;
 }
+/** A screenshot an operation took, under the label its `image` field returned. */
+export interface GraphQLScreenshot {
+    readonly entityId: string;
+    readonly view: string;
+    /** The id the server stored the picture under, which the tool result references it by. */
+    readonly imageId: string;
+}
 export interface GraphQLSystemContext {
     /** The assistant the initialized session runs: the operations are validated and executed against its schema. */
     readonly getAssistantSetup: () => SessionAssistantSetup;
+    /**
+     * Renders the picture an `agentScreenshot` component of a state declares, behind every export
+     * already queued, as a JPEG or PNG blob; `null` from an executor that renders no pictures. One of
+     * the two async steps of an execution, and the only one that needs a canvas.
+     */
+    readonly renderScreenshot: (component: ComponentSnapshot<AgentScreenshotComponent>, state: AnyDomainState) => Promise<Blob | null>;
+    /**
+     * Stores a rendered screenshot in the assistant thread on the server and resolves with the id the
+     * tool result references it by. The other async step of an execution, run right after each render.
+     */
+    readonly uploadScreenshot: (image: Blob) => Promise<{
+        readonly imageId: string;
+    }>;
     readonly specSelectors: SpecSelectors;
     readonly domainContextSelectors: DomainContextSelectors;
     readonly domainServicesSelectors: DomainServicesSelectors;
@@ -25,6 +45,8 @@ type AnyStateUpdateEmission = StateUpdateEmission<DomainEntity<string>, Record<s
 export interface PreparedOperation {
     readonly result: ExecutionResult;
     readonly emissions: readonly AnyStateUpdateEmission[];
+    /** The screenshots the operation took, by label, in the order they were taken. */
+    readonly screenshots: ReadonlyMap<string, GraphQLScreenshot>;
 }
 /**
  * What {@link GraphQLSystem.execute} returns: the results of the operations as prepared from the
@@ -45,6 +67,8 @@ export interface GraphQLExecution {
      * the undo history by it. It stays in the browser: nothing that leaves it may carry the state.
      */
     readonly preparedState?: AnyDomainState;
+    /** The screenshots the operations took, by the label their `image` field returned, in the order they were taken. */
+    readonly screenshots: ReadonlyMap<string, GraphQLScreenshot>;
 }
 /**
  * Resolves a localizable value, or each item of a list of them, to a string in the current locale.
@@ -77,6 +101,17 @@ export declare class GraphQLSystem {
     /** Root field resolvers, called by the executor with the field arguments and the operation context. */
     private readonly _rootValue;
     private readonly _resolveType;
+    private _generation;
+    /**
+     * The picture of an entity of a state from one `agentScreenshot` view, as a blob of the view's
+     * file format; `null` when the view is not attached to the entity there or nothing renders it.
+     */
+    private readonly _renderScreenshot;
+    /**
+     * Starts a new generation for a new configuration load. Screenshots wait on renders that take
+     * seconds, so an execution can outlive its configuration: one started under the ended generation
+     * renders no more screenshots and commits nothing, not even on a conflict retry.
+     */
     initialize: () => void;
     /**
      * Runs one mutation field against the working state: its implementation computes updates from the
@@ -87,6 +122,13 @@ export declare class GraphQLSystem {
      */
     private readonly _resolveMutation;
     private readonly _runMutation;
+    /**
+     * Takes a screenshot once every one asked for before it in the execution has been taken, so they
+     * render in document order, and uploads it as soon as it has rendered. A failure nulls only its
+     * own field and fails nothing else: the user kept changing the configuration, rendering failed,
+     * or the server did not store the picture.
+     */
+    private readonly _takeScreenshot;
     private readonly _setup;
     /**
      * Parses, validates and executes one operation document. Validation adds the rule against
@@ -97,22 +139,27 @@ export declare class GraphQLSystem {
     /**
      * Runs the operations in order through one working state that starts at `originalState`: a query
      * reads the current working state, and each mutation field advances it with its own emission.
-     * The lenses an operation spreads are injected into its document first. Nothing is committed. The first operation that fails stops the list; every later one gets a
-     * "not run" error instead.
+     * The closing braces an operation's document left off are added, then the lenses it spreads are injected into it. Nothing is committed. The first operation that fails stops the list; every later one gets a
+     * "not run" error instead. Screenshots render only while `generation`, the current one by
+     * default, is active.
      */
-    prepare: (originalState: AnyDomainState, operations: readonly GraphQLOperation[]) => Promise<readonly PreparedOperation[]>;
+    prepare: (originalState: AnyDomainState, operations: readonly GraphQLOperation[], generation?: InitializationGeneration) => Promise<readonly PreparedOperation[]>;
     /**
      * The side effects of prepared operations: the hints of every update of their emissions, as the
      * agent is told them, in applied order.
      */
     readSideEffects: (prepared: readonly PreparedOperation[]) => readonly string[];
+    /** The screenshots of prepared operations, by label, in the order they were taken. */
+    readScreenshots: (prepared: readonly PreparedOperation[]) => ReadonlyMap<string, GraphQLScreenshot>;
     private readonly _prepareAndCommit;
     /**
      * Prepares the operations from the committed state and commits their changes as one emission,
      * synthesized from every field emission of the list: one undo step, `onBeforeCommit` hooks run once. Nothing is committed when an operation fails or
      * none changes anything. When the committed state changed meanwhile, the operations are prepared
      * once more from the new committed state; their earlier updates are never replayed, since they
-     * were computed from a state that is gone.
+     * were computed from a state that is gone. When another configuration was loaded meanwhile,
+     * nothing is committed or prepared again: the operations were written for the configuration
+     * that was left.
      */
     execute: (operations: readonly GraphQLOperation[]) => Promise<GraphQLExecution>;
 }

package/dist/configurator/application-runtime/extensions/systems/graphql-system/graphql-system.js

@@ -1 +1 @@
-import{GraphQLError as e,NoSchemaIntrospectionCustomRule as t,defaultFieldResolver as i,execute as o,getNamedType as n,parse as r,specifiedRules as a,validate as s,validateSchema as l}from"graphql";import{assertExistence as c,createSelector as d,isMessageDescriptor as h,isMultilingualString as u}from"@salsita-ai/common/utils";import{DomainEntityIdSchema as m,createAssistantExecutionSchema as f,findAssistantMutation as p}from"#package/domain";import{createEntityMeta as g}from"./entity-meta.js";import{injectAssistantLenses as y}from"./inject-assistant-lenses.js";import{readSideEffects as v}from"./side-effects.js";let S={errors:[new e("The configurator does not provide this request. This is a fault in the configurator, not in your request. Tell the user this is not available.")]},_={errors:[new e("The configuration is not loaded yet, so there is no state to query. Run the query again once the configurator has finished loading.")]},x=new RegExp(m.pattern),w=[...a,t],E=e=>"object"==typeof e&&null!==e&&"type"in e&&"string"==typeof e.type&&"id"in e&&"string"==typeof e.id,$=(e,t)=>"object"==typeof e&&null!==e?Reflect.get(e,t):void 0,b=e=>e instanceof Error?e.message:String(e),T=e=>/[.!?]$/.test(e)?e:`${e}.`,C=e=>"object"==typeof e&&null!==e&&Object.getPrototypeOf(e)===Object.prototype,R=(e,t)=>{let i=C(e)?e._raw:void 0;if(E(i))return i;if(!Array.isArray(e)&&!C(e))return e;if(t.has(e))throw Error("The value contains itself.");let o=new Set([...t,e]);return Array.isArray(e)?e.map(e=>R(e,o)):Object.fromEntries(Object.entries(e).map(([e,t])=>[e,R(t,o)]))};export const localize=(e,t)=>Array.isArray(e)?e.map(e=>localize(e,t)):"string"==typeof e||h(e)||u(e)?t(e):e;let j=t=>new e(`The configurator cannot handle this request: ${T(t)} This is a fault in the configurator, not in your request. Tell the user this is not available.`),A=e=>(e.errors?.length??0)>0,M=t=>({errors:[new e(`Not run: operation ${t+1} failed, so the operations after it were skipped and no change of the list takes effect. Fix the failing operation and send the whole list again.`)]});export class GraphQLSystem{_context;_selectSchema=d([d.leaf(e=>e)],e=>{try{let t=f(e),i=l(t);return i.length>0?j(i.map(e=>e.message).join(" ")):t}catch(e){return j(b(e))}});_selectLenses=d([d.leaf(e=>e)],e=>r(e));_selectFieldResolver=d([d.leaf(e=>e)],t=>(o,r,a,s)=>{if(s.parentType===s.schema.getQueryType())return i(o,r,a,s);if(s.parentType===s.schema.getMutationType())return this._resolveMutation(s.fieldName,String(s.path.key),r,a);if(!E(o))return i(o,r,a,s);if("meta"===s.fieldName){let e;return g({entity:o,state:("object"==typeof(e=$(o,"_state"))&&null!==e&&"entities"in e&&"rootEntityId"in e?e:void 0)??a.state},{manifest:a.manifest,recipes:this._recipeContext(),prepareStateEmission:(e,t,i)=>this._context.domainContextSelectors.getStoreSystem().prepareStateEmission(e,t,i),find$Entity:(e,t)=>this._find$Entity(e,t),validateEntity:e=>this._context.domainContextSelectors.getDomain().validateEntity(e)})}let{source:l,localized:c}=t[s.parentType.name]?.[s.fieldName]??{source:s.fieldName},d=((t,i)=>{try{return $(t,i)}catch(o){throw new e(`Expression "${i}" failed on ${E(t)?t.id:"an entity"}: ${T(b(o))} This is a fault in the configurator, not in your request. Tell the user this is not available.`,{originalError:o instanceof Error?o:void 0})}})(o,l);return c?localize(d,this._context.domainServicesSelectors.getResolveLocalizable()):l.startsWith("$")&&"JSON"===n(s.returnType).name?((t,i,o)=>{try{return R(o,new Set)}catch(o){throw new e(`Expression "${i}" returned a value that is not plain serializable data on ${E(t)?t.id:"an entity"}: ${T(b(o))} This is a fault in the configurator, not in your request. Tell the user this is not available.`,{originalError:o instanceof Error?o:void 0})}})(o,l,d):d});constructor(e){this._context=e}_get$Entity=(e,t)=>this._context.domainContextSelectors.getDomain().get$Entity(e,t);_find$Entity=(e,t)=>this._context.domainContextSelectors.getDomain().getEntity(e,t)?this._get$Entity(e,t):null;_recipeContext=()=>({componentReader:this._context.domainContextSelectors.getComponentReader(),recipeCooker:this._context.domainContextSelectors.getRecipeCookerSystem(),resolveLocalizable:this._context.domainServicesSelectors.getResolveLocalizable()});_rootValue={root:(e,{state:t})=>this._get$Entity(t.rootEntityId,t),entities:({ids:t},{state:i})=>{if(null==t)return i.entities.map(e=>this._get$Entity(e.id,i));var o=i.rootEntityId;let n=t.filter(e=>!x.test(e));if(n.length>0)throw new e(`${n.map(e=>`"${e}"`).join(", ")} ${1===n.length?"is not an entity id":"are not entity ids"}. Entity ids have the form "<Type>-<number>", e.g. "${o}". Use ids as returned by the "id" field.`);return t.map(e=>x.test(e)?this._find$Entity(e,i):null)},selectedEntity:(e,{state:t})=>this._find$Entity(this._context.domainContextSelectors.getNavigationSystem().getActiveSelectionState(t),t),navigation:(e,{state:t})=>{let i=this._context.domainContextSelectors.getNavigationSystem();return{navigationState:i.getActiveNavigationState(t),viewState:i.getActiveViewState(t),toolState:i.getActiveToolState(t)}}};_resolveType=e=>E(e)?e.type:void 0;initialize=()=>{};_resolveMutation=(t,i,o,n)=>{if(void 0!==n.failedMutationField)throw new e(`Not run: the earlier field "${n.failedMutationField}" of this operation failed, so "${i}" was skipped and no change of the operation takes effect. Fix the failing field and send the operation again.`);try{return this._runMutation(t,o,n)}catch(e){throw n.failedMutationField=i,e}};_runMutation=(t,i,o)=>{let n=p(t,o.manifest);if(!n)throw new e(`The schema declares the mutation "${t}", but the configurator has no implementation for it. This is a fault in the configurator, not in your request. Tell the user this is not available.`);let r=o.state,a=n.implementation(i,r,{manifest:o.manifest,action:this._context.domainContextSelectors.getActionSystem().createContext(r),resolveLocalizable:this._context.domainServicesSelectors.getResolveLocalizable()});if(a.updates.length>0){let i=this._context.domainContextSelectors.getStoreSystem().prepareStateEmission(a.updates,r,"committed");if(!i.validity.valid)throw new e(`The changes of "${t}" were not applied, because the resulting configuration is invalid: ${(e=>{if("uncaught"===e.severity)return`validating it threw: ${T(b(e.error))}`;let t=[...new Set(e.entityViolations.filter(({violation:t})=>t.severity===e.severity).map(({entityId:e})=>e))];return`it has ${e.severity} violations on ${t.join(", ")}.`})(i.validity)} Change the request so the configuration stays valid.`);o.emissions.push(i),o.state=i.state}return a.readResult({previousState:r,state:o.state})};_setup=()=>{let{manifest:t,error:i}=this._context.getAssistantSetup();if(i)return{ready:!1,result:{errors:[new e(i.message,{originalError:i})]}};if(!t)return{ready:!1,result:S};let o=this._selectSchema(t.sdl);return o instanceof e?{ready:!1,result:{errors:[o]}}:{ready:!0,assistant:t,schema:o,lenses:t.lenses?.definitions?this._selectLenses(t.lenses.definitions):void 0,fieldResolver:this._selectFieldResolver(t.fields)}};_run=(t,i,n,a)=>{let l;try{l=r(t)}catch(t){return{errors:[t instanceof e?t:new e(b(t))]}}let c=s(n.schema,l,w);return c.length>0?{errors:c}:o({schema:n.schema,document:l,rootValue:this._rootValue,contextValue:a,variableValues:i.variables,operationName:i.operationName,fieldResolver:n.fieldResolver,typeResolver:this._resolveType})};prepare=async(t,i)=>{let o,n=this._setup();if(!n.ready)return i.map(()=>({result:n.result,emissions:[]}));let r={manifest:n.assistant,state:t,emissions:[],failedMutationField:void 0},a=[];for(let[t,s]of i.entries())if(void 0===o){let i=r.emissions.length;r.failedMutationField=void 0;let l=n.lenses?y(s.document,n.lenses):s.document,c=l instanceof e?{errors:[l]}:await this._run(l,s,n,r);a.push({result:c,emissions:r.emissions.slice(i)}),A(c)&&(o=t)}else a.push({result:M(o),emissions:[]});return a};readSideEffects=e=>{let t=this._context.domainServicesSelectors.getResolveLocalizable();return e.flatMap(({emissions:e})=>e.flatMap(e=>v(e.updates,t)))};_prepareAndCommit=async e=>{let t,i,o,n=this._context.domainContextSelectors.getStoreSystem(),r=await this.prepare(n.stateSlices.committed.value.state,e),a=r.map(({result:e})=>e),s=this.readSideEffects(r),l=r.flatMap(e=>e.emissions);if(a.some(A)||0===l.length)return{results:a,sideEffects:s,outcome:"none"};let d=(t=c(l[0]),i=c(l[l.length-1]),o=l.some(e=>void 0!==e.transformationLog),{kind:"committed",previousState:t.previousState,state:i.state,updates:l.flatMap(e=>e.updates),validity:i.validity,transformationLog:o?l.flatMap(e=>e.transformationLog??[]):void 0});return{results:a,sideEffects:s,outcome:n.commitPrepared(d),preparedState:d.state}};execute=async e=>{if(!this._context.domainContextSelectors.getStoreSystem().isInitialized)return{results:e.map(()=>_),committed:!1,sideEffects:[]};let t=await this._prepareAndCommit(e),{results:i,sideEffects:o,outcome:n,preparedState:r}="conflict"===t.outcome?await this._prepareAndCommit(e):t;return"committed"===n?{results:i,committed:!0,sideEffects:o,preparedState:r}:"held"===n?{results:i,committed:!1,message:"The changes wait for the user's approval and are not applied yet. Do not send them again; the next `[changes]` block lists them once approved.",sideEffects:o,preparedState:r}:"conflict"===n?{results:i,committed:!1,message:"The changes were not committed, because the configuration changed while they were being applied. The results describe a state that was discarded. Query the current configuration and send the operations again if they still make sense.",sideEffects:o}:{results:i,committed:!1,sideEffects:o}}}
+import{GraphQLError as e,NoSchemaIntrospectionCustomRule as t,defaultFieldResolver as i,execute as n,getNamedType as o,parse as r,specifiedRules as s,validate as a,validateSchema as l}from"graphql";import{assertExistence as c,createSelector as h,isMessageDescriptor as d,isMultilingualString as u}from"@salsita-ai/common/utils";import{DomainEntityIdSchema as f,agentScreenshotComponent as m,createAssistantExecutionSchema as p,findAssistantMutation as g}from"#package/domain";import{ExportBusyError as y}from"../export-system/export-busy-error.js";import{closeUnclosedBraces as v}from"./close-unclosed-braces.js";import{createEntityMeta as S}from"./entity-meta.js";import{injectAssistantLenses as _}from"./inject-assistant-lenses.js";import{readSideEffects as w}from"./side-effects.js";let x={errors:[new e("The configurator does not provide this request. This is a fault in the configurator, not in your request. Tell the user this is not available.")]},$={errors:[new e("The configuration is not loaded yet, so there is no state to query. Run the query again once the configurator has finished loading.")]},b="Not taken: another configuration was loaded while this request ran. Query the current configuration before asking for screenshots again.",E=new RegExp(f.pattern),T=[...s,t],C=e=>"object"==typeof e&&null!==e&&"type"in e&&"string"==typeof e.type&&"id"in e&&"string"==typeof e.id,M=(e,t)=>"object"==typeof e&&null!==e?Reflect.get(e,t):void 0,j=e=>e instanceof Error?e.message:String(e),k=e=>/[.!?]$/.test(e)?e:`${e}.`,R=e=>"object"==typeof e&&null!==e&&Object.getPrototypeOf(e)===Object.prototype,N=(e,t)=>{let i=R(e)?e._raw:void 0;if(C(i))return i;if(!Array.isArray(e)&&!R(e))return e;if(t.has(e))throw Error("The value contains itself.");let n=new Set([...t,e]);return Array.isArray(e)?e.map(e=>N(e,n)):Object.fromEntries(Object.entries(e).map(([e,t])=>[e,N(t,n)]))};export const localize=(e,t)=>Array.isArray(e)?e.map(e=>localize(e,t)):"string"==typeof e||d(e)||u(e)?t(e):e;let A=t=>new e(`The configurator cannot handle this request: ${k(t)} This is a fault in the configurator, not in your request. Tell the user this is not available.`),q="SCREENSHOT_NOT_TAKEN",z=(t,i)=>new e(t,{originalError:i,extensions:{code:q}}),L=e=>(e.errors??[]).some(e=>e.extensions.code!==q),F=t=>({errors:[new e(`Not run: operation ${t+1} failed, so the operations after it were skipped and no change of the list takes effect. Fix the failing operation and send the whole list again.`)]});export class GraphQLSystem{_context;_selectSchema=h([h.leaf(e=>e)],e=>{try{let t=p(e),i=l(t);return i.length>0?A(i.map(e=>e.message).join(" ")):t}catch(e){return A(j(e))}});_selectLenses=h([h.leaf(e=>e)],e=>r(e));_selectFieldResolver=h([h.leaf(e=>e)],t=>(n,r,s,a)=>{if(a.parentType===a.schema.getQueryType())return i(n,r,s,a);if(a.parentType===a.schema.getMutationType())return this._resolveMutation(a.fieldName,String(a.path.key),r,s);if(!C(n))return i(n,r,s,a);if("meta"===a.fieldName){let e;return S({entity:n,state:("object"==typeof(e=M(n,"_state"))&&null!==e&&"entities"in e&&"rootEntityId"in e?e:void 0)??s.state},{manifest:s.manifest,recipes:this._recipeContext(),prepareStateEmission:(e,t,i)=>this._context.domainContextSelectors.getStoreSystem().prepareStateEmission(e,t,i),find$Entity:(e,t)=>this._find$Entity(e,t),validateEntity:e=>this._context.domainContextSelectors.getDomain().validateEntity(e),takeScreenshot:(e,t)=>this._takeScreenshot(e,t,s)})}let{source:l,localized:c}=t[a.parentType.name]?.[a.fieldName]??{source:a.fieldName},h=((t,i)=>{try{return M(t,i)}catch(n){throw new e(`Expression "${i}" failed on ${C(t)?t.id:"an entity"}: ${k(j(n))} This is a fault in the configurator, not in your request. Tell the user this is not available.`,{originalError:n instanceof Error?n:void 0})}})(n,l);return c?localize(h,this._context.domainServicesSelectors.getResolveLocalizable()):l.startsWith("$")&&"JSON"===o(a.returnType).name?((t,i,n)=>{try{return N(n,new Set)}catch(n){throw new e(`Expression "${i}" returned a value that is not plain serializable data on ${C(t)?t.id:"an entity"}: ${k(j(n))} This is a fault in the configurator, not in your request. Tell the user this is not available.`,{originalError:n instanceof Error?n:void 0})}})(n,l,h):h});constructor(e){this._context=e}_get$Entity=(e,t)=>this._context.domainContextSelectors.getDomain().get$Entity(e,t);_find$Entity=(e,t)=>this._context.domainContextSelectors.getDomain().getEntity(e,t)?this._get$Entity(e,t):null;_recipeContext=()=>({componentReader:this._context.domainContextSelectors.getComponentReader(),recipeCooker:this._context.domainContextSelectors.getRecipeCookerSystem(),resolveLocalizable:this._context.domainServicesSelectors.getResolveLocalizable()});_rootValue={root:(e,{state:t})=>this._get$Entity(t.rootEntityId,t),entities:({ids:t},{state:i})=>{if(null==t)return i.entities.map(e=>this._get$Entity(e.id,i));var n=i.rootEntityId;let o=t.filter(e=>!E.test(e));if(o.length>0)throw new e(`${o.map(e=>`"${e}"`).join(", ")} ${1===o.length?"is not an entity id":"are not entity ids"}. Entity ids have the form "<Type>-<number>", e.g. "${n}". Use ids as returned by the "id" field.`);return t.map(e=>E.test(e)?this._find$Entity(e,i):null)},selectedEntity:(e,{state:t})=>this._find$Entity(this._context.domainContextSelectors.getNavigationSystem().getActiveSelectionState(t),t),navigation:(e,{state:t})=>{let i=this._context.domainContextSelectors.getNavigationSystem();return{navigationState:i.getActiveNavigationState(t),viewState:i.getActiveViewState(t),toolState:i.getActiveToolState(t)}}};_resolveType=e=>C(e)?e.type:void 0;_generation={active:!0};_renderScreenshot=async(e,t,i)=>{let n=this._context.domainContextSelectors.getComponentReader().readOneComponent({entityId:e,componentType:m,instanceName:t},i);if(!n)return null;let o=await this._context.renderScreenshot(n,i);return null===o?null:new Blob([o],{type:"JPEG"===n.state.fileFormat?"image/jpeg":"image/png"})};initialize=()=>{this._generation.active=!1,this._generation={active:!0}};_resolveMutation=(t,i,n,o)=>{if(void 0!==o.failedMutationField)throw new e(`Not run: the earlier field "${o.failedMutationField}" of this operation failed, so "${i}" was skipped and no change of the operation takes effect. Fix the failing field and send the operation again.`);try{return this._runMutation(t,n,o)}catch(e){throw o.failedMutationField=i,e}};_runMutation=(t,i,n)=>{let o=g(t,n.manifest);if(!o)throw new e(`The schema declares the mutation "${t}", but the configurator has no implementation for it. This is a fault in the configurator, not in your request. Tell the user this is not available.`);let r=n.state,s=o.implementation(i,r,{manifest:n.manifest,action:this._context.domainContextSelectors.getActionSystem().createContext(r),resolveLocalizable:this._context.domainServicesSelectors.getResolveLocalizable()});if(s.updates.length>0){let i=this._context.domainContextSelectors.getStoreSystem().prepareStateEmission(s.updates,r,"committed");if(!i.validity.valid)throw new e(`The changes of "${t}" were not applied, because the resulting configuration is invalid: ${(e=>{if("uncaught"===e.severity)return`validating it threw: ${k(j(e.error))}`;let t=[...new Set(e.entityViolations.filter(({violation:t})=>t.severity===e.severity).map(({entityId:e})=>e))];return`it has ${e.severity} violations on ${t.join(", ")}.`})(i.validity)} Change the request so the configuration stays valid.`);n.emissions.push(i),n.state=i.state}return s.readResult({previousState:r,state:n.state})};_takeScreenshot=({entity:t,state:i},n,o)=>{let r=o.manifest.screenshots?.[t.type]?.find(e=>e.view===n);if(!r)return Promise.reject(new e(`The schema declares the screenshot view "${n}" on ${t.type}, but the configurator has no view of that name. This is a fault in the configurator, not in your request. Tell the user this is not available.`));let s=o.lastScreenshot.then(async()=>{if(!o.generation.active)throw z(b);let e=await this._renderScreenshot(t.id,r.instanceName,i).catch(e=>{throw z(e instanceof y?"User made concurrent actions that prevented the screenshot from being taken, try again":`The screenshot of ${t.id} from "${n}" could not be taken: ${k(j(e))} Try again; if it fails again, tell the user the screenshot is not available.`,e instanceof Error?e:void 0)});if(!o.generation.active)throw z(b);if(null===e)return null;let{imageId:s}=await this._context.uploadScreenshot(e).catch(e=>{throw z(`The screenshot of ${t.id} from "${n}" was taken but could not be stored: ${k(j(e))} Try again; if it fails again, tell the user the screenshot is not available.`,e instanceof Error?e:void 0)}),a=`${t.id}/${n}`,l=[...o.screenshots.values()].filter(e=>e.entityId===t.id&&e.view===n).length,c=0===l?a:`${a}#${l+1}`;return o.screenshots.set(c,{entityId:t.id,view:n,imageId:s}),{image:c}});return o.lastScreenshot=s.catch(()=>void 0),s};_setup=()=>{let{manifest:t,error:i}=this._context.getAssistantSetup();if(i)return{ready:!1,result:{errors:[new e(i.message,{originalError:i})]}};if(!t)return{ready:!1,result:x};let n=this._selectSchema(t.sdl);return n instanceof e?{ready:!1,result:{errors:[n]}}:{ready:!0,assistant:t,schema:n,lenses:t.lenses?.definitions?this._selectLenses(t.lenses.definitions):void 0,fieldResolver:this._selectFieldResolver(t.fields)}};_run=(t,i,o,s)=>{let l;try{l=r(t)}catch(t){return{errors:[t instanceof e?t:new e(j(t))]}}let c=a(o.schema,l,T);return c.length>0?{errors:c}:n({schema:o.schema,document:l,rootValue:this._rootValue,contextValue:s,variableValues:i.variables,operationName:i.operationName,fieldResolver:o.fieldResolver,typeResolver:this._resolveType})};prepare=async(t,i,n=this._generation)=>{let o,r=this._setup();if(!r.ready)return i.map(()=>({result:r.result,emissions:[],screenshots:new Map}));let s={manifest:r.assistant,state:t,emissions:[],failedMutationField:void 0,screenshots:new Map,lastScreenshot:Promise.resolve(),generation:n},a=[];for(let[t,n]of i.entries())if(void 0===o){let i=s.emissions.length,l=s.screenshots.size;s.failedMutationField=void 0;let c=v(n.document),h=r.lenses?_(c,r.lenses):c,d=h instanceof e?{errors:[h]}:await this._run(h,n,r,s);await s.lastScreenshot,a.push({result:d,emissions:s.emissions.slice(i),screenshots:new Map([...s.screenshots].slice(l))}),L(d)&&(o=t)}else a.push({result:F(o),emissions:[],screenshots:new Map});return a};readSideEffects=e=>{let t=this._context.domainServicesSelectors.getResolveLocalizable();return e.flatMap(({emissions:e})=>e.flatMap(e=>w(e.updates,t)))};readScreenshots=e=>new Map(e.flatMap(({screenshots:e})=>[...e]));_prepareAndCommit=async(e,t)=>{let i,n,o,r=this._context.domainContextSelectors.getStoreSystem(),s=await this.prepare(r.stateSlices.committed.value.state,e,t),a=s.map(({result:e})=>e),l=this.readSideEffects(s),h=this.readScreenshots(s),d=s.flatMap(e=>e.emissions);if(!t.active)return{results:a,sideEffects:l,screenshots:h,outcome:"conflict"};if(a.some(L)||0===d.length)return{results:a,sideEffects:l,screenshots:h,outcome:"none"};let u=(i=c(d[0]),n=c(d[d.length-1]),o=d.some(e=>void 0!==e.transformationLog),{kind:"committed",previousState:i.previousState,state:n.state,updates:d.flatMap(e=>e.updates),validity:n.validity,transformationLog:o?d.flatMap(e=>e.transformationLog??[]):void 0});return{results:a,sideEffects:l,screenshots:h,outcome:r.commitPrepared(u),preparedState:u.state}};execute=async e=>{let t=this._generation;if(!this._context.domainContextSelectors.getStoreSystem().isInitialized)return{results:e.map(()=>$),committed:!1,sideEffects:[],screenshots:new Map};let i=await this._prepareAndCommit(e,t),{results:n,sideEffects:o,screenshots:r,outcome:s,preparedState:a}="conflict"===i.outcome&&t.active?await this._prepareAndCommit(e,t):i;return"committed"===s?{results:n,committed:!0,sideEffects:o,screenshots:r,preparedState:a}:"held"===s?{results:n,committed:!1,message:"The changes wait for the user's approval and are not applied yet. Do not send them again; the next `[changes]` block lists them once approved.",sideEffects:o,screenshots:r,preparedState:a}:"conflict"===s?{results:n,committed:!1,message:"The changes were not committed, because the configuration changed while they were being applied. The results describe a state that was discarded. Query the current configuration and send the operations again if they still make sense.",sideEffects:o,screenshots:r}:{results:n,committed:!1,sideEffects:o,screenshots:r}}}

package/dist/configurator/application-runtime/extensions/systems/image-rendering-system/image-rendering-system.d.ts

@@ -1,8 +1,9 @@
 import type { EffectComposer } from 'postprocessing';
 import { Color, OrthographicCamera, PerspectiveCamera } from 'three';
 import type { AuthorizedPhoenixApiClient } from '#package/client';
-import type { ClientSideImageComponent, ComponentSnapshot, DomainContextSelectors, DomainEntity, DomainServicesSelectors, DomainState, SaveTemplateThumbnailComponent } from '#package/domain';
+import type { AgentScreenshotComponent, ClientSideImageComponent, ComponentSnapshot, DomainContextSelectors, DomainEntity, DomainServicesSelectors, DomainState, SaveTemplateThumbnailComponent } from '#package/domain';
 import type { ConfiguratorExtensionSelectors } from '../../selectors.js';
+import type { ExportRunOptions } from '../export-system/export-system.js';
 import type { ImageRenderConfig, ImageRenderer, RenderConfig } from './image-renderer.js';
 /**
  * Constructor context of an `ImageRenderingSystem`. Same-layer configurator peers are reached
@@ -20,6 +21,8 @@ export interface ClientSideImageRenderingOptions {
     /** Opens rendered images in new browser tabs instead of uploading them. */
     readonly debug?: boolean;
 }
+/** A component that declares an image the export renders: its state says how, its entity what. */
+type ImageComponentSnapshot = ComponentSnapshot<ClientSideImageComponent> | ComponentSnapshot<SaveTemplateThumbnailComponent> | ComponentSnapshot<AgentScreenshotComponent>;
 /** ImageRenderingSystem with its entity types erased — how the runtime selectors expose the instance. */
 export type AnyImageRenderingSystem = ImageRenderingSystem<any>;
 export declare class ImageRenderingSystem<ENTITIES extends DomainEntity<string>> {
@@ -94,7 +97,7 @@ export declare class ImageRenderingSystem<ENTITIES extends DomainEntity<string>>
     generateAndUploadDeclaredClientSideImages(state: DomainState<ENTITIES>, finalizationUuid: string, options?: ClientSideImageRenderingOptions): Promise<readonly {
         name: string;
         blob: Blob;
-        imageComponent: ComponentSnapshot<ClientSideImageComponent> | ComponentSnapshot<SaveTemplateThumbnailComponent>;
+        imageComponent: ImageComponentSnapshot;
     }[]>;
     /**
      * Generates client side images from declarative clientSideImage components without uploading them.
@@ -102,12 +105,18 @@ export declare class ImageRenderingSystem<ENTITIES extends DomainEntity<string>>
     generateDeclaredClientSideImages(state: DomainState<ENTITIES>, options?: ClientSideImageRenderingOptions): Promise<readonly {
         name: string;
         blob: Blob;
-        imageComponent: ComponentSnapshot<ClientSideImageComponent> | ComponentSnapshot<SaveTemplateThumbnailComponent>;
+        imageComponent: ImageComponentSnapshot;
     }[]>;
-    generateImagesFromComponents(imageComponents: ReadonlyArray<ComponentSnapshot<ClientSideImageComponent> | ComponentSnapshot<SaveTemplateThumbnailComponent>>, sourceState: DomainState<ENTITIES>, options?: ClientSideImageRenderingOptions): Promise<ReadonlyArray<{
+    /**
+     * Renders the image components from the given state in one export run. With `awaitSettledState`,
+     * the run waits until the user is not in the middle of a change, as the assistant's screenshots do.
+     */
+    generateImagesFromComponents(imageComponents: ReadonlyArray<ImageComponentSnapshot>, sourceState: DomainState<ENTITIES>, options?: ClientSideImageRenderingOptions, runOptions?: ExportRunOptions): Promise<ReadonlyArray<{
         name: string;
         blob: Blob;
-        imageComponent: ComponentSnapshot<ClientSideImageComponent> | ComponentSnapshot<SaveTemplateThumbnailComponent>;
+        imageComponent: ImageComponentSnapshot;
     }>>;
+    private _generateImagesFromComponents;
     initialize: () => void;
 }
+export {};

package/dist/configurator/application-runtime/extensions/systems/image-rendering-system/image-rendering-system.js

@@ -1 +1 @@
-import{Color as e,HalfFloatType as t,NoToneMapping as r,OrthographicCamera as a,PerspectiveCamera as n,WebGLRenderTarget as o}from"three";import{preloadFont as i}from"troika-three-text";import{match as s}from"ts-pattern";import{clientSideImageComponent as l,dimensionIndicatorComponent as c,domainEntityTypeFromId as m,editableDistanceDimensionIndicatorComponent as g,isDomainEntityId as d,isVirtualEntityId as h,sketchingEditComponent as u}from"#package/domain";import{createCameraControls as f}from"../camera-control-system/create-camera-controls.js";import{createCanvasFreezeFrame as p}from"./canvas-freeze-frame.js";import{ExportCapturePass as w,readTargetToBlob as C,resolveExportBackground as _}from"./export-image-capture.js";export class ImageRenderingSystem{_context;_renderer=null;_effectComposer=null;_generation=null;_debugObjectUrls=new Set;_canvasFreeze=null;constructor(e){this._context=e}_captureGenerationAssertion=()=>{let e=this._generation,t=()=>{if(!e?.active)throw Error("Image rendering generation ended while images were being rendered! The configurator context was reinitialized before the renderer finished, so the results belong to a configuration that is no longer active. Await the render before leaving the configuration, or discard the rejection.")};return t(),t};_captureGenerationGuard=()=>{let e=this._captureGenerationAssertion();return{assertActive:e,waitFor:async t=>{let r=await t;return e(),r},runEffect:t=>(e(),t())}};register(e){return this._renderer=e,()=>{this._renderer===e&&(this._renderer=null)}}registerEffectComposer(e){return this._effectComposer=e,()=>{this._effectComposer===e&&(this._effectComposer=null)}}_openDebugImage=e=>{let t=URL.createObjectURL(e);this._debugObjectUrls.add(t),window.open(t,"_blank")};_getRenderer=async()=>{let e=this._generation,t=Date.now(),r=()=>{if(!e?.active)throw Error("Image rendering generation ended while waiting for the renderer! The configurator context was reinitialized before the renderer arrived, so the render would target a scene that is gone. Await the render before leaving the configuration, or discard the rejection.")};r();let a=this._renderer;for(;null===a;){if(await new Promise(e=>setTimeout(e,50)),r(),Date.now()-t>1e4)throw Error("Renderer could not be retrieved! Reached timeout.");a=this._renderer}return a};generateImageUsingOriginalCanvas=async(e,t,r=!1)=>{let a=this._captureGenerationGuard(),n=await a.waitFor(this._getRenderer());if(r){let{blob:e}=await a.waitFor(a.runEffect(()=>n.renderUsingOriginalCanvas(t)));a.runEffect(()=>this._openDebugImage(e));return}let o=await Promise.all([t].map(async e=>{let{blob:t}=await a.waitFor(a.runEffect(()=>n.renderUsingOriginalCanvas(e)));return{blob:t,name:e.name}})),i=await a.waitFor(a.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),e,[t.name])));await Promise.all(i.map(async e=>{let t=o.find(t=>t.name===e.name);if(null==t)throw Error("Blob not found!");await Promise.all(i.map(async e=>{await a.waitFor(a.runEffect(()=>fetch(e.url,{method:"PUT",body:t.blob,headers:{"Content-Type":"image/png","Content-Length":t.blob.size.toString()}})))}))}))};async generateImagesUsingOriginalCanvas(e,t,r=!1){let a=this._captureGenerationGuard(),n=await a.waitFor(this._getRenderer()),o=Array.isArray(t)?t:[t],i=await o.reduce(async(e,t)=>[...await e,await a.waitFor(a.runEffect(()=>n.renderUsingOriginalCanvas(t)))],Promise.resolve([]));if(r){for(let e of i)a.runEffect(()=>this._openDebugImage(e.blob)),await a.waitFor(new Promise(e=>setTimeout(e,100)));return}let s=o.map(e=>e.name),l=await a.waitFor(a.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),e,s)));await Promise.all(l.map(async e=>{let t=i.find(t=>t.name===e.name);if(null==t)throw Error("Blob not found!");await Promise.all(l.map(async e=>{await a.waitFor(a.runEffect(()=>fetch(e.url,{method:"PUT",body:t.blob,headers:{"Content-Type":"image/png","Content-Length":t.blob.size.toString()}})))}))}))}async generateImages(e,t,r=!1){let a=this._captureGenerationGuard(),n=await a.waitFor(this._getRenderer()),o=t.map(e=>e.name);if(r)return void await Promise.all(t.map(async e=>{let t=await a.waitFor(a.runEffect(()=>n.renderImage(e)));a.runEffect(()=>this._openDebugImage(t))}));let i=await Promise.all(t.map(async e=>({blob:await a.waitFor(a.runEffect(()=>n.renderImage(e))),name:e.name}))),s=await a.waitFor(a.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),e,o)));await Promise.all(s.map(async e=>{let t=i.find(t=>t.name===e.name);if(null==t)throw Error("Blob not found!");await Promise.all(s.map(async e=>{await a.waitFor(a.runEffect(()=>fetch(e.url,{method:"PUT",body:t.blob,headers:{"Content-Type":"image/png","Content-Length":t.blob.size.toString()}})))}))}))}async getGeneratedImages(e,t=!1){let r=this._captureGenerationAssertion(),a=await this._getRenderer();return(r(),t)?(await Promise.all(e.map(async e=>{let t=await a.renderImage(e);r(),this._openDebugImage(t)})),[]):Promise.all(e.map(async e=>{let t=await a.renderImage(e);return r(),{blob:t,name:e.name}}))}_renderCurrentView=e=>{let{gl:t,scene:r,camera:a}=e.get();null!==this._effectComposer?this._effectComposer.render():t.render(r,a)};_freezeCanvas=e=>{this._canvasFreeze?.handle===e?this._canvasFreeze.holders+=1:(this._canvasFreeze?.remove(),this._canvasFreeze={handle:e,remove:p(e.get().gl.domElement,()=>this._renderCurrentView(e)),resumeFrameloop:this._context.configuratorExtensionSelectors.getExportSystem().pauseFrameloop(e),holders:1});let t=this._canvasFreeze,r=!1;return async()=>{if(!r&&(r=!0,t.holders-=1,!(t.holders>0)))try{let r=this._context.configuratorExtensionSelectors.getCanvasSystem();r.r3fHandle$.value===e&&await r.waitForFlush(),r.r3fHandle$.value===e&&0===t.holders&&this._renderCurrentView(e)}catch{}finally{0===t.holders&&(t.remove(),t.resumeFrameloop(),this._canvasFreeze===t&&(this._canvasFreeze=null))}}};async renderImage(a){let n=this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value;if(null===n)throw Error("R3F state not ready");let{gl:i,scene:s,camera:l,size:c,advance:m}=n.get(),g=i.getRenderTarget(),d=i.getClearColor(new e),h=i.getClearAlpha(),u=i.autoClearColor,f=e=>new w(a.width,a.height,e,i.outputColorSpace),p={composer:null,pass:null},y=null,b=null,x=e=>{let t=p.pass??f(r);return p.pass=t,p.composer===e&&e.passes.at(-1)===t||(p.composer?.removePass(t),e.addPass(t),p.composer=e),t},v=async()=>{if(await this._context.configuratorExtensionSelectors.getCanvasSystem().waitForFlush(),this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value!==n)throw Error("Canvas was remounted while an image was being rendered! The export borrowed a canvas that is gone, so it cannot capture the image. Retry the export once the configurator has settled.")},E=this._freezeCanvas(n);try{n.set({size:{height:a.height,width:a.width,top:0,left:0,updateStyle:!1}}),n.set({camera:a.camera}),await v(),null!==this._effectComposer&&x(this._effectComposer),m(void 0),await v();let r="JPEG"===a.fileFormat?"image/jpeg":"image/png",l=_({sceneBackground:s.background,backgroundColor:a.backgroundColor,fileFormat:a.fileFormat,outputColorSpace:i.outputColorSpace});if(null!==this._effectComposer){i.setRenderTarget(null),"JPEG"===a.fileFormat?i.setClearColor(a.backgroundColor??0xffffff):a.backgroundColor?i.setClearColor(a.backgroundColor):i.setClearAlpha(0),i.autoClearColor=!0;let e=x(this._effectComposer);return this._effectComposer.render(),await C(i,e.renderTarget,l,r)}y=f(i.toneMapping),b=new o(a.width,a.height,{samples:4,type:t,stencilBuffer:i.getContextAttributes().stencil??!1});let c=s.background;c instanceof e&&(s.background=null);try{i.setClearColor(0,0),i.setRenderTarget(b),i.clear(),i.render(s,a.camera)}finally{s.background=c}return y.render(i,b),await C(i,y.renderTarget,l,r)}finally{null!==p.pass&&(p.composer?.removePass(p.pass),p.pass.dispose()),y?.dispose(),b?.dispose(),this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value===n&&(i.setClearColor(d,h),i.autoClearColor=u,i.setRenderTarget(g),n.set({camera:l,size:{...c,updateStyle:!1}})),await E()}}async generateAndUploadDeclaredClientSideImages(e,t,r={}){let a=this._captureGenerationGuard(),n=await a.waitFor(this.generateDeclaredClientSideImages(e,r));if(r.debug)return n;let o=new Map((await a.waitFor(a.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),t,n.map(e=>e.name))))).map(e=>[e.name,e.url]));return await Promise.all(n.map(async e=>{let t=o.get(e.name);if(!t)throw Error(`Presigned link for image ${e.name} not found!`);await a.waitFor(a.runEffect(()=>fetch(t,{method:"PUT",body:e.blob})))})),n}generateDeclaredClientSideImages(e,t={}){let r=this._context.domainContextSelectors.getComponentReader().readManyComponents({componentTypes:[l]},e);return this.generateImagesFromComponents(r,e,t)}async generateImagesFromComponents(t,r,o={}){let l=this._captureGenerationGuard(),p=this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value;if(null===p)throw Error("R3F state not ready");let w=!1,C=this._context.domainContextSelectors.getExportStates(),_=t.map(t=>{if(!C.includes(t.state.exportState)){let e=d(t.componentInstance.entityId)?m(t.componentInstance.entityId):"unknown entity",r=t.componentInstance.componentType.name,a=t.componentInstance.instanceName;throw Error(`Export state ${t.state.exportState} declared in component ${r}/${a} on ${e} is not a valid export state. Expected one of: ${C.join(", ")}`)}let p=t.componentInstance.entityId;if(h(p))throw Error("Virtual entities cannot be used for export");return this._context.configuratorExtensionSelectors.getExportSystem().createExportJob(r,{exportState:t.state.exportState,exportedEntityId:p,toolState:t.state.toolState,viewState:t.state.viewState,navigationState:t.state.navigationState,selectedEntityId:r.rootEntityId},async r=>{let m=this._context.domainContextSelectors.getComponentReader().readManyComponents({componentTypes:[c,g,u]},r.state);!w&&m.length>0&&(await new Promise(e=>{i({font:void 0,characters:void 0},e)}),w=!0,await this._context.configuratorExtensionSelectors.getCanvasSystem().waitForFlush());let d=this._context.configuratorExtensionSelectors.getCameraSystem().getActiveCameraConfig(r.state);if(null==d)throw Error(`No camera config is attached for export state ${t.state.exportState} and exported entity ${p}. Whenever using a client-side image component, you need to attach a camera configuration to the export state defined on that componentin the domain spec. This camera will be used to render the image.`);let h=s(d.typeSpecificConfig.cameraType).with("perspective",()=>new n(45,t.state.width/t.state.height,1,1e4)).with("orthographic",()=>new a(0,0,1e4,0,1,1e4)).exhaustive(),C=f(h);await this._context.configuratorExtensionSelectors.getCameraSystem().applyConfig(d,C,!1,{width:t.state.width,height:t.state.height,padding:{top:0,right:0,bottom:0,left:0}}),C.update(1e6),await new Promise(e=>setTimeout(e,100));let _=await l.waitFor(l.runEffect(()=>this.renderImage({width:t.state.width,height:t.state.height,fileFormat:t.state.fileFormat,backgroundColor:t.state.backgroundColor?new e(t.state.backgroundColor):void 0,camera:h})));return o.debug&&l.runEffect(()=>this._openDebugImage(_)),{blob:_,imageComponent:t,name:`${t.componentInstance.componentType.name}-${t.componentInstance.entityId}-${t.componentInstance.instanceName}`}})});if(0===_.length)return this._context.configuratorExtensionSelectors.getExportSystem().runExportJobs(_);let y=this._freezeCanvas(p);try{return await this._context.configuratorExtensionSelectors.getExportSystem().runExportJobs(_)}finally{await y()}}initialize=()=>{for(let e of(null!==this._generation&&(this._generation.active=!1),this._debugObjectUrls))URL.revokeObjectURL(e);this._debugObjectUrls.clear(),this._generation={active:!0}}}
+import{Color as e,HalfFloatType as t,NoToneMapping as a,OrthographicCamera as r,PerspectiveCamera as n,WebGLRenderTarget as o}from"three";import{preloadFont as i}from"troika-three-text";import{match as s}from"ts-pattern";import{clientSideImageComponent as l,dimensionIndicatorComponent as c,domainEntityTypeFromId as m,editableDistanceDimensionIndicatorComponent as g,isDomainEntityId as d,isVirtualEntityId as h,sketchingEditComponent as u}from"#package/domain";import{createCameraControls as f}from"../camera-control-system/create-camera-controls.js";import{createCanvasFreezeFrame as p}from"./canvas-freeze-frame.js";import{ExportCapturePass as w,readTargetToBlob as C,resolveExportBackground as _}from"./export-image-capture.js";export class ImageRenderingSystem{_context;_renderer=null;_effectComposer=null;_generation=null;_debugObjectUrls=new Set;_canvasFreeze=null;constructor(e){this._context=e}_captureGenerationAssertion=()=>{let e=this._generation,t=()=>{if(!e?.active)throw Error("Image rendering generation ended while images were being rendered! The configurator context was reinitialized before the renderer finished, so the results belong to a configuration that is no longer active. Await the render before leaving the configuration, or discard the rejection.")};return t(),t};_captureGenerationGuard=()=>{let e=this._captureGenerationAssertion();return{assertActive:e,waitFor:async t=>{let a=await t;return e(),a},runEffect:t=>(e(),t())}};register(e){return this._renderer=e,()=>{this._renderer===e&&(this._renderer=null)}}registerEffectComposer(e){return this._effectComposer=e,()=>{this._effectComposer===e&&(this._effectComposer=null)}}_openDebugImage=e=>{let t=URL.createObjectURL(e);this._debugObjectUrls.add(t),window.open(t,"_blank")};_getRenderer=async()=>{let e=this._generation,t=Date.now(),a=()=>{if(!e?.active)throw Error("Image rendering generation ended while waiting for the renderer! The configurator context was reinitialized before the renderer arrived, so the render would target a scene that is gone. Await the render before leaving the configuration, or discard the rejection.")};a();let r=this._renderer;for(;null===r;){if(await new Promise(e=>setTimeout(e,50)),a(),Date.now()-t>1e4)throw Error("Renderer could not be retrieved! Reached timeout.");r=this._renderer}return r};generateImageUsingOriginalCanvas=async(e,t,a=!1)=>{let r=this._captureGenerationGuard(),n=await r.waitFor(this._getRenderer());if(a){let{blob:e}=await r.waitFor(r.runEffect(()=>n.renderUsingOriginalCanvas(t)));r.runEffect(()=>this._openDebugImage(e));return}let o=await Promise.all([t].map(async e=>{let{blob:t}=await r.waitFor(r.runEffect(()=>n.renderUsingOriginalCanvas(e)));return{blob:t,name:e.name}})),i=await r.waitFor(r.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),e,[t.name])));await Promise.all(i.map(async e=>{let t=o.find(t=>t.name===e.name);if(null==t)throw Error("Blob not found!");await Promise.all(i.map(async e=>{await r.waitFor(r.runEffect(()=>fetch(e.url,{method:"PUT",body:t.blob,headers:{"Content-Type":"image/png","Content-Length":t.blob.size.toString()}})))}))}))};async generateImagesUsingOriginalCanvas(e,t,a=!1){let r=this._captureGenerationGuard(),n=await r.waitFor(this._getRenderer()),o=Array.isArray(t)?t:[t],i=await o.reduce(async(e,t)=>[...await e,await r.waitFor(r.runEffect(()=>n.renderUsingOriginalCanvas(t)))],Promise.resolve([]));if(a){for(let e of i)r.runEffect(()=>this._openDebugImage(e.blob)),await r.waitFor(new Promise(e=>setTimeout(e,100)));return}let s=o.map(e=>e.name),l=await r.waitFor(r.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),e,s)));await Promise.all(l.map(async e=>{let t=i.find(t=>t.name===e.name);if(null==t)throw Error("Blob not found!");await Promise.all(l.map(async e=>{await r.waitFor(r.runEffect(()=>fetch(e.url,{method:"PUT",body:t.blob,headers:{"Content-Type":"image/png","Content-Length":t.blob.size.toString()}})))}))}))}async generateImages(e,t,a=!1){let r=this._captureGenerationGuard(),n=await r.waitFor(this._getRenderer()),o=t.map(e=>e.name);if(a)return void await Promise.all(t.map(async e=>{let t=await r.waitFor(r.runEffect(()=>n.renderImage(e)));r.runEffect(()=>this._openDebugImage(t))}));let i=await Promise.all(t.map(async e=>({blob:await r.waitFor(r.runEffect(()=>n.renderImage(e))),name:e.name}))),s=await r.waitFor(r.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),e,o)));await Promise.all(s.map(async e=>{let t=i.find(t=>t.name===e.name);if(null==t)throw Error("Blob not found!");await Promise.all(s.map(async e=>{await r.waitFor(r.runEffect(()=>fetch(e.url,{method:"PUT",body:t.blob,headers:{"Content-Type":"image/png","Content-Length":t.blob.size.toString()}})))}))}))}async getGeneratedImages(e,t=!1){let a=this._captureGenerationAssertion(),r=await this._getRenderer();return(a(),t)?(await Promise.all(e.map(async e=>{let t=await r.renderImage(e);a(),this._openDebugImage(t)})),[]):Promise.all(e.map(async e=>{let t=await r.renderImage(e);return a(),{blob:t,name:e.name}}))}_renderCurrentView=e=>{let{gl:t,scene:a,camera:r}=e.get();null!==this._effectComposer?this._effectComposer.render():t.render(a,r)};_freezeCanvas=e=>{this._canvasFreeze?.handle===e?this._canvasFreeze.holders+=1:(this._canvasFreeze?.remove(),this._canvasFreeze={handle:e,remove:p(e.get().gl.domElement,()=>this._renderCurrentView(e)),resumeFrameloop:this._context.configuratorExtensionSelectors.getExportSystem().pauseFrameloop(e),holders:1});let t=this._canvasFreeze,a=!1;return async()=>{if(!a&&(a=!0,t.holders-=1,!(t.holders>0)))try{let a=this._context.configuratorExtensionSelectors.getCanvasSystem();a.r3fHandle$.value===e&&await a.waitForFlush(),a.r3fHandle$.value===e&&0===t.holders&&this._renderCurrentView(e)}catch{}finally{0===t.holders&&(t.remove(),t.resumeFrameloop(),this._canvasFreeze===t&&(this._canvasFreeze=null))}}};async renderImage(r){let n=this._context.configuratorExtensionSelectors.getCanvasSystem(),i=n.r3fHandle$.value??await n.waitForCanvas(),{gl:s,scene:l,camera:c,size:m,advance:g}=i.get(),d=s.getRenderTarget(),h=s.getClearColor(new e),u=s.getClearAlpha(),f=s.autoClearColor,p=e=>new w(r.width,r.height,e,s.outputColorSpace),y={composer:null,pass:null},b=null,x=null,v=e=>{let t=y.pass??p(a);return y.pass=t,y.composer===e&&e.passes.at(-1)===t||(y.composer?.removePass(t),e.addPass(t),y.composer=e),t},E=async()=>{if(await this._context.configuratorExtensionSelectors.getCanvasSystem().waitForFlush(),this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value!==i)throw Error("Canvas was remounted while an image was being rendered! The export borrowed a canvas that is gone, so it cannot capture the image. Retry the export once the configurator has settled.")},S=this._freezeCanvas(i);try{i.set({size:{height:r.height,width:r.width,top:0,left:0,updateStyle:!1}}),i.set({camera:r.camera}),await E(),null!==this._effectComposer&&v(this._effectComposer),g(void 0),await E();let a="JPEG"===r.fileFormat?"image/jpeg":"image/png",n=_({sceneBackground:l.background,backgroundColor:r.backgroundColor,fileFormat:r.fileFormat,outputColorSpace:s.outputColorSpace});if(null!==this._effectComposer){s.setRenderTarget(null),"JPEG"===r.fileFormat?s.setClearColor(r.backgroundColor??0xffffff):r.backgroundColor?s.setClearColor(r.backgroundColor):s.setClearAlpha(0),s.autoClearColor=!0;let e=v(this._effectComposer);return this._effectComposer.render(),await C(s,e.renderTarget,n,a)}b=p(s.toneMapping),x=new o(r.width,r.height,{samples:4,type:t,stencilBuffer:s.getContextAttributes().stencil??!1});let c=l.background;c instanceof e&&(l.background=null);try{s.setClearColor(0,0),s.setRenderTarget(x),s.clear(),s.render(l,r.camera)}finally{l.background=c}return b.render(s,x),await C(s,b.renderTarget,n,a)}finally{null!==y.pass&&(y.composer?.removePass(y.pass),y.pass.dispose()),b?.dispose(),x?.dispose(),this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value===i&&(s.setClearColor(h,u),s.autoClearColor=f,s.setRenderTarget(d),i.set({camera:c,size:{...m,updateStyle:!1}})),await S()}}async generateAndUploadDeclaredClientSideImages(e,t,a={}){let r=this._captureGenerationGuard(),n=await r.waitFor(this.generateDeclaredClientSideImages(e,a));if(a.debug)return n;let o=new Map((await r.waitFor(r.runEffect(()=>this._context.getAuthorizedClient().generateUploadLinks(this._context.getConfigurationId(),t,n.map(e=>e.name))))).map(e=>[e.name,e.url]));return await Promise.all(n.map(async e=>{let t=o.get(e.name);if(!t)throw Error(`Presigned link for image ${e.name} not found!`);await r.waitFor(r.runEffect(()=>fetch(t,{method:"PUT",body:e.blob})))})),n}generateDeclaredClientSideImages(e,t={}){let a=this._context.domainContextSelectors.getComponentReader().readManyComponents({componentTypes:[l]},e);return this.generateImagesFromComponents(a,e,t)}generateImagesFromComponents(e,t,a={},r={}){return this._generateImagesFromComponents(e,t,a,r)}async _generateImagesFromComponents(t,a,o,l){let p=this._captureGenerationGuard(),w=!1,C=this._context.domainContextSelectors.getExportStates(),_=t.map(t=>{if(!C.includes(t.state.exportState)){let e=d(t.componentInstance.entityId)?m(t.componentInstance.entityId):"unknown entity",a=t.componentInstance.componentType.name,r=t.componentInstance.instanceName;throw Error(`Export state ${t.state.exportState} declared in component ${a}/${r} on ${e} is not a valid export state. Expected one of: ${C.join(", ")}`)}let l=t.componentInstance.entityId;if(h(l))throw Error("Virtual entities cannot be used for export");return this._context.configuratorExtensionSelectors.getExportSystem().createExportJob(a,{exportState:t.state.exportState,exportedEntityId:l,toolState:t.state.toolState,viewState:t.state.viewState,navigationState:t.state.navigationState,selectedEntityId:a.rootEntityId},async a=>{let m=this._context.domainContextSelectors.getComponentReader().readManyComponents({componentTypes:[c,g,u]},a.state);!w&&m.length>0&&(await new Promise(e=>{i({font:void 0,characters:void 0},e)}),w=!0,await this._context.configuratorExtensionSelectors.getCanvasSystem().waitForFlush());let d=this._context.configuratorExtensionSelectors.getCameraSystem().getActiveCameraConfig(a.state);if(null==d)throw Error(`No camera config is attached for export state ${t.state.exportState} and exported entity ${l}. Whenever using a client-side image component, you need to attach a camera configuration to the export state defined on that componentin the domain spec. This camera will be used to render the image.`);let h=s(d.typeSpecificConfig.cameraType).with("perspective",()=>new n(45,t.state.width/t.state.height,1,1e4)).with("orthographic",()=>new r(0,0,1e4,0,1,1e4)).exhaustive(),C=f(h);await this._context.configuratorExtensionSelectors.getCameraSystem().applyConfig(d,C,!1,{width:t.state.width,height:t.state.height,padding:{top:0,right:0,bottom:0,left:0}}),C.update(1e6),await new Promise(e=>setTimeout(e,100));let _=await p.waitFor(p.runEffect(()=>this.renderImage({width:t.state.width,height:t.state.height,fileFormat:t.state.fileFormat,backgroundColor:t.state.backgroundColor?new e(t.state.backgroundColor):void 0,camera:h})));return o.debug&&p.runEffect(()=>this._openDebugImage(_)),{blob:_,imageComponent:t,name:`${t.componentInstance.componentType.name}-${t.componentInstance.entityId}-${t.componentInstance.instanceName}`}})});if(0===_.length)return this._context.configuratorExtensionSelectors.getExportSystem().runExportJobs(_,l);let y=this._context.configuratorExtensionSelectors.getCanvasSystem(),b=y.r3fHandle$.value??await p.waitFor(y.waitForCanvas().catch(e=>{throw p.assertActive(),e})),x=this._freezeCanvas(b);try{return await this._context.configuratorExtensionSelectors.getExportSystem().runExportJobs(_,l)}finally{await x()}}initialize=()=>{for(let e of(null!==this._generation&&(this._generation.active=!1),this._debugObjectUrls))URL.revokeObjectURL(e);this._debugObjectUrls.clear(),this._generation={active:!0}}}

package/dist/configurator/application-runtime/extensions/systems/index.d.ts

@@ -6,7 +6,7 @@ export { createCameraControls } from './camera-control-system/create-camera-cont
 export { type AnyCanvasSystem, CanvasSystem, type EntityObjectFilter, type FlushToken } from './canvas-system.js';
 export { type AnyDragAndDropSystem, DragAndDropSystem, type DragAndDropSystemContext, type DraggableState, type DraggingState, type RotationDraggingState, } from './drag-and-drop-system/drag-and-drop-system.js';
 export { type AnyExportSystem, ExportSystem, type ExportSystemContext } from './export-system/export-system.js';
-export { type GraphQLExecution, type GraphQLOperation, GraphQLSystem, type GraphQLSystemContext, type PreparedOperation, } from './graphql-system/graphql-system.js';
+export { type GraphQLExecution, type GraphQLScreenshot, type GraphQLOperation, GraphQLSystem, type GraphQLSystemContext, type PreparedOperation, } from './graphql-system/graphql-system.js';
 export type * from './image-rendering-system/image-renderer.js';
 export { type AnyImageRenderingSystem, ImageRenderingSystem, type ImageRenderingSystemContext, } from './image-rendering-system/image-rendering-system.js';
 export { type AnyLayoutSystem, LayoutSystem, type LayoutSystemContext } from './layout-system/layout-system.js';

package/dist/configurator/common/configurator-interface.d.ts

@@ -1,14 +1,14 @@
 import { type $DomainEntity, type ConfiguratorBuilder, type CreateCustomPhoenixEntityElement, type CreateCustomPhoenixLayoutElement, type CreateGetThemeHandler, type CreateGetWebComponentOptionsHandler, type CreatePhoenixHandler, type DomainEntity, type IsCreateRecipeUpdate, type IsReplaceRecipeUpdate, type TransformerBuilder, type TransformerFactory, type UpdateFactory, getIdSequence } from '#package/domain';
-import { type CreateCollectFrontendDataHandler, type CreateFilterPublishedChunksHandler, type CreateNotAuthenticatedPage, type IsAngleDimensionUpdate, type IsAttributeSelectionUpdate, type IsAttributeSwitchUpdate, type IsDeleteEntityUpdate, type IsDistanceDimensionUpdate, type IsGenericDimensionUpdate, type IsSwatchSelectionUpdate, type IsTextValueUpdate, type UseAccessService, type UseActiveNavigationState, type UseActiveToolState, type UseActiveViewState, type UseAnalyticsService, type UseAngleDimension, type UseAttributeSelection, type UseAttributeSwitch, type UseAuthenticatedClient, type UseAuthorizedClient, type UseBackendData, type UseChildEntitySelection, type UseComponent, type UseComponents, type UseComposition, type UseConfigurationId, type UseConfiguratorMessages, type UseControlViolations, type UseCookRecipes, type UseCookReplaceRecipes, type UseCookedRecipes, type UseCookedReplaceRecipes, type UseCreateAuthorizedClient, type UseDeleteEntity, type UseDeletedEntity, type UseDeselect, type UseDistanceDimension, type UseDistanceDimensionSelection, type UseDomainApplicationContext, type UseDomainApplicationProps, type UseDomainContext, type UseDomainEntityState, type UseEntityPrice, type UseEntitySelector, type UseFinalizeViolations, type UseFirstComponent, type UseFirstRootComponent, type UseFrontendData, type UseGenericDimension, type UseGroupedRecipeOptions, type UseHoveredDomainEntityId, type UseHoveredEntity, type UseHoveredEntityId, type UseIntegrationService, type UseIntegrationState, type UseIsFullscreenActive, type UseLoadedData, type UseLoadingState, type UseMapViolationHints, type UseNavigate, type UsePopNavigate, type UsePresetEmbeddedState, type UsePublishedData, type UsePushNavigate, type UseRecipeEmbeddedState, type UseReplaceEntityRecipeOptions, type UseRootComponents, type UseRootEntityId, type UseRootEntityPrice, type UseRootEntitySelector, type UseRootEntityState, type UseSelectEntity, type UseSelectParent, type UseSelectedDomainEntityId, type UseSelectedEntity, type UseSelectedEntityId, type UseSession, type UseSessionRole, type UseSessionService, type UseSetFullscreen, type UseSetViewState, type UseSlice, type UseState, type UseStateValidity, type UseSwatchSelection, type UseSynchronizedSelector, type UseSynchronizedSelector$, type UseTextValue, type UseUpdateControl, type UseUpdatedControl, useLoadingStateValue } from '#package/react-sdk';
+import { type CreateAddEntityFab, type CreateAppLoader, type CreateCollectFrontendDataHandler, type CreateConfigurationNotFoundPage, type CreateConfiguratorErrorPage, type CreateDeleteEntityFab, type CreateFilterPublishedChunksHandler, type CreateNavigationHotspot, type CreateNotAuthenticatedPage, type CreatePresetUi, type CreateSelectionHotspot, type CreateToolMenuFab, type IsAngleDimensionUpdate, type IsAttributeSelectionUpdate, type IsAttributeSwitchUpdate, type IsDeleteEntityUpdate, type IsDistanceDimensionUpdate, type IsGenericDimensionUpdate, type IsSwatchSelectionUpdate, type IsTextValueUpdate, type UseAccessService, type UseActiveNavigationState, type UseActiveToolState, type UseActiveViewState, type UseActiveViewports, type UseAnalyticsService, type UseAngleDimension, type UseAttributeSelection, type UseAttributeSwitch, type UseAuthenticatedClient, type UseAuthorizedClient, type UseBackendData, type UseChildEntitySelection, type UseComponent, type UseComponents, type UseComposition, type UseConfigurationId, type UseConfigurationSaveState, type UseConfiguratorMessages, type UseControlViolations, type UseCookRecipes, type UseCookReplaceRecipes, type UseCookedRecipes, type UseCookedReplaceRecipes, type UseCreateAuthorizedClient, type UseDeleteEntity, type UseDeletedEntity, type UseDeselect, type UseDistanceDimension, type UseDistanceDimensionSelection, type UseDomainApplicationContext, type UseDomainApplicationProps, type UseDomainContext, type UseDomainEntityState, type UseEntityPrice, type UseEntitySelector, type UseFinalizeAction, type UseFinalizeActions, type UseFinalizeViolations, type UseFirstComponent, type UseFirstRootComponent, type UseFrontendData, type UseGenericDimension, type UseGroupedRecipeOptions, type UseHoveredDomainEntityId, type UseHoveredEntity, type UseHoveredEntityId, type UseIntegrationService, type UseIntegrationState, type UseIsFullscreenActive, type UseLoadedData, type UseLoadingState, type UseLocaleSwitch, type UseMapViolationHints, type UseNavigate, type UsePopNavigate, type UsePresetEmbeddedState, type UsePublishedData, type UsePushNavigate, type UseRecipeEmbeddedState, type UseReplaceEntityRecipeOptions, type UseRootComponents, type UseRootEntityId, type UseRootEntityPrice, type UseRootEntitySelector, type UseRootEntityState, type UseSelectEntity, type UseSelectParent, type UseSelectedDomainEntityId, type UseSelectedEntity, type UseSelectedEntityId, type UseSession, type UseSessionRole, type UseSessionService, type UseSetFullscreen, type UseSetViewState, type UseShareLinks, type UseSlice, type UseState, type UseStateValidity, type UseStepNavigation, type UseSwatchSelection, type UseSynchronizedSelector, type UseSynchronizedSelector$, type UseTabNavigation, type UseTextValue, type UseUndoRedo, type UseUpdateControl, type UseUpdatedControl, useGenerateShareLink, useLoadingStateValue, useLocalizable, useResolveLocalizable } from '#package/react-sdk';
 import { type CreatePhoenixIconSet } from '#package/ui-sdk';
 import { type UseConfiguratorExtensions } from '../application-runtime/index.js';
-import { type CreateOnApplicationStartProvider, type CreateOnBackendDataReadyProvider, type CreateOnConfiguratorReadyProvider, type CreateOnFrontendDataReadyProvider, type CreateOnGoToIndexHandler, type CreateOnPresetLoadedHandler, type CreateOnPublishedDataReadyProvider, type CreateOnRoutingReadyProvider, type CreateOnSessionReadyProvider, type UseConfiguratorRouting, type UsePresetSelection, usePropertyPageStack, usePropertyPageState } from '../configurator-context/index.js';
+import { type CreateOnApplicationStartProvider, type CreateOnBackendDataReadyProvider, type CreateOnConfiguratorReadyProvider, type CreateOnFrontendDataReadyProvider, type CreateOnGoToIndexHandler, type CreateOnPresetLoadedHandler, type CreateOnPublishedDataReadyProvider, type CreateOnRoutingReadyProvider, type CreateOnSessionReadyProvider, type UseConfiguratorRouting, type UsePresetSelection, usePreview, usePropertyPageStack, usePropertyPageState } from '../configurator-context/index.js';
+import { useCloseAction } from '../integration/index.js';
 import { type CreateGetTextureProcessingMapHandler } from '../scene/index.js';
 import type { UseUpdateEntityObjectSelection } from '../scene/scene-entity/drag-and-drop/use-updated-selection.js';
-import { type CreateAppLoader, type CreateCanvasLoader, type CreateLayoutAdminUi, type CreateLayoutCustomOwnerUi, type CreateLayoutCustomReadUi, type CreateLayoutDialog, type CreateLayoutFooter, type CreateLayoutToolbarDesktop, type CreateLayoutToolbarDesktopFullScreen, type CreateLayoutToolbarReadDesktop, type CreateLayoutToolbarReadDesktopFullScreen, type CreateLayoutUserUi, type CreateToolbarHelp } from '../ui/index.js';
-import { useGenerateShareLink } from '../ui/phoenix-layout-elements/share/use-share.js';
-import { type CreatePresetDeviceNotSupported, type CreatePresetPageAction, type CreatePresetUi } from '../ui/preset-layout/PresetUi.js';
-import { type UseFinalizeAction } from './use-finalize-action.js';
+import { type UseAssistantPanel, type UseMeasurements, type UseToolbarActions } from '../toolbar-actions/index.js';
+import { type CreateCanvasLoader, type CreateLayoutAdminUi, type CreateLayoutCustomOwnerUi, type CreateLayoutCustomReadUi, type CreateLayoutDialog, type CreateLayoutFooter, type CreateLayoutToolbarDesktop, type CreateLayoutToolbarDesktopFullScreen, type CreateLayoutToolbarReadDesktop, type CreateLayoutToolbarReadDesktopFullScreen, type CreateLayoutUserUi, type CreateToolbarHelp, LayoutSlots, useSceneSafeArea } from '../ui/index.js';
+import { type CreatePresetDeviceNotSupported, type CreatePresetPageAction } from '../ui/preset-layout/PresetUi.js';
 import { type UseResetCamera } from './use-reset-camera.js';
 export interface ConfiguratorInterface<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, FINALIZE_DATA extends Record<string, unknown>, FINALIZE_RESULT extends Record<string, unknown>> {
     /**
@@ -181,6 +181,42 @@ export interface ConfiguratorInterface<ENTITIES extends DomainEntity<string>, AL
      * Creates a custom page shown when session authentication fails.
      */
     createNotAuthenticatedPage: CreateNotAuthenticatedPage;
+    /**
+     * Creates the page shown when a configuration cannot be loaded or opened, replacing the built-in
+     * `ConfigurationNotFoundPage`.
+     */
+    createConfigurationNotFoundPage: CreateConfigurationNotFoundPage;
+    /**
+     * Creates the page the configurator shows in production when it cannot go on, replacing the built-in
+     * `ConfiguratorErrorPage`.
+     */
+    createConfiguratorErrorPage: CreateConfiguratorErrorPage;
+    /**
+     * Creates the in-scene FAB that adds child entities (`sceneEntityAddFab`), replacing the built-in
+     * `AddEntityFab` element. It receives the component's settings and reads the recipes it offers
+     * with `useGroupedRecipeOptions(entityId, instanceNames, fixableViolations)`.
+     */
+    createAddEntityFab: CreateAddEntityFab;
+    /**
+     * Creates the in-scene FAB that deletes an entity (`sceneEntityDeleteFab`), replacing the built-in
+     * `DeleteEntityFab` element. It receives `onDelete`, `disabled` and `disabledHint`.
+     */
+    createDeleteEntityFab: CreateDeleteEntityFab;
+    /**
+     * Creates the in-scene hotspot that selects an entity (`sceneEntitySelectHotspot`), replacing the
+     * built-in `SelectionHotspot` element. It receives `onSelect`.
+     */
+    createSelectionHotspot: CreateSelectionHotspot;
+    /**
+     * Creates the in-scene hotspot that goes to a navigation state (`sceneEntityNavigationHotspot`),
+     * replacing the built-in `NavigationHotspot` element. It receives `onNavigate`.
+     */
+    createNavigationHotspot: CreateNavigationHotspot;
+    /**
+     * Creates the in-scene FAB that switches tools (`toolMenuFab`), replacing the built-in `ToolMenuFab`
+     * element. It receives the tool `options` and `onSelectTool`.
+     */
+    createToolMenuFab: CreateToolMenuFab;
     /**
      * Factory for creating transformers for entities.
      * @deprecated Use {@link #transformerBuilder} instead.
@@ -349,11 +385,21 @@ export interface ConfiguratorInterface<ENTITIES extends DomainEntity<string>, AL
      * text resolved
      */
     useConfiguratorMessages: UseConfiguratorMessages<ENTITIES, $MAP>;
+    /**
+     * The save status of the configuration: `{ revisionId, isSaving, failure }`, where `failure` is the latest save's
+     * `{ error, timestamp }` until a later save succeeds
+     */
+    useConfigurationSaveState: UseConfigurationSaveState;
     /**
      * Runs the project handler a `finalizeAction` component names, with its pending state, its error and the
      * finalize violations; call it once per component, wrapped in `PhoenixHandlerBoundary`
      */
     useFinalizeAction: UseFinalizeAction;
+    /**
+     * The spec's finalize actions, each with its resolved texts and its own `run`, `isPending` and `error`, the
+     * primary one picked as the built-in footer picks it; call it anywhere and render the actions in a loop
+     */
+    useFinalizeActions: UseFinalizeActions;
     /**
      * Returns component based on a filter specified
      */
@@ -491,6 +537,75 @@ export interface ConfiguratorInterface<ENTITIES extends DomainEntity<string>, AL
      * Move the camera back to the framing of the active camera configuration, as the toolbar's reset button does
      */
     useResetCamera: UseResetCamera;
+    /**
+     * Undo and redo changes of the configuration, with whether each is possible, as the toolbar's undo and redo
+     * buttons do
+     */
+    useUndoRedo: UseUndoRedo;
+    /**
+     * The spec's tabs (`sidebarTabs` or `horizontalTabs`) with the active one, and switching between them, as the
+     * built-in tabs do
+     */
+    useTabNavigation: UseTabNavigation<NAVIGATION_STATES>;
+    /**
+     * The spec's steps (`navigationSteps`) with the active one, and moving between them, as the built-in step buttons
+     * and the header's stepper do
+     */
+    useStepNavigation: UseStepNavigation<NAVIGATION_STATES>;
+    /**
+     * Tell the camera which part of the canvas a project layout leaves free for the scene. Attach `containerRef` to the
+     * element that covers the whole canvas and `safeAreaRef` to the region the scene should stay visible in
+     */
+    useSceneSafeArea: typeof useSceneSafeArea;
+    /**
+     * Get the responsive breakpoints the configurator's container satisfies, or `null` before it is measured
+     */
+    useActiveViewports: UseActiveViewports;
+    /**
+     * Get the preview state: whether the layout shows a preview start screen, and functions that enter and leave it
+     */
+    usePreview: typeof usePreview;
+    /**
+     * Get the host's close action, or `null` when the integration mode offers none
+     */
+    useCloseAction: typeof useCloseAction;
+    /**
+     * Whether a viewer of a configuration shared for viewing may clone it to edit: the application config sets
+     * `shareCloneToEdit` and the session's role may create configurations
+     */
+    useIsCloningAllowed: typeof LayoutSlots.useIsCloningAllowed;
+    /**
+     * Returns a function that turns a localizable text of the spec into a string in the current language
+     */
+    useResolveLocalizable: typeof useResolveLocalizable;
+    /**
+     * Turn one localizable text of the spec into a string in the current language
+     */
+    useLocalizable: typeof useLocalizable;
+    /**
+     * The spec's toolbar for a placement as runnable entries, grouped as the spec groups them, for a layout's own
+     * toolbar
+     */
+    useToolbarActions: UseToolbarActions;
+    /**
+     * The unit of dimensions and the dimension indicators, with functions that change them, as the toolbar's
+     * measurements button does
+     */
+    useMeasurements: UseMeasurements;
+    /**
+     * The languages the configurator offers and the active one, with a function that switches it, as the toolbar's
+     * language button does
+     */
+    useLocaleSwitch: UseLocaleSwitch;
+    /**
+     * Links that share the configuration for editing and for viewing, as the toolbar's share dialog generates them
+     */
+    useShareLinks: UseShareLinks;
+    /**
+     * Whether the assistant panel is open, with a function that opens or closes it, as the toolbar's assistant button
+     * does
+     */
+    useAssistantPanel: UseAssistantPanel;
     /**
      * Returns composition tree of the domain
      */