@lankajs/vue 0.1.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,47 @@
+# @lankajs/vue
+
+**▸ module** · Vue binding
+
+> One composable — `useLankaVM` — and the access tracking core already does.
+
+A library in the same box. The app imports and calls it; core does not know it exists.
+
+**Runs in:** the browser.
+
+**Requires:** Vue. Enforced by `check-runtime.mjs`, which refuses an import of any other.
+
+**How to use it:** [GUIDE.md](./GUIDE.md) — the user guide, with examples. **How to change it:** [SKILL.md](./SKILL.md).
+
+## Contents
+
+- `useLankaVM` — the one name, and the same one every member of this shelf publishes
+- `renderWithLanka` (from `@lankajs/vue/testing`) — a render with a bootstrapped framework
+
+## What a Vue call answers, and why it differs from React's
+
+`useLankaVM(vm)` hands back a `ShallowRef`, so a template reads `state.todos` and a
+script reads `state.value.todos`. React hands back the state itself. That is the one
+difference the shelf does NOT hide: it is the framework's own idea of reactivity, and a
+binding that flattened it would be a second reactivity system fighting the first —
+every `watch` a consumer wrote would stop seeing changes.
+
+Everything else is identical, and `lankaViewBindingConformance` is what says so rather
+than this paragraph: every scene this package runs is one `@lankajs/react` runs too,
+and writing this package reworded none of them.
+
+## No client directive, and nothing to replace it
+
+React Server Components make importing a hook a build error; Vue has no equivalent and
+needs no directive. Nuxt renders this package on the server as ordinary code.
+
+## The effect scope, and the one case it is not there
+
+Inside a component or an `effectScope`, the subscription is released by
+`onScopeDispose` and a consumer does nothing. Called OUTSIDE one — a module-level read,
+a test — there is no scope to attach to, so the returned ref carries `stop()` and the
+caller owns it. Vue warns about the first case and says nothing about the second, which
+is why the second is a published member rather than a note.
+
+---
+
+Repository map: [../../../README.md](../../../README.md)

package/dist/chunk-PLDDJCW6.js

@@ -0,0 +1,49 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+export {
+  __require,
+  __esm,
+  __commonJS,
+  __export,
+  __toESM,
+  __toCommonJS
+};
+//# sourceMappingURL=chunk-PLDDJCW6.js.map

package/dist/chunk-PLDDJCW6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import { ILankaReadableVM } from 'lanka/viewmodel';
+import { ComputedRef, ShallowRef } from 'vue';
+
+/**
+ * A ViewModel as Vue reads one: its own members, directly.
+ *
+ * `vm.rows`, `vm.load()` — no `.value`, in the script and in the template alike
+ * — plus the one meta member a caller needs. `$`-prefixed, which is Pinia's
+ * convention and its reason: the keys belong to the application, and a meta
+ * member sharing that namespace collides the day somebody adds a `stop` of their
+ * own.
+ *
+ * Called a ViewModel and not a store, deliberately. Pinia's word for the thing a
+ * component reads is "store", and this reads the way one does — but what holds
+ * the state, the actions and the scenario bindings is the ViewModel, and naming
+ * it after the shape it wears would hide where the work lives.
+ */
+type TLankaVueVM<TState extends object> = TState & {
+    /** Releases the subscription. Rarely needed: a component scope does it. */
+    $stop: () => void;
+};
+/**
+ * Declares the composable a Vue component reads a ViewModel through.
+ *
+ * ```ts
+ * // todosVM.ts — at module level, the way `defineStore` is declared
+ * export const useTodosVM = defineLankaComposable(todosVM);
+ * ```
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * const todos = useTodosVM();
+ * </script>
+ *
+ * <template><li v-for="row in todos.rows" :key="row">{{ row }}</li></template>
+ * ```
+ *
+ * ## Why this exists beside `useLankaVM`
+ *
+ * `useLankaVM` answers a `ShallowRef`, which is the honest shape for Vue's
+ * reactivity and the one every other binding on the shelf parallels. It is also
+ * not what a Pinia codebase reads: there a component reads members straight off
+ * what it was handed, in the template and the script alike, and `.value` appears
+ * in neither. A consumer with that habit types `todos.rows`, gets `undefined`,
+ * and learns that lanka is a foreign object.
+ *
+ * ## Why it answers a FUNCTION and not the reader itself
+ *
+ * Pinia's shape, and not only for the look of it. A reader built at module level
+ * would open its subscription at IMPORT time, outside any component scope — so
+ * nothing would ever release it, and every component would share ONE recording.
+ * Two components reading different keys would then wake each other, which is the
+ * whole of what access tracking exists to prevent. Measured before this shape
+ * existed: the component reading only `rows` re-rendered when `unread` moved.
+ *
+ * So each CALL builds a reader, inside the calling component's scope, with its
+ * own subscription and its own recording — and Vue releases it when that
+ * component goes.
+ *
+ * ## Where it differs from Pinia, and why
+ *
+ * `useTodosVM()` in two components answers two objects, where Pinia answers one.
+ * The ViewModel behind them is the same one and there is no second copy of the
+ * state — what differs is the RECORDING, which belongs to whoever did the
+ * reading. Sharing the object would make tracking coarse, and an idiom is not
+ * allowed to change behaviour: that is the rule the parity canon sets for all of
+ * them.
+ *
+ * Calling it outside a component is legal and gives an unscoped reader; the
+ * caller then owns `$stop`.
+ *
+ * ## Reading is tracking
+ *
+ * Reads go through the access tracker, so a template reading only `rows` is not
+ * woken by `isLoading`, and a ViewModel that turned tracking off is heard for
+ * everything. Both are core's answers; nothing here decides either. The ref
+ * holds a version counter rather than the state, because a ref holding the state
+ * is a SNAPSHOT — right for a template, which re-reads when the ref changes, and
+ * wrong for something also read from ordinary code at arbitrary moments.
+ *
+ * ## Destructuring loses reactivity, exactly as it does in Pinia
+ *
+ * `const { rows } = todos` copies a value out and stops tracking, which is the
+ * single most common mistake in a Pinia codebase. `lankaVMToRefs(todos)` is the
+ * same answer Pinia gives, under a name that says what it is reading.
+ */
+declare const defineLankaComposable: <TState extends object>(viewModel: ILankaReadableVM<TState>) => () => TLankaVueVM<TState>;
+
+/** Every state member of the ViewModel, as a ref that keeps tracking. */
+type TLankaVMRefs<TState extends object> = {
+    [TKey in keyof TState]: ComputedRef<TState[TKey]>;
+};
+/**
+ * Names you can destructure, without losing the reactivity.
+ *
+ * ```ts
+ * const todos = useTodosVM();
+ * const { rows, isLoading } = lankaVMToRefs(todos);
+ *
+ * // in a template: {{ rows }} — in script: rows.value
+ * ```
+ *
+ * `const { rows } = todos` reads the value ONCE and stops tracking, and it is
+ * the commonest mistake in a Pinia codebase for the good reason that it looks
+ * exactly like code that works: the first paint is right and nothing updates
+ * after it. Pinia's answer is `storeToRefs`, so this is that answer under a name
+ * a reader recognises.
+ *
+ * Each ref is a `computed` over the same ViewModel, so nothing is copied and nothing
+ * is subscribed a second time — the composable's own subscription is still the only
+ * one.
+ *
+ * Actions are left OUT, and that is not an oversight: an action is a stable
+ * function for the life of the store, so `const { load } = todos` is correct and
+ * wrapping it in a ref would make every call site write `load.value()`.
+ */
+declare const lankaVMToRefs: <TState extends object>(viewModel: TLankaVueVM<TState>) => TLankaVMRefs<TState>;
+
+/** A ViewModel read from Vue: a ref, and a way to stop reading it. */
+interface ILankaVMRef<TValue> extends ShallowRef<TValue> {
+    /**
+     * Releases the subscription.
+     *
+     * Called for you by `onScopeDispose` inside a component or an `effectScope`.
+     * It is published because a read made OUTSIDE a scope — at module level, in a
+     * test — has nobody to call it, and Vue says nothing about that case.
+     */
+    stop: () => void;
+}
+/**
+ * Reads a ViewModel from a Vue component.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * const state = useLankaVM(todoVM);
+ * </script>
+ *
+ * <template>
+ *   <li v-for="todo in state.todos" :key="todo.id">{{ todo.title }}</li>
+ * </template>
+ * ```
+ *
+ * Without a selector the component receives a Proxy that records which keys it
+ * read, and the next change updates the ref only if one of THOSE keys moved.
+ * With a selector the selector decides and tracking is bypassed.
+ *
+ * ## What a Vue call answers, and why React's answers differently
+ *
+ * A `ShallowRef`. A template unwraps it (`state.todos`) and a script does not
+ * (`state.value.todos`), which is Vue's own idea of reactivity — and the one
+ * thing this shelf deliberately does NOT hide. Flattening it would mean a second
+ * reactivity system fighting the first, and every `watch` a consumer writes
+ * would stop seeing changes.
+ *
+ * Everything else is the same as every other binding, and
+ * `lankaViewBindingConformance` is what says so rather than this paragraph.
+ *
+ * ## What this function does NOT contain
+ *
+ * The recording, the comparison and the blind-spot warning are
+ * `createLankaAccessTracker` in core. If this file ever needs more than the port
+ * gives it, the port has the defect and the fix belongs in core, for everybody.
+ */
+declare function useLankaVM<TState extends object>(viewModel: ILankaReadableVM<TState>): ILankaVMRef<TState>;
+declare function useLankaVM<TState extends object, TSelected>(viewModel: ILankaReadableVM<TState>, selector: (state: TState) => TSelected): ILankaVMRef<TSelected>;
+
+export { type ILankaVMRef, type TLankaVMRefs, type TLankaVueVM, defineLankaComposable, lankaVMToRefs, useLankaVM };

package/dist/index.js

@@ -0,0 +1,102 @@
+import "./chunk-PLDDJCW6.js";
+
+// src/define-lanka-composable/defineLankaComposable.ts
+import { getCurrentScope, onScopeDispose, shallowRef, triggerRef } from "vue";
+import { createLankaViewSubscription } from "lanka/extend";
+var readsTheViewModel = (current, stop) => ({
+  get: (_target, key) => key === "$stop" ? stop : Reflect.get(current(), key),
+  has: (_target, key) => key === "$stop" || key in current(),
+  ownKeys: () => Reflect.ownKeys(current()),
+  /*
+   * Reported as configurable, always.
+   *
+   * A Proxy must not claim a non-configurable descriptor its target lacks — the
+   * runtime throws. The target here is a bare object while the keys live on the
+   * state, so every descriptor this hands back is invented and must say it can
+   * be redefined. Without it `{ ...vm }` and `Object.keys(vm)` throw rather than
+   * read, and a Vue devtool does one of them on sight.
+   */
+  getOwnPropertyDescriptor: (_target, key) => key === "$stop" ? { value: stop, configurable: true, enumerable: false, writable: false } : { ...Reflect.getOwnPropertyDescriptor(current(), key), configurable: true }
+});
+var defineLankaComposable = (viewModel) => () => {
+  const version = shallowRef(0);
+  const view = createLankaViewSubscription(viewModel, () => {
+    version.value += 1;
+    triggerRef(version);
+  });
+  if (getCurrentScope()) onScopeDispose(view.stop);
+  const current = () => {
+    void version.value;
+    return view.read();
+  };
+  return new Proxy({}, readsTheViewModel(current, view.stop));
+};
+
+// src/lanka-vm-to-refs/lankaVMToRefs.ts
+import { computed } from "vue";
+var lankaVMToRefs = (viewModel) => {
+  const refs = {};
+  for (const key of Object.keys(viewModel)) {
+    if (typeof viewModel[key] === "function") continue;
+    refs[key] = computed(() => viewModel[key]);
+  }
+  return refs;
+};
+
+// src/use-lanka-vm/useLankaVM.ts
+import {
+  getCurrentInstance,
+  getCurrentScope as getCurrentScope2,
+  onMounted,
+  onScopeDispose as onScopeDispose2,
+  shallowRef as shallowRef2,
+  triggerRef as triggerRef2
+} from "vue";
+import { createLankaAccessTracker } from "lanka/extend";
+function useLankaVM(viewModel, selector) {
+  const tracker = createLankaAccessTracker(viewModel);
+  const read = () => selector ? selector(viewModel.getState()) : tracker.read();
+  const state = shallowRef2(read());
+  const hear = (next, prev) => {
+    if (selector) {
+      const picked = read();
+      if (Object.is(picked, state.value)) return;
+      state.value = picked;
+      triggerRef2(state);
+      return;
+    }
+    if (!tracker.shouldNotify(next, prev)) {
+      tracker.reportSkipped(next, prev);
+      return;
+    }
+    state.value = read();
+    triggerRef2(state);
+  };
+  let stop = () => void 0;
+  const start = () => {
+    stop = viewModel.subscribe(hear);
+  };
+  const release = () => {
+    stop();
+  };
+  if (getCurrentInstance()) {
+    const stateAtSetup = viewModel.getState();
+    onMounted(() => {
+      start();
+      if (Object.is(viewModel.getState(), stateAtSetup)) return;
+      state.value = read();
+      triggerRef2(state);
+    });
+  } else {
+    start();
+  }
+  state.stop = release;
+  if (getCurrentScope2()) onScopeDispose2(release);
+  return state;
+}
+export {
+  defineLankaComposable,
+  lankaVMToRefs,
+  useLankaVM
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/define-lanka-composable/defineLankaComposable.ts","../src/lanka-vm-to-refs/lankaVMToRefs.ts","../src/use-lanka-vm/useLankaVM.ts"],"sourcesContent":["import { getCurrentScope, onScopeDispose, shallowRef, triggerRef } from \"vue\";\nimport { createLankaViewSubscription } from \"lanka/extend\";\nimport type { ILankaReadableVM } from \"lanka/viewmodel\";\n\n/**\n * A ViewModel as Vue reads one: its own members, directly.\n *\n * `vm.rows`, `vm.load()` — no `.value`, in the script and in the template alike\n * — plus the one meta member a caller needs. `$`-prefixed, which is Pinia's\n * convention and its reason: the keys belong to the application, and a meta\n * member sharing that namespace collides the day somebody adds a `stop` of their\n * own.\n *\n * Called a ViewModel and not a store, deliberately. Pinia's word for the thing a\n * component reads is \"store\", and this reads the way one does — but what holds\n * the state, the actions and the scenario bindings is the ViewModel, and naming\n * it after the shape it wears would hide where the work lives.\n */\nexport type TLankaVueVM<TState extends object> = TState & {\n\t/** Releases the subscription. Rarely needed: a component scope does it. */\n\t$stop: () => void;\n};\n\n/**\n * How the composable answers for the ViewModel behind it.\n *\n * Its own function, because the traps are the whole mechanism and the factory\n * below is then the subscription and the Proxy.\n */\nconst readsTheViewModel = <TState extends object, TFacade extends object>(\n\tcurrent: () => TState,\n\tstop: () => void,\n): ProxyHandler<TFacade> => ({\n\tget: (_target, key) => (key === \"$stop\" ? stop : Reflect.get(current(), key)),\n\n\thas: (_target, key) => key === \"$stop\" || key in current(),\n\n\townKeys: () => Reflect.ownKeys(current()),\n\n\t/*\n\t * Reported as configurable, always.\n\t *\n\t * A Proxy must not claim a non-configurable descriptor its target lacks — the\n\t * runtime throws. The target here is a bare object while the keys live on the\n\t * state, so every descriptor this hands back is invented and must say it can\n\t * be redefined. Without it `{ ...vm }` and `Object.keys(vm)` throw rather than\n\t * read, and a Vue devtool does one of them on sight.\n\t */\n\tgetOwnPropertyDescriptor: (_target, key) =>\n\t\tkey === \"$stop\"\n\t\t\t? { value: stop, configurable: true, enumerable: false, writable: false }\n\t\t\t: { ...Reflect.getOwnPropertyDescriptor(current(), key), configurable: true },\n});\n\n/**\n * Declares the composable a Vue component reads a ViewModel through.\n *\n * ```ts\n * // todosVM.ts — at module level, the way `defineStore` is declared\n * export const useTodosVM = defineLankaComposable(todosVM);\n * ```\n *\n * ```vue\n * <script setup lang=\"ts\">\n * const todos = useTodosVM();\n * </script>\n *\n * <template><li v-for=\"row in todos.rows\" :key=\"row\">{{ row }}</li></template>\n * ```\n *\n * ## Why this exists beside `useLankaVM`\n *\n * `useLankaVM` answers a `ShallowRef`, which is the honest shape for Vue's\n * reactivity and the one every other binding on the shelf parallels. It is also\n * not what a Pinia codebase reads: there a component reads members straight off\n * what it was handed, in the template and the script alike, and `.value` appears\n * in neither. A consumer with that habit types `todos.rows`, gets `undefined`,\n * and learns that lanka is a foreign object.\n *\n * ## Why it answers a FUNCTION and not the reader itself\n *\n * Pinia's shape, and not only for the look of it. A reader built at module level\n * would open its subscription at IMPORT time, outside any component scope — so\n * nothing would ever release it, and every component would share ONE recording.\n * Two components reading different keys would then wake each other, which is the\n * whole of what access tracking exists to prevent. Measured before this shape\n * existed: the component reading only `rows` re-rendered when `unread` moved.\n *\n * So each CALL builds a reader, inside the calling component's scope, with its\n * own subscription and its own recording — and Vue releases it when that\n * component goes.\n *\n * ## Where it differs from Pinia, and why\n *\n * `useTodosVM()` in two components answers two objects, where Pinia answers one.\n * The ViewModel behind them is the same one and there is no second copy of the\n * state — what differs is the RECORDING, which belongs to whoever did the\n * reading. Sharing the object would make tracking coarse, and an idiom is not\n * allowed to change behaviour: that is the rule the parity canon sets for all of\n * them.\n *\n * Calling it outside a component is legal and gives an unscoped reader; the\n * caller then owns `$stop`.\n *\n * ## Reading is tracking\n *\n * Reads go through the access tracker, so a template reading only `rows` is not\n * woken by `isLoading`, and a ViewModel that turned tracking off is heard for\n * everything. Both are core's answers; nothing here decides either. The ref\n * holds a version counter rather than the state, because a ref holding the state\n * is a SNAPSHOT — right for a template, which re-reads when the ref changes, and\n * wrong for something also read from ordinary code at arbitrary moments.\n *\n * ## Destructuring loses reactivity, exactly as it does in Pinia\n *\n * `const { rows } = todos` copies a value out and stops tracking, which is the\n * single most common mistake in a Pinia codebase. `lankaVMToRefs(todos)` is the\n * same answer Pinia gives, under a name that says what it is reading.\n */\nexport const defineLankaComposable =\n\t<TState extends object>(viewModel: ILankaReadableVM<TState>) =>\n\t(): TLankaVueVM<TState> => {\n\t\t/*\n\t\t * `triggerRef` as well as the increment for the reason every binding on this\n\t\t * shelf carries: a tracked read hands back the SAME proxy while the state\n\t\t * object is unchanged, and a shallow ref compares by identity.\n\t\t */\n\t\tconst version = shallowRef(0);\n\n\t\tconst view = createLankaViewSubscription(viewModel, () => {\n\t\t\tversion.value += 1;\n\t\t\ttriggerRef(version);\n\t\t});\n\n\t\t// Inside a component or an `effectScope`, Vue owns the lifetime and the\n\t\t// subscription goes with it. Outside one there is nothing to attach to, and\n\t\t// `onScopeDispose` would warn — so the caller keeps `$stop`.\n\t\tif (getCurrentScope()) onScopeDispose(view.stop);\n\n\t\tconst current = (): TState => {\n\t\t\t// Read for the DEPENDENCY, discard the number. A template reading\n\t\t\t// `todos.rows` must re-render when the counter moves, and the counter is\n\t\t\t// the only reactive thing in here.\n\t\t\tvoid version.value;\n\n\t\t\treturn view.read();\n\t\t};\n\n\t\treturn new Proxy({} as TLankaVueVM<TState>, readsTheViewModel(current, view.stop));\n\t};\n","import { computed } from \"vue\";\nimport type { ComputedRef } from \"vue\";\nimport type { TLankaVueVM } from \"../define-lanka-composable/defineLankaComposable\";\n\n/** Every state member of the ViewModel, as a ref that keeps tracking. */\nexport type TLankaVMRefs<TState extends object> = {\n\t[TKey in keyof TState]: ComputedRef<TState[TKey]>;\n};\n\n/**\n * Names you can destructure, without losing the reactivity.\n *\n * ```ts\n * const todos = useTodosVM();\n * const { rows, isLoading } = lankaVMToRefs(todos);\n *\n * // in a template: {{ rows }} — in script: rows.value\n * ```\n *\n * `const { rows } = todos` reads the value ONCE and stops tracking, and it is\n * the commonest mistake in a Pinia codebase for the good reason that it looks\n * exactly like code that works: the first paint is right and nothing updates\n * after it. Pinia's answer is `storeToRefs`, so this is that answer under a name\n * a reader recognises.\n *\n * Each ref is a `computed` over the same ViewModel, so nothing is copied and nothing\n * is subscribed a second time — the composable's own subscription is still the only\n * one.\n *\n * Actions are left OUT, and that is not an oversight: an action is a stable\n * function for the life of the store, so `const { load } = todos` is correct and\n * wrapping it in a ref would make every call site write `load.value()`.\n */\nexport const lankaVMToRefs = <TState extends object>(\n\tviewModel: TLankaVueVM<TState>,\n): TLankaVMRefs<TState> => {\n\tconst refs = {} as TLankaVMRefs<TState>;\n\n\tfor (const key of Object.keys(viewModel) as (keyof TState)[]) {\n\t\tif (typeof viewModel[key] === \"function\") continue;\n\n\t\trefs[key] = computed(() => viewModel[key]);\n\t}\n\n\treturn refs;\n};\n","import {\n\tgetCurrentInstance,\n\tgetCurrentScope,\n\tonMounted,\n\tonScopeDispose,\n\tshallowRef,\n\ttriggerRef,\n} from \"vue\";\nimport { createLankaAccessTracker } from \"lanka/extend\";\nimport type { ShallowRef } from \"vue\";\nimport type { ILankaReadableVM } from \"lanka/viewmodel\";\n\n/** A ViewModel read from Vue: a ref, and a way to stop reading it. */\nexport interface ILankaVMRef<TValue> extends ShallowRef<TValue> {\n\t/**\n\t * Releases the subscription.\n\t *\n\t * Called for you by `onScopeDispose` inside a component or an `effectScope`.\n\t * It is published because a read made OUTSIDE a scope — at module level, in a\n\t * test — has nobody to call it, and Vue says nothing about that case.\n\t */\n\tstop: () => void;\n}\n\n/**\n * Reads a ViewModel from a Vue component.\n *\n * ```vue\n * <script setup lang=\"ts\">\n * const state = useLankaVM(todoVM);\n * </script>\n *\n * <template>\n *   <li v-for=\"todo in state.todos\" :key=\"todo.id\">{{ todo.title }}</li>\n * </template>\n * ```\n *\n * Without a selector the component receives a Proxy that records which keys it\n * read, and the next change updates the ref only if one of THOSE keys moved.\n * With a selector the selector decides and tracking is bypassed.\n *\n * ## What a Vue call answers, and why React's answers differently\n *\n * A `ShallowRef`. A template unwraps it (`state.todos`) and a script does not\n * (`state.value.todos`), which is Vue's own idea of reactivity — and the one\n * thing this shelf deliberately does NOT hide. Flattening it would mean a second\n * reactivity system fighting the first, and every `watch` a consumer writes\n * would stop seeing changes.\n *\n * Everything else is the same as every other binding, and\n * `lankaViewBindingConformance` is what says so rather than this paragraph.\n *\n * ## What this function does NOT contain\n *\n * The recording, the comparison and the blind-spot warning are\n * `createLankaAccessTracker` in core. If this file ever needs more than the port\n * gives it, the port has the defect and the fix belongs in core, for everybody.\n */\nexport function useLankaVM<TState extends object>(\n\tviewModel: ILankaReadableVM<TState>,\n): ILankaVMRef<TState>;\n\nexport function useLankaVM<TState extends object, TSelected>(\n\tviewModel: ILankaReadableVM<TState>,\n\tselector: (state: TState) => TSelected,\n): ILankaVMRef<TSelected>;\n\nexport function useLankaVM<TState extends object, TSelected>(\n\tviewModel: ILankaReadableVM<TState>,\n\tselector?: (state: TState) => TSelected,\n): ILankaVMRef<TState | TSelected> {\n\tconst tracker = createLankaAccessTracker(viewModel);\n\tconst read = (): TState | TSelected =>\n\t\tselector ? selector(viewModel.getState()) : tracker.read();\n\n\t// `as unknown` first: Vue's `shallowRef` return type is a conditional over the\n\t// value, and TypeScript cannot see that adding `stop` to it lands on this\n\t// interface. The object IS the ref — `stop` is assigned two lines below.\n\tconst state = shallowRef(read()) as unknown as ILankaVMRef<TState | TSelected>;\n\n\tconst hear = (next: TState, prev: TState): void => {\n\t\tif (selector) {\n\t\t\tconst picked = read();\n\n\t\t\t// Only when the SELECTION moved. Without this the ref is set on every\n\t\t\t// notification and the reader wakes for everything, so the same call\n\t\t\t// means one thing here and another in React — which is what the\n\t\t\t// conformance suite's selector scenes now refuse.\n\t\t\tif (Object.is(picked, state.value)) return;\n\n\t\t\tstate.value = picked;\n\t\t\ttriggerRef(state);\n\n\t\t\treturn;\n\t\t}\n\n\t\tif (!tracker.shouldNotify(next, prev)) {\n\t\t\t// No update will follow. If the changed key is linked to this component\n\t\t\t// through a getter it read, the screen froze — and in development core\n\t\t\t// says so by name.\n\t\t\ttracker.reportSkipped(next, prev);\n\t\t\treturn;\n\t\t}\n\n\t\t// `triggerRef` as well as the assignment: a tracked read hands back the SAME\n\t\t// proxy while the state object is unchanged, and a shallow ref compares by\n\t\t// identity — so an assignment alone would be a no-op exactly when the\n\t\t// tracker did its job. Vue re-renders, the proxy records afresh.\n\t\tstate.value = read();\n\t\ttriggerRef(state);\n\t};\n\n\tlet stop = (): void => undefined;\n\tconst start = (): void => {\n\t\tstop = viewModel.subscribe(hear);\n\t};\n\tconst release = (): void => {\n\t\tstop();\n\t};\n\n\t/**\n\t * Inside a component the subscription starts at MOUNT; everywhere else, now.\n\t *\n\t * A server renders once and throws the tree away. Nothing is mounted and\n\t * nothing is unmounted, so the instance's scope is never stopped and\n\t * `onScopeDispose` never runs — a subscription opened in `setup` there is a\n\t * listener on a module-level ViewModel that outlives the request, and the\n\t * process collects one per request until it dies. The conformance suite's\n\t * server scene is what found it, on the day this package started answering\n\t * that scene instead of skipping it.\n\t *\n\t * `onMounted` is the seam because it is the one lifecycle a server never\n\t * reaches. Outside a component there is no mount to wait for — a module-level\n\t * read, a test, an `effectScope` — and the subscription opens immediately, as\n\t * it always did.\n\t *\n\t * The catch-up is not optional. Between `setup` and the mount the ViewModel may\n\t * have moved, and the ref still holds what `setup` saw.\n\t *\n\t * What it compares is the STATE OBJECT, not the value the reader sees. The\n\t * value was the obvious thing to compare and it is wrong on the selector arm:\n\t * a selector building a fresh object — `(s) => ({ … })`, the shape a consumer\n\t * reaches for first — is never `Object.is`-equal to anything, so every such\n\t * component rendered a second time at mount whether or not a thing had moved.\n\t * The state object is the question both arms actually mean: core answers the\n\t * same one while nothing has changed.\n\t *\n\t * ## The window this leaves, and the trade in it\n\t *\n\t * A change made synchronously in `setup` AFTER this call — a bootstrap line, a\n\t * hydration — is no longer in the first render; it lands on the next tick.\n\t * `onBeforeMount` would close that window and open a worse one: it runs inside\n\t * the hydration render, so correcting the value there makes the client paint\n\t * something the server did not send. That is a markup mismatch in a process\n\t * this framework owns no part of, and `skills/hosts/SKILL.md` §5 is the rule\n\t * it breaks — take the frame, which is a cost inside our own layer, over a\n\t * mismatch the host reports and the application cannot act on.\n\t *\n\t * It is a cost the other four bindings do not pay, which is the part worth\n\t * knowing before anyone calls it a Vue bug.\n\t */\n\tif (getCurrentInstance()) {\n\t\tconst stateAtSetup = viewModel.getState();\n\n\t\tonMounted(() => {\n\t\t\tstart();\n\n\t\t\tif (Object.is(viewModel.getState(), stateAtSetup)) return;\n\n\t\t\tstate.value = read();\n\t\t\ttriggerRef(state);\n\t\t});\n\t} else {\n\t\tstart();\n\t}\n\n\tstate.stop = release;\n\n\t// Inside a component or an `effectScope`, Vue owns the lifetime and the\n\t// subscription goes with it. Outside one there is nothing to attach to, and\n\t// `onScopeDispose` would warn — so the caller keeps `stop`.\n\tif (getCurrentScope()) onScopeDispose(release);\n\n\treturn state;\n}\n"],"mappings":";;;AAAA,SAAS,iBAAiB,gBAAgB,YAAY,kBAAkB;AACxE,SAAS,mCAAmC;AA4B5C,IAAM,oBAAoB,CACzB,SACA,UAC4B;AAAA,EAC5B,KAAK,CAAC,SAAS,QAAS,QAAQ,UAAU,OAAO,QAAQ,IAAI,QAAQ,GAAG,GAAG;AAAA,EAE3E,KAAK,CAAC,SAAS,QAAQ,QAAQ,WAAW,OAAO,QAAQ;AAAA,EAEzD,SAAS,MAAM,QAAQ,QAAQ,QAAQ,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWxC,0BAA0B,CAAC,SAAS,QACnC,QAAQ,UACL,EAAE,OAAO,MAAM,cAAc,MAAM,YAAY,OAAO,UAAU,MAAM,IACtE,EAAE,GAAG,QAAQ,yBAAyB,QAAQ,GAAG,GAAG,GAAG,cAAc,KAAK;AAC/E;AAmEO,IAAM,wBACZ,CAAwB,cACxB,MAA2B;AAM1B,QAAM,UAAU,WAAW,CAAC;AAE5B,QAAM,OAAO,4BAA4B,WAAW,MAAM;AACzD,YAAQ,SAAS;AACjB,eAAW,OAAO;AAAA,EACnB,CAAC;AAKD,MAAI,gBAAgB,EAAG,gBAAe,KAAK,IAAI;AAE/C,QAAM,UAAU,MAAc;AAI7B,SAAK,QAAQ;AAEb,WAAO,KAAK,KAAK;AAAA,EAClB;AAEA,SAAO,IAAI,MAAM,CAAC,GAA0B,kBAAkB,SAAS,KAAK,IAAI,CAAC;AAClF;;;ACrJD,SAAS,gBAAgB;AAiClB,IAAM,gBAAgB,CAC5B,cAC0B;AAC1B,QAAM,OAAO,CAAC;AAEd,aAAW,OAAO,OAAO,KAAK,SAAS,GAAuB;AAC7D,QAAI,OAAO,UAAU,GAAG,MAAM,WAAY;AAE1C,SAAK,GAAG,IAAI,SAAS,MAAM,UAAU,GAAG,CAAC;AAAA,EAC1C;AAEA,SAAO;AACR;;;AC7CA;AAAA,EACC;AAAA,EACA,mBAAAA;AAAA,EACA;AAAA,EACA,kBAAAC;AAAA,EACA,cAAAC;AAAA,EACA,cAAAC;AAAA,OACM;AACP,SAAS,gCAAgC;AA2DlC,SAAS,WACf,WACA,UACkC;AAClC,QAAM,UAAU,yBAAyB,SAAS;AAClD,QAAM,OAAO,MACZ,WAAW,SAAS,UAAU,SAAS,CAAC,IAAI,QAAQ,KAAK;AAK1D,QAAM,QAAQD,YAAW,KAAK,CAAC;AAE/B,QAAM,OAAO,CAAC,MAAc,SAAuB;AAClD,QAAI,UAAU;AACb,YAAM,SAAS,KAAK;AAMpB,UAAI,OAAO,GAAG,QAAQ,MAAM,KAAK,EAAG;AAEpC,YAAM,QAAQ;AACd,MAAAC,YAAW,KAAK;AAEhB;AAAA,IACD;AAEA,QAAI,CAAC,QAAQ,aAAa,MAAM,IAAI,GAAG;AAItC,cAAQ,cAAc,MAAM,IAAI;AAChC;AAAA,IACD;AAMA,UAAM,QAAQ,KAAK;AACnB,IAAAA,YAAW,KAAK;AAAA,EACjB;AAEA,MAAI,OAAO,MAAY;AACvB,QAAM,QAAQ,MAAY;AACzB,WAAO,UAAU,UAAU,IAAI;AAAA,EAChC;AACA,QAAM,UAAU,MAAY;AAC3B,SAAK;AAAA,EACN;AA2CA,MAAI,mBAAmB,GAAG;AACzB,UAAM,eAAe,UAAU,SAAS;AAExC,cAAU,MAAM;AACf,YAAM;AAEN,UAAI,OAAO,GAAG,UAAU,SAAS,GAAG,YAAY,EAAG;AAEnD,YAAM,QAAQ,KAAK;AACnB,MAAAA,YAAW,KAAK;AAAA,IACjB,CAAC;AAAA,EACF,OAAO;AACN,UAAM;AAAA,EACP;AAEA,QAAM,OAAO;AAKb,MAAIH,iBAAgB,EAAG,CAAAC,gBAAe,OAAO;AAE7C,SAAO;AACR;","names":["getCurrentScope","onScopeDispose","shallowRef","triggerRef"]}

package/dist/testing.d.ts

@@ -0,0 +1,43 @@
+import { RenderOptions, RenderResult } from '@testing-library/vue';
+import { Component } from 'vue';
+import { IPrepareLankaRenderOptions } from '@lankajs/tool-testing';
+import { ILankaInstance } from 'lanka';
+
+interface IRenderWithLankaOptions extends Omit<RenderOptions<Component>, "wrapper">, IPrepareLankaRenderOptions {
+}
+/**
+ * What a render with a bootstrapped framework ADDS to the library's own result.
+ *
+ * An interface over the addition rather than over the whole result, and the same
+ * in all five bindings: Svelte Testing Library's result carries a string index
+ * signature for its bound queries, so a named member added by extension has to
+ * satisfy it — and `lanka` is an instance, not a query. Describing only the
+ * addition is true of every library and needs no cast anywhere.
+ */
+interface IRenderWithLankaResult {
+    /** The instance the render used. */
+    lanka: ILankaInstance;
+}
+/**
+ * Rendering a Vue tree with a bootstrapped framework.
+ *
+ * ## Why
+ *
+ * A component reading a ViewModel needs a live instance: without one the first
+ * scenario or locator access fails. Assembling bootstrap in every component test
+ * is twenty lines of preamble that diverge between files silently — one test
+ * creates an instance, another relies on the previous one, and file order starts
+ * deciding the outcome.
+ *
+ * ## What is here, and what is in the kit
+ *
+ * The four bindings publish this name and differ only in which `render` they
+ * call. Everything else — a fresh instance, the doubles, the caller's setup, and
+ * the scenario layer brought up in that order — is `prepareLankaRender` in
+ * `@lankajs/tool-testing`, which is the one place all four already look. It also
+ * carries the reasons: why the instance is fresh, and why the order matters to a
+ * ViewModel built at module level.
+ */
+declare const renderWithLanka: (ui: Component, options?: IRenderWithLankaOptions) => RenderResult & IRenderWithLankaResult;
+
+export { type IRenderWithLankaOptions, type IRenderWithLankaResult, renderWithLanka };