ivue 2.1.0 → 2.2.1

package/dist/Reactive.d.ts

@@ -87,7 +87,9 @@ export declare type ReactiveInstance<T> = T & WritableGetters<T> & {
     /** Stop the instance's effect scope and drop cached cells. */
     $stopEffects: () => void;
 };
-export declare type ReactiveClass<C extends new (...args: any) => any> = new (...args: ConstructorParameters<C>) => ReactiveInstance<InstanceType<C>>;
+export declare type ReactiveClass<C extends new (...args: any) => any> = {
+    [Key in keyof C]: C[Key];
+} & (new (...args: ConstructorParameters<C>) => ReactiveInstance<InstanceType<C>>);
 /**
  * Component-authoring type utilities (types only — erased at build time).
  * These complement `propsWithDefaults` for the params/defaults component

package/dist/Static.d.ts

@@ -6,6 +6,29 @@
  * retain as callbacks (routers, watchers, command handlers) while the
  * selected `Class` slot remains replaceable by a kernel/plugin.
  *
+ * Get-only static accessors whose name starts with `$` become
+ * compute-once-per-receiver caches: the getter body runs on first read
+ * through a given class, its result is stored under a symbol OWN property
+ * of that receiver, and later reads return the stored value. The
+ * `Object.hasOwn` guard never walks the prototype chain, so a parent's
+ * cache can never shadow a subclass — each class in a hierarchy derives
+ * through its own overrides on its own first read, in ANY read order.
+ * The `$` prefix IS the API: it promises STABLE IDENTITY per receiver,
+ * nothing more — whether the cached value is then treated as immutable
+ * config or as a mutable memo table is the author's design. A static
+ * getter that must stay live (a knob for subclasses to pinch, a
+ * fresh-per-read value) must not use the prefix.
+ *
+ * Method binding uses the same per-receiver symbol discipline: the bound
+ * function is cached under a symbol own property, never under the method
+ * name — so a parent-first read can never install a parent-bound method
+ * where a subclass's chain lookup would find it.
+ *
+ * `$` semantics are GRANTED BY the transform: a raw class, a raw
+ * subclass, or a class only passed through `Reactive()` keeps native
+ * getter behavior. A class that needs instance reactivity AND static
+ * `$`-caches composes the transforms: `Static(Reactive($Class))`.
+ *
  * This is the namespace pattern's backend adapter: canonical namespace +
  * mutable `Class` slot + late reads, for STATELESS capability classes (a
  * function bag). Never wrap stateful/reactive instance classes with it — use

package/dist/extras.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"}),exports.Static=function(o){const r=class extends o{},c=new Set;for(let e=o;e!==Function.prototype;e=Object.getPrototypeOf(e))for(const t of Reflect.ownKeys(e)){if(c.has(t))continue;c.add(t);const n=Object.getOwnPropertyDescriptor(e,t);if(typeof n.value!="function")continue;const u=n.value;Object.defineProperty(r,t,{configurable:!0,enumerable:n.enumerable,get(){const i=u.bind(this);return Object.defineProperty(this,t,{...n,value:i}),i}})}return r};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=Object.hasOwn;exports.Static=function(c){const r=class extends c{},s=new Set;for(let o=c;o!==Function.prototype;o=Object.getPrototypeOf(o))for(const e of Reflect.ownKeys(o)){if(s.has(e))continue;s.add(e);const t=Object.getOwnPropertyDescriptor(o,e);if(typeof t.value=="function"){const i=t.value,n=typeof e=="string"?Symbol.for(`ivue.staticBound.${e}`):Symbol("ivue.staticBound");Object.defineProperty(r,e,{configurable:!0,enumerable:t.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:i.bind(this)}),this[n]}})}else if(t.get&&!t.set&&typeof e=="string"&&e.startsWith("$")){const i=t.get,n=Symbol.for(`ivue.staticCache.${e}`);Object.defineProperty(r,e,{configurable:!0,enumerable:t.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:i.call(this)}),this[n]}})}}return r};

package/dist/extras.es.js

@@ -1,22 +1,27 @@
-function f(o) {
-  const r = class extends o {
+const a = Object.hasOwn;
+function u(s) {
+  const r = class extends s {
   }, c = /* @__PURE__ */ new Set();
-  for (let e = o; e !== Function.prototype; e = Object.getPrototypeOf(e))
-    for (const t of Reflect.ownKeys(e)) {
-      if (c.has(t))
+  for (let n = s; n !== Function.prototype; n = Object.getPrototypeOf(n))
+    for (const e of Reflect.ownKeys(n)) {
+      if (c.has(e))
         continue;
-      c.add(t);
-      const n = Object.getOwnPropertyDescriptor(e, t);
-      if (typeof n.value != "function")
-        continue;
-      const s = n.value;
-      Object.defineProperty(r, t, { configurable: !0, enumerable: n.enumerable, get() {
-        const i = s.bind(this);
-        return Object.defineProperty(this, t, { ...n, value: i }), i;
-      } });
+      c.add(e);
+      const t = Object.getOwnPropertyDescriptor(n, e);
+      if (typeof t.value == "function") {
+        const i = t.value, o = typeof e == "string" ? Symbol.for(`ivue.staticBound.${e}`) : Symbol("ivue.staticBound");
+        Object.defineProperty(r, e, { configurable: !0, enumerable: t.enumerable, get() {
+          return a(this, o) || Object.defineProperty(this, o, { configurable: !0, value: i.bind(this) }), this[o];
+        } });
+      } else if (t.get && !t.set && typeof e == "string" && e.startsWith("$")) {
+        const i = t.get, o = Symbol.for(`ivue.staticCache.${e}`);
+        Object.defineProperty(r, e, { configurable: !0, enumerable: t.enumerable, get() {
+          return a(this, o) || Object.defineProperty(this, o, { configurable: !0, value: i.call(this) }), this[o];
+        } });
+      }
     }
   return r;
 }
 export {
-  f as Static
+  u as Static
 };

package/lib/Reactive.ts

@@ -434,9 +434,9 @@ export type ReactiveInstance<T> = T &
     $stopEffects: () => void;
   };
 
-export type ReactiveClass<C extends new (...args: any) => any> = new (
-  ...args: ConstructorParameters<C>
-) => ReactiveInstance<InstanceType<C>>;
+export type ReactiveClass<C extends new (...args: any) => any> = {
+  [Key in keyof C]: C[Key];
+} & (new (...args: ConstructorParameters<C>) => ReactiveInstance<InstanceType<C>>);
 
 /**
  * Component-authoring type utilities (types only — erased at build time).

package/lib/Static.ts

@@ -6,6 +6,29 @@
  * retain as callbacks (routers, watchers, command handlers) while the
  * selected `Class` slot remains replaceable by a kernel/plugin.
  *
+ * Get-only static accessors whose name starts with `$` become
+ * compute-once-per-receiver caches: the getter body runs on first read
+ * through a given class, its result is stored under a symbol OWN property
+ * of that receiver, and later reads return the stored value. The
+ * `Object.hasOwn` guard never walks the prototype chain, so a parent's
+ * cache can never shadow a subclass — each class in a hierarchy derives
+ * through its own overrides on its own first read, in ANY read order.
+ * The `$` prefix IS the API: it promises STABLE IDENTITY per receiver,
+ * nothing more — whether the cached value is then treated as immutable
+ * config or as a mutable memo table is the author's design. A static
+ * getter that must stay live (a knob for subclasses to pinch, a
+ * fresh-per-read value) must not use the prefix.
+ *
+ * Method binding uses the same per-receiver symbol discipline: the bound
+ * function is cached under a symbol own property, never under the method
+ * name — so a parent-first read can never install a parent-bound method
+ * where a subclass's chain lookup would find it.
+ *
+ * `$` semantics are GRANTED BY the transform: a raw class, a raw
+ * subclass, or a class only passed through `Reactive()` keeps native
+ * getter behavior. A class that needs instance reactivity AND static
+ * `$`-caches composes the transforms: `Static(Reactive($Class))`.
+ *
  * This is the namespace pattern's backend adapter: canonical namespace +
  * mutable `Class` slot + late reads, for STATELESS capability classes (a
  * function bag). Never wrap stateful/reactive instance classes with it — use
@@ -17,6 +40,8 @@
  */
 export type ClassConstructor = new (...arguments_: any[]) => any;
 
+const hasOwn = Object.hasOwn;
+
 export function Static<Class extends ClassConstructor>(targetClass: Class): Class {
   const SelectedClass = class extends targetClass {};
   const visitedKeys = new Set<PropertyKey>();
@@ -31,18 +56,50 @@ export function Static<Class extends ClassConstructor>(targetClass: Class): Clas
       visitedKeys.add(key);
 
       const descriptor = Object.getOwnPropertyDescriptor(currentClass, key)!;
-      if (typeof descriptor.value !== 'function') continue;
-      const method = descriptor.value;
-
-      Object.defineProperty(SelectedClass, key, {
-        configurable: true,
-        enumerable: descriptor.enumerable,
-        get(this: ClassConstructor) {
-          const boundMethod = method.bind(this);
-          Object.defineProperty(this, key, { ...descriptor, value: boundMethod });
-          return boundMethod;
-        },
-      });
+
+      if (typeof descriptor.value === 'function') {
+        const method = descriptor.value;
+        const bindKey =
+          typeof key === 'string'
+            ? Symbol.for(`ivue.staticBound.${key}`)
+            : Symbol('ivue.staticBound');
+
+        Object.defineProperty(SelectedClass, key, {
+          configurable: true,
+          enumerable: descriptor.enumerable,
+          get(this: any) {
+            if (!hasOwn(this, bindKey)) {
+              Object.defineProperty(this, bindKey, {
+                configurable: true,
+                value: method.bind(this),
+              });
+            }
+            return this[bindKey];
+          },
+        });
+      } else if (
+        descriptor.get &&
+        !descriptor.set &&
+        typeof key === 'string' &&
+        key.startsWith('$')
+      ) {
+        const getter = descriptor.get;
+        const cacheKey = Symbol.for(`ivue.staticCache.${key}`);
+
+        Object.defineProperty(SelectedClass, key, {
+          configurable: true,
+          enumerable: descriptor.enumerable,
+          get(this: any) {
+            if (!hasOwn(this, cacheKey)) {
+              Object.defineProperty(this, cacheKey, {
+                configurable: true,
+                value: getter.call(this),
+              });
+            }
+            return this[cacheKey];
+          },
+        });
+      }
     }
   }
 

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

@@ -1,4 +1,6 @@
+import { ref } from 'vue';
 import { describe, expect, it } from 'vitest';
+import { Reactive } from '../Reactive';
 import { Static } from '../Static';
 
 describe('Static', () => {
@@ -81,6 +83,23 @@ describe('Static', () => {
     expect(Config.resolve('/path')).toBe('https://example.test/path');
   });
 
+  it('binds symbol-keyed static methods with the same discipline', () => {
+    const describeKind = Symbol('describeKind');
+
+    class $Shape {
+      static kind = 'circle';
+      static [describeKind]() {
+        return `kind:${this.kind}`;
+      }
+    }
+
+    const Shape = Static($Shape);
+    const described = (Shape as any)[describeKind];
+
+    expect((Shape as any)[describeKind]).toBe(described); // identity-stable
+    expect(described()).toBe('kind:circle'); // bound through detachment
+  });
+
   it('binds `this` to the wrapped class, so statics compose', () => {
     class $Report {
       static header() {
@@ -97,3 +116,270 @@ describe('Static', () => {
     expect(render()).toBe('HEADER|body');
   });
 });
+
+describe('Static $-cached getters', () => {
+  it('computes a $-getter exactly once per receiver', () => {
+    let computeRuns = 0;
+
+    class $Palette {
+      static get $tokens() {
+        computeRuns++;
+        return { accent: 'cyan' };
+      }
+    }
+
+    const Palette = Static($Palette);
+    const firstRead = Palette.$tokens;
+
+    expect(Palette.$tokens).toBe(firstRead); // same object, cached
+    expect(Palette.$tokens.accent).toBe('cyan');
+    expect(computeRuns).toBe(1);
+  });
+
+  it('is order-correct: parent read first, child override still wins', () => {
+    class $Momentum {
+      static get friction() {
+        return 2; // a live knob — subclasses pinch it
+      }
+      static get $atRest() {
+        return { velocity: 0, threshold: this.friction * 10 };
+      }
+    }
+
+    const Momentum = Static($Momentum);
+    class TunedMomentum extends Momentum {
+      static override get friction() {
+        return 7;
+      }
+    }
+
+    // PARENT reads first — the hand-rolled self-replacement idiom
+    // caches on the parent here and silently shadows the child forever
+    expect(Momentum.$atRest.threshold).toBe(20);
+    expect(TunedMomentum.$atRest.threshold).toBe(70); // child derives itself
+    expect(TunedMomentum.$atRest).not.toBe(Momentum.$atRest);
+  });
+
+  it('is order-correct: child read first, parent unaffected', () => {
+    let computeRuns = 0;
+
+    class $Momentum {
+      static get friction() {
+        return 2;
+      }
+      static get $atRest() {
+        computeRuns++;
+        return { threshold: this.friction * 10 };
+      }
+    }
+
+    const Momentum = Static($Momentum);
+    class TunedMomentum extends Momentum {
+      static override get friction() {
+        return 7;
+      }
+    }
+
+    expect(TunedMomentum.$atRest.threshold).toBe(70); // CHILD reads first
+    expect(Momentum.$atRest.threshold).toBe(20);
+    expect(computeRuns).toBe(2); // once per receiver, never shared
+  });
+
+  it('promises stable identity, not immutability — memo tables mutate freely', () => {
+    class $Wrap {
+      static get $memo() {
+        return new Map<string, number>();
+      }
+      static get $state() {
+        return { frame: 0, quiescent: false };
+      }
+    }
+
+    const Wrap = Static($Wrap);
+
+    // a cached Map used as a per-class memo table — the dominant real pattern
+    Wrap.$memo.set('row', 42);
+    expect(Wrap.$memo.get('row')).toBe(42); // same table, mutation retained
+
+    // a cached plain object used as deliberate mutable state
+    Object.assign(Wrap.$state, { frame: 7, quiescent: true });
+    expect(Wrap.$state.frame).toBe(7);
+    expect(Wrap.$state).toBe(Wrap.$state); // identity stable throughout
+  });
+
+  it('caches primitive results too', () => {
+    let computeRuns = 0;
+
+    class $Layout {
+      static get $gutterWidth() {
+        computeRuns++;
+        return 4;
+      }
+    }
+
+    const Layout = Static($Layout);
+
+    expect(Layout.$gutterWidth).toBe(4);
+    expect(Layout.$gutterWidth).toBe(4);
+    expect(computeRuns).toBe(1);
+  });
+
+  it('leaves non-$ getters live — knobs re-read every time', () => {
+    let reads = 0;
+
+    class $Driver {
+      static get retainedLimit() {
+        reads++;
+        return 96;
+      }
+    }
+
+    const Driver = Static($Driver);
+    Driver.retainedLimit;
+    Driver.retainedLimit;
+
+    expect(reads).toBe(2); // no caching without the $ prefix
+  });
+
+  it('leaves accessor pairs with a setter untouched', () => {
+    class $Tunable {
+      static backing = 1;
+      static get $level() {
+        return this.backing;
+      }
+      static set $level(value: number) {
+        this.backing = value;
+      }
+    }
+
+    const Tunable = Static($Tunable);
+    Tunable.$level = 5;
+
+    expect(Tunable.$level).toBe(5); // still the live pair, not a cache
+    Tunable.$level = 9;
+    expect(Tunable.$level).toBe(9);
+  });
+
+  it('a subclass overriding the $-getter itself wins', () => {
+    class $Theme {
+      static get $accent() {
+        return 'blue';
+      }
+    }
+
+    const Theme = Static($Theme);
+    expect(Theme.$accent).toBe('blue');
+
+    class DarkTheme extends Theme {
+      static override get $accent() {
+        return 'violet';
+      }
+    }
+
+    // the subclass's own getter descriptor shadows the caching wrapper
+    expect(DarkTheme.$accent).toBe('violet');
+    expect(Theme.$accent).toBe('blue');
+  });
+
+  it('method binding is order-correct: parent read first, child dispatch intact', () => {
+    class $Render {
+      static get glyph() {
+        return '-'; // a knob subclasses pinch
+      }
+      static paint() {
+        return this.glyph.repeat(3);
+      }
+    }
+
+    const Render = Static($Render);
+    class DottedRender extends Render {
+      static override get glyph() {
+        return '.';
+      }
+    }
+
+    // PARENT reads first — the named-own-property shape poisoned this order
+    const parentPaint = Render.paint;
+    expect(parentPaint()).toBe('---');
+    expect(DottedRender.paint()).toBe('...'); // child binds itself, chain not shadowed
+    expect(DottedRender.paint).toBe(DottedRender.paint); // still identity-stable
+    expect(Render.paint).toBe(parentPaint);
+  });
+
+  it('method binding is order-correct: child read first, parent unaffected', () => {
+    class $Render {
+      static get glyph() {
+        return '-';
+      }
+      static paint() {
+        return this.glyph.repeat(2);
+      }
+    }
+
+    const Render = Static($Render);
+    class DottedRender extends Render {
+      static override get glyph() {
+        return '.';
+      }
+    }
+
+    expect(DottedRender.paint()).toBe('..');
+    expect(Render.paint()).toBe('--');
+  });
+
+  it('composes with Reactive(): Static(Reactive($Class)) grants both contracts', () => {
+    let derivations = 0;
+
+    class $Channel {
+      get status() {
+        return ref('idle');
+      }
+      announce() {
+        return `channel:${this.status.value}`;
+      }
+      static get $defaults() {
+        derivations++;
+        return { retries: 3 };
+      }
+      static open() {
+        return this.$defaults.retries;
+      }
+    }
+
+    const Channel = Static(Reactive($Channel));
+
+    // instance side: Reactive semantics intact through the Static subclass
+    const channel: any = new Channel();
+    const statusCell = channel.status;
+    expect(statusCell.value).toBe('idle');
+    expect(channel.status).toBe(statusCell); // cached ref cell
+    expect(channel.announce()).toBe('channel:idle');
+
+    // static side: $-cache + bound methods from Static
+    expect(Channel.$defaults).toBe(Channel.$defaults);
+    expect(derivations).toBe(1);
+    const open = Channel.open;
+    expect(open()).toBe(3); // detached, still bound
+  });
+
+  it('walks the raw inheritance chain — ancestor $-getters cache per receiver', () => {
+    class $Base {
+      static get scale() {
+        return 1;
+      }
+      static get $metrics() {
+        return { unit: this.scale * 8 };
+      }
+    }
+    class $Wide extends $Base {
+      static override get scale() {
+        return 3;
+      }
+    }
+
+    const Wide = Static($Wide);
+
+    expect(Wide.$metrics.unit).toBe(24); // derived through the override
+    expect(Wide.$metrics).toBe(Wide.$metrics); // and cached
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
@@ -40,6 +40,7 @@
     "build:docs": "npm run sync:examples && npm --prefix docs_v2 run build",
     "render:og": "node docs_v2/scripts/brand-image-generator.mjs og",
     "render:form-header": "node docs_v2/scripts/brand-image-generator.mjs form-header",
+    "render:banner": "node docs_v2/scripts/brand-image-generator.mjs blog",
     "preview:demo": "npm run build:demo && vite preview demo --host",
     "preview:docs": "npm --prefix docs_v2 run preview",
     "release": "npm run build && npm publish",