@lankajs/svelte 0.1.0

package/dist/wrapper-scaffold-3RO7M4FF.js

@@ -0,0 +1,39 @@
+import "./chunk-5WRI5ZAA.js";
+
+// ../../../node_modules/.pnpm/@testing-library+svelte-cor_4dd48ea7741982ca29c6e300d35ac45b/node_modules/@testing-library/svelte-core/src/wrapper-scaffold.svelte
+import "svelte/internal/disclose-version";
+import * as $ from "svelte/internal/client";
+function Wrapper_scaffold($$anchor, $$props) {
+  $.push($$props, true);
+  let wrapperInstance = $.state(void 0);
+  let componentInstance = $.state(void 0);
+  const getWrapper = () => $.get(wrapperInstance);
+  const getComponent = () => $.get(componentInstance);
+  const getComponentProps = () => $$props.componentProps;
+  var $$exports = { getWrapper, getComponent, getComponentProps };
+  var fragment = $.comment();
+  var node = $.first_child(fragment);
+  $.component(node, () => $$props.wrapper, ($$anchor2, Wrapper_1) => {
+    $.bind_this(
+      Wrapper_1($$anchor2, $.spread_props(() => $$props.wrapperProps, {
+        children: ($$anchor3, $$slotProps) => {
+          var fragment_1 = $.comment();
+          var node_1 = $.first_child(fragment_1);
+          $.component(node_1, () => $$props.component, ($$anchor4, Component_1) => {
+            $.bind_this(Component_1($$anchor4, $.spread_props(() => $$props.componentProps)), ($$value) => $.set(componentInstance, $$value, true), () => $.get(componentInstance));
+          });
+          $.append($$anchor3, fragment_1);
+        },
+        $$slots: { default: true }
+      })),
+      ($$value) => $.set(wrapperInstance, $$value, true),
+      () => $.get(wrapperInstance)
+    );
+  });
+  $.append($$anchor, fragment);
+  return $.pop($$exports);
+}
+export {
+  Wrapper_scaffold as default
+};
+//# sourceMappingURL=wrapper-scaffold-3RO7M4FF.js.map

package/dist/wrapper-scaffold-3RO7M4FF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../node_modules/.pnpm/@testing-library+svelte-cor_4dd48ea7741982ca29c6e300d35ac45b/node_modules/@testing-library/svelte-core/src/wrapper-scaffold.svelte"],"sourcesContent":["import 'svelte/internal/disclose-version';\nimport * as $ from 'svelte/internal/client';\n\nexport default function Wrapper_scaffold($$anchor, $$props) {\n\t$.push($$props, true);\n\n\tlet wrapperInstance = $.state(void 0);\n\tlet componentInstance = $.state(void 0);\n\tconst getWrapper = () => $.get(wrapperInstance);\n\tconst getComponent = () => $.get(componentInstance);\n\tconst getComponentProps = () => $$props.componentProps;\n\tvar $$exports = { getWrapper, getComponent, getComponentProps };\n\tvar fragment = $.comment();\n\tvar node = $.first_child(fragment);\n\n\t$.component(node, () => $$props.wrapper, ($$anchor, Wrapper_1) => {\n\t\t$.bind_this(\n\t\t\tWrapper_1($$anchor, $.spread_props(() => $$props.wrapperProps, {\n\t\t\t\tchildren: ($$anchor, $$slotProps) => {\n\t\t\t\t\tvar fragment_1 = $.comment();\n\t\t\t\t\tvar node_1 = $.first_child(fragment_1);\n\n\t\t\t\t\t$.component(node_1, () => $$props.component, ($$anchor, Component_1) => {\n\t\t\t\t\t\t$.bind_this(Component_1($$anchor, $.spread_props(() => $$props.componentProps)), ($$value) => $.set(componentInstance, $$value, true), () => $.get(componentInstance));\n\t\t\t\t\t});\n\n\t\t\t\t\t$.append($$anchor, fragment_1);\n\t\t\t\t},\n\t\t\t\t$$slots: { default: true }\n\t\t\t})),\n\t\t\t($$value) => $.set(wrapperInstance, $$value, true),\n\t\t\t() => $.get(wrapperInstance)\n\t\t);\n\t});\n\n\t$.append($$anchor, fragment);\n\n\treturn $.pop($$exports);\n}"],"mappings":";;;AAAA,OAAO;AACP,YAAY,OAAO;AAEJ,SAAR,iBAAkC,UAAU,SAAS;AAC3D,EAAE,OAAK,SAAS,IAAI;AAEpB,MAAI,kBAAoB,QAAM,MAAM;AACpC,MAAI,oBAAsB,QAAM,MAAM;AACtC,QAAM,aAAa,MAAQ,MAAI,eAAe;AAC9C,QAAM,eAAe,MAAQ,MAAI,iBAAiB;AAClD,QAAM,oBAAoB,MAAM,QAAQ;AACxC,MAAI,YAAY,EAAE,YAAY,cAAc,kBAAkB;AAC9D,MAAI,WAAa,UAAQ;AACzB,MAAI,OAAS,cAAY,QAAQ;AAEjC,EAAE,YAAU,MAAM,MAAM,QAAQ,SAAS,CAACA,WAAU,cAAc;AACjE,IAAE;AAAA,MACD,UAAUA,WAAY,eAAa,MAAM,QAAQ,cAAc;AAAA,QAC9D,UAAU,CAACA,WAAU,gBAAgB;AACpC,cAAI,aAAe,UAAQ;AAC3B,cAAI,SAAW,cAAY,UAAU;AAErC,UAAE,YAAU,QAAQ,MAAM,QAAQ,WAAW,CAACA,WAAU,gBAAgB;AACvE,YAAE,YAAU,YAAYA,WAAY,eAAa,MAAM,QAAQ,cAAc,CAAC,GAAG,CAAC,YAAc,MAAI,mBAAmB,SAAS,IAAI,GAAG,MAAQ,MAAI,iBAAiB,CAAC;AAAA,UACtK,CAAC;AAED,UAAE,SAAOA,WAAU,UAAU;AAAA,QAC9B;AAAA,QACA,SAAS,EAAE,SAAS,KAAK;AAAA,MAC1B,CAAC,CAAC;AAAA,MACF,CAAC,YAAc,MAAI,iBAAiB,SAAS,IAAI;AAAA,MACjD,MAAQ,MAAI,eAAe;AAAA,IAC5B;AAAA,EACD,CAAC;AAED,EAAE,SAAO,UAAU,QAAQ;AAE3B,SAAS,MAAI,SAAS;AACvB;","names":["$$anchor"]}

package/dist/wrapper-scaffold-legacy-UQDPD4HL.js

@@ -0,0 +1,48 @@
+import "./chunk-5WRI5ZAA.js";
+
+// ../../../node_modules/.pnpm/@testing-library+svelte-cor_4dd48ea7741982ca29c6e300d35ac45b/node_modules/@testing-library/svelte-core/src/wrapper-scaffold-legacy.svelte
+import "svelte/internal/disclose-version";
+import "svelte/internal/flags/legacy";
+import * as $ from "svelte/internal/client";
+function Wrapper_scaffold_legacy($$anchor, $$props) {
+  $.push($$props, false);
+  let wrapper = $.prop($$props, "wrapper", 8);
+  let wrapperProps = $.prop($$props, "wrapperProps", 8);
+  let component2 = $.prop($$props, "component", 8);
+  let componentProps = $.prop($$props, "componentProps", 8);
+  let wrapperInstance = $.mutable_source();
+  let componentInstance = $.mutable_source();
+  const getWrapper = () => $.get(wrapperInstance);
+  const getComponent = () => $.get(componentInstance);
+  const getComponentProps = () => componentProps();
+  var $$exports = { getWrapper, getComponent, getComponentProps };
+  var fragment = $.comment();
+  var node = $.first_child(fragment);
+  $.component(node, wrapper, ($$anchor2, $$component) => {
+    $.bind_this(
+      $$component($$anchor2, $.spread_props(wrapperProps, {
+        children: ($$anchor3, $$slotProps) => {
+          var fragment_1 = $.comment();
+          var node_1 = $.first_child(fragment_1);
+          $.component(node_1, component2, ($$anchor4, $$component2) => {
+            $.bind_this($$component2($$anchor4, $.spread_props(componentProps, { $$legacy: true })), ($$value) => $.set(componentInstance, $$value), () => $.get(componentInstance));
+          });
+          $.append($$anchor3, fragment_1);
+        },
+        $$slots: { default: true },
+        $$legacy: true
+      })),
+      ($$value) => $.set(wrapperInstance, $$value),
+      () => $.get(wrapperInstance)
+    );
+  });
+  $.append($$anchor, fragment);
+  $.bind_prop($$props, "getWrapper", getWrapper);
+  $.bind_prop($$props, "getComponent", getComponent);
+  $.bind_prop($$props, "getComponentProps", getComponentProps);
+  return $.pop($$exports);
+}
+export {
+  Wrapper_scaffold_legacy as default
+};
+//# sourceMappingURL=wrapper-scaffold-legacy-UQDPD4HL.js.map

package/dist/wrapper-scaffold-legacy-UQDPD4HL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../node_modules/.pnpm/@testing-library+svelte-cor_4dd48ea7741982ca29c6e300d35ac45b/node_modules/@testing-library/svelte-core/src/wrapper-scaffold-legacy.svelte"],"sourcesContent":["import 'svelte/internal/disclose-version';\nimport 'svelte/internal/flags/legacy';\nimport * as $ from 'svelte/internal/client';\n\nexport default function Wrapper_scaffold_legacy($$anchor, $$props) {\n\t$.push($$props, false);\n\n\tlet wrapper = $.prop($$props, 'wrapper', 8);\n\tlet wrapperProps = $.prop($$props, 'wrapperProps', 8);\n\tlet component = $.prop($$props, 'component', 8);\n\tlet componentProps = $.prop($$props, 'componentProps', 8);\n\tlet wrapperInstance = $.mutable_source();\n\tlet componentInstance = $.mutable_source();\n\tconst getWrapper = () => $.get(wrapperInstance);\n\tconst getComponent = () => $.get(componentInstance);\n\tconst getComponentProps = () => componentProps();\n\tvar $$exports = { getWrapper, getComponent, getComponentProps };\n\tvar fragment = $.comment();\n\tvar node = $.first_child(fragment);\n\n\t$.component(node, wrapper, ($$anchor, $$component) => {\n\t\t$.bind_this(\n\t\t\t$$component($$anchor, $.spread_props(wrapperProps, {\n\t\t\t\tchildren: ($$anchor, $$slotProps) => {\n\t\t\t\t\tvar fragment_1 = $.comment();\n\t\t\t\t\tvar node_1 = $.first_child(fragment_1);\n\n\t\t\t\t\t$.component(node_1, component, ($$anchor, $$component) => {\n\t\t\t\t\t\t$.bind_this($$component($$anchor, $.spread_props(componentProps, { $$legacy: true })), ($$value) => $.set(componentInstance, $$value), () => $.get(componentInstance));\n\t\t\t\t\t});\n\n\t\t\t\t\t$.append($$anchor, fragment_1);\n\t\t\t\t},\n\t\t\t\t$$slots: { default: true },\n\t\t\t\t$$legacy: true\n\t\t\t})),\n\t\t\t($$value) => $.set(wrapperInstance, $$value),\n\t\t\t() => $.get(wrapperInstance)\n\t\t);\n\t});\n\n\t$.append($$anchor, fragment);\n\t$.bind_prop($$props, 'getWrapper', getWrapper);\n\t$.bind_prop($$props, 'getComponent', getComponent);\n\t$.bind_prop($$props, 'getComponentProps', getComponentProps);\n\n\treturn $.pop($$exports);\n}"],"mappings":";;;AAAA,OAAO;AACP,OAAO;AACP,YAAY,OAAO;AAEJ,SAAR,wBAAyC,UAAU,SAAS;AAClE,EAAE,OAAK,SAAS,KAAK;AAErB,MAAI,UAAY,OAAK,SAAS,WAAW,CAAC;AAC1C,MAAI,eAAiB,OAAK,SAAS,gBAAgB,CAAC;AACpD,MAAIA,aAAc,OAAK,SAAS,aAAa,CAAC;AAC9C,MAAI,iBAAmB,OAAK,SAAS,kBAAkB,CAAC;AACxD,MAAI,kBAAoB,iBAAe;AACvC,MAAI,oBAAsB,iBAAe;AACzC,QAAM,aAAa,MAAQ,MAAI,eAAe;AAC9C,QAAM,eAAe,MAAQ,MAAI,iBAAiB;AAClD,QAAM,oBAAoB,MAAM,eAAe;AAC/C,MAAI,YAAY,EAAE,YAAY,cAAc,kBAAkB;AAC9D,MAAI,WAAa,UAAQ;AACzB,MAAI,OAAS,cAAY,QAAQ;AAEjC,EAAE,YAAU,MAAM,SAAS,CAACC,WAAU,gBAAgB;AACrD,IAAE;AAAA,MACD,YAAYA,WAAY,eAAa,cAAc;AAAA,QAClD,UAAU,CAACA,WAAU,gBAAgB;AACpC,cAAI,aAAe,UAAQ;AAC3B,cAAI,SAAW,cAAY,UAAU;AAErC,UAAE,YAAU,QAAQD,YAAW,CAACC,WAAUC,iBAAgB;AACzD,YAAE,YAAUA,aAAYD,WAAY,eAAa,gBAAgB,EAAE,UAAU,KAAK,CAAC,CAAC,GAAG,CAAC,YAAc,MAAI,mBAAmB,OAAO,GAAG,MAAQ,MAAI,iBAAiB,CAAC;AAAA,UACtK,CAAC;AAED,UAAE,SAAOA,WAAU,UAAU;AAAA,QAC9B;AAAA,QACA,SAAS,EAAE,SAAS,KAAK;AAAA,QACzB,UAAU;AAAA,MACX,CAAC,CAAC;AAAA,MACF,CAAC,YAAc,MAAI,iBAAiB,OAAO;AAAA,MAC3C,MAAQ,MAAI,eAAe;AAAA,IAC5B;AAAA,EACD,CAAC;AAED,EAAE,SAAO,UAAU,QAAQ;AAC3B,EAAE,YAAU,SAAS,cAAc,UAAU;AAC7C,EAAE,YAAU,SAAS,gBAAgB,YAAY;AACjD,EAAE,YAAU,SAAS,qBAAqB,iBAAiB;AAE3D,SAAS,MAAI,SAAS;AACvB;","names":["component","$$anchor","$$component"]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lankajs/svelte",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "module: One function — `useLankaVM` — over `createSubscriber`, and the access tracking core already does.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lankajs/lanka.git",
+    "directory": "modules/bindings/svelte"
+  },
+  "homepage": "https://github.com/lankajs/lanka/tree/main/modules/bindings/svelte#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "skills"
+  ],
+  "dependencies": {
+    "lanka": "^2.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/svelte": "^5.4.2",
+    "@lankajs/tool-testing": "^2.0.0"
+  },
+  "peerDependencies": {
+    "svelte": "^5.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/svelte": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint src _playground --max-warnings=0",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "bench": "vitest bench --run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/lanka-svelte/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: lanka-svelte
+description: Read a lanka ViewModel from a Svelte 5 component with useLankaVM, select one value through `.current`, or satisfy the `svelte/store` contract with toLankaSvelteVM so `$todos` works. Use when writing or reviewing a Svelte or SvelteKit screen in a lanka application, when markup does not update after state changed, when a selector wakes on every change, when a store helper refuses a ViewModel, or when reviewing code that imports `@lankajs/svelte`.
+license: MIT
+metadata:
+    author: lankajs
+    package: @lankajs/svelte
+    version: "0.1.0"
+---
+
+# @lankajs/svelte
+
+One call to read a ViewModel, and the store contract for the half of Svelte that
+still speaks it. `reference.md` beside this file is the full guide.
+
+> [!NOTE]
+> Only what the framework or a gate refuses is binding. Everything else here is a
+> recommendation you can adapt.
+
+## Pick the call
+
+| The situation                                     | Use                                                     |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| a component reads a ViewModel                     | `useLankaVM(todoVM)` — an object of getters             |
+| it needs one derived value                        | `useLankaVM(todoVM, (s) => s.rows.length)` → `.current` |
+| `derived`, `get`, a `$` prefix, a SvelteKit store | `toLankaSvelteVM(todoVM)`                               |
+| outside a component — a handler, a module         | `todoVM.getState()`                                     |
+| a component test                                  | `renderWithLanka` from `@lankajs/svelte/testing`        |
+
+```svelte
+<script lang="ts">
+	import { useLankaVM } from "@lankajs/svelte";
+	import { todoVM } from "./todoVM";
+
+	const state = useLankaVM(todoVM);
+</script>
+
+{#if state.isLoading}
+	<p>loading</p>
+{:else}
+	<ul onclick={() => state.load()}>
+		{#each state.todos as todo (todo.id)}
+			<li>{todo.title}</li>
+		{/each}
+	</ul>
+{/if}
+```
+
+It answers **an object whose properties are getters** — Svelte 5's own shape, and
+the one thing the shelf does not make uniform. A read registers with the
+reactivity graph and with the access tracker in ONE access, so nothing needs a
+`$`. `const` is right: the object never changes, its getters do.
+
+**No compiler and no extra plugin.** `createSubscriber` from `svelte/reactivity`
+is a runtime function, so this package is plain TypeScript.
+
+## Selecting one value
+
+```svelte
+<script lang="ts">
+	const count = useLankaVM(todoVM, (state) => state.rows.length);
+</script>
+
+<p>{count.current}</p>
+```
+
+`current` is Svelte's own convention for a reactive value, the way `MediaQuery`
+and the rest of `svelte/reactivity` read. Any selector, including one answering a
+number.
+
+The reader wakes when the **selection** moves, compared with `Object.is` — so a
+selector building a fresh object every call is a reader saying it depends on
+everything. Pick the leaves instead.
+
+## The store contract, when you want `$`
+
+```svelte
+<script lang="ts">
+	import { toLankaSvelteVM } from "@lankajs/svelte";
+	const todos = toLankaSvelteVM(todoVM);
+</script>
+
+{#each $todos.rows as row}<li>{row}</li>{/each}
+```
+
+`run` is called immediately and synchronously, so `$todos` is never `undefined`
+on the first render, and `derived`, `get` and every other `svelte/store` helper
+accept it. Each subscriber gets its own recording.
+
+Reach for it when something else demands the contract — a `derived`, a `get`, a
+codebase that has not moved to runes. `useLankaVM` is the default, because a
+plain read is what every other binding on the shelf writes.
+
+## What re-renders
+
+Without a selector the view RECORDS which keys you read, and the next change
+repaints only if one of those moved. With a selector, the selector decides and
+tracking is bypassed.
+
+> [!WARNING]
+> **The blind spot.** Tracking sees keys you read DIRECTLY. A key reached only
+> inside a derived getter is invisible to it, so a change to that key repaints
+> nothing and the screen freezes with no error. Set
+> `enableAccessTrackingOptimization: false` on such a ViewModel. Do NOT read the
+> underlying keys in the markup "for the side effect": that is dead code, and a
+> refactor or a lint autofix removes it. In development the framework announces
+> the mismatch by ViewModel and key name.
+
+## Releasing the subscription
+
+`createSubscriber` releases it when the last effect reading the view is
+destroyed, which is every case inside a component. A read where there is no
+effect at all — a module-level snapshot, a script, a test — has none, so the view
+carries `stop()` and you own it.
+
+## Testing
+
+```ts
+import { renderWithLanka } from "@lankajs/svelte/testing";
+
+renderWithLanka(TodoScreen, {
+	fakes: { gateways: { TodoGateway: { list: () => Promise.resolve([]) } } },
+});
+```
+
+Every call gets a fresh instance and disposes the previous one.
+
+## A selector that builds an object
+
+A selector answering a fresh object is never identical to its own last answer,
+so the reader wakes for EVERY change in the ViewModel — including the keys the
+selector exists to ignore. Hold it:
+
+```ts
+import { createLankaShallowHold } from "lanka/viewmodel";
+
+const hold = createLankaShallowHold<{ title: string }>();
+const mission = useLankaVM(missionVM, (s) => hold({ title: s.title }));
+```
+
+One hold per reader, declared in the component script — never at module level and never
+shared between two components. A selector answering a **primitive** needs none
+of this. The comparison is one level deep: own keys, same count, `Object.is` on
+each value, arrays included.
+
+## Never do these
+
+- **Never pass an object-building selector without a hold.** The reader then
+  wakes for every change in the ViewModel, selector or no selector.
+- **Never destructure the view.** `const { rows } = state` reads the getter once
+  and the value stops tracking; keep reading through `state.rows`.
+- **Never look for `.current` without a selector.** The plain call answers the
+  getters directly; `current` is the selected shape only.
+- **Never build a fresh object in a selector.** `Object.is` then says it changed
+  every time, and the reader wakes on everything.
+- **Never leave a read outside an effect unstopped.** A module-level or script
+  read has no effect to hang on, so nothing releases the subscription but you.
+- **Never reach for `$` by default.** `toLankaSvelteVM` is for the store
+  contract; a plain read is the spelling the rest of the shelf shares.
+
+## Symptom → cause
+
+| What you see                                      | What it is                                      |
+| ------------------------------------------------- | ----------------------------------------------- |
+| a screen repainting for changes it never selected | an object selector with no hold                 |
+| the first paint is right, nothing updates         | the view was destructured                       |
+| `undefined` from a selected read                  | `.current` missing                              |
+| a reader waking on every change                   | a selector returning a fresh object             |
+| `derived` or `get` refuses the ViewModel          | it wants the store contract — `toLankaSvelteVM` |
+| a subscription that outlives the test             | a read with no effect, `stop()` never called    |
+
+## More
+
+`reference.md` — the full guide: the tracking rules, the store contract in
+detail, and what this package deliberately is not.

package/skills/lanka-svelte/reference.md

@@ -0,0 +1,247 @@
+<!-- Generated from modules/bindings/svelte/GUIDE.md by scripts/skills.mjs. Edit the guide. -->
+
+> **`@lankajs/svelte@0.1.0`** — this document describes that version.
+>
+> Install: `npm install @lankajs/svelte svelte zustand` (the peers are not optional; only npm adds a missing one for you).
+>
+> Complete code, compiled and run in CI: [modules/bindings/svelte/_playground/playground.test.ts](https://github.com/lankajs/lanka/blob/main/modules/bindings/svelte/_playground/playground.test.ts)
+
+# @lankajs/svelte — user guide
+
+How a Svelte component reads a lanka ViewModel.
+
+## You will learn
+
+- the one call this package publishes, and what it answers
+- when a component re-renders and when it deliberately does not
+- why a selector that builds an object needs a hold, and when it needs nothing
+- what to do about a ViewModel that derives what the screen shows
+- how to test a Svelte component with a live framework behind it
+
+## When to reach for this
+
+Reach for it the moment a Svelte component has to read a lanka ViewModel — that
+is the whole job, and there is no other supported way to do it. Install this one
+package and no other binding: the five are alternatives, not layers.
+
+You do NOT need it to reach the rest of the framework. Gateways, scenarios and
+the locator are plain calls with no view in them, and `viewModel.getState()`
+works anywhere, including on a server.
+
+> [!NOTE]
+> Everything below is how this package is _meant_ to be used, not how it must
+> be. The framework bends at the seams it publishes — see
+> [ARCHITECTURE.md](https://github.com/lankajs/lanka/blob/main/ARCHITECTURE.md) for what is checked and what is
+> merely advice.
+
+## Install
+
+```bash
+npm install @lankajs/svelte svelte zustand
+```
+
+> [!IMPORTANT]
+> `svelte` is already in your project; `zustand` is `lanka`'s own peer. No
+> compiler plugin is needed — this package is plain TypeScript. npm adds a
+> missing peer for you and pnpm does not, so the line names all of them.
+
+## The one call
+
+`useLankaVM` is a function. Every member of `modules/bindings/` publishes that same
+name, so moving a screen from one framework to another rewrites the view and not
+the vocabulary.
+
+```svelte
+<script lang="ts">
+	import { useLankaVM } from "@lankajs/svelte";
+	import { todoVM } from "./todoVM";
+
+	const state = useLankaVM(todoVM);
+</script>
+
+{#if state.isLoading}
+	<p>loading</p>
+{:else}
+	<ul onclick={() => state.load()}>
+		{#each state.todos as todo (todo.id)}
+			<li>{todo.title}</li>
+		{/each}
+	</ul>
+{/if}
+```
+
+It answers **an object whose properties are getters** — the one thing this shelf does not make uniform,
+because that is Svelte's own idea of reactivity and a binding that hid it
+would be a second reactivity system fighting the first.
+
+## Svelte's store contract, when you want `$`
+
+`useLankaVM` answers an object of getters, which is Svelte 5's own shape: a read
+registers with the reactivity graph and with the access tracker in one access,
+and nothing needs a `$`.
+
+The store contract is the other half of Svelte and has not gone anywhere —
+`$page`, `derived`, `get`, and every codebase that has not moved to runes — so
+this package publishes it:
+
+```svelte
+<script lang="ts">
+	import { toLankaSvelteVM } from "@lankajs/svelte";
+	const todos = toLankaSvelteVM(todosVM);
+</script>
+
+{#each $todos.rows as row}<li>{row}</li>{/each}
+```
+
+It satisfies the contract properly: `run` is called immediately and
+synchronously, so `$todos` is never `undefined` on the first render, and
+`derived`, `get` and every other `svelte/store` helper accept it.
+
+Each Svelte subscriber gets its own recording, because two readers of one
+ViewModel read different keys and must be woken for different changes — the same
+rule every binding on the shelf follows.
+
+## Selecting one value
+
+With a selector the call answers ONE value, under `current` — Svelte's own
+convention for a reactive value, the way `MediaQuery` and the rest of
+`svelte/reactivity` read:
+
+```svelte
+<script lang="ts">
+	const count = useLankaVM(todosVM, (state) => state.rows.length);
+</script>
+
+<p>{count.current}</p>
+```
+
+Any selector, including one answering a number: the shape that carried the
+selection's own keys could not, and a member of this shelf narrowing the shared
+name is what the conformance suite's selector scenes now refuse.
+
+The reader wakes when the SELECTION moves, not when the state does — compared
+with `Object.is`.
+
+### A selector that builds its answer
+
+That comparison is why a selector answering a fresh object wakes the reader for
+**every** change in the ViewModel, including the keys it exists to ignore: the
+object is new on every call, so it is never identical to the previous one.
+`createLankaShallowHold` is the comparison that fixes it — it answers the
+PREVIOUS object while nothing in the selection moved, one level deep over own
+keys:
+
+```svelte
+<script lang="ts">
+	import { createLankaShallowHold } from "lanka/viewmodel";
+	import { useLankaVM } from "@lankajs/svelte";
+
+	const hold = createLankaShallowHold<{ title: string; status: string }>();
+	const mission = useLankaVM(missionVM, (state) =>
+		hold({ title: state.title, status: state.status }),
+	);
+</script>
+
+<h1>{mission.current.title} — {mission.current.status}</h1>
+```
+
+One hold per reader, created beside the read in the component — never at module
+level and never shared between two of them, because the answer it holds belongs
+to whoever selected it.
+
+A selector answering a **primitive** needs none of this and was always free. 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.
+
+## What re-renders, and what does not
+
+Without a selector you get a value that RECORDS which keys you read. The next
+change re-renders only if one of those moved:
+
+```ts
+// reads `todos`; a change to `isLoading` alone repaints nothing
+```
+
+With a selector, the selector decides and tracking is bypassed:
+
+```ts
+const count = useLankaVM(todoVM, (state) => state.todos.length);
+```
+
+> [!WARNING]
+> **The blind spot.** Tracking sees keys you read DIRECTLY. A key reached only
+> inside a derived getter — an action calling `get()` — is invisible to it, so a
+> change to that key re-renders nothing and the screen freezes with no error.
+>
+> Set `enableAccessTrackingOptimization: false` on such a ViewModel. Do NOT patch
+> it in the view by reading the underlying keys "for the side effect": that is
+> dead code, and a refactor or a lint autofix removes it.
+>
+> In development the framework announces the mismatch by ViewModel and key name.
+
+## Releasing the subscription
+
+`createSubscriber` releases the subscription when the last effect reading this
+view is destroyed, which is every case inside a component. A read where there is
+no effect at all — a module-level snapshot, a script — has none, so the view
+carries `stop()` and you own it.
+
+## No compiler
+
+This package is plain TypeScript: `createSubscriber` from `svelte/reactivity` is
+a runtime function, so nothing here needs the Svelte compiler and your build
+needs no extra plugin.
+
+## Which spelling, and when
+
+`useLankaVM` is the default. A read registers with the reactivity graph and with
+the access tracker in one access, it composes with `$state` and `$derived`, and
+it is the plain read every other binding on the shelf writes — so a screen moves
+between frameworks with the view rewritten and the vocabulary kept.
+
+`toLankaSvelteVM` is for when something else demands the store contract: a
+`derived`, a `get`, a helper from `svelte/store`, or a codebase that has not
+moved to runes. Reaching for `$todoVM` by preference is the one case to weigh,
+because it is the spelling no other framework has.
+
+## Testing
+
+`@lankajs/svelte/testing` renders a component with a bootstrapped framework, so a component
+test needs no bootstrap preamble of its own:
+
+```ts
+import { renderWithLanka } from "@lankajs/svelte/testing";
+
+renderWithLanka(TodoScreen, {
+	fakes: { gateways: { TodoGateway: { list: () => Promise.resolve([]) } } },
+});
+```
+
+Every call gets a FRESH instance and disposes the previous one, so a test never
+inherits its neighbour's subscriptions.
+
+## What this package is not
+
+It is a subscription and a render trigger, and nothing else. The recording of
+which keys you read, the comparison that decides whether a change is worth a
+render, and the blind-spot warning are all in `lanka` itself — which is why the
+behaviour you see is the framework's rather than this package's reading of it,
+and why `lankaViewBindingConformance` can hold every binding to one list.
+
+If this package ever needs more than the ViewModel port gives it, the port has
+the defect and the fix belongs in `lanka`, for every framework at once.
+
+## Recap
+
+- `useLankaVM(todoVM)` is the one call, and every binding publishes that name.
+- It answers an object of getters, so reading `state.todos` registers with Svelte's graph and records the key in one access.
+- A selected read answers one value under `.current` — Svelte's own convention, and the only shape that can carry a selection which is not an object.
+- A key reached only through a derived getter is invisible to tracking: set `enableAccessTrackingOptimization: false` on that ViewModel.
+- `toLankaSvelteVM` is there for the `$` spelling; the plain read is what the other four frameworks write.
+- Inside a component the subscription is released for you; outside one, `stop()` is yours to call.
+
+---
+
+Maintaining this package: [SKILL.md](https://github.com/lankajs/lanka/blob/main/modules/bindings/svelte/SKILL.md) · What it is:
+[README.md](https://github.com/lankajs/lanka/blob/main/modules/bindings/svelte/README.md) · Repository map: [../../../README.md](https://github.com/lankajs/lanka/blob/main/README.md)