@salsita-ai/sdk 0.50.0-develop.662fa65a4c → 0.50.0-develop.6806625cca

package/dist/configurator/application-runtime/extensions/systems/assistant-system/composer-attachments.d.ts

@@ -0,0 +1,68 @@
+import type { ObservableWithLastValue } from '@salsita-ai/common/utils';
+import type { AssistantAnnotationPin, AssistantAnnotationSource } from '@salsita-ai/contracts/assistant';
+/** The most images one message can carry, annotations included. */
+export declare const MAX_COMPOSER_ATTACHMENTS = 4;
+/**
+ * An image or an annotation attached to the message being written, prepared for the upload; see
+ * {@link AssistantSystem.composerAttachments$}.
+ */
+export interface AssistantDraftAttachment {
+    readonly id: string;
+    readonly blob: Blob;
+    /** The comment pins of an annotation; nothing for an image. */
+    readonly pins?: ReadonlyArray<AssistantAnnotationPin>;
+    /** What an annotation marks up; nothing for an image. */
+    readonly source?: AssistantAnnotationSource;
+}
+/** What makes an attached blob an annotation. */
+export interface AssistantDraftAnnotation {
+    readonly pins: ReadonlyArray<AssistantAnnotationPin>;
+    readonly source: AssistantAnnotationSource;
+}
+/**
+ * The attachments of the message being written, up to {@link MAX_COMPOSER_ATTACHMENTS}. A slot can
+ * be reserved while an image is prepared or an annotation made, so nothing attached meanwhile pushes
+ * the message over the limit once it is done.
+ */
+export declare class ComposerAttachments {
+    private readonly _attachments;
+    private readonly _hasFreeSlot;
+    /** Slots held for images being prepared and annotations being made. */
+    private _reserved;
+    /** Counts the clears, so a slot held across one knows its message is gone. */
+    private _generation;
+    /** The attachments, in their order. It never completes. */
+    readonly attachments$: ObservableWithLastValue<ReadonlyArray<AssistantDraftAttachment>>;
+    /** Whether one more attachment fits, counting the reserved slots. It never completes. */
+    readonly hasFreeSlot$: ObservableWithLastValue<boolean>;
+    /**
+     * Holds a slot until the returned function is called, which frees it and returns whether the message
+     * it was held for is still being written: `false` once the attachments were cleared meanwhile, when
+     * what it was held for is not to be attached. Calling it again frees nothing. `null` when the message
+     * is full.
+     */
+    reserveSlot: () => (() => boolean) | null;
+    /**
+     * Attaches an image, or an annotation when `annotation` is given, after the others, and returns its
+     * id; `null` when the message is full. The slot reserved for it, if any, is to be freed first.
+     */
+    attach: (blob: Blob, annotation?: AssistantDraftAnnotation) => string | null;
+    /**
+     * Puts attachments that were taken off back in front of the others, as many as fit, the first ones
+     * first. Returns whether all of them fit.
+     */
+    restore: (attachments: ReadonlyArray<AssistantDraftAttachment>) => boolean;
+    /**
+     * Puts an annotation in place of the attachment `id`, at its position, and returns the annotation's
+     * id; `null`, and nothing changes, when `id` is no longer attached. It takes no other slot.
+     */
+    replace: (id: string, blob: Blob, annotation: AssistantDraftAnnotation) => string | null;
+    /** Takes an attachment off; nothing happens when it is not attached. */
+    remove: (id: string) => void;
+    /**
+     * Takes every attachment off: the message is gone. Reserved slots stay held until they are freed, and
+     * what they were held for is not attached.
+     */
+    clear: () => void;
+    private _update;
+}

package/dist/configurator/application-runtime/extensions/systems/assistant-system/composer-attachments.js

@@ -0,0 +1 @@
+import{BehaviorSubject as t}from"rxjs";export const MAX_COMPOSER_ATTACHMENTS=4;let e=0;export class ComposerAttachments{_attachments=new t([]);_hasFreeSlot=new t(!0);_reserved=0;_generation=0;attachments$=this._attachments;hasFreeSlot$=this._hasFreeSlot;reserveSlot=()=>{if(!this._hasFreeSlot.value)return null;let t=this._generation,e=!0;return this._reserved+=1,this._update(this._attachments.value),()=>(e&&(e=!1,this._reserved-=1,this._update(this._attachments.value)),t===this._generation)};attach=(t,a)=>{if(!this._hasFreeSlot.value)return null;let s=`attachment-${++e}`;return this._update([...this._attachments.value,{id:s,blob:t,...a}]),s};restore=t=>{let e=this._attachments.value,a=t.slice(0,Math.max(0,4-e.length-this._reserved));return this._update([...a,...e]),a.length===t.length};replace=(t,a,s)=>{let h=this._attachments.value;if(!h.some(e=>e.id===t))return null;let r={id:`attachment-${++e}`,blob:a,...s};return this._update(h.map(e=>e.id===t?r:e)),r.id};remove=t=>{let e=this._attachments.value,a=e.filter(e=>e.id!==t);a.length!==e.length&&this._update(a)};clear=()=>{this._generation+=1,this._attachments.value.length>0&&this._update([])};_update=t=>{t!==this._attachments.value&&this._attachments.next(t);let e=t.length+this._reserved<4;e!==this._hasFreeSlot.value&&this._hasFreeSlot.next(e)}}

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

@@ -7,7 +7,7 @@ import type { GraphQLExecution, GraphQLSystem } from '../graphql-system/graphql-
  * mode current at that moment, never against ones captured when its reply began streaming.
  */
 export interface AssistantToolDependencies {
-    readonly getGraphQLSystem: () => Pick<GraphQLSystem, 'prepare' | 'execute' | 'readSideEffects' | 'readScreenshots'>;
+    readonly getGraphQLSystem: () => Pick<GraphQLSystem, 'prepare' | 'execute' | 'readSideEffects' | 'readWarnings' | 'readScreenshots'>;
     readonly getStoreSystem: () => {
         readonly isInitialized: boolean;
         readonly stateSlices: {
@@ -35,7 +35,8 @@ export interface AssistantToolDependencies {
 /**
  * A tool result as the chat client accepts it: content parts, the execution's JSON as a text part
  * followed, per screenshot, by its label as a text part and its picture as an image part, so the
- * model reads each picture under the label its `image` field returned. The client deep-clones a
+ * model reads each picture under the label its `image` field returned; the image part references the picture the browser uploaded, which the server
+ * inlines only for the model. The client deep-clones a
  * result and rejects anything that is not plain JSON, so the `GraphQLError` instances of a result
  * are formatted through their `toJSON` and `undefined` members are dropped. The prepared state stays
  * in the browser.
@@ -44,12 +45,16 @@ export declare const toToolResult: ({ preparedState, screenshots, ...execution }
 /**
  * Browser implementation of the assistant's `query` tool: prepares the operations from the
  * committed state and drops their emissions, so mutations in the list show a hypothetical state and
- * the configuration, the undo stack and the saved revision stay as they were. The side effects of
- * the dropped emissions are still reported, as what the changes would do.
+ * the configuration, the undo stack and the saved revision stay as they were. The side effects and
+ * the new warnings of the dropped emissions are still reported, as what the changes would do.
  */
 export declare const createQueryClientTool: (dependencies: AssistantToolDependencies) => import("@tanstack/ai").ClientTool<{
     type: string;
     properties: {
+        title: {
+            type: string;
+            description: string;
+        };
         operations: {
             type: string;
             minItems: number;
@@ -79,6 +84,10 @@ export declare const createQueryClientTool: (dependencies: AssistantToolDependen
     inputSchema: {
         type: string;
         properties: {
+            title: {
+                type: string;
+                description: string;
+            };
             operations: {
                 type: string;
                 minItems: number;
@@ -132,6 +141,10 @@ export declare const createQueryClientTool: (dependencies: AssistantToolDependen
 export declare const createApplyClientTool: (dependencies: AssistantToolDependencies) => import("@tanstack/ai").ClientTool<{
     type: string;
     properties: {
+        title: {
+            type: string;
+            description: string;
+        };
         operations: {
             type: string;
             minItems: number;
@@ -161,6 +174,10 @@ export declare const createApplyClientTool: (dependencies: AssistantToolDependen
     inputSchema: {
         type: string;
         properties: {
+            title: {
+                type: string;
+                description: string;
+            };
             operations: {
                 type: string;
                 minItems: number;

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

@@ -1 +1 @@
-import{AssistantGraphQLToolInput as e,applyTool as t,queryTool as o}from"@salsita-ai/contracts/assistant";let a=e=>({results:[],committed:!1,message:e,sideEffects:[],screenshots:new Map});export const toToolResult=({preparedState:e,screenshots:t,...o})=>[{type:"text",content:JSON.stringify(o)},...[...t].flatMap(([e,{data:t,mimeType:o}])=>[{type:"text",content:e},{type:"image",source:{type:"data",value:t,mimeType:o}}])];let i=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:a(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const createQueryClientTool=e=>o.client(async t=>{let o=i(t);if(!o.ok)return toToolResult(o.refusal);let s=e.getStoreSystem();if(!s.isInitialized)return toToolResult(a("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading."));let n=e.getGraphQLSystem(),r=await n.prepare(s.stateSlices.committed.value.state,o.operations);return toToolResult({results:r.map(({result:e})=>e),committed:!1,sideEffects:n.readSideEffects(r),screenshots:n.readScreenshots(r)})});export const createApplyClientTool=e=>t.client(async(t,o)=>{if("finalize"===e.getActiveMode())return toToolResult(a("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it."));if(e.getIsViewMode())return toToolResult(a("Nothing was run, because the configuration is read-only right now: the user may view it but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it. Call apply again only once the configuration is editable."));let s=i(t);if(!s.ok)return toToolResult(s.refusal);let n=await e.getGraphQLSystem().execute(s.operations),r=o?.toolCallId;return void 0!==r&&void 0!==n.preparedState&&e.rememberCommit(r,n.preparedState),n.committed&&e.clearChanges(),toToolResult(n)});
+import{AssistantGraphQLToolInput as e,applyTool as t,assistantImageReference as o,queryTool as a}from"@salsita-ai/contracts/assistant";let i=e=>({results:[],committed:!1,message:e,sideEffects:[],screenshots:new Map,warnings:[]});export const toToolResult=({preparedState:e,screenshots:t,...a})=>[{type:"text",content:JSON.stringify(a)},...[...t].flatMap(([e,{imageId:t}])=>[{type:"text",content:e},{type:"image",source:{type:"url",value:o(t)}}])];let s=t=>{let o=e.safeParse(t);if(!o.success){let e=o.error.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("; ");return{ok:!1,refusal:i(`Nothing was run, because the tool input is not a list of operations (${e}). Send { "operations": [{ "query": "<one GraphQL operation>" }] } with at least one item.`)}}return{ok:!0,operations:o.data.operations.map(({query:e,variables:t,operationName:o})=>({document:e,variables:t??void 0,operationName:o??void 0}))}};export const createQueryClientTool=e=>a.client(async t=>{let o=s(t);if(!o.ok)return toToolResult(o.refusal);let a=e.getStoreSystem();if(!a.isInitialized)return toToolResult(i("Nothing was run, because the configuration is not loaded yet, so there is no state to query. Call the tool again once the configurator has finished loading."));let n=e.getGraphQLSystem(),r=a.stateSlices.committed.value.state,l=await n.prepare(r,o.operations);return toToolResult({results:l.map(({result:e})=>e),committed:!1,sideEffects:n.readSideEffects(l),screenshots:n.readScreenshots(l),warnings:n.readWarnings(r,l)})});export const createApplyClientTool=e=>t.client(async(t,o)=>{if("finalize"===e.getActiveMode())return toToolResult(i("Nothing was run, because changes cannot be applied in this session: the user may view this configuration but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it."));if(e.getIsViewMode())return toToolResult(i("Nothing was run, because the configuration is read-only right now: the user may view it but not change it. The query tool still works here, including mutations, to show what a change would do without keeping it. Call apply again only once the configuration is editable."));let a=s(t);if(!a.ok)return toToolResult(a.refusal);let n=await e.getGraphQLSystem().execute(a.operations),r=o?.toolCallId;return void 0!==r&&void 0!==n.preparedState&&e.rememberCommit(r,n.preparedState),n.committed&&e.clearChanges(),toToolResult(n)});

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

@@ -0,0 +1,13 @@
+interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Draws an image onto a canvas of `area` pixels for the annotation editor: contain-fitted and centred
+ * over `background`, which also fills the margins. An SVG is drawn at the fitted size, so it stays sharp.
+ *
+ * Rejects when the image cannot be decoded, and when the browser taints the canvas with it, because
+ * a tainted canvas cannot be flattened into the annotation.
+ */
+export declare const rasterizeImage: (image: Blob, background: string, area: Size) => Promise<HTMLCanvasElement>;
+export {};

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

@@ -0,0 +1 @@
+let t="image/svg+xml",e=t=>{let e=/^\s*([\d.]+)(px)?\s*$/.exec(t??""),i=e?Number(e[1]):NaN;return i>0?i:void 0},i=async i=>{let a=new DOMParser().parseFromString(await i.text(),t).documentElement,[,,r=NaN,h=NaN]=(a.getAttribute("viewBox")??"").trim().split(/[\s,]+/).map(Number);if(r>0&&h>0)return{width:r,height:h};let n=e(a.getAttribute("width")),d=e(a.getAttribute("height"));return void 0!==n&&void 0!==d?{width:n,height:d}:void 0};export const rasterizeImage=async(e,a,r)=>{let h=URL.createObjectURL(e);try{let n=new Image;n.src=h,await n.decode();let d=(e.type===t?await i(e):void 0)??(n.naturalWidth>0&&n.naturalHeight>0?{width:n.naturalWidth,height:n.naturalHeight}:r),g=Math.min(r.width/d.width,r.height/d.height),l=d.width*g,o=d.height*g,w=document.createElement("canvas");w.width=r.width,w.height=r.height;let m=w.getContext("2d");if(!m)throw Error("The browser gave no 2D canvas to draw the annotated image on.");return m.fillStyle=a,m.fillRect(0,0,r.width,r.height),m.drawImage(n,(r.width-l)/2,(r.height-o)/2,l,o),m.getImageData(0,0,1,1),w}finally{URL.revokeObjectURL(h)}};

package/dist/configurator/application-runtime/extensions/systems/assistant-system/speakable-reply.d.ts

@@ -0,0 +1,7 @@
+import type { UIMessage } from '@tanstack/ai-client';
+/**
+ * Whether the server reads an assistant message aloud: its text parts, cleaned to speech, say something and stay
+ * within {@link ASSISTANT_SPEECH_MAX_CHARACTERS}. A reply that is still being written is not asked about: its text
+ * changes with every chunk.
+ */
+export declare const isSpeakableReply: (message: UIMessage) => boolean;

package/dist/configurator/application-runtime/extensions/systems/assistant-system/speakable-reply.js

@@ -0,0 +1 @@
+import{ASSISTANT_SPEECH_MAX_CHARACTERS as t,buildSpeechText as e}from"@salsita-ai/contracts/assistant";let a=new WeakMap;export const isSpeakableReply=s=>{if("assistant"!==s.role)return!1;let r=a.get(s.parts);if(void 0!==r)return r;let n=e(s.parts.flatMap(t=>"text"===t.type?[t.content]:[])),p=""!==n&&n.length<=t;return a.set(s.parts,p),p};

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

@@ -65,6 +65,10 @@ export declare class CameraControlSystem {
      */
     private readonly _canvasPadding$;
     readonly canvasPadding$: ObservableWithLastValue<CanvasPadding>;
+    /** The padding the interactive cameras were last offset by, through `applyCameraOffset`. */
+    private _appliedCameraOffset;
+    /** How many holders keep CameraPadding from writing the offset; see `holdCameraOffset`. */
+    private _cameraOffsetHolds;
     private _generation;
     private _pendingAbortController;
     private _lastTransition;
@@ -118,6 +122,45 @@ export declare class CameraControlSystem {
     readonly fitRootCamera: () => void;
     readonly fitEntity: (id: DomainEntityId<string>) => void;
     readonly setCameraOffset: (props: CameraOffsetProps) => void;
+    /**
+     * The padding the interactive cameras were last offset by; a glide starts from it.
+     *
+     * @internal
+     */
+    get appliedCameraOffset(): CanvasPadding;
+    /**
+     * True while someone else than CameraPadding owns the offset of the interactive cameras.
+     *
+     * @internal
+     */
+    get isCameraOffsetHeld(): boolean;
+    /**
+     * Takes the offset of the interactive cameras over from CameraPadding, which stops writing it until
+     * every hold is released, so the holder can move the view without a refit (see
+     * `glideCameraOffset`). Releasing wakes the frameloop, so CameraPadding glides on from wherever the
+     * holder left the offset. The returned release does nothing when called again.
+     *
+     * @internal
+     */
+    readonly holdCameraOffset: () => (() => void);
+    /**
+     * Offsets both interactive cameras by `padding` against the measured canvas viewport. Nothing
+     * happens while no canvas has been measured: there is no viewport to offset against.
+     *
+     * @internal
+     */
+    readonly applyCameraOffset: (padding: CanvasPadding) => void;
+    /**
+     * Moves the offset of the interactive cameras from the applied padding to `to` in a fixed time, a
+     * frame at a time, and resolves once it is there. The offset is a function of the elapsed time, so
+     * a slow device shows fewer frames but takes no longer. With reduced motion it is set at once.
+     * Meant for the holder of `holdCameraOffset`; CameraPadding would otherwise overwrite every step.
+     *
+     * @internal
+     */
+    readonly glideCameraOffset: (to: CanvasPadding) => Promise<void>;
+    /** Wakes the demand frameloop of the mounted canvas, so an offset written outside a frame is drawn. */
+    private readonly _invalidate;
     initialize: () => void;
 }
 export {};

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

@@ -1 +1 @@
-import t from"promise-queue";import{BehaviorSubject as e,Subject as r,debounceTime as a,map as i,of as o,shareReplay as s,startWith as n,switchMap as h}from"rxjs";import{OrthographicCamera as l,PerspectiveCamera as p}from"three";import{match as c}from"ts-pattern";import{DEFAULT_DIMENSION_UNIT as C,distanceUnitToDefault as m}from"#package/domain";import{createCameraControls as g}from"./create-camera-controls.js";export const CameraControlType={Perspective:"perspective",Orthographic:"orthographic"};let d=t=>Number.isFinite(t.width)&&Number.isFinite(t.height)&&t.width>0&&t.height>0;export class CameraControlSystem{_context;perspectiveCamera=Object.assign(new p,{manual:!0});orthographicCamera=Object.assign(new l,{manual:!0});perspectiveCameraControls=g(this.perspectiveCamera);orthographicCameraControls=g(this.orthographicCamera);_transitionState$=new e("still");_rendered$=new r;_transitionQueue=new t(1,1/0);_activeCameraControls$=new e(void 0);activeCameraControls$=this._activeCameraControls$;_canvasPadding$=new e({top:0,right:0,bottom:0,left:0});canvasPadding$=this._canvasPadding$;_generation=null;_pendingAbortController=void 0;_lastTransition=void 0;_cameraControlState$=new e("idle");cameraControlState$=this._cameraControlState$;transitionState$=this._transitionState$.pipe(h(t=>"sleep"===t?this._rendered$.pipe(a(200),i(()=>"still"),n("sleep")):o(t)),s(1));constructor(t){this._context=t,this.perspectiveCamera.fov=50,this.perspectiveCamera.near=m(500,C),this.perspectiveCamera.far=m(4e4,C),this.perspectiveCamera.position.set(0,1,0),this.orthographicCamera.left=m(-500,C),this.orthographicCamera.bottom=m(-500,C),this.orthographicCamera.right=m(500,C),this.orthographicCamera.top=m(500,C),this.orthographicCamera.far=m(4e4,C),this.orthographicCamera.near=m(500,C),this.orthographicCamera.position.set(0,1,0),this._context.configuratorExtensionSelectors.getCanvasSystem().interactiveViewport$.subscribe(t=>{null!==t&&this.handleCanvasResize(t)})}_seedCameraControls=()=>{this.perspectiveCameraControls.enabled=!0,this.orthographicCameraControls.enabled=!0,this.perspectiveCameraControls.rotateTo(0,1.2,!1),this.orthographicCameraControls.rotateTo(0,1.2,!1),this.orthographicCameraControls.dollyTo(m(1e4,C),!1)};resetCamera=()=>{this._lastTransition&&this.scheduleCameraTransition(this._lastTransition,{bypassViewLocks:!0})};setTransitionState=t=>{this._transitionState$.next(t)};reportRender=()=>{this._rendered$.next()};scheduleCameraTransition(t,e={}){this._pendingAbortController?.abort();let r=new AbortController;this._pendingAbortController=r;let a=this._generation;return{finished:this._transitionQueue.add(async()=>{let i=r.signal;if(i.aborted||!a?.active)return;let o=c(t.cameraType).with(CameraControlType.Perspective,()=>this.perspectiveCameraControls).with(CameraControlType.Orthographic,()=>this.orthographicCameraControls).exhaustive(),s=null==this._activeCameraControls$.value,n=this._activeCameraControls$.value!==o;n&&this._activeCameraControls$.next(o),this._lastTransition=t,await t.run({controls:o,camera:o.camera,abortSignal:i,firstLoad:s,typeChanged:n,bypassViewLocks:!0===e.bypassViewLocks})}),abort:()=>{r.abort()}}}setCameraControlState=t=>{this._cameraControlState$.next(t)};handleCanvasResize=t=>{if(!d(t))return;let e=t.width/t.height;this.perspectiveCamera.aspect=e,this.perspectiveCamera.updateProjectionMatrix();let r=this.orthographicCamera,a=(r.left+r.right)/2,i=(r.top-r.bottom)/2*e;r.left=a-i,r.right=a+i,r.updateProjectionMatrix()};setCanvasPadding=t=>{let e=this._canvasPadding$.value;(e.top!==t.top||e.right!==t.right||e.bottom!==t.bottom||e.left!==t.left)&&this._canvasPadding$.next(t)};enable=()=>{this.perspectiveCameraControls.enabled=!0,this.orthographicCameraControls.enabled=!0};disable=()=>{this.perspectiveCameraControls.enabled=!1,this.orthographicCameraControls.enabled=!1};fitRootCamera=()=>{let t=this._context.configuratorExtensionSelectors.getCanvasSystem().ready$.value?.scene;t&&this.perspectiveCameraControls.fitToSphere(t,!1)};fitEntity=t=>{let e=this._context.configuratorExtensionSelectors.getCanvasSystem().ready$.value?.scene;if(!e)return;let r=e.getObjectByName(t.toString());null!=r&&this.perspectiveCameraControls.fitToBox(r,!1)};setCameraOffset=t=>{let{padding:e,viewPort:r,camera:a}=t;if(!d(r))return;if(![e.top,e.right,e.bottom,e.left].every(Number.isFinite)||e.left+e.right>=r.width||e.top+e.bottom>=r.height)return void a.clearViewOffset();let i=(e.right-e.left)/2,o=(e.bottom-e.top)/2;a.setViewOffset(r.width,r.height,i,o,r.width,r.height)};initialize=()=>{null!==this._generation&&(this._generation.active=!1),this._pendingAbortController?.abort(),this._pendingAbortController=void 0,this._lastTransition=void 0,this._transitionState$.next("still"),this._cameraControlState$.next("idle"),this._activeCameraControls$.next(void 0),this._generation={active:!0},this._seedCameraControls()}}
+import t from"promise-queue";import{BehaviorSubject as e,Subject as a,debounceTime as r,map as i,of as o,shareReplay as s,startWith as n,switchMap as h}from"rxjs";import{OrthographicCamera as l,PerspectiveCamera as m}from"three";import{match as p}from"ts-pattern";import{DEFAULT_DIMENSION_UNIT as c,distanceUnitToDefault as C}from"#package/domain";import{createCameraControls as d}from"./create-camera-controls.js";export const CameraControlType={Perspective:"perspective",Orthographic:"orthographic"};let f=Object.freeze({top:0,right:0,bottom:0,left:0}),g=t=>Number.isFinite(t.width)&&Number.isFinite(t.height)&&t.width>0&&t.height>0;export class CameraControlSystem{_context;perspectiveCamera=Object.assign(new m,{manual:!0});orthographicCamera=Object.assign(new l,{manual:!0});perspectiveCameraControls=d(this.perspectiveCamera);orthographicCameraControls=d(this.orthographicCamera);_transitionState$=new e("still");_rendered$=new a;_transitionQueue=new t(1,1/0);_activeCameraControls$=new e(void 0);activeCameraControls$=this._activeCameraControls$;_canvasPadding$=new e({top:0,right:0,bottom:0,left:0});canvasPadding$=this._canvasPadding$;_appliedCameraOffset=f;_cameraOffsetHolds=0;_generation=null;_pendingAbortController=void 0;_lastTransition=void 0;_cameraControlState$=new e("idle");cameraControlState$=this._cameraControlState$;transitionState$=this._transitionState$.pipe(h(t=>"sleep"===t?this._rendered$.pipe(r(200),i(()=>"still"),n("sleep")):o(t)),s(1));constructor(t){this._context=t,this.perspectiveCamera.fov=50,this.perspectiveCamera.near=C(500,c),this.perspectiveCamera.far=C(4e4,c),this.perspectiveCamera.position.set(0,1,0),this.orthographicCamera.left=C(-500,c),this.orthographicCamera.bottom=C(-500,c),this.orthographicCamera.right=C(500,c),this.orthographicCamera.top=C(500,c),this.orthographicCamera.far=C(4e4,c),this.orthographicCamera.near=C(500,c),this.orthographicCamera.position.set(0,1,0),this._context.configuratorExtensionSelectors.getCanvasSystem().interactiveViewport$.subscribe(t=>{null!==t&&this.handleCanvasResize(t)})}_seedCameraControls=()=>{this.perspectiveCameraControls.enabled=!0,this.orthographicCameraControls.enabled=!0,this.perspectiveCameraControls.rotateTo(0,1.2,!1),this.orthographicCameraControls.rotateTo(0,1.2,!1),this.orthographicCameraControls.dollyTo(C(1e4,c),!1)};resetCamera=()=>{this._lastTransition&&this.scheduleCameraTransition(this._lastTransition,{bypassViewLocks:!0})};setTransitionState=t=>{this._transitionState$.next(t)};reportRender=()=>{this._rendered$.next()};scheduleCameraTransition(t,e={}){this._pendingAbortController?.abort();let a=new AbortController;this._pendingAbortController=a;let r=this._generation;return{finished:this._transitionQueue.add(async()=>{let i=a.signal;if(i.aborted||!r?.active)return;let o=p(t.cameraType).with(CameraControlType.Perspective,()=>this.perspectiveCameraControls).with(CameraControlType.Orthographic,()=>this.orthographicCameraControls).exhaustive(),s=null==this._activeCameraControls$.value,n=this._activeCameraControls$.value!==o;n&&this._activeCameraControls$.next(o),this._lastTransition=t,await t.run({controls:o,camera:o.camera,abortSignal:i,firstLoad:s,typeChanged:n,bypassViewLocks:!0===e.bypassViewLocks})}),abort:()=>{a.abort()}}}setCameraControlState=t=>{this._cameraControlState$.next(t)};handleCanvasResize=t=>{if(!g(t))return;let e=t.width/t.height;this.perspectiveCamera.aspect=e,this.perspectiveCamera.updateProjectionMatrix();let a=this.orthographicCamera,r=(a.left+a.right)/2,i=(a.top-a.bottom)/2*e;a.left=r-i,a.right=r+i,a.updateProjectionMatrix()};setCanvasPadding=t=>{let e=this._canvasPadding$.value;(e.top!==t.top||e.right!==t.right||e.bottom!==t.bottom||e.left!==t.left)&&this._canvasPadding$.next(t)};enable=()=>{this.perspectiveCameraControls.enabled=!0,this.orthographicCameraControls.enabled=!0};disable=()=>{this.perspectiveCameraControls.enabled=!1,this.orthographicCameraControls.enabled=!1};fitRootCamera=()=>{let t=this._context.configuratorExtensionSelectors.getCanvasSystem().ready$.value?.scene;t&&this.perspectiveCameraControls.fitToSphere(t,!1)};fitEntity=t=>{let e=this._context.configuratorExtensionSelectors.getCanvasSystem().ready$.value?.scene;if(!e)return;let a=e.getObjectByName(t.toString());null!=a&&this.perspectiveCameraControls.fitToBox(a,!1)};setCameraOffset=t=>{let{padding:e,viewPort:a,camera:r}=t;if(!g(a))return;if(![e.top,e.right,e.bottom,e.left].every(Number.isFinite)||e.left+e.right>=a.width||e.top+e.bottom>=a.height)return void r.clearViewOffset();let i=(e.right-e.left)/2,o=(e.bottom-e.top)/2;r.setViewOffset(a.width,a.height,i,o,a.width,a.height)};get appliedCameraOffset(){return this._appliedCameraOffset}get isCameraOffsetHeld(){return this._cameraOffsetHolds>0}holdCameraOffset=()=>{this._cameraOffsetHolds+=1;let t=!1;return()=>{t||(t=!0,this._cameraOffsetHolds-=1,this._invalidate())}};applyCameraOffset=t=>{let e=this._context.configuratorExtensionSelectors.getCanvasSystem().interactiveViewport$.value;null!==e&&(this.setCameraOffset({padding:t,viewPort:e,camera:this.perspectiveCamera}),this.setCameraOffset({padding:t,viewPort:e,camera:this.orthographicCamera}),this._appliedCameraOffset=t)};glideCameraOffset=async t=>{let e=this._appliedCameraOffset;if(globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches===!0){this.applyCameraOffset(t),this._invalidate();return}let a=performance.now();await new Promise(r=>{let i=o=>{let s,n=Math.min(1,Math.max(0,(o-a)/300));this.applyCameraOffset((s=n<.5?4*n*n*n:1-(-2*n+2)**3/2,{top:e.top+(t.top-e.top)*s,right:e.right+(t.right-e.right)*s,bottom:e.bottom+(t.bottom-e.bottom)*s,left:e.left+(t.left-e.left)*s})),this._invalidate(),n<1?requestAnimationFrame(i):r()};requestAnimationFrame(i)})};_invalidate=()=>{this._context.configuratorExtensionSelectors.getCanvasSystem().r3fHandle$.value?.get().invalidate()};initialize=()=>{null!==this._generation&&(this._generation.active=!1),this._pendingAbortController?.abort(),this._pendingAbortController=void 0,this._lastTransition=void 0,this._transitionState$.next("still"),this._cameraControlState$.next("idle"),this._activeCameraControls$.next(void 0),this._generation={active:!0},this._seedCameraControls()}}

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

@@ -48,7 +48,9 @@ export declare class ExportSystem<ENTITIES extends DomainEntity<string>, ALLOWED
     private _frameloopPause;
     private _queue;
     private readonly _exporting;
-    /** True while an export run is queued or running; the configurator UI is inert meanwhile. */
+    /** Releases the layout's inert hold, taken while anything is exporting; nothing otherwise. */
+    private _releaseInert;
+    /** True while an export run is queued or running; the layout system holds the configurator inert meanwhile. */
     readonly exporting$: ObservableWithLastValue<boolean>;
     constructor(_context: ExportSystemContext);
     /**
@@ -79,4 +81,5 @@ export declare class ExportSystem<ENTITIES extends DomainEntity<string>, ALLOWED
     private readonly _awaitSettledState;
     private readonly _runExportJobs;
     initialize: () => void;
+    private _stopExporting;
 }

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

@@ -1 +1 @@
-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)}}
+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);_releaseInert=null;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)),n=i.catch(()=>void 0);return this._queue=n,this._exporting.value||(this._releaseInert=this._context.configuratorExtensionSelectors.getLayoutSystem().makeInert(),this._exporting.next(!0)),n.then(()=>{this._queue===n&&(this._queue=null,this._stopExporting())}),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 n=()=>{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.")};n(),o&&await this._awaitSettledState(n);let a=this._context.configuratorExtensionSelectors.getCanvasSystem(),r=a.r3fHandle$.value??await a.waitForCanvas().catch(t=>{throw n(),t});n();let s=this.pauseFrameloop(r);try{let o=[];for(let i of t){n();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(),n(),!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 a=t.state,s=this._context.domainContextSelectors.getDomain().get$Entity(i.exportedEntityId,a),l=this._context.domainContextSelectors.getDomain().getRoot$Entity(a),c=await i.execute({$entity:s,$root:l,state:a,scene:r.get().scene});n(),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._stopExporting()};_stopExporting=()=>{this._releaseInert?.(),this._releaseInert=null,this._exporting.next(!1)}}

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. */
@@ -27,76 +28,89 @@ export interface EntityMetaContext {
     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 {
-    readonly type: string;
-    readonly entityId: EntityId<DomainEntity<string>> | null;
-    readonly message: 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;
- * `screenshot` renders the entity there.
+ * 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 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)}};
+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,6 +1,7 @@
 import { type ExecutionResult } from 'graphql';
 import { type Localizable } from '@salsita-ai/common/utils';
-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 $DomainEntity, type AgentScreenshotComponent, type ComponentSnapshot, type DomainContextSelectors, type DomainEntity, type DomainServicesSelectors, type DomainState, type InitializationGeneration, type SessionAssistantSetup, 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;
@@ -11,20 +12,25 @@ export interface GraphQLOperation {
 export interface GraphQLScreenshot {
     readonly entityId: string;
     readonly view: string;
-    /** The picture as base64 data. */
-    readonly data: string;
-    readonly mimeType: 'image/jpeg' | 'image/png';
+    /** 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; `null` from an executor that renders no pictures. The only async step of an
-     * execution, and the only one that needs a canvas.
+     * 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>;
-    readonly specSelectors: SpecSelectors;
+    /**
+     * 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 domainContextSelectors: DomainContextSelectors;
     readonly domainServicesSelectors: DomainServicesSelectors;
 }
@@ -55,6 +61,12 @@ 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
@@ -69,6 +81,13 @@ export interface GraphQLExecution {
  * `null` and values that are not localizable pass through, so the schema's nullability decides.
  */
 export declare const localize: (value: unknown, resolveLocalizable: (message: Localizable) => string) => unknown;
+/**
+ * The code of the error a screenshot that was not taken fails its own field with. Such an error is
+ * no failure of its operation: the screenshot is only a look at the configuration, so it neither
+ * stops the operations after it nor keeps `apply` from committing, and the assistant panel shows a
+ * query that failed only on it as done.
+ */
+export declare const SCREENSHOT_NOT_TAKEN = "SCREENSHOT_NOT_TAKEN";
 /**
  * Executes GraphQL operations against the schema generated from the application spec `assistant`
  * manifest, resolving it against the committed domain state. Agent-independent: the assistant's
@@ -91,13 +110,15 @@ 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 base64 of the view's
+     * 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;
@@ -118,9 +139,9 @@ export declare class GraphQLSystem {
     private readonly _runMutation;
     /**
      * Takes a screenshot once every one asked for before it in the execution has been taken, so they
-     * render and spend the budget in document order. A failure nulls only its own field and fails
-     * nothing else: the user kept changing the configuration, the image did not fit the budget, or
-     * rendering failed. Once the budget is spent, no later screenshot renders.
+     * 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;
@@ -145,6 +166,12 @@ export declare class GraphQLSystem {
     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,