ivue 2.4.0 → 2.6.0

package/README.md

@@ -189,7 +189,7 @@ export namespace TextSegmentation {
 [**Invar**](https://ivue.dev/examples/invar) is ivue at full scale: a
 complete terminal IDE — editor, workspace search, git, terminals, LSP,
 agents — running on ivue classes under Bun, with no DOM and no Vue
-components. **94,000 source lines, 345 classes, 35 invariant contracts,
+components. **108,000 source lines, 384 classes, 39 invariant contracts,
 zero import cycles**, built almost entirely by AI agents holding the
 [Standard](https://ivue.dev/guide/standard) as their base discipline.
 

package/bin/ivue.mjs

@@ -10,6 +10,7 @@
  * the installed package, so the manual always matches the engine version
  * the project actually runs.
  */
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -27,7 +28,11 @@ if (command !== 'skill') {
 
   npx ivue skill [targets] [--force]
 
-  Installs the ivue operating manual for coding agents. Targets:
+  Installs the ivue operating manual for coding agents, and (for the
+  Claude target) the house gate seed — your own extendable Standard
+  gate at .claude/skills/ivue/ivue-house-gate.ts. A house gate you have
+  customized is never overwritten; upgrade it with your AI agent using
+  the ivue skill, or --force. Targets:
     (none) / --claude   .claude/skills/ivue/SKILL.md
     --cursor            .cursor/rules/ivue.mdc
     --copilot           .github/instructions/ivue.instructions.md
@@ -58,6 +63,50 @@ const skillDescription =
   /description:\s*([^\n]+)/.exec(skillText)?.[1] ??
   'The ivue operating manual.';
 
+/**
+ * A SEED is a file the user is meant to edit (the house gate). The install
+ * stamps it with a hash of its own content; on upgrade, a matching stamp
+ * means "untouched since install" (safe to replace), anything else means
+ * the user customized it — leave it alone and point at AI reconciliation.
+ */
+const SEED_STAMP = /^\/\/ ivue-seed: ([0-9a-f]{64})\n/;
+
+function stampSeed(content) {
+  const hash = createHash('sha256').update(content).digest('hex');
+  return `// ivue-seed: ${hash}\n${content}`;
+}
+
+function seedUntouched(existing) {
+  const stamp = SEED_STAMP.exec(existing);
+  if (!stamp) return false;
+  const body = existing.slice(stamp[0].length);
+  return createHash('sha256').update(body).digest('hex') === stamp[1];
+}
+
+function installSeed(relativePath, content, label) {
+  const targetPath = join(process.cwd(), relativePath);
+  const stamped = stampSeed(content);
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf8');
+    if (existing === stamped) {
+      console.log(`ivue: ${label} already up to date (ivue v${version}).`);
+      return;
+    }
+    if (!seedUntouched(existing) && !force) {
+      console.log(
+        `ivue: ${label} at ${relativePath} was customized — keeping yours.\n` +
+          '      To upgrade it, ask your AI agent (with the ivue skill installed) to\n' +
+          "      reconcile your gate with the new Standard's — it knows both sides.\n" +
+          '      Or re-run with --force to overwrite your customizations.',
+      );
+      return;
+    }
+  }
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, stamped);
+  console.log(`ivue: ${label} installed at ${relativePath} (ivue v${version}).`);
+}
+
 /** Write one target idempotently; refuse to clobber local edits sans --force. */
 function install(relativePath, content, label) {
   const targetPath = join(process.cwd(), relativePath);
@@ -104,6 +153,18 @@ const wantClaude =
 
 if (wantClaude) {
   install('.claude/skills/ivue/SKILL.md', skillText, 'Claude skill');
+  // the house gate seed — the user's own gate, never clobbered once edited
+  const housePath = [
+    join(packageRoot, 'skills', 'ivue', 'ivue-house-gate.ts'),
+    join(packageRoot, '.claude', 'skills', 'ivue', 'ivue-house-gate.ts'),
+  ].find(existsSync);
+  if (housePath) {
+    const houseSeed = readFileSync(housePath, 'utf8')
+      .replace("from '../../lib/Static'", "from 'ivue/extras'")
+      .replace("from './ivue-standards-check'", "from 'ivue/skills/ivue/ivue-standards-check'")
+      .replace("from './ivue-generator-standard'", "from 'ivue/skills/ivue/ivue-generator-standard'");
+    installSeed('.claude/skills/ivue/ivue-house-gate.ts', houseSeed, 'house gate');
+  }
 }
 if (wantAll && !wantCursor) skipped('Cursor rule', '.cursor/', '--cursor');
 if (wantAll && !wantCopilot) skipped('Copilot instructions', '.github/', '--copilot');

package/dist/LazyShared.d.ts

@@ -35,11 +35,11 @@
  * entry stays minimal.
  */
 export declare class LazyShared<T> {
-    private readonly make;
+    protected readonly make: () => T;
     constructor(make: () => T);
-    private constructed;
-    private constructing;
-    private stored;
+    protected constructed: boolean;
+    protected constructing: boolean;
+    protected stored: T | null;
     get value(): T;
     /**
      * Drop the constructed value; the next read constructs again. For

package/dist/Reactive.d.ts

@@ -1,4 +1,5 @@
 import { watch, watchEffect, type ExtractPropTypes, type Ref } from 'vue';
+export { clone } from './clone';
 /**
  * Create a reactive class.
  * @param targetClass The class to make reactive.
@@ -54,14 +55,14 @@ export declare function isClass(val: any): boolean;
  * but leave primitive properties and functions intact so that
  * the final object is fully defineComponent() style compatible.
  *
- * The default cloner is the native `structuredClone` (zero-dependency, handles
- * plain data, Map/Set/Date/typed arrays, circular refs). For defaults that
- * contain class instances or functions — which `structuredClone` cannot clone —
- * pass a `customCloner` such as lodash `cloneDeep`.
+ * The default cloner copies acyclic plain-object and array trees while
+ * retaining callbacks, class constructors and opaque objects by reference.
+ * For independent Map/Set/Date values or cyclic data, pass a `customCloner`
+ * such as `structuredClone` when the values support it.
  *
  * @param defaults Regular object of default key -> values
  * @param typedProps Props declared in defineComponent() style with type and possibly required declared, but without default
- * @param customCloner Optional cloner used for object/array defaults (defaults to structuredClone)
+ * @param customCloner Optional cloner used for object/array defaults (defaults to clone)
  * @returns Props declared in defineComponent() style with all properties having default property declared.
  */
 export declare function propsWithDefaults<T extends VuePropsObject>(defaults: Record<string, any>, typedProps: T, customCloner?: (val: any) => any): VuePropsWithDefaults<T>;
@@ -79,7 +80,16 @@ declare type IsWritableGetter<R> = R extends Ref<any> ? true : R extends Writabl
 declare type WritableGetters<T> = {
     [K in GetterKeys<T> as IsWritableGetter<GetterReturn<T, K>> extends true ? K : never]-?: T[K];
 };
-export declare type ReactiveInstance<T> = T & WritableGetters<T> & {
+/**
+ * The members `Reactive()` installs on every instance's prototype. A raw
+ * class body cannot see them (the transform runs after the class is typed),
+ * so a class that calls them merges this interface into its own instance
+ * type — one declaration beside the class, zero runtime:
+ *
+ *   class $Session { constructor() { this.$watch(…) } }
+ *   interface $Session extends ReactiveHelpers {}
+ */
+export interface ReactiveHelpers {
     /** Register a watcher in the instance's lazy effect scope (same signature as Vue `watch`). */
     $watch: typeof watch;
     /** Register a watchEffect in the instance's lazy effect scope (same signature as Vue `watchEffect`). */
@@ -90,7 +100,8 @@ export declare type ReactiveInstance<T> = T & WritableGetters<T> & {
     $stopEffects: (options?: {
         reset?: boolean;
     }) => void;
-};
+}
+export declare type ReactiveInstance<T> = T & WritableGetters<T> & ReactiveHelpers;
 export declare type ReactiveClass<C extends new (...args: any) => any> = {
     [Key in keyof C]: C[Key];
 } & (new (...args: ConstructorParameters<C>) => ReactiveInstance<InstanceType<C>>);
@@ -118,11 +129,28 @@ export declare type ExtractEmitTypes<T extends Record<string, any>> = UnionToInt
 }>>;
 /**
  * Extract properties as all-assigned (non-optional) because every one of
- * them carries a default.
+ * them carries a default — the honesty check: a declared type without a
+ * default is a compile error. Props declared `required: true` are FILTERED
+ * OUT automatically (a required prop can never carry a default —
+ * propsWithDefaults skips them at runtime), so no manual `Omit` is needed;
+ * a deliberately default-free OPTIONAL prop is declared `key: undefined`,
+ * stating the ruling in the defaults object itself. The `required: true`
+ * literal survives `typeof` only through generic inference — declare the
+ * types map with `definePropTypes({...})`, never as a bare object const.
  */
 export declare type ExtractPropDefaultTypes<O> = {
-    [K in keyof O]: K extends keyof ExtractPropTypes<O> ? ExtractPropTypes<O>[K] : never;
+    [K in keyof O as O[K] extends {
+        required: true;
+    } ? never : K]: K extends keyof ExtractPropTypes<O> ? ExtractPropTypes<O>[K] : never;
 };
+/**
+ * Identity helper for a prop-TYPES map. Exists for one reason: in a bare
+ * `const propsTypes = {...}`, TypeScript widens `required: true` to
+ * `boolean`, which blinds ExtractPropDefaultTypes' required-key filter —
+ * generic inference through this call preserves the literal. Costs
+ * nothing at runtime.
+ */
+export declare function definePropTypes<T extends VuePropsObject>(types: T): T;
 /**
  * Extend a slots interface T with prefixed 'before--' & 'after--' slots to
  * create fully extensible wrapped components.
@@ -134,4 +162,3 @@ export declare type FnParameter<F extends AnyFn, K extends number> = Parameters<
 export declare type IFnParameters<T extends Record<any, any>, K extends string> = Parameters<Required<Pick<T, K>>[K]>;
 /** Get interface T property P's function parameter by index K. */
 export declare type IFnParameter<T extends Record<any, any>, P extends keyof T, K extends number> = FnParameter<NonNullable<T[P]> extends AnyFn ? NonNullable<T[P]> : never, K>;
-export {};

package/dist/clone.d.ts

@@ -0,0 +1,3 @@
+/** Copy plain configuration containers; retain callbacks, constructors and
+ *  opaque objects by reference. Container trees must be acyclic. */
+export declare function clone<T>(value: T): T;

package/dist/extras.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=Object.hasOwn;exports.LazyShared=class{constructor(s){this.make=s,this.constructed=!1,this.constructing=!1,this.stored=null}get value(){if(!this.constructed){if(this.constructing)throw new Error("LazyShared thunk cycle: this cell is read inside its own construction. Break the dependency between the two thunks.");this.constructing=!0;try{this.stored=this.make(),this.constructed=!0}finally{this.constructing=!1}}return this.stored}reset(){this.constructed=!1,this.stored=null}},exports.Static=function(s){const i=class extends s{},c=new Set;for(let r=s;r!==Function.prototype;r=Object.getPrototypeOf(r))for(const t of Reflect.ownKeys(r)){if(c.has(t))continue;c.add(t);const e=Object.getOwnPropertyDescriptor(r,t);if(typeof e.value=="function"){const o=e.value,n=typeof t=="string"?Symbol.for(`ivue.staticBound.${t}`):Symbol("ivue.staticBound");Object.defineProperty(i,t,{configurable:!0,enumerable:e.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:o.bind(this)}),this[n]}})}else if(e.get&&!e.set&&typeof t=="string"&&t.startsWith("$")){const o=e.get,n=Symbol.for(`ivue.staticCache.${t}`);Object.defineProperty(i,t,{configurable:!0,enumerable:e.enumerable,get(){return u(this,n)||Object.defineProperty(this,n,{configurable:!0,value:o.call(this)}),this[n]}})}}return i};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=Object.hasOwn,e=new Set;function o(t){if(Array.isArray(t)){const e=new Array(t.length);for(let n=0;n<t.length;n++)n in t&&(e[n]=o(t[n]));return e}if(null===t||"object"!=typeof t||t.constructor!==Object&&void 0!==t.constructor)return t;const e={__proto__:Object.getPrototypeOf(t),...t};for(const t in e)e[t]=o(e[t]);return e}function n(t){return null!==t&&"object"==typeof t&&(t.constructor===Object||void 0===t.constructor)}function r(t,e,o){for(const s in e){const c=t[s],i=e[s];void 0===c?t[s]=o(i):n(c)&&n(i)&&r(c,i,o)}}exports.LazyShared=class{constructor(t){this.make=t,this.constructed=!1,this.constructing=!1,this.stored=null}get value(){if(!this.constructed){if(this.constructing)throw new Error("LazyShared thunk cycle: this cell is read inside its own construction. Break the dependency between the two thunks.");this.constructing=!0;try{this.stored=this.make(),this.constructed=!0}finally{this.constructing=!1}}return this.stored}reset(){this.constructed=!1,this.stored=null}},exports.Static=function(o){var n;const r=class extends o{},s=new Set;for(let c=o;c!==Function.prototype;c=Object.getPrototypeOf(c))for(const o of Reflect.ownKeys(c)){if(s.has(o)||(s.add(o),"symbol"==typeof o&&null!=(n=Symbol.keyFor(o))&&n.startsWith("ivue.static"))||e.has(o))continue;const i=Object.getOwnPropertyDescriptor(c,o);if("function"==typeof i.value){const n=i.value,s="string"==typeof o?Symbol.for(`ivue.staticBound.${o}`):Symbol("ivue.staticBound");e.add(s),Object.defineProperty(r,o,{configurable:!0,enumerable:i.enumerable,get(){return t(this,s)||Object.defineProperty(this,s,{configurable:!0,value:n.bind(this)}),this[s]}})}else if(i.get&&!i.set&&"string"==typeof o&&o.startsWith("$")){const n=i.get,s=Symbol.for(`ivue.staticCache.${o}`);e.add(s),Object.defineProperty(r,o,{configurable:!0,enumerable:i.enumerable,get(){return t(this,s)||Object.defineProperty(this,s,{configurable:!0,value:n.call(this)}),this[s]}})}}return r},exports.nestedProps=function(t,e,s=o){for(const o in e){const c=t[o],i=e[o];n(c)&&n(i)&&r(c,i,s)}return t};

package/dist/extras.d.ts

@@ -8,3 +8,4 @@
  */
 export { Static, type ClassConstructor } from './Static';
 export { LazyShared } from './LazyShared';
+export { nestedProps, type NestedPartial, type NestedProps } from './nestedProps';

package/dist/extras.es.js

@@ -1,49 +1 @@
-const u = Object.hasOwn;
-function a(i) {
-  const n = class extends i {
-  }, c = /* @__PURE__ */ new Set();
-  for (let r = i; r !== Function.prototype; r = Object.getPrototypeOf(r))
-    for (const t of Reflect.ownKeys(r)) {
-      if (c.has(t))
-        continue;
-      c.add(t);
-      const e = Object.getOwnPropertyDescriptor(r, t);
-      if (typeof e.value == "function") {
-        const o = e.value, s = typeof t == "string" ? Symbol.for(`ivue.staticBound.${t}`) : Symbol("ivue.staticBound");
-        Object.defineProperty(n, t, { configurable: !0, enumerable: e.enumerable, get() {
-          return u(this, s) || Object.defineProperty(this, s, { configurable: !0, value: o.bind(this) }), this[s];
-        } });
-      } else if (e.get && !e.set && typeof t == "string" && t.startsWith("$")) {
-        const o = e.get, s = Symbol.for(`ivue.staticCache.${t}`);
-        Object.defineProperty(n, t, { configurable: !0, enumerable: e.enumerable, get() {
-          return u(this, s) || Object.defineProperty(this, s, { configurable: !0, value: o.call(this) }), this[s];
-        } });
-      }
-    }
-  return n;
-}
-class h {
-  constructor(n) {
-    this.make = n, this.constructed = !1, this.constructing = !1, this.stored = null;
-  }
-  get value() {
-    if (!this.constructed) {
-      if (this.constructing)
-        throw new Error("LazyShared thunk cycle: this cell is read inside its own construction. Break the dependency between the two thunks.");
-      this.constructing = !0;
-      try {
-        this.stored = this.make(), this.constructed = !0;
-      } finally {
-        this.constructing = !1;
-      }
-    }
-    return this.stored;
-  }
-  reset() {
-    this.constructed = !1, this.stored = null;
-  }
-}
-export {
-  h as LazyShared,
-  a as Static
-};
+const t=Object.hasOwn,e=/* @__PURE__ */new Set;function n(n){var o;const r=class extends n{},s=/* @__PURE__ */new Set;for(let c=n;c!==Function.prototype;c=Object.getPrototypeOf(c))for(const n of Reflect.ownKeys(c)){if(s.has(n)||(s.add(n),"symbol"==typeof n&&null!=(o=Symbol.keyFor(n))&&o.startsWith("ivue.static"))||e.has(n))continue;const i=Object.getOwnPropertyDescriptor(c,n);if("function"==typeof i.value){const o=i.value,s="string"==typeof n?Symbol.for(`ivue.staticBound.${n}`):Symbol("ivue.staticBound");e.add(s),Object.defineProperty(r,n,{configurable:!0,enumerable:i.enumerable,get(){return t(this,s)||Object.defineProperty(this,s,{configurable:!0,value:o.bind(this)}),this[s]}})}else if(i.get&&!i.set&&"string"==typeof n&&n.startsWith("$")){const o=i.get,s=Symbol.for(`ivue.staticCache.${n}`);e.add(s),Object.defineProperty(r,n,{configurable:!0,enumerable:i.enumerable,get(){return t(this,s)||Object.defineProperty(this,s,{configurable:!0,value:o.call(this)}),this[s]}})}}return r}class o{constructor(t){this.make=t,this.constructed=!1,this.constructing=!1,this.stored=null}get value(){if(!this.constructed){if(this.constructing)throw new Error("LazyShared thunk cycle: this cell is read inside its own construction. Break the dependency between the two thunks.");this.constructing=!0;try{this.stored=this.make(),this.constructed=!0}finally{this.constructing=!1}}return this.stored}reset(){this.constructed=!1,this.stored=null}}function r(t){if(Array.isArray(t)){const e=new Array(t.length);for(let n=0;n<t.length;n++)n in t&&(e[n]=r(t[n]));return e}if(null===t||"object"!=typeof t||t.constructor!==Object&&void 0!==t.constructor)return t;const e={__proto__:Object.getPrototypeOf(t),...t};for(const t in e)e[t]=r(e[t]);return e}function s(t){return null!==t&&"object"==typeof t&&(t.constructor===Object||void 0===t.constructor)}function c(t,e,n){for(const o in e){const r=t[o],i=e[o];void 0===r?t[o]=n(i):s(r)&&s(i)&&c(r,i,n)}}function i(t,e,n=r){for(const o in e){const r=t[o],i=e[o];s(r)&&s(i)&&c(r,i,n)}return t}export{o as LazyShared,n as Static,i as nestedProps};

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("vue"),g=Object.hasOwn,y=Object.getPrototypeOf,w=Object.getOwnPropertyDescriptor,m=Object.getOwnPropertyNames,a=Object.defineProperty,d=Object.prototype,b=Symbol.for("ivue.raw"),p=Symbol.for("ivue.scope"),h=Symbol.for("ivue.processed");function i(e){const c=l.toRaw(e);if(c!==e)return c[b]??(c[b]=c);const r=e[b];return r?r===e?r:l.toRaw(r):e[b]=e}function O(e,c,r,o){a(e,c,{configurable:!0,enumerable:!1,get(){const t=i(this);return t[r]??(t[r]=o.bind(t))},set(t){i(this)[r]=t}})}function S(e,c,r,o,t){const n=c[0]==="$";a(e,c,{configurable:!0,enumerable:!1,get:function(){const u=i(this);if(r in u)return u[r];const f=o.call(u);return n?(u[r]=f,f):(l.isRef(f)?u[r]=f:a(e,c,{configurable:!0,enumerable:!1,get(){return o.call(i(this))},set:t?function(s){return t.call(i(this),s)}:void 0}),f)},set:t?function(u){return t.call(i(this),u)}:void 0})}function v(e){var c;return typeof e=="function"&&!!e.prototype&&!((c=w(e,"prototype"))!=null&&c.writable)}exports.Reactive=function(e){const c=[];let r=e.prototype;for(;r&&r!==d;)c.push(r),r=y(r);c.reverse();for(const o of c){if(g(o,h))continue;const t=m(o),n=[];for(const u of t){if(u==="constructor")continue;const f=w(o,u);if(typeof f.value=="function"){const s=Symbol(u);n.push(s),O(o,u,s,f.value)}else if(f.get){const s=Symbol(u);n.push(s),S(o,u,s,f.get,f.set)}}a(o,h,{value:n})}return g(e.prototype,"$stopEffects")||(a(e.prototype,"$watch",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const t=i(this);return(t[p]??(t[p]=l.effectScope(!0))).run(()=>l.watch(...o))}}),a(e.prototype,"$watchEffect",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const t=i(this);return(t[p]??(t[p]=l.effectScope(!0))).run(()=>l.watchEffect(...o))}}),a(e.prototype,"$stopEffects",{enumerable:!1,configurable:!0,writable:!0,value:function(o){const t=i(this);try{const n=t[p];n&&n.stop()}finally{if(delete t[p],(o==null?void 0:o.reset)!==!1){let n=y(t);for(;n&&n!==d;){const u=n[h];if(u)for(const f of u)delete t[f];n=y(n)}}}}})),e},exports.isClass=v,exports.propsWithDefaults=function(e,c,r){const o={};for(const t in c){const n=e==null?void 0:e[t],u=c[t];o[t]={...u},u.required||n===void 0||(typeof n=="object"&&n!==null?o[t].default=()=>r?r(n):structuredClone(n):v(n)?o[t].default=()=>n:o[t].default=n)}return o};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("vue");function e(t){if(Array.isArray(t)){const o=new Array(t.length);for(let n=0;n<t.length;n++)n in t&&(o[n]=e(t[n]));return o}if(null===t||"object"!=typeof t||t.constructor!==Object&&void 0!==t.constructor)return t;const o={__proto__:Object.getPrototypeOf(t),...t};for(const t in o)o[t]=e(o[t]);return o}const o=Object.hasOwn,n=Object.getPrototypeOf,r=Object.getOwnPropertyDescriptor,c=Object.getOwnPropertyNames,u=Object.defineProperty,s=Object.prototype,i=Symbol.for("ivue.raw"),f=Symbol.for("ivue.scope"),l=Symbol.for("ivue.processed");function a(e){const o=t.toRaw(e);if(o!==e)return o[i]??(o[i]=o);const n=e[i];return n?n===e?n:t.toRaw(n):e[i]=e}function p(t,e,o,n){u(t,e,{configurable:!0,enumerable:!1,get(){const t=a(this);return t[o]??(t[o]=n.bind(t))},set(t){a(this)[o]=t}})}function b(e,o,n,r,c){const s="$"===o[0];u(e,o,{configurable:!0,enumerable:!1,get:function(){const i=a(this);if(n in i)return i[n];const f=r.call(i);return s?(i[n]=f,f):(t.isRef(f)?i[n]=f:u(e,o,{configurable:!0,enumerable:!1,get(){return r.call(a(this))},set:c?function(t){return c.call(a(this),t)}:void 0}),f)},set:c?function(t){return c.call(a(this),t)}:void 0})}function y(t){var e;return!("function"!=typeof t||!t.prototype||null!=(e=r(t,"prototype"))&&e.writable)}exports.Reactive=function(e){const i=[];let y=e.prototype;for(;y&&y!==s;)i.push(y),y=n(y);i.reverse();for(const t of i){if(o(t,l))continue;const e=c(t),n=[];for(const o of e){if("constructor"===o)continue;const e=r(t,o);if("function"==typeof e.value){const r=Symbol(o);n.push(r),p(t,o,r,e.value)}else if(e.get){const r=Symbol(o);n.push(r),b(t,o,r,e.get,e.set)}}u(t,l,{value:n})}return o(e.prototype,"$stopEffects")||(u(e.prototype,"$watch",{enumerable:!1,configurable:!0,writable:!0,value:function(...e){const o=a(this);return(o[f]??(o[f]=t.effectScope(!0))).run((()=>t.watch(...e)))}}),u(e.prototype,"$watchEffect",{enumerable:!1,configurable:!0,writable:!0,value:function(...e){const o=a(this);return(o[f]??(o[f]=t.effectScope(!0))).run((()=>t.watchEffect(...e)))}}),u(e.prototype,"$stopEffects",{enumerable:!1,configurable:!0,writable:!0,value:function(t){const e=a(this);try{const t=e[f];t&&t.stop()}finally{if(delete e[f],!1!==(null==t?void 0:t.reset)){let t=n(e);for(;t&&t!==s;){const o=t[l];if(o)for(const t of o)delete e[t];t=n(t)}}}}})),e},exports.clone=e,exports.definePropTypes=function(t){return t},exports.isClass=y,exports.propsWithDefaults=function(t,o,n){const r={};for(const c in o){const u=null==t?void 0:t[c],s=o[c];r[c]={...s},!s.required&&void 0!==u&&("object"==typeof u&&null!==u?r[c].default=()=>n?n(u):e(u):y(u)?r[c].default=()=>u:r[c].default=u)}return r};

package/dist/index.es.js

@@ -1,99 +1 @@
-import { effectScope as h, watch as w, watchEffect as O, toRaw as g, isRef as j } from "vue";
-const m = Object.hasOwn, b = Object.getPrototypeOf, d = Object.getOwnPropertyDescriptor, S = Object.getOwnPropertyNames, a = Object.defineProperty, v = Object.prototype, p = Symbol.for("ivue.raw"), l = Symbol.for("ivue.scope"), y = Symbol.for("ivue.processed");
-function f(e) {
-  const c = g(e);
-  if (c !== e)
-    return c[p] ?? (c[p] = c);
-  const r = e[p];
-  return r ? r === e ? r : g(r) : e[p] = e;
-}
-function $(e, c, r, o) {
-  a(e, c, { configurable: !0, enumerable: !1, get() {
-    const t = f(this);
-    return t[r] ?? (t[r] = o.bind(t));
-  }, set(t) {
-    f(this)[r] = t;
-  } });
-}
-function E(e, c, r, o, t) {
-  const n = c[0] === "$";
-  a(e, c, { configurable: !0, enumerable: !1, get: function() {
-    const s = f(this);
-    if (r in s)
-      return s[r];
-    const u = o.call(s);
-    return n ? (s[r] = u, u) : (j(u) ? s[r] = u : a(e, c, { configurable: !0, enumerable: !1, get() {
-      return o.call(f(this));
-    }, set: t ? function(i) {
-      return t.call(f(this), i);
-    } : void 0 }), u);
-  }, set: t ? function(s) {
-    return t.call(f(this), s);
-  } : void 0 });
-}
-function C(e) {
-  const c = [];
-  let r = e.prototype;
-  for (; r && r !== v; )
-    c.push(r), r = b(r);
-  c.reverse();
-  for (const o of c) {
-    if (m(o, y))
-      continue;
-    const t = S(o), n = [];
-    for (const s of t) {
-      if (s === "constructor")
-        continue;
-      const u = d(o, s);
-      if (typeof u.value == "function") {
-        const i = Symbol(s);
-        n.push(i), $(o, s, i, u.value);
-      } else if (u.get) {
-        const i = Symbol(s);
-        n.push(i), E(o, s, i, u.get, u.set);
-      }
-    }
-    a(o, y, { value: n });
-  }
-  return m(e.prototype, "$stopEffects") || (a(e.prototype, "$watch", { enumerable: !1, configurable: !0, writable: !0, value: function(...o) {
-    const t = f(this);
-    return (t[l] ?? (t[l] = h(!0))).run(() => w(...o));
-  } }), a(e.prototype, "$watchEffect", { enumerable: !1, configurable: !0, writable: !0, value: function(...o) {
-    const t = f(this);
-    return (t[l] ?? (t[l] = h(!0))).run(() => O(...o));
-  } }), a(e.prototype, "$stopEffects", { enumerable: !1, configurable: !0, writable: !0, value: function(o) {
-    const t = f(this);
-    try {
-      const n = t[l];
-      n && n.stop();
-    } finally {
-      if (delete t[l], (o == null ? void 0 : o.reset) !== !1) {
-        let n = b(t);
-        for (; n && n !== v; ) {
-          const s = n[y];
-          if (s)
-            for (const u of s)
-              delete t[u];
-          n = b(n);
-        }
-      }
-    }
-  } })), e;
-}
-function P(e) {
-  var c;
-  return typeof e == "function" && !!e.prototype && !((c = d(e, "prototype")) != null && c.writable);
-}
-function D(e, c, r) {
-  const o = {};
-  for (const t in c) {
-    const n = e == null ? void 0 : e[t], s = c[t];
-    o[t] = { ...s }, s.required || n === void 0 || (typeof n == "object" && n !== null ? o[t].default = () => r ? r(n) : structuredClone(n) : P(n) ? o[t].default = () => n : o[t].default = n);
-  }
-  return o;
-}
-export {
-  C as Reactive,
-  P as isClass,
-  D as propsWithDefaults
-};
+import{effectScope as t,watch as e,watchEffect as o,toRaw as n,isRef as r}from"vue";function c(t){if(Array.isArray(t)){const e=new Array(t.length);for(let o=0;o<t.length;o++)o in t&&(e[o]=c(t[o]));return e}if(null===t||"object"!=typeof t||t.constructor!==Object&&void 0!==t.constructor)return t;const e={__proto__:Object.getPrototypeOf(t),...t};for(const t in e)e[t]=c(e[t]);return e}const s=Object.hasOwn,u=Object.getPrototypeOf,i=Object.getOwnPropertyDescriptor,f=Object.getOwnPropertyNames,l=Object.defineProperty,a=Object.prototype,p=Symbol.for("ivue.raw"),b=Symbol.for("ivue.scope"),y=Symbol.for("ivue.processed");function h(t){const e=n(t);if(e!==t)return e[p]??(e[p]=e);const o=t[p];return o?o===t?o:n(o):t[p]=t}function v(t,e,o,n){l(t,e,{configurable:!0,enumerable:!1,get(){const t=h(this);return t[o]??(t[o]=n.bind(t))},set(t){h(this)[o]=t}})}function g(t,e,o,n,c){const s="$"===e[0];l(t,e,{configurable:!0,enumerable:!1,get:function(){const u=h(this);if(o in u)return u[o];const i=n.call(u);return s?(u[o]=i,i):(r(i)?u[o]=i:l(t,e,{configurable:!0,enumerable:!1,get(){return n.call(h(this))},set:c?function(t){return c.call(h(this),t)}:void 0}),i)},set:c?function(t){return c.call(h(this),t)}:void 0})}function d(n){const r=[];let c=n.prototype;for(;c&&c!==a;)r.push(c),c=u(c);r.reverse();for(const t of r){if(s(t,y))continue;const e=f(t),o=[];for(const n of e){if("constructor"===n)continue;const e=i(t,n);if("function"==typeof e.value){const r=Symbol(n);o.push(r),v(t,n,r,e.value)}else if(e.get){const r=Symbol(n);o.push(r),g(t,n,r,e.get,e.set)}}l(t,y,{value:o})}return s(n.prototype,"$stopEffects")||(l(n.prototype,"$watch",{enumerable:!1,configurable:!0,writable:!0,value:function(...o){const n=h(this);return(n[b]??(n[b]=t(!0))).run((()=>e(...o)))}}),l(n.prototype,"$watchEffect",{enumerable:!1,configurable:!0,writable:!0,value:function(...e){const n=h(this);return(n[b]??(n[b]=t(!0))).run((()=>o(...e)))}}),l(n.prototype,"$stopEffects",{enumerable:!1,configurable:!0,writable:!0,value:function(t){const e=h(this);try{const t=e[b];t&&t.stop()}finally{if(delete e[b],!1!==(null==t?void 0:t.reset)){let t=u(e);for(;t&&t!==a;){const o=t[y];if(o)for(const t of o)delete e[t];t=u(t)}}}}})),n}function m(t){var e;return!("function"!=typeof t||!t.prototype||null!=(e=i(t,"prototype"))&&e.writable)}function w(t,e,o){const n={};for(const r in e){const s=null==t?void 0:t[r],u=e[r];n[r]={...u},!u.required&&void 0!==s&&("object"==typeof s&&null!==s?n[r].default=()=>o?o(s):c(s):m(s)?n[r].default=()=>s:n[r].default=s)}return n}function O(t){return t}export{d as Reactive,c as clone,O as definePropTypes,m as isClass,w as propsWithDefaults};

package/dist/nestedProps.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `nestedProps(props, defaults)` — fill a nested object prop from its
+ * defaults, in place, so the class reads complete props at every depth.
+ *
+ * Vue resolves a prop's default only when the prop is ABSENT: pass
+ * `{ wheel: { gain: 2 } }` for a prop whose default is
+ * `{ wheel: { gain: 1, follow: 0.1 }, touch: { … } }` and the component
+ * receives exactly the object it was passed — `follow` and `touch` are
+ * gone. `propsWithDefaults` decides what the default IS and clones it per
+ * instance; it cannot reach inside a supplied object. The fill is possible
+ * at all because the defaults are a value the class owns — a compiler-only
+ * default has nothing to fill from.
+ *
+ * The semantics are lodash's `defaultsDeep` with arrays taken whole: for
+ * every prop whose value and default are both plain objects, each leaf the
+ * supplied object lacks is written into it from the default, recursively;
+ * a leaf it has is kept. Missing plain-object and array defaults are copied
+ * recursively so instances never share those mutable containers. Arrays
+ * are never merged; class instances and functions retain their identity. Vue's
+ * props proxy is shallow, so the nested objects are the parent's own and
+ * are written directly; the props object itself is untouched and returned.
+ *
+ * Call it once, at the seam where props enter the class:
+ *
+ *   constructor(props: Scroller.Props, public emit: Scroller.Emits) {
+ *     this.props = nestedProps(props, this.self.propsDefaults);
+ *   }
+ *
+ * The parent passes a stable object: a constant inline literal (Vue hoists
+ * it), a `ref`'s value, a store field. An object built anew on every
+ * parent render is a new, unfilled object each time.
+ *
+ * `customCloner` is the same policy knob `propsWithDefaults` has: it copies
+ * each default branch written into the props. The default, `clone`, copies
+ * plain containers and keeps callbacks, constructors and opaque objects by
+ * reference, so no two instances share a mutable default. Pass
+ * `structuredClone` when `Date`, `Map` or `Set` defaults need their own
+ * copies; pass the identity, `value => value`, only when the caller owns
+ * every default it passes — a fresh tree per instance, never a shared one.
+ *
+ * `NestedPartial<T>` is the matching declaration for the prop's type — the
+ * shape an author may pass — and `NestedProps<P, D>` the type of the
+ * filled props, where every key both sides carry as an object is complete.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+/** Every key optional at every plain-object depth; arrays stay whole. */
+export declare type NestedPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: NestedPartial<T[K]>;
+} : T;
+/** The filled props' type: a key both sides carry as a plain object is complete. */
+export declare type NestedProps<P, D> = {
+    [K in keyof P as K extends keyof D ? K : never]-?: NestedLeaf<NonNullable<P[K]>, D[K & keyof D]>;
+} & {
+    [K in keyof P as K extends keyof D ? never : K]: P[K];
+};
+/** A value the fill takes whole: not a plain container. */
+declare type Opaque = Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never[]) => unknown);
+declare type NestedLeaf<V, D> = V extends readonly unknown[] ? V : V extends Opaque ? V : V extends object ? D extends readonly unknown[] ? V : D extends object ? NestedProps<V, D> : V : V;
+/**
+ * Fill every nested object prop from its default, in place, and return
+ * the props typed as complete. Top-level props are Vue's to default and
+ * are never written.
+ */
+export declare function nestedProps<P extends object, D extends object>(props: P, defaults: D, customCloner?: (value: unknown) => unknown): NestedProps<P, D>;
+export {};

package/lib/LazyShared.ts

@@ -35,11 +35,11 @@
  * entry stays minimal.
  */
 export class LazyShared<T> {
-  constructor(private readonly make: () => T) {}
+  constructor(protected readonly make: () => T) {}
 
-  private constructed = false;
-  private constructing = false;
-  private stored: T | null = null;
+  protected constructed = false;
+  protected constructing = false;
+  protected stored: T | null = null;
 
   get value(): T {
     if (!this.constructed) {

package/lib/Reactive.ts

@@ -7,6 +7,9 @@ import {
   type ExtractPropTypes,
   type Ref,
 } from 'vue';
+import { clone } from './clone';
+
+export { clone } from './clone';
 
 /**
  * Constants & Helpers
@@ -363,20 +366,20 @@ export function isClass(val: any): boolean {
  * but leave primitive properties and functions intact so that
  * the final object is fully defineComponent() style compatible.
  *
- * The default cloner is the native `structuredClone` (zero-dependency, handles
- * plain data, Map/Set/Date/typed arrays, circular refs). For defaults that
- * contain class instances or functions — which `structuredClone` cannot clone —
- * pass a `customCloner` such as lodash `cloneDeep`.
+ * The default cloner copies acyclic plain-object and array trees while
+ * retaining callbacks, class constructors and opaque objects by reference.
+ * For independent Map/Set/Date values or cyclic data, pass a `customCloner`
+ * such as `structuredClone` when the values support it.
  *
  * @param defaults Regular object of default key -> values
  * @param typedProps Props declared in defineComponent() style with type and possibly required declared, but without default
- * @param customCloner Optional cloner used for object/array defaults (defaults to structuredClone)
+ * @param customCloner Optional cloner used for object/array defaults (defaults to clone)
  * @returns Props declared in defineComponent() style with all properties having default property declared.
  */
 export function propsWithDefaults<T extends VuePropsObject>(
   defaults: Record<string, any>,
   typedProps: T,
-  // Optional: Allows user to pass a custom cloner if structuredClone isn't enough
+  // Optional: Choose different ownership semantics for opaque objects or cycles.
   customCloner?: (val: any) => any,
 ): VuePropsWithDefaults<T> {
   // NON-MUTATING: descriptor objects are routinely SHARED between props
@@ -394,7 +397,7 @@ export function propsWithDefaults<T extends VuePropsObject>(
 
     if (typeof def === 'object' && def !== null) {
       result[prop].default = () =>
-        customCloner ? customCloner(def) : structuredClone(def);
+        customCloner ? customCloner(def) : clone(def);
     } else {
       if (isClass(def)) {
         result[prop].default = () => def;
@@ -432,17 +435,27 @@ type WritableGetters<T> = {
   ]-?: T[K];
 };
 
-export type ReactiveInstance<T> = T &
-  WritableGetters<T> & {
-    /** Register a watcher in the instance's lazy effect scope (same signature as Vue `watch`). */
-    $watch: typeof watch;
-    /** Register a watchEffect in the instance's lazy effect scope (same signature as Vue `watchEffect`). */
-    $watchEffect: typeof watchEffect;
-    /** Stop the instance's effect scope and drop cached cells (the next
-     * touch re-materializes). `{ reset: false }` stops watchers only —
-     * every cached cell survives with its current value. */
-    $stopEffects: (options?: { reset?: boolean }) => void;
-  };
+/**
+ * The members `Reactive()` installs on every instance's prototype. A raw
+ * class body cannot see them (the transform runs after the class is typed),
+ * so a class that calls them merges this interface into its own instance
+ * type — one declaration beside the class, zero runtime:
+ *
+ *   class $Session { constructor() { this.$watch(…) } }
+ *   interface $Session extends ReactiveHelpers {}
+ */
+export interface ReactiveHelpers {
+  /** Register a watcher in the instance's lazy effect scope (same signature as Vue `watch`). */
+  $watch: typeof watch;
+  /** Register a watchEffect in the instance's lazy effect scope (same signature as Vue `watchEffect`). */
+  $watchEffect: typeof watchEffect;
+  /** Stop the instance's effect scope and drop cached cells (the next
+   * touch re-materializes). `{ reset: false }` stops watchers only —
+   * every cached cell survives with its current value. */
+  $stopEffects: (options?: { reset?: boolean }) => void;
+}
+
+export type ReactiveInstance<T> = T & WritableGetters<T> & ReactiveHelpers;
 
 export type ReactiveClass<C extends new (...args: any) => any> = {
   [Key in keyof C]: C[Key];
@@ -486,14 +499,32 @@ export type ExtractEmitTypes<T extends Record<string, any>> =
 
 /**
  * Extract properties as all-assigned (non-optional) because every one of
- * them carries a default.
+ * them carries a default — the honesty check: a declared type without a
+ * default is a compile error. Props declared `required: true` are FILTERED
+ * OUT automatically (a required prop can never carry a default —
+ * propsWithDefaults skips them at runtime), so no manual `Omit` is needed;
+ * a deliberately default-free OPTIONAL prop is declared `key: undefined`,
+ * stating the ruling in the defaults object itself. The `required: true`
+ * literal survives `typeof` only through generic inference — declare the
+ * types map with `definePropTypes({...})`, never as a bare object const.
  */
 export type ExtractPropDefaultTypes<O> = {
-  [K in keyof O]: K extends keyof ExtractPropTypes<O>
-    ? ExtractPropTypes<O>[K]
-    : never;
+  [K in keyof O as O[K] extends { required: true }
+    ? never
+    : K]: K extends keyof ExtractPropTypes<O> ? ExtractPropTypes<O>[K] : never;
 };
 
+/**
+ * Identity helper for a prop-TYPES map. Exists for one reason: in a bare
+ * `const propsTypes = {...}`, TypeScript widens `required: true` to
+ * `boolean`, which blinds ExtractPropDefaultTypes' required-key filter —
+ * generic inference through this call preserves the literal. Costs
+ * nothing at runtime.
+ */
+export function definePropTypes<T extends VuePropsObject>(types: T): T {
+  return types;
+}
+
 /**
  * Extend a slots interface T with prefixed 'before--' & 'after--' slots to
  * create fully extensible wrapped components.
@@ -516,4 +547,4 @@ export type IFnParameter<
   T extends Record<any, any>,
   P extends keyof T,
   K extends number,
-> = FnParameter<NonNullable<T[P]> extends AnyFn ? NonNullable<T[P]> : never, K>;
+> = FnParameter<NonNullable<T[P]> extends AnyFn ? NonNullable<T[P]> : never, K>;