@salsita-ai/sdk 0.50.0-develop.bc08a38ffe → 0.50.0-develop.bc204720a8

package/dist/docs/selection-and-highlight/hierarchy.mdx

@@ -13,69 +13,81 @@ of transformers that will nail down the desired selection behavior and component
 The crucial things for this usecase are:
 
 - `createSelectParentOnDeselectionTransformer` is used to achieve selecting of the parent based on deselection
-- `createNavigationOnSelectionChangeTransformer` to navigate to entry states when entity is selected
-- `createResetSelectionOnNavigationTransformer` is used to disable selections in tabs where it should not apply
+- `when.entity([...]).selected({ insteadOf: [...] }).then.navigateTo(...)` to navigate to entry states when entity is selected
+- `when.navigated({ to: [...] }).then.deselect()` is used to disable selections in tabs where it should not apply
 - `.withGradualFilter` is used to show hotspots when their parent is selected
 
 Note: This is very complex use case, it is recommended to dive deeper into the codebase. This document covers just the basics.
 
 ## Code
 
-Register the selection fallback transformer (transformers start from 101 to run after the system transformers)
+Each transformer is the default export of a file in `src/transformers/`. The `transformers` section of the spec turns it on by the name passed to `build(...)`, or by the file name for a plain function such as `select-parent`. Without a `priority`, they run after the built-in transformers in the listed order (see [Transformers](?path=/docs/other-features-transformers--docs#transformer-pipeline)):
 
-```ts
-{
-    priority: 101,
-    transformer: createSelectParentOnDeselectionTransformer(ctx),
-}
+```yaml
+transformers:
+  - name: select-parent
+  - name: select-parent-from-monitor
+  - name: navigate-from-room
+  - name: navigate-from-console-group
+  - name: navigate-from-console-to-room
+  - name: navigate-from-console-to-group
+  - name: navigate-from-group-to-room
+  - name: reset-selection
 ```
 
-Configure the navigation details using
+Register the selection fallback transformer
 
 ```ts
-{
-    priority: 102,
-    transformer: transformer: createNavigationOnSelectionChangeTransformer(
-          'Room',
-          'Console',
-          NavigationStateTag.ConsoleShape,
-          ctx
-        ),
-}
+// src/transformers/select-parent.ts
+import { createSelectParentOnDeselectionTransformer } from '@salsita-ai/sdk/domain'
+
+export default createSelectParentOnDeselectionTransformer
 ```
 
-Setup states when selection is rest on navigation changes
+Configure the navigation details, one transformer per selection change, e.g. from the room to a console
 
 ```ts
-{
-    priority: 103,
-    transformer: createResetSelectionOnNavigationTransformer([NavigationStateTag.Colors, NavigationStateTag.RoomLayout], ctx),
-},
+// src/transformers/navigate-from-room.ts
+export default phx.frontend.transformerBuilder.when
+  .entity(['Console'])
+  .selected({ insteadOf: ['Room'] })
+  .then.navigateTo(phx.applicationTypes.NavigationState.ConsoleShape)
+  .build('navigate-from-room')
+```
 
+Setup states when selection is reset on navigation changes
+
+```ts
+// src/transformers/reset-selection.ts
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.Colors, phx.applicationTypes.NavigationState.RoomLayout],
+  })
+  .then.deselect()
+  .build('reset-selection')
 ```
 
 Register the selection controls to be shown only if parent is selected
 
 ```tsx
- attachComponent
-        .withComponent(htmlHotspotComponent, 'main')
-        .withEntity('Monitor')
-        .withGradualFilter({
-          navigationStates: [NavigationStateTag.ConsoleMonitors],
-          selectedEntityIds: s => [s.$parent.id],
-        })
-        .attach(
-          memoEval(
-            s => [s.id],
-            id => ({
-              offsetX: 0,
-              offsetY: 500,
-              offsetZ: 1500,
-              unit: 'mm',
-              node: <SelectionHotspot id={id} />,
-            })
-          )
-        ),
+phx.domain.attachComponent
+  .withComponent(htmlHotspotComponent, 'main')
+  .withEntity('Monitor')
+  .withGradualFilter({
+    navigationStates: [phx.applicationTypes.NavigationState.ConsoleMonitors],
+    selectedEntityIds: s => [s.$parent.id, ...s.$parent.$monitors.map(m => m.id).filter(m => m !== s.id)],
+  })
+  .attach(
+    memoEval(
+      s => [s.id],
+      id => ({
+        offsetX: 0,
+        offsetY: 300,
+        offsetZ: 500,
+        node: <SelectionHotspot id={id} />,
+      })
+    )
+  )
 ```
 
 ## Example
@@ -328,7 +340,6 @@ import { entityHeaderComponent, htmlHotspotComponent, memoEval, sidebarTabsCompo
 
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
 import { getMonitorRenderingComponents } from '../../../../common/monitor-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [
   ...getConsoleRenderingComponents('Console', phx.domain.attachComponent),
@@ -480,8 +491,6 @@ export default [
 ### ./src/expressions/expressions.ts
 
 ```ts
-import { phx } from '../../.phoenix/phx.js'
-
 export default phx.domain.implementCustomExpressions({
   ConsoleGroup: {
     $center: s => {
@@ -497,142 +506,82 @@ export default phx.domain.implementCustomExpressions({
 ### ./src/transformers/navigate-from-console-group.ts
 
 ```ts
-import { createNavigationOnSelectionChangeTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return createNavigationOnSelectionChangeTransformer(
-    'ConsoleGroup',
-    'Console',
-    phx.applicationTypes.NavigationState.ConsoleShape,
-    ctx
-  )
-})
+export default phx.frontend.transformerBuilder.when
+  .entity(['Console'])
+  .selected({ insteadOf: ['ConsoleGroup'] })
+  .then.navigateTo(phx.applicationTypes.NavigationState.ConsoleShape)
+  .build('navigate-from-console-group')
 ```
 
 ### ./src/transformers/navigate-from-console-to-group.ts
 
 ```ts
-import { createNavigationOnSelectionChangeTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return createNavigationOnSelectionChangeTransformer(
-    'Console',
-    'ConsoleGroup',
-    phx.applicationTypes.NavigationState.Console,
-    ctx
-  )
-})
+export default phx.frontend.transformerBuilder.when
+  .entity(['ConsoleGroup'])
+  .selected({ insteadOf: ['Console'] })
+  .then.navigateTo(phx.applicationTypes.NavigationState.Console)
+  .build('navigate-from-console-to-group')
 ```
 
 ### ./src/transformers/navigate-from-console-to-room.ts
 
 ```ts
-import { createNavigationOnSelectionChangeTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return createNavigationOnSelectionChangeTransformer(
-    'Console',
-    'Room',
-    phx.applicationTypes.NavigationState.Console,
-    ctx
-  )
-})
+export default phx.frontend.transformerBuilder.when
+  .entity(['Room'])
+  .selected({ insteadOf: ['Console'] })
+  .then.navigateTo(phx.applicationTypes.NavigationState.Console)
+  .build('navigate-from-console-to-room')
 ```
 
 ### ./src/transformers/navigate-from-group-to-room.ts
 
 ```ts
-import { createNavigationOnSelectionChangeTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return createNavigationOnSelectionChangeTransformer(
-    'ConsoleGroup',
-    'Room',
-    phx.applicationTypes.NavigationState.Console,
-    ctx
-  )
-})
+export default phx.frontend.transformerBuilder.when
+  .entity(['Room'])
+  .selected({ insteadOf: ['ConsoleGroup'] })
+  .then.navigateTo(phx.applicationTypes.NavigationState.Console)
+  .build('navigate-from-group-to-room')
 ```
 
 ### ./src/transformers/navigate-from-room.ts
 
 ```ts
-import { createNavigationOnSelectionChangeTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return createNavigationOnSelectionChangeTransformer(
-    'Room',
-    'Console',
-    phx.applicationTypes.NavigationState.ConsoleShape,
-    ctx
-  )
-})
+export default phx.frontend.transformerBuilder.when
+  .entity(['Console'])
+  .selected({ insteadOf: ['Room'] })
+  .then.navigateTo(phx.applicationTypes.NavigationState.ConsoleShape)
+  .build('navigate-from-room')
 ```
 
 ### ./src/transformers/reset-selection.ts
 
 ```ts
-import { createResetSelectionOnNavigationTransformer } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return createResetSelectionOnNavigationTransformer(
-    [phx.applicationTypes.NavigationState.Colors, phx.applicationTypes.NavigationState.RoomLayout],
-    ctx
-  )
-})
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.Colors, phx.applicationTypes.NavigationState.RoomLayout],
+  })
+  .then.deselect()
+  .build('reset-selection')
 ```
 
 ### ./src/transformers/select-parent-from-monitor.ts
 
 ```ts
-import { isNavigationUpdate } from '@salsita-ai/sdk/domain'
-
-import { phx } from '../../.phoenix/phx.js'
-
-export default phx.frontend.createTransformer(ctx => {
-  return (updates, state) => {
-    return updates.flatMap(update => {
-      if (!isNavigationUpdate(update)) {
-        return [update]
-      }
-
-      if (
-        (
-          [
-            phx.applicationTypes.NavigationState.ConsoleAccessories,
-            phx.applicationTypes.NavigationState.ConsoleShape,
-          ] as string[]
-        ).includes(update.writableState.activeState)
-      ) {
-        const selectedEntity = ctx.navigationSystem.getActiveSelectionState(state)
-
-        if (phx.domain.model.Monitor.isId(selectedEntity)) {
-          const parent = ctx.compositionProjections.getTree(state).map.get(selectedEntity)?.parent
-
-          if (parent) {
-            return [update, ctx.navigationSystem.getSelectUpdate(parent.id)]
-          }
-        }
-
-        return [update]
-      }
-
-      return [update]
-    })
-  }
-})
+export default phx.frontend.transformerBuilder.when
+  .navigated({
+    to: [phx.applicationTypes.NavigationState.ConsoleAccessories, phx.applicationTypes.NavigationState.ConsoleShape],
+  })
+  .then.select.entity(ctx => {
+    const oldState = ctx.getOldState()
+    const selectedEntity = ctx.domainContext.navigationSystem.getActiveSelectionState(oldState)
+
+    if (!phx.domain.model.Monitor.isId(selectedEntity)) {
+      return undefined
+    }
+
+    return ctx.domainContext.compositionProjections.getTree(oldState).map.get(selectedEntity)?.parent?.id
+  })
+  .build('select-parent-from-monitor')
 ```
 
 ### ./src/transformers/select-parent.ts

package/dist/docs/selection-and-highlight/hotspots.mdx

@@ -56,6 +56,8 @@ sceneEntitySelectHotspot:
 
 The `title` supplies the tooltip text. Tooltips appear on hover by default; `tooltipVisibility` can instead keep them visible continuously, while the camera is still, or hide them. The `showWhen` property controls visibility based on selection state. The default `['unselected']` hides hotspots once entities are selected, keeping the view clean. Setting it to `['selected', 'unselected']` keeps hotspots always visible.
 
+The hotspot is the entity element `SelectionHotspot`. A project replaces its look by registering its own with `phx.frontend.createSelectionHotspot`, which receives `onSelect`, the selection with its analytics event; the settings above still apply. See [Configurator Interface → In-Scene Controls](?path=/docs/phoenix-configurator-interface--docs#in-scene-controls).
+
 ## System Component Interfaces
 
 ```typescript
@@ -277,7 +279,6 @@ components:
 
 ```tsx
 import { getConsoleRenderingComponents } from '../../../../common/console-rendering.js'
-import { phx } from '../../.phoenix/phx.js'
 
 export default [...getConsoleRenderingComponents('ConsoleUnit', phx.domain.attachComponent)]
 ```

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

@@ -1,5 +1,5 @@
 import type { ConfiguratorBuilder } from '../application/configurator-builder.js';
-import { type $DomainEntity, DomainComponentOpticBuilder, type DomainEntity } from '../core/index.js';
+import { type $DomainEntity, type ActionTypes, DomainComponentOpticBuilder, type DomainEntity } from '../core/index.js';
 import type { FinalizeData, FinalizeResult, FrontendData, NavigationState, PublishedData, SessionData, ViewState } from './__generated/application-types.js';
 import type { $Map } from './__generated/enhanced-model.js';
 import type { Aliases, CommonAdminEntity, RootEntity } from './__generated/model/index.js';
@@ -28,5 +28,5 @@ export declare const commonAdminComponents: import("../index.js").DomainComponen
  * work at runtime anyway. The null cast is the whole point — it makes "this value has no runtime
  * behavior" explicit instead of building dead machinery to carry the same types.
  */
-export declare const configuratorBuilder: ConfiguratorBuilder<DomainEntity<string>, DomainEntity<string>, Record<string, $DomainEntity<DomainEntity<string>>>, never, never, never, never, PublishedData, SessionData, FrontendData, AnyDomainEntity, RootEntity, $Map, NavigationState, ViewState, FinalizeData, FinalizeResult, SessionData>;
+export declare const configuratorBuilder: ConfiguratorBuilder<DomainEntity<string>, DomainEntity<string>, Record<string, $DomainEntity<DomainEntity<string>>>, never, never, never, never, PublishedData, SessionData, FrontendData, ActionTypes, AnyDomainEntity, RootEntity, $Map, NavigationState, ViewState, FinalizeData, FinalizeResult, SessionData>;
 export type CommondAdminEntities = Omit<CommonAdminEntity['type'], 'Admin' | 'DummyDoNotUse'>;

package/dist/domain/application/GetApplicationWrapperHandler.d.ts

@@ -1,6 +1,6 @@
 import type { ComponentType } from 'react';
 import type { $DomainEntity, DomainEntity } from '../core/index.js';
-import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../spec/index.js';
 import type { ApplicationConfig } from './application-config.js';
 export declare const createGetApplicationWrapperHandler: (fn: (ctx: ApplicationConfig<any, any, any, any, any, any, never, any, any, any, any, any, any, any, any, any>) => ComponentType) => SystemPhoenixHandlerRegistration<ApplicationConfig<any, any, any, any, any, any, never, any, any, any, any, any, any, any, any, any>, ComponentType>;
 export type CreateGetApplicationWrapperHandler = typeof createGetApplicationWrapperHandler;

package/dist/domain/application/GetThemeHandler.d.ts

@@ -1,5 +1,5 @@
 import type { ThemeOptions } from '@mui/material';
-import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../spec/index.js';
 export declare const GetThemeHandlerName = "GetThemeHandler";
 export declare const createGetThemeHandler: (fn: () => ThemeOptions) => SystemPhoenixHandlerRegistration<void, ThemeOptions>;
 export type CreateGetThemeHandler = (fn: () => ThemeOptions) => SystemPhoenixHandlerRegistration<void, ThemeOptions>;

package/dist/domain/application/GetWebComponentOptions.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../domain-runtime/index.js';
+import type { HandlerRegistration, SystemPhoenixHandlerRegistration } from '../spec/index.js';
 import type { WebComponentOptions } from './application-config.js';
 export declare const createGetWebComponentOptionsHandler: (fn: () => WebComponentOptions) => SystemPhoenixHandlerRegistration<undefined, WebComponentOptions>;
 export type CreateGetWebComponentOptionsHandler = (fn: () => WebComponentOptions) => SystemPhoenixHandlerRegistration<undefined, WebComponentOptions>;

package/dist/domain/application/application-config.d.ts

@@ -8,8 +8,7 @@ import type { CellValue } from '@salsita-ai/contracts/webhook';
 import type { AdminIntegrationService } from '#package/react-sdk';
 import type { $DomainEntity, DataCellValue, DataSchema, DomainEntity, DomainFactory, ProductPreset } from '../core/index.js';
 import type { AnalyticsSystem, RegistrableTransformer, TransformerFactory } from '../domain-context/index.js';
-import type { ProjectModule } from '../domain-runtime/index.js';
-import type { AssistantResolvedManifest } from './assistant/index.js';
+import type { AdminPagesSection, AssistantResolvedManifest, ElementRegistration, ProjectModule } from '../spec/index.js';
 import type { WebComponentEventDescriptor } from './web-component-event.js';
 import type { WebComponentPropertyDescriptor } from './web-component-property.js';
 type TransformerExport = ReturnType<TransformerFactory<any, any, any, any, any, any, any>> | RegistrableTransformer<any, any, any, any, any, any, any>;
@@ -55,30 +54,11 @@ export type DataSpec = {
 export type ChunksSpec = Readonly<Record<string, {
     readonly scope: string;
 }>>;
-export type AdminPagesSpec = {
-    readonly presets?: boolean | {
-        readonly categoryNavigationState?: string;
-        readonly presetNavigationState?: string;
-    };
-    readonly recipes?: ReadonlyArray<{
-        readonly name: string;
-        readonly navigationState?: string;
-    }>;
-    readonly pages?: ReadonlyArray<{
-        readonly key: string;
-        readonly title: string;
-        readonly icon?: string;
-        readonly navigationState?: string;
-        readonly entity?: string;
-        readonly component?: string;
-        readonly actionsComponent?: string;
-        readonly connectedDataEntry?: string;
-        readonly sidebar?: {
-            readonly title: string;
-            readonly component: string;
-        };
-    }>;
-};
+/**
+ * The admin pages of an application config: the `$adminPages` section of the application spec as
+ * written, which `createAdminPagesFromSpec` turns into admin pages; see {@link AdminPagesSection}.
+ */
+export type AdminPagesSpec = AdminPagesSection;
 type PersistenceConfig = {
     readonly type: 'server';
     /**
@@ -292,6 +272,8 @@ export interface ApplicationConfig<ENTITIES extends DomainEntity<string>, ALLOWE
     /** The `src/handlers/` and `src/elements/` files as project modules; the runtime spec validates and flattens both. */
     readonly handlers: readonly ProjectModule[];
     readonly elements: readonly ProjectModule[];
+    /** The SDK's default element registrations; a project element with the same name replaces one. */
+    readonly defaultElements?: readonly ElementRegistration[];
     readonly mount: MountConfig<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, CHAT_CONTEXT, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ADMIN_ENTITIES, ADMIN_ALLOWED_ROOT_ENTITIES, ADMIN_$MAP, ADMIN_NAVIGATION_STATES, ADMIN_VIEW_STATES>;
 }
 export {};

package/dist/domain/application/assistant/assistant-fields.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantDeclaredField, AssistantResolvedField } from './assistant-resolved-manifest.js';
+import type { AssistantDeclaredField, AssistantResolvedField } from '../../spec/index.js';
 /** Combines the effective description with allowed string values. */
 export declare const describeAssistantValues: (description: string | undefined, values: readonly string[] | undefined) => string | undefined;
 /** Applies GraphQL field inheritance identically at parse time and after session narrowing. */

package/dist/domain/application/assistant/assistant-value-type.d.ts

@@ -1,5 +1,5 @@
 import { type GraphQLInputType, type GraphQLOutputType, GraphQLScalarType } from 'graphql';
-import type { AssistantValueType } from './assistant-resolved-manifest.js';
+import type { AssistantValueType } from '../../spec/index.js';
 /**
  * Opaque scalar for values the assistant schema does not type: objects, custom TypeScript types and
  * loose unions. A value is plain serializable data and passes through unchanged.

package/dist/domain/application/assistant/build-assistant-lenses.d.ts

@@ -1,6 +1,5 @@
 import { type GraphQLSchema } from 'graphql';
-import type { AssistantManifest } from './assistant-manifest.js';
-import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+import type { AssistantManifest, AssistantResolvedManifest } from '../../spec/index.js';
 /**
  * Generates the lens fragments of a resolved manifest for the execution schema compiled from it. A
  * declared lens becomes one fragment on `AnyDomainEntity`; one that session narrowing left without a

package/dist/domain/application/assistant/build-assistant-lenses.js

@@ -1,4 +1,4 @@
-import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
+import{NoUnusedFragmentsRule as e,parse as t,specifiedRules as i,validate as n}from"graphql";let s="AnyDomainEntity",r=[{name:"RecipeGroup",description:"A recipe group with its recipes, without their dry-runs.",selections:["groupId","name","description","recipes { ...Recipe }"]},{name:"Recipe",description:"A recipe without its dry-run.",selections:["key","name","description","imageUrl"]},{name:"FieldOption",description:"A value a field accepts, without its dry-run.",selections:["value","name","description","imageUrl","color"]},{name:"DryRun",description:"What a dry-run would do, with the ids of the entities it would change instead of the entities.",selections:["ok","deletedEntityIds","sideEffects","warnings","errors { type entityId message }","changedEntities { id }"]}],a=(e,t)=>0===t?e:`${e}__${t}`,l=e=>e.split("\n").map(e=>`# ${e}`.trimEnd()).join("\n"),o=(e,t,i)=>[`fragment ${e} on ${t} {`,...i.map(e=>`  ${e}`),"}"].join("\n"),p=(e,t,i)=>{let n=e=>"edge"===e.type.kind?`${e.name} { ${i} }`:e.name;return o(e,s,["id",...t.flatMap(({typeName:e,fields:t})=>e===s?t.map(n):[`... on ${e} {`,...t.map(e=>`  ${n(e)}`),"}"])])};export const buildAssistantLenses=(d,m)=>{let c=Object.entries(d.lenses).flatMap(([e,t])=>{let i=[s,...Object.keys(d.aliases).filter(e=>e!==s),...d.entityTypes].flatMap(t=>{let i=(d.fields[t]??[]).filter(t=>t.lenses?.includes(e));return i.length>0?[{typeName:t,fields:i}]:[]});return i.length>0?[{name:e,...t,conditions:i}]:[]}),$=r.filter(({name:e})=>void 0!==m.getType(e)),h=[...c.map(({name:e,description:t,maxDepth:i,conditions:n})=>{let s=n.some(({fields:e})=>e.some(e=>"edge"===e.type.kind));return`${l(s?`${t} ${`Nested relations carry the same selection up to ${i} ${1===i?"level":"levels"}, below that only \`id\`.`}`:t)}
 ${p(e,n,`...${e}`)}`}),...$.map(({name:e,description:t,selections:i})=>`${l(t)}
 ${o(e,e,i)}`)].join("\n\n"),u=[...c.flatMap(({name:e,maxDepth:t,conditions:i})=>Array.from({length:t+1},(n,s)=>p(a(e,s),i,s<t?`...${a(e,s+1)}`:"id"))),...$.map(({name:e,selections:t})=>o(e,e,t))].join("\n\n");if(""!==u){let s=c.length>0?`entities { ${c.map(({name:e})=>`...${e}`).join(" ")} }`:"__typename",r=n(m,t(`${u}
 

package/dist/domain/application/assistant/build-assistant-manifest.d.ts

@@ -1,4 +1,3 @@
-import type { AssistantManifest } from './assistant-manifest.js';
-import type { AssistantResolvedManifest } from './assistant-resolved-manifest.js';
+import type { AssistantManifest, AssistantResolvedManifest } from '../../spec/index.js';
 /** Constructs the schema and runtime sources exclusively from serializable resolved data. */
 export declare const buildAssistantManifest: (resolved: AssistantResolvedManifest) => Required<AssistantManifest>;

package/dist/domain/application/assistant/build-assistant-manifest.js

@@ -1 +1 @@
-import{GraphQLBoolean as e,GraphQLID as t,GraphQLInputObjectType as n,GraphQLInterfaceType as i,GraphQLList as r,GraphQLNonNull as s,GraphQLObjectType as o,GraphQLSchema as a,GraphQLString as p,printSchema as d,validateSchema as c}from"graphql";import{GraphQLJSON as l,createAssistantValueType as h}from"./assistant-value-type.js";import{buildAssistantLenses as y}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as w}from"./create-assistant-execution-schema.js";let u="AnyDomainEntity",m="RootEntity",f=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],g={section:"childRecipes",mutation:"addChild"},b={section:"replaceRecipes",mutation:"replaceEntity"},j=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],v=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},$=({target:e,cardinality:t},n)=>{let i=n(e);switch(t){case"1-1":return new s(i);case"0-1":return i;case"0-N":case"1-N":return new s(new r(new s(i)))}},O=(e,n,i)=>{let r={id:{type:new s(t),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new s(p),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let t of e)r[t.name]={type:"edge"===t.type.kind?$(t.type,n):h(t.type.type),description:t.description};return r},E=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),R={sameForAllInstances:e=>`Same recipe groups and recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},k={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},I=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),T=({section:e},{groups:t,hints:n},{entityType:i,purpose:o,recipeGroup:a})=>{let p=t.filter(({dryRuns:e})=>!e).map(({groupId:e})=>e);return 0===t.length?{}:{[e]:{type:new s(new r(new s(a))),description:`The recipe groups for ${o} this ${i}: ${t.map(({groupId:e})=>e).join(", ")}. A group is listed only while the configurator offers it on the entity.${p.length>0?` Recipes of these groups cannot be dry-run: ${p.join(", ")}.`:""}${I(n,R,i)}`}}},N=({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i},{recipeGroup:a,fieldOption:p})=>new o({name:`${e}Meta`,fields:Object.assign(T(g,t,{entityType:e,purpose:"adding children to",recipeGroup:a}),T(b,n,{entityType:e,purpose:"replacing",recipeGroup:a}),...i.map(({options:{edgeName:t,field:n,validate:i,dryRuns:o},hints:a})=>({[t]:{type:new r(new s(p)),description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${o?"":" Cannot be dry-run."}${I(a,k,e)}`}})))}),A=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=$=>{var R,k,I,T,S;let D,M,F,W,{entityTypes:x,aliases:C,exampleType:q,fields:G,states:U,deletableTypes:K,writableTypes:P,actionFields:V,optionsEdges:z}=$,Q=Object.fromEntries(Object.entries($.childRecipes).map(([e,t])=>[e,t.groups])),B=Object.fromEntries(Object.entries($.replaceRecipes).map(([e,t])=>[e,t.groups])),H=new Map,J=new Map,L=new Map,X=e=>{let[t,...n]=Object.entries(C).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?J.get(t):void 0)??L.get(e)??Z},Y=e=>J.get(e)??X(e),Z=new i({name:u,description:"Every entity of the configuration.",fields:()=>O(G[u]??[],Y,q)});for(let e of(L.set(u,Z),Object.keys(C)))e!==u&&L.set(e,new i({name:e,interfaces:[Z],fields:()=>O(G[e]??[],Y)}));let _={};for(let e of x){let t=[u,...Object.entries(C).filter(([t,n])=>t!==u&&n.includes(e)).map(([e])=>e)],n=G[e]??[];_[e]=E(n),J.set(e,new o({name:e,interfaces:t.flatMap(e=>L.get(e)??[]),fields:()=>{let t=H.get(e);return{...O(n,Y),...t?{meta:{type:new s(t),description:"What can be done to this entity right now."}}:{}}}}))}let ee=(R=()=>X(L.has(m)?m:u),k=()=>X(u),D=new o({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new s(p),description:"Kind of the problem."},entityId:{type:t,description:"The entity the problem is on, when it is on one."},message:{type:p,description:"The problem as the user would be told it."}}}),new o({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new s(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:R(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new s(new r(new s(k()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new s(new r(new s(t))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new s(new r(new s(p))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},errors:{type:new s(new r(new s(D))),description:"Why the change cannot be made; empty when ok is true."}})})),et={recipeGroup:(I=[...Object.keys(Q).length>0?[g.mutation]:[],...Object.keys(B).length>0?[b.mutation]:[]],M=I.join(" or "),F=new o({name:"Recipe",description:`${I.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${I.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new s(p),description:`Pass to ${M} as recipeKey. Valid only for the listing it came from.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Thumbnail shown to the user."},dryRun:{type:ee,description:"What using this recipe would do. Null when it cannot be tried."}}}),new o({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new s(p),description:`Pass to ${M} as recipeGroupId.`},name:{type:new s(p),description:"Name shown to the user."},description:{type:p},recipes:{type:new s(new r(new s(F)))}}})),fieldOption:new o({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new s(l),description:"The value to write to the field."},name:{type:p,description:"Name shown to the user."},description:{type:p},imageUrl:{type:p,description:"Image shown to the user."},color:{type:p,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:ee,description:"What writing this value would do. Null when it cannot be tried."}}})};for(let e of x){let t=j($.childRecipes,e)??{groups:[],hints:[]},n=j($.replaceRecipes,e)??{groups:[],hints:[]},i=j(z,e)??[];(t.groups.length>0||n.groups.length>0||i.length>0)&&H.set(e,N({entityType:e,childRecipes:t,replaceRecipes:n,optionsEdges:i.map(t=>({...t,hints:(C[m]??[]).includes(e)?t.hints.filter(e=>"sameForAllInstances"!==e):t.hints}))},et))}let en=new a({query:(T=X(L.has(m)?m:u),S=X(u),W=(e=>{let t={};for(let[n,i,r]of f){let o=e[r];o.length>1&&(t[n]={type:new s(p),description:v(i,o)})}if(0!==Object.keys(t).length)return new o({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(U),new o({name:"Query",fields:{root:{type:new s(T),description:"The root entity of the configuration."},entities:{type:new s(new r(S)),args:{ids:{type:new r(new s(t))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new s(S),description:"The selected entity, or the root entity when nothing is selected."},...W?{navigation:{type:new s(W)}}:{}}})),mutation:(({deletableTypes:e,writableTypes:i,childRecipes:a,replaceRecipes:d,actionFields:c,objectTypes:l,anyDomainEntity:y,targetOutputType:w})=>{let u,m;if(0!==e.length||0!==i.length||0!==Object.keys(a).length||0!==Object.keys(d).length||0!==c.length)return new o({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new s(new r(new s(t))),args:{id:{type:new s(t)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=A(a)).length?{}:{addChild:{type:new s(new r(new s(y))),args:{parentId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(m=A(d)).length?{}:{replaceEntity:{type:new s(new r(new s(y))),args:{entityId:{type:new s(t)},recipeGroupId:{type:new s(p)},recipeKey:{type:new s(p)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${m.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...i.flatMap(e=>{let i=l.get(e.entityType);return i?[(({entityType:e,fields:i},r)=>{let o=Object.fromEntries(i.map(({name:e,type:t,description:n})=>[e,{type:h(t),description:n}]));return{[`modify${e}`]:{type:r,args:{id:{type:new s(t)},delta:{type:new s(new n({name:`${e}Delta`,fields:o}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,i)]:[]}),Object.fromEntries(c.map(e=>{var t;return[e.fieldName,{type:new s(new o({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?(({target:e,list:t,nullable:n},i)=>{let o=t?new r(new s(i(e))):i(e);return n?o:new s(o)})(t,w):h(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:h(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:K,writableTypes:P,childRecipes:Q,replaceRecipes:B,actionFields:V,objectTypes:J,anyDomainEntity:X(u),targetOutputType:Y}),types:[...L.values(),...J.values()]}),ei=c(en);if(ei.length>0)throw Error(ei.map(e=>e.message).join(" "));let er=d(en);return{sdl:er,navigationFields:f.filter(([,,e])=>U[e].length>1).map(([e])=>e),fields:_,deletableTypes:K,writableFields:Object.fromEntries(P.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:Q,replaceRecipes:B,fieldOptions:Object.fromEntries(x.flatMap(e=>{let t=j(z,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),actions:Object.fromEntries(V.map(({fieldName:e,actionName:t})=>[e,t])),lenses:y($,w(er))}};
+import{GraphQLBoolean as e,GraphQLEnumType as t,GraphQLID as n,GraphQLInputObjectType as i,GraphQLInterfaceType as s,GraphQLList as r,GraphQLNonNull as o,GraphQLObjectType as a,GraphQLSchema as p,GraphQLString as d,printSchema as c,validateSchema as l}from"graphql";import{GraphQLJSON as h,createAssistantValueType as y}from"./assistant-value-type.js";import{buildAssistantLenses as w}from"./build-assistant-lenses.js";import{createAssistantExecutionSchema as u}from"./create-assistant-execution-schema.js";let g="AnyDomainEntity",f="RootEntity",m=[["navigationState","Active navigation state.","navigationStates"],["viewState","Active view state.","viewStates"],["toolState","Active tool state.","toolStates"]],b={section:"childRecipes",mutation:"addChild",typeSuffix:"ChildRecipes"},v={section:"replaceRecipes",mutation:"replaceEntity",typeSuffix:"ReplaceRecipes"},$=(e,t)=>Object.entries(e).find(([e])=>e===t)?.[1],j=(e,t)=>{if(!t||0===t.length)return e;let n=`One of: ${t.map(e=>`"${e}"`).join(", ")}.`;return e?/[.!?]$/.test(e)?`${e} ${n}`:`${e}. ${n}`:n},O=({target:e,list:t,nullable:n},i)=>{let s=t?new r(new o(i(e))):i(e);return n?s:new o(s)},E=(e,t,i)=>{let s={id:{type:new o(n),description:i?`Unique id of the entity, assigned by the configurator, e.g. "${i}-1".`:void 0},type:{type:new o(d),description:i?`Entity type name, e.g. "${i}".`:void 0}};for(let n of e)s[n.name]={type:"edge"===n.type.kind?O(n.type,t):y(n.type.type),description:n.description};return s},R=e=>Object.fromEntries(e.map(({name:e,source:t,localized:n})=>[e,n?{source:t,localized:!0}:{source:t}])),k=new o(new r(new o(h))),T=' Each is { type, severity, entityId, message }: severity is "warning" or "notice", entityId the entity it is on or null, message the warning as the user would be told it or null.',I={sameForAllInstances:e=>`Same recipes for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},S={sameForAllInstances:e=>`Same for every ${e}.`,constantDuringSession:()=>"Fixed for the session."},N=(e,t,n)=>e.map(e=>` ${t[e](n)}`).join(""),A=({section:e,typeSuffix:t},n,{entityType:i,purpose:s,recipeGroup:r})=>0===n.length?{}:{[e]:{type:new o(new a({name:`${i}${t}`,fields:Object.fromEntries(n.map(({groupId:e,description:t,dryRuns:n,hints:s})=>{let o;return[e,{type:r,description:`${!(o=t?.trim())?"":/[.!?]$/.test(o)?`${o} `:`${o}. `}Null while the configurator does not offer it on the entity.${n?"":" Cannot be dry-run."}${N(s,I,i)}`}]}))})),description:`The recipe groups for ${s} this ${i}, one field each.`}},M=({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s,screenshots:p,hasInvariants:d},{recipeGroup:c,fieldOption:l,screenshot:y})=>new a({name:`${e}Meta`,fields:Object.assign(A(b,n,{entityType:e,purpose:"adding children to",recipeGroup:c}),A(v,i,{entityType:e,purpose:"replacing",recipeGroup:c}),...s.map(({options:{edgeName:t,field:n,validate:i,dryRuns:s},hints:a})=>({[t]:{type:new r(new o(l)),args:{values:{type:new r(new o(h)),description:"Only the options with these values; values not listed are ignored."}},description:`Values "${n}" accepts on this ${e}. Null when there is no choice to make.${i?"":" Not checked on write."}${s?"":" Cannot be dry-run."}${N(a,S,e)}`}})),0===p.length?{}:{screenshot:{type:y,args:{view:{type:new o(new t({name:`${e}ScreenshotView`,values:Object.fromEntries(p.map(({view:e,description:t})=>[e,{description:t}]))}))}},description:"Renders this entity from a predefined view. The picture follows the tool result as an image labelled with `image`. Null when the view does not apply to this entity right now."}},d?{warnings:{type:k,description:`The warnings and notices this ${e} has right now.${T}`}}:{})}),D=(e,t)=>t?e?"What can be done to this entity right now, and its warnings.":"The warnings of this entity right now.":"What can be done to this entity right now.",W=e=>Object.entries(e).map(([e,t])=>`${e} (${t.map(({groupId:e})=>e).join(", ")})`);export const buildAssistantManifest=t=>{var I,S,N,A,x;let C,F,q,G,{entityTypes:U,aliases:K,exampleType:P,fields:V,states:z,deletableTypes:L,writableTypes:Q,actionFields:B,optionsEdges:H,invariantTypes:J}=t,{childRecipes:X,replaceRecipes:Y}=t,Z=new Map,_=new Map,ee=new Map,et=e=>{let[t,...n]=Object.entries(K).find(([t])=>t===e)?.[1]??[];return(t&&0===n.length?_.get(t):void 0)??ee.get(e)??ei},en=e=>_.get(e)??et(e),ei=new s({name:g,description:"Every entity of the configuration.",fields:()=>E(V[g]??[],en,P)});for(let e of(ee.set(g,ei),Object.keys(K)))e!==g&&ee.set(e,new s({name:e,interfaces:[ei],fields:()=>E(V[e]??[],en)}));let es={};for(let e of U){let t=[g,...Object.entries(K).filter(([t,n])=>t!==g&&n.includes(e)).map(([e])=>e)],n=V[e]??[];es[e]=R(n),_.set(e,new a({name:e,interfaces:t.flatMap(e=>ee.get(e)??[]),fields:()=>{let t=Z.get(e);return{...E(n,en),...t?{meta:{type:new o(t.type),description:t.description}}:{}}}}))}let er=(I=()=>et(ee.has(f)?f:g),S=()=>et(g),C=new a({name:"DryRunError",description:"One reason a change cannot be made right now.",fields:{type:{type:new o(d),description:"Kind of the problem."},entityId:{type:n,description:"The entity the problem is on, when it is on one."},message:{type:d,description:"The problem as the user would be told it."}}}),new a({name:"DryRun",description:"What using a recipe or writing an option would do, tried out on the configuration the query reads. Nothing is changed.",fields:()=>({ok:{type:new o(e),description:"Whether the change would succeed on the configuration the query reads."},root:{type:I(),description:"The root entity of the configuration as it would be after the change; null when ok is false. Everything selected under it reads that configuration."},changedEntities:{type:new o(new r(new o(S()))),description:"Entities the change would add or modify; empty when ok is false. One whose id is not in the configuration would be added, and its real id may differ. An entity written to is listed even when its values stay the same."},deletedEntityIds:{type:new o(new r(new o(n))),description:"The ids of the entities the change would remove; empty when ok is false."},sideEffects:{type:new o(new r(new o(d))),description:"The major or unexpected things the configurator would change along with it; empty when ok is false."},warnings:{type:k,description:`The warnings and notices the change would newly cause, which do not stop it; empty when ok is false.${T}`},errors:{type:new o(new r(new o(C))),description:"Why the change cannot be made; empty when ok is true."}})})),eo={recipeGroup:(N=[...Object.keys(X).length>0?[b.mutation]:[],...Object.keys(Y).length>0?[v.mutation]:[]],F=N.join(" or "),q=new a({name:"Recipe",description:`${N.includes("addChild")?"One thing that can be added to the entity (under childRecipes)":"One thing the entity can be replaced with (under replaceRecipes)"}${N.length>1?" or that it can be replaced with (under replaceRecipes)":""}.`,fields:{key:{type:new o(d),description:`Pass to ${F} as recipeKey, or to recipes(keys:) to read this recipe again.`},name:{type:new o(d),description:"Name shown to the user."},description:{type:d},imageUrl:{type:d,description:"Thumbnail shown to the user."},dryRun:{type:er,description:"What using this recipe would do. Null when it cannot be tried."}}}),new a({name:"RecipeGroup",description:"A group of recipes for this entity.",fields:{groupId:{type:new o(d),description:`Pass to ${F} as recipeGroupId.`},name:{type:new o(d),description:"Name shown to the user."},description:{type:d},recipes:{type:new o(new r(new o(q))),args:{keys:{type:new r(new o(d)),description:"Only the recipes with these keys; keys not in the group are ignored."}}}}})),fieldOption:new a({name:"FieldOption",description:"One value a field accepts. Writing a value outside the list is rejected unless the field description says it is not checked.",fields:{value:{type:new o(h),description:"The value to write to the field."},name:{type:d,description:"Name shown to the user."},description:{type:d},imageUrl:{type:d,description:"Image shown to the user."},color:{type:d,description:'Color shown to the user, as "#rrggbb".'},dryRun:{type:er,description:"What writing this value would do. Null when it cannot be tried."}}}),screenshot:new a({name:"Screenshot",description:"A screenshot of an entity. The picture itself follows the tool result.",fields:{image:{type:new o(n),description:"Label of the image that follows the tool result."}}})};for(let e of U){let n=$(X,e)??[],i=$(Y,e)??[],s=$(H,e)??[],r=$(t.screenshots,e)??[],o=J.includes(e),a=n.length>0||i.length>0||s.length>0||r.length>0;(a||o)&&Z.set(e,{description:D(a,o),type:M({entityType:e,childRecipes:n,replaceRecipes:i,optionsEdges:s,screenshots:r,hasInvariants:o},eo)})}let ea=new p({query:(A=et(ee.has(f)?f:g),x=et(g),G=(e=>{let t={};for(let[n,i,s]of m){let r=e[s];r.length>1&&(t[n]={type:new o(d),description:j(i,r)})}if(0!==Object.keys(t).length)return new a({name:"Navigation",description:"The active UI states of the configurator.",fields:t})})(z),new a({name:"Query",fields:{root:{type:new o(A),description:"The root entity of the configuration."},entities:{type:new o(new r(x)),args:{ids:{type:new r(new o(n))}},description:"Every entity, or the given ids in order with null for an unknown id."},selectedEntity:{type:new o(x),description:"The selected entity, or the root entity when nothing is selected."},...G?{navigation:{type:new o(G)}}:{},warnings:{type:k,description:`Every warning and notice of the configuration the query reads.${T}`}}})),mutation:(({deletableTypes:e,writableTypes:t,childRecipes:s,replaceRecipes:p,actionFields:c,objectTypes:l,anyDomainEntity:h,targetOutputType:w})=>{let u,g;if(0!==e.length||0!==t.length||0!==Object.keys(s).length||0!==Object.keys(p).length||0!==c.length)return new a({name:"Mutation",fields:Object.assign(0===e.length?{}:{deleteEntity:{type:new o(new r(new o(n))),args:{id:{type:new o(n)}},description:`Deletes the entity and everything composed into it. Deletable types: ${e.join(", ")}. Returns the ids removed, the given one first.`}},0===(u=W(s)).length?{}:{addChild:{type:new o(new r(new o(h))),args:{parentId:{type:new o(n)},recipeGroupId:{type:new o(d)},recipeKey:{type:new o(d)}},description:`Adds a child to the entity parentId from a recipe listed under its meta { childRecipes }. Types with child recipes: ${u.join("; ")}. Returns the entities added, the recipe's own first; empty when they were removed again.`}},0===(g=W(p)).length?{}:{replaceEntity:{type:new o(new r(new o(h))),args:{entityId:{type:new o(n)},recipeGroupId:{type:new o(d)},recipeKey:{type:new o(d)}},description:`Replaces the entity entityId from a recipe listed under its meta { replaceRecipes }. Types with replace recipes: ${g.join("; ")}. The replacement is a new entity: it has a new id and the field values of its recipe, and entityId no longer exists. Returns the entities added, the replacement first; empty when they were removed again.`}},...t.flatMap(e=>{let t=l.get(e.entityType);return t?[(({entityType:e,fields:t},s)=>{let r=Object.fromEntries(t.map(({name:e,type:t,description:n})=>[e,{type:y(t),description:n}]));return{[`modify${e}`]:{type:s,args:{id:{type:new o(n)},delta:{type:new o(new i({name:`${e}Delta`,fields:r}))}},description:`Sets the fields named in delta on one ${e}. Returns the entity after the change, or null when the change removed it.`}}})(e,t)]:[]}),Object.fromEntries(c.map(e=>{var t;return[e.fieldName,{type:new o(new a({name:(t=e.fieldName,`${t.charAt(0).toUpperCase()+t.slice(1)}Result`),description:`What ${e.fieldName} returns, read from the configuration after the change.`,fields:()=>Object.fromEntries(Object.entries(e.result).map(([e,t])=>[e,{type:"edge"===t.kind?O(t,w):y(t.type),description:t.description}]))})),args:Object.fromEntries(Object.entries(e.args).map(([e,t])=>[e,{type:y(t.type),description:t.description}])),description:e.description}]})))})})({deletableTypes:L,writableTypes:Q,childRecipes:X,replaceRecipes:Y,actionFields:B,objectTypes:_,anyDomainEntity:et(g),targetOutputType:en}),types:[...ee.values(),..._.values()]}),ep=l(ea);if(ep.length>0)throw Error(ep.map(e=>e.message).join(" "));let ed=c(ea);return{sdl:ed,navigationFields:m.filter(([,,e])=>z[e].length>1).map(([e])=>e),fields:es,deletableTypes:L,writableFields:Object.fromEntries(Q.map(({entityType:e,fields:t})=>[e,Object.fromEntries(t.map(({name:e,property:t})=>[e,t]))])),childRecipes:X,replaceRecipes:Y,fieldOptions:Object.fromEntries(U.flatMap(e=>{let t=$(H,e);return t?[[e,t.map(({options:e})=>e)]]:[]})),screenshots:Object.fromEntries(U.flatMap(e=>{let n=$(t.screenshots,e);return n?[[e,n]]:[]})),actions:Object.fromEntries(B.map(({fieldName:e,actionName:t})=>[e,t])),lenses:w(t,u(ed)),formElements:t.formElements}};

package/dist/domain/application/assistant/generate-assistant-prompt.d.ts

@@ -1,3 +1,5 @@
-import type { AssistantManifest } from './assistant-manifest.js';
+import { type AssistantFormElementDescriptor, type AssistantManifest } from '../../spec/index.js';
+/** How the prompt writes an element: its tag with each attribute and what it takes. Exported for tests. */
+export declare const formElementSignature: ({ name, role, attributes }: AssistantFormElementDescriptor) => string;
 /** SDK-version conventions for using the manifest's capabilities and reading their results. */
 export declare const generateAssistantPrompt: (assistant: AssistantManifest) => string;

package/dist/domain/application/assistant/generate-assistant-prompt.js

@@ -1 +1 @@
-export const generateAssistantPrompt=e=>{let t=Object.values(e.childRecipes??{}).some(e=>e.length>0),a=Object.values(e.replaceRecipes??{}).some(e=>e.length>0),n=Object.values(e.fieldOptions??{}).some(e=>e.length>0),s=Object.keys(e.actions??{}).length>0,i=(e.deletableTypes?.length??0)>0||Object.values(e.writableFields??{}).some(e=>Object.keys(e).length>0)||t||a||s,o=t||a||n,r=[...t?["`childRecipes` is what can be added to it"]:[],...a?["`replaceRecipes` what it can be replaced with"]:[],...n?["`<field>Options` the values a field accepts"]:[]],h=["`selected`",...(e.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",...i?[`- Use a mutation inside \`query\` to answer a what-if about a change ${o?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead."],...i?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...s?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...o?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${r.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...t||a?["recipes"]:[],...n?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${h} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...i?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(e.deletableTypes?.length??0)>0||a?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${i?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Entity links","- When you name an entity the user may want to find, write it as a Markdown link whose target is `entity:` and its id: `[the corner cabinet](entity:<id>)`. The user sees only the text; the id is never shown.","- Link only entities that exist in the configuration now, never one created only inside `query`."],...e.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",e.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};
+import{ASSISTANT_BUILT_IN_FORM_ELEMENTS as e}from"../../spec/index.js";let t=[["Containers",["group","choice","choices"]],["Options",["option"]],["Inputs",["input"]]];export const formElementSignature=({name:e,role:t,attributes:a})=>{let n=["label",...Object.entries(a).map(([e,t])=>((e,{type:t,enum:a})=>a?`${e}="${a.join("|")}"`:"string"===t?e:`${e}="<${t}>"`)(e,t))];return"option"===t||"input"===t?`<${e} ${n.join(" ")} />`:`<${e} ${n.join(" ")}>…</${e}>`};export const generateAssistantPrompt=a=>{let n,s=Object.values(a.childRecipes??{}).some(e=>e.length>0),o=Object.values(a.replaceRecipes??{}).some(e=>e.length>0),i=Object.values(a.fieldOptions??{}).some(e=>e.length>0),r=Object.keys(a.actions??{}).length>0,h=Object.values(a.screenshots??{}).some(e=>e.length>0),l=(a.deletableTypes?.length??0)>0||Object.values(a.writableFields??{}).some(e=>Object.keys(e).length>0)||s||o||r,d=s||o||i,c=[...s?["`childRecipes` is what can be added to it"]:[],...o?["`replaceRecipes` what it can be replaced with"]:[],...i?["`<field>Options` the values a field accepts"]:[]],u=["`selected`",...(a.navigationFields??[]).map(e=>`\`${e}\``)].join(", ");return[["Tools","- Put related operations in one call and select only the fields you need.",`- Give every ${l?"`query` and `apply` call":"`query` call"} a \`title\` of two to five words in the user's language that says what it does for them, e.g. ${l?'"Add two drawers"':'"Compare drawer prices"'}.`,...l?[`- Use a mutation inside \`query\` to answer a what-if about a change ${d?"the lists under `meta` do not show":"before making it"}.`,"- Use `apply` only for what the user asked for."]:["- Nothing in this configurator can be changed through you. Say so when the user asks for a change."],"- When an operation fails, its `errors` say why and what to send instead. A change the configuration does not allow fails with one error per reason, as the user would be told it.","- Warnings and notices never make anything fail. The root `warnings` field lists every current one, and `meta { warnings }` those of one entity, where its type has them."],...l?[["After a change","- A change is made only when the `apply` result has `committed: true`. Otherwise `errors` or `message` says what happened; without either, nothing changed. Never say a change was made when it was not.","- `sideEffects` names the major or unexpected things the configurator changed along with your change. Tell the user about them when committed; otherwise they describe what would happen. Smaller adjustments are not listed.","- `warnings` lists the warnings and notices your change newly causes. They do not block it: tell the user about them, and offer a fix when one is clear.","- A mutation returns the state after the change: use the ids and values it returned, not the ones you sent.",...r?["- When one mutation does the whole of what the user asked, use it instead of building the same change from several others."]:[]]]:[],...d?[["What can be done to an entity",`- \`meta\` lists what is possible right now: ${c.join(", ")}. Read the list before such a change and before telling the user what is available.`,`- You can select \`dryRun\` on ${[...s||o?["recipes"]:[],...i?["options"]:[]].join(" or ")} to look ahead and pick one that meets what the user asked for. It is optional before a change.`,`- Select only the ${[...s||o?["recipe groups"]:[],...i?["options edges"]:[]].join(" and ")} you need. To read again only the ones you are deciding between, pass ${[...s||o?["their `key` to `recipes(keys:)`"]:[],...i?["their `value` to `<field>Options(values:)`"]:[]].join(" or ")}.`,"- Read the lists again after a change, unless their descriptions say they stay the same."]]:[],...h?[["Seeing the design","- `meta { screenshot(view: …) { image } }` renders an entity from one of the views its `<Type>ScreenshotView` lists. The picture follows the tool result.","- Take one when the user asks how the design looks, or when you are not sure something is laid out right: what sits where, what overlaps or lines up. Otherwise rely on the data.","- Each one costs tokens and blocks the user's configurator while it renders."]]:[],["Images from the user","- The user may attach photos or reference images to a message, such as their room or a design they like.","- Sizes you read from a photo are estimates: tell the user the values you read and confirm them before you apply them.","- An image the message calls an annotation is marked up by the user: the red strokes are drawn by the user, and each numbered red pin marks the place its comment, listed by number before the message, is about.","- An annotation of the configurator view is the user's own current view of the configurator, not one of the screenshot views. An annotation of an image marks up an image, such as one of your drawings."],["The `[changes]` block","- Every user message starts with it: a glimpse of what the user did in the configurator since your last turn.",`- \`[changes: none]\`, or only ${u} lines: what you know still holds. Do not query it again.`,"- Other lines are a hint at what to read again: `A` added, `D` deleted, `M` modified with the fields. Text after `#` says what caused the line; `reset: undo/redo` says the user undid or redid changes.","- Read computed fields again when a listed change may affect them.","- `[changes: unavailable]` and `[changes: too many (n)]`: read again before relying on anything you read earlier.",...l?["- Your applied changes are not listed, except those waiting for user approval: they appear once approved."]:[]],["Reading the schema","- Take ids from results.",...(a.deletableTypes?.length??0)>0||o?["- The id of a deleted or replaced entity is gone and may later be given to another entity."]:[],`- A field whose name starts with \`_\` is computed: read it${l?", never write it":""}.`,"- Numbers are in the unit the field description names. Convert when the user uses another unit."],["Links","- You may link an entity of the current configuration when you speak about that very entity: `[the left burner](entity:CookingTop-1)`. It helps the user find it in the configurator.",...d?["- Whenever you name recipes or options you read from `meta`, in a list, a table or a sentence, link each one: `[Single gas burner](recipe:KitchenRange-1/top/gas_single)` or `[Oak](option:Cabinet-2/finishOptions/oak)`. The link shows the user its picture or color and its description, so never draw previews yourself. The target is the entity id, the recipe group id or the options field you read, and the key or value, each encoded as in a URL."]:[]],["Replies","- Write Markdown only, never HTML: the panel does not render it. Only a drawing holds markup.","- An image, `![alt](path)`, is shown only when its path is relative.","- To make a warning or a key note stand out, write a GitHub alert: a blockquote whose first line is only `[!WARNING]` or `[!NOTE]`. Use it sparingly."],["Drawings","- You can draw a schematic for the user: a fenced code block with the language `svg` that holds one SVG document. The panel shows it as a picture, and the user can open it larger beside the chat.","- Draw when a schematic explains better than words, such as a layout seen from above, dimensions or clearances, or a comparison of options, or when the user or the instructions of this configurator ask for one. Never draw what the product looks like: the user sees it in the configurator.","- At most one drawing per reply.",'- The root is `<svg xmlns="http://www.w3.org/2000/svg" viewBox="…">`, and its first child is a `<title>` that says what the drawing shows.',"- Paint the background first with a `<rect>` that covers the whole `viewBox`, and give every fill and stroke an explicit colour, never `currentColor` or a CSS variable.","- The picture is as wide as the chat panel, about 360 px: keep text at least 14 px tall at that width, and use generic font families such as `sans-serif`.","- A drawing runs no script and loads nothing: no `<script>`, event attributes, `<foreignObject>`, external links or images.","- Keep it simple: a drawing that is not well-formed SVG, or is over 200 KB, is not shown.","- The user can annotate a drawing to give you feedback on it: their message then carries it as an annotation of an image."],["Forms","- To ask the user something they answer by picking or typing, end your reply with a form: a fenced code block with the language `form`. It holds only elements, written as lowercase tags with string attributes, without Markdown or text.","- Every element takes `label`, the text the user sees; on a container or an input it also names the answer. An option or an input whose signature lists `value` takes it: an option sends it instead of its label, and an input starts with it.",'- A bare attribute in a signature takes any text, `name="<type>"` takes a value of that type written as text, such as `min="<number>"`, and `name="a|b"` takes one of the words listed.',"- Options can also stand on their own, outside a `choice` or `choices`.","- An element or attribute not listed here, or an element other than an option inside a `choice` or `choices`, makes the whole form fail.","- The answer is the user's next message. Each container or input gives a line `Label: value`, or the bare value without a label; the lines of a labelled container are indented by two spaces under it, a `choices` lists each picked option on its own line, and `—` marks what was left unanswered.",'- Example: `<choice label="Plinth"><reply label="Black" /><reply label="Oak" /></choice>` is answered with `Plinth: Oak`.',"- The chat shows the answer as the user's own message, so a `value` reads as natural words, never as an id, key or code. Give `value` only when the label alone would be unclear as an answer, and map the answer's labels back to ids yourself.",...(n=[...e,...a.formElements??[]],t.flatMap(([e,t])=>{let a=n.filter(({role:e})=>t.includes(e));return 0===a.length?[]:[`- ${e}:`,...a.map(e=>`  - \`${formElementSignature(e)}\`: ${(({description:e,required:t=[]})=>0===t.length?e:`${e} Requires ${t.map(e=>`\`${e}\``).join(", ")}.`)(e)}`)]}))],...a.lenses?.declarations?[["Built-in fragments","- These fragments are already defined for every operation. Spread one by name on a field of its type, as in `field { ...FragmentName }`, instead of listing its fields.","- A fragment is a starting selection: add the other fields you need next to the spread, by name from the schema.","- Never define a fragment with one of these names.","",a.lenses.declarations]]:[]].map(e=>e.join("\n")).join("\n\n")};

package/dist/domain/application/assistant/index.d.ts

@@ -1,9 +1,6 @@
-export { ASSISTANT_HINTS } from './assistant-resolved-manifest.js';
-export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedHint, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
 export { buildAssistantManifest } from './build-assistant-manifest.js';
 export type { AssistantFieldExposure } from './create-assistant-execution-schema.js';
 export { AssistantFieldClashError, createAssistantExecutionSchema } from './create-assistant-execution-schema.js';
-export type { AssistantFieldSource, AssistantRecipeGroup, AssistantFieldOptions, AssistantManifest, } from './assistant-manifest.js';
 export { generateAssistantPrompt } from './generate-assistant-prompt.js';
 export * from './session-setup/index.js';
 export { describeAssistantValues, mergeAssistantFields, resolveAssistantField } from './assistant-fields.js';

package/dist/domain/application/assistant/index.js

@@ -1 +1 @@
-export{ASSISTANT_HINTS}from"./assistant-resolved-manifest.js";export{buildAssistantManifest}from"./build-assistant-manifest.js";export{AssistantFieldClashError,createAssistantExecutionSchema}from"./create-assistant-execution-schema.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";export*from"./session-setup/index.js";export{describeAssistantValues,mergeAssistantFields,resolveAssistantField}from"./assistant-fields.js";
+export{buildAssistantManifest}from"./build-assistant-manifest.js";export{AssistantFieldClashError,createAssistantExecutionSchema}from"./create-assistant-execution-schema.js";export{generateAssistantPrompt}from"./generate-assistant-prompt.js";export*from"./session-setup/index.js";export{describeAssistantValues,mergeAssistantFields,resolveAssistantField}from"./assistant-fields.js";