lanka 1.2.0 → 1.3.0

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';
 
@@ -257,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.
  *
@@ -281,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;
 }
 
 /**
@@ -300,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> {
@@ -389,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> {
@@ -469,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`.
  */

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
@@ -106,10 +138,12 @@ 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;
     },
@@ -259,25 +293,20 @@ var ALankaVM = class extends ALankaVMEnvironment {
       this.name,
       getLankaFlags().isDevelopment === true
     );
-    const bindings = this.scenarioHandlers();
-    const hasBindings = typeof bindings === "function" || bindings.length > 0;
+    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,
@@ -291,7 +320,7 @@ var ALankaVM = class extends ALankaVMEnvironment {
     );
     const store = create()(enhancedCreator);
     const registerScenarioViewModel = (viewModel) => {
-      if (hasBindings) {
+      if (needsBootstrap2) {
         lankaScenarioBootstrap.registerViewModel(viewModel, this.name);
       }
     };
@@ -344,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();
@@ -461,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 (typeof bindings === "function" || bindings.length > 0) {
+    if (needsBootstrap2) {
       lankaScenarioBootstrap.registerViewModel(state, this.name);
     }
     const useStatelessViewModel = ((selector) => selector ? selector(state) : state);
@@ -500,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();
@@ -551,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,
@@ -578,8 +610,7 @@ function createSharedStoreLankaVM(config) {
   const useSharedStoreViewModel = isAccessTrackingEnabled ? useTrackedSharedStoreViewModel : useUntrackedSharedStoreViewModel;
   useSharedStoreViewModel.getState = () => getFullState();
   useSharedStoreViewModel.getStoreState = () => config.store.getState();
-  const declaredBindings = config.scenarioHandlers;
-  if (typeof declaredBindings === "function" || declaredBindings !== void 0 && declaredBindings.length > 0) {
+  if (needsBootstrap2) {
     const scenarioViewModel = {
       initializeScenario,
       resetScenario
@@ -626,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,
@@ -642,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
     });
   }
 };