lanka 1.2.0 → 2.0.0

package/dist/storage/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The half every engine has: four operations over string values.
+ *
+ * The clauses each one keeps are on `ILankaStorageAdapter`, together with the
+ * ones about how the two halves agree.
+ */
+interface ILankaAsyncStorageAdapter {
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Every key this store holds, when it can say.
+     *
+     * OPTIONAL, because a store need not be able to: a Cache Storage answers
+     * `Request` objects rather than the keys it was given, and a native bridge
+     * may answer nothing at all. A required member here would be a compile error
+     * in every adapter a consumer had already written.
+     *
+     * What it is for: `LankaCipher.clear()` removes what IT wrote instead of
+     * emptying the whole store — a store that cannot enumerate leaves it no
+     * choice but the latter.
+     */
+    keys?(): Promise<string[]>;
+}
+
+/**
+ * The half an engine only has when it answers without awaiting.
+ *
+ * ALL FOUR OR NONE. A caller narrows on three of them and then uses the fourth —
+ * an adapter declaring two type-checks and lies at the one call site that has no
+ * `await` to fall back to.
+ *
+ * What it is for: a store read during the first render. `localStorage` and MMKV
+ * can answer there; a bridge and a keychain cannot, and a screen that awaits its
+ * persisted state renders once without it and again with it — the flash a user
+ * reads as a bug.
+ */
+interface ILankaSyncStorageAdapter {
+    setItemSync(key: string, value: string): void;
+    getItemSync(key: string): string | null;
+    removeItemSync(key: string): void;
+    clearSync(): void;
+}
+
+/**
+ * What a key-value engine must do to stand behind `@lankajs/storage`.
+ *
+ * A PORT and nothing else: core declares the shape and ships no engine, because
+ * every platform already has one and they have nothing in common but these four
+ * operations. The asynchronous half is the whole port; the synchronous half is a
+ * capability an engine either has or does not, and a caller asks before using it
+ * rather than forcing the type.
+ *
+ * Implementations: `@lankajs/storage` carries three over what a browser already
+ * provides — `LankaWebStorageAdapter`, `LankaCacheStorageAdapter`,
+ * `LankaIndexedDbAdapter` — and `modules/storage-adapters/` holds one per engine
+ * an application installs. An application is free to write its own; the
+ * conformance suite in `@lankajs/tool-testing` is what says whether it is right.
+ *
+ * ## The clauses an implementation must keep
+ *
+ * Behaviour, not signatures, is where two honest adapters diverge, so each
+ * clause below is a promise and every one of them is an assertion in
+ * `lankaStorageAdapterConformance`. Run it; do not read a member's source.
+ *
+ * 1. Values are STRINGS, and what was written comes back byte for byte — `""`,
+ *    `"null"` and `"{}"` included. An engine that serialises on the way in and
+ *    parses on the way out answers a different type than it was given.
+ * 2. A missing key answers `null` — never `undefined`, never a throw.
+ * 3. `removeItem` of a key that is not there succeeds.
+ * 4. `setItem` over an existing key replaces it. Nothing merges.
+ * 5. `clear()` empties this adapter's NAMESPACE: afterwards every key it wrote
+ *    answers `null`.
+ * 6. `keys()` is optional. Declared, it answers what this adapter wrote and
+ *    nothing else — the namespace's keys, not the engine's.
+ * 7. An engine that can neither enumerate nor wipe keeps its own index of what
+ *    it wrote, so clause 5 holds anyway. `expo-secure-store` is the reason this
+ *    clause exists: it deletes a key it is handed and offers nothing else.
+ * 8. The synchronous half is all four methods or none.
+ * 9. The two halves see ONE store: a value written synchronously is visible to
+ *    `getItem`, and the other way round.
+ * 10. A value the engine cannot hold FAILS. Truncation surfaces a week later as
+ *     a token that decrypts to nonsense.
+ * 11. A key is used AS GIVEN. A key holding a space, a slash, a colon or a
+ *     letter outside ASCII names its own value, and `keys()` answers it in the
+ *     spelling it was written with. An engine that restricts which characters a
+ *     key may hold — `expo-secure-store` allows only letters, digits, `.`, `-`
+ *     and `_` — encodes on the way in and decodes on the way out, rather than
+ *     handing the caller a key it never wrote.
+ *
+ * ## Why `clear()` is required where `ILankaReadCache.cancel` is optional
+ *
+ * The port next door made an operation optional when three of four libraries
+ * could not do it. This one does the opposite with the same kind of gap, and the
+ * difference is what absence COSTS. A cache that cannot cancel finishes a
+ * request nobody wants: wasteful, never wrong. A store that cannot clear ends a
+ * session with the tokens still in it — which is not waste, it is the failure.
+ *
+ * So the cost lands on the one adapter with the problem (clause 7) instead of on
+ * every caller having to ask whether sign-out worked.
+ *
+ * ## What this port does not decide
+ *
+ * Three promises cannot be observed from inside an implementation and belong to
+ * whoever wires one:
+ *
+ * - **The adapter takes its engine, and never constructs it.** `new
+ *   LankaWebStorageAdapter(localStorage)` is the existing shape and the reason
+ *   an engine that only exists on a device is testable in node at all.
+ * - **An engine that encrypts itself is not encrypted twice.** MMKV with a key
+ *   and a keychain-backed store are already ciphertext at rest;
+ *   `LankaEncryptedStorage` over one of them is a second lock on one door.
+ * - **On a server the namespace is per REQUEST**, never a module-level
+ *   singleton — one process serves every reader.
+ */
+interface ILankaStorageAdapter extends ILankaAsyncStorageAdapter, Partial<ILankaSyncStorageAdapter> {
+}
+
+export type { ILankaAsyncStorageAdapter, ILankaStorageAdapter, ILankaSyncStorageAdapter };

package/dist/storage/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

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

package/dist/stream/index.d.ts

@@ -1,15 +1,16 @@
-import { c as ILankaPlugin } from '../createLanka-DI1CSy2Q.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-B336NU5I.js';
-import '../ILankaScenarioVM-DUsI-fSc.js';
-import '../LankaScenarioLocator-D86TIwiu.js';
-import '../ILankaScenarioMetadata-GoWWNEQL.js';
-import '../ALankaGateway-CkW1LbKE.js';
-import '../lankaStandardValidator-CL-r-zEV.js';
+import '../activeRuntime-BO-qY0yY.js';
+import '../ILankaScenarioVM-DpKFL3iE.js';
+import '../LankaScenarioLocator-Dki2Es3O.js';
+import '../ILankaScenarioMetadata-Dj4GCqmX.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';

package/dist/validation/index.d.ts

@@ -1,5 +1,6 @@
-export { I as ILankaValidator, T as TLankaSchema, a as TLankaValidationResult, l as lankaStandardValidator } from '../lankaStandardValidator-CL-r-zEV.js';
-import { L as LankaError } from '../LankaError-xpI-qj35.js';
+export { I as ILankaValidator, T as TLankaSchema, a as TLankaValidationResult, l as lankaStandardValidator } from '../lankaStandardValidator-BUFnysK0.js';
+import { L as LankaError } from '../LankaError-D6RWNyLM.js';
+import { I as ILankaFieldError } from '../ILankaFieldError-D5931-vT.js';
 import '@standard-schema/spec';
 
 /**
@@ -12,10 +13,12 @@ import '@standard-schema/spec';
  * that told a contract drift from a network failure by `kind` never saw it.
  *
  * `name` stays `LankaValidationError` and `status` stays 422: both are what a
- * consumer's existing `catch` reads, and the message list is `errors`.
+ * consumer's existing `catch` reads, and the message list is `errors`. The same
+ * issues arrive a second time as `fields`, with the path in segments, for the
+ * consumer that has an input to show each one at.
  */
 declare class LankaValidationError extends LankaError {
-    constructor(message: string, errors?: string[]);
+    constructor(message: string, errors?: string[], fields?: readonly ILankaFieldError[]);
     /** Always present here, unlike the base's optional list. */
     get errors(): string[];
 }

package/dist/validation/index.js

@@ -1,8 +1,10 @@
 import {
-  LankaValidationError,
   lankaStandardValidator
-} from "../chunk-GV5DUYST.js";
-import "../chunk-Q7QESSYF.js";
+} from "../chunk-HVSQOMRE.js";
+import {
+  LankaValidationError
+} from "../chunk-CRIRTOLB.js";
+import "../chunk-G32H73QY.js";
 export {
   LankaValidationError,
   lankaStandardValidator

package/dist/viewmodel/index.d.ts

@@ -1,8 +1,27 @@
-import { StoreApi, StateCreator, UseBoundStore } from 'zustand';
-import { a as ILankaScenario, T as TLankaReplayRequest, I as ILankaScenarioVM } from '../ILankaScenarioVM-DUsI-fSc.js';
+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.
@@ -257,6 +294,19 @@ declare function createLazySharedStoreLankaVM<StoreState extends object, Actions
 declare function createLazySharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Record<string, never>>): TLazySharedStoreReturn<StoreState, Actions, Store, TGateways, Record<string, never>>;
 declare function createLazySharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Services>): TLazySharedStoreReturn<StoreState, Actions, Store, TGateways, Services>;
 
+/**
+ * The lifecycle moments a ViewModel took, as the scenario binder receives them.
+ *
+ * A hook is present only when the ViewModel DECLARED it — overrode the method,
+ * or passed it in config. Bootstrap registers a ViewModel for the sake of these
+ * calls, so "declared" is what decides registration; a default no-op must not
+ * count, or every ViewModel would sit in the scenario registry for nothing.
+ */
+interface ILankaVMLifecycleHooks {
+    onInit?: () => void;
+    onReset?: () => void;
+}
+
 /**
  * What every ViewModel is given, and the two moments it is told about.
  *
@@ -281,10 +331,36 @@ declare abstract class ALankaVMEnvironment<TGateways extends object = Record<str
     protected createGateways(): TGateways;
     /** Non-gateway collaborators, built once per ViewModel. */
     protected createServices(): Services;
-    /** Runs after the scenarios are bound. */
+    /**
+     * Runs once the scenarios are bound: inside `startLanka()` for a ViewModel built
+     * at module level, inside `build()` for one built after bootstrap — in both
+     * cases before any screen has read the hook the build returns.
+     */
     protected onInit(): void;
-    /** Runs when the screen goes away, before the scenarios are unbound. */
+    /**
+     * Runs when the ViewModel is released — the framework instance disposed, or a
+     * lazy ViewModel's `dispose()` — after its scenario subscriptions are gone.
+     */
     protected onReset(): void;
+    /**
+     * The two moments above as the scenario binder receives them: present only
+     * where this ViewModel took them.
+     *
+     * Framework plumbing, not an extension point — a ViewModel overrides `onInit`
+     * and `onReset`, never this. Protected because the three bases call it, and
+     * named after `toStyleContext` for the same reason: a derived view of the
+     * protected surface, assembled by the framework.
+     *
+     * Why "took them" decides anything: `onInit` runs inside `initializeScenario`,
+     * which bootstrap alone calls, on the ViewModels registered with it.
+     * Registration used to follow scenario bindings only, so a ViewModel that
+     * overrode `onInit` and bound nothing was never initialised — silently. Now a
+     * declared hook registers the ViewModel too, and a default no-op must not
+     * count, or every ViewModel would sit in the scenario registry for nothing.
+     * The functional bridges declare theirs as own properties over these methods,
+     * which is what this comparison sees.
+     */
+    protected toLifecycleHooks(): ILankaVMLifecycleHooks;
 }
 
 /**
@@ -300,7 +376,9 @@ declare abstract class ALankaVMEnvironment<TGateways extends object = Record<str
  * value or a thunk, the class supplies by overriding a method of the same name —
  * `states`, `scenarioHandlers`, `enhancers`, `onInit`, `onReset` — with the two
  * dependency suppliers named `createGateways` and `createServices`, because
- * `gateways` and `services` already name what they answer.
+ * `gateways` and `services` already name what they answer. `toLifecycleHooks`
+ * is protected too and is not one of these: it is how the framework reads the
+ * two hooks, and a ViewModel overrides the hooks, never it.
  *
  * ```ts
  * class TodoVM extends ALankaVM<ITodoState, ITodoActions, ITodoGateways> {
@@ -345,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. */
@@ -372,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>;
 }
 
 /**
@@ -389,6 +475,9 @@ declare abstract class ALankaVM<State extends object, Actions extends object, TG
  * or a thunk, the class supplies by overriding a method of the same name, with
  * the two dependency suppliers named `createGateways` and `createServices`
  * because `gateways` and `services` already name what they answer.
+ * `toLifecycleHooks` is protected too and is not one of these: it is how the
+ * framework reads `onInit` and `onReset`, and a ViewModel overrides those,
+ * never it.
  *
  * ```ts
  * class SessionVM extends ALankaStatelessVM<ISessionActions, ISessionGateways> {
@@ -438,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>;
 }
 
 /**
@@ -469,7 +563,9 @@ declare abstract class ALankaStatelessVM<Actions extends object, TGateways exten
  * implementation: the store, the tracked hook and the two memoised state
  * references are the factory's, and duplicating them here would be the second
  * implementation the parity canon exists to prevent. What it gives a class-style
- * consumer is the same protected surface under the same names.
+ * consumer is the same protected surface under the same names — plus
+ * `toLifecycleHooks`, the framework's reading of `onInit`/`onReset`, which is
+ * not an extension point.
  *
  * Canon: `skills/parity/SKILL.md`.
  */
@@ -513,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 };