@salsita-ai/sdk 0.50.0-develop.98e8b1502f → 0.50.0-develop.9db1e1f3bf

package/dist/domain/core/action/action-factory.d.ts

@@ -0,0 +1,11 @@
+import type { DomainEntity } from '../model/index.js';
+import type { ActionImplementations, ActionTypes } from './action.js';
+/**
+ * Creates the `implementActions` factory the generated `domain-spec.ts` exposes as
+ * `phx.domain.implementActions`. A module in `src/actions/` implements any subset of the declared
+ * actions and gets each parameter and result typed from the spec; a name the spec does not declare
+ * is a type error, since its implementation would have to be `never`. The generated barrel lists
+ * the modules; `DomainBuilder.withActionModules` merges them, and domain initialization checks that
+ * every declared action is implemented.
+ */
+export declare const createActionFactory: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ACTION_TYPES extends ActionTypes, CONTEXT_EXTENSION = unknown, SYSTEMS = unknown>() => <IMPLEMENTATIONS extends Partial<ActionImplementations<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ACTION_TYPES, CONTEXT_EXTENSION, SYSTEMS>>>(implementations: IMPLEMENTATIONS & Readonly<Record<Exclude<keyof IMPLEMENTATIONS, keyof ACTION_TYPES>, never>>) => IMPLEMENTATIONS;

package/dist/domain/core/{action.d.ts → action/action.d.ts}

@@ -1,10 +1,8 @@
 import type { ExtendedJsonSchema } from '@salsita-ai/common/utils';
-import type { StateUpdate, UpdateFactory } from '../components/updates.js';
-import type { DomainContextSystems } from '../domain-context/domain-context-systems.js';
-import type { IdSequence } from '../domain-context/store-system/next-domain-entity-id.js';
-import type { ExpressionContext } from './expression.js';
-import type { $DomainEntity, DomainEntity } from './model.js';
-import type { DomainState } from './state.js';
+import type { StateUpdate, UpdateFactory } from '../component/index.js';
+import type { OpenExpressionContext } from '../expression/index.js';
+import type { DomainEntity } from '../model/index.js';
+import type { DomainState, IdSequence } from '../state/index.js';
 /**
  * The parameter and result types of the actions an application declares under `actions`, keyed by
  * action name. Codegen derives it from the spec; `ActionSystem.prepareAction` and the
@@ -41,27 +39,33 @@ export interface PreparedAction<ENTITIES extends DomainEntity<string>, RESULT> {
     readonly readResult: (change: ActionStateChange<ENTITIES>) => RESULT;
 }
 /**
- * What an action implementation reads besides its parameters and the state: the expression context
- * (domain, data, projections), the domain systems, an id sequence for entities it creates, and the
- * update factory typed for the application's entities.
+ * What an action implementation reads besides its parameters and the state. Core declares its own
+ * part: the expression context (core's part of it, and in `CONTEXT_EXTENSION` what whoever runs the
+ * action adds to it, such as the projections), an id sequence for entities the action creates, and
+ * the update factory typed for the application's entities. `SYSTEMS` is what whoever runs the action
+ * hands it as `systems`, such as the systems of the domain runtime. An action that reads only core's
+ * part leaves both parameters out.
  */
-export interface ActionContext<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string> {
-    readonly expressionContext: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>;
-    readonly systems: DomainContextSystems<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>;
+export interface OpenActionContext<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, CONTEXT_EXTENSION = unknown, SYSTEMS = unknown> {
+    readonly expressionContext: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>;
+    readonly systems: SYSTEMS;
     readonly getIdSequence: () => IdSequence<ENTITIES>;
     readonly updates: UpdateFactory<ENTITIES>;
 }
-export type AnyActionContext = ActionContext<any, any, any, any, any, any, any, any, any, any>;
 /**
  * The implementation of one declared action. It must not change anything itself; a thrown error
  * fails the call, and its message reaches whoever asked for the action, so it says what went wrong
  * and how to fix the request.
  */
-export type ActionImplementation<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, PARAMS, RESULT> = (params: PARAMS, state: DomainState<ENTITIES>, context: ActionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES>) => PreparedAction<ENTITIES, RESULT>;
-export type AnyActionImplementation = ActionImplementation<any, any, any, any, any, any, any, any, any, any, any, unknown>;
-/** The implementations of every declared action by name, as the generated barrel merges them from `src/actions/`. */
-export type ActionImplementations<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, NAVIGATION_STATES extends string, VIEW_STATES extends string, TOOL_STATES extends string, EXPORT_STATES extends string, ACTION_TYPES extends ActionTypes> = {
-    readonly [NAME in keyof ACTION_TYPES]: ActionImplementation<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, NAVIGATION_STATES, VIEW_STATES, TOOL_STATES, EXPORT_STATES, ACTION_TYPES[NAME]['params'], ACTION_TYPES[NAME]['result']>;
+export type ActionImplementation<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, PARAMS, RESULT, CONTEXT_EXTENSION = unknown, SYSTEMS = unknown> = (params: PARAMS, state: DomainState<ENTITIES>, context: OpenActionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION, SYSTEMS>) => PreparedAction<ENTITIES, RESULT>;
+/**
+ * One action implementation with its types erased. The two parameters of its context are erased
+ * too, so that an implementation written against a closed context is assignable to it.
+ */
+export type AnyActionImplementation = ActionImplementation<any, any, any, any, any, any, unknown, any, any>;
+/** The implementations of every declared action by name, as `DomainBuilder.withActionModules` merges them from `src/actions/`. */
+export type ActionImplementations<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ACTION_TYPES extends ActionTypes, CONTEXT_EXTENSION = unknown, SYSTEMS = unknown> = {
+    readonly [NAME in keyof ACTION_TYPES]: ActionImplementation<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ACTION_TYPES[NAME]['params'], ACTION_TYPES[NAME]['result'], CONTEXT_EXTENSION, SYSTEMS>;
 };
 /** The action implementations of an application with their types erased, as the runtime spec slice holds them. */
 export type AnyActionImplementations = Readonly<Record<string, AnyActionImplementation>>;

package/dist/domain/core/action/index.d.ts

@@ -0,0 +1,2 @@
+export * from './action-factory.js';
+export type * from './action.js';

package/dist/domain/core/action/index.js

@@ -0,0 +1 @@
+export*from"./action-factory.js";

package/dist/domain/{components → core/component}/component-reader-types.d.ts

@@ -1,5 +1,4 @@
-import type { ComponentInstance, SystemComponentTypeConstraint } from '../core/component.js';
-import type { EntityId } from '../core/model.js';
+import type { ComponentInstance, EntityId, SystemComponentTypeConstraint } from '../model/index.js';
 import type { ComponentSystemFilterState, FilterMismatchReason } from './system-component-filter.js';
 /**
  * Filter for reading a single attachment of a component on one entity.

package/dist/domain/{components → core/component}/debug-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from '../core/model.js';
+import { type EntityId } from '../model/index.js';
 export type DebugStateComponentState = {
     readonly enabled: boolean;
 };

package/dist/domain/core/component/debug-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as e}from"../model/index.js";import{SystemComponentBuilder as t}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const debugStateComponent=t.component("debugState").withState({type:"object",properties:{enabled:{type:"boolean"}},required:["enabled"],additionalProperties:!1}).withWritableKeys(["enabled"]).build();export const isDebugStateComponentSnapshot=t=>e(t,"singleton",debugStateComponent);export const isSystemDebugStateComponentSnapshot=e(o,"singleton",debugStateComponent);

package/dist/domain/core/component/domain-component-optic.d.ts

@@ -0,0 +1,65 @@
+import { type CustomExpression, type OpenExpressionContext } from '../expression/index.js';
+import type { $DomainEntity, AliasMap, DomainEntity, EntityByType, StateOfComponent, SystemComponentType, SystemComponentTypeConstraint, WritableStateOfComponent } from '../model/index.js';
+import type { DomainState } from '../state/index.js';
+import { type ComponentSystemFilter, type NavigationFilterOptic } from './legacy-filter.js';
+import type { ComponentSystemFilterProps, GradualComponentSystemFilter } from './system-component-filter.js';
+/**
+ * The value a project states for one filter criterion: the value `ComponentSystemFilterProps`
+ * states for it, with an array read-only. `system-component-filter.ts` holds the same rule for the
+ * filter an optic carries; each file keeps its own copy so that the folder exports no new name.
+ */
+type FilterCriterion<KEY extends keyof ComponentSystemFilterProps> = [
+    Required<ComponentSystemFilterProps>[KEY]
+] extends [ReadonlyArray<infer ITEM>] ? readonly ITEM[] : Required<ComponentSystemFilterProps>[KEY];
+type CustomOpticAttach<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ENTITY extends ENTITIES, $ENTITY extends $DomainEntity<ENTITIES>, COMPONENT_TYPE extends SystemComponentTypeConstraint, CONTEXT_EXTENSION> = (read: CustomExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, $ENTITY, StateOfComponent<COMPONENT_TYPE>, CONTEXT_EXTENSION>, write?: DomainComponentSimpleOptic<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITY, COMPONENT_TYPE, CONTEXT_EXTENSION>['write']) => DomainComponentSimpleOptic<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITY, COMPONENT_TYPE, CONTEXT_EXTENSION>;
+export interface DomainComponentSimpleOptic<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ENTITY extends ENTITIES, COMPONENT_TYPE extends SystemComponentTypeConstraint, CONTEXT_EXTENSION = unknown> {
+    readonly kind: 'simple';
+    readonly instanceName: string;
+    readonly componentType: COMPONENT_TYPE;
+    readonly entityTypes: ReadonlySet<ENTITIES['type']>;
+    readonly generated?: boolean;
+    readonly navigationFilters: ReadonlyArray<GradualComponentSystemFilter<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>>;
+    read(entityId: ENTITIES['id'], state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>): StateOfComponent<COMPONENT_TYPE>;
+    write(writableState: WritableStateOfComponent<COMPONENT_TYPE>): Partial<Omit<ENTITY, 'id' | 'type'>>;
+}
+export interface DomainComponentDynamicOptic<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, COMPONENT_TYPE extends SystemComponentTypeConstraint, CONTEXT_EXTENSION = unknown> {
+    readonly kind: 'dynamic';
+    readonly instanceName: string;
+    readonly componentType: COMPONENT_TYPE;
+    readonly entityTypes: ReadonlySet<ENTITIES['type']>;
+    readonly generated?: boolean;
+    readonly navigationFilters: ReadonlyArray<GradualComponentSystemFilter<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>>;
+    read(entityId: ENTITIES['id'], state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>): ReadonlyArray<StateOfComponent<COMPONENT_TYPE> & {
+        key: string;
+    }>;
+}
+export type DomainComponentOptic<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ENTITY extends ENTITIES, COMPONENT_TYPE extends SystemComponentTypeConstraint, CONTEXT_EXTENSION = unknown> = DomainComponentSimpleOptic<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITY, COMPONENT_TYPE, CONTEXT_EXTENSION> | DomainComponentDynamicOptic<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, COMPONENT_TYPE, CONTEXT_EXTENSION>;
+export type AnyDomainComponentOptic = DomainComponentOptic<any, any, any, any, any, any, any>;
+export declare class DomainComponentOpticBuilder<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ALIASES extends Record<string, ENTITIES>, ENTITY extends ENTITIES, $ENTITY extends $DomainEntity<ENTITIES>, COMPONENT_TYPE extends SystemComponentTypeConstraint, CONTEXT_EXTENSION = unknown> {
+    private readonly aliasMap;
+    private readonly entityTypes;
+    private readonly componentType?;
+    private readonly instanceName?;
+    private readonly navigationFilters;
+    private readonly generated;
+    private readonly entityTypeOrAliasNames;
+    private constructor();
+    static from<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, $MAP extends Record<ENTITIES['type'], $DomainEntity<ENTITIES>>, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, ALIASES extends Record<string, ENTITIES>, CONTEXT_EXTENSION = unknown>(aliasMap: AliasMap<ALIASES>): DomainComponentOpticBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, never, never, never, CONTEXT_EXTENSION>;
+    withEntity<TYPE extends ENTITIES['type']>(entityType: TYPE): DomainComponentOpticBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, ENTITY | EntityByType<ENTITIES, TYPE>, $ENTITY | $MAP[TYPE], COMPONENT_TYPE, CONTEXT_EXTENSION>;
+    withAlias<ALIAS extends keyof ALIASES & keyof $MAP>(alias: ALIAS): DomainComponentOpticBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, ENTITY | ALIASES[ALIAS], $ENTITY | $MAP[ALIAS], COMPONENT_TYPE, CONTEXT_EXTENSION>;
+    withComponent<NEW_COMPONENT_TYPE extends SystemComponentType<any, any, any>>(componentType: NEW_COMPONENT_TYPE, instanceName: string, generated?: boolean): DomainComponentOpticBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, ENTITY, $ENTITY, NEW_COMPONENT_TYPE, CONTEXT_EXTENSION>;
+    /**
+     * @deprecated Use withGradualFilter instead
+     */
+    withFilter(filter: ComponentSystemFilter | NavigationFilterOptic<ENTITIES, $ENTITY>): DomainComponentOpticBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, ENTITY, $ENTITY, COMPONENT_TYPE, CONTEXT_EXTENSION>;
+    withGradualFilter(filter: {
+        readonly [KEY in keyof ComponentSystemFilterProps]?: FilterCriterion<KEY> | CustomExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, $ENTITY, FilterCriterion<KEY> | undefined, CONTEXT_EXTENSION>;
+    }): DomainComponentOpticBuilder<ENTITIES, ALLOWED_ROOT_ENTITIES, $MAP, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ALIASES, ENTITY, $ENTITY, COMPONENT_TYPE, CONTEXT_EXTENSION>;
+    private validate;
+    private _getProfilerLabel;
+    attach: CustomOpticAttach<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITY, $ENTITY, COMPONENT_TYPE, CONTEXT_EXTENSION>;
+    attachMany: (read: (entity: $ENTITY, state: DomainState<ENTITIES>, ctx: OpenExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, CONTEXT_EXTENSION>) => ReadonlyArray<StateOfComponent<COMPONENT_TYPE> & {
+        key: string;
+    }>) => DomainComponentDynamicOptic<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, COMPONENT_TYPE, CONTEXT_EXTENSION>;
+}
+export {};

package/dist/domain/core/component/domain-component-optic.js

@@ -0,0 +1,16 @@
+import{createCacheToken as t,getStickyCache as e}from"@salsita-ai/common/utils";import{withProfilerLabel as i}from"../../utils/profiler-label.js";import{createCustomExpression as n}from"../expression/index.js";let s={navigationStates:void 0,selectedEntityIds:void 0,hoveredEntityIds:void 0,draggedEntityIds:void 0,viewStates:void 0,toolStates:void 0,modes:void 0,roles:void 0,active:void 0,fullscreen:void 0,debug:void 0,viewports:void 0,exportedEntityIds:void 0,exportStates:void 0},a=(n,s)=>{let a=t(),o=i(s,n.read);return{...n,read:(t,i,n)=>{let s=e(i,a),r=s.get(t);if(r)return r;let l=o(t,i,n);return s.put(t,l),l}}};export class DomainComponentOpticBuilder{aliasMap;entityTypes;componentType;instanceName;navigationFilters;generated;entityTypeOrAliasNames;constructor(t,e,i,n,s=[],a=!1,o=[]){this.aliasMap=t,this.entityTypes=e,this.componentType=i,this.instanceName=n,this.navigationFilters=s,this.generated=a,this.entityTypeOrAliasNames=o}static from(t){return new DomainComponentOpticBuilder(t,[])}withEntity(t){return new DomainComponentOpticBuilder(this.aliasMap,[...this.entityTypes,t],this.componentType,this.instanceName,this.navigationFilters,this.generated,[...this.entityTypeOrAliasNames,t])}withAlias(t){return new DomainComponentOpticBuilder(this.aliasMap,[...this.entityTypes,...this.aliasMap[t]],this.componentType,this.instanceName,this.navigationFilters,this.generated,[...this.entityTypeOrAliasNames,String(t)])}withComponent(t,e,i=!1){return new DomainComponentOpticBuilder(this.aliasMap,this.entityTypes,t,e,this.navigationFilters,i,this.entityTypeOrAliasNames)}withFilter(i){if(console.warn(`Component ${this.componentType?.name}#${this.instanceName} on entity ${this.entityTypes.join(", ")} uses a legacy filter with full filter evaluation. This is a suboptimal variant and is deprecated in favor of per-criterion evaluation.
+
+  In your TS files, replace
+    withFilter()
+    ->
+    withGradualFilter()
+
+  In YAML, replace
+    $filter:
+      $read: $falseOrFilterExpression
+    ->
+    $filter:
+      active:
+        $read: $trueOrFalseExpression
+        # ... other eventual criteria
+  `),"function"==typeof i){let n=t(),a=t=>({evaluate:(s,a,o)=>{let r=e(a,n),l=r.get(s);if(!l){if(void 0===(l=i(o.domain.get$Entity(s,a),a)))throw Error(`Dynamic filter on component ${this.componentType?.name}.${this.instanceName} on entity ${s} returned 'undefined'. This is likely a bug in the component definition, check whether you are referencing a correct expression or field!`);r.put(s,l)}return"boolean"==typeof l?"active"===t?l:void 0:l[t]},meta:{}});return new DomainComponentOpticBuilder(this.aliasMap,this.entityTypes,this.componentType,this.instanceName,[...this.navigationFilters,{...s,navigationStates:a("navigationStates"),selectedEntityIds:a("selectedEntityIds"),hoveredEntityIds:a("hoveredEntityIds"),draggedEntityIds:a("draggedEntityIds"),viewStates:a("viewStates"),toolStates:a("toolStates"),modes:a("modes"),roles:a("roles"),active:a("active"),fullscreen:a("fullscreen"),debug:a("debug"),viewports:a("viewports")}],this.generated,this.entityTypeOrAliasNames)}return"boolean"==typeof i?new DomainComponentOpticBuilder(this.aliasMap,this.entityTypes,this.componentType,this.instanceName,[...this.navigationFilters,{...s,active:i}],this.generated,this.entityTypeOrAliasNames):new DomainComponentOpticBuilder(this.aliasMap,this.entityTypes,this.componentType,this.instanceName,[...this.navigationFilters,{...s,...i}],this.generated,this.entityTypeOrAliasNames)}withGradualFilter(t){let e=t=>"function"==typeof t?n(t,{}):t,i={navigationStates:e(t.navigationStates),selectedEntityIds:e(t.selectedEntityIds),hoveredEntityIds:e(t.hoveredEntityIds),draggedEntityIds:e(t.draggedEntityIds),exportedEntityIds:e(t.exportedEntityIds),viewStates:e(t.viewStates),toolStates:e(t.toolStates),exportStates:e(t.exportStates),modes:e(t.modes),roles:e(t.roles),active:e(t.active),fullscreen:e(t.fullscreen),debug:e(t.debug),viewports:e(t.viewports)};return new DomainComponentOpticBuilder(this.aliasMap,this.entityTypes,this.componentType,this.instanceName,[...this.navigationFilters,i],this.generated,this.entityTypeOrAliasNames)}validate(){if(!this.componentType||!this.instanceName)throw Error("Use withComponent before attaching");if(!this.entityTypes.length)throw Error("Use withEntity and/or withAlias before attaching")}_getProfilerLabel(){return[...this.entityTypeOrAliasNames,this.componentType.name,this.instanceName].join("_")}attach=(t,e)=>(this.validate(),a({kind:"simple",entityTypes:new Set(this.entityTypes),componentType:this.componentType,instanceName:this.instanceName,navigationFilters:this.navigationFilters,read:(e,i,n)=>t(n.domain.get$Entity(e,i),i,n),write:e??(()=>({})),generated:this.generated},this._getProfilerLabel()));attachMany=t=>(this.validate(),a({kind:"dynamic",entityTypes:new Set(this.entityTypes),componentType:this.componentType,instanceName:this.instanceName,navigationFilters:this.navigationFilters,read:(e,i,n)=>t(n.domain.get$Entity(e,i),i,n)},this._getProfilerLabel()))}

package/dist/domain/{components → core/component}/drag-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { DomainEntityId, EntityId } from '../core/model.js';
+import { type DomainEntityId, type EntityId } from '../model/index.js';
 export type DragStateComponentState = {
     /** The entity currently being dragged in the scene, or `null` while nothing is dragged. */
     readonly draggedEntityId: DomainEntityId<string> | null;

package/dist/domain/core/component/drag-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const dragStateComponent=e.component("dragState").withState({type:"object",properties:{draggedEntityId:{oneOf:[{type:"string"},{type:"null"}]}},required:["draggedEntityId"],additionalProperties:!1,tsType:"DragStateComponentState",import:[{module:"@salsita-ai/sdk/domain",member:"DragStateComponentState"}]}).withWritableKeys(["draggedEntityId"]).build();export const isDragStateComponentSnapshot=e=>t(e,"singleton",dragStateComponent);export const isSystemDragStateComponentSnapshot=t(o,"singleton",dragStateComponent);

package/dist/domain/{components → core/component}/export-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { DomainEntityId, EntityId } from '../core/model.js';
+import { type DomainEntityId, type EntityId } from '../model/index.js';
 export type ExportStateComponentState = {
     readonly activeState: string;
     readonly exportedEntityId: DomainEntityId<string>;

package/dist/domain/core/component/export-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const exportStateComponent=e.component("exportState").withState({type:"object",properties:{activeState:{type:"string"},exportedEntityId:{oneOf:[{type:"string"},{type:"null"}]}},required:["activeState","exportedEntityId"],additionalProperties:!1}).withWritableKeys(["activeState","exportedEntityId"]).build();export const isExportStateComponentSnapshot=e=>t(e,"singleton",exportStateComponent);export const isSystemExportStateComponentSnapshot=t(o,"singleton",exportStateComponent);

package/dist/domain/{components → core/component}/fullscreen-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from '../core/index.js';
+import type { EntityId } from '../model/index.js';
 export type FullscreenStateComponentState = {
     readonly enabled: boolean;
 };

package/dist/domain/core/component/fullscreen-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as e}from"../model/index.js";import{SystemComponentBuilder as t}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const fullscreenStateComponent=t.component("fullscreenState").withState({type:"object",properties:{enabled:{type:"boolean"}},required:["enabled"],additionalProperties:!1}).withWritableKeys(["enabled"]).build();export const isFullscreenStateComponentSnapshot=t=>e(t,"singleton",fullscreenStateComponent);export const isSystemFullscreenStateComponentSnapshot=e(o,"singleton",fullscreenStateComponent);

package/dist/domain/{components → core/component}/group-components-by-entity-id-and-name.d.ts

@@ -1,5 +1,4 @@
-import { type ComponentSnapshot, type SystemComponentTypeConstraint } from '../core/component.js';
-import type { EntityId } from '../core/model.js';
+import { type ComponentSnapshot, type EntityId, type SystemComponentTypeConstraint } from '../model/index.js';
 export type GroupedComponentSnapshots<COMPONENT_TYPE extends SystemComponentTypeConstraint> = {
     [NAME in COMPONENT_TYPE['name']]: ReadonlyArray<ComponentSnapshot<Extract<COMPONENT_TYPE, {
         name: NAME;

package/dist/domain/core/component/group-components-by-entity-id-and-name.js

@@ -0,0 +1 @@
+import{isArray as o,isShallowEqual as t}from"@salsita-ai/common/utils";import{areEqualComponentSnapshots as n,isEqualComponentSnapshot as e}from"../model/index.js";export const isEqualGroupedComponentSnapshots=(p,m)=>t(p,m,(t,p)=>t===p||void 0!==t&&void 0!==p&&(o(t)&&o(p)?n(t,p):!(o(t)||o(p))&&e(t,p)));export const groupComponentsByEntityIdAndName=o=>{let t=new Map;return o.forEach(o=>{let n=o.componentInstance.entityId,e=o.componentInstance.componentType.name,p=t.get(n);p||(p={},t.set(n,p));let m=p[e]??[];p[e]=m,m.push(o)}),t};

package/dist/domain/{components → core/component}/hover-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { DomainEntityId, EntityId } from '../core/model.js';
+import { type DomainEntityId, type EntityId } from '../model/index.js';
 export type HoverStateComponentState = {
     readonly hoveredEntityId: DomainEntityId<string> | null;
 };

package/dist/domain/core/component/hover-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const hoverStateComponent=e.component("hoverState").withState({type:"object",properties:{hoveredEntityId:{oneOf:[{type:"string"},{type:"null"}]}},required:["hoveredEntityId"],additionalProperties:!1,tsType:"HoverStateComponentState",import:[{module:"@salsita-ai/sdk/domain",member:"HoverStateComponentState"}]}).withWritableKeys(["hoveredEntityId"]).build();export const isHoverStateComponentSnapshot=e=>t(e,"singleton",hoverStateComponent);export const isSystemHoverStateComponentSnapshot=t(o,"singleton",hoverStateComponent);

package/dist/domain/core/component/index.d.ts

@@ -0,0 +1,18 @@
+export type * from './component-reader-types.js';
+export * from './debug-state-component.js';
+export * from './domain-component-optic.js';
+export * from './drag-state-component.js';
+export * from './export-state-component.js';
+export * from './fullscreen-state-component.js';
+export * from './group-components-by-entity-id-and-name.js';
+export * from './hover-state-component.js';
+export * from './legacy-filter.js';
+export * from './navigation-state-component.js';
+export * from './selection-state-component.js';
+export * from './system-component-builder.js';
+export * from './system-component-filter.js';
+export * from './system-virtual-entity.js';
+export * from './tool-state-component.js';
+export * from './updates.js';
+export * from './view-state-component.js';
+export * from './viewport-state-component.js';

package/dist/domain/core/component/index.js

@@ -0,0 +1 @@
+export*from"./debug-state-component.js";export*from"./domain-component-optic.js";export*from"./drag-state-component.js";export*from"./export-state-component.js";export*from"./fullscreen-state-component.js";export*from"./group-components-by-entity-id-and-name.js";export*from"./hover-state-component.js";export*from"./legacy-filter.js";export*from"./navigation-state-component.js";export*from"./selection-state-component.js";export*from"./system-component-builder.js";export*from"./system-component-filter.js";export*from"./system-virtual-entity.js";export*from"./tool-state-component.js";export*from"./updates.js";export*from"./view-state-component.js";export*from"./viewport-state-component.js";

package/dist/domain/{components → core/component}/legacy-filter.d.ts

@@ -1,22 +1,7 @@
-import type { SessionRole } from '@salsita-ai/contracts/api';
-import type { $DomainEntity, DomainEntity } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
-import { type IdOrWithId } from './system-component-filter.js';
-import type { Viewport } from './viewport-state-component.js';
-export type DeclarativeComponentSystemFilter = {
-    navigationStates?: string[];
-    selectedEntityIds?: readonly IdOrWithId[] | IdOrWithId;
-    hoveredEntityIds?: readonly IdOrWithId[] | IdOrWithId;
-    draggedEntityIds?: readonly IdOrWithId[] | IdOrWithId;
-    viewStates?: string[];
-    toolStates?: string[];
-    modes?: Array<'owner' | 'read' | 'finalize'>;
-    roles?: SessionRole[];
-    active?: boolean;
-    fullscreen?: boolean;
-    debug?: boolean;
-    viewports?: readonly Viewport[];
-};
+import type { $DomainEntity, DomainEntity } from '../model/index.js';
+import type { DomainState } from '../state/index.js';
+import { type ComponentSystemFilterProps } from './system-component-filter.js';
+export type DeclarativeComponentSystemFilter = Omit<ComponentSystemFilterProps, 'exportedEntityIds' | 'exportStates'>;
 export type ComponentSystemFilter = DeclarativeComponentSystemFilter | boolean;
 export declare const ComponentSystemFilterSchema: {
     readonly anyOf: [{

package/dist/domain/{components → core/component}/navigation-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from '../core/model.js';
+import { type EntityId } from '../model/index.js';
 export type NavigationStateComponentState = {
     readonly activeState: string;
     readonly historyStack?: string[];

package/dist/domain/core/component/navigation-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const navigationStateComponent=e.component("navigationState").withState({type:"object",properties:{activeState:{type:"string"},historyStack:{type:"array",items:{type:"string"}}},required:["activeState"],additionalProperties:!1}).withWritableKeys(["activeState","historyStack"]).build();export const isNavigationComponentSnapshot=e=>t(e,"singleton",navigationStateComponent);export const isSystemNavigationComponentSnapshot=t(o,"singleton",navigationStateComponent);

package/dist/domain/{components → core/component}/selection-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { DomainEntityId, EntityId } from '../core/model.js';
+import { type DomainEntityId, type EntityId } from '../model/index.js';
 export type SelectionStateComponentState = {
     readonly selectedEntityId: DomainEntityId<string>;
 };

package/dist/domain/core/component/selection-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const selectionStateComponent=e.component("selectionState").withState({type:"object",properties:{selectedEntityId:{type:"string"}},required:["selectedEntityId"],additionalProperties:!1,tsType:"SelectionStateComponentState",import:[{module:"@salsita-ai/sdk/domain",member:"SelectionStateComponentState"}]}).withWritableKeys(["selectedEntityId"]).build();export const isSelectionComponentSnapshot=e=>t(e,"singleton",selectionStateComponent);export const isSystemSelectionComponentSnapshot=t(o,"singleton",selectionStateComponent);

package/dist/domain/{components → core/component}/system-component-builder.d.ts

@@ -1,5 +1,4 @@
-import type { SystemComponentType } from '../core/component.js';
-import type { SchemaOfObject } from '../core/reflection.js';
+import type { SchemaOfObject, SystemComponentType } from '../model/index.js';
 export declare class SystemComponentBuilder<NAME extends string, COMPONENT_STATE extends Record<string, unknown>, WRITABLE_KEYS extends keyof COMPONENT_STATE> {
     private readonly name;
     private readonly writableKeys;

package/dist/domain/core/component/system-component-builder.js

@@ -0,0 +1 @@
+import e from"lodash-es/pick.js";import{getCommonPhxDefinitions as t}from"../model/index.js";import{extendedSchemaValidator as i}from"../schema/index.js";export class SystemComponentBuilder{name;writableKeys;jsonSchema;constructor(e,t,i){this.name=e,this.writableKeys=t,this.jsonSchema=i}static component(e){return new SystemComponentBuilder(e,[],{type:"object",properties:{},required:[],additionalProperties:!1})}withState(e){return new SystemComponentBuilder(this.name,[],e)}withWritableKeys(e){return new SystemComponentBuilder(this.name,e,this.jsonSchema)}build(){let s=t(),r={...this.jsonSchema,definitions:{...s,...this.jsonSchema.definitions}};return{name:this.name,writableKeys:this.writableKeys,schema:this.jsonSchema,validateState:i.compile(r),validateWritableState:i.compile({...r,properties:e(this.jsonSchema.properties,this.writableKeys),required:this.jsonSchema.required?.filter(e=>this.writableKeys.includes(e))})}}}

package/dist/domain/{components → core/component}/system-component-filter.d.ts

@@ -1,7 +1,7 @@
 import type { SessionRole } from '@salsita-ai/contracts/api';
-import type { AnonymousExpression, ExpressionContext } from '../core/expression.js';
-import type { DomainEntity, DomainEntityId } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
+import type { AnonymousExpression } from '../expression/index.js';
+import type { DomainEntity, DomainEntityId } from '../model/index.js';
+import type { DomainState } from '../state/index.js';
 import { type Viewport } from './viewport-state-component.js';
 export interface ComponentSystemFilterState {
     navigationState: string | undefined;
@@ -22,6 +22,12 @@ interface WithDomainEntityId {
     id: DomainEntityId<string>;
 }
 export type IdOrWithId = DomainEntityId<string> | WithDomainEntityId;
+/**
+ * The criteria a component filter can state, each with the value it is compared with. This is the
+ * one place that lists them: the filter an optic carries (`GradualComponentSystemFilter`), the
+ * filter `withGradualFilter` takes and the legacy `DeclarativeComponentSystemFilter` take their
+ * keys and value types from it.
+ */
 export type ComponentSystemFilterProps = {
     navigationStates?: string[];
     selectedEntityIds?: readonly IdOrWithId[] | IdOrWithId;
@@ -38,22 +44,21 @@ export type ComponentSystemFilterProps = {
     debug?: boolean;
     viewports?: readonly Viewport[];
 };
-export interface GradualComponentSystemFilter<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>> {
-    navigationStates: undefined | readonly string[] | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly string[] | undefined>;
-    selectedEntityIds: undefined | readonly IdOrWithId[] | IdOrWithId | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly IdOrWithId[] | IdOrWithId | undefined>;
-    hoveredEntityIds: undefined | readonly IdOrWithId[] | IdOrWithId | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly IdOrWithId[] | IdOrWithId | undefined>;
-    draggedEntityIds: undefined | readonly IdOrWithId[] | IdOrWithId | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly IdOrWithId[] | IdOrWithId | undefined>;
-    exportedEntityIds: undefined | readonly IdOrWithId[] | IdOrWithId | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly IdOrWithId[] | IdOrWithId | undefined>;
-    viewStates: undefined | readonly string[] | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly string[] | undefined>;
-    toolStates: undefined | readonly string[] | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly string[] | undefined>;
-    exportStates: undefined | readonly string[] | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly string[] | undefined>;
-    modes: undefined | ReadonlyArray<'owner' | 'read' | 'finalize'> | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, ReadonlyArray<'owner' | 'read' | 'finalize'> | undefined>;
-    roles: undefined | readonly SessionRole[] | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly SessionRole[] | undefined>;
-    active: undefined | boolean | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, boolean | undefined>;
-    fullscreen: undefined | boolean | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, boolean | undefined>;
-    debug: undefined | boolean | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, boolean | undefined>;
-    viewports: undefined | readonly Viewport[] | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, readonly Viewport[] | undefined>;
-}
+/**
+ * The value an optic's filter holds for one criterion: the value `ComponentSystemFilterProps`
+ * states for it, with an array read-only.
+ */
+type FilterCriterion<KEY extends keyof ComponentSystemFilterProps> = [
+    Required<ComponentSystemFilterProps>[KEY]
+] extends [ReadonlyArray<infer ITEM>] ? readonly ITEM[] : Required<ComponentSystemFilterProps>[KEY];
+/**
+ * The filter a component optic carries: every criterion of `ComponentSystemFilterProps`, each
+ * unset, a value, or an expression that yields the value for one entity. The criteria are
+ * evaluated one by one, and the first one that does not match ends the evaluation.
+ */
+export type GradualComponentSystemFilter<ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, CONTEXT_EXTENSION = unknown> = {
+    [KEY in keyof Required<ComponentSystemFilterProps>]: undefined | FilterCriterion<KEY> | AnonymousExpression<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA, ENTITIES, FilterCriterion<KEY> | undefined, CONTEXT_EXTENSION>;
+};
 export interface FilterMismatchReason {
     readonly modes?: ReadonlyArray<'owner' | 'read' | 'finalize'>;
     readonly roles?: readonly SessionRole[];
@@ -70,7 +75,20 @@ export interface FilterMismatchReason {
     readonly draggedEntityIds?: readonly IdOrWithId[] | IdOrWithId;
     readonly active?: boolean;
 }
-export declare const isComponentActive: <ENTITIES extends DomainEntity<string>, ALLOWED_ROOT_ENTITIES extends ENTITIES, PUBLISHED_DATA extends Record<string, unknown>, SESSION_DATA extends Record<string, unknown>, FRONTEND_DATA extends Record<string, unknown>, SELF extends ENTITIES>(filterState: ComponentSystemFilterState, filters: ReadonlyArray<GradualComponentSystemFilter<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>>, id: SELF['id'], domainState: DomainState<ENTITIES>, context: ExpressionContext<ENTITIES, ALLOWED_ROOT_ENTITIES, PUBLISHED_DATA, SESSION_DATA, FRONTEND_DATA>, reportReason?: boolean) => boolean | readonly FilterMismatchReason[];
+/**
+ * A filter as `isComponentActive` reads it: every criterion unset, a value, or an expression that
+ * is evaluated with the given id, state and context. A `GradualComponentSystemFilter` is one for
+ * the ids, the state and the expression context of its project.
+ */
+type EvaluableComponentSystemFilter<ID, STATE, CONTEXT> = {
+    readonly [KEY in keyof Required<ComponentSystemFilterProps>]: undefined | FilterCriterion<KEY> | {
+        readonly evaluate: (id: ID, domainState: STATE, context: CONTEXT) => FilterCriterion<KEY> | undefined;
+    };
+};
+export declare const isComponentActive: <ID, STATE, CONTEXT extends {
+    readonly mode: 'owner' | 'read' | 'finalize';
+    readonly role: SessionRole;
+}>(filterState: ComponentSystemFilterState, filters: ReadonlyArray<EvaluableComponentSystemFilter<ID, STATE, CONTEXT>>, id: ID, domainState: STATE, context: CONTEXT, reportReason?: boolean) => boolean | readonly FilterMismatchReason[];
 export declare const ComponentSystemFilterPropsSchema: {
     readonly tsType: 'ComponentSystemFilterProps';
     readonly import: [{

package/dist/domain/core/component/system-virtual-entity.js

@@ -0,0 +1 @@
+import{createVirtualEntityId as t}from"../model/index.js";export const systemVirtualEntityId=t("system");

package/dist/domain/{components → core/component}/tool-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from '../core/model.js';
+import { type EntityId } from '../model/index.js';
 export type ToolStateComponentState = {
     readonly activeState: string;
 };

package/dist/domain/core/component/tool-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as o}from"./system-component-builder.js";import{systemVirtualEntityId as e}from"./system-virtual-entity.js";export const toolStateComponent=o.component("toolState").withState({type:"object",properties:{activeState:{type:"string"}},required:["activeState"],additionalProperties:!1}).withWritableKeys(["activeState"]).build();export const isToolStateComponentSnapshot=o=>t(o,"singleton",toolStateComponent);export const isSystemToolStateComponentSnapshot=t(e,"singleton",toolStateComponent);

package/dist/domain/{components → core/component}/updates.d.ts

@@ -1,12 +1,13 @@
 import type { Localizable } from '@salsita-ai/common/utils';
-import type { ComponentInstance, StateOfComponent, SystemComponentType, SystemComponentTypeConstraint, WritableStateOfComponent } from '../core/component.js';
-import type { DomainEntity, EntityByType, EntityId } from '../core/model.js';
+import type { ComponentInstance, DomainEntity, EntityByType, EntityId, StateOfComponent, SystemComponentType, SystemComponentTypeConstraint, WritableStateOfComponent } from '../model/index.js';
 import type { OneComponentFilter } from './component-reader-types.js';
 export interface ComponentModification<COMPONENT_TYPE extends SystemComponentTypeConstraint> {
     kind: 'modifyComponent';
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     writableState: WritableStateOfComponent<COMPONENT_TYPE>;
     metadata?: Record<string, unknown>;
@@ -17,6 +18,8 @@ export interface EphemeralRecordModification<COMPONENT_TYPE extends SystemCompon
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     writableState: WritableStateOfComponent<COMPONENT_TYPE>;
 }
@@ -25,6 +28,8 @@ export interface EphemeralRecordCreation<COMPONENT_TYPE extends SystemComponentT
     entityId: EntityId;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     initialState: StateOfComponent<COMPONENT_TYPE>;
 }
@@ -34,6 +39,8 @@ export interface EphemeralRecordDeletion<COMPONENT_TYPE extends SystemComponentT
     componentInstance: ComponentInstance<COMPONENT_TYPE>;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export type DomainEntityStateDelta<ENTITY extends DomainEntity<string>> = Partial<Omit<ENTITY, 'id' | 'type'>>;
 export interface DomainEntityModification<ENTITY extends DomainEntity<string> = DomainEntity<string>> {
@@ -41,6 +48,8 @@ export interface DomainEntityModification<ENTITY extends DomainEntity<string> =
     entityId: ENTITY['id'];
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
     stateDelta: DomainEntityStateDelta<ENTITY>;
     origin?: ComponentModification<SystemComponentTypeConstraint>;
 }
@@ -55,6 +64,8 @@ export interface DomainEntityCreation<ENTITY extends DomainEntity<string>, PAREN
     collection?: string;
     parentId: PARENT['id'];
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export interface DomainEntityReplacement<ENTITY extends DomainEntity<string>> {
     kind: 'replaceDomainEntity';
@@ -63,12 +74,16 @@ export interface DomainEntityReplacement<ENTITY extends DomainEntity<string>> {
     updateTag: string;
     keepChildren: boolean;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export interface EntityDeletion<ENTITY extends DomainEntity<string>> {
     kind: 'deleteEntity';
     entityId: EntityId<ENTITY>;
     updateTag: string;
     hint?: Localizable;
+    /** What the assistant agent is told about this update instead of `hint`; `null` keeps the wording from it, and its change record then explains the change by `updateTag`. Never shown to the user. */
+    agentHint?: string | null;
 }
 export type DataUpdate<ENTITY extends DomainEntity<string>, PARENT extends DomainEntity<string>> = EphemeralRecordModification | EphemeralRecordCreation | EphemeralRecordDeletion | DomainEntityModification<ENTITY> | DomainEntityCreation<ENTITY, PARENT> | DomainEntityReplacement<ENTITY> | EntityDeletion<ENTITY>;
 export type StateUpdate<ENTITY extends DomainEntity<string>, PARENT extends DomainEntity<string>> = ComponentModification<SystemComponentTypeConstraint> | DataUpdate<ENTITY, PARENT>;

package/dist/domain/{components → core/component}/view-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from '../core/model.js';
+import { type EntityId } from '../model/index.js';
 export type ViewStateComponentState = {
     readonly activeState: string;
 };

package/dist/domain/core/component/view-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const viewStateComponent=e.component("viewState").withState({type:"object",properties:{activeState:{type:"string"}},required:["activeState"],additionalProperties:!1}).withWritableKeys(["activeState"]).build();export const isViewComponentSnapshot=e=>t(e,"singleton",viewStateComponent);export const isSystemViewComponentSnapshot=t(o,"singleton",viewStateComponent);

package/dist/domain/{components → core/component}/viewport-state-component.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId } from '../core/model.js';
+import { type EntityId } from '../model/index.js';
 /**
  * A responsive class the configurator container currently satisfies. The values mirror the
  * responsive flags computed by the UI layer from the theme breakpoints (`isPhone`, `isMobile`,

package/dist/domain/core/component/viewport-state-component.js

@@ -0,0 +1 @@
+import{isSnapshotInstance as t}from"../model/index.js";import{SystemComponentBuilder as e}from"./system-component-builder.js";import{systemVirtualEntityId as o}from"./system-virtual-entity.js";export const VIEWPORTS=["phone","mobile","tablet","desktop","landscape","portrait"];export const viewportStateComponent=e.component("viewportState").withState({type:"object",properties:{active:{oneOf:[{type:"array",items:{type:"string",enum:[...VIEWPORTS]}},{type:"null"}]}},required:["active"],additionalProperties:!1,tsType:"ViewportStateComponentState",import:[{module:"@salsita-ai/sdk/domain",member:"ViewportStateComponentState"}]}).withWritableKeys(["active"]).build();export const isViewportStateComponentSnapshot=e=>t(e,"singleton",viewportStateComponent);export const isSystemViewportStateComponentSnapshot=t(o,"singleton",viewportStateComponent);

package/dist/domain/core/data-schema/data-cell-value.d.ts

@@ -0,0 +1,4 @@
+import type { CellValue } from '@salsita-ai/contracts/webhook';
+export type DataCellValue = CellValue | null | {
+    readonly $lang: Record<string, string>;
+} | readonly CellValue[];

package/dist/domain/core/data-schema/data-schema-array-field.d.ts

@@ -0,0 +1,5 @@
+export interface DataSchemaArrayField {
+    readonly type: 'array';
+    readonly items: 'string' | 'number' | 'boolean';
+    readonly description?: string;
+}

package/dist/domain/core/data-schema/data-schema-field-object.d.ts

@@ -0,0 +1,4 @@
+import type { DataSchemaArrayField } from './data-schema-array-field.js';
+import type { DataSchemaLocalizedField } from './data-schema-localized-field.js';
+import type { DataSchemaPrimitiveField } from './data-schema-primitive-field.js';
+export type DataSchemaFieldObject = DataSchemaPrimitiveField | DataSchemaLocalizedField | DataSchemaArrayField;

package/dist/domain/core/data-schema/data-schema-field.d.ts

@@ -0,0 +1,2 @@
+import type { DataSchemaFieldObject } from './data-schema-field-object.js';
+export type DataSchemaField = 'string' | 'number' | 'boolean' | readonly ['string', 'null'] | readonly ['number', 'null'] | readonly ['boolean', 'null'] | DataSchemaFieldObject;