lanka 1.3.0 → 2.0.0

package/dist/index.js

@@ -6,28 +6,27 @@ import {
   createLanka,
   resetActiveLanka,
   startLanka
-} from "./chunk-UBGXDTXC.js";
-import "./chunk-B7EYIAW7.js";
-import "./chunk-5MAQVBI2.js";
-import "./chunk-O5ROO7QF.js";
+} from "./chunk-SZVNPK24.js";
+import "./chunk-UMPSR4US.js";
+import "./chunk-EYDMBI5T.js";
 import {
   createLankaHost
 } from "./chunk-XESL274R.js";
-import "./chunk-UJEC7H6K.js";
+import "./chunk-BHQ2SQ7P.js";
 import {
   LankaError
 } from "./chunk-G32H73QY.js";
 import {
   getLankaHost
-} from "./chunk-RKYKK6MN.js";
+} from "./chunk-RUMUFHSL.js";
 import "./chunk-UE2C76OR.js";
 import {
   lankaLogger
-} from "./chunk-C2HP7CRD.js";
+} from "./chunk-FII3PW2G.js";
 import {
   getLankaFlags
-} from "./chunk-D27MREPB.js";
-import "./chunk-BGVDPDX4.js";
+} from "./chunk-7DQUF2QR.js";
+import "./chunk-XGMXT4XZ.js";
 export {
   ALankaPlugin,
   LankaError,

package/dist/locator/index.d.ts

@@ -1,5 +1,5 @@
-export { I as ILankaScope } from '../createLankaScope-BiFxNQgl.js';
-export { a as ILankaLocator, I as ILankaLocatorConfig, c as ILankaSharedStoreLocatorConfig, d as ILankaSingletonLocatorConfig } from '../LankaSharedStoreLocator-zS2kLu-S.js';
+export { I as ILankaScope } from '../createLankaScope-DomNbEvb.js';
+export { b as ILankaLocator, I as ILankaLocatorConfig, c as ILankaSharedStoreLocatorConfig, d as ILankaSingletonLocatorConfig } from '../LankaSharedStoreLocator-jsz_gnUm.js';
 import * as GatewaysModule from '@lanka_di/Gateways';
 import { A as ALankaGateway } from '../ALankaGateway-BrVPaZN5.js';
 import * as ScenariosModule from '@lanka_di/Scenarios';

package/dist/locator/index.js

@@ -2,11 +2,11 @@ import {
   createLankaLocatorProxy,
   lankaSharedStores,
   lankaSingletons
-} from "../chunk-DTO27QFR.js";
+} from "../chunk-H5TIUKRK.js";
 import "../chunk-UE2C76OR.js";
 import {
   requireActiveRuntime
-} from "../chunk-BGVDPDX4.js";
+} from "../chunk-XGMXT4XZ.js";
 
 // src/locator/gateway/_facades/lanka-gateways/lankaGateways.ts
 var gatewayLocator = {

package/dist/logger/index.js

@@ -1,9 +1,9 @@
 import {
   LankaLogger,
   lankaLogger
-} from "../chunk-C2HP7CRD.js";
-import "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+} from "../chunk-FII3PW2G.js";
+import "../chunk-7DQUF2QR.js";
+import "../chunk-XGMXT4XZ.js";
 export {
   LankaLogger,
   lankaLogger

package/dist/mock/index.js

@@ -1,10 +1,10 @@
 import {
   lankaLogger
-} from "../chunk-C2HP7CRD.js";
+} from "../chunk-FII3PW2G.js";
 import {
   getLankaFlags
-} from "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+} from "../chunk-7DQUF2QR.js";
+import "../chunk-XGMXT4XZ.js";
 
 // src/_internal/sleep.ts
 var sleep = (ms = 300) => {

package/dist/scenario/index.d.ts

@@ -223,6 +223,31 @@ declare class LankaScenarioBootstrap {
      * registry already holds.
      */
     adoptDeclaredViewModels(): void;
+    /**
+     * Whether the ViewModel being built belongs to ONE scope.
+     *
+     * A module-level ViewModel is declared once and adopted by every instance
+     * ever created, which is what `declaredViewModels` is for and why it is never
+     * drained. A SCOPED one is the opposite: it belongs to the request that built
+     * it and to nothing after.
+     *
+     * Declaring one would be the defect this flag exists to prevent, and it is
+     * worth spelling out because nothing would look wrong. The array grows by an
+     * entry per request for the life of the process, and request N+1 ADOPTS
+     * request N's ViewModel — subscribing it to N+1's scenarios, so a dispatch
+     * runs N's handlers against N's gateways and writes into N's store. Every
+     * suite stays green and the leak is one user seeing another's board.
+     */
+    private isBuildingScoped;
+    /**
+     * Runs `build` with its declarations kept OUT of the process-wide list.
+     *
+     * Called by `resolveLankaVM` and by nothing else. A narrow seam rather than a
+     * parameter on every factory: the nine ways to build a ViewModel would each
+     * have to carry a flag through to `registerViewModel`, and eight of them have
+     * no business knowing what a scope is.
+     */
+    buildScoped<TBuilt>(build: () => TBuilt): TBuilt;
     registerViewModel(viewModel: ILankaScenarioVM, name?: string): void;
     private attachViewModel;
     /**

package/dist/scenario/index.js

@@ -1,13 +1,11 @@
-import {
-  lankaScenarioBootstrap
-} from "../chunk-B7EYIAW7.js";
 import {
   ALankaScenario,
-  lankaEventBus
-} from "../chunk-O5ROO7QF.js";
-import "../chunk-C2HP7CRD.js";
-import "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+  lankaEventBus,
+  lankaScenarioBootstrap
+} from "../chunk-EYDMBI5T.js";
+import "../chunk-FII3PW2G.js";
+import "../chunk-7DQUF2QR.js";
+import "../chunk-XGMXT4XZ.js";
 
 // src/scenario/_factories/create-lanka-scenario/createLankaScenario.ts
 var createLankaScenario = (config) => {

package/dist/scenario/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/scenario/_factories/create-lanka-scenario/createLankaScenario.ts"],"sourcesContent":["import { ALankaScenario } from \"../../_abstractions/lanka-scenario/ALankaScenario\";\nimport type { ILankaScenario } from \"../../_interfaces/ILankaScenario\";\n\n/** What a scenario is: three names and nothing else. */\nexport interface ILankaScenarioConfig {\n\t/** The scenario's name, and the key it is found by. */\n\tname: string;\n\t/** The event type on the bus. */\n\teventType: string;\n\t/** The event data's type name — for the bus metadata. */\n\tdataTypeName: string;\n\t/** Opts out of self-registration, as `skipAutoRegistration` does on a class. */\n\tskipAutoRegistration?: boolean;\n}\n\n/**\n * A scenario, without writing a class whose body is data.\n *\n * The class style is right where a scenario has behaviour — an `initialize` that\n * warms something, a `cleanup` that lets go. Most have neither: in the two\n * applications this framework grew out of, every scenario is a class holding\n * three `readonly` fields and nothing else.\n *\n * One implementation: this builds a subclass of `ALankaScenario`, so\n * self-registration, `trigger` and `subscribe` are the same code either way.\n */\nexport const createLankaScenario = <TData = void>(\n\tconfig: ILankaScenarioConfig,\n): ILankaScenario<TData> => {\n\tclass FunctionalScenario extends ALankaScenario<TData> {\n\t\tpublic static override skipAutoRegistration = config.skipAutoRegistration ?? false;\n\n\t\tpublic readonly name = config.name;\n\t\tpublic readonly eventType = config.eventType;\n\t\tpublic readonly dataTypeName = config.dataTypeName;\n\t}\n\n\treturn new FunctionalScenario();\n};\n"],"mappings":";;;;;;;;;;;;AA0BO,IAAM,sBAAsB,CAClC,WAC2B;AAAA,EAC3B,MAAM,2BAA2B,eAAsB;AAAA,IACtD,OAAuB,uBAAuB,OAAO,wBAAwB;AAAA,IAE7D,OAAO,OAAO;AAAA,IACd,YAAY,OAAO;AAAA,IACnB,eAAe,OAAO;AAAA,EACvC;AAEA,SAAO,IAAI,mBAAmB;AAC/B;","names":[]}
+{"version":3,"sources":["../../src/scenario/_factories/create-lanka-scenario/createLankaScenario.ts"],"sourcesContent":["import { ALankaScenario } from \"../../_abstractions/lanka-scenario/ALankaScenario\";\nimport type { ILankaScenario } from \"../../_interfaces/ILankaScenario\";\n\n/** What a scenario is: three names and nothing else. */\nexport interface ILankaScenarioConfig {\n\t/** The scenario's name, and the key it is found by. */\n\tname: string;\n\t/** The event type on the bus. */\n\teventType: string;\n\t/** The event data's type name — for the bus metadata. */\n\tdataTypeName: string;\n\t/** Opts out of self-registration, as `skipAutoRegistration` does on a class. */\n\tskipAutoRegistration?: boolean;\n}\n\n/**\n * A scenario, without writing a class whose body is data.\n *\n * The class style is right where a scenario has behaviour — an `initialize` that\n * warms something, a `cleanup` that lets go. Most have neither: in the two\n * applications this framework grew out of, every scenario is a class holding\n * three `readonly` fields and nothing else.\n *\n * One implementation: this builds a subclass of `ALankaScenario`, so\n * self-registration, `trigger` and `subscribe` are the same code either way.\n */\nexport const createLankaScenario = <TData = void>(\n\tconfig: ILankaScenarioConfig,\n): ILankaScenario<TData> => {\n\tclass FunctionalScenario extends ALankaScenario<TData> {\n\t\tpublic static override skipAutoRegistration = config.skipAutoRegistration ?? false;\n\n\t\tpublic readonly name = config.name;\n\t\tpublic readonly eventType = config.eventType;\n\t\tpublic readonly dataTypeName = config.dataTypeName;\n\t}\n\n\treturn new FunctionalScenario();\n};\n"],"mappings":";;;;;;;;;;AA0BO,IAAM,sBAAsB,CAClC,WAC2B;AAAA,EAC3B,MAAM,2BAA2B,eAAsB;AAAA,IACtD,OAAuB,uBAAuB,OAAO,wBAAwB;AAAA,IAE7D,OAAO,OAAO;AAAA,IACd,YAAY,OAAO;AAAA,IACnB,eAAe,OAAO;AAAA,EACvC;AAEA,SAAO,IAAI,mBAAmB;AAC/B;","names":[]}

package/dist/stream/index.d.ts

@@ -1,11 +1,11 @@
-import { c as ILankaPlugin } from '../createLanka-NrlvN-WQ.js';
-import '../createLankaScope-BiFxNQgl.js';
-import '../LankaSharedStoreLocator-zS2kLu-S.js';
+import { c as ILankaPlugin } from '../createLanka-x4oSMs7P.js';
+import '../createLankaScope-DomNbEvb.js';
+import '../LankaSharedStoreLocator-jsz_gnUm.js';
 import '../ALankaSharedStore-B7uepuuk.js';
 import 'zustand/vanilla';
-import '../activeRuntime-BYd2D6Lx.js';
+import '../activeRuntime-BO-qY0yY.js';
 import '../ILankaScenarioVM-DpKFL3iE.js';
-import '../LankaScenarioLocator-CAENLhDO.js';
+import '../LankaScenarioLocator-Dki2Es3O.js';
 import '../ILankaScenarioMetadata-Dj4GCqmX.js';
 import '../ALankaGateway-BrVPaZN5.js';
 import '../lankaStandardValidator-BUFnysK0.js';

package/dist/viewmodel/index.d.ts

@@ -1,8 +1,27 @@
-import { StoreApi, StateCreator, UseBoundStore } from 'zustand';
+import { I as ILankaReadableVM } from '../ILankaReadableVM-BoPzHEPV.js';
 import { a as ILankaScenario, T as TLankaReplayRequest, I as ILankaScenarioVM } from '../ILankaScenarioVM-DpKFL3iE.js';
+import { StoreApi, StateCreator } from 'zustand';
 import { A as ALankaSharedStore } from '../ALankaSharedStore-B7uepuuk.js';
 import { StoreApi as StoreApi$1 } from 'zustand/vanilla';
 
+/**
+ * A ViewModel that can also be written to from outside.
+ *
+ * The reading half plus the two members a host needs: the state a screen starts
+ * from, and a way to make server data that first state — which is what
+ * `hydrateLankaVM` does and the only reason writing is published at all.
+ *
+ * A view binding takes `ILankaReadableVM` instead. The narrower type is not
+ * politeness: a binding holding this one could write during a render, which is
+ * the defect no framework's scheduler survives.
+ */
+interface ILankaVM<TState extends object> extends ILankaReadableVM<TState> {
+    /** The state the ViewModel was built with, before anything wrote to it. */
+    getInitialState(): TState;
+    /** Writes state. Partial by default; `replace` swaps the whole object. */
+    setState(partial: TState | Partial<TState> | ((state: TState) => TState | Partial<TState>), replace?: false): void;
+}
+
 interface ILankaVMContext<TState, TGateways extends object, TServices extends object> {
     set: StoreApi<TState>["setState"];
     get: () => TState;
@@ -122,10 +141,10 @@ interface ILankaVMConfig<State extends object, Actions extends object, TGateways
  * through a getter — and warns with the ViewModel and key names. "Remember to
  * set the flag" is not a mechanism.
  */
-declare function createLankaVM<State extends object, Actions extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Record<string, never>>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
-declare function createLankaVM<State extends object, Actions extends object, Services extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Services>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
-declare function createLankaVM<State extends object, Actions extends object, TGateways extends object>(config: ILankaVMConfig<State, Actions, TGateways, Record<string, never>>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
-declare function createLankaVM<State extends object, Actions extends object, TGateways extends object, Services extends object>(config: ILankaVMConfig<State, Actions, TGateways, Services>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+declare function createLankaVM<State extends object, Actions extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Record<string, never>>): ILankaVM<State & Actions & ILankaScenarioVM>;
+declare function createLankaVM<State extends object, Actions extends object, Services extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Services>): ILankaVM<State & Actions & ILankaScenarioVM>;
+declare function createLankaVM<State extends object, Actions extends object, TGateways extends object>(config: ILankaVMConfig<State, Actions, TGateways, Record<string, never>>): ILankaVM<State & Actions & ILankaScenarioVM>;
+declare function createLankaVM<State extends object, Actions extends object, TGateways extends object, Services extends object>(config: ILankaVMConfig<State, Actions, TGateways, Services>): ILankaVM<State & Actions & ILankaScenarioVM>;
 
 declare function createLazyLankaVM<State extends object, Actions extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Record<string, never>>): TLazyLankaVM<ReturnType<typeof createLankaVM<State, Actions, Record<string, never>, Record<string, never>>>, State & Actions & ILankaScenarioVM>;
 declare function createLazyLankaVM<State extends object, Actions extends object, Services extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Services>): TLazyLankaVM<ReturnType<typeof createLankaVM<State, Actions, Record<string, never>, Services>>, State & Actions & ILankaScenarioVM>;
@@ -166,14 +185,18 @@ type TLankaStatelessVMConfig$1<Actions extends object, TGateways extends object
     onInit?: (ctx: ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>) => void;
     onReset?: (ctx: ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>) => void;
 };
-type TLankaStatelessVMHook<Actions extends object> = {
-    <TSelected = Actions & ILankaScenarioVM>(selector?: (full: Actions & ILankaScenarioVM) => TSelected): TSelected;
-    getState: () => Actions & ILankaScenarioVM;
-};
-declare function createStatelessLankaVM<Actions extends object>(config: TLankaStatelessVMConfig$1<Actions, Record<string, never>, Record<string, never>>): TLankaStatelessVMHook<Actions>;
-declare function createStatelessLankaVM<Actions extends object, Services extends object>(config: TLankaStatelessVMConfig$1<Actions, Record<string, never>, Services>): TLankaStatelessVMHook<Actions>;
-declare function createStatelessLankaVM<Actions extends object, TGateways extends object>(config: TLankaStatelessVMConfig$1<Actions, TGateways, Record<string, never>>): TLankaStatelessVMHook<Actions>;
-declare function createStatelessLankaVM<Actions extends object, TGateways extends object, Services extends object>(config: TLankaStatelessVMConfig$1<Actions, TGateways, Services>): TLankaStatelessVMHook<Actions>;
+/**
+ * @deprecated since 2.0.0 - use ILankaReadableVM, which is what a stateless
+ * ViewModel now IS: `createStatelessLankaVM` answers a readable ViewModel rather
+ * than a React hook, so the word "Hook" in this name no longer describes
+ * anything. The alias is kept because a published name is never removed, and it
+ * resolves to exactly the type the factory returns.
+ */
+type TLankaStatelessVMHook<Actions extends object> = ILankaReadableVM<Actions & ILankaScenarioVM>;
+declare function createStatelessLankaVM<Actions extends object>(config: TLankaStatelessVMConfig$1<Actions, Record<string, never>, Record<string, never>>): ILankaReadableVM<Actions & ILankaScenarioVM>;
+declare function createStatelessLankaVM<Actions extends object, Services extends object>(config: TLankaStatelessVMConfig$1<Actions, Record<string, never>, Services>): ILankaReadableVM<Actions & ILankaScenarioVM>;
+declare function createStatelessLankaVM<Actions extends object, TGateways extends object>(config: TLankaStatelessVMConfig$1<Actions, TGateways, Record<string, never>>): ILankaReadableVM<Actions & ILankaScenarioVM>;
+declare function createStatelessLankaVM<Actions extends object, TGateways extends object, Services extends object>(config: TLankaStatelessVMConfig$1<Actions, TGateways, Services>): ILankaReadableVM<Actions & ILankaScenarioVM>;
 
 type TLankaStatelessVMConfig<Actions extends object, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> = Omit<ILankaVMConfig<object, Actions, TGateways, Services>, "states"> & {
     states?: never;
@@ -197,11 +220,25 @@ interface ILankaSharedStoreVMContext<TStoreState extends object, TFullState exte
     trigger: <T>(scenario: ILankaScenario<T>, data?: T) => void;
 }
 
-type TLankaSharedStoreVMHook<TStoreState extends object, TActions extends object> = {
-    <TSelected = TStoreState & TActions & ILankaScenarioVM>(selector?: (full: TStoreState & TActions & ILankaScenarioVM) => TSelected): TSelected;
-    getState: () => TStoreState & TActions & ILankaScenarioVM;
+/**
+ * A ViewModel over a store somebody else owns.
+ *
+ * The port, plus the one member the shape genuinely adds: the SLICE, without the
+ * actions and scenario members composed onto it. A screen reads `getState`; code
+ * that has to reason about what is actually persisted — a hydration, a devtools
+ * panel, a second ViewModel over the same store — reads `getStoreState`.
+ */
+interface ILankaSharedStoreVM<TStoreState extends object, TActions extends object> extends ILankaReadableVM<TStoreState & TActions & ILankaScenarioVM> {
+    /** The shared store's own state, without this ViewModel's actions on top. */
     getStoreState: () => TStoreState;
-};
+}
+/**
+ * @deprecated since 2.0.0 - use ILankaSharedStoreVM, which is the same type
+ * under a name that is still true: `createSharedStoreLankaVM` answers a readable
+ * ViewModel rather than a React hook. The alias is kept because a published name
+ * is never removed.
+ */
+type TLankaSharedStoreVMHook<TStoreState extends object, TActions extends object> = ILankaSharedStoreVM<TStoreState, TActions>;
 interface ILankaSharedStoreScenarioBinding<TData, TStoreState extends object, TActions extends object, TStore extends ALankaSharedStore<TStoreState>, TGateways extends object, TServices extends object> {
     scenario: ILankaScenario<TData>;
     /**
@@ -235,10 +272,10 @@ interface ILankaSharedStoreVMConfig<TStoreState extends object, TActions extends
  * Factory for ViewModels backed by an external shared store instance.
  * Multiple ViewModels can be created on top of the same store instance.
  */
-declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Record<string, never>>): TLankaSharedStoreVMHook<StoreState, Actions>;
-declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Services>): TLankaSharedStoreVMHook<StoreState, Actions>;
-declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Record<string, never>>): TLankaSharedStoreVMHook<StoreState, Actions>;
-declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Services>): TLankaSharedStoreVMHook<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Record<string, never>>): ILankaSharedStoreVM<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Services>): ILankaSharedStoreVM<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Record<string, never>>): ILankaSharedStoreVM<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Services>): ILankaSharedStoreVM<StoreState, Actions>;
 
 /**
  * What a lazy shared-store ViewModel is, in the type as well as at runtime.
@@ -386,7 +423,7 @@ declare abstract class ALankaVM<State extends object, Actions extends object, TG
      */
     protected readonly enableAccessTrackingOptimization: boolean;
     /** Writes state. Available from `createActions` onwards, never before. */
-    protected set: StoreApi<State & Actions & ILankaScenarioVM>["setState"];
+    protected set: StoreApi$1<State & Actions & ILankaScenarioVM>["setState"];
     /** Reads state. The read a tracked hook cannot see — hence the switch above. */
     protected get: () => State & Actions & ILankaScenarioVM;
     /** Fires a scenario, which every ViewModel bound to it then hears. */
@@ -413,8 +450,16 @@ declare abstract class ALankaVM<State extends object, Actions extends object, TG
      * the wrong half. Canon: `skills/parity/SKILL.md` section 3a.
      */
     protected toStyleContext(): ILankaVMContext<State & Actions & ILankaScenarioVM, TGateways, Services>;
-    /** Builds the hook a screen calls. One store per call. */
-    build(): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+    /**
+     * Builds the ViewModel a screen reads. One store per call.
+     *
+     * What comes back is a STORE, not a hook: `getState`, `subscribe`, `setState`,
+     * plus the name and the tracking flag. A screen reaches it through its
+     * framework's binding — `useLankaVM(todoVM)` from `@lankajs/react`,
+     * `@lankajs/vue` and the rest of the shelf — and a program with no framework
+     * at all reads `getState()` and `subscribe()` directly.
+     */
+    build(): ILankaVM<State & Actions & ILankaScenarioVM>;
 }
 
 /**
@@ -482,8 +527,13 @@ declare abstract class ALankaStatelessVM<Actions extends object, TGateways exten
      * read. Canon: `skills/parity/SKILL.md` section 3a.
      */
     protected toStyleContext(): ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>;
-    /** Builds the hook a screen calls. One ViewModel per call. */
-    build(): TLankaStatelessVMHook<Actions>;
+    /**
+     * Builds the ViewModel a screen reads. One per call.
+     *
+     * What comes back answers the read half of the port and nothing more: there
+     * is no store to write to from outside, because there is no state to write.
+     */
+    build(): ILankaReadableVM<Actions & ILankaScenarioVM>;
 }
 
 /**
@@ -559,8 +609,68 @@ declare abstract class ALankaSharedStoreVM<StoreState extends object, Actions ex
  */
 declare const createLankaSharedStore: <TState extends object>(createInitialState: () => TState) => ALankaSharedStore<TState>;
 
+/**
+ * Keeps a selection's IDENTITY while nothing in it moved.
+ *
+ * ```ts
+ * const hold = createLankaShallowHold<{ title: string; status: string }>();
+ *
+ * // in any binding on the shelf
+ * const view = useLankaVM(missionVM, (state) => hold({
+ * 	title: state.title,
+ * 	status: state.status,
+ * }));
+ * ```
+ *
+ * ## What it is for
+ *
+ * A selector narrows what a reader depends on, and a selector that BUILDS its
+ * answer — `(state) => ({ a: state.a })`, `(state) => rows.filter(…)`, the shape
+ * a consumer reaches for first — cannot say so. Every binding compares the new
+ * selection with the last one by identity, and a fresh object is never identical
+ * to anything, so the reader wakes for every change in the ViewModel including
+ * the keys the selector exists to ignore. This is the comparison that makes the
+ * selection mean something.
+ *
+ * A selector answering a PRIMITIVE never needed it, which is what makes the cost
+ * quiet: the shape that is free and the shape that repaints on everything look
+ * the same on the page.
+ *
+ * ## Why it is in core and not in a binding
+ *
+ * It was `useLankaShallow` in `@lankajs/react` and nowhere else, and that made it
+ * a CAPABILITY one member of the shelf had and four did not. An idiom is a
+ * spelling; this changes which notifications reach a reader, and it encodes a
+ * policy — one level deep, own keys, `Object.is` — that five packages inventing
+ * separately would answer five ways. `skills/parity/SKILL.md` 3c: a binding that
+ * needs more than the port gives it has found something that belongs in core, for
+ * everybody.
+ *
+ * `useLankaShallow` keeps working and is now React's spelling over this. It has
+ * to exist there and cannot exist here: a React component re-runs the hook on
+ * every render, so the holding has to survive a render while the SELECTOR stays
+ * the current one — which is a `useRef`, and a ref is not something core can
+ * have.
+ *
+ * ## Why it holds a value and not a selector
+ *
+ * `createLankaShallowSelector(selector)` was the other shape and it cannot serve
+ * React: the wrapper would be rebuilt whenever the selector's identity moved, and
+ * an inline arrow is a new function every render, so the holding would reset
+ * before it ever held anything. Taking the VALUE puts the state in the only place
+ * every framework can keep it, and the extra line at a call site is the price of
+ * one name that works in all five rather than two that each work in some.
+ *
+ * ## One level, and it says so by failing
+ *
+ * Deeper would mean walking a state of unknown size on every read, which is the
+ * cost a reader took a selector to avoid. A selection with a nested object wants
+ * a selector that picks the leaves.
+ */
+declare const createLankaShallowHold: <TValue>() => ((next: TValue) => TValue);
+
 type TLankaVMStateCreator<TFullState> = StateCreator<TFullState, TLankaAnyMutators, TLankaAnyMutators>;
 
 type TLankaSharedStoreSetState<TState extends object> = (partial: TState | Partial<TState> | ((state: TState) => TState | Partial<TState>), replace?: boolean) => void;
 
-export { ALankaSharedStore, ALankaSharedStoreVM, ALankaStatelessVM, ALankaVM, type ILankaScenarioBinding, type ILankaSharedStoreScenarioBinding, type ILankaSharedStoreVMConfig, type ILankaSharedStoreVMContext, type ILankaStatelessScenarioBinding, type ILankaStatelessVMContext, type ILankaVMConfig, type ILankaVMContext, type TLankaAnyMutators, type TLankaSetState, type TLankaSharedStoreSetState, type TLankaSharedStoreVMHook, type TLankaStatelessVMConfig$1 as TLankaStatelessVMConfig, type TLankaStatelessVMHook, type TLankaVMEnhancer, type TLankaVMStateCreator, type TLazyLankaVM, type TUnknownLankaScenarioBinding, createLankaSharedStore, createLankaVM, createLazyLankaVM, createLazySharedStoreLankaVM, createLazyStatelessLankaVM, createSharedStoreLankaVM, createStatelessLankaVM };
+export { ALankaSharedStore, ALankaSharedStoreVM, ALankaStatelessVM, ALankaVM, ILankaReadableVM, type ILankaScenarioBinding, type ILankaSharedStoreScenarioBinding, type ILankaSharedStoreVM, type ILankaSharedStoreVMConfig, type ILankaSharedStoreVMContext, type ILankaStatelessScenarioBinding, type ILankaStatelessVMContext, type ILankaVM, type ILankaVMConfig, type ILankaVMContext, type TLankaAnyMutators, type TLankaSetState, type TLankaSharedStoreSetState, type TLankaSharedStoreVMHook, type TLankaStatelessVMConfig$1 as TLankaStatelessVMConfig, type TLankaStatelessVMHook, type TLankaVMEnhancer, type TLankaVMStateCreator, type TLazyLankaVM, type TUnknownLankaScenarioBinding, createLankaShallowHold, createLankaSharedStore, createLankaVM, createLazyLankaVM, createLazySharedStoreLankaVM, createLazyStatelessLankaVM, createSharedStoreLankaVM, createStatelessLankaVM };