lanka 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lankajs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# lanka
+
+**◆ core** · Core
+
+> Ten subsystems, two peer dependencies, five extension points.
+
+One, unscoped. Everything depends on it; it depends on nothing.
+
+**Runs in:** the browser, node and React Native — everywhere.
+
+**How to use it:** [GUIDE.md](./GUIDE.md) — the user guide, with examples. **How to change it:** [SKILL.md](./SKILL.md).
+
+## Extension points core declares
+
+| Point | What it gives | Available |
+| --- | --- | --- |
+| `useRequestMiddleware(mw)` | wrap every request | yes |
+| `inFlight.subscribe(fn)` | observe the number of requests on the wire | yes |
+| `lankaEventBus.addMiddleware` | intercept bus events | yes |
+| `LankaLogger sinks` | where log output goes | yes |
+| `use(plugin)` | register a whole plugin | yes |
+
+The list is closed on purpose. Each point is a public contract for the lifetime of a
+major version, so anything that can be a module must be a module.
+
+## Subsystems
+
+Flat, with no intermediate `Layers/`: **folder = subpath in `exports` = line in this list.**
+
+Each subsystem is exported through its BARREL (`index.ts`), so public is exactly what the
+barrel lists, moving a file inside a subsystem is not a breaking change, and a consumer's
+import reads `lanka/gateway`.
+
+`internal/` is not in the map — that is what may be refactored without a major. Hence the
+rule: a primitive a neighbouring package needs has two honest exits, becoming public here
+or moving to the neighbour. `src/publicSurface.test.ts` checks the map, the barrels and
+the seal on `internal`, and catches a subsystem added as a folder and forgotten in
+`exports`.
+
+- `src/bootstrap/`
+- `src/role/`
+- `src/config/`
+- `src/locator/`
+- `src/gateway/`
+- `src/validation/`
+- `src/mock/`
+- `src/errors/`
+- `src/scenario/`
+- `src/viewmodel/`
+- `src/logger/`
+- `src/internal/` — **not exported.** Refactored without a major.
+
+## Instance
+
+```ts
+const lanka = createLanka({ host, flags });
+await lanka.bootstrap({ services });
+```
+
+The instance owns all framework state: the bus, the scenario registries, four locator
+caches, the config and the in-flight request counter. Module-level state made three
+things impossible, none of which looked like a bug: two apps in one process shared a
+bus, SSR reused state between different users' requests, and test isolation rested on a
+global `beforeEach` reaching into internal registries.
+
+**Ambient facades** — `lankaEventBus.dispatch`, `lankaSingletons.foo`, `getLankaFlags()`,
+`lankaHttpInFlight` — resolve THE ONE active instance (`internal/activeRuntime.ts`).
+They exist for callers that cannot hold an instance: a user-extended `ALankaScenario`,
+the static `LankaScenarioBootstrap`, a module package with no instance in scope.
+Isolation belongs to the instance holder; a facade cannot offer it.
+
+One thing stays at module level deliberately: `ALankaScenario` collects constructed
+scenarios into a static pool. That is not runtime state but a REGISTRY OF DEFINITIONS —
+the classes come from one `@lanka_di/Scenarios` barrel and both instances must see the
+same list. Splitting it would be divergence, not isolation.
+
+## Failure
+
+`LankaError` carries a TAGGED kind: `network` · `timeout` · `aborted` · `http` · `schema` ·
+`domain`. Six rather than one, because each demands something different of the interface:
+a network failure invites a retry, an aborted request is not shown at all (the user left),
+a schema break is reported as a break rather than as the user's fault.
+
+The kind is assigned where the failure is born: in `ALankaRequest.execute`, the single
+point every request passes through.
+
+Parsing a particular response body format is NOT here: which JSON the backend sends is
+policy, and policy lives in `@lankajs/plugin-http`.
+
+## Host contract
+
+```ts
+interface ILankaHost {
+	apiBaseUrl: string;
+	httpErrorMessage(status: number): string;
+	networkErrorMessage(): string;
+	timeoutErrorMessage(): string;
+}
+```
+
+All required, and that is the choice: a forgotten field is a compile error in the one
+place it can be passed, rather than a wrong-language string in the interface or an
+`undefined` inside a request URL. `ALankaGateway.endpoint()` prefixes with `apiBaseUrl`.
+
+### Request middleware shape
+
+**Request middleware is a WRAPPER, not a set of hooks.** The `(ctx, next) => …` shape,
+because retry cannot be expressed with `onRequest`/`onResponse`/`onError`: `onError` can
+replace an error but cannot run the request again — and retry plus auth refresh are the
+two main abilities of a request-policy plugin. Registered first wraps the rest.
+
+The objection to `next()` that holds for the event bus does not carry over: there a
+middleware that skips `next` SILENCES the event, here it returns a value instead of a
+request, and the caller sees it.
+
+**Cancellation and timeout.** `execute` takes `signal` and `timeoutMs`; the default
+timeout is per instance. The framework combines the caller's signal and its own timer
+into ONE signal and still distinguishes who aborted: a timed-out request yields `timeout`
+and is shown, a caller-aborted one yields `aborted` and stays silent. `AbortSignal` does
+not distinguish them — it has one `abort` for everyone.
+
+## Response body validation
+
+The port accepts ANY schema implementing Standard Schema: zod 4, valibot, arktype. An
+abstraction typed by its single implementation is not an abstraction; the proof is a
+second implementation passing the same assertions, and it is in the tests.
+
+There are no adapter classes: a schema describes itself. The app chooses the library —
+`@lankajs/zod`, `@lankajs/valibot`, or neither, working with schemas directly.
+
+An async schema is rejected LOUDLY. Standard Schema allows `validate` to return a
+promise, a synchronous port cannot await it, and answering "fine" would let unvalidated
+data through — a check that cannot fail reporting success.
+
+## Lifetime
+
+`lanka.createScope()` gives a lifetime shorter than the application's: an object created
+in a scope goes away with it.
+
+A scope takes only ITS OWN objects. One that took others' would be more dangerous than no
+scopes at all: closing a screen would break the app. Resolving from a closed scope is
+rejected loudly — it is almost always a reference that outlived its screen.
+
+A lazy ViewModel has `dispose()` for the same reason: it subscribes to scenarios on first
+use, and without explicit disposal the subscription outlives the screen that created it.
+
+## Access-tracking blind spot
+
+A consumer re-renders only for keys it READ through the proxy. An action computing a
+value via `get()` reads state past the proxy — so a component whose only link to a key
+goes through such a getter never re-renders: the screen freezes and there is no error.
+
+It cannot be fixed in the view: destructuring "for the side effect" reads as dead code and
+the next refactor or lint autofix removes it. The fix is
+`enableAccessTrackingOptimization: false`, and so that nobody has to remember it, 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.
+
+The trap stays silent on healthy code: not reading what you do not need is the work
+tracking exists for.
+
+## Event bus
+
+**Buffering on request only.** Buffer depth is the maximum of what the event declares
+(`registerEvent({ replay: N })`) and what subscribers ask for; when the last asker
+unsubscribes the buffer is cleared. Buffering every payload unconditionally holds
+personal data in memory with no consumer at all.
+
+**`replay` counts values:** `false | "last" | N`, where `true` means "last".
+
+**`subscribe` returns an unsubscribe.** It removes EXACTLY that subscription: by callback,
+two subscriptions of one function are indistinguishable.
+
+**Delivery iterates a COPY of the subscriber list.** A subscriber may unsubscribe inside
+its own handler, and unsubscribing splices the same array, so iterating the original
+skipped a neighbour silently. The deliberate side effect: subscribing during delivery
+waits for the next event.
+
+**`registerEvent` merges metadata** instead of recreating state; recreating dropped every
+subscriber silently.
+
+**Middleware returns a decision** — `"pass"` or `{ stop: reason }`. A `next()`-based shape
+means not calling it makes the event vanish SILENTLY: a mechanism that exists for
+observability would be its own blind spot. A stop is written to the event log and is
+visible to the inspector. An exception in middleware is treated the same way.
+
+## Which of the three carries a connection
+
+The framework ships a ViewModel, a scenario and a shared store, and the hardest
+question is not how any of them works but which one a connection belongs to. The
+ladder, in order — take the first rung that fits and stop:
+
+1. **One ViewModel owns the state.** Start here always. A screen with a question
+   about its own data has no connection to carry.
+2. **Another must REACT — a scenario.** It carries a fact (`GapCompleted`), not a
+   command, and each side decides what the fact means for its own state. Nobody
+   imports anybody: that is the whole reason the layer exists.
+3. **Several must CO-EDIT one state — one shared store.** Only when scenarios have
+   turned into synchronisation: the same value written in three ViewModels, kept in
+   step by hand, racing on a slow answer. Keep the store scoped to the feature and
+   give it explicit reset points.
+4. **The store became a bus — the feature boundary is wrong.** A shared store that
+   everything reads is global state with extra steps. Split the feature and hand
+   cross-feature connections back to scenarios.
+
+The rungs are not styles to pick between. Each costs more than the one above: a
+scenario is a name in two files, a shared store is a lifetime somebody has to own.
+
+`no-viewmodel-to-viewmodel` in `@lankajs/tool-eslint` enforces the only hard part —
+that rung 1 never reaches sideways — and the core playground runs rungs 2 and 3
+beside each other: a scenario writes into a ViewModel that never heard of the
+trigger, and two ViewModels share one selection through `PlaygroundTodoStore`.
+
+## Naming rule
+
+**Anything the consumer writes in their own code carries the framework name.**
+`ALankaGateway`, `ALankaScenario`, `createLankaVM`, `lankaEventBus`, `LankaLogger`,
+`lankaSingletons`.
+
+Two reasons, the second the stronger one. A reader of an unfamiliar file can see where
+`ALankaGateway` came from; `AGateway` says nothing. And the framework does not squat
+popular names — `Logger`, `EventBus`, `Storage`, `Singletons`, `Scenarios` are exactly
+the names an app wants for ITS own things, and a library that takes them forces the app
+to rename.
+
+`ViewModel` shortens to `VM` in class, factory and type names: `ALankaVM` and
+`createLankaVM` are written in every screen file — the same ViewModel reached from
+either style, one of the nine roles `skills/parity/SKILL.md` governs.
+
+Three names stay bare — `isRecord`, `getStringField`, `generateUuid`. They are pure
+utilities over ordinary values; a collision there is resolved at the import site, which
+is not available for a class that gets EXTENDED.
+
+The rule is executed by `core/src/brand.test.ts`, not stated in a document.
+
+`.lanka_di` barrel names (`Gateways.ts`, `Scenarios.ts`, …) are NOT branded: those files
+belong to the consumer and the folder already says whose they are.
+
+---
+
+Repository map: [../README.md](../README.md)

package/dist/ALankaGateway-ExlRGT3D.d.ts

@@ -0,0 +1,122 @@
+import { I as ILankaValidator } from './lankaStandardValidator-CL-r-zEV.js';
+
+/**
+ * Transport options plus what core controls.
+ *
+ * `signal` and `timeoutMs` are taken out and never reach the transport as given:
+ * core combines them into one signal and passes that.
+ */
+type TLankaExecuteOptions<TOptions> = TOptions & {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+
+/**
+ * What a gateway needs of a request: one method that sends and returns a value.
+ *
+ * The port, so a consumer can supply their OWN request rather than inheriting
+ * from ours. `ALankaRequest` implements it and remains the convenient way in —
+ * it brings middleware composition, deadline resolution, in-flight accounting
+ * and failure classification — but a consumer with a different transport story
+ * (a native bridge, an offline queue, a test double that never touches the
+ * network) needs none of that and should not have to extend a class to be
+ * accepted.
+ *
+ * `mockHandler` is part of the contract rather than an implementation detail: it
+ * is how development without a backend works, and a request that ignored it
+ * would silently disable mock mode for the gateway holding it.
+ */
+interface ILankaRequest<TOptions = RequestInit> {
+    /**
+     * Sends the request and returns the value the caller asked for.
+     *
+     * Rejects with a `LankaError` carrying a kind — `http`, `network`, `timeout`,
+     * `aborted`, `schema` — because the kind is what a caller branches on: a
+     * timeout is shown, a cancellation is not, and only a network failure invites
+     * a retry.
+     */
+    execute<TReturn = Response>(endpoint: string, options?: TLankaExecuteOptions<TOptions>, mockHandler?: () => Promise<TReturn>): Promise<TReturn>;
+}
+
+type TLankaQueryParams = string | number | boolean | null | undefined | TLankaQueryParams[] | {
+    [key: string]: TLankaQueryParams;
+};
+
+type TLankaQueryBuilder = (params: Record<string, TLankaQueryParams>) => URLSearchParams;
+
+interface IALankaGatewayConfig<TOptions> {
+    /**
+     * The request this gateway sends through. Defaults to `LankaFetchJsonRequest`.
+     *
+     * Each request kind has its own logic — one answers a parsed JSON body, another
+     * the raw `Response`, another uploads multipart — and JSON over `fetch` is what
+     * almost every gateway wants. So it is supplied when the gateway is NOT
+     * ordinary, and omitted otherwise.
+     *
+     * Typed as the PORT: `ALankaRequest` is the convenient implementation, not a
+     * requirement. A consumer with their own transport story supplies their own,
+     * and a test supplies one that never leaves the process.
+     */
+    request?: ILankaRequest<TOptions>;
+    /** Base API path for this gateway, e.g. "/admin/company" */
+    basePath?: string;
+    /**
+     * Serialises query parameters for every request of this gateway.
+     *
+     * An error-body handler does NOT belong here: it is given to the request —
+     * `new LankaFetchJsonRequest({ errorHandler })` — which is the only layer that
+     * reads it.
+     */
+    queryParamsHandler?: TLankaQueryBuilder;
+    /** Validation service (DI). May be replaced for tests / migration. */
+    validationService?: ILankaValidator;
+    /**
+     * Enable mock mode. If undefined, reads from infrastructure flags (isMockMode).
+     * If true, mock handlers passed to request methods will be used instead of real requests.
+     */
+    useMock?: boolean;
+}
+
+declare abstract class ALankaGateway<TOptions = RequestInit> {
+    protected requestExecutor: ILankaRequest<TOptions>;
+    protected queryParamsHandler: TLankaQueryBuilder;
+    protected readonly useMock: boolean;
+    protected readonly basePath: string;
+    protected constructor(config: IALankaGatewayConfig<TOptions>);
+    /**
+     * Resolves endpoint for request.
+     * - Absolute paths (starting with "/") are returned as-is
+     * - Relative paths are joined with basePath
+     * - Query-only strings like "?a=1" are attached to basePath
+     */
+    protected endpoint(path?: string): string;
+    /**
+     * Joins `basePath` and the method path.
+     */
+    private resolvePath;
+    /**
+     * Prefixes the API base URL from the host contract.
+     *
+     * Here rather than in every consumer: otherwise each consumer knows the URL
+     * and the framework does not, and a realtime plugin would have to know a
+     * specific application's build.
+     *
+     * Declaring the field and not using it would be worse than not declaring it: a
+     * declaration nothing is built from is a second truth, free to diverge from
+     * the first.
+     *
+     * An absolute URL never reaches here — `endpoint()` filters it out before the
+     * join.
+     */
+    private withApiBase;
+    protected buildQueryParams<T extends object>(params: T): URLSearchParams;
+    protected request<TReturn = unknown>(path: string, options?: TLankaExecuteOptions<TOptions>, mockHandler?: () => Promise<TReturn>): Promise<TReturn>;
+    /**
+     * Allows to replace request implementation at runtime (e.g. feature flags / tests).
+     * If you prefer static customization - override `request()` in a subclass.
+     */
+    protected setRequest(request: ILankaRequest<TOptions>): void;
+    protected setQueryParamsHandler(handler: TLankaQueryBuilder): void;
+}
+
+export { ALankaGateway as A, type IALankaGatewayConfig as I, type TLankaExecuteOptions as T, type ILankaRequest as a, type TLankaQueryBuilder as b, type TLankaQueryParams as c };

package/dist/ALankaSharedStore-B7uepuuk.d.ts

@@ -0,0 +1,29 @@
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * Base abstraction for shared feature stores.
+ *
+ * A store built on this class is resolved through the shared-store locator and
+ * reused across several ViewModels.
+ */
+declare abstract class ALankaSharedStore<TState extends object> {
+    private readonly api;
+    private readonly createInitialState;
+    protected constructor(createInitialState: () => TState);
+    getApi(): StoreApi<TState>;
+    getState(): TState;
+    setState(partial: TState | Partial<TState> | ((state: TState) => TState | Partial<TState>), replace?: boolean): void;
+    subscribe(listener: (state: TState, prevState: TState) => void): () => void;
+    /**
+     * Back to what the store was built with.
+     *
+     * Public, and it was not: while this was `protected` only a subclass could
+     * reset, so the class style had a capability the functional one could not
+     * reach — the asymmetry `skills/parity/SKILL.md` forbids. A shared store needs
+     * explicit reset points (see the ladder in `core/README.md`), and the
+     * application that owns them is outside the class either way.
+     */
+    reset(): void;
+}
+
+export { ALankaSharedStore as A };

package/dist/ILankaApiError-zI_2bNs0.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Structural API-error shape read by consumer code.
+ *
+ * `status` is OPTIONAL: a network drop and an aborted request carry no status,
+ * and three of the six `LankaError` kinds have none.
+ *
+ * `LankaError` implements this interface, so consumers may read `status` and
+ * `errors` off any thrown framework error.
+ */
+interface ILankaApiError {
+    status?: number;
+    errors?: string[];
+    message?: string;
+}
+
+export type { ILankaApiError as I };

package/dist/ILankaRuntimeConfig-Vl436GWK.d.ts

@@ -0,0 +1,62 @@
+interface ILankaFlags {
+    isMockMode?: boolean;
+    loggerEnabled?: boolean;
+    loggerGateway?: boolean;
+    loggerScenario?: boolean;
+    loggerViewModel?: boolean;
+    loggerView?: boolean;
+    loggerBootstrap?: boolean;
+    /** Comes from `import.meta.env.PROD` — silences all log output. */
+    isProduction?: boolean;
+    /** Comes from `import.meta.env.DEV` — enables development-only behaviour. */
+    isDevelopment?: boolean;
+}
+
+/**
+ * What the package needs from the HOSTING application and cannot know itself.
+ *
+ * A package cannot import its consumer, and should not: these are product
+ * decisions belonging to whoever owns the screens and the session.
+ *
+ * The fields are REQUIRED, and that is the point. None has a sensible default —
+ * a missing message factory would mean a wrong-language string in the interface,
+ * a missing base URL an `undefined` inside a request path. So omitting one is a
+ * TYPE ERROR in the app's own barrel rather than a surprise at runtime.
+ */
+interface ILankaHost {
+    /**
+     * What to show when a response carried a status but no message.
+     *
+     * ONE method rather than a map of seven: which statuses the app has copy for,
+     * and what it says for the rest, is the app's business. The package knows only
+     * that it has a number and needs a sentence.
+     */
+    httpErrorMessage(status: number): string;
+    /**
+     * API base URL — where the framework calls.
+     *
+     * In the contract because otherwise each consumer would know the URL and the
+     * framework would not, making `@lankajs/plugin-sse` impossible: it would
+     * have to know a specific application's build.
+     *
+     * Without a trailing slash — `ALankaGateway.endpoint()` normalises it.
+     */
+    apiBaseUrl: string;
+    /**
+     * What to say when the request never reached the server.
+     *
+     * `LankaError` separates `network` from `timeout` because the interface needs
+     * different things from them. How the app phrases each is not the framework's
+     * to guess.
+     */
+    networkErrorMessage(): string;
+    /** What to say when it arrived but no response came. */
+    timeoutErrorMessage(): string;
+}
+
+interface ILankaRuntimeConfig {
+    flags?: ILankaFlags;
+    host?: ILankaHost;
+}
+
+export type { ILankaFlags as I, ILankaHost as a, ILankaRuntimeConfig as b };

package/dist/ILankaScenarioMetadata-Bu-yggTZ.d.ts

@@ -0,0 +1,14 @@
+import { a as ILankaScenario } from './ILankaScenarioVM-DuCyPoyT.js';
+
+/**
+ * Metadata about a registered scenario
+ */
+interface ILankaScenarioMetadata {
+    scenario: ILankaScenario<unknown>;
+    name: string;
+    eventType: string;
+    dataTypeName: string;
+    isRegistered: boolean;
+}
+
+export type { ILankaScenarioMetadata as I };