ivue 2.2.2 → 2.3.0

package/README.md

@@ -79,6 +79,24 @@ const { count } = counter;
 
 Full walkthrough: [Getting Started](https://ivue.dev/guide/getting-started).
 
+## Built for humans and AI
+
+ivue ships with a
+[Standard Operating Manual](https://ivue.dev/guide/standard) — the complete
+authoring standard as annotated templates, rules, and a review checklist. It
+reads as documentation and works as a drop-in skill for AI coding agents, so
+generated code follows the same standard your team writes:
+
+```sh
+npx ivue skill        # installs .claude/skills/ivue/SKILL.md, version-locked
+npx ivue skill --all  # + Codex/Cursor/Copilot where already in use
+```
+
+Agents holding the Standard have
+[derived correct patterns its own author never wrote](https://ivue.dev/blog/patterns-the-author-never-wrote) —
+the manual is a generator, not a catalog. The wider argument:
+[Reactive framework for the AI era](https://ivue.dev/blog/reactive-framework-for-the-ai-era).
+
 ## Why classes, why now
 
 - **Native class API** — `extends`, `super`, getters, setters, private
@@ -207,24 +225,6 @@ Taken all the way down: a fully reactive spreadsheet model holding
 floor — because in ivue, everything costs proportional to what's *observed*,
 nothing costs proportional to what *exists*.
 
-## Built for humans and AI
-
-ivue ships with a
-[Standard Operating Manual](https://ivue.dev/guide/standard) — the complete
-authoring standard as annotated templates, rules, and a review checklist. It
-reads as documentation and works as a drop-in skill for AI coding agents, so
-generated code follows the same standard your team writes:
-
-```sh
-npx ivue skill        # installs .claude/skills/ivue/SKILL.md, version-locked
-npx ivue skill --all  # + Codex/Cursor/Copilot where already in use
-```
-
-Agents holding the Standard have
-[derived correct patterns its own author never wrote](https://ivue.dev/blog/patterns-the-author-never-wrote) —
-the manual is a generator, not a catalog. The wider argument:
-[Reactive framework for the AI era](https://ivue.dev/blog/reactive-framework-for-the-ai-era).
-
 ## Go deeper
 
 - [Fundamental Principles](https://ivue.dev/guide/principles) — the design, from first ideas

package/dist/LazyShared.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `LazyShared<T>` — the safe shared-store cell for static classes.
+ *
+ * The static-class split (see `Static()`): `$`-prefixed static getters
+ * are compute-once-PER-RECEIVER caches — perfect for memos and per-class
+ * tuning, where a subclass forking its own copy is the feature. A SHARED
+ * store (a registry, a ledger) must never live there: per-receiver
+ * caching means a subclass reading `this.$store` silently forks the
+ * registry. The fix is a `static readonly` FIELD — one reference on the
+ * declaring class, inherited, never receiver-cached — but an eager field
+ * initializer runs at MODULE LOAD, so it may only hold dependency-free
+ * values; the moment it constructs another namespace's class it races
+ * import cycles.
+ *
+ * `LazyShared` closes the triangle. The field eagerly stores the CELL
+ * (load-safe — a thunk evaluates nothing), the thunk runs on first
+ * `.value` read (cycle-safe — every module in any import cycle has
+ * finished loading), and memoization mutates cell-internal state
+ * (fork-safe — no receiver, subclass included, can fork it):
+ *
+ *   class $SearchRegistry {
+ *     protected static readonly sharedBackend = new LazyShared(
+ *       () => new SearchBackend.Class(),
+ *     );
+ *     protected static get $backend() {
+ *       return this.sharedBackend.value; // the field IS the pin
+ *     }
+ *   }
+ *
+ * A thunk that reads its own cell (directly or through another cell)
+ * throws a NAMED cycle error instead of a bare stack overflow, and a
+ * failed construction leaves the cell retryable, never poisoned.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+export declare class LazyShared<T> {
+    private readonly make;
+    constructor(make: () => T);
+    private constructed;
+    private constructing;
+    private stored;
+    get value(): T;
+    /**
+     * Drop the constructed value; the next read constructs again. For
+     * tests and process recomposition — production code never resets.
+     */
+    reset(): void;
+}

package/dist/extras.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=Object.hasOwn;exports.Static=function(c){const r=class extends c{},s=new Set;for(let o=c;o!==Function.prototype;o=Object.getPrototypeOf(o))for(const e of Reflect.ownKeys(o)){if(s.has(e))continue;s.add(e);const t=Object.getOwnPropertyDescriptor(o,e);if(typeof t.value=="function"){const i=t.value,n=typeof e=="string"?Symbol.for(`ivue.staticBound.${e}`):Symbol("ivue.staticBound");Object.defineProperty(r,e,{configurable:!0,enumerable:t.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:i.bind(this)}),this[n]}})}else if(t.get&&!t.set&&typeof e=="string"&&e.startsWith("$")){const i=t.get,n=Symbol.for(`ivue.staticCache.${e}`);Object.defineProperty(r,e,{configurable:!0,enumerable:t.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:i.call(this)}),this[n]}})}}return r};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=Object.hasOwn;exports.LazyShared=class{constructor(s){this.make=s,this.constructed=!1,this.constructing=!1,this.stored=null}get value(){if(!this.constructed){if(this.constructing)throw new Error("LazyShared thunk cycle: this cell is read inside its own construction. Break the dependency between the two thunks.");this.constructing=!0;try{this.stored=this.make(),this.constructed=!0}finally{this.constructing=!1}}return this.stored}reset(){this.constructed=!1,this.stored=null}},exports.Static=function(s){const i=class extends s{},c=new Set;for(let r=s;r!==Function.prototype;r=Object.getPrototypeOf(r))for(const t of Reflect.ownKeys(r)){if(c.has(t))continue;c.add(t);const e=Object.getOwnPropertyDescriptor(r,t);if(typeof e.value=="function"){const o=e.value,n=typeof t=="string"?Symbol.for(`ivue.staticBound.${t}`):Symbol("ivue.staticBound");Object.defineProperty(i,t,{configurable:!0,enumerable:e.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:o.bind(this)}),this[n]}})}else if(e.get&&!e.set&&typeof t=="string"&&t.startsWith("$")){const o=e.get,n=Symbol.for(`ivue.staticCache.${t}`);Object.defineProperty(i,t,{configurable:!0,enumerable:e.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:o.call(this)}),this[n]}})}}return i};

package/dist/extras.d.ts

@@ -7,3 +7,4 @@
  *   import { Static } from 'ivue/extras';
  */
 export { Static, type ClassConstructor } from './Static';
+export { LazyShared } from './LazyShared';

package/dist/extras.es.js

@@ -1,27 +1,49 @@
-const a = Object.hasOwn;
-function u(s) {
-  const r = class extends s {
+const u = Object.hasOwn;
+function a(i) {
+  const n = class extends i {
   }, c = /* @__PURE__ */ new Set();
-  for (let n = s; n !== Function.prototype; n = Object.getPrototypeOf(n))
-    for (const e of Reflect.ownKeys(n)) {
-      if (c.has(e))
+  for (let r = i; r !== Function.prototype; r = Object.getPrototypeOf(r))
+    for (const t of Reflect.ownKeys(r)) {
+      if (c.has(t))
         continue;
-      c.add(e);
-      const t = Object.getOwnPropertyDescriptor(n, e);
-      if (typeof t.value == "function") {
-        const i = t.value, o = typeof e == "string" ? Symbol.for(`ivue.staticBound.${e}`) : Symbol("ivue.staticBound");
-        Object.defineProperty(r, e, { configurable: !0, enumerable: t.enumerable, get() {
-          return a(this, o) || Object.defineProperty(this, o, { configurable: !0, value: i.bind(this) }), this[o];
+      c.add(t);
+      const e = Object.getOwnPropertyDescriptor(r, t);
+      if (typeof e.value == "function") {
+        const o = e.value, s = typeof t == "string" ? Symbol.for(`ivue.staticBound.${t}`) : Symbol("ivue.staticBound");
+        Object.defineProperty(n, t, { configurable: !0, enumerable: e.enumerable, get() {
+          return u(this, s) || Object.defineProperty(this, s, { configurable: !0, value: o.bind(this) }), this[s];
         } });
-      } else if (t.get && !t.set && typeof e == "string" && e.startsWith("$")) {
-        const i = t.get, o = Symbol.for(`ivue.staticCache.${e}`);
-        Object.defineProperty(r, e, { configurable: !0, enumerable: t.enumerable, get() {
-          return a(this, o) || Object.defineProperty(this, o, { configurable: !0, value: i.call(this) }), this[o];
+      } else if (e.get && !e.set && typeof t == "string" && t.startsWith("$")) {
+        const o = e.get, s = Symbol.for(`ivue.staticCache.${t}`);
+        Object.defineProperty(n, t, { configurable: !0, enumerable: e.enumerable, get() {
+          return u(this, s) || Object.defineProperty(this, s, { configurable: !0, value: o.call(this) }), this[s];
         } });
       }
     }
-  return r;
+  return n;
+}
+class h {
+  constructor(n) {
+    this.make = n, this.constructed = !1, this.constructing = !1, this.stored = null;
+  }
+  get value() {
+    if (!this.constructed) {
+      if (this.constructing)
+        throw new Error("LazyShared thunk cycle: this cell is read inside its own construction. Break the dependency between the two thunks.");
+      this.constructing = !0;
+      try {
+        this.stored = this.make(), this.constructed = !0;
+      } finally {
+        this.constructing = !1;
+      }
+    }
+    return this.stored;
+  }
+  reset() {
+    this.constructed = !1, this.stored = null;
+  }
 }
 export {
-  u as Static
+  h as LazyShared,
+  a as Static
 };

package/lib/LazyShared.ts

@@ -0,0 +1,71 @@
+/**
+ * `LazyShared<T>` — the safe shared-store cell for static classes.
+ *
+ * The static-class split (see `Static()`): `$`-prefixed static getters
+ * are compute-once-PER-RECEIVER caches — perfect for memos and per-class
+ * tuning, where a subclass forking its own copy is the feature. A SHARED
+ * store (a registry, a ledger) must never live there: per-receiver
+ * caching means a subclass reading `this.$store` silently forks the
+ * registry. The fix is a `static readonly` FIELD — one reference on the
+ * declaring class, inherited, never receiver-cached — but an eager field
+ * initializer runs at MODULE LOAD, so it may only hold dependency-free
+ * values; the moment it constructs another namespace's class it races
+ * import cycles.
+ *
+ * `LazyShared` closes the triangle. The field eagerly stores the CELL
+ * (load-safe — a thunk evaluates nothing), the thunk runs on first
+ * `.value` read (cycle-safe — every module in any import cycle has
+ * finished loading), and memoization mutates cell-internal state
+ * (fork-safe — no receiver, subclass included, can fork it):
+ *
+ *   class $SearchRegistry {
+ *     protected static readonly sharedBackend = new LazyShared(
+ *       () => new SearchBackend.Class(),
+ *     );
+ *     protected static get $backend() {
+ *       return this.sharedBackend.value; // the field IS the pin
+ *     }
+ *   }
+ *
+ * A thunk that reads its own cell (directly or through another cell)
+ * throws a NAMED cycle error instead of a bare stack overflow, and a
+ * failed construction leaves the cell retryable, never poisoned.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+export class LazyShared<T> {
+  constructor(private readonly make: () => T) {}
+
+  private constructed = false;
+  private constructing = false;
+  private stored: T | null = null;
+
+  get value(): T {
+    if (!this.constructed) {
+      if (this.constructing) {
+        throw new Error(
+          'LazyShared thunk cycle: this cell is read inside its own ' +
+            'construction. Break the dependency between the two thunks.',
+        );
+      }
+      this.constructing = true;
+      try {
+        this.stored = this.make();
+        this.constructed = true;
+      } finally {
+        this.constructing = false;
+      }
+    }
+    return this.stored as T;
+  }
+
+  /**
+   * Drop the constructed value; the next read constructs again. For
+   * tests and process recomposition — production code never resets.
+   */
+  reset(): void {
+    this.constructed = false;
+    this.stored = null;
+  }
+}

package/lib/__tests__/LazyShared.vitest.spec.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { LazyShared } from '../LazyShared';
+import { Static } from '../Static';
+
+describe('LazyShared', () => {
+  it('evaluates nothing at definition, constructs once, shares the result', () => {
+    let constructionCount = 0;
+    const cell = new LazyShared(() => {
+      constructionCount += 1;
+      return { count: constructionCount };
+    });
+    expect(constructionCount).toBe(0); // load-safe: the thunk is inert
+    expect(cell.value).toBe(cell.value);
+    expect(constructionCount).toBe(1);
+  });
+
+  it('every receiver converges on the ONE singleton — forking the access path is harmless', () => {
+    let constructionCount = 0;
+    class $Owner {
+      protected static readonly sharedStore = new LazyShared(() => {
+        constructionCount += 1;
+        return new Map<string, number>();
+      });
+      static store(): Map<string, number> {
+        return this.sharedStore.value;
+      }
+    }
+    class $SubReceiver extends $Owner {}
+    $Owner.store().set('planted', 7);
+    expect($SubReceiver.store().get('planted')).toBe(7);
+    expect($SubReceiver.store()).toBe($Owner.store());
+    expect(constructionCount).toBe(1);
+  });
+
+  it('even a per-receiver $-cache over the cell returns the same singleton', () => {
+    // The registry-fork trap: Static()'s $-getters cache per receiver,
+    // so parent and subclass each run the getter body once. With the
+    // body reading a LazyShared cell, both receivers cache the SAME
+    // constructed value — the fork exists only in the access path.
+    let constructionCount = 0;
+    class $Registry {
+      protected static readonly sharedEntries = new LazyShared(() => {
+        constructionCount += 1;
+        return new Map<string, number>();
+      });
+      static get $entries(): Map<string, number> {
+        return this.sharedEntries.value;
+      }
+    }
+    const Registry = Static($Registry);
+    class $SubRegistry extends Registry {}
+    const SubRegistry = Static($SubRegistry);
+    Registry.$entries.set('planted', 7);
+    expect(SubRegistry.$entries).toBe(Registry.$entries);
+    expect(SubRegistry.$entries.get('planted')).toBe(7);
+    expect(constructionCount).toBe(1);
+  });
+
+  it('reset drops the value and the next read constructs again', () => {
+    let constructionCount = 0;
+    const cell = new LazyShared(() => (constructionCount += 1));
+    expect(cell.value).toBe(1);
+    cell.reset();
+    expect(cell.value).toBe(2);
+  });
+
+  it('a thunk cycle throws a named error and leaves the cell retryable', () => {
+    const cellA = new LazyShared((): number => cellB.value + 1);
+    const cellB = new LazyShared((): number => cellA.value + 1);
+    expect(() => cellA.value).toThrow('LazyShared thunk cycle');
+    // not poisoned: break the cycle and the same cell constructs fine
+    let repaired = 0;
+    const cellC = new LazyShared((): number => (repaired += 1));
+    expect(cellC.value).toBe(1);
+    // the failed cell itself retries once its dependency resolves
+    expect(() => cellB.value).toThrow('LazyShared thunk cycle');
+  });
+
+  it('a throwing thunk does not poison the cell — the next read retries', () => {
+    let attempts = 0;
+    const cell = new LazyShared(() => {
+      attempts += 1;
+      if (attempts === 1) throw new Error('backend not ready');
+      return 'ready';
+    });
+    expect(() => cell.value).toThrow('backend not ready');
+    expect(cell.value).toBe('ready');
+    expect(attempts).toBe(2);
+  });
+});

package/lib/extras.ts

@@ -7,3 +7,4 @@
  *   import { Static } from 'ivue/extras';
  */
 export { Static, type ClassConstructor } from './Static';
+export { LazyShared } from './LazyShared';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
@@ -29,6 +29,8 @@
     "measure:formula": "node demo/formula/measure.mjs",
     "measure:grid": "node demo/grid/measure.mjs",
     "dev:docs": "npm --prefix docs_v2 run dev -- --port 5174",
+    "admin": "vite newsletter/dashboard --host",
+    "build:admin": "vite build newsletter/dashboard",
     "test": "vitest --coverage.enabled=true --reporter=verbose --ui",
     "coverage": "vitest run --coverage",
     "bench": "vitest bench --run",
@@ -37,11 +39,16 @@
     "cypress:headed": "cypress run --component --browser chrome --headed --no-exit",
     "build": "tsc --version;tsc --p ./tsconfig.json && vite build",
     "build:demo": "tsc --p ./tsconfig.json && vite build demo",
-    "build:docs": "npm run sync:examples && npm --prefix docs_v2 run build && npm run check:links",
+    "build:docs": "npm run sync:examples && npm run sync:releases && npm run sync:blog-index && npm --prefix docs_v2 run build && npm run check:links && node docs_v2/scripts/check-related-posts.mjs",
+    "sync:releases": "node docs_v2/scripts/releases-page-generator.mjs",
+    "sync:blog-index": "node docs_v2/scripts/blog-index-generator.mjs",
     "check:links": "node docs_v2/scripts/check-links.mjs",
     "render:og": "node docs_v2/scripts/brand-image-generator.mjs og",
     "render:form-header": "node docs_v2/scripts/brand-image-generator.mjs form-header",
     "render:banner": "node docs_v2/scripts/brand-image-generator.mjs blog",
+    "render:diagram": "node docs_v2/scripts/brand-image-generator.mjs diagram",
+    "render:embeds": "node docs_v2/scripts/blog-embed-shots.mjs",
+    "render:code-shots": "node docs_v2/scripts/blog-code-shots.mjs",
     "sync:blog-dates": "node docs_v2/scripts/blog-dates-generator.mjs",
     "preview:demo": "npm run build:demo && vite preview demo --host",
     "preview:docs": "npm --prefix docs_v2 run preview",
@@ -51,7 +58,8 @@
     "sync:examples": "node -e \"require('fs').copyFileSync('lib/Reactive.ts','examples/playground/src/ivue.ts')\"",
     "dev:playground": "vite examples/playground --host",
     "build:playground": "vite build examples/playground",
-    "preview:playground": "vite preview examples/playground --host"
+    "preview:playground": "vite preview examples/playground --host",
+    "rename:blog-slug": "node docs_v2/scripts/rename-blog-slug.mjs"
   },
   "peerDependencies": {
     "vue": "^3.2.0",

package/skills/ivue/SKILL.md

@@ -12,6 +12,12 @@ tracking), methods become stable bound functions. Instances stay plain objects.
 Follow the rules below exactly — every deviation is either a compile error or a
 silent no-op at runtime.
 
+The manual reads in three parts: the **`Reactive()` instance world**
+(the class and SFC templates, ownership, typing, watches, stores, keyed
+state), the **static world** (`Static()`, shared stores, and reading
+your own statics — everything from `ivue/extras`), and the **style
+contract** (naming, spacing, the self-review checklist).
+
 ## Setup — ivue must be installed
 
 `import { Reactive } from 'ivue'` resolves only when the package is a
@@ -30,7 +36,6 @@ path and skip the install; never add the dependency alongside a vendored copy.
 
 ```ts
 import { Reactive } from 'ivue'; // in this app: 'src/utils/ivue'
-import { Static } from 'ivue/extras';
 import {
   ref,
   shallowRef,
@@ -43,10 +48,6 @@ import {
 import { useProjectStore } from 'src/stores/project.store';
 
 class $Box {
-  static get DEFAULT_HEIGHT() {
-    return 4;
-  }
-
   // Constructor runs SYNCHRONOUSLY where you `new` — in setup() that
   // means the constructor body IS setup code, and the whole toolbox
   // works here:
@@ -73,7 +74,7 @@ class $Box {
   // RAW: read AND write via .value. shallowRef for big structures you
   // REPLACE wholesale.
   get height() {
-    return ref((this.constructor as typeof $Box).DEFAULT_HEIGHT);
+    return ref(4);
   }
   get rows() {
     return shallowRef<Row[]>([]);
@@ -179,13 +180,18 @@ class $Box {
 }
 
 export namespace Box {
-  export const $Class = Static($Box); // static anchor — children `extends` this
+  export const $Class = $Box; // raw — children `extends` this
   export let Class = Reactive($Class); // reactive — you `new` this
   // the type of every unwrapping surface (defineExpose, reactive())
   export type Instance = typeof Class.Instance;
 }
 ```
 
+A class with NO static members exports exactly this shape. Only a class
+that DECLARES statics anchors them — `export const $Class =
+Static($Box)` — and reads them from instance code through `self`; both
+live in the static-world sections below.
+
 ### The optional `Model` line (domain entity graphs)
 
 When classes hold and pass RAW instances of each other — entity
@@ -348,6 +354,23 @@ call site. Rules that keep it clean:
   nobody keeps it; here a named plain getter costs zero bytes, so there is
   no excuse. Templates read as prose: bindings, names, and events — never
   expressions.
+- **The rule covers EVERY binding kind, not just `v-if`** — the common
+  leaks are display strings, disabled states, and class objects:
+
+  | leaked into the template | derived on the class |
+  | --- | --- |
+  | interpolating `sending ? 'Sending…' : 'Send to ' + recipients.length` | interpolating `model.sendButtonLabel` |
+  | `:disabled="!model.canSend \|\| sending"` | `:disabled="model.sendDisabled"` |
+  | `:class="{ active: view === tab.name }"` | `:class="{ active: app.isOpen(tab.name) }"` |
+  | `row.name \|\| '—'` in a `v-for` cell | `Format.Class.orDash(row.name)` |
+  | `:style` width from `(day.count / peak) * 100 + '%'` | `:style` width from `model.barWidth(day)` |
+
+  Each right-hand form is a prototype member: unit-testable without
+  mounting anything, greppable by name, typed, and hot-graftable. The
+  one thing that stays in the template is STRUCTURE — `v-if`/`v-else`
+  branching on a named condition or a data field (`v-if="entry.nextSlug"`)
+  and `v-for` over a collection. Branching on data is structure;
+  COMPUTING with data is logic, and logic lives on the class.
 
 ## The outliving instance (module singleton, entity)
 
@@ -417,11 +440,13 @@ session.dispose();
 | ✅ `new X.Class(props, emit)` — raw instance everywhere | ❌ wrap in `reactive(instance)` or any shallow-unwrap view as the standard |
 | ✅ destructure ALL template-touched Refs/Computeds + element refs, grouped | ❌ destructure plain getters or methods — snapshots a dead value / loses nothing but clarity |
 | ✅ state bindings in templates; dotted `box.x` only for plain getters/methods | ❌ reach a Ref through the instance in a template — `v-if="box.someRef"` is always-truthy |
+| ✅ labels, disabled states, and class conditions as named getters/methods (`model.sendButtonLabel`, `model.sendDisabled`) | ❌ ternaries, `\|\|`/`&&` chains, comparisons, or string-building inside template expressions |
 | ✅ `defineExpose(box as X.Instance)` | ❌ `defineExpose(box)` raw — readonly-accessor writes will type-error for consumers |
 | ✅ constructor runs init; register hooks/watchers there | ❌ add an `init()` method expecting auto-call — ivue never calls it |
 | ✅ plain `watch` in component-scoped constructors; `$watch` + a `$stopEffects` dispose path for outliving instances | ❌ default to `this.$watch` in a component-scoped class — its scope silently outlives unmount |
 | ✅ compose cleanup as an ordinary method — `dispose() { /* non-Vue cleanup */ this.$stopEffects(); }` | ❌ expect a teardown hook — ivue auto-calls NOTHING (no `init()`, no `stopEffects()`) |
 | ✅ a class with static members anchors them: `const $Class = Static($X)` (`ivue/extras`) | ❌ `extends X.Class` — the mutable slot is an eager snapshot of one generation; always extend `$Class` |
+| ✅ instance code reads its own statics through `this.self` (the one cast per class); hoist `const self = this.self` for 2+ reads or any loop | ❌ per-site `(this.constructor as typeof $X)` casts — each one is an unchecked class-name assertion |
 
 ## The unwrapping-surface typing invariant
 
@@ -483,6 +508,220 @@ until mount — use `?.` in watch getters).
 - Watch CALLBACKS delegate to methods (the thin-closure rule):
   `watch(source, (newValue, oldValue) => this.onChanged(newValue, oldValue))`.
 
+## computed() and watch callbacks delegate to methods
+
+A reactive closure is cached per instance. Keep that closure as a small
+pointer to behavior on the prototype: **closures connect; methods contain
+logic.**
+
+```ts
+// ✅ THIN — the closure only delegates; logic stays named and testable
+get sortedItems() {
+  return computed(() => this.sortItems());
+}
+sortItems() {
+  return [...this.items.value].sort(byPrice);
+}
+
+// ✅ same rule for watch callbacks wired in constructors
+watch(value, (newValue, oldValue) =>
+  this.onValueChanged(newValue, oldValue),
+);
+
+// ❌ FAT — logic is anonymous and duplicated inside the cached closure
+get sortedItems() {
+  return computed(() => [...this.items.value].sort(byPrice));
+}
+```
+
+Also buys: guaranteed-minimum memory (the thin closure captures nothing but
+the instance — a fat closure silently pins any getter-scope local for the
+instance's lifetime) and direct testability (`instance.sortItems()`).
+Reactivity is unaffected — reads inside the method are tracked through the
+computed's evaluation exactly as if inlined.
+
+Do NOT "optimize" the arrow away to `computed(this.sortItems)`: it works
+(ivue methods are lazy-bound) but Vue 3.4+ passes the previous value as the
+getter's first argument, so a method that later gains an optional parameter
+silently receives stale data. Always the arrow.
+
+`$`-prefixed singleton getters are frozen caches too — keep their bodies to
+a single composable/service call (`return useThing()`), nothing more.
+
+## The store pattern: a singleton behind `use()`, injected by `$`-getter
+
+Shared application state (session, navigation, toasts, the current user)
+is a STORE — one ivue class published as a module singleton — never a
+model passed down as a prop. Prop-drilling a shared model
+(`<ChildView :app="app" />`, `constructor(public app: AppModel.Instance)`)
+threads one object through every component and constructor signature it
+crosses; the store pattern deletes the thread.
+
+```ts
+// app/AppStore.ts — the store IS an ivue class; `use()` owns the singleton
+class $AppStore {
+  get authenticated() {
+    return ref(false);
+  }
+
+  notify(message: string) {
+    /* ... */
+  }
+}
+
+export namespace AppStore {
+  export const $Class = $AppStore;
+  export let Class = Reactive($Class);
+  export type Instance = typeof Class.Instance;
+
+  let singleton: Instance | null = null;
+  export function use(): Instance {
+    return (singleton ??= new Class());
+  }
+}
+```
+
+Consumers never receive it — they REACH for it:
+
+```ts
+// any model — the `$`-getter caches the store per instance, forever
+class $SubscribersModel {
+  protected get $app() {
+    return AppStore.use();
+  }
+
+  async refresh() {
+    try {
+      /* ... */
+    } catch (error) {
+      this.$app.reportFailure(error);
+    }
+  }
+}
+```
+
+```vue
+<script setup lang="ts">
+// any component — call use() directly; no prop, no provide/inject
+import { AppStore } from '../app/AppStore';
+
+const app = AppStore.use();
+const { authenticated } = app;
+</script>
+
+<template>
+  <button v-if="authenticated" @click="app.logout()">Lock</button>
+</template>
+```
+
+Why this shape and not alternatives:
+
+- **`use()` is lazy** — the singleton constructs on first touch, after the
+  app exists, so module-load order and circular imports stay non-events
+  (the same late-read property as every cross-module reference).
+- **The `$`-getter is the injection point** — cached whole, per instance,
+  on first read. A model names its dependency once; every method reads
+  `this.$app` with zero lookup cost and zero constructor plumbing.
+- **Tests swap the slot, not the callers** — `AppStore.Class = $TestStore`
+  before the first `use()` (or reset the singleton) and every consumer
+  gets the double through the same seam.
+- A store is component-OUTLIVING by definition: watchers inside it use
+  `this.$watch`/`$watchEffect`, never plain `watch`, and lifecycle hooks
+  never belong in it.
+- Pass PROPS for what is genuinely per-instance input (a row, a slug, a
+  config knob). Reach for the STORE for what is genuinely shared. A prop
+  named `app`, `store`, or `session` is the tell that a store is being
+  drilled.
+
+## Keyed reactivity — the third state shape
+
+Ref-getters express NAMED members; `shallowRef` expresses wholesale-replaced
+structures. When state is KEYED — sparse, unbounded, indexed by ids or
+coordinates unknown until runtime (cells by (row,col), entities by id, rows
+of a stream) — a getter per key is impossible. Hold **collections of
+reactive primitives as plain values** and materialize per observation:
+
+```ts
+class $Sheet {
+  // Plain readonly fields — the COLLECTIONS aren't reactive;
+  // their VALUES are.
+  private readonly cellVersions = new Map<number, Ref<number>>();
+
+  /**
+   * READ path: get-OR-CREATE, then subscribe — observation
+   * materializes.
+   */
+  private trackCell(cellKey: number): void {
+    let versionRef = this.cellVersions.get(cellKey);
+    if (!versionRef) {
+      versionRef = ref(0);
+      this.cellVersions.set(cellKey, versionRef);
+    }
+    // subscribes whatever effect is currently running
+    void versionRef.value;
+  }
+
+  /**
+   * WRITE path: PEEK-ONLY — unobserved keys allocate nothing,
+   * notify no one.
+   */
+  private bumpCell(cellKey: number): void {
+    const versionRef = this.cellVersions.get(cellKey);
+    if (versionRef) versionRef.value++;
+  }
+}
+```
+
+The read/write ASYMMETRY is the pattern: reads get-or-create (cost is priced
+by observation), while writes to unobserved keys allocate no signal. Rules that keep it honest:
+
+- Ground truth lives in plain storage (typed arrays, Maps); the refs are
+  VERSION SIGNALS, not value holders — bump to invalidate, readers re-derive.
+- Per-key cached computeds follow the same shape (`Map<key, ComputedRef>`),
+  bodies delegating to methods (the thin-closure rule), and MUST have an explicit release/
+  eviction path — keyed overlays cannot GC on their own (the Map holds
+  strong refs; attached watchers subscribe permanently).
+- Coarse tiers are the same pattern at lower resolution: one ref covering
+  many keys (a block of rows, a whole-collection version counter) for
+  subscribers that span many keys — one integer where naive design puts a
+  million nodes.
+- No wrapper needed: `ref()`/`computed()` are first-class values from
+  `@vue/reactivity`; Maps of them inside a `Reactive()` class compose with
+  everything (methods stay bound and `$watch` works).
+
+| state shape                  | expression                                            |
+| ---------------------------- | ----------------------------------------------------- |
+| named members                | `get x() { return ref(v) }`                           |
+| wholesale-replaced structure | `get rows() { return shallowRef<Row[]>([]) }`         |
+| keyed / sparse / unbounded   | `Map<key, Ref>` + get-or-create track, peek-only bump |
+
+Same invariant at three granularities — nothing exists until observed: getters
+price MEMBERS, keyed collections price KEYS. (Proven at 20M cells / 4.7
+bytes each — see the flyweight grid.)
+
+## Generic classes (brief)
+
+`ReactiveClass<C>` cannot carry `<T>` through (no higher-kinded types), but
+`Reactive(X) === X` by identity — so cast `Class` back to the raw
+constructor and apply `ReactiveInstance` explicitly for `Instance`:
+
+```ts
+class $Scroller<T extends BaseItem> {
+  get items() {
+    return ref<T[]>([]);
+  }
+}
+
+export namespace Scroller {
+  export const $Class = $Scroller;
+  // the cast keeps <T> available at `new` sites
+  export let Class = Reactive($Class) as unknown as typeof $Class;
+  export type Instance<T extends BaseItem> =
+    ReactiveInstance<$Scroller<T>>;
+}
+// consumer of a template ref: ShallowUnwrapRef<Scroller.Instance<T>>
+```
+
 ## Circular references resolve by construction
 
 The hoisted-namespace + getter convention makes late cross-module references
@@ -509,8 +748,51 @@ files, git, parsers, clocks: never constructed, only called and swapped — use
   router/queue/listener callback, bound to the RECEIVING class.
 - **Get-only statics named `$…` compute once PER RECEIVER.** The `$` prefix
   promises stable identity, NOT immutability — a mutable memo table is a
-  legitimate `$`-cache. Non-`$` static getters stay LIVE: those are the knobs
-  test subclasses pinch.
+  legitimate `$`-cache. Non-`$` static getters stay LIVE: the settings a
+  subclass or test double overrides.
+- **A SHARED STORE never lives in receiver-space.** Per-receiver caching
+  means a subclass reading `this.$store` silently forks a fresh copy — the
+  registry-fork trap. The store is a `static readonly` FIELD on the
+  declaring class — one reference, inherited through the prototype chain,
+  never receiver-cached — so every receiver read (`this.$store`,
+  `this.constructor.$store`) resolves to the one store with no special
+  case anywhere; the `$`-getter pins by returning the field:
+  ```ts
+  class $Registry {
+    protected static readonly sharedRegistrations = new Map<object, Registration>();
+    protected static get $registrations() {
+      return this.sharedRegistrations; // the field IS the pin
+    }
+  }
+  ```
+  Two questions place every static value:
+
+  1. **Should a subclass get its own copy?** Yes → per-receiver
+     `$`-cache. That is what memos and per-class tuning want: forking on
+     subclass is the feature. No → it is a SHARED store (a registry, a
+     ledger — forking is the bug), and it lives in a `static readonly`
+     field as above.
+  2. **Shared store: can its initializer run at module load?** A field
+     initializer runs while modules are still loading, so it may only
+     hold a dependency-free value — a bare `new Map()`, a literal. The
+     moment construction needs ANOTHER module's class, the field holds a
+     `LazyShared` cell instead (`import { LazyShared } from
+     'ivue/extras'`), and the `$`-getter reads through it:
+     ```ts
+     protected static readonly sharedBackend = new LazyShared(
+       () => new SearchBackend.Class(),
+     );
+     protected static get $backend() {
+       return this.sharedBackend.value;
+     }
+     ```
+     Each step is safe on its own terms. Storing the cell eagerly is
+     safe because a thunk evaluates nothing at load. Running the thunk
+     on first read is safe because by then every import cycle has
+     resolved. And sharing is safe because the memoized value lives
+     INSIDE the cell — every access path, subclass receivers and
+     per-receiver `$`-caches over the cell included, converges on the
+     one constructed singleton.
 
 THE ANCHOR RULE — a class that declares static members wraps them ONCE, at
 `$Class`, so subclasses and test doubles inherit working semantics by
@@ -577,85 +859,56 @@ Take the first rung that applies:
    ```ts
    protected get tooltipDwellSeconds() { return 0.4; }
    ```
-2. **Something outside reads it** (tests pinching the knob, another class)
-   → keep the static and read it live off the receiver:
+2. **Something outside reads it** (a test overriding the knob, another class)
+   → keep the static and read it through **`self`** — the one cast per
+   class, declared beside the statics it types — DIRECTLY at each call
+   site:
    ```ts
-   protected get tooltipDwellSeconds() {
-     return (this.constructor as typeof $Tooltip).TOOLTIP_DWELL_SECONDS;
+   protected get self() {
+     return this.constructor as typeof $Tooltip;
+   }
+
+   show() {
+     this.dwellTimer.start(this.self.TOOLTIP_DWELL_SECONDS);
    }
    ```
-   `this.constructor` is the actual class: the subclass when subclassed, and
-   an engine class that INHERITS `$Class` for a plain reactive instance, so
-   statics resolve in both cases. TypeScript types `constructor` as
-   `Function`, so the one cast is required and is the honest cost.
+   An instance getter over a static earns its place when it genuinely
+   derives — mixing in instance state or transforming the value; a
+   plain read stays a direct `this.self.X` at the call site, so the
+   knob keeps one name and one override surface (the static).
+   `this.constructor` is the actual class — the subclass when subclassed,
+   and an engine class that INHERITS `$Class` for a plain reactive
+   instance — so statics resolve late-bound in both cases.
+   TypeScript types `constructor` as bare
+   `Function`, so ONE cast is unavoidable; `self` is where it lives.
+   Never scatter per-site `(this.constructor as typeof $X)` casts: each
+   is an unchecked assertion that the class name is right, and the
+   copy-paste error it invites typechecks silently against the wrong
+   statics. Rules that keep `self` honest:
+   - **Plain getter, never `$self`** — a `$`-cache would spend a
+     per-instance slot on what `this.constructor` hands back for free.
+   - **One read → `this.self.X` inline. Two or more reads, or any
+     loop → hoist:** `const self = this.self;` as the first line, then
+     `self.X` throughout. Measured (Node 26): the de-opted `self` getter
+     costs ~2 ns/read over an inline cast — noise for a single read —
+     while the hoisted form runs at ~0.4 ns/iter in loops, CHEAPER than
+     the inline cast, because the engine hoists the class as a loop
+     constant.
+   - **A subclass that adds statics redeclares `self`** with its own
+     `typeof $Sub` (a covariant override); a subclass that only tunes
+     inherited statics needs nothing — `self` is already late-bound.
+   - **`self` is NOT the namespace slot.** `this.self` is the class you
+     were constructed from; `Namespace.Class` is the live mutable slot a
+     kernel may have re-pointed since. Receiver statics (constants,
+     per-class tuning, `$`-caches) read through `self`; late-bound
+     capability dispatch reads through `Namespace.Class`. Blurring them
+     trades typo bugs for staleness bugs.
 3. **Overriding must NOT happen** → name the class directly,
    `$Tooltip.TOOLTIP_DWELL_SECONDS`, and let the code say so.
 
 Never introduce a `protected get <ClassName>()` self-reference getter. It is a
-cast wearing a getter costume: it looks live and is not.
-
-## Generic classes (brief)
-
-`ReactiveClass<C>` cannot carry `<T>` through (no higher-kinded types), but
-`Reactive(X) === X` by identity — so cast `Class` back to the raw
-constructor and apply `ReactiveInstance` explicitly for `Instance`:
-
-```ts
-class $Scroller<T extends BaseItem> {
-  get items() {
-    return ref<T[]>([]);
-  }
-}
-
-export namespace Scroller {
-  export const $Class = $Scroller;
-  // the cast keeps <T> available at `new` sites
-  export let Class = Reactive($Class) as unknown as typeof $Class;
-  export type Instance<T extends BaseItem> =
-    ReactiveInstance<$Scroller<T>>;
-}
-// consumer of a template ref: ShallowUnwrapRef<Scroller.Instance<T>>
-```
-
-## computed() and watch callbacks delegate to methods
-
-A reactive closure is cached per instance. Keep that closure as a small
-pointer to behavior on the prototype: **closures connect; methods contain
-logic.**
-
-```ts
-// ✅ THIN — the closure only delegates; logic stays named and testable
-get sortedItems() {
-  return computed(() => this.sortItems());
-}
-sortItems() {
-  return [...this.items.value].sort(byPrice);
-}
-
-// ✅ same rule for watch callbacks wired in constructors
-watch(value, (newValue, oldValue) =>
-  this.onValueChanged(newValue, oldValue),
-);
-
-// ❌ FAT — logic is anonymous and duplicated inside the cached closure
-get sortedItems() {
-  return computed(() => [...this.items.value].sort(byPrice));
-}
-```
-
-Also buys: guaranteed-minimum memory (the thin closure captures nothing but
-the instance — a fat closure silently pins any getter-scope local for the
-instance's lifetime) and direct testability (`instance.sortItems()`).
-Reactivity is unaffected — reads inside the method are tracked through the
-computed's evaluation exactly as if inlined.
-
-Do NOT "optimize" the arrow away to `computed(this.sortItems)`: it works
-(ivue methods are lazy-bound) but Vue 3.4+ passes the previous value as the
-getter's first argument, so a method that later gains an optional parameter
-silently receives stale data. Always the arrow.
-
-`$`-prefixed singleton getters are frozen caches too — keep their bodies to
-a single composable/service call (`return useThing()`), nothing more.
+cast wearing a getter costume: it looks live and is not — `self` is its
+honest replacement.
 
 ## Naming: unfold to the domain
 
@@ -688,72 +941,6 @@ like prose — don't ruin it with letter soup:
 // ✅ watch(value, (newValue, oldValue) => this.onChanged(…))
 ```
 
-## Keyed reactivity — the third state shape
-
-Ref-getters express NAMED members; `shallowRef` expresses wholesale-replaced
-structures. When state is KEYED — sparse, unbounded, indexed by ids or
-coordinates unknown until runtime (cells by (row,col), entities by id, rows
-of a stream) — a getter per key is impossible. Hold **collections of
-reactive primitives as plain values** and materialize per observation:
-
-```ts
-class $Sheet {
-  // Plain readonly fields — the COLLECTIONS aren't reactive;
-  // their VALUES are.
-  private readonly cellVersions = new Map<number, Ref<number>>();
-
-  /**
-   * READ path: get-OR-CREATE, then subscribe — observation
-   * materializes.
-   */
-  private trackCell(cellKey: number): void {
-    let versionRef = this.cellVersions.get(cellKey);
-    if (!versionRef) {
-      versionRef = ref(0);
-      this.cellVersions.set(cellKey, versionRef);
-    }
-    // subscribes whatever effect is currently running
-    void versionRef.value;
-  }
-
-  /**
-   * WRITE path: PEEK-ONLY — unobserved keys allocate nothing,
-   * notify no one.
-   */
-  private bumpCell(cellKey: number): void {
-    const versionRef = this.cellVersions.get(cellKey);
-    if (versionRef) versionRef.value++;
-  }
-}
-```
-
-The read/write ASYMMETRY is the pattern: reads get-or-create (cost is priced
-by observation), while writes to unobserved keys allocate no signal. Rules that keep it honest:
-
-- Ground truth lives in plain storage (typed arrays, Maps); the refs are
-  VERSION SIGNALS, not value holders — bump to invalidate, readers re-derive.
-- Per-key cached computeds follow the same shape (`Map<key, ComputedRef>`),
-  bodies delegating to methods (the thin-closure rule), and MUST have an explicit release/
-  eviction path — keyed overlays cannot GC on their own (the Map holds
-  strong refs; attached watchers subscribe permanently).
-- Coarse tiers are the same pattern at lower resolution: one ref covering
-  many keys (a block of rows, a whole-collection version counter) for
-  subscribers that span many keys — one integer where naive design puts a
-  million nodes.
-- No wrapper needed: `ref()`/`computed()` are first-class values from
-  `@vue/reactivity`; Maps of them inside a `Reactive()` class compose with
-  everything (methods stay bound and `$watch` works).
-
-| state shape                  | expression                                            |
-| ---------------------------- | ----------------------------------------------------- |
-| named members                | `get x() { return ref(v) }`                           |
-| wholesale-replaced structure | `get rows() { return shallowRef<Row[]>([]) }`         |
-| keyed / sparse / unbounded   | `Map<key, Ref>` + get-or-create track, peek-only bump |
-
-Same invariant at three granularities — nothing exists until observed: getters
-price MEMBERS, keyed collections price KEYS. (Proven at 20M cells / 4.7
-bytes each — see the flyweight grid.)
-
 ## Spacing is information
 
 Contiguity says "same kind of thing"; a blank line says "the kind changes,
@@ -841,5 +1028,6 @@ convention and check it in review.
 - [ ] Identifiers are unfolded to domain words (`row`/`col`/`cell`/`cellValue`/`versionRef`…), loop indices and specs included — no single-letter names, no name meaning different things in different methods.
 - [ ] Keyed/sparse state uses the Map-of-refs shape (get-or-create on read, peek-only bump on write, explicit release path) — never one getter per key, never a deep `reactive()` collection.
 - [ ] Static members are anchored (`const $Class = Static($X)`); `$`-prefixed static getters are compute-once-per-receiver caches, non-`$` statics stay live knobs, and inheritance extends `$Class` — never the mutable `Class`.
+- [ ] Instance reads of own statics go through `this.self` (declared once per class needing it, cast to `typeof $X`, plain getter never `$self`); 2+ reads or loops hoist `const self = this.self`; no per-site `this.constructor` casts; `Namespace.Class` reads stay reserved for late-bound capability dispatch.
 - [ ] Static members precede the constructor; the constructor precedes state, prop, and derived getters; methods come last.
 - [ ] Spacing carries meaning: declaration-like getters contiguous within their group; blank lines only where a doc comment / multi-line body / category boundary begins; methods always separated.