ivue 2.4.0 → 2.6.0

package/skills/ivue/SKILL.md

@@ -145,7 +145,7 @@ class $Box {
   // STORE / COMPOSABLE — `$`-getter caches WHOLE, forever, per
   // instance. Resolves on first touch (after Pinia/app ready);
   // circular-import safe.
-  private get $project() {
+  protected get $project() {
     return useProjectStore();
   }
   get projectId() {
@@ -270,6 +270,244 @@ defineExpose(box as Box.Instance);
 </template>
 ```
 
+## The class carries the WHOLE contract; the namespace is identity and types
+
+A class FILE is a SINGLE-FILE MODEL — the model-side twin of the
+single-file component. It has exactly three residents: imports, the
+class, the namespace. The component contract — prop types, prop defaults, their
+fusion, emits, and every tuning constant — lives ON THE CLASS as static
+getters, beside the state and behavior it governs. The namespace holds
+identity and TYPES only, every type DERIVED from `$Class`. Two worlds
+would make a class half extensible: a `const` in a namespace cannot be
+overridden by a subclass, is not inherited, and does not swap with
+`Class` under a global override — so a runtime declaration never lives
+there.
+
+- **Contract (on the class, static)** — `static get propsTypes()`
+  (defineComponent-style, no defaults, returned through
+  `definePropTypes({...})` so the `required: true` literal survives
+  `typeof`); `static get propsDefaults()` (plain values, annotated
+  `ExtractPropDefaultTypes<typeof $X.propsTypes>` — required props are
+  filtered out of the check automatically, and a deliberately
+  default-free optional prop is declared `key: undefined`, stating the
+  ruling in data); `static get props()` — the ONE fusion line,
+  `propsWithDefaults(this.propsDefaults, this.propsTypes)`, reading
+  through the receiver so a subclass's `props` fuses ITS types and
+  defaults; `static get emits()` (object-declared validators). Tuning
+  constants are plain static getters too — live knobs a subclass or test
+  double overrides; the `$` prefix stays reserved for compute-once caches.
+  Types and defaults stay two members ON PURPOSE: a variant re-tunes
+  defaults without re-typing. A nested object prop (a knobs tree) is
+  filled from the defaults at every depth with `nestedProps(props,
+  this.self.propsDefaults)` from `ivue/extras`, once, in the
+  constructor (in place — lodash's `defaultsDeep` with arrays taken
+  whole); the class reads complete props and never merges in a getter.
+  Vue itself never merges a supplied object with its default.
+- **Identity (namespace)** — `$Class` (raw, for children to extend),
+  `Class` (`Reactive()`, for you to `new`), `Instance` (and `Model` when
+  used).
+- **Types (namespace)** — DERIVED from the class, never hand-duplicated:
+  `Props` is `ExtractPropTypes<typeof $Class.props>` (a generic component
+  grafts its parameter back over the one prop a runtime map cannot
+  carry: `Omit<ExtractPropTypes<typeof $Class.props>, 'modelValue'> &
+  { modelValue: T[] }`); `Emits` is `ExtractEmitTypes<typeof
+  $Class.emits>`; `Slots`; `Exposed` is `ShallowUnwrapRef<Instance>`.
+  Domain types the contract refers to (an item shape, a variant preset)
+  live here as namespace types; the class reads them as `X.Item`.
+
+Combined — the canonical file, everything above in one shape:
+
+```ts
+// Box.ts — the whole module: imports, the class, the namespace. Nothing else.
+import type { ExtractPropTypes, PropType, ShallowUnwrapRef } from 'vue';
+import {
+  definePropTypes,
+  propsWithDefaults,
+  Reactive,
+  type ExtractEmitTypes,
+  type ExtractPropDefaultTypes,
+} from 'ivue';
+import { Static } from 'ivue/extras';
+
+class $Box {
+  /* Contract — STATIC: owned by the class, extended with `super` */
+
+  /** 1 — the TYPES: a defineComponent-style object, no defaults inside.
+   *  definePropTypes is an identity call that keeps `required: true` a
+   *  LITERAL — a bare object widens it to boolean, which would blind the
+   *  defaults check below. */
+  static get propsTypes() {
+    return definePropTypes({
+      title: { type: String as PropType<string>, required: true },
+      size: { type: Number as PropType<number> },
+      maxHeight: { type: Number as PropType<number> },
+      disabled: { type: Boolean as PropType<boolean> },
+    });
+  }
+
+  /** 2 — the DEFAULTS: plain values, typed against the types object.
+   *  Required props (`title`) are filtered out of the check
+   *  automatically; every OPTIONAL prop must appear — `undefined` is the
+   *  explicit "no default ON PURPOSE" ruling, stated in data. */
+  static get propsDefaults(): ExtractPropDefaultTypes<typeof $Box.propsTypes> {
+    return {
+      size: this.defaultSize,
+      maxHeight: undefined, // unset = unbounded — deliberately default-free
+      disabled: false,
+    };
+  }
+
+  /** 3 — the FUSION: a standard Vue props object, ready for defineProps.
+   *  Reads through the receiver — a subclass's `props` fuses ITS own
+   *  types and defaults. Written once per hierarchy; a subclass that ADDS
+   *  props re-declares this one line so its derived `Props` widens (a
+   *  static's return type is not polymorphic). */
+  static get props() {
+    return propsWithDefaults(this.propsDefaults, this.propsTypes);
+  }
+
+  static get emits() {
+    return {
+      close: (title: string) => true,
+    };
+  }
+
+  /** A tuning constant: a LIVE static knob (no `$`), overridable. */
+  static get defaultSize() {
+    return 400;
+  }
+
+  /** The one cast per class: instance code reads its own statics here. */
+  protected get self() {
+    return this.constructor as typeof $Box;
+  }
+
+  // Type positions resolve non-positionally — the class names its own
+  // namespace's derived types freely.
+  constructor(
+    public props: Box.Props,
+    public emit: Box.Emits,
+  ) {}
+
+  get title() {
+    return this.props.title;
+  }
+
+  get sizeLabel() {
+    return `${this.props.size}px`;
+  }
+
+  close() {
+    this.emit('close', this.props.title);
+  }
+}
+
+export namespace Box {
+  /* Identity */
+
+  export const $Class = Static($Box); // anchor — it declares statics; children `extends` this
+  export let Class = Reactive($Class); // reactive — you `new` this
+  export type Instance = typeof Class.Instance; // defineExpose type & reactive() interop
+
+  /* Types — DERIVED from the class's statics, never hand-duplicated */
+
+  export type Props = ExtractPropTypes<typeof $Class.props>;
+  export type Emits = ExtractEmitTypes<typeof $Class.emits>;
+
+  export interface Slots {
+    default: (scope: { title: string }) => any;
+  }
+
+  /** What consumers hold through a template ref (expose unwraps refs). */
+  export type Exposed = ShallowUnwrapRef<Instance>;
+}
+```
+
+The SFC is pure wiring against the seam, and it reads the contract
+through `Class` — the mutable slot — so a global override swaps the
+contract together with the runner. The macros receive RUNTIME objects,
+so no compiler macro ever resolves a cross-file type:
+
+```ts
+const props = defineProps(Box.Class.props); // non-generic: the type is inferred
+const emit = defineEmits(Box.Class.emits) as Box.Emits;
+defineSlots<Box.Slots>();
+// generic components cast the one graft:
+// defineProps(X.Class.props) as unknown as X.Props<T>
+```
+
+A subclass extends its contract the way it extends behavior — with
+`super`, overriding only what defines the specialization, with the
+reason on the line. Re-tuning a default needs ONE override; adding a
+prop needs the types override plus the one-line `props` re-declaration:
+
+```ts
+class $CardBox extends Box.$Class {
+  static override get propsDefaults(): typeof Box.$Class.propsDefaults {
+    return {
+      ...super.propsDefaults,
+      size: 300, // cards are hundreds of px wide; rows were tens tall
+    };
+  }
+}
+
+class $TaggedBox extends Box.$Class {
+  static override get propsTypes() {
+    return definePropTypes({
+      ...super.propsTypes,
+      tag: { type: String as PropType<string> },
+    });
+  }
+  static override get propsDefaults(): ExtractPropDefaultTypes<typeof $TaggedBox.propsTypes> {
+    return { ...super.propsDefaults, tag: '' };
+  }
+  static override get props() {
+    return propsWithDefaults(this.propsDefaults, this.propsTypes); // widens TaggedBox.Props
+  }
+}
+```
+
+The anchor rule is unchanged and now reaches every component class: a
+class that DECLARES statics — and the contract is statics — anchors at
+`$Class` with `Static()` (`export const $Class = Static($Box)`), and so
+does a subclass that overrides one. A subclass that only inherits stays
+raw. The anchor costs nothing on getters (native reads) and is what
+gives a `$`-cached static its compute-once semantics.
+
+**One seam, any size.** A contract of forty documented props is still
+authored on its class — a static getter scrolls like any other member,
+and a sibling `XProps.ts` would be the parallel world again (a second
+runtime owner the class mechanics cannot reach). Shared base surfaces
+are a base CLASS (`class $ChooseField extends Field.$Class`), never a
+spread-in const: inheritance is the only composition the contract uses.
+
+**Overrides say so out loud.** `noImplicitOverride` is on: every member
+that overrides a base member carries the `override` keyword
+(`protected override get offsetSize() { ... }`). A silent override
+refuses to compile, and a base rename breaks every subclass at the
+exact overriding member instead of quietly orphaning it.
+
+**`private` is banned — visibility is a three-tier semantic.** ivue's
+core promise is extend-don't-fork, and `private` is the one keyword
+that structurally revokes it: a subclass that needs a private member
+has exactly one option, copy the file. TypeScript's `private` is
+compile-time advisory anyway — it protects nothing at runtime and
+forbids only the legitimate extender. So every member picks its tier
+by AUDIENCE:
+
+| tier | audience | meaning |
+| --- | --- | --- |
+| `public` | templates & consumers | the component/module surface |
+| `protected` | subclasses | a seam of the hierarchy — reachable to extend, invisible to templates and consumers (TS enforces this) |
+| `private` | nobody | banned — "must hide it even from subclasses" is a design smell; resolve by naming and documenting the member |
+
+The pairing with `noImplicitOverride` is what makes protected-everything
+safe rather than fragile: every subclass touchpoint is annotated
+`override`, so a base renaming or removing a protected seam breaks
+every extender's BUILD at the exact member — seam drift is loud, never
+silent. (Both halves are load-bearing: `protected` opens every seam,
+the tsconfig makes changing one detectable.)
+
 ## One template, one logic owner
 
 Every behavioral SFC has exactly one ivue class as its template logic owner.
@@ -286,6 +524,17 @@ belong in plain getters, setup work belongs in the constructor, and event
 handlers belong in methods — even when the handler only normalizes a DOM event
 before delegating to a domain model.
 
+**One DOM event, one handler, named for the event.** A template never binds
+two events to the same method (`@pointerup="x.onUp" @pointercancel="x.onUp"`),
+and a class never registers one method for two event types. A cancel gets
+`onPointerCancel`, whose body may be one line delegating to `onPointerUp`;
+a track's `touchstart` and `touchmove` get `onTrackTouchStart` and
+`onTrackTouchMove` even when both only claim the touch. The reason is the
+override seam: a subclass that must treat a cancel differently can override
+`onPointerCancel` alone, where a shared handler would make it re-derive
+which event it is handling from the event object — and the standard's
+whole point is that behavior extends by name.
+
 When building on a class-backed component, **extend its class, not its
 `<script setup>`**. Add behavior to the existing class when it belongs to the
 same component contract. When it is a real specialization, subclass the raw
@@ -353,7 +602,10 @@ call site. Rules that keep it clean:
   In ordinary Vue this discipline costs a `computed()` per condition, so
   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.
+  expressions. The split is stage directions and script: the template says
+  who is on stage and what happens when someone acts; the class says what
+  everything MEANS. Structure stays in the template, meaning moves to the
+  class.
 - **The rule covers EVERY binding kind, not just `v-if`** — the common
   leaks are display strings, disabled states, and class objects:
 
@@ -379,6 +631,8 @@ created in a callback — watchers go in the instance's OWN scope, and the
 owner of its lifetime disposes it:
 
 ```ts
+import { Reactive, type ReactiveHelpers } from 'ivue';
+
 class $Session {
   get user() {
     return ref<User | null>(null);
@@ -441,6 +695,12 @@ export namespace Session {
   export type Instance = typeof Class.Instance;
 }
 
+// The engine installs $watch / $watchEffect / $stopEffects at Reactive(),
+// AFTER the class body was typed — so a class that calls them merges the
+// helpers into its own instance type. One line, zero runtime; the gate
+// reads it as the class's second half, never as a stray type.
+interface $Session extends ReactiveHelpers {}
+
 // The owner disposes — the class's own method, like any other:
 session.dispose();
 ```
@@ -454,7 +714,7 @@ session.dispose();
 | ✅ `.value` for every Ref/Computed inside the class and in the script body | ❌ write `this.x = v` for a Ref/Computed in the class — it clobbers the ref or no-ops |
 | ✅ derive with a PLAIN getter | ❌ wrap every derivation in `computed()` — pays ~300 bytes/instance for nothing |
 | ✅ `computed()` only for expensive / render-suppressing / stable-handle needs | ❌ reach for `computed()` by default |
-| ✅ inject stores via `private get $store() { return useStore() }` | ❌ `store = useStore()` field initializer — runs at construction, breaks tests/SSR/cycles |
+| ✅ inject stores via `protected get $store() { return useStore() }` | ❌ `store = useStore()` field initializer — runs at construction, breaks tests/SSR/cycles |
 | ✅ `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 |
@@ -462,8 +722,10 @@ session.dispose();
 | ✅ `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 |
+| ✅ a class that calls `this.$watch` / `$watchEffect` / `$stopEffects` merges the engine's helpers beside itself: `interface $X extends ReactiveHelpers {}` (one line, zero runtime) | ❌ `(this as any).$watch(...)` or per-member `declare $watch: …` lines — the body should typecheck without a cast |
 | ✅ 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` |
+| ✅ `protected` for every internal member — subclasses reach every seam | ❌ `private` anywhere in an ivue class — it forbids only the legitimate extender |
 | ✅ 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
@@ -580,8 +842,21 @@ 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
+// app/AppStore.ts — the store IS an ivue class; a static owns the singleton
+// (imports: Reactive from 'ivue'; Static from 'ivue/extras')
 class $AppStore {
+  // The ONE instance, as a `$`-static: constructed on first read, after
+  // the app exists, and cached on the receiver. It constructs through the
+  // namespace slot, so a test double swapped into `Class` is what gets
+  // built — the store has one receiver, the slot, so nothing forks.
+  protected static get $shared(): AppStore.Instance {
+    return new AppStore.Class();
+  }
+
+  static use(): AppStore.Instance {
+    return this.$shared;
+  }
+
   get authenticated() {
     return ref(false);
   }
@@ -592,14 +867,9 @@ class $AppStore {
 }
 
 export namespace AppStore {
-  export const $Class = $AppStore;
-  export let Class = Reactive($Class);
+  export const $Class = Static($AppStore); // anchor — it declares statics
+  export let Class = Reactive($Class); // reactive — use() does the one `new`
   export type Instance = typeof Class.Instance;
-
-  let singleton: Instance | null = null;
-  export function use(): Instance {
-    return (singleton ??= new Class());
-  }
 }
 ```
 
@@ -609,7 +879,7 @@ Consumers never receive it — they REACH for it:
 // any model — the `$`-getter caches the store per instance, forever
 class $SubscribersModel {
   protected get $app() {
-    return AppStore.use();
+    return AppStore.Class.use();
   }
 
   async refresh() {
@@ -627,7 +897,7 @@ class $SubscribersModel {
 // any component — call use() directly; no prop, no provide/inject
 import { AppStore } from '../app/AppStore';
 
-const app = AppStore.use();
+const app = AppStore.Class.use();
 const { authenticated } = app;
 </script>
 
@@ -640,13 +910,25 @@ 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 same late-read property as every cross-module reference). It lives
+  in a `$`-static on the class — never a namespace `let`, which is a
+  parallel world no subclass can reach (the gate's
+  `the_namespace_holds_identity_and_types_only` check refuses it). A
+  `$`-static caches per receiver, and a store reached only through
+  `X.Class.use()` has one receiver, so nothing forks; `LazyShared` is for
+  a REGISTRY that several receivers (subclasses) must share.
 - **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.
+- **A store may publish itself as a `reactive()` view** — `use()` stays
+  the one door; the `$`-static behind it returns
+  `reactive(new AppStore.Class() as AppStore.Instance)` and consumers read
+  and write with no `.value`. The `as Instance` cast is the interop form
+  the gate sanctions (it is what makes the unwrapped writes typecheck);
+  bare `reactive(new …)` is refused.
 - **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.
+  before the first `use()` and every consumer, calling
+  `AppStore.Class.use()`, 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.
@@ -667,13 +949,13 @@ reactive primitives as plain values** and materialize per observation:
 class $Sheet {
   // Plain readonly fields — the COLLECTIONS aren't reactive;
   // their VALUES are.
-  private readonly cellVersions = new Map<number, Ref<number>>();
+  protected readonly cellVersions = new Map<number, Ref<number>>();
 
   /**
    * READ path: get-OR-CREATE, then subscribe — observation
    * materializes.
    */
-  private trackCell(cellKey: number): void {
+  protected trackCell(cellKey: number): void {
     let versionRef = this.cellVersions.get(cellKey);
     if (!versionRef) {
       versionRef = ref(0);
@@ -687,7 +969,7 @@ class $Sheet {
    * WRITE path: PEEK-ONLY — unobserved keys allocate nothing,
    * notify no one.
    */
-  private bumpCell(cellKey: number): void {
+  protected bumpCell(cellKey: number): void {
     const versionRef = this.cellVersions.get(cellKey);
     if (versionRef) versionRef.value++;
   }
@@ -854,6 +1136,26 @@ export namespace Settings {
 
 No static members → no wrapper: `$Class = $X`, the standard form unchanged.
 
+**Hot loops read the method through the accessor — hoist it, not the
+class.** The bound method itself is plain-function speed (measured,
+Chromium, 9M calls, fresh page per variant: module function 31.7 ms,
+hoisted bound method 30.0 ms); the ONLY per-call cost is re-reading it
+through the accessor inside the loop (84.6 ms same loop — the
+own-property guard that buys per-receiver binding). Ordinary call
+frequency never notices. In a million-call loop, destructure once,
+INSIDE the function:
+
+```ts
+// one accessor read per method — a late read of the mutable slot,
+// so a swapped-in subclass is still honored
+const { isDataCol, numDataValue } = FlyweightLogic.Class;
+for (let row = 0; row < ROWS_1M; row++) sum += numDataValue(row, col) ?? 0;
+```
+
+Never hoist at module scope (captures today's `Class` forever, blind to
+swaps) and never reach for `$Class` as a "fast path" — the raw class
+skips per-receiver binding, which is the capability seam itself.
+
 ## Reading your own statics — the ladder
 
 `Reactive(X) === X`, so a namespace's `Class` slot IS the base class. A getter
@@ -951,6 +1253,11 @@ like prose — don't ruin it with letter soup:
 - Abbreviate only when the abbreviation IS the domain term (`px`, `id`,
   `fx`, A1-notation like `startRow`/`endCol`).
 - Tests are code — the same rules apply to specs.
+- **A `v-for` alias is a declaration the template makes** — the same
+  rule: `v-for="(cell, columnIndex) in sheet.grid[row]"`, never
+  `(cell, ci) in sheet.grid[r]`. The template is read by the same
+  people as the class; `r`, `c`, `ci` cost them the same re-derivation
+  there.
 
 ```ts
 // ❌ const v = this.cellVersions.get(k);
@@ -978,7 +1285,7 @@ Constants use one form per role:
 
 | Role | Form |
 | --- | --- |
-| Tunable or overridable class constant | `static get SCREAMING_SNAKE_CASE()` |
+| Tunable or overridable class constant — a literal, or a tree composed of other SCREAMING constants (`{ mouse: Selection.Class.AUTOSCROLL_MOUSE }`) | `static get SCREAMING_SNAKE_CASE()` |
 | Protocol or byte constant on a hot path, never overridden | `static readonly SCREAMING_SNAKE_CASE` with a one-line hot-path comment |
 | Contributor or pane identity data | Instance `readonly lowerCamelCase` field |
 | Extensible constructed dependency | Field assigned from a prototype `createX()` factory method |
@@ -1036,7 +1343,7 @@ convention and check it in review.
 - [ ] Every mutable state member is `get x() { return ref(...) }` — no mutable plain fields.
 - [ ] Inside the class, every Ref/Computed read/write uses `.value`; every plain field matches one role in the constants table.
 - [ ] Derived values are PLAIN getters; `computed()` appears only for expensive / render-suppressing / stable-handle cases.
-- [ ] Stores/composables are injected via `private get $store() { return useStore() }`, not field initializers.
+- [ ] Stores/composables are injected via `protected get $store() { return useStore() }`, not field initializers.
 - [ ] The class is exported through the namespace (`$Class` / `Class = Reactive($Class)` / `Instance`); generics cast `Class` and hand-apply `ReactiveInstance` to `Instance<T>`.
 - [ ] The SFC does `new X.Class(...)` once — no `reactive()` wrapper, no unwrap view.
 - [ ] `<script setup>` is wiring only: no component-local Ref/Computed, watcher, lifecycle hook, or free function beside the class instance; extend an existing class-backed component through its class, never through parallel setup behavior.
@@ -1047,9 +1354,14 @@ convention and check it in review.
 - [ ] Watch sources are the FUNCTION form; component-scoped constructors use plain `watch`/`watchEffect`; `this.$watch`/`this.$watchEffect` only for component-outliving instances — each with a dispose path (`$stopEffects()` owner or `onScopeDispose` auto-wire).
 - [ ] Lifecycle hooks / init logic live in the constructor (no `init()` expecting auto-call); template refs guarded with `?.` where read pre-mount.
 - [ ] Every `computed()`/constructor-watch CALLBACK delegates to a method (`computed(() => this.recalculate())`) — no logic inlined in reactive closures; the arrow form, never `computed(this.method)`.
-- [ ] 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.
+- [ ] Identifiers are unfolded to domain words (`row`/`col`/`cell`/`cellValue`/`versionRef`…), loop indices, `v-for` aliases 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`.
+- [ ] Million-call loops over a `Static()` class destructure the bound methods once inside the function (never module-scope, never `$Class`); `Class.method()` stays the form everywhere else.
 - [ ] 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.
+- [ ] A class that calls `this.$watch` / `$watchEffect` / `$stopEffects` merges the engine's helpers beside itself — `interface $X extends ReactiveHelpers {}` — so the body typechecks (never `(this as any)`, never per-member `declare` lines).
+- [ ] The class carries the WHOLE contract as static getters (`propsTypes`, `propsDefaults`, the one-line `props` fusion, `emits`, tuning knobs) and the namespace holds identity and types ONLY, every type derived from `$Class`; no module-level consts or TYPE declarations beside imports/class/namespace (every type a class file declares is a namespace member, read as `X.Name`), no `const`, `let`, or `function` of any kind in the namespace — contract data, tuning knobs, seed data, singletons (`use()`), helpers all live on the class as statics (the gate's `the_namespace_holds_identity_and_types_only` check enforces it), no sibling `XProps.ts`; the SFC reads `X.Class.props` / `X.Class.emits`; a subclass extends the contract with `super` and re-declares the fusion line only when it ADDS props.
+- [ ] Every member that overrides a base member carries `override` (with `noImplicitOverride` enabled).
+- [ ] No `private` members — internal members are `protected` (three-tier visibility: public = consumer surface, protected = hierarchy seam, private = banned).

package/skills/ivue/constitution.test.ts

@@ -0,0 +1,143 @@
+/*
+=== GENERATOR ===
+Subject: ivue-standards-check.ts ivue-generator-standard.ts
+Goal: Prove the gate's constitution is data a subclass inherits and extends — every manifest check travels with its claim, its impossibility, and both proof arms, and a gate that grows a check without them refuses itself.
+// domain-invariant: $CheckStandard — If a check is in the manifest, then its proofs entry carries the claim, the impossibility, and at least one red and one green arm
+// domain-invariant: $CheckStandard — If a red arm's fixture runs through the gate, then its check reports the expected finding
+// domain-invariant: $CheckStandard — If a green arm's fixture runs through the gate, then its check stays silent
+// domain-invariant: $CheckStandard — If a subclass overrides or adds a check getter, then the manifest, the skip-list validation, and the proofs follow the receiving class
+Impossible if true: a check enters the manifest without a red and a green proof arm
+Impossible if true: a file breaking a manifest check passes the gate
+
+=== GENERATOR-DESCRIBED ===
+The $CheckStandard class carries its own proof kit as per-receiver static
+data, so an agent extending someone's gate inherits the proven
+checks and is refused the moment it adds one more without arms —
+the discipline teaches itself to whoever extends it. The driver below
+runs every arm through the same run() the command line uses; hand-written
+tests here carry the meta-claims, and the per-check claims live in the
+proof data where prove() reads them.
+*/
+import { expect, test } from 'vitest';
+import { Static } from '../../lib/Static';
+import * as Gate from './ivue-standards-check';
+import { GeneratorStandard } from './ivue-generator-standard';
+
+// domain-invariant: $CheckStandard — If a check is in the manifest, then its proofs entry carries the claim, the impossibility, and at least one red and one green arm
+test('the shipped constitution is complete for every manifest check', () => {
+  const GateClass = Gate.CheckStandard.Class;
+  expect(GateClass.checks.length).toBe(32);
+  const report = GateClass.prove({ completenessOnly: true });
+  expect(report.problems).toEqual([]);
+  for (const check of GateClass.checks) {
+    // one form everywhere: the check's name IS its getter's name
+    expect((GateClass as unknown as Record<string, Gate.StandardCheck>)[check.name]?.name).toBe(check.name);
+    const proof = GateClass.proofs[check.name];
+    expect(proof, check.name).toBeDefined();
+    expect(proof.claim).toMatch(/^If .+, then .+/);
+    expect(proof.impossibility.length).toBeGreaterThan(0);
+    expect(proof.red.length).toBeGreaterThan(0);
+    expect(proof.green.length).toBeGreaterThan(0);
+  }
+});
+
+// domain-invariant: $CheckStandard — If a red arm's fixture runs through the gate, then its check reports the expected finding
+// domain-invariant: $CheckStandard — If a green arm's fixture runs through the gate, then its check stays silent
+// impossible-if-true: $CheckStandard — a file breaking a manifest check passes the gate
+test('every red arm produces its named finding and every green arm stays silent', () => {
+  const report = Gate.CheckStandard.Class.prove();
+  expect(report.problems).toEqual([]);
+  expect(report.ran.red).toBeGreaterThanOrEqual(30);
+  expect(report.ran.green).toBeGreaterThanOrEqual(30);
+});
+
+test('the generator standard is the extension mechanism eating its own cooking', () => {
+  // ten methodology checks arrive the same way a house check does:
+  // getters + checks + proofs on a subclass — fully proven, opt-in
+  const GeneratorClass = GeneratorStandard.Class;
+  expect(GeneratorClass.checks.length).toBe(42);
+  const report = GeneratorClass.prove({ completenessOnly: true });
+  expect(report.problems).toEqual([]);
+  // the base stays ivue-only: no header check leaks upward
+  // the methodology checks wear their jurisdiction as a prefix
+  expect(Gate.CheckStandard.Class.checks.map((check) => check.name)).not.toContain('invariants_a_test_file_opens_with_its_generator_header');
+  expect(GeneratorClass.checks.map((check) => check.name)).toContain('invariants_a_test_file_opens_with_its_generator_header');
+  expect(GeneratorClass.checks.filter((check) => check.name.startsWith('invariants_')).length).toBe(10);
+});
+
+test('prove isolates one check when asked', () => {
+  const GateClass = Gate.CheckStandard.Class;
+  const report = GateClass.prove({ only: 'a_ref_is_read_and_written_through_value' });
+  expect(report.problems).toEqual([]);
+  expect(report.ran.red).toBe(1);
+  expect(report.ran.green).toBe(1);
+  const unknown = GateClass.prove({ only: 'No such check' });
+  expect(unknown.problems.some((problem) => problem.includes('No such check'))).toBe(true);
+  expect(unknown.ran.red + unknown.ran.green).toBe(0);
+});
+
+test('the CLI refuses to combine --prove with a gate run', async () => {
+  const GateClass = Gate.CheckStandard.Class;
+  expect(await GateClass.main(['--prove', '--source-root', '../../'])).toBe(2);
+  expect(await GateClass.main(['--source-root', 'src', '--prove'])).toBe(2);
+});
+
+// impossible-if-true: $CheckStandard — a check enters the manifest without a red and a green proof arm
+test('an armless check is refused by its own constitution', () => {
+  class $ArmlessGate extends Gate.CheckStandard.$Class {
+    static get a_house_rule_without_arms(): Gate.StandardCheck {
+      return { name: 'a_house_rule_without_arms', enforced: true, run: () => [] };
+    }
+
+    static get checks(): readonly Gate.StandardCheck[] {
+      return [...super.checks, this.a_house_rule_without_arms];
+    }
+  }
+  const ArmlessGate = Static($ArmlessGate);
+  const report = ArmlessGate.prove({ completenessOnly: true });
+  expect(report.problems.some((problem) => problem.includes('a_house_rule_without_arms'))).toBe(true);
+});
+
+// domain-invariant: $CheckStandard — If a subclass overrides or adds a check getter, then the manifest, the skip-list validation, and the proofs follow the receiving class
+test('a house gate extends the manifest and its constitution through the receiver', () => {
+  const houseCheck: Gate.StandardCheck = {
+    name: 'a_source_file_stays_under_nine_hundred_lines',
+    enforced: true,
+    run: (context) =>
+      context.sources
+        .filter((unit) => unit.lines.length > 900)
+        .map((unit) => ({ check: 'a_source_file_stays_under_nine_hundred_lines', file: unit.relativePath, line: 1, message: `${unit.lines.length} lines — split the module` })),
+  };
+  const longFile = `${'// filler\n'.repeat(901)}export type Filler = number;\n`;
+  class $HouseGate extends Gate.CheckStandard.$Class {
+    static get a_source_file_stays_under_nine_hundred_lines(): Gate.StandardCheck {
+      return houseCheck;
+    }
+
+    static get checks(): readonly Gate.StandardCheck[] {
+      return [...super.checks, this.a_source_file_stays_under_nine_hundred_lines];
+    }
+
+    static get proofs(): Readonly<Record<string, Gate.CheckProof>> {
+      return {
+        ...super.proofs,
+        [houseCheck.name]: {
+          check: houseCheck,
+          claim: 'If a source file exceeds nine hundred lines, then the gate names it',
+          impossibility: 'a nine-hundred-line source file passes the gate',
+          red: [{ files: { 'src/Long.ts': longFile }, expectFindings: [/90\d lines — split the module/] }],
+          green: [{ files: { 'src/Short.ts': 'export type Short = number;\n' } }],
+        },
+      };
+    }
+  }
+  const HouseGate = Static($HouseGate);
+  // the manifest follows the receiver…
+  expect(HouseGate.checks.map((check) => check.name)).toContain(houseCheck.name);
+  // …the constitution follows the receiver (39 proven checks, zero problems)…
+  const report = HouseGate.prove();
+  expect(report.problems).toEqual([]);
+  expect(report.ran.red).toBeGreaterThanOrEqual(31);
+  // …and the base class is untouched: no house rule leaks upward
+  expect(Gate.CheckStandard.Class.checks.map((check) => check.name)).not.toContain(houseCheck.name);
+});