lanka 1.3.0 → 2.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 **◆ core** · Core
 
-> Fourteen subsystems, two peer dependencies, five extension points.
+> Fourteen subsystems, one peer dependency, six extension points.
 
 One, unscoped. Everything depends on it; it depends on nothing.
 

package/dist/{LankaSharedStoreLocator-zS2kLu-S.d.ts → ALankaLocator-BUCCz0Q5.d.ts}

@@ -1,5 +1,3 @@
-import { A as ALankaSharedStore } from './ALankaSharedStore-B7uepuuk.js';
-
 /**
  * Resolves instances by camelCase property name, mapping it to the PascalCase
  * class name.
@@ -100,48 +98,4 @@ declare abstract class ALankaLocator<TInstance> implements ILankaLocator<TInstan
     isRegistered(className: string): boolean;
 }
 
-/**
- * LankaSingletonLocator configuration.
- */
-interface ILankaSingletonLocatorConfig {
-    /** The module holding singleton classes — the consumer's barrel. */
-    singletonIndexModule?: Record<string, unknown>;
-}
-/**
- * Resolves singletons by property name (camelCase) or class name (PascalCase),
- * constructing them on first use and caching them.
- *
- * A class arrives either from the consumer's barrel or registered by hand — the
- * latter for tests and for objects that arrive already built.
- */
-declare class LankaSingletonLocator extends ALankaLocator<unknown> {
-    private readonly singletonIndexModule?;
-    constructor(config?: ILankaSingletonLocatorConfig);
-    /**
-     * Creates a NEW service object, bypassing the locator's cache.
-     *
-     * For scopes: they take the class from here and set the lifetime themselves.
-     * The root cache is untouched — otherwise the first resolution inside a scope
-     * would replace the application's root object.
-     */
-    createScopedInstance(className: string, propertyName: string): unknown;
-}
-
-type TSharedStoreState = object;
-/**
- * LankaSharedStoreLocator configuration.
- */
-interface ILankaSharedStoreLocatorConfig {
-    /** The module holding shared store classes — the consumer's barrel. */
-    sharedStoreIndexModule?: Record<string, unknown>;
-}
-/**
- * Resolves shared stores by property name (camelCase) or class name
- * (PascalCase), constructing them on first use and caching them.
- */
-declare class LankaSharedStoreLocator extends ALankaLocator<ALankaSharedStore<TSharedStoreState>> {
-    private readonly sharedStoreIndexModule?;
-    constructor(config?: ILankaSharedStoreLocatorConfig);
-}
-
-export { ALankaLocator as A, type ILankaLocatorConfig as I, LankaSharedStoreLocator as L, type ILankaLocator as a, LankaSingletonLocator as b, type ILankaSharedStoreLocatorConfig as c, type ILankaSingletonLocatorConfig as d };
+export { ALankaLocator as A, type ILankaLocatorConfig as I, type ILankaLocator as a };

package/dist/ILankaReadableVM-BoPzHEPV.d.ts

@@ -0,0 +1,72 @@
+/**
+ * What a view binding needs of a ViewModel, and nothing else.
+ *
+ * The reading half: a name, the current state, a way to hear about the next one,
+ * and whether this ViewModel wants access tracking. Writing is deliberately
+ * absent — a binding renders, and a binding that could write would be a second
+ * place actions live.
+ *
+ * ## Why this is the port and not `StoreApi`
+ *
+ * All three ViewModel shapes answer it, and they are built out of different
+ * things: the stateful one over a store of its own, the shared-store one over a
+ * slice of somebody else's, the stateless one over a plain object with no store
+ * at all. A binding written against a store type would work for one of the three.
+ *
+ * It is also what keeps zustand inside core. `@lankajs/react`, `@lankajs/vue`
+ * and every later member of the shelf see this interface and never `StoreApi`,
+ * so the store underneath can change without a binding hearing about it — and if
+ * a binding ever needs something zustand-shaped, the abstraction leaked and the
+ * fix belongs here rather than there. Canon: `skills/hosts/SKILL.md` §1a.
+ *
+ * @see ILankaVM for the half that also writes, which `hydrateLankaVM` needs.
+ */
+interface ILankaReadableVM<TState extends object> {
+    /**
+     * Names the ViewModel in logs, the scenario registry and the blind-spot
+     * warning — and in whatever a binding's devtools shows.
+     */
+    readonly name: string;
+    /**
+     * The current state, in full — and the SAME object until something changes.
+     *
+     * The identity is part of the contract, not an accident of the six factories
+     * that keep it. Every binding on the shelf holds something against it: the
+     * access tracker caches its recording proxy by the identity of the state it
+     * wrapped, and `@lankajs/react` holds a selector's answer the same way. An
+     * implementation that composes a fresh object on every call hands React a
+     * snapshot that never agrees with itself between the render read and the
+     * post-commit one, and the component renders until React stops it — a crash
+     * whose stack names React and not the ViewModel.
+     *
+     * It costs an implementer nothing to keep: answer a held object, and build a
+     * new one when you write. A ViewModel that composes its state from somewhere
+     * else memoises the composition against what it composed from —
+     * `createSharedStoreLankaVM` is the worked example.
+     */
+    getState(): TState;
+    /**
+     * Hears about every change, with both states in FULL shape.
+     *
+     * A shared-store ViewModel composes its full state from a store slice, and
+     * does so HERE rather than in the binding: a binding compares two states, it
+     * does not know how one is assembled.
+     *
+     * A stateless ViewModel has nothing that changes, so its implementation
+     * returns an unsubscribe and never calls the listener. That is not a gap —
+     * it is what makes the same binding work for all three without asking which
+     * it was handed.
+     */
+    subscribe(listener: (next: TState, prev: TState) => void): () => void;
+    /**
+     * Whether this ViewModel wants a reader to track which keys it read.
+     *
+     * `enableAccessTrackingOptimization`, as a binding sees it. A binding that
+     * ignores it is not merely slower: the blind spot documented on `ALankaVM`
+     * becomes a frozen screen, because the ViewModel turned tracking OFF for
+     * exactly the reason that it derives what the view shows.
+     */
+    readonly isAccessTracked: boolean;
+}
+
+export type { ILankaReadableVM as I };

package/dist/{ILankaScenarioVM-DpKFL3iE.d.ts → ILankaScenario-DQd9ZfUw.d.ts}

@@ -342,33 +342,4 @@ interface ILankaScenario<TData = void> {
     cleanup?(): void;
 }
 
-/**
- * A ViewModel that participates in scenarios.
- *
- * Not every ViewModel does: one with no `scenarioHandlers` and neither
- * lifecycle hook has nothing for bootstrap to do and is never registered. This
- * is the pair of methods `LankaScenarioBootstrap` calls on those that are, which
- * is why the name says scenario rather than ViewModel — `onInit` and `onReset`
- * ride on the same two calls.
- *
- * Both are idempotent by contract: bootstrap may run after a ViewModel has
- * already initialised itself, and a reset may arrive for one that never did.
- */
-interface ILankaScenarioVM {
-    /**
-     * Subscribes this ViewModel's scenario handlers.
-     *
-     * Called once the scenario registry is populated — a ViewModel declared at
-     * module level exists before any scenario does.
-     */
-    initializeScenario(): void;
-    /**
-     * Releases every subscription, leaving the ViewModel ready to initialise again.
-     *
-     * Called when the framework instance is disposed, and by `resetLanka()`
-     * between tests.
-     */
-    resetScenario(): void;
-}
-
-export { type ILankaScenarioVM as I, LankaEventBusInstance as L, type TLankaReplayRequest as T, type ILankaScenario as a, type ILankaEventMetadata as b, type TLankaEventBusMiddleware as c, type TLankaEventBusObserver as d, type ILankaEventLog as e, type ILankaEventBusOutcome as f, type TLankaEventBusDecision as g };
+export { type ILankaScenario as I, LankaEventBusInstance as L, type TLankaReplayRequest as T, type ILankaEventMetadata as a, type TLankaEventBusMiddleware as b, type TLankaEventBusObserver as c, type ILankaEventLog as d, type ILankaEventBusOutcome as e, type TLankaEventBusDecision as f };

package/dist/{ILankaScenarioMetadata-Dj4GCqmX.d.ts → ILankaScenarioMetadata-BsDp0Bzm.d.ts}

@@ -1,4 +1,4 @@
-import { a as ILankaScenario } from './ILankaScenarioVM-DpKFL3iE.js';
+import { I as ILankaScenario } from './ILankaScenario-DQd9ZfUw.js';
 
 /**
  * Metadata about a registered scenario

package/dist/ILankaScenarioVM-DKwjbIRq.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A ViewModel that participates in scenarios.
+ *
+ * Not every ViewModel does: one with no `scenarioHandlers` and neither
+ * lifecycle hook has nothing for bootstrap to do and is never registered. This
+ * is the pair of methods `LankaScenarioBootstrap` calls on those that are, which
+ * is why the name says scenario rather than ViewModel — `onInit` and `onReset`
+ * ride on the same two calls.
+ *
+ * Both are idempotent by contract: bootstrap may run after a ViewModel has
+ * already initialised itself, and a reset may arrive for one that never did.
+ */
+interface ILankaScenarioVM {
+    /**
+     * Subscribes this ViewModel's scenario handlers.
+     *
+     * Called once the scenario registry is populated — a ViewModel declared at
+     * module level exists before any scenario does.
+     */
+    initializeScenario(): void;
+    /**
+     * Releases every subscription, leaving the ViewModel ready to initialise again.
+     *
+     * Called when the framework instance is disposed, and by `resetLanka()`
+     * between tests.
+     */
+    resetScenario(): void;
+}
+
+export type { ILankaScenarioVM as I };

package/dist/{LankaScenarioLocator-CAENLhDO.d.ts → LankaScenarioVMRegistry-DySAOaj2.d.ts}

@@ -1,7 +1,6 @@
-import { a as ILankaScenario, I as ILankaScenarioVM } from './ILankaScenarioVM-DpKFL3iE.js';
-import { I as ILankaScenarioMetadata } from './ILankaScenarioMetadata-Dj4GCqmX.js';
-import { A as ALankaGateway } from './ALankaGateway-BrVPaZN5.js';
-import { A as ALankaLocator } from './LankaSharedStoreLocator-zS2kLu-S.js';
+import { I as ILankaScenario } from './ILankaScenario-DQd9ZfUw.js';
+import { I as ILankaScenarioVM } from './ILankaScenarioVM-DKwjbIRq.js';
+import { I as ILankaScenarioMetadata } from './ILankaScenarioMetadata-BsDp0Bzm.js';
 
 /**
  * The scenario registry: both those that registered themselves and those
@@ -114,36 +113,4 @@ declare class LankaScenarioVMRegistry {
     resetAll(): void;
 }
 
-/**
- * Resolves a gateway by property name (camelCase) or class name (PascalCase),
- * constructing it lazily and caching the instance.
- *
- * Adding a gateway takes one export line in `@lanka_di/Gateways`: types are
- * inferred and nothing is registered.
- */
-declare class LankaGatewayLocator extends ALankaLocator<ALankaGateway<unknown>> {
-    constructor();
-}
-
-/**
- * Resolves scenarios by property name (camelCase) or scenario name
- * (PascalCase).
- *
- * Looks in the registry, then in the self-registration pool, and failing both
- * constructs the scenario from the consumer's barrel on first use.
- */
-declare class LankaScenarioLocator extends ALankaLocator<ILankaScenario<unknown>> {
-    /**
-     * The registry is read LAZILY rather than in a field initialiser.
-     *
-     * The locator is constructed INSIDE `createLanka`, before the instance becomes
-     * active. A field initialiser would ask for the active instance at that moment
-     * and fail with "no instance yet" while the instance being created is on the
-     * stack. Deferred reading resolves it: by the first scenario resolution an
-     * active instance exists.
-     */
-    private get registry();
-    constructor();
-}
-
-export { LankaGatewayLocator as L, LankaScenarioLocator as a, LankaScenarioVMRegistry as b, LankaScenariosRegistry as c };
+export { LankaScenariosRegistry as L, LankaScenarioVMRegistry as a };

package/dist/_extend/index.d.ts

@@ -1,10 +1,16 @@
-export { L as LankaGatewayLocator, a as LankaScenarioLocator, b as LankaScenarioVMRegistry, c as LankaScenariosRegistry } from '../LankaScenarioLocator-CAENLhDO.js';
-import { a as ILankaLocator } from '../LankaSharedStoreLocator-zS2kLu-S.js';
-export { A as ALankaLocator, L as LankaSharedStoreLocator, b as LankaSingletonLocator } from '../LankaSharedStoreLocator-zS2kLu-S.js';
-export { c as createLankaScope } from '../createLankaScope-BiFxNQgl.js';
+export { a as LankaScenarioVMRegistry, L as LankaScenariosRegistry } from '../LankaScenarioVMRegistry-DySAOaj2.js';
+import { a as ILankaLocator } from '../ALankaLocator-BUCCz0Q5.js';
+export { A as ALankaLocator } from '../ALankaLocator-BUCCz0Q5.js';
+export { c as createLankaScope } from '../createLankaScope-CVoV0EwO.js';
+export { LankaGatewayLocator } from '../locator/gateway/lanka-gateway-locator/LankaGatewayLocator.js';
+export { LankaScenarioLocator } from '../locator/scenario/lanka-scenario-locator/LankaScenarioLocator.js';
+export { LankaSingletonLocator } from '../locator/singleton/lanka-singleton-locator/LankaSingletonLocator.js';
+export { LankaSharedStoreLocator } from '../locator/shared-store/lanka-shared-store-locator/LankaSharedStoreLocator.js';
 export { c as composeLankaRequestMiddleware } from '../lankaRequestMiddleware-DAC5kCb7.js';
-import '../ILankaScenarioVM-DpKFL3iE.js';
-import '../ILankaScenarioMetadata-Dj4GCqmX.js';
+import { I as ILankaReadableVM } from '../ILankaReadableVM-BoPzHEPV.js';
+import '../ILankaScenario-DQd9ZfUw.js';
+import '../ILankaScenarioVM-DKwjbIRq.js';
+import '../ILankaScenarioMetadata-BsDp0Bzm.js';
 import '../ALankaGateway-BrVPaZN5.js';
 import '../lankaStandardValidator-BUFnysK0.js';
 import '@standard-schema/spec';
@@ -32,4 +38,226 @@ interface ILankaLocatorProxyConfig<TInstance> {
  */
 declare function createLankaLocatorProxy<TInstance, TType extends Record<string, TInstance>>(config: ILankaLocatorProxyConfig<TInstance>): TType;
 
-export { type ILankaLocatorProxyConfig, createLankaLocatorProxy };
+interface ILankaAccessTracker<TState extends object> {
+    /**
+     * The state as a recording Proxy: every key read off it is remembered.
+     *
+     * Cached by the IDENTITY of the state it wrapped, so a second read while
+     * nothing has changed hands back the same proxy — and therefore the same
+     * recorded keys — rather than starting the recording over.
+     *
+     * A ViewModel that turned tracking off gets the state itself, and every
+     * change then notifies. That is its decision, not a fallback: it turned
+     * tracking off because it DERIVES what the screen shows, and a recording that
+     * cannot see those reads would skip renders the screen needs.
+     */
+    read(): TState;
+    /**
+     * Whether a change touches anything this reader actually looked at.
+     *
+     * A reader that has looked at NOTHING yet is notified of everything: it has
+     * not had the chance to record a key, and staying silent would mean its first
+     * render never arrives.
+     */
+    shouldNotify(next: TState, prev: TState): boolean;
+    /**
+     * Says, in development, that a change was skipped — so the framework can warn
+     * if the screen reads the changed key through a getter.
+     *
+     * Called by a binding exactly when `shouldNotify` answered `false`. In
+     * production, and for a ViewModel with no trap, it does nothing.
+     */
+    reportSkipped(next: TState, prev: TState): void;
+    /**
+     * The state itself, never the proxy.
+     *
+     * For a render that happens once and is thrown away — a server snapshot. There
+     * is nothing to skip on a second render that will not happen, so recording
+     * reads would be work whose result nothing consults.
+     */
+    readPlain(): TState;
+    /** The keys read so far. Handed to the blind-spot diagnostic, which names them. */
+    readonly trackedKeys: ReadonlySet<string>;
+}
+/**
+ * Which state keys one reader looked at, and whether a change touched them.
+ *
+ * This is the whole of access tracking, and it is deliberately ignorant of how
+ * anybody subscribes. A component re-renders only for keys it READ off the proxy
+ * this returns; every framework asks that question the same way and answers it
+ * with a different mechanism — `useSyncExternalStore`, a `shallowRef`, a signal —
+ * so the question lives here and the mechanism lives in the binding.
+ *
+ * **This is the one piece of core a binding author needs.** It is published
+ * through `lanka/extend` for exactly that: a binding is then a subscription, a
+ * render trigger and these four calls, and the behaviour a consumer sees is the
+ * framework's rather than each binding's re-reading of it. Canon:
+ * `skills/parity/SKILL.md`.
+ *
+ * ## One tracker per reader, not per store
+ *
+ * The recorded keys are the property of whoever did the reading. Two components
+ * over one ViewModel read different keys and must re-render for different
+ * changes, so each holds its own tracker — which is also why this is a factory
+ * with closed-over state rather than a set of pure functions over a shared map:
+ * the lifetime of the recording is exactly the lifetime of the reader.
+ *
+ * ## The blind spot this cannot see, and reports instead
+ *
+ * Tracking sees reads made DIRECTLY off the proxy. A key reached only inside a
+ * derived getter — an action calling `get()` — is invisible here, so a change to
+ * it answers `shouldNotify` with `false` and the screen does not move. That is
+ * what `reportSkipped` is for: core kept a trap for this ViewModel, and in
+ * development it names the ViewModel and the key rather than leaving a frozen
+ * screen with no error anywhere.
+ */
+declare const createLankaAccessTracker: <TState extends object>(viewModel: ILankaReadableVM<TState>) => ILankaAccessTracker<TState>;
+
+/** One reader's live view of a ViewModel. */
+interface ILankaViewSubscription<TState extends object> {
+    /**
+     * The current state, RECORDED.
+     *
+     * Every key read off it is remembered, which is what lets the next change be
+     * skipped when it touched none of them. Call it again on every read: it asks
+     * the ViewModel for its state each time, so it is never a snapshot.
+     */
+    read: () => TState;
+    /** Releases the subscription. */
+    stop: () => void;
+}
+/**
+ * The TRACKED half of a view binding, minus the framework.
+ *
+ * The tracked half, and not the whole: all five shipped members also publish a
+ * selector arm, which this deliberately does not serve — the reason is below,
+ * under "Why it does not take a selector".
+ *
+ * ```ts
+ * // a binding for a framework this repository has never heard of
+ * export const useMyFrameworkVM = (viewModel) => {
+ * 	const view = createLankaViewSubscription(viewModel, () => invalidate());
+ * 	onTeardown(view.stop);
+ *
+ * 	return view.read;
+ * };
+ * ```
+ *
+ * Subscribe, ask whether the change touched anything this reader looked at,
+ * report the skip so the blind-spot diagnostic can fire, and hand back a read
+ * that records. Five packages wrote those four steps out by hand, identically —
+ * and five copies of a decision diverge on the day one of them gains a line.
+ *
+ * ## What a caller still owns
+ *
+ * `onChange` and the teardown, which are the only framework-shaped things left.
+ * That is the seam: a binding says how its framework is WOKEN and when a reader
+ * has gone, and everything about which changes are worth waking for is here.
+ *
+ * ## Why it does not take a selector
+ *
+ * A selector BYPASSES tracking — the selector decides, and there is nothing to
+ * record — so a subscription that took one would be two mechanisms behind one
+ * name, each right half the time. A binding with a selector arm calls
+ * `createLankaAccessTracker` directly, which is what the shelf's members do, and
+ * the four steps are worth writing out where they genuinely differ.
+ *
+ * ## What it is not
+ *
+ * Not a store, not a cache, not a second place state lives. It holds a tracker
+ * and an unsubscribe, and everything it answers comes from the ViewModel on the
+ * call.
+ */
+declare const createLankaViewSubscription: <TState extends object>(viewModel: ILankaReadableVM<TState>, onChange: () => void) => ILankaViewSubscription<TState>;
+
+/**
+ * The brand that makes a definition impossible to write by hand.
+ *
+ * Not exported, and that is the whole mechanism. A structural interface with
+ * `name` and `build` on it would let a consumer author one, and the moment one
+ * does, `ILankaVMDefinition` stops being a type the framework implements and
+ * becomes a PORT — after which every member added to it is a compile error in
+ * code nobody touched. Publishing an opaque type costs one line and keeps the
+ * option space: a `dispose`, a `scope` field, even a call signature so that
+ * `missionsVM()` could mean `resolveLankaVM(missionsVM)`, all stay additive.
+ */
+declare const LANKA_VM_DEFINITION: unique symbol;
+/**
+ * A ViewModel that has not been built yet.
+ *
+ * Hold it, pass it, type against it. There is nothing on it to call, because
+ * calling it is `resolveLankaVM`'s job and a definition built by hand would be
+ * an instance outside every scope's map.
+ */
+interface ILankaVMDefinition<TViewModel extends ILankaReadableVM<object>> {
+    readonly [LANKA_VM_DEFINITION]: TViewModel;
+}
+/**
+ * Declares a ViewModel WITHOUT building it.
+ *
+ * ## When NOT to use this
+ *
+ * A browser-only application needs none of it. One module is one instance per
+ * TAB there, so a module-level `createLankaVM` is still the shape, and wrapping
+ * the nine factories in this one buys nothing but a lookup per read. Reach for
+ * it when the same ViewModel has to exist on a SERVER, where one module is one
+ * instance per PROCESS — shared by every user connected to it, so the first
+ * request to write a draft into it serves that draft to the next stranger.
+ *
+ * ```ts
+ * export const missionsVM = defineLankaVM({
+ * 	name: "MissionsVM",
+ * 	build: () => createLankaVM({ … }),
+ * });
+ * ```
+ *
+ * ## What it is not
+ *
+ * Not a tenth way to write a ViewModel. `build` returns whatever the nine
+ * existing factories return and nothing here reaches inside it — a definition
+ * adds a lifetime and takes nothing away.
+ *
+ * Not lazy in the sense `createLazyLankaVM` is. That one defers the STORE until
+ * first read and still has one per module; this defers WHICH INSTANCE, and the
+ * two compose.
+ */
+declare const defineLankaVM: <TViewModel extends ILankaReadableVM<object>>(config: {
+    name: string;
+    build: () => TViewModel;
+}) => ILankaVMDefinition<TViewModel>;
+
+/**
+ * The instance of a definition that belongs to the CURRENT scope.
+ *
+ * Called twice in one scope it answers the same instance; called in two scopes
+ * it answers two, and neither can see the other's state. In a browser there is
+ * one scope for the life of the tab, so this is the module-level ViewModel a
+ * consumer already knows — written once and correct on a server as well.
+ *
+ * ## It throws outside a scope, and that is the feature
+ *
+ * On a server the answer comes from the SCOPE seam rather than from the active
+ * runtime, and the difference is not academic. `runInLankaServerScope` creates
+ * its instance inside the scope and `createLanka` activates every instance it
+ * builds, so during a request the process pointer and the scope's runtime are
+ * the same object — keying on the runtime would make "inside a request" and
+ * "after one ended" indistinguishable, and a call made after would be handed the
+ * last stranger's ViewModel.
+ *
+ * So: a scope resolver installed and answering `null` means this ran outside
+ * every request, and that fails loudly. No fallback, for the same reason
+ * `requireActiveRuntime` has none — a wrong answer here is one user's data in
+ * another user's page, and it would surface three layers from the call.
+ *
+ * ## Why the build is wrapped
+ *
+ * `ALankaVM.build()` declares a ViewModel that has scenario handlers into a
+ * PROCESS-wide list, so that every instance ever created adopts it. That is
+ * right for a module-level ViewModel and catastrophic for a scoped one: the list
+ * would grow per request forever, and request N+1 would adopt request N's
+ * ViewModel and run N's handlers against N's gateways. `buildScoped` is the seam
+ * that keeps a scoped declaration out of it.
+ */
+declare const resolveLankaVM: <TViewModel extends ILankaReadableVM<object>>(definition: ILankaVMDefinition<TViewModel>) => TViewModel;
+
+export { type ILankaAccessTracker, type ILankaLocatorProxyConfig, type ILankaVMDefinition, type ILankaViewSubscription, createLankaAccessTracker, createLankaLocatorProxy, createLankaViewSubscription, defineLankaVM, resolveLankaVM };