lanka 1.3.0 → 2.0.1

package/dist/locator/scenario/lanka-scenario-locator/LankaScenarioLocator.d.ts

@@ -0,0 +1,60 @@
+import { I as ILankaScenario } from '../../../ILankaScenario-DQd9ZfUw.js';
+import { A as ALankaLocator } from '../../../ALankaLocator-BUCCz0Q5.js';
+
+/**
+ * Resolves scenarios by property name (camelCase) or scenario name
+ * (PascalCase).
+ *
+ * Looks in the registry, then in the self-registration pool, and failing both
+ * constructs the scenario from the consumer's barrel on first use.
+ */
+declare class LankaScenarioLocator extends ALankaLocator<ILankaScenario<unknown>> {
+    /**
+     * The registry is read LAZILY rather than in a field initialiser.
+     *
+     * The locator is constructed INSIDE `createLanka`, before the instance becomes
+     * active. A field initialiser would ask for the active instance at that moment
+     * and fail with "no instance yet" while the instance being created is on the
+     * stack. Deferred reading resolves it: by the first scenario resolution an
+     * active instance exists.
+     */
+    private get registry();
+    /**
+     * Every constructible class the consumer's barrel exports.
+     *
+     * Published so that this file stays the ONE module in the framework that reads
+     * `@lanka_di/Scenarios`. `LankaScenarioBootstrap` used to read it too, and
+     * that second reader is what made `lanka/scenario` — the entry a consumer's
+     * scenario class imports `ALankaScenario` from — part of the import cycle the
+     * inversion creates. A bundler is free to order the chunks behind that entry
+     * however it likes, and when it put the barrel first the consumer's class
+     * extended `undefined`. `lanka/locator` carries the cycle instead, and no
+     * scenario class imports it.
+     *
+     * Not a filter on "is a scenario": an export that is not a function has no
+     * chance of being one, and anything further is decided by CONSTRUCTING it,
+     * which is the caller's job and the only honest test.
+     *
+     * ## Why the values are widened to `unknown` first
+     *
+     * A type predicate has to be assignable to the type it narrows, and the type
+     * of what this reads is the CONSUMER'S — whatever their `Scenarios` barrel
+     * happens to export. A real scenario class is `typeof TheirScenario`, which
+     * carries the statics `ALankaScenario` declares, and `new () => ILankaScenario`
+     * has none of them: the predicate is not assignable to it, and the file does
+     * not compile in any project whose barrel has a scenario in it.
+     *
+     * It compiled here for one reason: this repository's fixture barrel says
+     * `export {}`, so `Object.values` is `never[]` and every predicate is
+     * vacuously assignable. `_playgrounds/node` is where it failed, because that
+     * is a barrel with a real class in it — the same blind spot, in the same
+     * shape, as the empty probe barrels that let the 2.0.0 chunk cycle ship.
+     *
+     * `unknown` is also what this honestly knows. The framework cannot see a
+     * consumer's types; it sees exports and asks whether each is a function.
+     */
+    getDeclaredScenarioClasses(): readonly (new () => ILankaScenario<unknown>)[];
+    constructor();
+}
+
+export { LankaScenarioLocator };

package/dist/locator/scenario/lanka-scenario-locator/LankaScenarioLocator.js

@@ -0,0 +1,12 @@
+import {
+  LankaScenarioLocator
+} from "../../../chunk-42CWYVZJ.js";
+import "../../../chunk-NWEHOMTS.js";
+import "../../../chunk-N3275IPH.js";
+import "../../../chunk-FII3PW2G.js";
+import "../../../chunk-7DQUF2QR.js";
+import "../../../chunk-XGMXT4XZ.js";
+export {
+  LankaScenarioLocator
+};
+//# sourceMappingURL=LankaScenarioLocator.js.map

package/dist/locator/scenario/lanka-scenario-locator/LankaScenarioLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/locator/shared-store/lanka-shared-store-locator/LankaSharedStoreLocator.d.ts

@@ -0,0 +1,22 @@
+import { A as ALankaLocator } from '../../../ALankaLocator-BUCCz0Q5.js';
+import { A as ALankaSharedStore } from '../../../ALankaSharedStore-B7uepuuk.js';
+import 'zustand/vanilla';
+
+type TSharedStoreState = object;
+/**
+ * LankaSharedStoreLocator configuration.
+ */
+interface ILankaSharedStoreLocatorConfig {
+    /** The module holding shared store classes — the consumer's barrel. */
+    sharedStoreIndexModule?: Record<string, unknown>;
+}
+/**
+ * Resolves shared stores by property name (camelCase) or class name
+ * (PascalCase), constructing them on first use and caching them.
+ */
+declare class LankaSharedStoreLocator extends ALankaLocator<ALankaSharedStore<TSharedStoreState>> {
+    private readonly sharedStoreIndexModule?;
+    constructor(config?: ILankaSharedStoreLocatorConfig);
+}
+
+export { type ILankaSharedStoreLocatorConfig, LankaSharedStoreLocator };

package/dist/locator/shared-store/lanka-shared-store-locator/LankaSharedStoreLocator.js

@@ -0,0 +1,9 @@
+import {
+  LankaSharedStoreLocator
+} from "../../../chunk-3R2NO47A.js";
+import "../../../chunk-JZJ6GXX3.js";
+import "../../../chunk-N3275IPH.js";
+export {
+  LankaSharedStoreLocator
+};
+//# sourceMappingURL=LankaSharedStoreLocator.js.map

package/dist/locator/shared-store/lanka-shared-store-locator/LankaSharedStoreLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/locator/singleton/lanka-singleton-locator/LankaSingletonLocator.d.ts

@@ -0,0 +1,30 @@
+import { A as ALankaLocator } from '../../../ALankaLocator-BUCCz0Q5.js';
+
+/**
+ * LankaSingletonLocator configuration.
+ */
+interface ILankaSingletonLocatorConfig {
+    /** The module holding singleton classes — the consumer's barrel. */
+    singletonIndexModule?: Record<string, unknown>;
+}
+/**
+ * Resolves singletons by property name (camelCase) or class name (PascalCase),
+ * constructing them on first use and caching them.
+ *
+ * A class arrives either from the consumer's barrel or registered by hand — the
+ * latter for tests and for objects that arrive already built.
+ */
+declare class LankaSingletonLocator extends ALankaLocator<unknown> {
+    private readonly singletonIndexModule?;
+    constructor(config?: ILankaSingletonLocatorConfig);
+    /**
+     * Creates a NEW service object, bypassing the locator's cache.
+     *
+     * For scopes: they take the class from here and set the lifetime themselves.
+     * The root cache is untouched — otherwise the first resolution inside a scope
+     * would replace the application's root object.
+     */
+    createScopedInstance(className: string, propertyName: string): unknown;
+}
+
+export { type ILankaSingletonLocatorConfig, LankaSingletonLocator };

package/dist/locator/singleton/lanka-singleton-locator/LankaSingletonLocator.js

@@ -0,0 +1,9 @@
+import {
+  LankaSingletonLocator
+} from "../../../chunk-24MUFFHF.js";
+import "../../../chunk-JZJ6GXX3.js";
+import "../../../chunk-N3275IPH.js";
+export {
+  LankaSingletonLocator
+};
+//# sourceMappingURL=LankaSingletonLocator.js.map

package/dist/locator/singleton/lanka-singleton-locator/LankaSingletonLocator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

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

@@ -1,6 +1,7 @@
-import { a as ILankaScenario, T as TLankaReplayRequest, b as ILankaEventMetadata, c as TLankaEventBusMiddleware, d as TLankaEventBusObserver, e as ILankaEventLog, I as ILankaScenarioVM } from '../ILankaScenarioVM-DpKFL3iE.js';
-export { f as ILankaEventBusOutcome, g as TLankaEventBusDecision } from '../ILankaScenarioVM-DpKFL3iE.js';
-export { I as ILankaScenarioMetadata } from '../ILankaScenarioMetadata-Dj4GCqmX.js';
+import { I as ILankaScenario, T as TLankaReplayRequest, a as ILankaEventMetadata, b as TLankaEventBusMiddleware, c as TLankaEventBusObserver, d as ILankaEventLog } from '../ILankaScenario-DQd9ZfUw.js';
+export { e as ILankaEventBusOutcome, f as TLankaEventBusDecision } from '../ILankaScenario-DQd9ZfUw.js';
+import { I as ILankaScenarioVM } from '../ILankaScenarioVM-DKwjbIRq.js';
+export { I as ILankaScenarioMetadata } from '../ILankaScenarioMetadata-BsDp0Bzm.js';
 
 /**
  * The base of a scenario — a named unit of coordination over the event bus.
@@ -223,6 +224,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,13 @@
 import {
   lankaScenarioBootstrap
-} from "../chunk-B7EYIAW7.js";
+} from "../chunk-MKKMTLOY.js";
 import {
   ALankaScenario,
   lankaEventBus
-} from "../chunk-O5ROO7QF.js";
-import "../chunk-C2HP7CRD.js";
-import "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+} from "../chunk-NWEHOMTS.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/stream/index.d.ts

@@ -1,19 +1,24 @@
-import { c as ILankaPlugin } from '../createLanka-NrlvN-WQ.js';
-import '../createLankaScope-BiFxNQgl.js';
-import '../LankaSharedStoreLocator-zS2kLu-S.js';
-import '../ALankaSharedStore-B7uepuuk.js';
-import 'zustand/vanilla';
-import '../activeRuntime-BYd2D6Lx.js';
-import '../ILankaScenarioVM-DpKFL3iE.js';
-import '../LankaScenarioLocator-CAENLhDO.js';
-import '../ILankaScenarioMetadata-Dj4GCqmX.js';
+import { c as ILankaPlugin } from '../createLanka-DvUGu9Hl.js';
+import '../createLankaScope-CVoV0EwO.js';
+import '../locator/singleton/lanka-singleton-locator/LankaSingletonLocator.js';
+import '../ALankaLocator-BUCCz0Q5.js';
+import '../activeRuntime-ByucLPhj.js';
+import '../ILankaScenario-DQd9ZfUw.js';
+import '../LankaScenarioVMRegistry-DySAOaj2.js';
+import '../ILankaScenarioVM-DKwjbIRq.js';
+import '../ILankaScenarioMetadata-BsDp0Bzm.js';
+import '../ILankaRuntimeConfig-Vl436GWK.js';
+import '../lankaHttpInFlight-Bk1eIuSx.js';
+import '../lankaRequestMiddleware-DAC5kCb7.js';
+import '../locator/gateway/lanka-gateway-locator/LankaGatewayLocator.js';
 import '../ALankaGateway-BrVPaZN5.js';
 import '../lankaStandardValidator-BUFnysK0.js';
 import '@standard-schema/spec';
 import '../ILankaFieldError-D5931-vT.js';
-import '../ILankaRuntimeConfig-Vl436GWK.js';
-import '../lankaHttpInFlight-Bk1eIuSx.js';
-import '../lankaRequestMiddleware-DAC5kCb7.js';
+import '../locator/scenario/lanka-scenario-locator/LankaScenarioLocator.js';
+import '../locator/shared-store/lanka-shared-store-locator/LankaSharedStoreLocator.js';
+import '../ALankaSharedStore-B7uepuuk.js';
+import 'zustand/vanilla';
 
 /**
  * What a subscriber is handed when a named event arrives.

package/dist/viewmodel/index.d.ts

@@ -1,8 +1,28 @@
-import { StoreApi, StateCreator, UseBoundStore } from 'zustand';
-import { a as ILankaScenario, T as TLankaReplayRequest, I as ILankaScenarioVM } from '../ILankaScenarioVM-DpKFL3iE.js';
+import { I as ILankaReadableVM } from '../ILankaReadableVM-BoPzHEPV.js';
+import { I as ILankaScenarioVM } from '../ILankaScenarioVM-DKwjbIRq.js';
+import { StoreApi, StateCreator } from 'zustand';
+import { I as ILankaScenario, T as TLankaReplayRequest } from '../ILankaScenario-DQd9ZfUw.js';
 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 +142,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 +186,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 +221,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 +273,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 +424,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 +451,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 +528,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 +610,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 };