ivue 2.5.0 → 2.6.0

package/skills/ivue/SKILL.md

@@ -270,31 +270,50 @@ defineExpose(box as Box.Instance);
 </template>
 ```
 
-## The namespace carries the WHOLE contract (one seam)
-
-A class FILE has exactly three residents: imports, the class, the
-namespace. Everything else the module owns lives INSIDE the namespace,
-in canonical section order:
-
-- **Identity** — `$Class` (raw, for children to extend), `Class`
-  (`Reactive()`, for you to `new`), `Instance` (and `Model` when used).
-- **Values** — the component contract as plain data: `propsTypes`
-  (defineComponent-style, no defaults, wrapped in `definePropTypes({...})`
-  so the `required: true` literal survives `typeof`), `propsDefaults`
-  (plain values, typed by `ExtractPropDefaultTypes<typeof 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), `props =
-  propsWithDefaults(propsDefaults, propsTypes)`, and `emits`
-  (object-declared validators). Module constants live here too — a
-  value the module keeps to itself is a NON-EXPORTED namespace member,
-  private to the file. Nothing lives at module level beside the seam.
-- **Types** — DERIVED from the values, never hand-duplicated:
-  `Props` is `ExtractPropTypes<typeof props>` (a generic component
+## 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 props>, 'modelValue'> &
-  { modelValue: T[] }`); `Emits` is `ExtractEmitTypes<typeof emits>`;
-  `Slots`; `Exposed` is `ShallowUnwrapRef<Instance>`.
+  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:
 
@@ -308,10 +327,63 @@ import {
   type ExtractEmitTypes,
   type ExtractPropDefaultTypes,
 } from 'ivue';
+import { Static } from 'ivue/extras';
 
 class $Box {
-  // Forward references into the namespace below — legal: type positions
-  // resolve non-positionally, and the class never reads a contract VALUE.
+  /* 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,
@@ -333,48 +405,14 @@ class $Box {
 export namespace Box {
   /* Identity */
 
-  export const $Class = $Box; // raw — children `extends` this
+  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
 
-  /* Values */
-
-  // A value the module keeps to itself: NON-EXPORTED — private to the
-  // file, invisible to importers. Never a module-level const.
-  const DEFAULT_SIZE = 400;
-
-  /** 1 — the TYPES: a defineComponent-style object, no defaults inside.
-   *  definePropTypes is an identity call that keeps `required: true` a
-   *  LITERAL — a bare const widens it to boolean, which would blind the
-   *  defaults check below. */
-  export const propsTypes = 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. */
-  export const propsDefaults: ExtractPropDefaultTypes<typeof propsTypes> = {
-    size: DEFAULT_SIZE,
-    maxHeight: undefined, // unset = unbounded — deliberately default-free
-    disabled: false,
-  };
-
-  /** 3 — the MERGE: a standard Vue props object, ready for defineProps. */
-  export const props = propsWithDefaults(propsDefaults, propsTypes);
+  /* Types — DERIVED from the class's statics, never hand-duplicated */
 
-  export const emits = {
-    close: (title: string) => true,
-  };
-
-  /* Types — DERIVED from the values, never hand-duplicated */
-
-  export type Props = ExtractPropTypes<typeof props>;
-  export type Emits = ExtractEmitTypes<typeof emits>;
+  export type Props = ExtractPropTypes<typeof $Class.props>;
+  export type Emits = ExtractEmitTypes<typeof $Class.emits>;
 
   export interface Slots {
     default: (scope: { title: string }) => any;
@@ -385,37 +423,63 @@ export namespace Box {
 }
 ```
 
-The SFC is pure wiring against the seam. The macros receive the
-RUNTIME objects, so no compiler macro ever resolves a cross-file type:
+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.props); // non-generic: the type is inferred
-const emit = defineEmits(Box.emits) as Box.Emits;
+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.props) as unknown as X.Props<T>
+// defineProps(X.Class.props) as unknown as X.Props<T>
 ```
 
-A subclass composes its surface the way it composes behavior — by
-SPREADING the parent's maps and overriding only what defines the
-specialization, with the reason on the line:
+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
-export const propsTypes = { ...Box.propsTypes };
-export const propsDefaults = {
-  ...Box.propsDefaults,
-  assumedSize: 300, // cards are hundreds of px wide; rows were tens tall
-};
-export const props = propsWithDefaults(propsDefaults, propsTypes);
+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
+  }
+}
 ```
 
-**Two tiers, one seam.** A small contract (roughly under fifteen props)
-is authored inline in the namespace. A LARGE surface earns a sibling
-`XProps.ts`: authored there, imported ONLY by its own class file and by
-extending contract files, and re-exported through the namespace 1:1 —
-the re-export block is the seam's table of contents. Consumers never
-import `XProps.ts`; the namespace stays the whole truth either way.
-File placement is expression; the one-seam rule is the invariant.
+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
@@ -460,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
@@ -527,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:
 
@@ -553,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);
@@ -615,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();
 ```
@@ -636,6 +722,7 @@ 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 |
@@ -755,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);
   }
@@ -767,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());
-  }
 }
 ```
 
@@ -784,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() {
@@ -802,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>
 
@@ -815,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.
@@ -1029,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
@@ -1126,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);
@@ -1153,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 |
@@ -1222,12 +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.
-- [ ] The namespace is the ONE seam: no module-level consts beside imports/class/namespace (file-private values are non-exported namespace members); the contract is namespace data in Identity → Values → Types order, its types derived from its values; a large contract's sibling `XProps.ts` is imported only by its class file and extending contract files.
+- [ ] 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

@@ -26,7 +26,7 @@ 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(30);
+  expect(GateClass.checks.length).toBe(32);
   const report = GateClass.prove({ completenessOnly: true });
   expect(report.problems).toEqual([]);
   for (const check of GateClass.checks) {
@@ -55,7 +55,7 @@ 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(40);
+  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

package/skills/ivue/ivue-docs-skip.json

@@ -0,0 +1,37 @@
+[
+  {
+    "path": "examples/playground/src/examples/benchmarks/creationBench.ts",
+    "check": "a_public_class_publishes_its_namespace_manifest",
+    "reason": "benchmark arms: PlainBox and reactive(new PlainBox()) ARE the measured competitors; changing their shape changes the numbers the docs quote"
+  },
+  {
+    "path": "examples/playground/src/examples/benchmarks/creationBench.ts",
+    "check": "construction_goes_through_the_namespace_class_slot",
+    "reason": "benchmark arms: PlainBox and reactive(new PlainBox()) ARE the measured competitors; changing their shape changes the numbers the docs quote"
+  },
+  {
+    "path": "examples/playground/src/ivue.ts",
+    "check": "declarations_use_full_descriptive_names",
+    "reason": "vendored copy of the engine (lib/Reactive.ts, synced by sync:examples) \u2014 the engine keeps its own conventions"
+  },
+  {
+    "path": "examples/playground/src/lenis/Emitter.ts",
+    "check": "declarations_use_full_descriptive_names",
+    "reason": "vendored third-party (the Lenis smooth-scroll library, ported as-is) \u2014 not teaching code"
+  },
+  {
+    "path": "examples/playground/src/lenis/Lenis.ts",
+    "check": "declarations_use_full_descriptive_names",
+    "reason": "vendored third-party (the Lenis smooth-scroll library, ported as-is) \u2014 not teaching code"
+  },
+  {
+    "path": "examples/playground/src/lenis/LenisUtils.ts",
+    "check": "declarations_use_full_descriptive_names",
+    "reason": "vendored third-party (the Lenis smooth-scroll library, ported as-is) \u2014 not teaching code"
+  },
+  {
+    "path": "docs_v2/.vitepress/theme/components/grid/GridBenchmark.vue",
+    "check": "one_handler_per_event",
+    "reason": "benchmark arms: the composable and the ivue grid ARE the measured competitors, bound identically on purpose; giving either its own per-event methods changes the shape the numbers compare"
+  }
+]