lanka 1.2.0 → 2.0.0

package/skills/lanka-core/reference.md

@@ -1,10 +1,10 @@
 <!-- Generated from core/GUIDE.md by scripts/skills.mjs. Edit the guide. -->
 
-> **`lanka@1.2.0`** — this document describes that version.
+> **`lanka@2.0.0`** — this document describes that version.
 >
-> Install: `npm install lanka react zustand` (the peers are not optional; only npm adds a missing one for you).
+> Install: `npm install lanka zustand` (the peers are not optional; only npm adds a missing one for you).
 >
-> Complete code, compiled and run in CI: [core/_playground/playground.test.tsx](https://github.com/lankajs/lanka/blob/main/core/_playground/playground.test.tsx)
+> Complete code, compiled and run in CI: [core/_playground/playground.test.ts](https://github.com/lankajs/lanka/blob/main/core/_playground/playground.test.ts)
 
 # lanka — user guide
 
@@ -27,8 +27,31 @@ If you want to know _why_ the framework is shaped this way, read
 > required: [ARCHITECTURE.md](https://github.com/lankajs/lanka/blob/main/ARCHITECTURE.md) separates the five things the
 > machine checks from the many that are advice you can take or leave.
 
+## When to reach for this
+
+Every other package here is adopted one at a time; this one is the framework, so
+the question is the other way round. Reach for lanka when an application has
+SERVER STATE that several screens care about — a list one screen changes and
+another shows, a session two screens read, a fact that has to travel without one
+screen importing another. That is what the gateway, the ViewModel and the
+scenario bus are for, and it is the shape that gets expensive when it is left to
+grow by itself.
+
+Do not reach for it for a form, a landing page, or a screen that loads once and
+sits still: a `useState` and a `fetch` are the right size for those, and this
+framework would be four layers around nothing.
+
+It is not an application shell either. Your host framework — Next, React Router,
+TanStack Start, Astro, Expo — keeps routing, rendering and caching;
+[ARCHITECTURE.md](https://github.com/lankajs/lanka/blob/main/ARCHITECTURE.md#inside-another-framework) draws the line.
+
+It binds no UI framework of its own: core imports no UI library at all, and
+reading a ViewModel from a screen is one of the five packages in
+`modules/bindings/`.
+
 ## Contents
 
+- [When to reach for this](#when-to-reach-for-this)
 - [Install](#install)
 - [Your first application](#your-first-application)
 - [The layers, and which way imports go](#the-layers-and-which-way-imports-go)
@@ -60,16 +83,28 @@ If you want to know _why_ the framework is shaped this way, read
 ## Install
 
 ```bash
-npm  install lanka react react-dom zustand
-pnpm add     lanka react react-dom zustand
-yarn add     lanka react react-dom zustand
-bun  add     lanka react react-dom zustand
+npm  install lanka zustand
+pnpm add     lanka zustand
+yarn add     lanka zustand
+bun  add     lanka zustand
 ```
 
-**The peers are listed on purpose.** `react` 19 and `zustand` 5 are peer
-dependencies, and only npm installs those for you. Under pnpm, yarn or bun a
-missing peer is a warning at install time and a resolution error at build time —
-name them once and the question never comes up.
+**The peer is listed on purpose.** `zustand` 5 is core's one peer dependency,
+and only npm installs a missing peer for you. Under pnpm, yarn or bun it is a
+warning at install time and a resolution error at build time — name it once and
+the question never comes up.
+
+**No UI framework is in that line, and that is not an omission.** Core imports no
+UI library at all: a ViewModel is a store, a gateway is a function, and neither
+knows what renders. Reading a ViewModel from a screen is one package more, the
+one for your framework:
+
+```bash
+npm install @lankajs/react   # or @lankajs/vue, @lankajs/svelte, @lankajs/solid, @lankajs/angular
+```
+
+All five publish the same name — `useLankaVM` — so the guide you read for one
+is the guide for the next.
 
 > [!NOTE]
 > Any package manager works, and nothing in the framework knows which one you
@@ -439,16 +474,29 @@ Every failure that leaves a request is a `LankaError` with a **tagged kind**:
 | `domain`  | your own rule refused      | shows your message          |
 
 ```ts
-import { LankaError, createLankaApiError, handleLankaApiError } from "lanka/errors";
+import { LankaError, createLankaApiError } from "lanka/errors";
 
 try {
 	await gateway.list();
 } catch (error) {
-	if (error instanceof LankaError && error.kind === "aborted") return;
-	setError(handleLankaApiError(error));
+	if (!LankaError.is(error)) throw error; // not ours: let it go up
+	if (error.isSilent) return; // aborted — the user has already left
+	setError(error.message);
 }
 ```
 
+`error.message` is the sentence to show: your host wrote it for `network`,
+`timeout` and `http`, and your own code wrote it for `domain`. `isSilent` is the
+`aborted` check under a name that says what it is FOR — the interface shows
+nothing, because the person who cancelled knows they did.
+
+> [!NOTE]
+> `handleLankaApiError` is **not** this. It takes a `Response`, reads the body
+> once and throws the `LankaError` the rest of the application catches — it is
+> the default `errorHandler` of a request, and the place to pass one of your own:
+> `new LankaFetchJsonRequest({ errorHandler })`. It never returns, so nothing can
+> be assigned from it.
+
 Refuse locally with the same shape rather than a bare `throw`, so a screen has
 one failure shape to render:
 
@@ -580,20 +628,22 @@ export const useTodosVM = new TodosVM(gateway).build();
 The protected surface is exactly the factory's context — `set`, `get`,
 `gateways`, `services`, `trigger` — and that is enforced, not a convention. The
 overridable hooks are `states`, `createGateways`, `createServices`,
-`scenarioHandlers`, `enhancers`, `onInit`, `onReset` and `createActions`.
+`scenarioHandlers`, `enhancers`, `onInit`, `onReset` and `createActions`. One
+more protected member, `toLifecycleHooks`, is the framework's own reading of
+`onInit` and `onReset` — override those two, never it.
 
 ### Config reference
 
-| Field                              | Meaning                                             |
-| ---------------------------------- | --------------------------------------------------- |
-| `name`                             | Shown in logs and devtools. Required                |
-| `states`                           | The initial state. Omit for a stateless ViewModel   |
-| `createActions`                    | Receives the context, returns the actions           |
-| `gateways` / `services`            | An object or a factory; reachable as `gateways.x`   |
-| `scenarioHandlers`                 | `{ scenario, handler }` pairs, bound at bootstrap   |
-| `enhancers`                        | Store enhancers, zustand style                      |
-| `onInit` / `onReset`               | Lifecycle hooks over the same context               |
-| `enableAccessTrackingOptimization` | Default on; see [common mistakes](#common-mistakes) |
+| Field                              | Meaning                                                                                                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                             | Shown in logs and devtools. Required                                                                                                                                                                         |
+| `states`                           | The initial state. Omit for a stateless ViewModel                                                                                                                                                            |
+| `createActions`                    | Receives the context, returns the actions                                                                                                                                                                    |
+| `gateways` / `services`            | An object or a factory; reachable as `gateways.x`                                                                                                                                                            |
+| `scenarioHandlers`                 | `{ scenario, handler }` pairs, bound at bootstrap                                                                                                                                                            |
+| `enhancers`                        | Store enhancers, zustand style                                                                                                                                                                               |
+| `onInit` / `onReset`               | Lifecycle hooks over the same context. Declaring either enrols the ViewModel with scenario bootstrap: `onInit` runs when bootstrap binds it, `onReset` when the instance — or a lazy ViewModel — is disposed |
+| `enableAccessTrackingOptimization` | Default on; see [common mistakes](#common-mistakes)                                                                                                                                                          |
 
 ### Using one in a component
 
@@ -611,6 +661,48 @@ The hook re-renders a component only for the keys it actually **read**. That is
 usually free performance, and it has one blind spot, described at the end of this
 guide.
 
+### A selector that builds its answer
+
+Every binding also takes a selector, and then the selector decides instead of
+the tracking. A selector that **builds** what it answers has a trap in it:
+
+```ts
+useLankaVM(missionVM, (state) => ({ title: state.title, status: state.status }));
+```
+
+That object is new on every call, so it is never identical to the previous one,
+and a binding compares selections by identity. The reader is therefore woken by
+every change in the ViewModel — including the keys the selector exists to
+ignore. A selector answering a **primitive** never has the problem, which is what
+makes this quiet: the shape that is free and the shape that repaints on
+everything look the same on the page.
+
+`createLankaShallowHold` is the comparison that fixes it. It answers the
+**previous** object while nothing in the selection moved, one level deep — own
+keys, same count, `Object.is` on each value, arrays included:
+
+```ts
+import { createLankaShallowHold } from "lanka/viewmodel";
+
+const hold = createLankaShallowHold<{ title: string; status: string }>();
+
+const view = useLankaVM(missionVM, (state) => hold({ title: state.title, status: state.status }));
+```
+
+One hold per reader, created once beside the ViewModel read — never shared
+between two components, because the answer it holds belongs to whoever selected
+it.
+
+> [!NOTE]
+> In React, write `useLankaShallow` from `@lankajs/react` instead. It is the same
+> comparison as a hook, and React needs one: a component re-runs the hook on
+> every render, so the holding has to survive a render while the selector stays
+> the current one.
+
+A selection with a **nested** object wants a selector that picks the leaves.
+Comparing deeper would mean walking a state of unknown size on every read, which
+is the cost a selector was taken to avoid.
+
 ## Choosing a coordination tool
 
 When "A must affect B", one question decides it: **do A and B co-own a thing, or
@@ -770,25 +862,282 @@ Things worth knowing:
 - **Delivery iterates a copy** of the subscriber list, so a handler may
   unsubscribe itself mid-delivery. The deliberate consequence: subscribing
   _during_ delivery waits for the next event.
+- **A failing handler cannot take the dispatch down**, and that holds for an
+  async one too. A handler is typed `(data) => void`, but TypeScript assigns a
+  `Promise<void>` to a void return position — so `async () => { await refetch();
+}` compiles with nothing to warn about, and "refetch when the stream
+  reconnects" is the ordinary shape rather than an exotic one. Its rejection is
+  caught and written to the scenario log, not left to surface as an unhandled
+  rejection in whatever ran next.
+
+    What the framework cannot do is decide what the failure MEANT. A log line is a
+    diagnostic, not a retry and not a message on a screen — so an action called
+    from a handler should still own its own failure, because the handler returns
+    `void` and has nowhere to put one.
+
 - **Middleware returns a decision** — `"pass"` or `{ stop: reason }` — never
   `next()`. A middleware that forgot to call `next()` would make the event vanish
   silently, and a mechanism that exists for observability must not be its own
   blind spot. A stop is written to the event log; so is a throw.
 
+## Forms
+
+lanka ships no form library, the way it ships no router and no cache: React Hook
+Form, TanStack Form and Formik already exist and are better at it. What this
+section settles is the part nobody else can — **who owns what when your
+application brings one**, and what the framework hands it.
+
+### Start without one
+
+A ViewModel holds a screen's state, and a form's inputs are state. Give each
+input a key of its **own**:
+
+```ts
+createLankaVM<ILoginState, ILoginActions, { authGateway: AuthGateway }>({
+	name: "LoginVM",
+	states: { email: "", password: "", fieldErrors: [], screenError: null, isSubmitting: false },
+	gateways: () => ({ authGateway }),
+	createActions: ({ set }) => ({
+		setEmail: (email: string) => set({ email, fieldErrors: [] }),
+		// …
+	}),
+});
+```
+
+Flat keys matter: the hook tracks the state's **root** keys, so a component
+reading `email` re-renders when `email` moves and not when `password` does. One
+`values: { email, password }` object makes every keystroke everybody's, which is
+the whole cost a form library exists to remove — and here you get it for free.
+
+> [!TIP]
+> That is most screens. A sign-in, a filter, a settings page, a create form:
+> independent inputs, validation on submit, no dynamic rows.
+
+### Add a form library when the form grows its own behaviour
+
+| Reach for one when                                      | Why the ViewModel stops being enough           |
+| ------------------------------------------------------- | ---------------------------------------------- |
+| a field ARRAY — rows the user adds and removes          | rows force nesting, and nesting is not tracked |
+| validation on every keystroke                           | the whole object re-checked per character      |
+| one field's validity depends on another's value         | written by hand, it drifts                     |
+| `touched` / `dirty` / blur as behaviour, not decoration | three booleans per input in a screen's state   |
+| the screen is server-rendered WITH values               | see the warning at the end of this section     |
+
+Not on the list: how many forms the application has. A big application of flat
+forms needs nothing; one wizard with dynamic rows does.
+
+### The boundary
+
+|                                                              | Owner                                                               |
+| ------------------------------------------------------------ | ------------------------------------------------------------------- |
+| values, `touched`/`dirty`, focus, per-input messages         | the **form**                                                        |
+| `isSubmitting`                                               | the form — unless it is visible outside the form (a global overlay) |
+| `defaultValues`                                              | the ViewModel: the server's version, held as `server`               |
+| calling the gateway, `trigger`, clearing a draft, navigating | the **ViewModel**                                                   |
+| an input's ASYNCHRONOUS check                                | a ViewModel action — a resolver may not call a gateway              |
+| failures with an address                                     | pass through the ViewModel to the form                              |
+| failures without one                                         | the ViewModel's own state                                           |
+
+The last row is the interesting one, and the two before it are why a form cannot
+be left to talk to the network itself.
+
+### One schema, three readers
+
+The validation port speaks [Standard Schema](https://standardschema.dev), and so
+do React Hook Form (through `@hookform/resolvers`) and TanStack Form. **The same
+schema object is the form's resolver and the gateway's payload check** — there is
+no adapter to write and nothing declared twice.
+
+Keep the INPUT schema apart from the response ones. A form given the response
+schema asks for an `id` and an `updatedAt` the user does not have:
+
+| Schema       | Read by                                                 | Changes when                   |
+| ------------ | ------------------------------------------------------- | ------------------------------ |
+| `orderWire`  | the gateway, on the way in                              | the backend changes            |
+| `order`      | the gateway, the domain check                           | the application does           |
+| `orderInput` | **the form's resolver AND the gateway's payload check** | what a person may type changes |
+
+### A failure that knows which input it belongs to
+
+`LankaError.issues` is a flat list for a banner — `items.1.qty: only 2 left`. A
+form needs the address instead of the sentence, so a failure also carries
+`fields`, and `readLankaFieldErrors` reads them off anything:
+
+```ts
+import { readLankaFieldErrors } from "lanka/errors";
+// → readonly ILankaFieldError[]: { path: ["items", 1, "qty"], message, code? }
+```
+
+The path stays in **segments**. React Hook Form writes that address
+`items.1.qty`, TanStack Form writes `items[1].qty`, and a joined string cannot be
+taken apart again — a message may contain a colon, a key may contain a dot. An
+**empty** path is the value as a whole: a cross-field refusal ("the dates are in
+the wrong order"), which belongs to the form's root and not to an input named
+`""`.
+
+`lankaStandardValidator` fills `fields` from a schema's issues. A server's `422`
+is your backend's shape, so the gateway — or `@lankajs/plugin-http`, where body
+parsing is configured once — turns it into the same list.
+
+### Which failure goes where
+
+The kinds already say what each demands of an interface; a submit action reads
+them and answers the form. Write this once and call it from every submit:
+
+```ts
+type TSubmitOutcome<TData> =
+	| { ok: true; data: TData }
+	| { ok: false; fields: readonly ILankaFieldError[]; message?: string };
+
+const sortFailure = (error: unknown, toScreen: (m: string) => void): TSubmitOutcome<never> => {
+	if (!LankaError.is(error)) throw error;
+	if (error.isSilent) return { ok: false, fields: [] }; // aborted: the user left
+
+	const fields = readLankaFieldErrors(error);
+	if (fields.length > 0) return { ok: false, fields }; // it has an address
+	if (error.kind === "domain") return { ok: false, fields: [], message: error.message };
+
+	toScreen(error.message); // network, timeout, 5xx, schema — the screen's
+	return { ok: false, fields: [] };
+};
+```
+
+The framework publishes the reading (`readLankaFieldErrors`) and leaves the
+sorting to you, because which refusal your application shows under an input is
+your decision, not a framework's.
+
+**The form never sees a `LankaError`.** It does not know what a transport is.
+
+### The order after a save succeeds
+
+```ts
+const order = await gateways.orderGateway.update(id, values);
+
+set({ server: order, serverChangedAt: null }); // 1. mark your own write
+trigger(orderUpdated, { order }); // 2. announce it, WITH the data
+services.cache?.write(["order", id], order); // 3. tell a cache, if you have one
+return { ok: true, data: order }; // 4. the form is still mounted here
+// 5. navigate — after this returns
+```
+
+Step 1 before step 2 is the rule: a handler that hears its own save must
+recognise it and stay quiet. Compare by `id` and a version, never by reference.
+Step 4 before step 5 so the form is alive to be told.
+
+### While the form is open, nothing writes into it
+
+A scenario or a push can arrive mid-edit. **A scenario handler must not touch the
+fields** — it replaces the server's version and MARKS it:
+
+```ts
+scenarioHandlers: [
+	{
+		scenario: orderUpdated,
+		handler: ({ get, set }) => (data) => {
+			if (!data || data.order.updatedAt === get().server?.updatedAt) return;
+			set({ server: data.order, serverChangedAt: data.order.updatedAt });
+		},
+	},
+],
+```
+
+The screen then offers "this changed — reload", and the person decides. Resetting
+the form automatically erases what they were typing; ignoring the change hands
+them a conflict on save. The same rule holds when the inputs live in the
+ViewModel, where breaking it is merely easier.
+
+### The adapter, per library
+
+Ten lines, written once per application, and the only thing in them that is
+library-specific is how it spells an address.
+
+**React Hook Form** — the resolver is your schema:
+
+```tsx
+const form = useForm({ defaultValues: initial, resolver: standardSchemaResolver(orderInput) });
+
+const onSubmit = form.handleSubmit(async (values) => {
+	const outcome = await submit(values);
+	if (outcome.ok) return form.reset(values);
+
+	for (const field of outcome.fields) {
+		form.setError(field.path.length === 0 ? "root" : field.path.join("."), {
+			message: field.message,
+		});
+	}
+	if (outcome.message) form.setError("root", { message: outcome.message });
+});
+```
+
+**TanStack Form** — reads Standard Schema itself, and the server's answer is the
+return value of an async submit validator:
+
+```ts
+useForm({
+	defaultValues: initial,
+	validators: {
+		onSubmit: orderInput,
+		onSubmitAsync: async ({ value }) => {
+			const outcome = await submit(value);
+			if (outcome.ok) return undefined;
+
+			return {
+				form: outcome.message,
+				fields: Object.fromEntries(
+					outcome.fields
+						.filter((field) => field.path.length > 0)
+						.map((field) => [toBracketAddress(field.path), field.message]),
+				),
+			};
+		},
+	},
+});
+```
+
+**Formik** — no Standard Schema, and it does not need one: the port already
+answered `fields`, and Formik's nested error object folds from them.
+
+```ts
+validate: (values) => {
+	const checked = lankaStandardValidator.validateSafe(orderInput, values);
+	if (checked.success) return {};
+
+	return (checked.fields ?? []).reduce(
+		(errors, field) => setIn(errors, field.path.join("."), field.message),
+		{},
+	);
+},
+```
+
+A hand-written form implements the same two shapes and takes no dependency on
+lanka at all: a Standard Schema in, `ILankaFieldError[]` out.
+
+> [!WARNING]
+> **Under SSR, form values must not live in a ViewModel.** A ViewModel is a store
+> created at module level — one per PROCESS, which on a server is one shared by
+> every request — and `hydrateLankaVM` applies once per store. An empty form is
+> fine; an edit form pre-filled on the server is not. Use a form library there,
+> or `useState` in the component with the values passed to the action.
+
+> [!NOTE]
+> Moving a screen from the first shape to the second changes two things: where
+> the values live, and that the action takes them as an argument. The schema, the
+> gateway, the failure sorting and the scenarios are untouched.
+
 ## Streams — a change that arrives from the server
 
 `lanka/stream` is the protocol-free half of realtime: what is the same whether
 the wire is server-sent events, a WebSocket, a GraphQL subscription or a gRPC
 server stream.
 
-| Name                              | What it is                                                      |
-| --------------------------------- | ---------------------------------------------------------------- |
+| Name                              | What it is                                                            |
+| --------------------------------- | --------------------------------------------------------------------- |
 | `ILankaServerEventTransport`      | the port: `isSupported`, `connect`, `disconnect`, `on`, `onReconnect` |
-| `ALankaStreamBridge`              | a wire event → one of your scenarios                            |
-| `createLankaStreamBridge`         | the same, written by calling                                     |
-| `createLankaStreamTriggerContext` | the "this came from outside" marker                              |
-| `ALankaStreamTransport`           | the base a transport extends: dispatch, and the reconnect ladder |
-| `lankaStream`                     | the plugin: bridges attached, lifetime owned                     |
+| `ALankaStreamBridge`              | a wire event → one of your scenarios                                  |
+| `createLankaStreamBridge`         | the same, written by calling                                          |
+| `createLankaStreamTriggerContext` | the "this came from outside" marker                                   |
+| `ALankaStreamTransport`           | the base a transport extends: dispatch, and the reconnect ladder      |
+| `lankaStream`                     | the plugin: bridges attached, lifetime owned                          |
 
 You normally reach these through a protocol package —
 [`@lankajs/plugin-sse`](https://github.com/lankajs/lanka/blob/main/plugins/sse/GUIDE.md),
@@ -831,7 +1180,7 @@ the backoff ladder with its attempt ceiling and one auth refresh, and
 `onReconnect`. A subclass writes `open` and `close`, and reports through three
 handlers — `opened`, `received`, `lost`. Nothing else, and deliberately: the bug
 this shape is prone to is resetting the attempt counter where reconnection
-*starts* rather than where it *succeeds*, after which the ceiling exists, reads
+_starts_ rather than where it _succeeds_, after which the ceiling exists, reads
 as a guard, and can never fire.
 
 ## The locator
@@ -1038,7 +1387,7 @@ npx lanka-skills sync
 
 ### The modules and plugins
 
-Twenty-one more packages solve problems you may or may not have — four wire
+Thirty-seven more packages solve problems you may or may not have — four wire
 protocols, retry policy, optimistic updates, list handling, storage,
 prefetching. The table of
 "add it when" is in [ARCHITECTURE.md](https://github.com/lankajs/lanka/blob/main/ARCHITECTURE.md#adopting-the-packages),
@@ -1137,6 +1486,40 @@ runtime. `startLanka` — or `createLanka` — comes first.
 or the ViewModel was constructed after it: bootstrap binds what exists when it
 runs.
 
+**A scenario handler from an earlier TEST that fires when it should not.** The
+mirror image, and it only appears in test suites that build ViewModels inside
+test bodies rather than at module level.
+
+A ViewModel declares itself to the scenario layer when it is built, and the
+declaration deliberately outlives the instance: the next `createLanka` has to
+re-adopt every module-level ViewModel, or a second instance in one process would
+know none of them.
+
+So `lankaScenarioBootstrap.reset()` clears subscriptions but NOT declarations,
+and the next `bootstrap()` re-adopts everything ever built in that process. A
+ViewModel from a finished test hears the next test's facts and runs its handlers
+against the gateway IT was built with. The symptom is never "a stale subscriber":
+it is one extra call on a double, or a rejection surfacing in a test that already
+passed.
+
+```ts
+beforeEach(() => {
+	lankaScenarioBootstrap.reset({ withDeclarations: true });
+});
+```
+
+That is the fix, and it is opt-in on purpose: the default is what an application
+needs, and a suite whose ViewModels all live at module level should keep it —
+forgetting them would leave their handlers bound to nothing. Forgetting is not a
+tombstone, so a ViewModel declared again afterwards is adopted again.
+
+Two habits make a suite immune even where a reset is missed:
+
+- give each ViewModel its own double, so a stale one calling its own mock cannot
+  disturb the counts a live test asserts on;
+- let an action own its failure rather than rejecting at a handler — a handler
+  returns `void` and has nowhere to put a rejection.
+
 **Reading state through a getter and wondering why the screen froze.** A consumer
 re-renders only for the keys it _read through the proxy_. If a component's only
 link to `todos` goes through a getter that calls `get()` internally, that read