lanka 1.0.0

package/dist/validation/index.js

@@ -0,0 +1,53 @@
+// src/validation/lanka-validation-error/LankaValidationError.ts
+var LankaValidationError = class extends Error {
+  status;
+  errors;
+  constructor(message, errors = []) {
+    super(message);
+    this.name = "LankaValidationError";
+    this.status = 422;
+    this.errors = errors.length > 0 ? errors : [message];
+  }
+};
+
+// src/validation/lanka-standard-validator/lankaStandardValidator.ts
+function describeIssue(issue) {
+  const path = (issue.path ?? []).map(
+    (segment) => typeof segment === "object" && segment !== null && "key" in segment ? String(segment.key) : String(segment)
+  ).join(".");
+  return path ? `${path}: ${issue.message}` : issue.message;
+}
+function runSync(schema, data) {
+  const result = schema["~standard"].validate(data);
+  if (result instanceof Promise) {
+    throw new LankaValidationError(
+      "The schema is asynchronous and the validation port is synchronous. Parse such data by hand: passing it silently would be worse than failing.",
+      []
+    );
+  }
+  return result;
+}
+var lankaStandardValidator = Object.freeze({
+  validate(schema, data, context) {
+    const result = runSync(schema, data);
+    if (result.issues) {
+      throw new LankaValidationError(
+        `Validation failed for ${context}`,
+        result.issues.map(describeIssue)
+      );
+    }
+    return result.value;
+  },
+  validateSafe(schema, data) {
+    const result = runSync(schema, data);
+    if (result.issues) {
+      return { success: false, errors: result.issues.map(describeIssue) };
+    }
+    return { success: true, data: result.value };
+  }
+});
+export {
+  LankaValidationError,
+  lankaStandardValidator
+};
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/validation/lanka-validation-error/LankaValidationError.ts","../../src/validation/lanka-standard-validator/lankaStandardValidator.ts"],"sourcesContent":["import { ILankaApiError } from \"../../errors/_interfaces/ILankaApiError\";\n\n/**\n * What a schema refused, as an error a screen can catch by type.\n *\n * The one case where a class is the answer by itself: `instanceof` needs a\n * prototype. It carries the field errors a form renders, so a caller branches on\n * the type rather than parsing a message.\n */\nexport class LankaValidationError extends Error implements ILankaApiError {\n\tstatus: number;\n\terrors: string[];\n\n\tconstructor(message: string, errors: string[] = []) {\n\t\tsuper(message);\n\t\tthis.name = \"LankaValidationError\";\n\t\tthis.status = 422;\n\t\tthis.errors = errors.length > 0 ? errors : [message];\n\t}\n}\n","import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport { LankaValidationError } from \"../lanka-validation-error/LankaValidationError\";\nimport type { TLankaValidationResult } from \"../_types/TLankaValidationResult\";\n\n/**\n * Response body validation with any Standard Schema implementation.\n *\n * An abstraction typed by one library cannot be implemented by another, which is\n * the whole reason a validation port exists. Standard Schema is the shared\n * interface implemented by zod 4, valibot, arktype and others.\n *\n * `@standard-schema/spec` contains TYPES ONLY and adds no bytes to a build, so it\n * is a regular dependency rather than another peer.\n *\n * No adapter classes: a schema describes itself, and\n * `schema[\"~standard\"].validate(data)` is the whole protocol.\n */\n\n/** A schema the port understands: any Standard Schema implementation. */\nexport type TLankaSchema<TOutput = unknown> = StandardSchemaV1<unknown, TOutput>;\n\nexport interface ILankaValidator {\n\t/** Validates and returns the parsed value, or throws. */\n\tvalidate<TOutput>(schema: TLankaSchema<TOutput>, data: unknown, context: string): TOutput;\n\t/** Validates and returns an outcome, throwing nothing. */\n\tvalidateSafe<TOutput>(\n\t\tschema: TLankaSchema<TOutput>,\n\t\tdata: unknown,\n\t): TLankaValidationResult<TOutput>;\n}\n\n/**\n * A field path plus a message.\n *\n * The path is assembled WHOLE — `items.0.id`, not `id`. Without the index and the\n * parent the message points nowhere when the list has twenty items.\n */\nfunction describeIssue(issue: StandardSchemaV1.Issue): string {\n\tconst path = (issue.path ?? [])\n\t\t.map((segment) =>\n\t\t\ttypeof segment === \"object\" && segment !== null && \"key\" in segment\n\t\t\t\t? String(segment.key)\n\t\t\t\t: String(segment),\n\t\t)\n\t\t.join(\".\");\n\n\treturn path ? `${path}: ${issue.message}` : issue.message;\n}\n\nfunction runSync<TOutput>(\n\tschema: TLankaSchema<TOutput>,\n\tdata: unknown,\n): StandardSchemaV1.Result<TOutput> {\n\tconst result = schema[\"~standard\"].validate(data);\n\n\t// Standard Schema allows returning a promise. A synchronous port cannot await\n\t// it, and answering \"fine\" would let UNVALIDATED data through — a check that\n\t// cannot fail reporting success.\n\tif (result instanceof Promise) {\n\t\tthrow new LankaValidationError(\n\t\t\t\"The schema is asynchronous and the validation port is synchronous. Parse \" +\n\t\t\t\t\"such data by hand: passing it silently would be worse than failing.\",\n\t\t\t[],\n\t\t);\n\t}\n\n\treturn result;\n}\n\nexport const lankaStandardValidator: ILankaValidator = Object.freeze<ILankaValidator>({\n\tvalidate<TOutput>(schema: TLankaSchema<TOutput>, data: unknown, context: string): TOutput {\n\t\tconst result = runSync(schema, data);\n\n\t\tif (result.issues) {\n\t\t\tthrow new LankaValidationError(\n\t\t\t\t`Validation failed for ${context}`,\n\t\t\t\tresult.issues.map(describeIssue),\n\t\t\t);\n\t\t}\n\n\t\treturn result.value;\n\t},\n\n\tvalidateSafe<TOutput>(\n\t\tschema: TLankaSchema<TOutput>,\n\t\tdata: unknown,\n\t): TLankaValidationResult<TOutput> {\n\t\tconst result = runSync(schema, data);\n\n\t\tif (result.issues) {\n\t\t\treturn { success: false, errors: result.issues.map(describeIssue) };\n\t\t}\n\n\t\treturn { success: true, data: result.value };\n\t},\n});\n"],"mappings":";AASO,IAAM,uBAAN,cAAmC,MAAgC;AAAA,EACzE;AAAA,EACA;AAAA,EAEA,YAAY,SAAiB,SAAmB,CAAC,GAAG;AACnD,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,SAAS,OAAO,SAAS,IAAI,SAAS,CAAC,OAAO;AAAA,EACpD;AACD;;;ACkBA,SAAS,cAAc,OAAuC;AAC7D,QAAM,QAAQ,MAAM,QAAQ,CAAC,GAC3B;AAAA,IAAI,CAAC,YACL,OAAO,YAAY,YAAY,YAAY,QAAQ,SAAS,UACzD,OAAO,QAAQ,GAAG,IAClB,OAAO,OAAO;AAAA,EAClB,EACC,KAAK,GAAG;AAEV,SAAO,OAAO,GAAG,IAAI,KAAK,MAAM,OAAO,KAAK,MAAM;AACnD;AAEA,SAAS,QACR,QACA,MACmC;AACnC,QAAM,SAAS,OAAO,WAAW,EAAE,SAAS,IAAI;AAKhD,MAAI,kBAAkB,SAAS;AAC9B,UAAM,IAAI;AAAA,MACT;AAAA,MAEA,CAAC;AAAA,IACF;AAAA,EACD;AAEA,SAAO;AACR;AAEO,IAAM,yBAA0C,OAAO,OAAwB;AAAA,EACrF,SAAkB,QAA+B,MAAe,SAA0B;AACzF,UAAM,SAAS,QAAQ,QAAQ,IAAI;AAEnC,QAAI,OAAO,QAAQ;AAClB,YAAM,IAAI;AAAA,QACT,yBAAyB,OAAO;AAAA,QAChC,OAAO,OAAO,IAAI,aAAa;AAAA,MAChC;AAAA,IACD;AAEA,WAAO,OAAO;AAAA,EACf;AAAA,EAEA,aACC,QACA,MACkC;AAClC,UAAM,SAAS,QAAQ,QAAQ,IAAI;AAEnC,QAAI,OAAO,QAAQ;AAClB,aAAO,EAAE,SAAS,OAAO,QAAQ,OAAO,OAAO,IAAI,aAAa,EAAE;AAAA,IACnE;AAEA,WAAO,EAAE,SAAS,MAAM,MAAM,OAAO,MAAM;AAAA,EAC5C;AACD,CAAC;","names":[]}

package/dist/viewmodel/index.d.ts

@@ -0,0 +1,478 @@
+import { StoreApi, StateCreator, UseBoundStore } from 'zustand';
+import { a as ILankaScenario, T as TLankaReplayRequest, I as ILankaScenarioVM } from '../ILankaScenarioVM-DuCyPoyT.js';
+import { A as ALankaSharedStore } from '../ALankaSharedStore-B7uepuuk.js';
+import { StoreApi as StoreApi$1 } from 'zustand/vanilla';
+
+interface ILankaVMContext<TState, TGateways extends object, TServices extends object> {
+    set: StoreApi<TState>["setState"];
+    get: () => TState;
+    gateways: TGateways;
+    services: TServices;
+    trigger: <T>(scenario: ILankaScenario<T>, data?: T) => void;
+}
+
+/**
+ * A scenario handler, accepted bivariantly.
+ *
+ * The method-shorthand indirection is deliberate and cannot be simplified: under
+ * `strictFunctionTypes` an arrow-typed parameter is contravariant, so a handler
+ * declared for a specific payload would not satisfy the bus, which calls every
+ * subscriber as `(data?: unknown) => void`. A method position is checked
+ * bivariantly, which is what makes the two assignable.
+ *
+ * Written once here because it appeared identically in three binding types, and
+ * a reader meeting `bivarianceHack` for the first time deserves to find the
+ * reason rather than the trick.
+ */
+type TLankaScenarioHandler<TData> = {
+    bivarianceHack(data?: TData): void;
+}["bivarianceHack"];
+
+interface ILankaScenarioBinding<TData, TState extends object, TGateways extends object, TServices extends object> {
+    scenario: ILankaScenario<TData>;
+    /**
+     * Bivariant handler allows passing stricter callback signatures
+     * (e.g. data?: TFeatureGroupsListRefreshEventData) while the
+     * lankaEventBus expects (data?: unknown) => void.
+     */
+    handler: (ctx: ILankaVMContext<TState, TGateways, TServices>) => TLankaScenarioHandler<TData>;
+    options?: {
+        priority?: number;
+        replay?: TLankaReplayRequest;
+        usedBy?: string;
+    };
+}
+
+type TUnknownLankaScenarioBinding<TState extends object, TGateways extends object, TServices extends object> = ILankaScenarioBinding<unknown, TState & ILankaScenarioVM, TGateways, TServices>;
+
+type TLankaAnyMutators = any;
+
+type TLankaVMEnhancer<TState> = (creator: StateCreator<TState, TLankaAnyMutators, TLankaAnyMutators>) => StateCreator<TState, TLankaAnyMutators, TLankaAnyMutators>;
+
+interface ILankaVMConfig<State extends object, Actions extends object, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> {
+    name: string;
+    /**
+     * Enables access-tracking optimization for no-selector hook usage.
+     * Disable when the ViewModel is consumed by a single broad consumer
+     * that reads most fields, because proxy tracking overhead may outweigh gains.
+     */
+    enableAccessTrackingOptimization?: boolean;
+    states?: State;
+    createActions: (ctx: ILankaVMContext<State & Actions & ILankaScenarioVM, TGateways, Services>) => Actions;
+    scenarioHandlers?: TUnknownLankaScenarioBinding<State & Actions, TGateways, Services>[];
+    /** Non-gateway services. */
+    services?: Services | (() => Services);
+    /** TGateways (data layer) separated from services. */
+    gateways?: TGateways | (() => TGateways);
+    enhancers?: TLankaVMEnhancer<State & Actions & ILankaScenarioVM>[];
+    onInit?: (ctx: ILankaVMContext<State & Actions & ILankaScenarioVM, TGateways, Services>) => void;
+    onReset?: (ctx: ILankaVMContext<State & Actions & ILankaScenarioVM, TGateways, Services>) => void;
+}
+
+/**
+ * The functional style of `ALankaVM`: a ViewModel declared as an options object.
+ *
+ * Everything it can do, the class can do, because this IS the class — the hooks a
+ * subclass overrides arrive here as config fields of the same names, and the
+ * protected surface arrives as the `ctx` every hook is handed. What a ViewModel is
+ * and how it binds scenarios is documented once, on `ALankaVM`.
+ *
+ * ⚠️ ACCESS-TRACKING BLIND SPOT. A consumer re-renders only for state keys it READ
+ * off the returned proxy. An action that DERIVES a value (`getSomeView()`) reads the
+ * store through `get()`, which the proxy never sees — so a component whose only link
+ * to a state key is such a getter will never re-render when that key changes.
+ *
+ * Set `enableAccessTrackingOptimization: false` on such a ViewModel. Do NOT patch it
+ * in the view by destructuring the underlying keys for their side effect only: that
+ * reads as dead code, so a refactor, an unused-variable cleanup or a lint autofix
+ * removes it and the screen silently freezes again. `MeetingReportViewModel` carries
+ * the worked example (its report toggles froze exactly that way, twice).
+ *
+ * In development the mismatch ANNOUNCES ITSELF: the framework sees that a key
+ * changed, that no re-render will follow, and that the component reads that key
+ * through a getter — and warns with the ViewModel and key names. "Remember to
+ * set the flag" is not a mechanism.
+ */
+declare function createLankaVM<State extends object, Actions extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Record<string, never>>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+declare function createLankaVM<State extends object, Actions extends object, Services extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Services>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+declare function createLankaVM<State extends object, Actions extends object, TGateways extends object>(config: ILankaVMConfig<State, Actions, TGateways, Record<string, never>>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+declare function createLankaVM<State extends object, Actions extends object, TGateways extends object, Services extends object>(config: ILankaVMConfig<State, Actions, TGateways, Services>): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+
+declare function createLazyLankaVM<State extends object, Actions extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Record<string, never>>): TLazyLankaVM<ReturnType<typeof createLankaVM<State, Actions, Record<string, never>, Record<string, never>>>, State & Actions & ILankaScenarioVM>;
+declare function createLazyLankaVM<State extends object, Actions extends object, Services extends object>(config: ILankaVMConfig<State, Actions, Record<string, never>, Services>): TLazyLankaVM<ReturnType<typeof createLankaVM<State, Actions, Record<string, never>, Services>>, State & Actions & ILankaScenarioVM>;
+declare function createLazyLankaVM<State extends object, Actions extends object, TGateways extends object>(config: ILankaVMConfig<State, Actions, TGateways, Record<string, never>>): TLazyLankaVM<ReturnType<typeof createLankaVM<State, Actions, TGateways, Record<string, never>>>, State & Actions & ILankaScenarioVM>;
+declare function createLazyLankaVM<State extends object, Actions extends object, TGateways extends object, Services extends object>(config: ILankaVMConfig<State, Actions, TGateways, Services>): TLazyLankaVM<ReturnType<typeof createLankaVM<State, Actions, TGateways, Services>>, State & Actions & ILankaScenarioVM>;
+/**
+ * A lazy ViewModel hook: everything an ordinary store does, plus `dispose`.
+ */
+type TLazyLankaVM<TStore, TFullState> = TStore & {
+    getState: () => TFullState;
+    dispose: () => void;
+};
+
+type TLankaSetState<TState> = (partial: TState | Partial<TState> | ((state: TState) => TState | Partial<TState>), replace?: boolean) => void;
+interface ILankaStatelessVMContext<TState, TGateways extends object, TServices extends object> {
+    set: TLankaSetState<TState>;
+    get: () => TState;
+    gateways: TGateways;
+    services: TServices;
+    trigger: <T>(scenario: ILankaScenario<T>, data?: T) => void;
+}
+interface ILankaStatelessScenarioBinding<TData, TState extends object, TGateways extends object, TServices extends object> {
+    scenario: ILankaScenario<TData>;
+    handler: (ctx: ILankaStatelessVMContext<TState, TGateways, TServices>) => TLankaScenarioHandler<TData>;
+    options?: {
+        priority?: number;
+        replay?: TLankaReplayRequest;
+        usedBy?: string;
+    };
+}
+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>[];
+    services?: Services | (() => Services);
+    gateways?: TGateways | (() => TGateways);
+    onInit?: (ctx: ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>) => void;
+    onReset?: (ctx: ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>) => void;
+};
+type TLankaStatelessVMHook<Actions extends object> = {
+    <TSelected = Actions & ILankaScenarioVM>(selector?: (full: Actions & ILankaScenarioVM) => TSelected): TSelected;
+    getState: () => Actions & ILankaScenarioVM;
+};
+declare function createStatelessLankaVM<Actions extends object>(config: TLankaStatelessVMConfig$1<Actions, Record<string, never>, Record<string, never>>): TLankaStatelessVMHook<Actions>;
+declare function createStatelessLankaVM<Actions extends object, Services extends object>(config: TLankaStatelessVMConfig$1<Actions, Record<string, never>, Services>): TLankaStatelessVMHook<Actions>;
+declare function createStatelessLankaVM<Actions extends object, TGateways extends object>(config: TLankaStatelessVMConfig$1<Actions, TGateways, Record<string, never>>): TLankaStatelessVMHook<Actions>;
+declare function createStatelessLankaVM<Actions extends object, TGateways extends object, Services extends object>(config: TLankaStatelessVMConfig$1<Actions, TGateways, Services>): TLankaStatelessVMHook<Actions>;
+
+type TLankaStatelessVMConfig<Actions extends object, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> = Omit<ILankaVMConfig<object, Actions, TGateways, Services>, "states"> & {
+    states?: never;
+};
+type TLazyStatelessReturn<Actions extends object, TGateways extends object, Services extends object> = ReturnType<typeof createStatelessLankaVM<Actions, TGateways, Services>> & {
+    getState: () => Actions & ILankaScenarioVM;
+    dispose: () => void;
+};
+declare function createLazyStatelessLankaVM<Actions extends object>(config: TLankaStatelessVMConfig<Actions, Record<string, never>, Record<string, never>>): TLazyStatelessReturn<Actions, Record<string, never>, Record<string, never>>;
+declare function createLazyStatelessLankaVM<Actions extends object, Services extends object>(config: TLankaStatelessVMConfig<Actions, Record<string, never>, Services>): TLazyStatelessReturn<Actions, Record<string, never>, Services>;
+declare function createLazyStatelessLankaVM<Actions extends object, TGateways extends object>(config: TLankaStatelessVMConfig<Actions, TGateways, Record<string, never>>): TLazyStatelessReturn<Actions, TGateways, Record<string, never>>;
+declare function createLazyStatelessLankaVM<Actions extends object, TGateways extends object, Services extends object>(config: TLankaStatelessVMConfig<Actions, TGateways, Services>): TLazyStatelessReturn<Actions, TGateways, Services>;
+
+interface ILankaSharedStoreVMContext<TStoreState extends object, TFullState extends object, TStore extends ALankaSharedStore<TStoreState>, TGateways extends object, TServices extends object> {
+    set: StoreApi$1<TStoreState>["setState"];
+    getStore: () => TStoreState;
+    get: () => TFullState;
+    store: TStore;
+    gateways: TGateways;
+    services: TServices;
+    trigger: <T>(scenario: ILankaScenario<T>, data?: T) => void;
+}
+
+type TLankaSharedStoreVMHook<TStoreState extends object, TActions extends object> = {
+    <TSelected = TStoreState & TActions & ILankaScenarioVM>(selector?: (full: TStoreState & TActions & ILankaScenarioVM) => TSelected): TSelected;
+    getState: () => TStoreState & TActions & ILankaScenarioVM;
+    getStoreState: () => TStoreState;
+};
+interface ILankaSharedStoreScenarioBinding<TData, TStoreState extends object, TActions extends object, TStore extends ALankaSharedStore<TStoreState>, TGateways extends object, TServices extends object> {
+    scenario: ILankaScenario<TData>;
+    /**
+     * Bivariant handler allows stricter callback signatures while lankaEventBus expects unknown.
+     */
+    handler: (ctx: ILankaSharedStoreVMContext<TStoreState, TStoreState & TActions & ILankaScenarioVM, TStore, TGateways, TServices>) => TLankaScenarioHandler<TData>;
+    options?: {
+        priority?: number;
+        replay?: TLankaReplayRequest;
+        usedBy?: string;
+    };
+}
+interface ILankaSharedStoreVMConfig<TStoreState extends object, TActions extends object, TStore extends ALankaSharedStore<TStoreState>, TGateways extends object = Record<string, never>, TServices extends object = Record<string, never>> {
+    name: string;
+    /**
+     * Enables access-tracking optimization for no-selector hook usage.
+     * Disable when one broad consumer reads most store fields and updates are frequent.
+     */
+    enableAccessTrackingOptimization?: boolean;
+    store: TStore;
+    createActions: (ctx: ILankaSharedStoreVMContext<TStoreState, TStoreState & TActions & ILankaScenarioVM, TStore, TGateways, TServices>) => TActions;
+    scenarioHandlers?: ILankaSharedStoreScenarioBinding<unknown, TStoreState, TActions, TStore, TGateways, TServices>[];
+    services?: TServices | (() => TServices);
+    gateways?: TGateways | (() => TGateways);
+    onInit?: (ctx: ILankaSharedStoreVMContext<TStoreState, TStoreState & TActions & ILankaScenarioVM, TStore, TGateways, TServices>) => void;
+    onReset?: (ctx: ILankaSharedStoreVMContext<TStoreState, TStoreState & TActions & ILankaScenarioVM, TStore, TGateways, TServices>) => void;
+}
+
+/**
+ * Factory for ViewModels backed by an external shared store instance.
+ * Multiple ViewModels can be created on top of the same store instance.
+ */
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Record<string, never>>): TLankaSharedStoreVMHook<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Services>): TLankaSharedStoreVMHook<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Record<string, never>>): TLankaSharedStoreVMHook<StoreState, Actions>;
+declare function createSharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object, Services extends object>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, TGateways, Services>): TLankaSharedStoreVMHook<StoreState, Actions>;
+
+/**
+ * What a lazy shared-store ViewModel is, in the type as well as at runtime.
+ *
+ * The overloads used to promise the eager factory's return and nothing else, so
+ * `dispose` and `getStoreState` existed on the object and not in the type: a
+ * consumer releasing a closed screen's ViewModel got a compile error for calling
+ * something that was there.
+ */
+type TLazySharedStoreReturn<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object, Services extends object> = ReturnType<typeof createSharedStoreLankaVM<StoreState, Actions, Store, TGateways, Services>> & {
+    getState: () => StoreState & Actions & ILankaScenarioVM;
+    getStoreState: () => StoreState;
+    dispose: () => void;
+};
+declare function createLazySharedStoreLankaVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>>(config: ILankaSharedStoreVMConfig<StoreState, Actions, Store, Record<string, never>, Record<string, never>>): TLazySharedStoreReturn<StoreState, Actions, Store, Record<string, never>, Record<string, never>>;
+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>;
+
+/**
+ * What every ViewModel is given, and the two moments it is told about.
+ *
+ * The three ViewModel shapes — stateful, stateless, over a shared store — differ
+ * in where their state lives and in nothing else about this: each is handed a
+ * data layer and a set of collaborators, and each is told when its scenarios are
+ * bound and when they are about to be unbound.
+ *
+ * Stated once because a fifth hook added to two of the three is exactly the
+ * divergence `skills/parity/SKILL.md` is written against, and three copies of a
+ * default is how that starts.
+ *
+ * It is not a role and nothing extends it directly: the three bases do, and a
+ * consumer extends one of them.
+ */
+declare abstract class ALankaVMEnvironment<TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> {
+    /** What `createGateways` answered: the data layer, kept apart from services. */
+    protected gateways: TGateways;
+    /** What `createServices` answered: everything that is not a gateway. */
+    protected services: Services;
+    /** The data layer, built once per ViewModel. */
+    protected createGateways(): TGateways;
+    /** Non-gateway collaborators, built once per ViewModel. */
+    protected createServices(): Services;
+    /** Runs after the scenarios are bound. */
+    protected onInit(): void;
+    /** Runs when the screen goes away, before the scenarios are unbound. */
+    protected onReset(): void;
+}
+
+/**
+ * A ViewModel written as a class: the state a screen reads, and the only place a
+ * gateway is called from.
+ *
+ * This is the implementation of the role, and `createLankaVM` is the same thing
+ * reached the other way — a subclass built from an options object. Neither style
+ * can do what the other cannot, because there is nothing here to diverge from.
+ *
+ * The protected surface IS the functional context, member for member:
+ * `set`, `get`, `gateways`, `services`, `trigger`. What the config supplies as a
+ * 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.
+ *
+ * ```ts
+ * class TodoVM extends ALankaVM<ITodoState, ITodoActions, ITodoGateways> {
+ * 	protected readonly name = "TodoVM";
+ *
+ * 	protected states(): ITodoState {
+ * 		return { todos: [], isLoading: false };
+ * 	}
+ *
+ * 	protected createGateways(): ITodoGateways {
+ * 		return { todo: new TodoGateway() };
+ * 	}
+ *
+ * 	protected createActions(): ITodoActions {
+ * 		return {
+ * 			load: async () => {
+ * 				this.set({ isLoading: true });
+ * 				this.set({ todos: await this.gateways.todo.list(), isLoading: false });
+ * 			},
+ * 		};
+ * 	}
+ * }
+ *
+ * export const useTodoVM = new TodoVM().build();
+ * ```
+ *
+ * The access-tracking blind spot the functional style documents is the same one
+ * here, and `enableAccessTrackingOptimization` is the same switch. A consumer
+ * re-renders only for state keys it READ off the returned proxy; an action that
+ * DERIVES a value reads the store through `get`, which the proxy never sees, so a
+ * component whose only link to a key is such a getter never re-renders for it. In
+ * development the mismatch announces itself by name rather than by a frozen
+ * screen. Canon: `skills/parity/SKILL.md`.
+ */
+declare abstract class ALankaVM<State extends object, Actions extends object, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> extends ALankaVMEnvironment<TGateways, Services> {
+    /** Names the ViewModel in the logs, the scenario registry and the blind-spot warning. */
+    protected abstract readonly name: string;
+    /**
+     * Turn off when one broad consumer reads most fields, or when an action derives
+     * what the screen shows — proxy tracking then costs more than it saves, and in
+     * the second case it cannot see the read at all.
+     */
+    protected readonly enableAccessTrackingOptimization: boolean;
+    /** Writes state. Available from `createActions` onwards, never before. */
+    protected set: StoreApi<State & Actions & ILankaScenarioVM>["setState"];
+    /** Reads state. The read a tracked hook cannot see — hence the switch above. */
+    protected get: () => State & Actions & ILankaScenarioVM;
+    /** Fires a scenario, which every ViewModel bound to it then hears. */
+    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>[];
+    /** 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`. */
+    protected abstract createActions(): Actions;
+    /**
+     * The protected surface as an object, for the functional style.
+     *
+     * Assembled INSIDE the class because that is the only place `protected` can be
+     * read — a context built from outside could carry only the public half, which is
+     * the wrong half. Canon: `skills/parity/SKILL.md` section 3a.
+     */
+    protected toStyleContext(): ILankaVMContext<State & Actions & ILankaScenarioVM, TGateways, Services>;
+    /** Builds the hook a screen calls. One store per call. */
+    build(): UseBoundStore<StoreApi<State & Actions & ILankaScenarioVM>>;
+}
+
+/**
+ * A ViewModel that holds no reactive state: actions, and what they orchestrate.
+ *
+ * The second rung of the ladder in `core/README.md` written as a class. A screen
+ * that reads nothing and only DOES things — a sign-out, a share sheet, a form
+ * whose fields live in the form library — pays for a zustand store it never
+ * reads; this is the same role without one.
+ *
+ * The protected surface IS the functional context, member for member: `set`,
+ * `get`, `gateways`, `services`, `trigger`. What the config supplies as a value
+ * 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.
+ *
+ * ```ts
+ * class SessionVM extends ALankaStatelessVM<ISessionActions, ISessionGateways> {
+ * 	protected readonly name = "SessionVM";
+ *
+ * 	protected createGateways(): ISessionGateways {
+ * 		return { session: new SessionGateway() };
+ * 	}
+ *
+ * 	protected createActions(): ISessionActions {
+ * 		return {
+ * 			signOut: async () => {
+ * 				await this.gateways.session.signOut();
+ * 				this.trigger(sessionEnded);
+ * 			},
+ * 		};
+ * 	}
+ * }
+ *
+ * export const useSessionVM = new SessionVM().build();
+ * ```
+ *
+ * Canon: `skills/parity/SKILL.md`.
+ */
+declare abstract class ALankaStatelessVM<Actions extends object, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> extends ALankaVMEnvironment<TGateways, Services> {
+    /** Names the ViewModel in the logs, the scenario registry and any warning. */
+    protected abstract readonly name: string;
+    /** Writes state. Available from `createActions` onwards, never before. */
+    protected set: TLankaSetState<Actions & ILankaScenarioVM>;
+    /** Reads what the actions have written, including the actions themselves. */
+    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 actions the screen calls. Written against `this.set` and `this.get`. */
+    protected abstract createActions(): Actions;
+    /**
+     * The protected surface as an object, for the functional style.
+     *
+     * Assembled INSIDE the class because that is the only place `protected` can be
+     * read. Canon: `skills/parity/SKILL.md` section 3a.
+     */
+    protected toStyleContext(): ILankaStatelessVMContext<Actions & ILankaScenarioVM, TGateways, Services>;
+    /** Builds the hook a screen calls. One ViewModel per call. */
+    build(): TLankaStatelessVMHook<Actions>;
+}
+
+/**
+ * A ViewModel over a store several ViewModels share, written as a class.
+ *
+ * The third rung of the ladder in `core/README.md`: reach for it only when two
+ * ViewModels must CO-EDIT one state — a list and the badge that counts it, a
+ * form and the header that says it is dirty. What the class adds over the
+ * stateful base is where the state lives: in the store it is given, so `set`
+ * writes there and `getStore` reads it.
+ *
+ * ```ts
+ * class BadgeVM extends ALankaSharedStoreVM<ISelection, IBadgeActions, TodoStore> {
+ * 	protected readonly name = "BadgeVM";
+ *
+ * 	public constructor(store: TodoStore) {
+ * 		super(store);
+ * 	}
+ *
+ * 	protected createActions(): IBadgeActions {
+ * 		return { clear: () => this.set({ selectedId: null }) };
+ * 	}
+ * }
+ * ```
+ *
+ * Unlike its two siblings this one is a thin adapter rather than the
+ * 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.
+ *
+ * Canon: `skills/parity/SKILL.md`.
+ */
+declare abstract class ALankaSharedStoreVM<StoreState extends object, Actions extends object, Store extends ALankaSharedStore<StoreState>, TGateways extends object = Record<string, never>, Services extends object = Record<string, never>> extends ALankaVMEnvironment<TGateways, Services> {
+    /** Names the ViewModel in the logs and in the scenario registry. */
+    protected abstract readonly name: string;
+    /** The store this ViewModel and its siblings share. */
+    protected readonly store: Store;
+    /** Writes into the shared store, which every reader of it hears about. */
+    protected set: ILankaSharedStoreVMContext<StoreState, StoreState & Actions & ILankaScenarioVM, Store, TGateways, Services>["set"];
+    /** Reads the store's own state, without this ViewModel's actions on top. */
+    protected getStore: () => StoreState;
+    /** Reads the store's state WITH the actions, which is what a screen sees. */
+    protected get: () => StoreState & Actions & ILankaScenarioVM;
+    /** Fires a scenario, which every ViewModel bound to it then hears. */
+    protected trigger: ILankaSharedStoreVMContext<StoreState, StoreState & Actions & ILankaScenarioVM, Store, TGateways, Services>["trigger"];
+    constructor(store: Store);
+    /**
+     * Turn off when one broad consumer reads most fields of the store — proxy
+     * tracking then costs more than it saves.
+     */
+    protected readonly enableAccessTrackingOptimization: boolean;
+    /** The scenarios this ViewModel listens to, unsubscribed for it on reset. */
+    protected scenarioHandlers(): 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. */
+    build(): TLankaSharedStoreVMHook<StoreState, Actions>;
+}
+
+/**
+ * A shared store, without writing a class whose body is one function.
+ *
+ * A shared store is the third rung of the ladder in `core/README.md`: reach for
+ * it only when several ViewModels must CO-EDIT one state. Most stores have no
+ * behaviour of their own — the state and how to build it fresh is the whole
+ * declaration — and this is the shape for those.
+ *
+ * One implementation: what comes back is an `ALankaSharedStore`, so a reset, a
+ * subscription and the zustand api behave identically either way.
+ */
+declare const createLankaSharedStore: <TState extends object>(createInitialState: () => TState) => ALankaSharedStore<TState>;
+
+type TLankaVMStateCreator<TFullState> = StateCreator<TFullState, TLankaAnyMutators, TLankaAnyMutators>;
+
+type TLankaSharedStoreSetState<TState extends object> = (partial: TState | Partial<TState> | ((state: TState) => TState | Partial<TState>), replace?: boolean) => void;
+
+export { ALankaSharedStore, ALankaSharedStoreVM, ALankaStatelessVM, ALankaVM, type ILankaScenarioBinding, type ILankaSharedStoreScenarioBinding, type ILankaSharedStoreVMConfig, type ILankaSharedStoreVMContext, type ILankaStatelessScenarioBinding, type ILankaStatelessVMContext, type ILankaVMConfig, type ILankaVMContext, type TLankaAnyMutators, type TLankaSetState, type TLankaSharedStoreSetState, type TLankaSharedStoreVMHook, type TLankaStatelessVMConfig$1 as TLankaStatelessVMConfig, type TLankaStatelessVMHook, type TLankaVMEnhancer, type TLankaVMStateCreator, type TLazyLankaVM, type TUnknownLankaScenarioBinding, createLankaSharedStore, createLankaVM, createLazyLankaVM, createLazySharedStoreLankaVM, createLazyStatelessLankaVM, createSharedStoreLankaVM, createStatelessLankaVM };