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

package/dist/domain/mocks/create-test-application-config.d.ts

@@ -0,0 +1,59 @@
+import type { TransformersConfig } from '../application/index.js';
+import type { ProjectModule } from '../domain-runtime/index.js';
+/**
+ * What a project's test adds to its generated application before it builds the config.
+ *
+ * Each option names a part of the application config: the test states what it wants in the
+ * application, not how the application is assembled.
+ */
+export interface TestApplicationOptions {
+    /**
+     * Component files added after the components the generated application already has, for example
+     * the `customComponentOptics` of `.phoenix/configurator-domain-code.js`, which the configurator and
+     * the webhooks add to the domain the generated `configuratorBuilder` describes.
+     */
+    readonly componentModules?: readonly ProjectModule[];
+    /**
+     * The transformers of the application: the `src/transformers/` files the test runs, and the
+     * entries of the spec's `transformers` section that select and order them. Replaces the
+     * transformers the generated application has.
+     */
+    readonly transformers?: TransformersConfig;
+    /**
+     * The tag of the custom element the application mounts as. Without it the config keeps the tag of
+     * the generated application, which is `salsita-configurator` unless the application names another.
+     */
+    readonly tag?: string;
+}
+/**
+ * The shape of a generated application export (`configuratorBuilder` of `.phoenix/domain.js`,
+ * `configuratorConfig` of `.phoenix/configurator-config.js`) that the helper reads. `CONFIG` is the
+ * application config the export builds, with the project's types, so the result needs no type argument.
+ */
+interface GeneratedApplication<CONFIG> {
+    withComponentOptics(componentModules: readonly ProjectModule[]): GeneratedApplication<CONFIG>;
+    withTransformers(importedTransformers: TransformersConfig['importedTransformers'], specTransformers: TransformersConfig['specTransformers']): GeneratedApplication<CONFIG>;
+    withWebComponentTag(tag: string): GeneratedApplication<CONFIG>;
+    buildConfig(): CONFIG;
+}
+/**
+ * Builds the application config of a project for its tests, from the generated application export
+ * the test imports and the parts the test adds. The config carries the project's types, so it goes
+ * straight into `createDomainRuntime`, `createMockDomainContext`, `createMockState` or a mounted
+ * custom element, and its `initialPublishedData`, `domain.presets` and domain factories are the ones
+ * the deployed application starts with.
+ *
+ * This is the way a project's test builds its application. Its call does not depend on how the SDK
+ * assembles an application, so a test written against it needs no change when that assembly changes.
+ *
+ * @example
+ * const config = createTestApplicationConfig(configuratorBuilder, {
+ *   componentModules: customComponentOptics,
+ *   transformers: {
+ *     importedTransformers: [{ origin: 'src/transformers/add-cooking-top.ts', exports: addCookingTop }],
+ *     specTransformers: [{ name: 'addCookingTop', priority: 30 }],
+ *   },
+ * })
+ */
+export declare const createTestApplicationConfig: <CONFIG>(application: GeneratedApplication<CONFIG>, options?: TestApplicationOptions) => CONFIG;
+export {};

package/dist/domain/mocks/create-test-application-config.js

@@ -0,0 +1 @@
+export const createTestApplicationConfig=(e,o={})=>{let{componentModules:r,transformers:t,tag:n}=o,i=e;return r&&(i=i.withComponentOptics(r)),t&&(i=i.withTransformers(t.importedTransformers,t.specTransformers)),void 0!==n&&(i=i.withWebComponentTag(n)),i.buildConfig()};

package/dist/domain/mocks/index.d.ts

@@ -4,3 +4,4 @@ export { createMockDomainContext, type MockTransformer } from './create-mock-dom
 export { createMockDomainRuntime } from './create-mock-domain-runtime.js';
 export { createMockSessionContext } from './create-mock-session-context.js';
 export { createMockDomainRuntimeServices } from './create-mock-domain-runtime-services.js';
+export { type TestApplicationOptions, createTestApplicationConfig } from './create-test-application-config.js';

package/dist/domain/mocks/index.js

@@ -1 +1 @@
-export{createMockDomain}from"./create-mock-domain.js";export{createMockState}from"./create-mock-state.js";export{createMockDomainContext}from"./create-mock-domain-context.js";export{createMockDomainRuntime}from"./create-mock-domain-runtime.js";export{createMockSessionContext}from"./create-mock-session-context.js";export{createMockDomainRuntimeServices}from"./create-mock-domain-runtime-services.js";
+export{createMockDomain}from"./create-mock-domain.js";export{createMockState}from"./create-mock-state.js";export{createMockDomainContext}from"./create-mock-domain-context.js";export{createMockDomainRuntime}from"./create-mock-domain-runtime.js";export{createMockSessionContext}from"./create-mock-session-context.js";export{createMockDomainRuntimeServices}from"./create-mock-domain-runtime-services.js";export{createTestApplicationConfig}from"./create-test-application-config.js";

package/dist/domain/projections/blender-projections/blender-projections.d.ts

@@ -1,7 +1,6 @@
 import type { BlenderLight } from '@salsita-ai/contracts/webhook';
-import type { DomainEntity, DomainState } from '../../core/index.js';
-import type { DomainContextSelectors } from '../../domain-runtime/domain-context/index.js';
-import type { DomainServicesSelectors } from '../../domain-runtime/domain-services/index.js';
+import { type DomainEntity, type DomainState } from '../../core/index.js';
+import type { DomainContextSelectors, DomainServicesSelectors } from '../../domain-runtime/index.js';
 import type { BlenderCamera, BlenderImageConfig, BlenderImageSize, BlenderSceneConfig, BlenderSceneObject, SceneEntityNode } from './types.js';
 /**
  * Constructor context of a `BlenderProjections`. It reaches its domain collaborators through the

package/dist/domain/projections/blender-projections/blender-projections.js

@@ -1 +1 @@
-import{Matrix4 as e}from"three";import{groupComponentsByEntityIdAndName as t}from"../../components/group-components-by-entity-id-and-name.js";import{resolveMorphTargetInfluences as n}from"../../scene/index.js";import{customSceneEntityComponent as r,hiddenEntityComponent as i,materialOverridePropertyTransitionComponent as o,materialOverrideTransformerComponent as s,sceneEntityAmbientLightComponent as a,sceneEntityBoxObjectComponent as c,sceneEntityDirectionalLightComponent as l,sceneEntityLocalMaterialOverrideComponent as m,sceneEntityMaterialOverrideComponent as d,sceneEntityObjectClipComponent as g,sceneEntityObjectComponent as p,sceneEntityObjectDecalComponent as h,sceneEntityObjectGroupComponent as f,sceneEntityObjectLocalMaterialOverrideComponent as y,sceneEntityObjectMaterialOverrideComponent as j,sceneEntityObjectPropertiesComponent as x,sceneEntityObjectRemoteMaterialOverrideComponent as u,sceneEntityObjectTextDecalComponent as S,sceneEntityObjectTransformerComponent as v,sceneEntityObjectTransmissiveMaterialOverrideComponent as b,sceneEntityPointLightComponent as _,sceneEntityPropertiesComponent as E,sceneEntityRectAreaLightComponent as O,sceneEntityRemoteMaterialOverrideComponent as N,sceneEntityRemoteObjectComponent as B,sceneEntitySpotLightComponent as I,sceneEntityTransmissiveMaterialOverrideComponent as w}from"../../system-components/index.js";import{createSceneObjectGroupTransformResolver as $}from"../common/scene-object-transform.js";import{reduceMaterialOverrides as L}from"../material-overrides.js";import{projectBlenderCamera as C}from"./camera.js";import{getBlenderObjectMaterialOverrides as T}from"./entity-overrides.js";import{projectBlenderLight as D}from"./lights.js";import{projectBlenderMaterialOverrides as P}from"./materials.js";import{getBlenderObjectTransform as M}from"./transforms.js";let U=e=>"fileUrl"in e,R=(e,t)=>`${e}_${t}`;export class BlenderProjections{_context;constructor(e){this._context=e}_readEntityComponents=(e,n)=>t(this._context.selectors.getComponentReader().readManyComponents({entityIds:[e],componentTypes:[r,i,E,B,p,c,N,m,d,w,x,f,j,y,u,b,S,h,v,g,s,o,_,I,l,a,O]},n)).get(e);_traverse=(e,t,r)=>{let i=this._readEntityComponents(e.id,r),o=[...i?.sceneEntityRemoteObject??[],...i?.sceneEntityObject??[],...i?.sceneEntityBoxObject??[]],s={worldMatrix:this._context.selectors.getPositionProjections().getEntityWorldMatrix(e.id,r,null)},a=(i?.hiddenEntity?.length??0)>0,c={id:e.id,parent:t,customEntity:i?.customSceneEntity?.[0]?.state.node,isHidden:a,overrideComponents:i,properties:s,sceneObjects:o.map(r=>{let o=i?.sceneEntityObjectProperties?.find(e=>e.componentInstance.instanceName===r.componentInstance.instanceName)?.state,s=i?.sceneEntityObjectTextDecal?.filter(e=>e.componentInstance.instanceName===r.componentInstance.instanceName),a=i?.sceneEntityObjectDecal?.filter(e=>e.componentInstance.instanceName===r.componentInstance.instanceName),c=i?.sceneEntityObjectTransformer?.filter(e=>e.state.target===r.componentInstance.instanceName),l=n(o?.morphTargetInfluences,t=>this._context.domainServicesSelectors.getLogger().warn(`Morph target "${t}" on object ${r.componentInstance.instanceName} of entity ${e.id} has scaleZero equal to scaleOne, so its influence is undefined and is exported to Blender as 0. Give scaleZero and scaleOne different values.`)),m=i?.sceneEntityObjectClip?.filter(e=>e.state.target===r.componentInstance.instanceName),{overrides:d,transformations:g,transitions:p}=T(i??{},t,r.componentInstance.instanceName);return{instanceName:r.componentInstance.instanceName,object:r.state,properties:o,morphTargetInfluences:l,textDecals:s,decals:a,materialOverrides:d,materialOverrideTransformations:g,materialOverridePropertyTransitions:p,objectTransformations:c,clips:m}}),nodes:[]};for(let t of e.nodes){let e=this._traverse(t.node,c,r);c.nodes.push(e)}return c};getSceneEntityTree=e=>{let{root:t}=this._context.selectors.getCompositionProjections().getTree(e);return this._traverse(t,null,e)};_getBlenderObjects=(t,n)=>{let r=this._context.selectors.getDimensionSystem().getDataDistanceUnit(t),i=[],o=t=>{if(t.isHidden)return;if(null!=t.customEntity)return void this._context.domainServicesSelectors.getLogger().warn(`Custom entity ${t.id} is not supported in Blender.`);let n=t.overrideComponents?.materialOverrideTransformer??[];n.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Entity ${t.id} has ${n.length} material override transformer(s), they are not applied in Blender. Set the final material values on the overrides active in the export state.`);let s=t.properties,a=$(t.overrideComponents?.sceneEntityObjectGroup?.map(e=>({instanceName:e.componentInstance.instanceName,state:e.state}))??[],r),c=new Map(t.sceneObjects.map(e=>[e,a(e.properties?.targetParentGroup,e.instanceName)]));for(let n of t.sceneObjects){let o=c.get(n);if(o?.visible===!1||n.properties?.visible===!1||n.properties?.rendered===!1)continue;if(!U(n.object)){this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} is not a remote object, it will not be rendered in Blender.`);continue}n.textDecals&&n.textDecals.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has text decals, they are not rendered in Blender.`),n.decals&&n.decals.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has decals, they are not rendered in Blender.`),n.objectTransformations&&n.objectTransformations.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has object transformers, they are not applied in Blender. Express the transform through sceneEntityObjectProperties or a sceneEntityObjectGroup active in the export state.`),n.clips&&n.clips.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has animation clips, they are not played in Blender.`);let a=n.object,{position:l,scale:m,rotation:d}=M(o?new e().multiplyMatrices(s.worldMatrix,o.matrix):s.worldMatrix,n.properties,a.dimensionUnit??r,r),g=L(n.materialOverrides??[]),p=P({logger:this._context.domainServicesSelectors.getLogger(),materialOverrides:g,objectInstanceName:n.instanceName,transitions:n.materialOverridePropertyTransitions??[]});i.push({id:R(t.id,n.instanceName),objectName:a.objectName,position:l,scale:m,rotation:d,morphTargetInfluences:n.morphTargetInfluences,materialOverrides:p})}for(let e of t.nodes)o(e)};return o(n),i};getBlenderObjects=e=>this._getBlenderObjects(e,this.getSceneEntityTree(e));_prepareExportState=(e,t,n)=>{let r=this._context.selectors.getNavigationSystem().getExportUpdate(t,n),i=this._context.selectors.getStoreSystem().prepareStateEmission([r],e,"staged");if(!i.validity.valid)throw this._context.domainServicesSelectors.getLogger().error(`Setting an export state to ${t} for entity ${n} resulted in an invalid state! Check if there isn't a transformer corrupting the state as a reaction to setting the export state.`,i),Error("Exported state is invalid!");return i.state};_getBlenderLights=(e,t)=>{let n=this._context.selectors.getDimensionSystem().getDataDistanceUnit(e),r=[],i=e=>{if(e.isHidden||null!=e.customEntity)return;let t=e.overrideComponents,o=t?.sceneEntityAmbientLight??[];for(let i of(o.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Entity "${e.id}" has ${o.length} ambient light component(s) which are not exported to Blender because Blender has no equivalent ambient light type. Use HDRI lighting or additional point/area lights instead.`),[...t?.sceneEntityPointLight??[],...t?.sceneEntitySpotLight??[],...t?.sceneEntityDirectionalLight??[],...t?.sceneEntityRectAreaLight??[]])){let t=D({entityId:e.id,entityWorldMatrix:e.properties.worldMatrix,snapshot:i,distanceUnit:n});null!=t?r.push(t):this._context.domainServicesSelectors.getLogger().warn(`Unknown light component type for ${i.componentInstance.instanceName}`)}for(let t of e.nodes)i(t)};return i(t),r};getBlenderLights=e=>this._getBlenderLights(e,this.getSceneEntityTree(e));getBlenderCamera=(e,t)=>C(e,t,{componentReader:this._context.selectors.getComponentReader(),dimensionSystem:this._context.selectors.getDimensionSystem(),positionProjections:this._context.selectors.getPositionProjections()});_getBlenderSceneConfigFromState=e=>{let t=this.getSceneEntityTree(e),n=this._getBlenderObjects(e,t),r=this._getBlenderLights(e,t);return{renderedEntities:n.map(e=>({id:e.id,type:"default",objectName:e.objectName,position:e.position,scale:e.scale,rotation:e.rotation,materialOverrides:e.materialOverrides,morphTargetInfluences:e.morphTargetInfluences})),lights:r.length>0?r:void 0}};getBlenderSceneConfig=(e,t,n)=>{let r=this._prepareExportState(e,t,n);return this._getBlenderSceneConfigFromState(r)};getBlenderImageConfig=(e,t,n,r)=>{let i=this._prepareExportState(e,t,n);return{width:r.width,height:r.height,...this._getBlenderSceneConfigFromState(i),camera:this.getBlenderCamera(i,r)}}}
+import{Matrix4 as e}from"three";import{groupComponentsByEntityIdAndName as t}from"../../core/index.js";import{resolveMorphTargetInfluences as n}from"../../scene/index.js";import{customSceneEntityComponent as r,hiddenEntityComponent as i,materialOverridePropertyTransitionComponent as o,materialOverrideTransformerComponent as s,sceneEntityAmbientLightComponent as a,sceneEntityBoxObjectComponent as c,sceneEntityDirectionalLightComponent as l,sceneEntityLocalMaterialOverrideComponent as m,sceneEntityMaterialOverrideComponent as d,sceneEntityObjectClipComponent as g,sceneEntityObjectComponent as p,sceneEntityObjectDecalComponent as h,sceneEntityObjectGroupComponent as f,sceneEntityObjectLocalMaterialOverrideComponent as y,sceneEntityObjectMaterialOverrideComponent as j,sceneEntityObjectPropertiesComponent as x,sceneEntityObjectRemoteMaterialOverrideComponent as S,sceneEntityObjectTextDecalComponent as u,sceneEntityObjectTransformerComponent as v,sceneEntityObjectTransmissiveMaterialOverrideComponent as b,sceneEntityPointLightComponent as _,sceneEntityPropertiesComponent as E,sceneEntityRectAreaLightComponent as O,sceneEntityRemoteMaterialOverrideComponent as N,sceneEntityRemoteObjectComponent as B,sceneEntitySpotLightComponent as I,sceneEntityTransmissiveMaterialOverrideComponent as w}from"../../system-components/index.js";import{createSceneObjectGroupTransformResolver as $}from"../common/scene-object-transform.js";import{reduceMaterialOverrides as L}from"../material-overrides.js";import{projectBlenderCamera as C}from"./camera.js";import{getBlenderObjectMaterialOverrides as T}from"./entity-overrides.js";import{projectBlenderLight as D}from"./lights.js";import{projectBlenderMaterialOverrides as P}from"./materials.js";import{getBlenderObjectTransform as M}from"./transforms.js";let U=e=>"fileUrl"in e,R=(e,t)=>`${e}_${t}`;export class BlenderProjections{_context;constructor(e){this._context=e}_readEntityComponents=(e,n)=>t(this._context.selectors.getComponentReader().readManyComponents({entityIds:[e],componentTypes:[r,i,E,B,p,c,N,m,d,w,x,f,j,y,S,b,u,h,v,g,s,o,_,I,l,a,O]},n)).get(e);_traverse=(e,t,r)=>{let i=this._readEntityComponents(e.id,r),o=[...i?.sceneEntityRemoteObject??[],...i?.sceneEntityObject??[],...i?.sceneEntityBoxObject??[]],s={worldMatrix:this._context.selectors.getPositionProjections().getEntityWorldMatrix(e.id,r,null)},a=(i?.hiddenEntity?.length??0)>0,c={id:e.id,parent:t,customEntity:i?.customSceneEntity?.[0]?.state.node,isHidden:a,overrideComponents:i,properties:s,sceneObjects:o.map(r=>{let o=i?.sceneEntityObjectProperties?.find(e=>e.componentInstance.instanceName===r.componentInstance.instanceName)?.state,s=i?.sceneEntityObjectTextDecal?.filter(e=>e.componentInstance.instanceName===r.componentInstance.instanceName),a=i?.sceneEntityObjectDecal?.filter(e=>e.componentInstance.instanceName===r.componentInstance.instanceName),c=i?.sceneEntityObjectTransformer?.filter(e=>e.state.target===r.componentInstance.instanceName),l=n(o?.morphTargetInfluences,t=>this._context.domainServicesSelectors.getLogger().warn(`Morph target "${t}" on object ${r.componentInstance.instanceName} of entity ${e.id} has scaleZero equal to scaleOne, so its influence is undefined and is exported to Blender as 0. Give scaleZero and scaleOne different values.`)),m=i?.sceneEntityObjectClip?.filter(e=>e.state.target===r.componentInstance.instanceName),{overrides:d,transformations:g,transitions:p}=T(i??{},t,r.componentInstance.instanceName);return{instanceName:r.componentInstance.instanceName,object:r.state,properties:o,morphTargetInfluences:l,textDecals:s,decals:a,materialOverrides:d,materialOverrideTransformations:g,materialOverridePropertyTransitions:p,objectTransformations:c,clips:m}}),nodes:[]};for(let t of e.nodes){let e=this._traverse(t.node,c,r);c.nodes.push(e)}return c};getSceneEntityTree=e=>{let{root:t}=this._context.selectors.getCompositionProjections().getTree(e);return this._traverse(t,null,e)};_getBlenderObjects=(t,n)=>{let r=this._context.selectors.getDimensionSystem().getDataDistanceUnit(t),i=[],o=t=>{if(t.isHidden)return;if(null!=t.customEntity)return void this._context.domainServicesSelectors.getLogger().warn(`Custom entity ${t.id} is not supported in Blender.`);let n=t.overrideComponents?.materialOverrideTransformer??[];n.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Entity ${t.id} has ${n.length} material override transformer(s), they are not applied in Blender. Set the final material values on the overrides active in the export state.`);let s=t.properties,a=$(t.overrideComponents?.sceneEntityObjectGroup?.map(e=>({instanceName:e.componentInstance.instanceName,state:e.state}))??[],r),c=new Map(t.sceneObjects.map(e=>[e,a(e.properties?.targetParentGroup,e.instanceName)]));for(let n of t.sceneObjects){let o=c.get(n);if(o?.visible===!1||n.properties?.visible===!1||n.properties?.rendered===!1)continue;if(!U(n.object)){this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} is not a remote object, it will not be rendered in Blender.`);continue}n.textDecals&&n.textDecals.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has text decals, they are not rendered in Blender.`),n.decals&&n.decals.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has decals, they are not rendered in Blender.`),n.objectTransformations&&n.objectTransformations.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has object transformers, they are not applied in Blender. Express the transform through sceneEntityObjectProperties or a sceneEntityObjectGroup active in the export state.`),n.clips&&n.clips.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Object ${n.instanceName} of entity ${t.id} has animation clips, they are not played in Blender.`);let a=n.object,{position:l,scale:m,rotation:d}=M(o?new e().multiplyMatrices(s.worldMatrix,o.matrix):s.worldMatrix,n.properties,a.dimensionUnit??r,r),g=L(n.materialOverrides??[]),p=P({logger:this._context.domainServicesSelectors.getLogger(),materialOverrides:g,objectInstanceName:n.instanceName,transitions:n.materialOverridePropertyTransitions??[]});i.push({id:R(t.id,n.instanceName),objectName:a.objectName,position:l,scale:m,rotation:d,morphTargetInfluences:n.morphTargetInfluences,materialOverrides:p})}for(let e of t.nodes)o(e)};return o(n),i};getBlenderObjects=e=>this._getBlenderObjects(e,this.getSceneEntityTree(e));_prepareExportState=(e,t,n)=>{let r=this._context.selectors.getNavigationSystem().getExportUpdate(t,n),i=this._context.selectors.getStoreSystem().prepareStateEmission([r],e,"staged");if(!i.validity.valid)throw this._context.domainServicesSelectors.getLogger().error(`Setting an export state to ${t} for entity ${n} resulted in an invalid state! Check if there isn't a transformer corrupting the state as a reaction to setting the export state.`,i),Error("Exported state is invalid!");return i.state};_getBlenderLights=(e,t)=>{let n=this._context.selectors.getDimensionSystem().getDataDistanceUnit(e),r=[],i=e=>{if(e.isHidden||null!=e.customEntity)return;let t=e.overrideComponents,o=t?.sceneEntityAmbientLight??[];for(let i of(o.length>0&&this._context.domainServicesSelectors.getLogger().warn(`Entity "${e.id}" has ${o.length} ambient light component(s) which are not exported to Blender because Blender has no equivalent ambient light type. Use HDRI lighting or additional point/area lights instead.`),[...t?.sceneEntityPointLight??[],...t?.sceneEntitySpotLight??[],...t?.sceneEntityDirectionalLight??[],...t?.sceneEntityRectAreaLight??[]])){let t=D({entityId:e.id,entityWorldMatrix:e.properties.worldMatrix,snapshot:i,distanceUnit:n});null!=t?r.push(t):this._context.domainServicesSelectors.getLogger().warn(`Unknown light component type for ${i.componentInstance.instanceName}`)}for(let t of e.nodes)i(t)};return i(t),r};getBlenderLights=e=>this._getBlenderLights(e,this.getSceneEntityTree(e));getBlenderCamera=(e,t)=>C(e,t,{componentReader:this._context.selectors.getComponentReader(),dimensionSystem:this._context.selectors.getDimensionSystem(),positionProjections:this._context.selectors.getPositionProjections()});_getBlenderSceneConfigFromState=e=>{let t=this.getSceneEntityTree(e),n=this._getBlenderObjects(e,t),r=this._getBlenderLights(e,t);return{renderedEntities:n.map(e=>({id:e.id,type:"default",objectName:e.objectName,position:e.position,scale:e.scale,rotation:e.rotation,materialOverrides:e.materialOverrides,morphTargetInfluences:e.morphTargetInfluences})),lights:r.length>0?r:void 0}};getBlenderSceneConfig=(e,t,n)=>{let r=this._prepareExportState(e,t,n);return this._getBlenderSceneConfigFromState(r)};getBlenderImageConfig=(e,t,n,r)=>{let i=this._prepareExportState(e,t,n);return{width:r.width,height:r.height,...this._getBlenderSceneConfigFromState(i),camera:this.getBlenderCamera(i,r)}}}

package/dist/domain/projections/blender-projections/camera.d.ts

@@ -1,6 +1,6 @@
 import type { DomainEntity, DomainState } from '../../core/index.js';
 import type { AnyDimensionSystem } from '../../domain-context/index.js';
-import type { AnyComponentReader } from '../../domain-runtime/domain-context/index.js';
+import type { AnyComponentReader } from '../../domain-runtime/index.js';
 import type { AnyPositionProjections } from '../position-projections.js';
 import type { BlenderCamera, BlenderImageSize } from './types.js';
 export interface BlenderCameraProjectionContext {
@@ -8,4 +8,4 @@ export interface BlenderCameraProjectionContext {
     readonly dimensionSystem: Pick<AnyDimensionSystem, 'getDataDistanceUnit'>;
     readonly positionProjections: Pick<AnyPositionProjections, 'getEntityWorldMatrix'>;
 }
-export declare const projectBlenderCamera: <ENTITIES extends DomainEntity<string>>(state: DomainState<ENTITIES>, imageSize: BlenderImageSize, context: BlenderCameraProjectionContext) => BlenderCamera;
+export declare const projectBlenderCamera: (state: DomainState<DomainEntity<string>>, imageSize: BlenderImageSize, context: BlenderCameraProjectionContext) => BlenderCamera;

package/dist/domain/projections/collision-projections.d.ts

@@ -1,6 +1,6 @@
 import { Matrix4, Mesh, Vector3 } from 'three';
 import { type DomainEntity, type DomainState, type EntityId } from '../core/index.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 import { type AnyCollisionGeometrySnapshot } from '../system-components/index.js';
 /**
  * DE-9IM-style classification of the spatial relationship between two

package/dist/domain/projections/composition-projections.d.ts

@@ -1,6 +1,6 @@
 import { type Localizable } from '@salsita-ai/common/utils';
 import { type DomainEntity, type DomainEntityId, type DomainState, type EntityId, type VirtualEntityId } from '../core/index.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 export declare class CompositionCycleError extends Error {
     constructor(entityId: DomainEntityId<string>);
 }

package/dist/domain/projections/composition-projections.js

@@ -1 +1 @@
-import{isEqualArray as t}from"@salsita-ai/common/utils";import{groupComponentsByEntityIdAndName as e}from"../components/group-components-by-entity-id-and-name.js";import{domainEntityTypeFromId as o,isVirtualEntityId as i}from"../core/index.js";import{composedOfComponent as n}from"../relations/composed-of.js";import{detailComponent as s,priceComponent as r}from"../system-components/index.js";export class CompositionCycleError extends Error{constructor(t){super(`Entity ${t} is part of a cycle or appears in two branches in the scene graph! This is not allowed, fix the domain relationships to have clear composition hierarchy!`)}}export class EntityNotPartOfCompositionTreeError extends Error{constructor(t){super(`Entity ${t} is not part of the composition tree. Add composition relations to the entity so every entity is descendant of the root entity!`)}}export class EntityCompositionNode{id;parent;nodes;constructor(t,e,o){this.id=t,this.parent=e,this.nodes=o}descendants=t=>(function* t(e,o){for(let i of e.nodes)o&&i.relation!==o||(yield i.node,yield*t(i.node))})(this,t);children=t=>(function*(t,e){for(let o of t.nodes)e&&o.relation!==e||(yield o.node)})(this,t);ancestors=()=>(function*(t){let e=t.parent;for(;e;)yield e,e=e.parent})(this)}export class CompositionProjections{_context;_weakCache=new WeakMap;_previousValue=null;constructor(t){this._context=t}_traverseComposition=(t,e,o,i,n,s)=>{let r=new EntityCompositionNode(t,e,[]);if(o.has(r))throw new CompositionCycleError(t);for(let e of(i.set(t,r),o.add(r),s??[]))if(e.componentInstance.entityId===t)for(let t of e.state.childEntityIds){let a=this._traverseComposition(t,r,o,i,n,s);r.nodes.push({node:a,relation:e.componentInstance.instanceName})}return r};getTree=e=>{let o=this._weakCache.get(e);if(void 0!==o)return o;let i=this._context.selectors.getComponentReader().readManyComponents({componentTypes:[n]},e);if(this._previousValue&&this._previousValue.rootEntityId===e.rootEntityId&&t(i,this._previousValue.components??[]))return this._weakCache.set(e,this._previousValue.value),this._previousValue.value;let s=new Map,r=this._traverseComposition(e.rootEntityId,null,new Set,s,e,i);for(let t of e.entities)if(void 0===s.get(t.id))throw new EntityNotPartOfCompositionTreeError(t.id);let a={map:s,root:r};return this._weakCache.set(e,a),this._previousValue={components:i,value:a,rootEntityId:e.rootEntityId},a};readBasicEntityInfo=(t,n)=>{let a=e(this._context.selectors.getComponentReader().readManyComponents({entityIds:[t],componentTypes:[s,r]},n)).get(t),l=i(t)?t.name:o(t);return{entityId:t,title:a?.detail?.[0]?.state.title??l,shortDescription:a?.detail?.[0]?.state.description,subtitle:a?.detail?.[0]?.state.subtitle,price:a?.price?.[0]?.state.price,thumbnailUrl:a?.detail?.[0]?.state.thumbnailUrl}}}
+import{isEqualArray as t}from"@salsita-ai/common/utils";import{composedOfComponent as e,domainEntityTypeFromId as o,groupComponentsByEntityIdAndName as i,isVirtualEntityId as n}from"../core/index.js";import{detailComponent as s,priceComponent as r}from"../system-components/index.js";export class CompositionCycleError extends Error{constructor(t){super(`Entity ${t} is part of a cycle or appears in two branches in the scene graph! This is not allowed, fix the domain relationships to have clear composition hierarchy!`)}}export class EntityNotPartOfCompositionTreeError extends Error{constructor(t){super(`Entity ${t} is not part of the composition tree. Add composition relations to the entity so every entity is descendant of the root entity!`)}}export class EntityCompositionNode{id;parent;nodes;constructor(t,e,o){this.id=t,this.parent=e,this.nodes=o}descendants=t=>(function* t(e,o){for(let i of e.nodes)o&&i.relation!==o||(yield i.node,yield*t(i.node))})(this,t);children=t=>(function*(t,e){for(let o of t.nodes)e&&o.relation!==e||(yield o.node)})(this,t);ancestors=()=>(function*(t){let e=t.parent;for(;e;)yield e,e=e.parent})(this)}export class CompositionProjections{_context;_weakCache=new WeakMap;_previousValue=null;constructor(t){this._context=t}_traverseComposition=(t,e,o,i,n,s)=>{let r=new EntityCompositionNode(t,e,[]);if(o.has(r))throw new CompositionCycleError(t);for(let e of(i.set(t,r),o.add(r),s??[]))if(e.componentInstance.entityId===t)for(let t of e.state.childEntityIds){let a=this._traverseComposition(t,r,o,i,n,s);r.nodes.push({node:a,relation:e.componentInstance.instanceName})}return r};getTree=o=>{let i=this._weakCache.get(o);if(void 0!==i)return i;let n=this._context.selectors.getComponentReader().readManyComponents({componentTypes:[e]},o);if(this._previousValue&&this._previousValue.rootEntityId===o.rootEntityId&&t(n,this._previousValue.components??[]))return this._weakCache.set(o,this._previousValue.value),this._previousValue.value;let s=new Map,r=this._traverseComposition(o.rootEntityId,null,new Set,s,o,n);for(let t of o.entities)if(void 0===s.get(t.id))throw new EntityNotPartOfCompositionTreeError(t.id);let a={map:s,root:r};return this._weakCache.set(o,a),this._previousValue={components:n,value:a,rootEntityId:o.rootEntityId},a};readBasicEntityInfo=(t,e)=>{let a=i(this._context.selectors.getComponentReader().readManyComponents({entityIds:[t],componentTypes:[s,r]},e)).get(t),l=n(t)?t.name:o(t);return{entityId:t,title:a?.detail?.[0]?.state.title??l,shortDescription:a?.detail?.[0]?.state.description,subtitle:a?.detail?.[0]?.state.subtitle,price:a?.price?.[0]?.state.price,thumbnailUrl:a?.detail?.[0]?.state.thumbnailUrl}}}

package/dist/domain/projections/constraint-projections.d.ts

@@ -1,5 +1,5 @@
 import type { DomainEntity, DomainState } from '../core/index.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 import { type SpatialPredicateName } from '../system-components/index.js';
 /**
  * Constructor context of `ConstraintProjections`. It carries no `selectors` member because every

package/dist/domain/projections/index.d.ts

@@ -5,7 +5,7 @@ export { CollisionProjections, type CollisionMesh, type Collision, type SpatialR
 export { ConstraintProjections, type AnyConstraintProjections } from './constraint-projections.js';
 export { CompositionProjections, type AnyCompositionProjections, EntityCompositionNode, CompositionCycleError, EntityNotPartOfCompositionTreeError, type CompositionTreeWithIndex, } from './composition-projections.js';
 export { SnappingProjections, type AnySnapMatch, type WorldSnapPoint, type SnapMatch, type FindSnapOptions, type WorldSnapEdge, type EdgeSnapMatch, type WorldSnapPlane, type PlaneSnapMatch, type WorldSnapAxis, type AxisSnapMatch, type AnySnappingProjections, } from './snapping-projections.js';
-export { ValidationProjections, type AnyValidationProjections, type ValidationProjectionsContext, type StateValidationResult, type SystemViolation, } from './validation-projections.js';
+export { ValidationProjections, type AnyValidationProjections, type ValidationProjectionsContext, type SystemViolation, } from './validation-projections.js';
 export { findBestPointSnap, findAllPointSnaps, findBestEdgeSnap, findBestPlaneSnap, findBestAxisSnap, snapScore, extractYRotationFromMatrix, type AutoRotateContext, } from './snap-matching.js';
 export { computeWorldMatrix, computeWorldSnapPoints, computeWorldSnapEdges, computeWorldSnapPlanes, computeWorldSnapAxes, toMmBounds, } from './snap-utils.js';
 export { ProjectedEntitiesProjections, type AnyProjectedEntitiesProjections } from './projected-entities-projections.js';

package/dist/domain/projections/position-projections.d.ts

@@ -1,6 +1,6 @@
 import { Euler, Matrix4, Quaternion, Vector3 } from 'three';
 import type { DomainEntity, DomainEntityId, DomainState } from '../core/index.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 /**
  * Override for an entity's position during an active drag or rotation.
  * This is a simplified view of the dragging state — only the fields

package/dist/domain/projections/projected-entities-projections.d.ts

@@ -1,6 +1,5 @@
-import type { DomainEntity, DomainEntityId } from '../core/model.js';
-import type { DomainState } from '../core/state.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainEntity, DomainEntityId, DomainState } from '../core/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 /**
  * Constructor context of `ProjectedEntitiesProjections`. It carries no `selectors` member because
  * every registry read is transitive through collaborators that own their own registry window. A

package/dist/domain/projections/snap-matching.d.ts

@@ -1,7 +1,6 @@
 import type { Matrix4 } from 'three';
 import { Vector3 } from 'three';
-import type { ComponentSnapshot } from '../core/component.js';
-import type { DomainEntity } from '../core/model.js';
+import type { ComponentSnapshot, DomainEntity } from '../core/index.js';
 import type { SnapAxisComponent, SnapEdgeComponent, SnapPlaneComponent, SnapPointComponent } from '../system-components/index.js';
 /**
  * Common fields shared by all world-space snap primitives (points, edges, planes, axes).

package/dist/domain/projections/snap-utils.d.ts

@@ -1,6 +1,5 @@
 import { type Euler, Matrix4, Vector3 } from 'three';
-import type { ComponentSnapshot } from '../core/component.js';
-import type { DomainEntity } from '../core/model.js';
+import type { ComponentSnapshot, DomainEntity } from '../core/index.js';
 import type { DimensionUnit } from '../dimensions/dimensions.js';
 import type { SnapAxisComponent, SnapEdgeComponent, SnapPlaneComponent, SnapPointComponent } from '../system-components/index.js';
 import type { SnapAxisComponentState } from '../system-components/snap-axis.js';

package/dist/domain/projections/snapping-projections.d.ts

@@ -1,5 +1,5 @@
 import { type DomainEntity, type DomainState, type EntityId } from '../core/index.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 import { type AnySnapMatch, type AxisSnapMatch, type EdgeSnapMatch, type FindSnapOptions, type PlaneSnapMatch, type SnapMatch, type WorldSnapAxis, type WorldSnapEdge, type WorldSnapPlane, type WorldSnapPoint } from './snap-matching.js';
 export type { AnySnapMatch, WorldSnapPoint, SnapMatch, FindSnapOptions, WorldSnapEdge, EdgeSnapMatch, WorldSnapPlane, PlaneSnapMatch, WorldSnapAxis, AxisSnapMatch, };
 /**

package/dist/domain/projections/validation-projections.d.ts

@@ -1,24 +1,7 @@
-import type { $DomainEntity, DomainEntity, DomainState } from '../core/index.js';
-import type { AngleDimensionViolation, DistanceDimensionViolation, GenericDimensionViolation } from '../domain-context/dimension-system/dimension-system.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
-import type { EntityViolation, ViolationTypesOf$Entity } from '../invariants/violation.js';
+import { type $DomainEntity, type DomainEntity, type DomainState, type StateValidationResult, type ViolationTypesOf$Entity } from '../core/index.js';
+import type { AngleDimensionViolation, DistanceDimensionViolation, GenericDimensionViolation } from '../domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 export type SystemViolation = AngleDimensionViolation | DistanceDimensionViolation | GenericDimensionViolation;
-export type StateValidationResult<ENTITIES extends DomainEntity<string>, VIOLATION_TYPE extends string> = {
-    readonly valid: true;
-    readonly severity: null;
-} | {
-    readonly valid: true;
-    readonly severity: 'warning' | 'notice';
-    readonly entityViolations: ReadonlyArray<EntityViolation<ENTITIES, VIOLATION_TYPE>>;
-} | {
-    readonly valid: false;
-    readonly severity: 'uncaught';
-    readonly error: Error;
-} | {
-    readonly valid: false;
-    readonly severity: 'fatal' | 'fixable';
-    readonly entityViolations: ReadonlyArray<EntityViolation<ENTITIES, VIOLATION_TYPE>>;
-};
 /**
  * Constructor context of `ValidationProjections`. Runtime dependencies are resolved through
  * selectors on every read so a hot-reloaded spec is observed without rebuilding the projections.

package/dist/domain/projections/validation-projections.js

@@ -1 +1 @@
-import{violationsComponent as t}from"../invariants/violation-component.js";import{compareSeverity as e}from"../invariants/violation.js";export class ValidationProjections{_context;constructor(t){this._context=t}validateState(o){let n=[],r=null;try{for(let i of(this._context.selectors.getDomain().validateExpressions(o),this._context.selectors.getComponentReader().readManyComponents({componentTypes:[t]},o)))i.state.violations.forEach(t=>{(null===r||0>e(t.severity,r))&&(r=t.severity),n.push({entityId:i.componentInstance.entityId,violation:t})});for(let{entityId:t,violation:i}of this._context.selectors.getDimensionSystem().validateState(o))(null===r||0>e(i.severity,r))&&(r=i.severity),n.push({entityId:t,violation:i});if(null===r)return{valid:!0,severity:null};if("fatal"===r||"fixable"===r)return{valid:!1,severity:r,entityViolations:n};return{valid:!0,severity:r,entityViolations:n}}catch(t){return{valid:!1,error:t instanceof Error?t:Error(`Unknown error occurred - ${String(t)}`),severity:"uncaught"}}}}
+import{compareSeverity as t,violationsComponent as e}from"../core/index.js";export class ValidationProjections{_context;constructor(t){this._context=t}validateState(r){let o=[],n=null;try{for(let i of(this._context.selectors.getDomain().validateExpressions(r),this._context.selectors.getComponentReader().readManyComponents({componentTypes:[e]},r)))i.state.violations.forEach(e=>{(null===n||0>t(e.severity,n))&&(n=e.severity),o.push({entityId:i.componentInstance.entityId,violation:e})});for(let{entityId:e,violation:i}of this._context.selectors.getDimensionSystem().validateState(r))(null===n||0>t(i.severity,n))&&(n=i.severity),o.push({entityId:e,violation:i});if(null===n)return{valid:!0,severity:null};if("fatal"===n||"fixable"===n)return{valid:!1,severity:n,entityViolations:o};return{valid:!0,severity:n,entityViolations:o}}catch(t){return{valid:!1,error:t instanceof Error?t:Error(`Unknown error occurred - ${String(t)}`),severity:"uncaught"}}}}

package/dist/domain/sketching/sketching-projections.d.ts

@@ -1,5 +1,5 @@
 import type { DomainEntity, DomainState, EntityId } from '../core/index.js';
-import type { DomainContextSelectors } from '../domain-runtime/domain-context/index.js';
+import type { DomainContextSelectors } from '../domain-runtime/index.js';
 import { type Shape, type Sketching, type SketchingPoint } from './sketching.js';
 /**
  * Constructor context of `SketchingProjections`. It carries no `selectors` member because every

package/dist/domain/spec/application/admin-pages-section.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `$adminPages` section of an admin spec file as it is written, which the parsed admin pages
+ * keep as their `spec`. `application-spec` exports it as `RawAdminPages`, and the application
+ * config takes it as `AdminPagesSpec`.
+ */
+export interface AdminPagesSection {
+    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;
+        };
+    }>;
+}

package/dist/domain/spec/application/admin-pages-section.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/application/admin-pages.d.ts

@@ -0,0 +1,26 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ComponentEntry } from '../components/index.js';
+import type { AdminPagesSection } from './admin-pages-section.js';
+/**
+ * The parsed admin pages of an admin spec: the `$adminPages` section as written, the components
+ * the pages attach, the items of the admin navigation and the navigation states the pages add.
+ */
+export type AdminPages = Branded<'AdminPages', {
+    readonly spec: AdminPagesSection;
+    readonly components: readonly ComponentEntry[];
+    readonly navigationItems: readonly AdminNavigationItem[];
+    readonly navigationStates: readonly string[];
+}>;
+interface AdminNavigationListItem {
+    readonly label: string;
+    readonly icon?: string;
+    readonly navigationStates: readonly string[];
+}
+interface AdminNestedNavigationListItem {
+    readonly label: string;
+    readonly icon?: string;
+    readonly items: ReadonlyArray<Omit<AdminNavigationListItem, 'icon'>>;
+}
+/** One item of the admin navigation: a list item, or a nested list of them. */
+export type AdminNavigationItem = AdminNavigationListItem | AdminNestedNavigationListItem;
+export {};

package/dist/domain/spec/application/admin-pages.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/application/admin-states.d.ts

@@ -0,0 +1,5 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { StateValue } from '../sections/index.js';
+export type AdminStates = Branded<'AdminStates', {
+    readonly navigationStates: readonly StateValue[];
+}>;

package/dist/domain/spec/application/admin-states.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/application/configurator-states.d.ts

@@ -0,0 +1,8 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { StateValue } from '../sections/index.js';
+export type ConfiguratorStates = Branded<'ConfiguratorStates', {
+    readonly navigationStates: readonly StateValue[];
+    readonly viewStates: readonly StateValue[];
+    readonly toolStates: readonly StateValue[];
+    readonly exportStates: readonly StateValue[];
+}>;

package/dist/domain/spec/application/configurator-states.js

@@ -0,0 +1 @@
+export{};

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

@@ -0,0 +1,5 @@
+export type * from './admin-pages.js';
+export type * from './admin-pages-section.js';
+export type * from './admin-states.js';
+export * from './application-instance.js';
+export type * from './configurator-states.js';

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

@@ -0,0 +1 @@
+export*from"./application-instance.js";

package/dist/domain/spec/components/bindings/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './read-binding.js';
+export type * from './write-binding.js';

package/dist/domain/spec/components/bindings/index.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/bindings/read-binding.d.ts

@@ -0,0 +1,13 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * A validated `$read` dependency found anywhere in the component props tree.
+ * Used for memoEval dependency tracking — the target becomes `self.target` in generated code.
+ * Field targets are validated against the entity shape; expression targets ($-prefixed)
+ * are accepted without validation (they may be inferred during Phase C).
+ */
+export type ComponentReadBinding = Branded<'ComponentReadBinding', {
+    /** The raw target string from `$read` (e.g. "height" or "$price"). */
+    readonly target: string;
+    /** Whether the target is an expression (starts with `$`) or a shape field. */
+    readonly isExpression: boolean;
+}>;

package/dist/domain/spec/components/bindings/read-binding.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/bindings/write-binding.d.ts

@@ -0,0 +1,32 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Runtime type assertion to emit in the write callback.
+ * Resolved from the target entity field's schema during parsing.
+ */
+export type AssertionKind = {
+    readonly kind: 'declaredType';
+    readonly typeName: string;
+} | {
+    readonly kind: 'declaredTypeId';
+    readonly referencedType: string;
+} | {
+    readonly kind: 'primitive';
+    readonly assertFn: 'assertString' | 'assertNumber' | 'assertBoolean';
+} | {
+    readonly kind: 'literal';
+    readonly value: null;
+} | {
+    readonly kind: 'anyOf';
+    readonly assertions: readonly AssertionKind[];
+} | {
+    readonly kind: 'none';
+};
+/**
+ * A validated `$write` or `$bind` mapping from a component state key to an entity field.
+ * Includes the resolved assertion kind for runtime type checking in the write callback.
+ */
+export type ComponentWriteBinding = Branded<'ComponentWriteBinding', {
+    readonly propKey: string;
+    readonly entityField: string;
+    readonly assertion: AssertionKind;
+}>;

package/dist/domain/spec/components/bindings/write-binding.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/component-entry.d.ts

@@ -0,0 +1,90 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { MemoEvalPlan, MemoEvalPlanInput } from '../expressions/index.js';
+import type { EntityOrAliasName, InstanceName } from '../model/index.js';
+import type { ComponentReadBinding, ComponentWriteBinding } from './bindings/index.js';
+import type { ComponentFilters } from './component-filters.js';
+import type { SdkCodeRef } from './sdk-code-ref.js';
+/**
+ * Root-level `$read` variant — the entire instance state is driven by a single
+ * `$read` at the root (components.md §"Root-Level $read"). No `resolvedProps`
+ * tree, no write bindings; the single validated `readBinding` carries the
+ * target name and codegen emits `.attach(self => self.${readBinding.target}, …)`
+ * without `memoEval`.
+ */
+export interface RootReadImplementation {
+    readonly kind: 'rootRead';
+    readonly readBinding: ComponentReadBinding;
+}
+/**
+ * Composite variant — per-property reads with optional writes. `resolvedProps`
+ * is the instance props tree with `$read`/`$bind` lowered to
+ * {@link ComponentPropTarget} structs; each entry in `readBindings` corresponds
+ * to one target referenced from the tree. Codegen walks the tree and emits
+ * `memoEval(self => [deps], (…params) => body)` when the tree has no inline
+ * code, or `self => (body)` when it does. `writeBindings` carry per-prop write
+ * targets — only valid on this variant (root-read never has writes).
+ */
+export interface CompositeImplementation {
+    readonly kind: 'composite';
+    readonly resolvedProps: Readonly<Record<string, MemoEvalPlanInput>>;
+    readonly readBindings: readonly ComponentReadBinding[];
+    readonly writeBindings: readonly ComponentWriteBinding[];
+}
+/**
+ * User-bound component — filters apply uniformly, read/write behavior is
+ * carried in the discriminated {@link RootReadImplementation} |
+ * {@link CompositeImplementation} union under `implementation`.
+ * Root-read instances cannot carry write bindings by construction.
+ *
+ * `plan` is the shared {@link MemoEvalPlan} consumed by both codegen and
+ * runtime to emit a `memoEval(…)` reader or a cached static reader. It
+ * subsumes the old rootRead special case — a rootRead
+ * instance is simply a plan with a single read dep + slot template.
+ */
+interface UserBoundImplementation {
+    readonly kind: 'userBound';
+    readonly filters: ComponentFilters;
+    readonly plan: MemoEvalPlan;
+    readonly implementation: RootReadImplementation | CompositeImplementation;
+}
+export type SdkFactoryParam = SdkCodeRef | string | number | boolean | null | readonly SdkFactoryParam[] | {
+    readonly [key: string]: SdkFactoryParam;
+};
+/**
+ * An SDK factory call — codegen emits the function name with params inlined,
+ * runtime calls the function with resolved params (e.g. entity reflections).
+ */
+export interface SdkFactory {
+    /** SDK function name to import and call (e.g. "createSingleReferenceRead"). */
+    readonly sdkFunction: string;
+    /** Positional params — string/number are quoted, SdkCodeRef emitted as variable references. */
+    readonly params: readonly SdkFactoryParam[];
+}
+/**
+ * SDK-provided component — generic factory-based attachment.
+ * The SDK provides read + write factory functions; codegen imports and calls them with params.
+ * The component type itself comes from `ComponentEntry.componentName`.
+ * Used for relation-derived components (reference, composition) and extensible for future SDK types.
+ */
+interface SdkImplementation {
+    readonly kind: 'sdk';
+    readonly filters: ComponentFilters;
+    /** Factory that produces the read function for `.attach(readFn, writeFn)`. */
+    readonly readFactory: SdkFactory;
+    /** Factory that produces the write function for `.attach(readFn, writeFn)`. */
+    readonly writeFactory: SdkFactory;
+}
+/** Discriminated union — each variant carries the concrete typed params its builder needs. */
+export type ComponentImplementation = UserBoundImplementation | SdkImplementation;
+/**
+ * A single component attachment on the domain spec.
+ * Shared structure for user-declared and SDK-provided (relation-derived) components.
+ */
+export type ComponentEntry = Branded<'ComponentEntry', {
+    readonly typeOrAlias: EntityOrAliasName;
+    readonly instanceName: InstanceName;
+    readonly isAlias: boolean;
+    readonly componentName: string;
+    readonly implementation: ComponentImplementation;
+}>;
+export {};

package/dist/domain/spec/components/component-entry.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/components/component-filter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A single filter criterion — static value, dynamic `$read` reference, or
+ * inline `$eval` expression evaluated against `self` at runtime.
+ *
+ * The `target` field on the `'dynamic'` variant is a bare name (matches the
+ * same pattern as prop-level reads); codegen emits `self.target`, runtime
+ * reads `self[target]`.
+ */
+export type FilterCriterion<T> = {
+    readonly kind: 'static';
+    readonly value: T;
+} | {
+    readonly kind: 'dynamic';
+    readonly target: string;
+} | {
+    readonly kind: 'eval';
+    readonly code: string;
+};
+/**
+ * Parsed component filter controlling when the component is active, as the application spec
+ * declares it under `$filter`; `application-spec` exports it as `ComponentFilter`. Two
+ * mutually-exclusive shapes:
+ *
+ * - `'gradual'` — zero or more per-criterion fields; compiles to one entry per
+ *   set key inside `.withGradualFilter({…})`. The preferred form.
+ * - `'root'` — the entire filter is a single `$read` at the root (legacy
+ *   form `$filter: { $read: '$x' }`); compiles to `.withFilter(self => (self.target))`.
+ *   Distinct codegen because the SDK's `withFilter` and `withGradualFilter`
+ *   methods have different evaluation semantics (whole-closure vs per-key).
+ *
+ * See `components.md §"Simple expression filter"` / `§"Declarative filter"`.
+ */
+export type SpecComponentFilter = {
+    readonly kind: 'gradual';
+    readonly navigationStates?: FilterCriterion<readonly string[]>;
+    readonly viewStates?: FilterCriterion<readonly string[]>;
+    readonly toolStates?: FilterCriterion<readonly string[]>;
+    readonly exportStates?: FilterCriterion<readonly string[]>;
+    readonly modes?: FilterCriterion<readonly string[]>;
+    readonly roles?: FilterCriterion<readonly string[]>;
+    readonly selectedEntityIds?: FilterCriterion<unknown>;
+    readonly hoveredEntityIds?: FilterCriterion<unknown>;
+    readonly draggedEntityIds?: FilterCriterion<unknown>;
+    readonly exportedEntityIds?: FilterCriterion<unknown>;
+    readonly active?: FilterCriterion<boolean>;
+    readonly fullscreen?: FilterCriterion<boolean>;
+    readonly debug?: FilterCriterion<boolean>;
+    readonly viewports?: FilterCriterion<unknown>;
+} | {
+    readonly kind: 'root';
+    readonly target: string;
+};
+/** Criterion field names on the gradual variant — used for parse and iteration. */
+export declare const FILTER_CRITERION_KEYS: readonly ["navigationStates", "viewStates", "toolStates", "exportStates", "modes", "roles", "selectedEntityIds", "hoveredEntityIds", "draggedEntityIds", "exportedEntityIds", "active", "fullscreen", "debug", "viewports"];

package/dist/domain/spec/components/component-filter.js

@@ -0,0 +1 @@
+export const FILTER_CRITERION_KEYS=["navigationStates","viewStates","toolStates","exportStates","modes","roles","selectedEntityIds","hoveredEntityIds","draggedEntityIds","exportedEntityIds","active","fullscreen","debug","viewports"];