lanka 1.1.1 → 1.3.0

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,5 +1,5 @@
 import { StoreApi, StateCreator, UseBoundStore } from 'zustand';
-import { a as ILankaScenario, T as TLankaReplayRequest, I as ILankaScenarioVM } from '../ILankaScenarioVM-DUsI-fSc.js';
+import { a as ILankaScenario, T as TLankaReplayRequest, I as ILankaScenarioVM } from '../ILankaScenarioVM-DpKFL3iE.js';
 import { A as ALankaSharedStore } from '../ALankaSharedStore-B7uepuuk.js';
 import { StoreApi as StoreApi$1 } from 'zustand/vanilla';
 
@@ -45,6 +45,30 @@ interface ILankaScenarioBinding<TData, TState extends object, TGateways extends
 
 type TUnknownLankaScenarioBinding<TState extends object, TGateways extends object, TServices extends object> = ILankaScenarioBinding<unknown, TState & ILankaScenarioVM, TGateways, TServices>;
 
+/**
+ * Scenario bindings as a ViewModel declares them: the list, or a factory for it.
+ *
+ * The factory form exists for the same reason `TLankaDependencyBag` has one, and
+ * for a sharper case. A ViewModel declared at module level writes its bindings as
+ * an array literal, and each entry names its scenario — `lankaScenarios.<name>`,
+ * which is a LOCATOR read. Written directly, that read happens while the module
+ * is being evaluated, and a module body can run before `createLanka` has: then
+ * the locator refuses with "lanka used before an instance existed" and nothing
+ * renders.
+ *
+ * Import order is not a defence. It holds inside one chunk, and a bundler decides
+ * chunks — in ES modules the body of an imported chunk runs before the body of
+ * the chunk importing it, so an application that put its ViewModels in their own
+ * chunks evaluated them ahead of its own `createLanka` call. Measured in a real
+ * app: 44 application chunks were statically imported by the entry, and its whole
+ * browser-level suite died on the first of them.
+ *
+ * `gateways` and `services` already accept a factory for the identical reason.
+ * Bindings were the one field left out, and they are the field that reads the
+ * locator most.
+ */
+type TLankaScenarioBindingsDeclaration<TBinding> = readonly TBinding[] | (() => readonly TBinding[]);
+
 type TLankaAnyMutators = any;
 
 type TLankaVMEnhancer<TState> = (creator: StateCreator<TState, TLankaAnyMutators, TLankaAnyMutators>) => StateCreator<TState, TLankaAnyMutators, TLankaAnyMutators>;
@@ -59,7 +83,12 @@ interface ILankaVMConfig<State extends object, Actions extends object, TGateways
     enableAccessTrackingOptimization?: boolean;
     states?: State;
     createActions: (ctx: ILankaVMContext<State & Actions & ILankaScenarioVM, TGateways, Services>) => Actions;
-    scenarioHandlers?: TUnknownLankaScenarioBinding<State & Actions, TGateways, Services>[];
+    /**
+     * A FACTORY postpones building the list until bind time — see
+     * `TLankaScenarioBindingsDeclaration` for the module-scope locator read it
+     * exists to avoid.
+     */
+    scenarioHandlers?: TLankaScenarioBindingsDeclaration<TUnknownLankaScenarioBinding<State & Actions, TGateways, Services>>;
     /** Non-gateway services. */
     services?: Services | (() => Services);
     /** TGateways (data layer) separated from services. */
@@ -130,7 +159,8 @@ interface ILankaStatelessScenarioBinding<TData, TState extends object, TGateways
 type TLankaStatelessVMConfig$1<Actions extends object, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> = {
     name: string;
     createActions: (ctx: ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>) => Actions;
-    scenarioHandlers?: ILankaStatelessScenarioBinding<unknown, Actions & ILankaScenarioVM, TGateways, Services>[];
+    /** A FACTORY is read at bind time — see `TLankaScenarioBindingsDeclaration`. */
+    scenarioHandlers?: TLankaScenarioBindingsDeclaration<ILankaStatelessScenarioBinding<unknown, Actions & ILankaScenarioVM, TGateways, Services>>;
     services?: Services | (() => Services);
     gateways?: TGateways | (() => TGateways);
     onInit?: (ctx: ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>) => void;
@@ -193,7 +223,8 @@ interface ILankaSharedStoreVMConfig<TStoreState extends object, TActions extends
     enableAccessTrackingOptimization?: boolean;
     store: TStore;
     createActions: (ctx: ILankaSharedStoreVMContext<TStoreState, TStoreState & TActions & ILankaScenarioVM, TStore, TGateways, TServices>) => TActions;
-    scenarioHandlers?: ILankaSharedStoreScenarioBinding<unknown, TStoreState, TActions, TStore, TGateways, TServices>[];
+    /** A FACTORY is read at bind time — see `TLankaScenarioBindingsDeclaration`. */
+    scenarioHandlers?: TLankaScenarioBindingsDeclaration<ILankaSharedStoreScenarioBinding<unknown, TStoreState, TActions, TStore, TGateways, TServices>>;
     services?: TServices | (() => TServices);
     gateways?: TGateways | (() => TGateways);
     onInit?: (ctx: ILankaSharedStoreVMContext<TStoreState, TStoreState & TActions & ILankaScenarioVM, TStore, TGateways, TServices>) => void;
@@ -226,6 +257,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.
  *
@@ -250,10 +294,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;
 }
 
 /**
@@ -269,7 +339,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> {
@@ -321,8 +393,14 @@ declare abstract class ALankaVM<State extends object, Actions extends object, TG
     protected trigger: <TData>(scenario: ILankaScenario<TData>, data?: TData) => void;
     /** The reactive fields the screen reads. */
     protected states(): State;
-    /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
-    protected scenarioHandlers(): TUnknownLankaScenarioBinding<State & Actions, TGateways, Services>[];
+    /**
+     * The scenarios this ViewModel listens to, unsubscribed for it on reset.
+     *
+     * Returning a FACTORY postpones building the list until bind time, which is
+     * what a ViewModel declared at module level needs when its entries name their
+     * scenarios through the locator. See `TLankaScenarioBindingsDeclaration`.
+     */
+    protected scenarioHandlers(): TLankaScenarioBindingsDeclaration<TUnknownLankaScenarioBinding<State & Actions, TGateways, Services>>;
     /** Store middleware — `persist`, `lankaDevtools` — the last one applied outermost. */
     protected enhancers(): TLankaVMEnhancer<State & Actions & ILankaScenarioVM>[];
     /** The actions the screen calls. Written against `this.set` and `this.get`. */
@@ -352,6 +430,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> {
@@ -385,8 +466,13 @@ declare abstract class ALankaStatelessVM<Actions extends object, TGateways exten
     protected get: () => Actions & ILankaScenarioVM;
     /** Fires a scenario, which every ViewModel bound to it then hears. */
     protected trigger: <TData>(scenario: ILankaScenario<TData>, data?: TData) => void;
-    /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
-    protected scenarioHandlers(): ILankaStatelessScenarioBinding<unknown, Actions & ILankaScenarioVM, TGateways, Services>[];
+    /**
+     * The scenarios this ViewModel listens to, unsubscribed for it on reset.
+     *
+     * Returning a FACTORY postpones building the list until bind time. See
+     * `TLankaScenarioBindingsDeclaration`.
+     */
+    protected scenarioHandlers(): TLankaScenarioBindingsDeclaration<ILankaStatelessScenarioBinding<unknown, Actions & ILankaScenarioVM, TGateways, Services>>;
     /** The actions the screen calls. Written against `this.set` and `this.get`. */
     protected abstract createActions(): Actions;
     /**
@@ -427,7 +513,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`.
  */
@@ -451,7 +539,7 @@ declare abstract class ALankaSharedStoreVM<StoreState extends object, Actions ex
      */
     protected readonly enableAccessTrackingOptimization: boolean;
     /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
-    protected scenarioHandlers(): ILankaSharedStoreScenarioBinding<unknown, StoreState, Actions, Store, TGateways, Services>[];
+    protected scenarioHandlers(): TLankaScenarioBindingsDeclaration<ILankaSharedStoreScenarioBinding<unknown, StoreState, Actions, Store, TGateways, Services>>;
     /** The actions the screen calls. Written against `this.set` and `this.get`. */
     protected abstract createActions(): Actions;
     /** Builds the hook a screen calls. One ViewModel per call. */

package/dist/viewmodel/index.js

@@ -1,7 +1,7 @@
 "use client";
 import {
   lankaScenarioBootstrap
-} from "../chunk-UGXSGQPW.js";
+} from "../chunk-B7EYIAW7.js";
 import "../chunk-O5ROO7QF.js";
 import {
   lankaLogger
@@ -12,7 +12,7 @@ import {
 import "../chunk-BGVDPDX4.js";
 
 // src/viewmodel/_abstractions/lanka-vm-environment/ALankaVMEnvironment.ts
-var ALankaVMEnvironment = class {
+var ALankaVMEnvironment = class _ALankaVMEnvironment {
   /** What `createGateways` answered: the data layer, kept apart from services. */
   gateways;
   /** What `createServices` answered: everything that is not a gateway. */
@@ -25,12 +25,44 @@ var ALankaVMEnvironment = class {
   createServices() {
     return {};
   }
-  /** 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.
+   */
   onInit() {
   }
-  /** 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.
+   */
   onReset() {
   }
+  /**
+   * 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.
+   */
+  toLifecycleHooks() {
+    const defaults = _ALankaVMEnvironment.prototype;
+    const hooks = {};
+    if (this.onInit !== defaults.onInit) hooks.onInit = () => this.onInit();
+    if (this.onReset !== defaults.onReset) hooks.onReset = () => this.onReset();
+    return hooks;
+  }
 };
 
 // src/viewmodel/_abstractions/lanka-vm/ALankaVM.ts
@@ -105,17 +137,20 @@ var createLankaBlindSpotTrap = (viewModelName, isArmed) => {
 };
 
 // src/viewmodel/_internal/create-lanka-scenario-binder/createLankaScenarioBinder.ts
+var readBindings = (declared) => typeof declared === "function" ? declared() : declared ?? [];
+var needsBootstrap = (config) => typeof config.bindings === "function" || config.bindings !== void 0 && config.bindings.length > 0 || config.onInit !== void 0 || config.onReset !== void 0;
 var createLankaScenarioBinder = (config) => {
   const subscriptions = /* @__PURE__ */ new Map();
   let isInitialized = false;
   return {
+    needsBootstrap: needsBootstrap(config),
     get isInitialized() {
       return isInitialized;
     },
     initializeScenario() {
       if (isInitialized) return;
       const context = config.context();
-      for (const binding of config.bindings ?? []) {
+      for (const binding of readBindings(config.bindings)) {
         const key = binding.scenario.eventType;
         if (subscriptions.has(key)) continue;
         subscriptions.set(
@@ -221,7 +256,13 @@ var ALankaVM = class extends ALankaVMEnvironment {
   states() {
     return {};
   }
-  /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
+  /**
+   * The scenarios this ViewModel listens to, unsubscribed for it on reset.
+   *
+   * Returning a FACTORY postpones building the list until bind time, which is
+   * what a ViewModel declared at module level needs when its entries name their
+   * scenarios through the locator. See `TLankaScenarioBindingsDeclaration`.
+   */
   scenarioHandlers() {
     return [];
   }
@@ -252,24 +293,20 @@ var ALankaVM = class extends ALankaVMEnvironment {
       this.name,
       getLankaFlags().isDevelopment === true
     );
-    const bindings = this.scenarioHandlers();
+    const hooks = this.toLifecycleHooks();
+    const { initializeScenario, resetScenario, needsBootstrap: needsBootstrap2 } = createLankaScenarioBinder({
+      name: this.name,
+      bindings: this.scenarioHandlers(),
+      context: () => this.toStyleContext(),
+      onInit: hooks.onInit,
+      onReset: hooks.onReset
+    });
     const stateCreator = (set, get) => {
       this.set = set;
       this.get = blindSpot.observeGet(get);
       this.gateways = this.createGateways();
       this.services = this.createServices();
       const actions = blindSpot.observeActions(this.createActions());
-      const { initializeScenario, resetScenario } = createLankaScenarioBinder({
-        name: this.name,
-        bindings,
-        context: () => this.toStyleContext(),
-        onInit: () => {
-          this.onInit();
-        },
-        onReset: () => {
-          this.onReset();
-        }
-      });
       return {
         ...this.states(),
         ...actions,
@@ -283,7 +320,7 @@ var ALankaVM = class extends ALankaVMEnvironment {
     );
     const store = create()(enhancedCreator);
     const registerScenarioViewModel = (viewModel) => {
-      if (bindings.length > 0) {
+      if (needsBootstrap2) {
         lankaScenarioBootstrap.registerViewModel(viewModel, this.name);
       }
     };
@@ -336,11 +373,16 @@ function createLankaVM(config) {
     createActions() {
       return config.createActions(this.toStyleContext());
     }
-    onInit() {
-      config.onInit?.(this.toStyleContext());
-    }
-    onReset() {
-      config.onReset?.(this.toStyleContext());
+    // The config's hooks become this instance's OWN `onInit`/`onReset`, assigned
+    // only when declared. An unconditional method override would make the base
+    // read every functional ViewModel as taking both hooks and register it with
+    // bootstrap for nothing; an own property is seen by the same test a class
+    // override is, and `this.onInit()` means the same thing in both styles.
+    constructor() {
+      super();
+      const { onInit, onReset } = config;
+      if (onInit) this.onInit = () => onInit(this.toStyleContext());
+      if (onReset) this.onReset = () => onReset(this.toStyleContext());
     }
   }
   return new FunctionalVM().build();
@@ -417,7 +459,12 @@ var ALankaStatelessVM = class extends ALankaVMEnvironment {
   trigger = (scenario, data) => {
     scenario.trigger(data);
   };
-  /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
+  /**
+   * The scenarios this ViewModel listens to, unsubscribed for it on reset.
+   *
+   * Returning a FACTORY postpones building the list until bind time. See
+   * `TLankaScenarioBindingsDeclaration`.
+   */
   scenarioHandlers() {
     return [];
   }
@@ -448,20 +495,16 @@ var ALankaStatelessVM = class extends ALankaVMEnvironment {
     this.gateways = this.createGateways();
     this.services = this.createServices();
     const actions = this.createActions();
-    const bindings = this.scenarioHandlers();
-    const { initializeScenario, resetScenario } = createLankaScenarioBinder({
+    const hooks = this.toLifecycleHooks();
+    const { initializeScenario, resetScenario, needsBootstrap: needsBootstrap2 } = createLankaScenarioBinder({
       name: this.name,
-      bindings,
+      bindings: this.scenarioHandlers(),
       context: () => this.toStyleContext(),
-      onInit: () => {
-        this.onInit();
-      },
-      onReset: () => {
-        this.onReset();
-      }
+      onInit: hooks.onInit,
+      onReset: hooks.onReset
     });
     state = { ...state, ...actions, initializeScenario, resetScenario };
-    if (bindings.length > 0) {
+    if (needsBootstrap2) {
       lankaScenarioBootstrap.registerViewModel(state, this.name);
     }
     const useStatelessViewModel = ((selector) => selector ? selector(state) : state);
@@ -487,11 +530,13 @@ function createStatelessLankaVM(config) {
     createActions() {
       return config.createActions(this.toStyleContext());
     }
-    onInit() {
-      config.onInit?.(this.toStyleContext());
-    }
-    onReset() {
-      config.onReset?.(this.toStyleContext());
+    // Own properties, assigned only when declared — see the same constructor in
+    // `createLankaVM` for why not a method override.
+    constructor() {
+      super();
+      const { onInit, onReset } = config;
+      if (onInit) this.onInit = () => onInit(this.toStyleContext());
+      if (onReset) this.onReset = () => onReset(this.toStyleContext());
     }
   }
   return new FunctionalStatelessVM().build();
@@ -538,7 +583,7 @@ function createSharedStoreLankaVM(config) {
     services,
     trigger: (scenario, data) => scenario.trigger(data)
   };
-  const { initializeScenario, resetScenario } = createLankaScenarioBinder({
+  const { initializeScenario, resetScenario, needsBootstrap: needsBootstrap2 } = createLankaScenarioBinder({
     name: config.name,
     bindings: config.scenarioHandlers,
     context: () => ctx,
@@ -565,7 +610,7 @@ function createSharedStoreLankaVM(config) {
   const useSharedStoreViewModel = isAccessTrackingEnabled ? useTrackedSharedStoreViewModel : useUntrackedSharedStoreViewModel;
   useSharedStoreViewModel.getState = () => getFullState();
   useSharedStoreViewModel.getStoreState = () => config.store.getState();
-  if (config.scenarioHandlers && config.scenarioHandlers.length > 0) {
+  if (needsBootstrap2) {
     const scenarioViewModel = {
       initializeScenario,
       resetScenario
@@ -612,6 +657,7 @@ var ALankaSharedStoreVM = class extends ALankaVMEnvironment {
   }
   /** Builds the hook a screen calls. One ViewModel per call. */
   build() {
+    const hooks = this.toLifecycleHooks();
     return createSharedStoreLankaVM({
       name: this.name,
       store: this.store,
@@ -628,12 +674,8 @@ var ALankaSharedStoreVM = class extends ALankaVMEnvironment {
         this.trigger = context.trigger;
         return this.createActions();
       },
-      onInit: () => {
-        this.onInit();
-      },
-      onReset: () => {
-        this.onReset();
-      }
+      onInit: hooks.onInit,
+      onReset: hooks.onReset
     });
   }
 };