lanka 1.2.0 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 **◆ core** · Core
 
-> Twelve 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.
 
@@ -44,6 +44,8 @@ the seal on `internal`, and catches a subsystem added as a folder and forgotten
 - `src/locator/`
 - `src/gateway/`
 - `src/validation/`
+- `src/cache/`
+- `src/storage/`
 - `src/mock/`
 - `src/errors/`
 - `src/scenario/`

package/dist/{ALankaGateway-CkW1LbKE.d.ts → ALankaGateway-BrVPaZN5.d.ts}

@@ -1,4 +1,4 @@
-import { I as ILankaValidator } from './lankaStandardValidator-CL-r-zEV.js';
+import { I as ILankaValidator } from './lankaStandardValidator-BUFnysK0.js';
 
 /**
  * `RequestInit`, with the body a JSON API actually sends.

package/dist/ILankaFieldError-D5931-vT.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A failure with an ADDRESS: which input it belongs to, and what to say there.
+ *
+ * `issues` on `LankaError` flattens the address into the text — `items.1.qty:
+ * only 2 left` — which is right for a banner and useless for a form, which has
+ * a place per input and must find it. The path here stays in segments because
+ * the two form libraries this was designed against spell the same address
+ * differently (`items.1.qty` and `items[1].qty`) and neither can be parsed back
+ * out of a string safely: a message may contain a colon, a key may contain a
+ * dot.
+ *
+ * Produced by the validation port from a schema's issues, and by an
+ * application's request policy from a server body. Consumed by a ViewModel,
+ * which hands it to whatever holds the fields — its own state, or a form.
+ */
+interface ILankaFieldError {
+    /**
+     * Segments, never a joined string: `["items", 1, "qty"]`.
+     *
+     * A segment is a name or an index and nothing else — a producer holding a
+     * symbol stringifies it, because no form can address one. EMPTY means the
+     * value as a whole: a cross-field refusal ("the dates are in the wrong
+     * order"), or a body that was not the expected shape at all. That is the
+     * form's ROOT, and an adapter routes it there rather than to an input named
+     * `""`.
+     */
+    readonly path: readonly (string | number)[];
+    /** What to show at that address when the application does not translate. */
+    readonly message: string;
+    /** The machine-readable reason, when the producer had one — what i18n keys on. */
+    readonly code?: string;
+}
+
+export type { ILankaFieldError as I };

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/{ILankaScenarioMetadata-GoWWNEQL.d.ts → ILankaScenarioMetadata-Dj4GCqmX.d.ts}

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

package/dist/{ILankaScenarioVM-DUsI-fSc.d.ts → ILankaScenarioVM-DpKFL3iE.d.ts}

@@ -345,10 +345,11 @@ interface ILankaScenario<TData = void> {
 /**
  * A ViewModel that participates in scenarios.
  *
- * Not every ViewModel does: one with no `scenarioHandlers` never subscribes to
- * anything and is never registered. This is the pair of methods
- * `LankaScenarioBootstrap` calls on those that do, which is why the name says
- * scenario rather than ViewModel.
+ * 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.

package/dist/{LankaError-xpI-qj35.d.ts → LankaError-D6RWNyLM.d.ts}

@@ -1,3 +1,5 @@
+import { I as ILankaFieldError } from './ILankaFieldError-D5931-vT.js';
+
 /**
  * Structural API-error shape read by consumer code.
  *
@@ -42,6 +44,14 @@ interface ILankaErrorInit {
     code?: string;
     /** Details: server messages, or paths to the fields that failed validation. */
     issues?: readonly string[];
+    /**
+     * The failures that have an input to be shown at, with the path in segments.
+     *
+     * Beside `issues` rather than instead of it: `issues` is the banner's list and
+     * is promised; this is the form's, and a failure may have either, both or
+     * neither. Absent means "nothing here has an address", not "unknown".
+     */
+    fields?: readonly ILankaFieldError[];
     /**
      * The parsed ERROR response body, when there was one and it was JSON.
      *
@@ -72,6 +82,14 @@ declare class LankaError extends Error implements ILankaApiError {
     readonly status?: number;
     readonly code?: string;
     readonly issues?: readonly string[];
+    /**
+     * The failures with an input to be shown at. See `ILankaErrorInit.fields`.
+     *
+     * The array given is the array kept — unlike `errors`, which copies `issues`
+     * on every read. `readonly` carries the promise, and this is read on the way
+     * to a form, once, where a copy would buy nothing.
+     */
+    readonly fields?: readonly ILankaFieldError[];
     /** The parsed error response body; core carries it without reading it. */
     readonly body?: unknown;
     constructor(init: ILankaErrorInit);

package/dist/{LankaScenarioLocator-D86TIwiu.d.ts → LankaScenarioLocator-Dki2Es3O.d.ts}

@@ -1,7 +1,7 @@
-import { a as ILankaScenario, I as ILankaScenarioVM } from './ILankaScenarioVM-DUsI-fSc.js';
-import { I as ILankaScenarioMetadata } from './ILankaScenarioMetadata-GoWWNEQL.js';
-import { A as ALankaGateway } from './ALankaGateway-CkW1LbKE.js';
-import { A as ALankaLocator } from './LankaSharedStoreLocator-zS2kLu-S.js';
+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-jsz_gnUm.js';
 
 /**
  * The scenario registry: both those that registered themselves and those
@@ -146,4 +146,4 @@ declare class LankaScenarioLocator extends ALankaLocator<ILankaScenario<unknown>
     constructor();
 }
 
-export { LankaGatewayLocator as L, LankaScenarioLocator as a, LankaScenarioVMRegistry as b, LankaScenariosRegistry as c };
+export { LankaScenariosRegistry as L, LankaScenarioVMRegistry as a, LankaGatewayLocator as b, LankaScenarioLocator as c };

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

@@ -144,4 +144,4 @@ declare class LankaSharedStoreLocator extends ALankaLocator<ALankaSharedStore<TS
     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, LankaSingletonLocator as L, LankaSharedStoreLocator as a, type ILankaLocator as b, type ILankaSharedStoreLocatorConfig as c, type ILankaSingletonLocatorConfig as d };

package/dist/_extend/index.d.ts

@@ -1,13 +1,15 @@
-export { L as LankaGatewayLocator, a as LankaScenarioLocator, b as LankaScenarioVMRegistry, c as LankaScenariosRegistry } from '../LankaScenarioLocator-D86TIwiu.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 { b as LankaGatewayLocator, c as LankaScenarioLocator, a as LankaScenarioVMRegistry, L as LankaScenariosRegistry } from '../LankaScenarioLocator-Dki2Es3O.js';
+import { b as ILankaLocator } from '../LankaSharedStoreLocator-jsz_gnUm.js';
+export { A as ALankaLocator, a as LankaSharedStoreLocator, L as LankaSingletonLocator } from '../LankaSharedStoreLocator-jsz_gnUm.js';
+export { c as createLankaScope } from '../createLankaScope-DomNbEvb.js';
 export { c as composeLankaRequestMiddleware } from '../lankaRequestMiddleware-DAC5kCb7.js';
-import '../ILankaScenarioVM-DUsI-fSc.js';
-import '../ILankaScenarioMetadata-GoWWNEQL.js';
-import '../ALankaGateway-CkW1LbKE.js';
-import '../lankaStandardValidator-CL-r-zEV.js';
+import { I as ILankaReadableVM } from '../ILankaReadableVM-BoPzHEPV.js';
+import '../ILankaScenarioVM-DpKFL3iE.js';
+import '../ILankaScenarioMetadata-Dj4GCqmX.js';
+import '../ALankaGateway-BrVPaZN5.js';
+import '../lankaStandardValidator-BUFnysK0.js';
 import '@standard-schema/spec';
+import '../ILankaFieldError-D5931-vT.js';
 import '../ALankaSharedStore-B7uepuuk.js';
 import 'zustand/vanilla';
 
@@ -31,4 +33,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 };

package/dist/_extend/index.js

@@ -1,26 +1,151 @@
+import {
+  lankaBlindSpotRegistry
+} from "../chunk-UDP6IXDS.js";
 import {
   LankaGatewayLocator,
   LankaScenarioLocator,
   createLankaScope
-} from "../chunk-5MAQVBI2.js";
+} from "../chunk-UMPSR4US.js";
 import {
   LankaScenarioVMRegistry,
-  LankaScenariosRegistry
-} from "../chunk-O5ROO7QF.js";
+  LankaScenariosRegistry,
+  lankaScenarioBootstrap
+} from "../chunk-EYDMBI5T.js";
 import {
   composeLankaRequestMiddleware
 } from "../chunk-YR4MZXMU.js";
 import {
   createLankaLocatorProxy
-} from "../chunk-DTO27QFR.js";
+} from "../chunk-H5TIUKRK.js";
 import {
   ALankaLocator,
   LankaSharedStoreLocator,
   LankaSingletonLocator
 } from "../chunk-UE2C76OR.js";
-import "../chunk-C2HP7CRD.js";
-import "../chunk-D27MREPB.js";
-import "../chunk-BGVDPDX4.js";
+import "../chunk-FII3PW2G.js";
+import "../chunk-7DQUF2QR.js";
+import {
+  getActiveLankaScope,
+  hasLankaScopeResolver,
+  requireActiveRuntime
+} from "../chunk-XGMXT4XZ.js";
+
+// src/viewmodel/_internal/create-lanka-access-tracker/createLankaAccessTracker.ts
+var asRecord = (state) => state;
+var recordReadsInto = (state, keys) => new Proxy(state, {
+  get(target, prop, receiver) {
+    const value = Reflect.get(target, prop, receiver);
+    if (typeof prop === "string" && typeof value !== "function" && Object.hasOwn(target, prop)) {
+      keys.add(prop);
+    }
+    return value;
+  }
+});
+var trackedReadOf = (read) => {
+  let keys = /* @__PURE__ */ new Set();
+  let state = null;
+  let proxy = null;
+  return {
+    keys: () => keys,
+    current: () => {
+      const next = read();
+      if (state === next && proxy) return proxy;
+      keys = /* @__PURE__ */ new Set();
+      state = next;
+      proxy = recordReadsInto(next, keys);
+      return proxy;
+    }
+  };
+};
+var anyKeyMoved = (keys, next, prev) => {
+  const nextRecord = asRecord(next);
+  const prevRecord = asRecord(prev);
+  for (const key of keys) {
+    if (!Object.is(nextRecord[key], prevRecord[key])) return true;
+  }
+  return false;
+};
+var createLankaAccessTracker = (viewModel) => {
+  const trap = lankaBlindSpotRegistry.of(viewModel);
+  const isTracked = viewModel.isAccessTracked;
+  const tracked = trackedReadOf(() => viewModel.getState());
+  return {
+    get trackedKeys() {
+      return isTracked ? tracked.keys() : /* @__PURE__ */ new Set();
+    },
+    read() {
+      return isTracked ? tracked.current() : viewModel.getState();
+    },
+    shouldNotify(next, prev) {
+      if (!isTracked) return true;
+      const keys = tracked.keys();
+      return keys.size === 0 || anyKeyMoved(keys, next, prev);
+    },
+    reportSkipped(next, prev) {
+      trap?.report(new Set(tracked.keys()), asRecord(next), asRecord(prev));
+    },
+    readPlain() {
+      return viewModel.getState();
+    }
+  };
+};
+
+// src/viewmodel/_factories/create-lanka-view-subscription/createLankaViewSubscription.ts
+var createLankaViewSubscription = (viewModel, onChange) => {
+  const tracker = createLankaAccessTracker(viewModel);
+  const stop = viewModel.subscribe((next, prev) => {
+    if (!tracker.shouldNotify(next, prev)) {
+      tracker.reportSkipped(next, prev);
+      return;
+    }
+    onChange();
+  });
+  return { read: () => tracker.read(), stop };
+};
+
+// src/viewmodel/_internal/lanka-vm-recipes/lankaVMRecipes.ts
+var lankaVMRecipes = {
+  recipes: /* @__PURE__ */ new WeakMap(),
+  instances: /* @__PURE__ */ new WeakMap(),
+  /** The instances belonging to one scope, created on first use. */
+  forScope(scope) {
+    const existing = this.instances.get(scope);
+    if (existing) return existing;
+    const created = /* @__PURE__ */ new WeakMap();
+    this.instances.set(scope, created);
+    return created;
+  }
+};
+
+// src/viewmodel/_factories/define-lanka-vm/defineLankaVM.ts
+var defineLankaVM = (config) => {
+  const definition = Object.freeze({});
+  lankaVMRecipes.recipes.set(definition, config);
+  return definition;
+};
+
+// src/viewmodel/_factories/resolve-lanka-vm/resolveLankaVM.ts
+var resolveLankaVM = (definition) => {
+  const recipe = lankaVMRecipes.recipes.get(definition);
+  if (!recipe) {
+    throw new Error(
+      "resolveLankaVM was given something defineLankaVM did not make. A definition is opaque on purpose: build it with defineLankaVM rather than by hand."
+    );
+  }
+  const runtime = requireActiveRuntime();
+  const scope = getActiveLankaScope();
+  if (hasLankaScopeResolver() && !scope) {
+    throw new Error(
+      `resolveLankaVM("${recipe.name}") ran outside every scope. A scope resolver is installed, which on a server means this code ran outside a request \u2014 and a ViewModel resolved there would be the previous request's. Do this work inside the scope, or start one.`
+    );
+  }
+  const instances = lankaVMRecipes.forScope(scope ?? runtime);
+  const held = instances.get(definition);
+  if (held) return held;
+  const built = lankaScenarioBootstrap.buildScoped(() => recipe.build());
+  instances.set(definition, built);
+  return built;
+};
 export {
   ALankaLocator,
   LankaGatewayLocator,
@@ -30,7 +155,11 @@ export {
   LankaSharedStoreLocator,
   LankaSingletonLocator,
   composeLankaRequestMiddleware,
+  createLankaAccessTracker,
   createLankaLocatorProxy,
-  createLankaScope
+  createLankaScope,
+  createLankaViewSubscription,
+  defineLankaVM,
+  resolveLankaVM
 };
 //# sourceMappingURL=index.js.map