lanka 1.2.0 → 2.0.0

package/dist/viewmodel/index.js

@@ -1,18 +1,19 @@
-"use client";
+import {
+  lankaBlindSpotRegistry
+} from "../chunk-UDP6IXDS.js";
 import {
   lankaScenarioBootstrap
-} from "../chunk-UGXSGQPW.js";
-import "../chunk-O5ROO7QF.js";
+} from "../chunk-EYDMBI5T.js";
 import {
   lankaLogger
-} from "../chunk-C2HP7CRD.js";
+} from "../chunk-FII3PW2G.js";
 import {
   getLankaFlags
-} from "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+} from "../chunk-7DQUF2QR.js";
+import "../chunk-XGMXT4XZ.js";
 
 // 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,16 +26,48 @@ 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
-import { create } from "zustand";
+import { createStore } from "zustand/vanilla";
 
 // src/viewmodel/_internal/create-lanka-blind-spot-trap/createLankaBlindSpotTrap.ts
 var createLankaBlindSpotTrap = (viewModelName, isArmed) => {
@@ -106,10 +139,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;
     },
@@ -139,69 +174,6 @@ var createLankaScenarioBinder = (config) => {
   };
 };
 
-// src/viewmodel/_internal/create-lanka-tracked-hook/createLankaTrackedHook.ts
-import { useCallback, useRef, useSyncExternalStore } from "react";
-var asRecord = (state) => state;
-var createLankaTrackedHook = (config) => {
-  return (selector) => {
-    const selectorRef = useRef(selector);
-    selectorRef.current = selector;
-    const trackedKeysRef = useRef(/* @__PURE__ */ new Set());
-    const trackedStateRef = useRef(null);
-    const trackedProxyRef = useRef(null);
-    const subscribe = useCallback(
-      (onStoreChange) => config.subscribe((nextState, prevState) => {
-        if (selectorRef.current) {
-          onStoreChange();
-          return;
-        }
-        const trackedKeys = trackedKeysRef.current;
-        if (trackedKeys.size === 0) {
-          onStoreChange();
-          return;
-        }
-        const next = asRecord(nextState);
-        const prev = asRecord(prevState);
-        for (const key of trackedKeys) {
-          if (!Object.is(next[key], prev[key])) {
-            onStoreChange();
-            return;
-          }
-        }
-        config.onUntrackedChange?.(trackedKeys, next, prev);
-      }),
-      []
-    );
-    return useSyncExternalStore(subscribe, readTracked, readUntracked);
-    function readTracked() {
-      const state = config.readState();
-      const activeSelector = selectorRef.current;
-      if (activeSelector) return activeSelector(state);
-      if (trackedStateRef.current === state && trackedProxyRef.current) {
-        return trackedProxyRef.current;
-      }
-      const trackedKeys = /* @__PURE__ */ new Set();
-      const proxyState = new Proxy(state, {
-        get(target, prop, receiver) {
-          if (typeof prop === "string") {
-            trackedKeys.add(prop);
-          }
-          return Reflect.get(target, prop, receiver);
-        }
-      });
-      trackedKeysRef.current = trackedKeys;
-      trackedStateRef.current = state;
-      trackedProxyRef.current = proxyState;
-      return proxyState;
-    }
-    function readUntracked() {
-      const state = config.readState();
-      const activeSelector = selectorRef.current;
-      return activeSelector ? activeSelector(state) : state;
-    }
-  };
-};
-
 // src/viewmodel/_abstractions/lanka-vm/ALankaVM.ts
 var ALankaVM = class extends ALankaVMEnvironment {
   /**
@@ -252,32 +224,35 @@ var ALankaVM = class extends ALankaVMEnvironment {
       trigger: this.trigger
     };
   }
-  /** Builds the hook a screen calls. One store per call. */
+  /**
+   * 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() {
     lankaLogger.printViewModelLog("START Create VM", this.name);
     const blindSpot = createLankaBlindSpotTrap(
       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,
@@ -289,29 +264,21 @@ var ALankaVM = class extends ALankaVMEnvironment {
       (creator, enhance) => enhance(creator),
       stateCreator
     );
-    const store = create()(enhancedCreator);
-    const registerScenarioViewModel = (viewModel) => {
-      if (hasBindings) {
-        lankaScenarioBootstrap.registerViewModel(viewModel, this.name);
+    const store = createStore()(enhancedCreator);
+    const viewModel = Object.defineProperties(store, {
+      name: { value: this.name, enumerable: false, configurable: true },
+      isAccessTracked: {
+        value: this.enableAccessTrackingOptimization,
+        enumerable: false,
+        configurable: true
       }
-    };
-    if (!this.enableAccessTrackingOptimization) {
-      registerScenarioViewModel(store.getState());
-      lankaLogger.printViewModelLog("FINISH Create VM", this.name);
-      return store;
-    }
-    const useOptimizedViewModel = createLankaTrackedHook({
-      subscribe: (onChange) => store.subscribe(onChange),
-      readState: () => store.getState(),
-      onUntrackedChange: blindSpot.isArmed ? blindSpot.report : void 0
     });
-    useOptimizedViewModel.setState = store.setState;
-    useOptimizedViewModel.getState = store.getState;
-    useOptimizedViewModel.getInitialState = store.getInitialState;
-    useOptimizedViewModel.subscribe = store.subscribe;
-    registerScenarioViewModel(useOptimizedViewModel.getState());
+    lankaBlindSpotRegistry.remember(viewModel, blindSpot);
+    if (needsBootstrap2) {
+      lankaScenarioBootstrap.registerViewModel(store.getState(), this.name);
+    }
     lankaLogger.printViewModelLog("FINISH Create VM", this.name);
-    return useOptimizedViewModel;
+    return viewModel;
   }
 };
 
@@ -344,17 +311,22 @@ 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();
 }
 
-// src/viewmodel/_internal/create-lazy-lanka-hook/createLazyLankaHook.ts
+// src/viewmodel/_internal/create-lazy-lanka-vm-proxy/createLazyLankaVMProxy.ts
 var lazySlot = (config) => {
   let store = null;
   return {
@@ -388,29 +360,31 @@ var lazySlot = (config) => {
   };
 };
 var PROMISE_MEMBERS = /* @__PURE__ */ new Set(["then", "catch", "finally"]);
-var forwardEveryMember = (slot) => (_target, property) => {
+var forwardEveryMember = (slot, config) => (_target, property) => {
   if (property === "dispose") return slot.release;
   if (PROMISE_MEMBERS.has(property)) return void 0;
+  if (property === "name") return config.name;
+  if (property === "isAccessTracked") return config.isAccessTracked;
   return (...args) => {
     const built = slot.get();
     const member = built[property];
     return typeof member === "function" ? member.apply(built, args) : member;
   };
 };
-var createLazyLankaHook = (config) => {
+var createLazyLankaVMProxy = (config) => {
   const slot = lazySlot(config);
-  const hook = (selector) => {
-    const built = slot.get();
-    return selector ? built(selector) : built();
-  };
-  return new Proxy(hook, { get: forwardEveryMember(slot) });
+  return new Proxy(
+    {},
+    { get: forwardEveryMember(slot, config) }
+  );
 };
 
 // src/viewmodel/_factories/create-lazy-lanka-vm/createLazyLankaVM.ts
 function createLazyLankaVM(config) {
-  return createLazyLankaHook({
+  return createLazyLankaVMProxy({
     name: config.name,
     kind: "VM",
+    isAccessTracked: config.enableAccessTrackingOptimization ?? true,
     create: () => createLankaVM(config)
   });
 }
@@ -449,7 +423,12 @@ var ALankaStatelessVM = class extends ALankaVMEnvironment {
       trigger: this.trigger
     };
   }
-  /** Builds the hook a screen calls. One ViewModel per call. */
+  /**
+   * 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() {
     lankaLogger.printViewModelLog("START Create slVM", this.name);
     let state = {};
@@ -461,26 +440,26 @@ 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);
-    useStatelessViewModel.getState = () => state;
+    const statelessViewModel = {
+      name: this.name,
+      getState: () => state,
+      subscribe: () => () => void 0,
+      isAccessTracked: false
+    };
     lankaLogger.printViewModelLog("FINISH Create slVM", this.name);
-    return useStatelessViewModel;
+    return statelessViewModel;
   }
 };
 
@@ -500,11 +479,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();
@@ -512,15 +493,17 @@ function createStatelessLankaVM(config) {
 
 // src/viewmodel/_factories/create-lazy-stateless-lanka-vm/createLazyStatelessLankaVM.ts
 function createLazyStatelessLankaVM(config) {
-  return createLazyLankaHook({
+  return createLazyLankaVMProxy({
     name: config.name,
     kind: "slVM",
+    // A stateless ViewModel has no reactive fields, so there is nothing whose
+    // reads could be worth recording — the eager one answers false too.
+    isAccessTracked: false,
     create: () => createStatelessLankaVM(config)
   });
 }
 
 // src/viewmodel/_factories/create-shared-store-lanka-vm/createSharedStoreLankaVM.ts
-import { useStore } from "zustand";
 function createSharedStoreLankaVM(config) {
   lankaLogger.printViewModelLog("START Create ssVM", config.name);
   let actions = {};
@@ -551,7 +534,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,
@@ -562,24 +545,16 @@ function createSharedStoreLankaVM(config) {
   lastStoreStateRef = null;
   lastFullStateRef = null;
   const isAccessTrackingEnabled = config.enableAccessTrackingOptimization ?? true;
-  const useTrackedSharedStoreViewModel = createLankaTrackedHook({
-    subscribe: (onChange) => config.store.subscribe((storeState, prevStoreState) => {
-      onChange(buildFullState(storeState), buildFullState(prevStoreState));
-    }),
-    readState: getFullState
-  });
-  const useUntrackedSharedStoreViewModel = ((selector) => useStore(config.store.getApi(), (storeState) => {
-    const fullState = buildFullState(storeState);
-    if (selector) {
-      return selector(fullState);
-    }
-    return fullState;
-  }));
-  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) {
+  const sharedStoreViewModel = {
+    name: config.name,
+    getState: getFullState,
+    getStoreState: () => config.store.getState(),
+    isAccessTracked: isAccessTrackingEnabled,
+    subscribe: (listener) => config.store.subscribe((storeState, prevStoreState) => {
+      listener(buildFullState(storeState), buildFullState(prevStoreState));
+    })
+  };
+  if (needsBootstrap2) {
     const scenarioViewModel = {
       initializeScenario,
       resetScenario
@@ -587,14 +562,15 @@ function createSharedStoreLankaVM(config) {
     lankaScenarioBootstrap.registerViewModel(scenarioViewModel, config.name);
   }
   lankaLogger.printViewModelLog("FINISH Create ssVM", config.name);
-  return useSharedStoreViewModel;
+  return sharedStoreViewModel;
 }
 
 // src/viewmodel/_factories/create-lazy-shared-store-lanka-vm/createLazySharedStoreLankaVM.ts
 function createLazySharedStoreLankaVM(config) {
-  return createLazyLankaHook({
+  return createLazyLankaVMProxy({
     name: config.name,
     kind: "ssVM",
+    isAccessTracked: config.enableAccessTrackingOptimization ?? true,
     create: () => createSharedStoreLankaVM(config)
   });
 }
@@ -626,6 +602,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,24 +619,20 @@ var ALankaSharedStoreVM = class extends ALankaVMEnvironment {
         this.trigger = context.trigger;
         return this.createActions();
       },
-      onInit: () => {
-        this.onInit();
-      },
-      onReset: () => {
-        this.onReset();
-      }
+      onInit: hooks.onInit,
+      onReset: hooks.onReset
     });
   }
 };
 
 // src/viewmodel/_abstractions/lanka-shared-store/ALankaSharedStore.ts
-import { createStore } from "zustand/vanilla";
+import { createStore as createStore2 } from "zustand/vanilla";
 var ALankaSharedStore = class {
   api;
   createInitialState;
   constructor(createInitialState) {
     this.createInitialState = createInitialState;
-    this.api = createStore()(() => this.createInitialState());
+    this.api = createStore2()(() => this.createInitialState());
   }
   getApi() {
     return this.api;
@@ -701,11 +674,34 @@ var createLankaSharedStore = (createInitialState) => {
   }
   return new FunctionalSharedStore();
 };
+
+// src/viewmodel/_factories/create-lanka-shallow-hold/createLankaShallowHold.ts
+var isShallowEqual = (a, b) => {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) return false;
+  const left = Object.keys(a);
+  const right = Object.keys(b);
+  if (left.length !== right.length) return false;
+  return left.every(
+    (key) => Object.hasOwn(b, key) && Object.is(a[key], b[key])
+  );
+};
+var createLankaShallowHold = () => {
+  let held;
+  let holding = false;
+  return (next) => {
+    if (holding && isShallowEqual(held, next)) return held;
+    holding = true;
+    held = next;
+    return next;
+  };
+};
 export {
   ALankaSharedStore,
   ALankaSharedStoreVM,
   ALankaStatelessVM,
   ALankaVM,
+  createLankaShallowHold,
   createLankaSharedStore,
   createLankaVM,
   createLazyLankaVM,