ivue 2.3.0 → 2.5.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,180 @@ 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
+  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>`.
+
+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';
+
+class $Box {
+  // Forward references into the namespace below — legal: type positions
+  // resolve non-positionally, and the class never reads a contract VALUE.
+  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 = $Box; // raw — 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);
+
+  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 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. The macros receive the
+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;
+defineSlots<Box.Slots>();
+// generic components cast the one graft:
+// defineProps(X.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:
+
+```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);
+```
+
+**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.
+
+**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.
@@ -387,14 +561,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
@@ -436,7 +628,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 |
@@ -446,6 +638,7 @@ session.dispose();
 | ✅ 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` |
+| ✅ `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
@@ -490,7 +683,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
@@ -645,13 +842,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);
@@ -665,7 +862,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++;
   }
@@ -1014,7 +1211,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.
@@ -1031,3 +1228,6 @@ convention and check it in review.
 - [ ] 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.
+- [ ] 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(30);
+  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(40);
+  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);
+});