ivue 2.2.2 → 2.4.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)
 
@@ -364,14 +387,32 @@ class $Session {
   // Outliving instance: $watch/$watchEffect register in the
   // instance's lazy effectScope — there is no component scope here
   // to reap plain watch.
+  // WATCHERS live behind a method, not inline in the constructor —
+  // the constructor calls it once, and the instance can RESTART its
+  // watchers after a keep-state stop (see suspend() below).
   constructor() {
+    this.startWatchers();
+    // If constructed INSIDE some scope, auto-wire teardown instead:
+    //   getCurrentScope() && onScopeDispose(() => this.$stopEffects());
+  }
+
+  startWatchers() {
     this.$watch(
       () => this.user.value,
       (user, previousUser) => this.onUserChanged(user, previousUser),
     );
     this.$watchEffect(() => this.persist());
-    // If constructed INSIDE some scope, auto-wire teardown instead:
-    //   getCurrentScope() && onScopeDispose(() => this.$stopEffects());
+  }
+
+  // SUSPEND / RESUME: { reset: false } stops the watchers ONLY — every
+  // cached cell survives with its current value. startWatchers() in a
+  // fresh scope resumes. (Default $stopEffects() also CLEARS the cells:
+  // the next touch re-runs initializers — disposal is a reset.)
+  suspend() {
+    this.$stopEffects({ reset: false });
+  }
+  resume() {
+    this.startWatchers();
   }
 
   // CLEANUP composes as an ORDINARY method — no hooks, no reserved
@@ -417,11 +458,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
 
@@ -465,7 +508,11 @@ until mount — use `?.` in watch getters).
   its leaf reads subscribe directly (non-intuitive but structural).
 - The source MUST be the FUNCTION form. `watch(instance.plainGetter, cb)` passes a
   dead snapshot and never fires.
-- `$stopEffects()` stops the instance scope and clears cached Refs/Computeds;
+- `$stopEffects()` stops the instance scope and clears cached Refs/Computeds
+  (the next touch re-materializes — disposal is a reset);
+  `$stopEffects({ reset: false })` stops the WATCHERS only — every cached
+  cell survives with its current value, and `startWatchers()` in a fresh
+  scope resumes (the suspend/resume pattern above);
   instances that never `$watch` allocate no scope. There are NO hooks — richer
   cleanup is an ordinary method that does its work and then calls
   `$stopEffects()` itself. Every outliving instance needs an OWNER that calls
@@ -483,6 +530,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 +770,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 +881,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 +963,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 +1050,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.