@shopware-ag/dive 3.1.0 → 4.0.1

package/build/plugins/state/src/EngineGateway.d.ts

@@ -0,0 +1,98 @@
+import { DIVE, DIVERoot, DIVESceneObject } from '../../../index.ts';
+import { EntitySchema, MinimalSchema, PartialSchema } from '../types/index.ts';
+/**
+ * The scene properties that are not entities.
+ *
+ * They live on three different engine objects — scene, grid and floor — and
+ * used to be read and written in three places that had already drifted apart.
+ */
+export type SceneSettings = {
+    name: string;
+    backgroundColor: string;
+    gridEnabled: boolean;
+    floorEnabled: boolean;
+    floorColor: string;
+};
+/**
+ * What may be written back.
+ *
+ * Colours come out as hex strings but go in either way, because three accepts
+ * both and callers pass whatever they happen to hold.
+ */
+export type SceneSettingsPatch = Partial<Omit<SceneSettings, 'backgroundColor' | 'floorColor'> & {
+    backgroundColor: string | number;
+    floorColor: string | number;
+}>;
+/**
+ * #### EngineGateway
+ * is the single seam between the state plugin and the engine.
+ *
+ * The engine holds objects; it does not know what an entity, an action or a
+ * state is. Everything that turns entity data into scene objects passes through
+ * here.
+ *
+ * One direction only. Reports coming back the other way are `watchEntity`'s
+ * business — which is why this class holds no reference to the state and has no
+ * way to command it.
+ *
+ * It is not a facade over the engine API. It offers what the state layer
+ * needs, in the state layer's vocabulary: entities, scene settings, rendering.
+ *
+ * @module
+ */
+export declare class EngineGateway {
+    private readonly _engine;
+    /** id -> scene object, so lookups do not walk the tree. */
+    private readonly _entities;
+    constructor(engine: DIVE);
+    /** The scene root, for everything that needs the subtree as a whole. */
+    get root(): DIVERoot;
+    /**
+     * Resolves an entity id to its scene object.
+     *
+     * Backed by a map rather than a tree walk: this runs on every frame a gizmo
+     * is dragged, via `object-transform` -> `UPDATE_OBJECT` -> `updateEntity`,
+     * and a `traverse` visits every mesh of every loaded asset on the way.
+     */
+    findEntity(entity: MinimalSchema<EntitySchema>): DIVESceneObject | undefined;
+    /**
+     * Puts an empty scene object for this entity into the scene.
+     *
+     * Separate from {@link applyEntity} because of what happens in between:
+     * applying a model schema awaits the asset load, and `object-load` fires
+     * inside that await. Whoever wants to hear it has to be listening — and
+     * registered, or the report writes to an id the state does not know yet.
+     * One combined call left no moment for that.
+     *
+     * Synchronous, so nothing can slip in front of the caller either.
+     *
+     * @returns The scene object, or `undefined` for a state-only entity.
+     */
+    createEntity(entity: EntitySchema): DIVESceneObject | undefined;
+    /** Writes an entity's data onto the scene object created for it. */
+    applyEntity(sceneObject: DIVESceneObject, entity: PartialSchema): Promise<void>;
+    updateEntity(patch: PartialSchema): Promise<void>;
+    removeEntity(entity: MinimalSchema<EntitySchema>): void;
+    /** Forgets every scene object. Listener teardown belongs to the registry. */
+    dispose(): void;
+    readSceneSettings(): SceneSettings;
+    applySceneSettings(patch: SceneSettingsPatch): void;
+    startRendering(): Promise<void>;
+    registerTicker(ticker: Parameters<DIVE['clock']['addTicker']>[0]): void;
+    /**
+     * Builds the node for an entity by composing the components its type needs.
+     *
+     * This is the whole "which entity type means which capabilities" mapping.
+     * Note a `scene` light is not one component but two: a hemisphere and a
+     * directional one, each carrying its own intensity factor, which is what
+     * lets {@link _applyLight} stay free of per-type branching.
+     */
+    private _instantiate;
+    private _instantiateLight;
+    private _apply;
+    private _applyLight;
+    private _applyModel;
+    private _applyPrimitive;
+    private _applyGroup;
+    private _setParent;
+}

package/build/plugins/state/src/EntityRegistry.d.ts

@@ -0,0 +1,51 @@
+import { DIVESceneObject } from '../../../index.ts';
+import { EntitySchema, PartialSchema, RegisteredEntity } from '../types/index.ts';
+/**
+ * Holds every entity the state knows: its data, its scene object, and the
+ * teardown for the listeners on that object.
+ *
+ * The map itself never leaves this class. Actions get the registry and use
+ * `read` / `write` / `register` / `unregister`, so how an entity is stored stays
+ * a detail here — and `write` being the only way in means the vector-copy rule
+ * is enforced rather than remembered at each call site.
+ *
+ * @module
+ */
+export declare class EntityRegistry {
+    private readonly _entities;
+    /** How many entities are registered. */
+    get size(): number;
+    /** Every entity. */
+    read(): RegisteredEntity[];
+    /** One entity, or `undefined` if it is not registered. */
+    read(id: string): RegisteredEntity | undefined;
+    /**
+     * Patches an entity's data.
+     *
+     * Copies vectors on the way in. The engine reports them as live references
+     * into a buffer it reuses next frame, and `merge` assigns by reference when
+     * the target key is absent — so a moving object would otherwise keep
+     * rewriting its own stored transform.
+     *
+     * @param id - The entity to patch.
+     * @param patch - The fields to apply; anything absent stays as it is.
+     */
+    write(id: string, patch: PartialSchema): void;
+    /**
+     * Takes an entity in.
+     *
+     * @param schema - The entity data.
+     * @param node - Its scene object, absent for a state-only entity.
+     * @param unwatch - Drops the listeners on the node again.
+     */
+    register(schema: EntitySchema, node?: DIVESceneObject, unwatch?: () => void): void;
+    /**
+     * Drops an entity and the listeners on its node.
+     *
+     * @param id - The entity to drop.
+     * @returns Whether it was registered.
+     */
+    unregister(id: string): boolean;
+    /** Drops everything, listeners included. */
+    clear(): void;
+}

package/build/plugins/state/src/State.d.ts

@@ -5,24 +5,34 @@ export type ActionSubscriber<ActionType extends keyof ActionTypes> = (payload: A
 export type ActionUnsubscribe = () => void;
 export declare class State {
     private static __instances;
-    static get(id: string): State | undefined;
-    private _id;
-    get id(): string;
     private engine;
     private controller;
-    private _mediaCreator;
+    /** The only way from here into the engine, see {@link EngineGateway}. */
+    private gateway;
+    /**
+     * modules, each loaded on first use
+     * the promise is cached, not the instance, and stored before anything is
+     * awaited, or two callers in the same tick each build their own
+     */
+    private _mediaCreator?;
     private getMediaCreator;
-    private _arSystem;
+    private _arSystem?;
     private getARSystem;
-    private _assetExplorer;
+    private _assetExplorer?;
     private getAssetExporter;
-    private _animationSystem;
+    private _animationSystem?;
     private getAnimationSystem;
-    private _toolbox;
+    private _toolbox?;
     private getToolbox;
-    private registered;
+    /** Every entity this state holds. See {@link EntityRegistry}. */
+    private registry;
     private listeners;
     constructor(dive: DIVE, controller: OrbitController);
+    /**
+     * Tears this state down and forgets it.
+     *
+     * @returns Whether it was still registered.
+     */
     destroyInstance(): boolean;
     performAction<ActionType extends keyof ActionTypes>(action: ActionType, ...args: ActionPayload<ActionTypes[ActionType]> extends void ? [] : [ActionPayload<ActionTypes[ActionType]>]): ActionReturn<ActionTypes[ActionType]>;
     subscribe<ActionType extends keyof ActionTypes>(type: ActionType, listener: ActionSubscriber<ActionType>): ActionUnsubscribe;
@@ -30,6 +40,7 @@ export declare class State {
     private getDependencies;
 }
 export * from './ActionRegistry.ts';
+export * from './EngineGateway.ts';
 export * from './actions/index.ts';
 export * from '../types/index.ts';
 export type { ActionTypes };

package/build/plugins/state/src/actions/camera/computeencompassingview.d.ts

@@ -1,7 +1,7 @@
 import { Action } from '../action.ts';
 import { Vector3Like } from 'three/webgpu';
 import { ActionDependencies } from '../../../types/index.ts';
-export declare const ComputeEncompassingViewAction: new (payload: void, dependencies: Pick<ActionDependencies, "engine" | "controller">) => Action<void, Pick<ActionDependencies, "engine" | "controller">, {
+export declare const ComputeEncompassingViewAction: new (payload: void, dependencies: Pick<ActionDependencies, "gateway" | "controller">) => Action<void, Pick<ActionDependencies, "gateway" | "controller">, {
     position: Vector3Like;
     target: Vector3Like;
 }>;

package/build/plugins/state/src/actions/camera/movecamera.d.ts

@@ -10,7 +10,7 @@ export declare const MoveCameraAction: new (payload: {
     id: string;
     locked: boolean;
     duration: number;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine" | "controller" | "getAnimationSystem">) => Action<{
+}, dependencies: Pick<ActionDependencies, "registry" | "gateway" | "controller" | "getAnimationSystem">) => Action<{
     position: Vector3Like;
     target: Vector3Like;
     locked: boolean;
@@ -19,7 +19,7 @@ export declare const MoveCameraAction: new (payload: {
     id: string;
     locked: boolean;
     duration: number;
-}, Pick<ActionDependencies, "registered" | "engine" | "controller" | "getAnimationSystem">, Promise<{
+}, Pick<ActionDependencies, "registry" | "gateway" | "controller" | "getAnimationSystem">, Promise<{
     stop: () => void;
 }>>;
 declare global {

package/build/plugins/state/src/actions/media/generatemedia.d.ts

@@ -1,7 +1,7 @@
 import { Action } from '../action.ts';
 import { ActionDependencies } from '../../../types/index.ts';
 import { MediaGenerationByPosition, MediaGenerationById } from '../../../../mediacreator/index.ts';
-export declare const GenerateMediaAction: new (payload: MediaGenerationById | MediaGenerationByPosition, dependencies: Pick<ActionDependencies, "registered" | "getMediaCreator">) => Action<MediaGenerationById | MediaGenerationByPosition, Pick<ActionDependencies, "registered" | "getMediaCreator">, Promise<string>>;
+export declare const GenerateMediaAction: new (payload: MediaGenerationById | MediaGenerationByPosition, dependencies: Pick<ActionDependencies, "registry" | "getMediaCreator">) => Action<MediaGenerationById | MediaGenerationByPosition, Pick<ActionDependencies, "registry" | "getMediaCreator">, Promise<string>>;
 declare global {
     interface ActionTypes {
         GENERATE_MEDIA: typeof GenerateMediaAction;

package/build/plugins/state/src/actions/object/addobject.d.ts

@@ -1,7 +1,6 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
-export declare const AddObjectAction: new (payload: EntitySchema, dependencies: Pick<ActionDependencies, "registered" | "engine">) => Action<EntitySchema, Pick<ActionDependencies, "registered" | "engine">, Promise<import('../../../../../index.ts').DIVEModel | import('../../../../../index.ts').DIVEGroup | import('../../../../../index.ts').DIVEPrimitive | import('../../../../../index.ts').DIVELight | undefined>>;
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
+export declare const AddObjectAction: new (payload: EntitySchema, dependencies: Pick<ActionDependencies, "registry" | "dispatch" | "gateway">) => Action<EntitySchema, Pick<ActionDependencies, "registry" | "dispatch" | "gateway">, Promise<import('../../../../../index.ts').DIVENode | undefined>>;
 declare global {
     interface ActionTypes {
         ADD_OBJECT: typeof AddObjectAction;

package/build/plugins/state/src/actions/object/deleteobject.d.ts

@@ -1,11 +1,10 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
 export declare const DeleteObjectAction: new (payload: Partial<EntitySchema> & {
     id: string;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine">) => Action<Partial<EntitySchema> & {
+}, dependencies: Pick<ActionDependencies, "registry" | "gateway">) => Action<Partial<EntitySchema> & {
     id: string;
-}, Pick<ActionDependencies, "registered" | "engine">, void>;
+}, Pick<ActionDependencies, "registry" | "gateway">, void>;
 declare global {
     interface ActionTypes {
         DELETE_OBJECT: typeof DeleteObjectAction;

package/build/plugins/state/src/actions/object/deselectobject.d.ts

@@ -1,11 +1,10 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
 export declare const DeselectObjectAction: new (payload: Partial<EntitySchema> & {
     id: string;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine" | "getToolbox">) => Action<Partial<EntitySchema> & {
+}, dependencies: Pick<ActionDependencies, "registry" | "getToolbox">) => Action<Partial<EntitySchema> & {
     id: string;
-}, Pick<ActionDependencies, "registered" | "engine" | "getToolbox">, Promise<void>>;
+}, Pick<ActionDependencies, "registry" | "getToolbox">, Promise<void>>;
 declare global {
     interface ActionTypes {
         DESELECT_OBJECT: typeof DeselectObjectAction;

package/build/plugins/state/src/actions/object/dropit.d.ts

@@ -2,9 +2,9 @@ import { Action } from '../action.ts';
 import { ActionDependencies } from '../../../types/index.ts';
 export declare const DropItAction: new (payload: {
     id: string;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine">) => Action<{
+}, dependencies: Pick<ActionDependencies, "registry">) => Action<{
     id: string;
-}, Pick<ActionDependencies, "registered" | "engine">, void>;
+}, Pick<ActionDependencies, "registry">, void>;
 declare global {
     interface ActionTypes {
         DROP_IT: typeof DropItAction;

package/build/plugins/state/src/actions/object/getallobjects.d.ts

@@ -1,7 +1,6 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
-export declare const GetAllObjectsAction: new (payload: void, dependencies: Pick<ActionDependencies, "registered">) => Action<void, Pick<ActionDependencies, "registered">, Map<string, EntitySchema>>;
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
+export declare const GetAllObjectsAction: new (payload: void, dependencies: Pick<ActionDependencies, "registry">) => Action<void, Pick<ActionDependencies, "registry">, Map<string, EntitySchema>>;
 declare global {
     interface ActionTypes {
         GET_ALL_OBJECTS: typeof GetAllObjectsAction;

package/build/plugins/state/src/actions/object/getobjects.d.ts

@@ -1,11 +1,10 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
 export declare const GetObjectsAction: new (payload: {
     ids: string[];
-}, dependencies: Pick<ActionDependencies, "registered" | "engine">) => Action<{
+}, dependencies: Pick<ActionDependencies, "registry" | "gateway">) => Action<{
     ids: string[];
-}, Pick<ActionDependencies, "registered" | "engine">, EntitySchema[]>;
+}, Pick<ActionDependencies, "registry" | "gateway">, EntitySchema[]>;
 declare global {
     interface ActionTypes {
         GET_OBJECTS: typeof GetObjectsAction;

package/build/plugins/state/src/actions/object/index.d.ts

@@ -5,7 +5,6 @@ export * from './dropit.ts';
 export * from './getallobjects.ts';
 export * from './getobjects.ts';
 export * from './modelloaded.ts';
-export * from './placeonfloor.ts';
 export * from './selectobject.ts';
 export * from './setparent.ts';
 export * from './updateobject.ts';

package/build/plugins/state/src/actions/object/modelloaded.d.ts

@@ -2,9 +2,9 @@ import { Action } from '../action.ts';
 import { ActionDependencies } from '../../../types/index.ts';
 export declare const ModelLoadedAction: new (payload: {
     id: string;
-}, dependencies: Pick<ActionDependencies, "registered">) => Action<{
+}, dependencies: Pick<ActionDependencies, "registry">) => Action<{
     id: string;
-}, Pick<ActionDependencies, "registered">, void>;
+}, Pick<ActionDependencies, "registry">, void>;
 declare global {
     interface ActionTypes {
         MODEL_LOADED: typeof ModelLoadedAction;

package/build/plugins/state/src/actions/object/selectobject.d.ts

@@ -1,11 +1,10 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
 export declare const SelectObjectAction: new (payload: Partial<EntitySchema> & {
     id: string;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine" | "getToolbox">) => Action<Partial<EntitySchema> & {
+}, dependencies: Pick<ActionDependencies, "registry" | "getToolbox">) => Action<Partial<EntitySchema> & {
     id: string;
-}, Pick<ActionDependencies, "registered" | "engine" | "getToolbox">, Promise<void>>;
+}, Pick<ActionDependencies, "registry" | "getToolbox">, Promise<void>>;
 declare global {
     interface ActionTypes {
         SELECT_OBJECT: typeof SelectObjectAction;

package/build/plugins/state/src/actions/object/setparent.d.ts

@@ -1,6 +1,5 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
 export declare const SetParentAction: new (payload: {
     object: Partial<EntitySchema> & {
         id: string;
@@ -8,14 +7,14 @@ export declare const SetParentAction: new (payload: {
     parent: (Partial<EntitySchema> & {
         id: string;
     }) | null;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine">) => Action<{
+}, dependencies: Pick<ActionDependencies, "registry" | "gateway">) => Action<{
     object: Partial<EntitySchema> & {
         id: string;
     };
     parent: (Partial<EntitySchema> & {
         id: string;
     }) | null;
-}, Pick<ActionDependencies, "registered" | "engine">, void>;
+}, Pick<ActionDependencies, "registry" | "gateway">, void>;
 declare global {
     interface ActionTypes {
         SET_PARENT: typeof SetParentAction;

package/build/plugins/state/src/actions/object/updateobject.d.ts

@@ -1,11 +1,10 @@
 import { Action } from '../action.ts';
-import { ActionDependencies } from '../../../types/index.ts';
-import { EntitySchema } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
 export declare const UpdateObjectAction: new (payload: Partial<EntitySchema> & {
     id: string;
-}, dependencies: Pick<ActionDependencies, "registered" | "engine">) => Action<Partial<EntitySchema> & {
+}, dependencies: Pick<ActionDependencies, "registry" | "gateway">) => Action<Partial<EntitySchema> & {
     id: string;
-}, Pick<ActionDependencies, "registered" | "engine">, Promise<void>>;
+}, Pick<ActionDependencies, "registry" | "gateway">, Promise<void>>;
 declare global {
     interface ActionTypes {
         UPDATE_OBJECT: typeof UpdateObjectAction;

package/build/plugins/state/src/actions/renderer/startrender.d.ts

@@ -1,6 +1,6 @@
 import { Action } from '../action.ts';
 import { ActionDependencies } from '../../../types/index.ts';
-export declare const StartRenderAction: new (payload: void, dependencies: Pick<ActionDependencies, "engine">) => Action<void, Pick<ActionDependencies, "engine">, Promise<void>>;
+export declare const StartRenderAction: new (payload: void, dependencies: Pick<ActionDependencies, "gateway">) => Action<void, Pick<ActionDependencies, "gateway">, Promise<void>>;
 declare global {
     interface ActionTypes {
         START_RENDER: typeof StartRenderAction;

package/build/plugins/state/src/actions/scene/exportscene.d.ts

@@ -3,9 +3,9 @@ import { ActionDependencies } from '../../../types/index.ts';
 import { StateExportFileType } from '../../../types/StateExportFileType.ts';
 export declare const ExportSceneAction: new (payload: {
     type: keyof StateExportFileType;
-}, dependencies: Pick<ActionDependencies, "engine" | "getAssetExporter">) => Action<{
+}, dependencies: Pick<ActionDependencies, "gateway" | "getAssetExporter">) => Action<{
     type: keyof StateExportFileType;
-}, Pick<ActionDependencies, "engine" | "getAssetExporter">, Promise<ArrayBuffer | null>>;
+}, Pick<ActionDependencies, "gateway" | "getAssetExporter">, Promise<ArrayBuffer | null>>;
 declare global {
     interface ActionTypes {
         EXPORT_SCENE: typeof ExportSceneAction;

package/build/plugins/state/src/actions/scene/index.d.ts

@@ -1,4 +1,3 @@
 export * from './exportscene.ts';
-export * from './getallscenedata.ts';
 export * from './setbackground.ts';
 export * from './updatescene.ts';

package/build/plugins/state/src/actions/scene/setbackground.d.ts

@@ -2,9 +2,9 @@ import { Action } from '../action.ts';
 import { ActionDependencies } from '../../../types/index.ts';
 export declare const SetBackgroundAction: new (payload: {
     color: string | number;
-}, dependencies: Pick<ActionDependencies, "engine">) => Action<{
+}, dependencies: Pick<ActionDependencies, "gateway">) => Action<{
     color: string | number;
-}, Pick<ActionDependencies, "engine">, void>;
+}, Pick<ActionDependencies, "gateway">, void>;
 declare global {
     interface ActionTypes {
         SET_BACKGROUND: typeof SetBackgroundAction;

package/build/plugins/state/src/actions/scene/updatescene.d.ts

@@ -6,13 +6,13 @@ export declare const UpdateSceneAction: new (payload: Partial<{
     gridEnabled: boolean;
     floorEnabled: boolean;
     floorColor: string | number;
-}>, dependencies: Pick<ActionDependencies, "engine">) => Action<Partial<{
+}>, dependencies: Pick<ActionDependencies, "gateway">) => Action<Partial<{
     name: string;
     backgroundColor: string | number;
     gridEnabled: boolean;
     floorEnabled: boolean;
     floorColor: string | number;
-}>, Pick<ActionDependencies, "engine">, void>;
+}>, Pick<ActionDependencies, "gateway">, void>;
 declare global {
     interface ActionTypes {
         UPDATE_SCENE: typeof UpdateSceneAction;

package/build/plugins/state/src/actions/state/getstate.d.ts

@@ -1,6 +1,6 @@
 import { Action } from '../action.ts';
 import { ActionDependencies, StateData } from '../../../types/index.ts';
-export declare const GetStateAction: new (payload: void, dependencies: Pick<ActionDependencies, "registered" | "engine" | "controller">) => Action<void, Pick<ActionDependencies, "registered" | "engine" | "controller">, StateData>;
+export declare const GetStateAction: new (payload: void, dependencies: Pick<ActionDependencies, "registry" | "gateway" | "controller">) => Action<void, Pick<ActionDependencies, "registry" | "gateway" | "controller">, StateData>;
 declare global {
     interface ActionTypes {
         GET_STATE: typeof GetStateAction;

package/build/plugins/state/src/actions/state/setstate.d.ts

@@ -1,6 +1,6 @@
 import { Action } from '../action.ts';
 import { ActionDependencies, StateData } from '../../../types/index.ts';
-export declare const SetStateAction: new (payload: StateData, dependencies: Pick<ActionDependencies, "registered" | "engine" | "controller">) => Action<StateData, Pick<ActionDependencies, "registered" | "engine" | "controller">, Promise<(import('../../../../../index.ts').DIVEModel | import('../../../../../index.ts').DIVEGroup | import('../../../../../index.ts').DIVEPrimitive | import('../../../../../index.ts').DIVELight)[]>>;
+export declare const SetStateAction: new (payload: StateData, dependencies: Pick<ActionDependencies, "registry" | "dispatch" | "gateway" | "controller">) => Action<StateData, Pick<ActionDependencies, "registry" | "dispatch" | "gateway" | "controller">, Promise<import('../../../../../index.ts').DIVENode[]>>;
 declare global {
     interface ActionTypes {
         SET_STATE: typeof SetStateAction;

package/build/plugins/state/src/helpers/copyVectors/copyVectors.d.ts

@@ -0,0 +1,17 @@
+import { PartialSchema } from '../../../types/index.ts';
+/**
+ * Returns a patch whose vectors are plain copies.
+ *
+ * The engine reports transforms as live references into objects it keeps reusing
+ * — `DIVENode.onMove` hands out a scratch `Vector3` that the next frame
+ * overwrites. Storing such a reference means the stored schema silently changes
+ * underneath its owner, and `lodash.merge` assigns by reference whenever the
+ * target key is absent.
+ *
+ * This used to be `copyVec` at each call site in the gateway. It lives here
+ * because `EntityRegistry.write` is now the only way into a schema, so copying
+ * can happen once instead of being remembered every time.
+ *
+ * @param patch - The patch to sanitise.
+ */
+export declare const copyVectors: <T extends PartialSchema>(patch: T) => T;

package/build/plugins/state/src/helpers/updateParentLink/updateParentLink.d.ts

@@ -0,0 +1,29 @@
+import { DIVESceneObject } from '../../../../../index.ts';
+/**
+ * Draws the link from a group to one of its members, wherever the member is now.
+ *
+ * Grouping is a state-level idea: the engine only knows that some node holds a
+ * `MultiLineComponent`. So the knowledge that "a member gets a line from its
+ * parent's origin" lives here, and the line component stays a plain drawing
+ * primitive that watches nothing.
+ *
+ * Takes the **member**, not the group: it walks up to whatever the parent happens
+ * to be, so no caller has to know which group an object is in, or notice when
+ * that changes. Does nothing when the parent draws no lines, which is the normal
+ * case.
+ *
+ * Adding and moving are the same call, keyed by the member itself. The gateway
+ * used to keep a handle per member and had one method to add, one to remove and
+ * one to redraw — and the redraw had to be remembered at four call sites, where
+ * it was duly forgotten at one of them. There is nothing left to forget: a move
+ * arrives as `object-transform`, and this is idempotent.
+ *
+ * Only the drawing side lives here. Dropping a link is nobody's decision: the
+ * group hears `childremoved` and does it, which is set up where the line
+ * component is attached.
+ *
+ * @param sceneObject - The member whose link should be drawn.
+ *
+ * @module
+ */
+export declare const updateParentLink: (sceneObject: DIVESceneObject) => void;

package/build/plugins/state/src/helpers/watchEntity/watchEntity.d.ts

@@ -0,0 +1,30 @@
+import { DIVESceneObject } from '../../../../../index.ts';
+import { ActionDependencies, EntitySchema } from '../../../types/index.ts';
+/**
+ * Listens to what a scene object reports about itself and records it.
+ *
+ * ### Why this reports instead of commanding
+ *
+ * An object's own report travels engine -> state. The state is the destination,
+ * not the source, so the report writes the schema and announces the change —
+ * it does not run an action. Running `UPDATE_OBJECT` here, as this code used to,
+ * meant sending a command back to the very object that had just moved: the
+ * position went out through `updateEntity` -> `setPosition` -> `worldToLocal`
+ * onto the node it came from, once per frame of a gizmo drag.
+ *
+ * Subscribers see no difference. `dispatch` is the same call `performAction`
+ * makes at the end, with the same payload under the same name, so
+ * `state.subscribe('UPDATE_OBJECT', …)` keeps receiving gizmo positions.
+ *
+ * The closure is the routing: the id comes from the entity that was just
+ * created, so nothing has to search for it later, and the engine never learns
+ * that any of this happens.
+ *
+ * @param node - The scene object to listen to.
+ * @param entity - The entity it stands for.
+ * @param deps - EntityRegistry to write, dispatch to announce.
+ * @returns Drops every listener again. Belongs in the registry entry.
+ *
+ * @module
+ */
+export declare const watchEntity: (node: DIVESceneObject, entity: EntitySchema, { registry, dispatch }: Pick<ActionDependencies, "registry" | "dispatch">) => (() => void);

package/build/plugins/state/types/ActionTypes.d.ts

@@ -1,13 +1,28 @@
-import { DIVE, EntitySchema } from '../../../index.ts';
 import { OrbitController } from '../../orbitcontroller/index.ts';
+import { EngineGateway } from '../src/EngineGateway.ts';
+import { EntityRegistry } from '../src/EntityRegistry.ts';
 export type ActionPayload<T> = T extends new (payload: infer P, dependencies: infer D) => unknown ? P : never;
 export type ActionReturn<T> = T extends new (payload: infer P, dependencies: infer D) => infer ClassInstance ? ClassInstance extends {
     execute(): infer E;
 } ? E : never : never;
 export type ActionDeps<T> = T extends new (payload: unknown, dependencies: infer D) => unknown ? D extends Partial<ActionDependencies> ? D : never : never;
 export interface ActionDependencies {
-    registered: Map<string, EntitySchema>;
-    engine: DIVE;
+    /**
+     * Every entity the state holds: data, scene object, listener teardown.
+     *
+     * Handed out as an object rather than as a map, so that how an entity is
+     * stored stays the registry's business — and so `write` stays the only way
+     * into a schema, which is what makes the vector-copy rule enforceable.
+     */
+    registry: EntityRegistry;
+    /**
+     * Notifies subscribers without performing an action.
+     *
+     * This is what an engine-to-state report uses: the state already changed, so
+     * running a command would write it back into the engine it came from.
+     */
+    dispatch: <ActionType extends keyof ActionTypes>(type: ActionType, payload: ActionPayload<ActionTypes[ActionType]>) => void;
+    gateway: EngineGateway;
     controller: OrbitController;
     getAnimationSystem: () => Promise<import('../../animation/index.ts').AnimationSystem>;
     getARSystem: () => Promise<import('../../ar/index.ts').ARSystem>;

package/build/plugins/state/types/RegisteredEntity.d.ts

@@ -0,0 +1,27 @@
+import { DIVESceneObject } from '../../../index.ts';
+import { EntitySchema } from './schema/index.ts';
+/**
+ * One entity, as the state holds it: its data, the node representing it, and the
+ * teardown for the listeners attached to that node.
+ *
+ * Kept together on purpose. All three share an id, a lifetime and every state
+ * change, so splitting them across separate maps only created the chance for
+ * them to drift apart — and made every caller that needed two of them do two
+ * lookups.
+ *
+ * This shape is a state-internal detail. Actions reach it through
+ * {@link EntityRegistry}, never through the map, so it can change without
+ * touching them.
+ *
+ * @module
+ */
+export type RegisteredEntity = {
+    schema: EntitySchema;
+    /**
+     * Absent for a state-only entity. A camera has a position and a target, but
+     * nothing in the scene tree.
+     */
+    node?: DIVESceneObject;
+    /** Drops the listeners on {@link node}. Called by `EntityRegistry.unregister`. */
+    unwatch?: () => void;
+};