@salsita-ai/sdk 0.50.0-develop.d81d7591c5 → 0.50.0-develop.d9534cf412

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

@@ -1,4 +1,5 @@
 import type { Scene } from 'three';
+import { type ObservableWithLastValue } from '@salsita-ai/common/utils';
 import type { $DomainEntity, DomainContextSelectors, DomainEntity, DomainEntityId, DomainServicesSelectors, DomainState } from '#package/domain';
 import type { ConfiguratorExtensionSelectors } from '../../selectors.js';
 import type { R3FHandle } from '../canvas-system.js';
@@ -29,12 +30,26 @@ export interface ExportJob<EXPORT_STATES extends string, ENTITIES extends Domain
     selectedEntityId?: ENTITIES['id'];
     execute: (props: ExportJobArguments<ENTITIES, any, any>) => Promise<R>;
 }
+/** How one export run starts. */
+export interface ExportRunOptions {
+    /**
+     * Waits for the user to finish a change they are making, such as a drag, before the first job, for
+     * up to {@link SETTLE_TIMEOUT_MS}, and rejects with an {@link ExportBusyError} when they do not. A run
+     * the user did not start themselves, such as the assistant's screenshot, must not export over it. A
+     * hover is no such change: the run's restore drops it, as it always did.
+     */
+    readonly awaitSettledState?: boolean;
+}
 /** ExportSystem with its entity types erased — how the runtime selectors expose the instance. */
 export type AnyExportSystem = ExportSystem<any, any, any, any, any, any, any>;
 export declare class ExportSystem<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> {
     private readonly _context;
     private _generation;
     private _frameloopPause;
+    private _queue;
+    private readonly _exporting;
+    /** True while an export run is queued or running; the configurator UI is inert meanwhile. */
+    readonly exporting$: ObservableWithLastValue<boolean>;
     constructor(_context: ExportSystemContext);
     /**
      * Pauses the frameloop of the given canvas mount until the returned release has been called as
@@ -55,6 +70,13 @@ export declare class ExportSystem<ENTITIES extends DomainEntity<string>, ALLOWED
         navigationState?: NAVIGATION_STATES;
         selectedEntityId?: DomainEntityId<ENTITY_TYPE>;
     }, job: (props: ExportJobArguments<ENTITIES, $MAP[ENTITY_TYPE], $MAP[ALLOWED_ROOT_ENTITIES['type']]>) => Promise<R>) => ExportJob<EXPORT_STATES, ENTITIES, TOOL_STATES, VIEW_STATES, NAVIGATION_STATES, R>;
-    runExportJobs: <R>(jobs: ReadonlyArray<ExportJob<EXPORT_STATES, ENTITIES, TOOL_STATES, VIEW_STATES, NAVIGATION_STATES, R>>) => Promise<R[]>;
+    /**
+     * Queues the jobs as one export run behind every run already queued and resolves with their
+     * results in order. While the run is queued or running, `exporting$` is true. Afterwards the store
+     * shows the committed state current at that moment, not the one the run started from.
+     */
+    runExportJobs: <R>(jobs: ReadonlyArray<ExportJob<EXPORT_STATES, ENTITIES, TOOL_STATES, VIEW_STATES, NAVIGATION_STATES, R>>, options?: ExportRunOptions) => Promise<R[]>;
+    private readonly _awaitSettledState;
+    private readonly _runExportJobs;
     initialize: () => void;
 }

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

@@ -1,4 +1,5 @@
-import { type $DomainEntity, type AssistantManifest, type AssistantRecipeContext, type DomainEntity, type DomainEntityId, type DomainState, type EntityId, type StateUpdate, type StateUpdateEmission } from '#package/domain';
+import { type $DomainEntity, type AssistantManifest, type AssistantRecipeContext, type DomainEntity, type DomainEntityId, type DomainState, type StateUpdate, type StateUpdateEmission, type StateValidationResult } from '#package/domain';
+import { type ViolationEntry } from './violations.js';
 type AnyDomainState = DomainState<DomainEntity<string>>;
 type AnyStateUpdate = StateUpdate<DomainEntity<string>, DomainEntity<string>>;
 /** An entity and the state it was read on, which everything under its `meta` field resolves against. */
@@ -20,70 +21,96 @@ export interface EntityMetaContext {
         readonly success: false;
         readonly errors: readonly string[];
     };
-}
-/** One reason a dry-run reports for a change that cannot be made; a violation can sit on a virtual entity. */
-interface DryRunError {
-    readonly type: string;
-    readonly entityId: EntityId<DomainEntity<string>> | null;
-    readonly message: string | null;
+    /**
+     * 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>;
+    /**
+     * Validates a state: the one an entity was read on, for its warnings, or the one a dry-run ran on,
+     * whose warnings the dry-run's own are compared with.
+     */
+    readonly validateState: (state: AnyDomainState) => StateValidationResult<DomainEntity<string>, string>;
 }
 /**
  * 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.
+ * was read on. `childRecipes` and `replaceRecipes` hold one field per manifest recipe group of their
+ * kind, read only when selected, `null` when the group is not 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, and `warnings` lists the warnings and notices the entity holds there.
  */
 export declare const createEntityMeta: (source: EntityMetaSource, context: EntityMetaContext) => {
     childRecipes: () => {
-        groupId: string;
-        name: string;
-        description: string | null;
-        recipes: {
-            key: string;
+        [k: string]: () => {
+            groupId: string;
             name: string;
             description: string | null;
-            imageUrl: string | null;
-            dryRun: () => {
-                ok: boolean;
-                root: null;
-                changedEntities: never[];
-                deletedEntityIds: never[];
-                sideEffects: never[];
-                errors: readonly DryRunError[];
-            } | {
-                ok: boolean;
-                root: unknown;
-                changedEntities: {}[];
-                deletedEntityIds: DomainEntityId<string>[];
-                sideEffects: readonly string[];
-                errors: never[];
-            } | null;
-        }[];
-    }[];
+            recipes: ({ keys }: {
+                readonly keys?: readonly string[] | null;
+            }) => {
+                key: string;
+                name: string;
+                description: string | null;
+                imageUrl: string | null;
+                dryRun: () => {
+                    ok: boolean;
+                    root: null;
+                    changedEntities: never[];
+                    deletedEntityIds: never[];
+                    sideEffects: never[];
+                    warnings: never[];
+                    errors: readonly ViolationEntry[];
+                } | {
+                    ok: boolean;
+                    root: unknown;
+                    changedEntities: {}[];
+                    deletedEntityIds: DomainEntityId<string>[];
+                    sideEffects: readonly string[];
+                    warnings: () => readonly import("./violations.js").AssistantWarning[];
+                    errors: never[];
+                } | null;
+            }[];
+        } | null;
+    };
     replaceRecipes: () => {
-        groupId: string;
-        name: string;
-        description: string | null;
-        recipes: {
-            key: string;
+        [k: string]: () => {
+            groupId: string;
             name: string;
             description: string | null;
-            imageUrl: string | null;
-            dryRun: () => {
-                ok: boolean;
-                root: null;
-                changedEntities: never[];
-                deletedEntityIds: never[];
-                sideEffects: never[];
-                errors: readonly DryRunError[];
-            } | {
-                ok: boolean;
-                root: unknown;
-                changedEntities: {}[];
-                deletedEntityIds: DomainEntityId<string>[];
-                sideEffects: readonly string[];
-                errors: never[];
-            } | null;
-        }[];
-    }[];
+            recipes: ({ keys }: {
+                readonly keys?: readonly string[] | null;
+            }) => {
+                key: string;
+                name: string;
+                description: string | null;
+                imageUrl: string | null;
+                dryRun: () => {
+                    ok: boolean;
+                    root: null;
+                    changedEntities: never[];
+                    deletedEntityIds: never[];
+                    sideEffects: never[];
+                    warnings: never[];
+                    errors: readonly ViolationEntry[];
+                } | {
+                    ok: boolean;
+                    root: unknown;
+                    changedEntities: {}[];
+                    deletedEntityIds: DomainEntityId<string>[];
+                    sideEffects: readonly string[];
+                    warnings: () => readonly import("./violations.js").AssistantWarning[];
+                    errors: never[];
+                } | null;
+            }[];
+        } | null;
+    };
+    screenshot: ({ view }: {
+        readonly view: string;
+    }) => Promise<{
+        readonly image: string;
+    } | null>;
+    warnings: () => readonly import("./violations.js").AssistantWarning[];
 };
 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 s,systemUpdateFactory as a}from"#package/domain";import{readSideEffects as o}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:s,state:a,updates:l}=r(e,t,"committed");if(s.valid){let e=new Map(t.entities.map(e=>[e.id,e])),r=new Set(a.entities.map(e=>e.id));return{ok:!0,root:n(a.rootEntityId,a),changedEntities:a.entities.filter(t=>e.get(t.id)!==t).flatMap(e=>n(e.id,a)??[]),deletedEntityIds:t.entities.map(e=>e.id).filter(e=>!r.has(e)),sideEffects:o(l,i.resolveLocalizable),errors:[]}}return d("uncaught"===s.severity?[{type:"uncaught",entityId:null,message:s.error.message}]:s.entityViolations.filter(({violation:e})=>e.severity===s.severity).map(({entityId:e,violation:t})=>({type:t.type,entityId:e,message:void 0===t.message?null:i.resolveLocalizable(t.message)})))};export const createEntityMeta=(o,c)=>{let p=e=>()=>t(c.manifest,e,o.entity.type).flatMap(t=>{let i=s(e,t,o.entity.id,o.state,c.recipes);return i?[((e,t,i)=>{let{group:n,label:s,description:a,recipes:o}=e,{resolveLocalizable:c}=i.recipes;return{groupId:n.groupId,name:void 0===s?n.instanceName:c(s),description:n.description??(void 0===a?null:c(a)),recipes:o.map(n=>((e,t,i,n)=>{let{key:s,item:a}=e,{resolveLocalizable:o}=n.recipes;return{key:s,name:o(a.title),description:void 0===a.description?null:o(a.description),imageUrl:void 0===a.thumbnailUrl?null:o(a.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,n)=>{let{updates:s,error:a}=((e,t,{entity:i,state:n},{recipes:s})=>{try{return{updates:r(e,t,i.id,n,s),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===s?d([{type:"uncaught",entityId:null,message:a}]):l(s,i,n)})(e,t,i,n):null}})(n,e,t,i))}})(i,o,c)]:[]});return{...Object.fromEntries(e(c.manifest,o.entity.type).map(e=>[e.edgeName,()=>n(e,o.entity.id,o.state,c.recipes)?.map(t=>({...t,dryRun:()=>e.dryRuns?(({field:e},{value:t},r,n)=>{let{entity:s}=r,o=Object.entries(Object.entries(n.manifest.writableFields??{}).find(([e])=>e===s.type)?.[1]??{}).find(([t])=>t===e)?.[1];if(void 0===o)throw Error(`The options of "${e}" on "${s.id}" cannot be dry-run: the schema lists them, but the configurator has no writable field "${e}" on ${s.type}. Regenerate the application so the schema matches the configurator.`);let c=r.state.entities.find(e=>e.id===s.id),p={[o]:t},u=c?n.validateEntity({...c,...p}):{success:!0};return u.success?l([a.DomainEntityModification({entityId:s.id,stateDelta:p,updateTag:i})],r,n):d([{type:"uncaught",entityId:s.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${s.id}" an invalid ${s.type}: ${u.errors.join("; ")}.${e===o?"":` The message names the stored property: ${e} is stored as ${o}.`} The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(e,t,o,c):null}))??null])),childRecipes:p("child"),replaceRecipes:p("replace")}};
+import e from"lodash-es/isEqual.js";import{findAssistantFieldOptions as t,findAssistantRecipeGroups as i,modifyEntityUpdateTag as r,prepareAssistantRecipeUpdates as n,readAssistantFieldOptions as o,readAssistantRecipeGroup as a,systemUpdateFactory as s}from"#package/domain";import{readSideEffects as d}from"./side-effects.js";import{readEntityWarnings as l,readStateWarnings as c,readViolationEntries as u}from"./violations.js";let p=e=>({ok:!1,root:null,changedEntities:[],deletedEntityIds:[],sideEffects:[],warnings:[],errors:e}),m=(e,{state:t},{recipes:i,prepareStateEmission:r,find$Entity:n,validateState:o})=>{let{validity:a,state:s,updates:l}=r(e,t,"committed");if(a.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:d(l,i.resolveLocalizable),warnings:()=>c(a,o(t),i.resolveLocalizable),errors:[]}}return p(u(a,i.resolveLocalizable))};export const createEntityMeta=(d,c)=>{let u=e=>()=>Object.fromEntries(i(c.manifest,e,d.entity.type).map(t=>[t.groupId,()=>{let i=a(e,t,d.entity.id,d.state,c.recipes);return i?((e,t,i)=>{let{group:r,label:o,description:a,recipes:s}=e,{resolveLocalizable:d}=i.recipes;return{groupId:r.groupId,name:void 0===o?r.instanceName:d(o),description:void 0===a?null:d(a),recipes:({keys:r})=>s.filter(e=>!r||r.includes(e.key)).map(r=>((e,t,i,r)=>{let{key:o,item:a}=e,{resolveLocalizable:s}=r.recipes;return{key:o,name:s(a.title),description:void 0===a.description?null:s(a.description),imageUrl:void 0===a.thumbnailUrl?null:s(a.thumbnailUrl),dryRun:()=>t.group.dryRuns?((e,t,i,r)=>{let{updates:o,error:a}=((e,t,{entity:i,state:r},{recipes:o})=>{try{return{updates:n(e,t,i.id,r,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,r);return void 0===o?p([{type:"uncaught",entityId:null,message:a}]):m(o,i,r)})(e,t,i,r):null}})(r,e,t,i))}})(i,d,c):null}]));return{...Object.fromEntries(t(c.manifest,d.entity.type).map(t=>[t.edgeName,({values:i})=>o(t,d.entity.id,d.state,c.recipes)?.filter(t=>!i||i.some(i=>e(i,t.value))).map(e=>({...e,dryRun:()=>t.dryRuns?(({field:e},{value:t},i,n)=>{let{entity:o}=i,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 d=i.state.entities.find(e=>e.id===o.id);if(!d)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 l={[a]:t},c=n.validateEntity({...d,...l});return c.success?m([s.DomainEntityModification({entityId:o.id,stateDelta:l,updateTag:r})],i,n):p([{type:"uncaught",entityId:o.id,message:`Writing ${JSON.stringify(t)} to "${e}" would make "${o.id}" an invalid ${o.type}: ${c.errors.join("; ")}. The option comes from the configurator and cannot be corrected from here, so do not write it.`}])})(t,e,d,c):null}))??null])),childRecipes:u("child"),replaceRecipes:u("replace"),screenshot:({view:e})=>c.takeScreenshot(d,e),warnings:()=>l(d.entity.id,c.validateState(d.state),c.recipes.resolveLocalizable)}};

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

@@ -1,13 +1,36 @@
 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 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';
+import { type AssistantWarning } from './violations.js';
 /** 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;
@@ -23,6 +46,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
@@ -37,6 +62,20 @@ export interface GraphQLExecution {
     readonly message?: string;
     /** What the configurator did, or would do, beyond what the operations asked for, in applied order. */
     readonly sideEffects: readonly string[];
+    /**
+     * The warnings and notices the prepared changes newly cause, whether or not they were committed:
+     * those of the prepared state that the state the operations started from did not have. Empty when
+     * nothing changed or an operation failed.
+     */
+    readonly warnings: readonly AssistantWarning[];
+    /**
+     * The state the operations prepared, when it was committed or held for the user's approval; a
+     * held state is the one committed if the user approves. A caller can recognize its own change in
+     * 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.
@@ -51,10 +90,12 @@ export declare const localize: (value: unknown, resolveLocalizable: (message: Lo
 export declare class GraphQLSystem {
     private readonly _context;
     /**
-     * Compiles the manifest's SDL and checks the schema's semantic rules, once per SDL text, so a schema
-     * that parses but is not valid GraphQL fails every operation with an error result.
+     * Compiles the execution schema of the manifest's SDL and checks its semantic rules, once per SDL
+     * text, so a schema that parses but is not valid GraphQL fails every operation with an error result.
      */
     private readonly _selectSchema;
+    /** Parses the manifest's lens definitions, which the builder has validated, once per text. */
+    private readonly _selectLenses;
     /**
      * Query fields call the root resolvers; entity fields read the stored field or expression their
      * GraphQL name maps to. Rebuilt only when the manifest's field sources change.
@@ -63,10 +104,23 @@ export declare class GraphQLSystem {
     constructor(_context: GraphQLSystemContext);
     private readonly _get$Entity;
     private readonly _find$Entity;
+    private readonly _validateState;
+    private readonly _validateCached;
     private readonly _recipeContext;
     /** 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
@@ -77,26 +131,50 @@ 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
+     * introspection to the standard ones: the agent reads the schema from its prompt, and the schema
+     * operations run against is the widened execution schema, which is not the one to describe.
+     */
+    private readonly _run;
     /**
      * 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.
-     * 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>;
+    /**
+     * The warnings and notices prepared operations newly cause: those of the state their last emission
+     * left that `originalState`, the state they were prepared from, did not have. Empty when nothing
+     * changed or an operation failed, so the original state is validated only for a change.
+     */
+    readWarnings: (originalState: AnyDomainState, prepared: readonly PreparedOperation[]) => readonly AssistantWarning[];
     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,buildSchema as t,defaultFieldResolver as i,getNamedType as o,graphql as a,validateSchema as n}from"graphql";import{assertExistence as r,createSelector as s,isMessageDescriptor as l,isMultilingualString as c}from"@salsita-ai/common/utils";import{DomainEntityIdSchema as h,findAssistantMutation as d}from"#package/domain";import{createEntityMeta as m}from"./entity-meta.js";import{readSideEffects as p}from"./side-effects.js";let f={errors:[new e('No assistant manifest in the application spec. The GraphQL schema is generated from the "assistant" section. Add an "assistant" section to a spec file to expose a schema.')]},u={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.")]},y=new RegExp(h.pattern),g=e=>"object"==typeof e&&null!==e&&"type"in e&&"string"==typeof e.type&&"id"in e&&"string"==typeof e.id,v=(e,t)=>"object"==typeof e&&null!==e?Reflect.get(e,t):void 0,S=e=>e instanceof Error?e.message:String(e),x=e=>/[.!?]$/.test(e)?e:`${e}.`,_=e=>"object"==typeof e&&null!==e&&Object.getPrototypeOf(e)===Object.prototype,w=(e,t)=>{let i=_(e)?e._raw:void 0;if(g(i))return i;if(!Array.isArray(e)&&!_(e))return e;if(t.has(e))throw Error("The value contains itself. Return ids or copies of the values instead of objects that reference each other.");let o=new Set([...t,e]);return Array.isArray(e)?e.map(e=>w(e,o)):Object.fromEntries(Object.entries(e).map(([e,t])=>[e,w(t,o)]))};export const localize=(e,t)=>Array.isArray(e)?e.map(e=>localize(e,t)):"string"==typeof e||l(e)||c(e)?t(e):e;let E=t=>new e(`The GraphQL schema generated from the "assistant" manifest is invalid: ${x(t)} Regenerate the application so the schema is rebuilt from the current spec.`),$=e=>(e.errors?.length??0)>0,b=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=s([s.leaf(e=>e)],e=>{try{let i=t(e),o=n(i);return o.length>0?E(o.map(e=>e.message).join(" ")):i}catch(e){return E(S(e))}});_selectFieldResolver=s([s.leaf(e=>e)],t=>(a,n,r,s)=>{if(s.parentType===s.schema.getQueryType())return i(a,n,r,s);if(s.parentType===s.schema.getMutationType())return this._resolveMutation(s.fieldName,String(s.path.key),n,r);if(!g(a))return i(a,n,r,s);if("meta"===s.fieldName){let e;return m({entity:a,state:("object"==typeof(e=v(a,"_state"))&&null!==e&&"entities"in e&&"rootEntityId"in e?e:void 0)??r.state},{manifest:r.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},h=((t,i)=>{try{return v(t,i)}catch(o){throw new e(`Expression "${i}" failed on ${g(t)?t.id:"an entity"}: ${x(S(o))} The expression threw while the query read it; fix the expression or the configuration state it reads.`,{originalError:o instanceof Error?o:void 0})}})(a,l);return c?localize(h,this._context.domainServicesSelectors.getResolveLocalizable()):l.startsWith("$")&&"JSON"===o(s.returnType).name?((t,i,o)=>{try{return w(o,new Set)}catch(o){throw new e(`Expression "${i}" returned a value that is not plain serializable data on ${g(t)?t.id:"an entity"}: ${x(S(o))} A JSON field can only return data that serializes to JSON.`,{originalError:o instanceof Error?o:void 0})}})(a,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 o=i.rootEntityId;let a=t.filter(e=>!y.test(e));if(a.length>0)throw new e(`${a.map(e=>`"${e}"`).join(", ")} ${1===a.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=>y.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=>g(e)?e.type:void 0;initialize=()=>{};_resolveMutation=(t,i,o,a)=>{if(void 0!==a.failedMutationField)throw new e(`Not run: the earlier field "${a.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,a)}catch(e){throw a.failedMutationField=i,e}};_runMutation=(t,i,o)=>{let a=d(t,o.manifest);if(!a)throw new e(`The schema declares the mutation "${t}", but the configurator has no implementation for it. Regenerate the application so the schema matches the configurator.`);let n=o.state,r=a.implementation(i,n,{manifest:o.manifest,action:this._context.domainContextSelectors.getActionSystem().createContext(n),resolveLocalizable:this._context.domainServicesSelectors.getResolveLocalizable()});if(r.updates.length>0){let i=this._context.domainContextSelectors.getStoreSystem().prepareStateEmission(r.updates,n,"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: ${x(S(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 r.readResult({previousState:n,state:o.state})};_setup=()=>{let t=this._context.specSelectors.getAssistant();if(!t)return{ready:!1,result:f};let i=this._selectSchema(t.sdl);return i instanceof e?{ready:!1,result:{errors:[i]}}:{ready:!0,assistant:t,schema:i,fieldResolver:this._selectFieldResolver(t.fields)}};prepare=async(e,t)=>{let i,o=this._setup();if(!o.ready)return t.map(()=>({result:o.result,emissions:[]}));let n={manifest:o.assistant,state:e,emissions:[],failedMutationField:void 0},r=[];for(let[e,s]of t.entries())if(void 0===i){let t=n.emissions.length;n.failedMutationField=void 0;let l=await a({schema:o.schema,source:s.document,rootValue:this._rootValue,contextValue:n,variableValues:s.variables,operationName:s.operationName,fieldResolver:o.fieldResolver,typeResolver:this._resolveType});r.push({result:l,emissions:n.emissions.slice(t)}),$(l)&&(i=e)}else r.push({result:b(i),emissions:[]});return r};readSideEffects=e=>{let t=this._context.domainServicesSelectors.getResolveLocalizable();return e.flatMap(({emissions:e})=>e.flatMap(e=>p(e.updates,t)))};_prepareAndCommit=async e=>{let t,i,o,a=this._context.domainContextSelectors.getStoreSystem(),n=await this.prepare(a.stateSlices.committed.value.state,e),s=n.map(({result:e})=>e),l=this.readSideEffects(n),c=n.flatMap(e=>e.emissions);return s.some($)||0===c.length?{results:s,sideEffects:l,outcome:"none"}:{results:s,sideEffects:l,outcome:a.commitPrepared((t=r(c[0]),i=r(c[c.length-1]),o=c.some(e=>void 0!==e.transformationLog),{kind:"committed",previousState:t.previousState,state:i.state,updates:c.flatMap(e=>e.updates),validity:i.validity,transformationLog:o?c.flatMap(e=>e.transformationLog??[]):void 0}))}};execute=async e=>{if(!this._context.domainContextSelectors.getStoreSystem().isInitialized)return{results:e.map(()=>u),committed:!1,sideEffects:[]};let t=await this._prepareAndCommit(e),{results:i,sideEffects:o,outcome:a}="conflict"===t.outcome?await this._prepareAndCommit(e):t;return"committed"===a?{results:i,committed:!0,sideEffects:o}:"held"===a?{results:i,committed:!1,message:"The changes were not committed yet: the application held them, usually to ask the user for approval. They may still be applied once the user approves, and the next turn shows whether they were. Do not send the operations again.",sideEffects:o}:"conflict"===a?{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 a,validate as s,validateSchema as l}from"graphql";import{assertExistence as c,createSelector as h,isMessageDescriptor as d,isMultilingualString as u}from"@salsita-ai/common/utils";import{AGENT_SCREENSHOT_MAX_SIDE as m,DomainEntityIdSchema as f,agentScreenshotComponent as p,createAssistantExecutionSchema as g,findAssistantMutation as v}from"#package/domain";import{ExportBusyError as y}from"../export-system/export-busy-error.js";import{closeUnclosedBraces as S}from"./close-unclosed-braces.js";import{createEntityMeta as w}from"./entity-meta.js";import{injectAssistantLenses as _}from"./inject-assistant-lenses.js";import{readSideEffects as x}from"./side-effects.js";import{ViolationsError as $,readStateWarnings as b,readViolationEntries as E}from"./violations.js";let T={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.")]},C={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.")]},M="Not taken: another configuration was loaded while this request ran. Query the current configuration before asking for screenshots again.",R=class ScreenshotTooLargeError extends Error{constructor(e,t){super(`The view is configured at ${e} \xd7 ${t} px, more than the ${m} \xd7 ${m} px a screenshot may have.`),this.name="ScreenshotTooLargeError"}},k=new RegExp(f.pattern),j=[...a,t],L=e=>"object"==typeof e&&null!==e&&"type"in e&&"string"==typeof e.type&&"id"in e&&"string"==typeof e.id,N=(e,t)=>"object"==typeof e&&null!==e?Reflect.get(e,t):void 0,A=e=>e instanceof Error?e.message:String(e),z=e=>/[.!?]$/.test(e)?e:`${e}.`,q=e=>"object"==typeof e&&null!==e&&Object.getPrototypeOf(e)===Object.prototype,O=(e,t)=>{let i=q(e)?e._raw:void 0;if(L(i))return i;if(!Array.isArray(e)&&!q(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=>O(e,n)):Object.fromEntries(Object.entries(e).map(([e,t])=>[e,O(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 F=t=>new e(`The configurator cannot handle this request: ${z(t)} This is a fault in the configurator, not in your request. Tell the user this is not available.`),I="SCREENSHOT_NOT_TAKEN",V=(t,i)=>new e(t,{originalError:i,extensions:{code:I}}),P=e=>(e.errors??[]).some(e=>e.extensions.code!==I),D=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=g(e),i=l(t);return i.length>0?F(i.map(e=>e.message).join(" ")):t}catch(e){return F(A(e))}});_selectLenses=h([h.leaf(e=>e)],e=>r(e));_selectFieldResolver=h([h.leaf(e=>e)],t=>(n,r,a,s)=>{if(s.parentType===s.schema.getQueryType())return i(n,r,a,s);if(s.parentType===s.schema.getMutationType())return this._resolveMutation(s.fieldName,String(s.path.key),r,a);if(!L(n))return i(n,r,a,s);if("meta"===s.fieldName){let e;return w({entity:n,state:("object"==typeof(e=N(n,"_state"))&&null!==e&&"entities"in e&&"rootEntityId"in e?e:void 0)??a.state},{manifest:a.manifest,recipes:this._recipeContext(),prepareStateEmission:(e,t,i)=>{let n=this._context.domainContextSelectors.getStoreSystem().prepareStateEmission(e,t,i);return a.validities.set(n.state,n.validity),n},find$Entity:(e,t)=>this._find$Entity(e,t),validateEntity:e=>this._context.domainContextSelectors.getDomain().validateEntity(e),takeScreenshot:(e,t)=>this._takeScreenshot(e,t,a),validateState:e=>this._validateCached(e,a)})}let{source:l,localized:c}=t[s.parentType.name]?.[s.fieldName]??{source:s.fieldName},h=((t,i)=>{try{return N(t,i)}catch(n){throw new e(`Expression "${i}" failed on ${L(t)?t.id:"an entity"}: ${z(A(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(s.returnType).name?((t,i,n)=>{try{return O(n,new Set)}catch(n){throw new e(`Expression "${i}" returned a value that is not plain serializable data on ${L(t)?t.id:"an entity"}: ${z(A(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;_validateState=e=>this._context.domainContextSelectors.getValidationProjections().validateState(e);_validateCached=(e,{validities:t})=>{let i=t.get(e);if(i)return i;let n=this._validateState(e);return t.set(e,n),n};_recipeContext=()=>({componentReader:this._context.domainContextSelectors.getComponentReader(),recipeCooker:this._context.domainContextSelectors.getRecipeCookerSystem(),resolveLocalizable:this._context.domainServicesSelectors.getResolveLocalizable()});_rootValue={warnings:(e,t)=>b(this._validateCached(t.state,t),void 0,this._context.domainServicesSelectors.getResolveLocalizable()),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=>!k.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=>k.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=>L(e)?e.type:void 0;_generation={active:!0};_renderScreenshot=async(e,t,i)=>{let n=this._context.domainContextSelectors.getComponentReader().readOneComponent({entityId:e,componentType:p,instanceName:t},i);if(!n)return null;let{width:o,height:r}=n.state;if(o>m||r>m)throw new R(o,r);let a=await this._context.renderScreenshot(n,i);return null===a?null:new Blob([a],{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=v(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,a=o.implementation(i,r,{manifest:n.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"),{validity:o}=i;if("uncaught"===o.severity)throw new e(`The changes of "${t}" were not applied, because the resulting configuration is invalid: validating it threw: ${z(A(o.error))} Change the request so the configuration stays valid.`,{originalError:o.error});if(!o.valid)throw new $(`The changes of "${t}" were not applied, because the resulting configuration has ${o.severity} violations.`,E(o,this._context.domainServicesSelectors.getResolveLocalizable()));n.emissions.push(i),n.validities.set(i.state,o),n.state=i.state}return a.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 a=o.lastScreenshot.then(async()=>{if(!o.generation.active)throw V(M);let e=await this._renderScreenshot(t.id,r.instanceName,i).catch(e=>{throw V(e instanceof y?"User made concurrent actions that prevented the screenshot from being taken, try again":e instanceof R?`The screenshot of ${t.id} from "${n}" cannot be taken: ${e.message} Tell the user the screenshot is not available.`:`The screenshot of ${t.id} from "${n}" could not be taken: ${z(A(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 V(M);if(null===e)return null;let{imageId:a}=await this._context.uploadScreenshot(e).catch(e=>{throw V(`The screenshot of ${t.id} from "${n}" was taken but could not be stored: ${z(A(e))} Try again; if it fails again, tell the user the screenshot is not available.`,e instanceof Error?e:void 0)}),s=`${t.id}/${n}`,l=[...o.screenshots.values()].filter(e=>e.entityId===t.id&&e.view===n).length,c=0===l?s:`${s}#${l+1}`;return o.screenshots.set(c,{entityId:t.id,view:n,imageId:a}),{image:c}});return o.lastScreenshot=a.catch(()=>void 0),a};_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:T};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=async(t,i,o,a)=>{var l;let c;try{c=r(t)}catch(t){return{errors:[t instanceof e?t:new e(A(t))]}}let h=s(o.schema,c,j);return h.length>0?{errors:h}:(l=await n({schema:o.schema,document:c,rootValue:this._rootValue,contextValue:a,variableValues:i.variables,operationName:i.operationName,fieldResolver:o.fieldResolver,typeResolver:this._resolveType}),l.errors?.some(e=>e.originalError instanceof $)?{...l,errors:l.errors.flatMap(t=>t.originalError instanceof $?t.originalError.entries.map(({type:i,entityId:n,message:o})=>new e(o??i,{nodes:t.nodes,source:t.source,positions:t.positions,path:t.path,extensions:{code:"VIOLATION",type:i,entityId:n}})):[t])}:l)};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 a={manifest:r.assistant,state:t,emissions:[],failedMutationField:void 0,screenshots:new Map,lastScreenshot:Promise.resolve(),generation:n,validities:new WeakMap},s=[];for(let[t,n]of i.entries())if(void 0===o){let i=a.emissions.length,l=a.screenshots.size;a.failedMutationField=void 0;let c=S(n.document),h=r.lenses?_(c,r.lenses):c,d=h instanceof e?{errors:[h]}:await this._run(h,n,r,a);await a.lastScreenshot,s.push({result:d,emissions:a.emissions.slice(i),screenshots:new Map([...a.screenshots].slice(l))}),P(d)&&(o=t)}else s.push({result:D(o),emissions:[],screenshots:new Map});return s};readSideEffects=e=>{let t=this._context.domainServicesSelectors.getResolveLocalizable();return e.flatMap(({emissions:e})=>e.flatMap(e=>x(e.updates,t)))};readScreenshots=e=>new Map(e.flatMap(({screenshots:e})=>[...e]));readWarnings=(e,t)=>{let i=t.flatMap(({emissions:e})=>e).at(-1);return void 0===i||t.some(({result:e})=>P(e))?[]:b(i.validity,this._validateState(e),this._context.domainServicesSelectors.getResolveLocalizable())};_prepareAndCommit=async(e,t)=>{let i,n,o,r=this._context.domainContextSelectors.getStoreSystem(),a=r.stateSlices.committed.value.state,s=await this.prepare(a,e,t),l=s.map(({result:e})=>e),h=this.readSideEffects(s),d=this.readScreenshots(s),u=s.flatMap(e=>e.emissions);if(!t.active)return{results:l,sideEffects:h,screenshots:d,warnings:[],outcome:"conflict"};if(l.some(P)||0===u.length)return{results:l,sideEffects:h,screenshots:d,warnings:[],outcome:"none"};let m=(i=c(u[0]),n=c(u[u.length-1]),o=u.some(e=>void 0!==e.transformationLog),{kind:"committed",previousState:i.previousState,state:n.state,updates:u.flatMap(e=>e.updates),validity:n.validity,transformationLog:o?u.flatMap(e=>e.transformationLog??[]):void 0});return{results:l,sideEffects:h,screenshots:d,warnings:this.readWarnings(a,s),outcome:r.commitPrepared(m),preparedState:m.state}};execute=async e=>{let t=this._generation;if(!this._context.domainContextSelectors.getStoreSystem().isInitialized)return{results:e.map(()=>C),committed:!1,sideEffects:[],warnings:[],screenshots:new Map};let i=await this._prepareAndCommit(e,t),{results:n,sideEffects:o,warnings:r,screenshots:a,outcome:s,preparedState:l}="conflict"===i.outcome&&t.active?await this._prepareAndCommit(e,t):i;return"committed"===s?{results:n,committed:!0,sideEffects:o,warnings:r,screenshots:a,preparedState:l}:"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,warnings:r,screenshots:a,preparedState:l}:"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,warnings:r,screenshots:a}:{results:n,committed:!1,sideEffects:o,warnings:r,screenshots:a}}}

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

@@ -0,0 +1,11 @@
+import { type DocumentNode, GraphQLError } from 'graphql';
+/**
+ * Makes the lenses an operation document spreads available to it: appends the definition of every
+ * lens the document spreads, with the copies that definition spreads in turn, taken from the
+ * manifest's lens `definitions`. Appending keeps the positions GraphQL reports for the caller's own
+ * text. A document that defines a fragment under the name of a lens, or of a copy of one, is
+ * rejected, since the caller would silently read its own selection instead of the lens. A document
+ * that does not parse is returned as it is, so GraphQL reports the syntax error; a spread that names
+ * no lens is left for GraphQL to report as an unknown fragment.
+ */
+export declare const injectAssistantLenses: (document: string, definitions: DocumentNode) => string | GraphQLError;

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

@@ -0,0 +1 @@
+import{GraphQLError as e,Kind as n,parse as t,print as a,visit as i}from"graphql";let r=e=>{let n=[];return i(e,{FragmentSpread:e=>{n.push(e.name.value)}}),n};export const injectAssistantLenses=(i,o)=>{let l,s=new Map;for(let e of o.definitions)e.kind===n.FRAGMENT_DEFINITION&&s.set(e.name.value,e);try{l=t(i)}catch{return i}for(let t of l.definitions)if(t.kind===n.FRAGMENT_DEFINITION&&s.has(t.name.value)){let n=t.name.value.split("__")[0];return new e(`A built-in fragment named "${n}" already exists, so "${t.name.value}" cannot be defined. Remove the definition and spread "...${n}", or give your fragment another name.`)}let m=new Map,u=[...r(l)];for(;u.length>0;){let e=u.pop(),n=void 0===e?void 0:s.get(e);n&&!m.has(n.name.value)&&(m.set(n.name.value,n),u.push(...r(n)))}return 0===m.size?i:[i,...[...m.values()].map(a)].join("\n\n")};

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

@@ -0,0 +1,40 @@
+import type { Localizable } from '@salsita-ai/common/utils';
+import type { DomainEntity, EntityId, StateValidationResult } from '#package/domain';
+type AnyStateValidationResult = StateValidationResult<DomainEntity<string>, string>;
+/** One violation that makes a change fail, as the agent reads it; a violation can sit on a virtual entity. */
+export interface ViolationEntry {
+    readonly type: string;
+    readonly entityId: EntityId | null;
+    readonly message: string | null;
+}
+/** One warning or notice, which never makes a change fail. */
+export interface AssistantWarning {
+    readonly type: string;
+    readonly severity: 'warning' | 'notice';
+    readonly entityId: EntityId | null;
+    readonly message: string | null;
+}
+/**
+ * Thrown by a mutation field whose changes would leave the configuration invalid. graphql-js reports
+ * one error per failed field, so the field throws this one error and the executor's caller replaces
+ * it with one GraphQL error per violation.
+ */
+export declare class ViolationsError extends Error {
+    readonly entries: readonly ViolationEntry[];
+    constructor(message: string, entries: readonly ViolationEntry[]);
+}
+/**
+ * The violations an invalid validity fails on: those of its failing severity, or the one error that
+ * validation threw.
+ */
+export declare const readViolationEntries: (validity: Extract<AnyStateValidationResult, {
+    readonly valid: false;
+}>, resolveLocalizable: (message: Localizable) => string) => readonly ViolationEntry[];
+/**
+ * The warnings and notices of `after` that `before` did not have, in the order of `after`; every one
+ * of `after` when there is no `before`.
+ */
+export declare const readStateWarnings: (after: AnyStateValidationResult, before: AnyStateValidationResult | undefined, resolveLocalizable: (message: Localizable) => string) => readonly AssistantWarning[];
+/** The warnings and notices of a validity that are on one entity, in the order of the validity. */
+export declare const readEntityWarnings: (entityId: EntityId, validity: AnyStateValidationResult, resolveLocalizable: (message: Localizable) => string) => readonly AssistantWarning[];
+export {};

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

@@ -0,0 +1 @@
+export class ViolationsError extends Error{entries;constructor(e,t){super(e),this.entries=t}}let e=(e,t)=>void 0===e?null:t(e);export const readViolationEntries=(t,r)=>"uncaught"===t.severity?[{type:"uncaught",entityId:null,message:t.error.message}]:t.entityViolations.filter(({violation:e})=>e.severity===t.severity).map(({entityId:t,violation:i})=>({type:i.type,entityId:t,message:e(i.message,r)}));let t=e=>null===e.severity||"uncaught"===e.severity?[]:e.entityViolations.filter(({violation:e})=>{let t;return"warning"===(t=e.severity)||"notice"===t}),r=({entityId:e,violation:{type:t,severity:r}})=>JSON.stringify([e,t,r]),i=(t,r,i)=>({type:r.type,severity:"notice"===r.severity?"notice":"warning",entityId:t,message:e(r.message,i)});export const readStateWarnings=(e,n,s)=>{let a=new Set(void 0===n?[]:t(n).map(r));return t(e).filter(e=>!a.has(r(e))).map(({entityId:e,violation:t})=>i(e,t,s))};export const readEntityWarnings=(e,r,n)=>t(r).filter(t=>t.entityId===e).map(({violation:t})=>i(e,t,n));

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 {};