@vmz/core 0.1.32 → 0.2.1

package/dist/{dom-core.d.ts → browser/dom-core.d.ts}

@@ -1,30 +1,37 @@
 /**
- * VMZ DOM client runtime — precise patches, no VDOM diff (SSR lives in dom-ssr).
+ * VMZ DOM client runtime ??precise patches, no VDOM diff (SSR lives in dom-ssr).
  *
  *
  * Direct components expose `__vmzCreate` / `__vmzSerialize` / `__vmzPlan`.
  * Mount and client patches run that same schedule (SSR/hydrate/resume in dom-ssr).
- * Field writes only run registered dep patches — never re-create structure.
+ * Field writes only run registered dep patches ??never re-create structure.
  */
+import type { BindingId, DirectInstance, PatchFn } from './direct-api.types.js';
+import type { ComponentCtor, EachCtx, ResumeAdoptCtx } from './dom-core.types.js';
+export { mergeClassParts, mergeStyleParts } from '../shared/dom-attr-normalize.js';
 export { applyDirectHostBox, INLINE_HOST_CONTENTS, resolveDirectHostBox } from './direct-host-box.js';
 export { createUnknownComponentElement, markUnknownComponentHost, serializeUnknownComponentNode, UNKNOWN_COMPONENT_ERROR, } from './unknown-component.js';
-/** @param {boolean} [on] */
 export declare function __vmzPrecisionEnable(on?: boolean): void;
-/** @param {boolean} [on] */
 export declare function __vmzTraceEnable(on?: boolean): void;
 export declare function __vmzPrecisionReset(): void;
 export declare function __vmzTraceReset(): void;
 /**
- * StableId event snapshot (`vmz.dx.trace.v0` shape without schema stamp —
- * host may wrap via ingestRuntimeTrace).
- * @returns {{ schema: string, events: typeof traceBuf.events, status: string }}
+ * StableId event snapshot (`vmz.dx.trace.v0` shape without schema stamp ?? * host may wrap via ingestRuntimeTrace).
  */
 export declare function __vmzTraceSnapshot(): {
     schema: string;
-    events: any[];
+    events: {
+        stableId: {
+            kind: string;
+            id: string;
+        };
+        kind: string;
+        dep?: string;
+        t?: number;
+        chunkId?: string | null;
+    }[];
     status: string;
 };
-/** @returns {typeof precision} */
 export declare function __vmzPrecisionSnapshot(): {
     enabled: boolean;
     writes: number;
@@ -34,369 +41,209 @@ export declare function __vmzPrecisionSnapshot(): {
     domMoves: number;
     domRemoves: number;
     componentExecs: number;
-    writesByRoot: any;
-    bindingEvalsByDep: any;
-    patchesByDep: any;
-    bindingEvalsByBinding: any;
-    patchesByBinding: any;
+    writesByRoot: {
+        [x: string]: number;
+    };
+    bindingEvalsByDep: {
+        [x: string]: number;
+    };
+    patchesByDep: {
+        [x: string]: number;
+    };
+    bindingEvalsByBinding: {
+        [x: string]: number;
+    };
+    patchesByBinding: {
+        [x: string]: number;
+    };
 };
 export declare function noteDomCreate(): void;
-/** @param {Record<string, any>} map — Prefer createRenderHost().ensureComponents(); process-global registry. */
 export declare function registerComponents(map: any): void;
-/** Sync registry lookup (SSR serialize / client). */
-export declare function getRegisteredComponent(name: any): any;
+export declare function getRegisteredComponent(name: any): ComponentCtor;
 /**
  * Lazy component loader for EventEntry mixed packs (set by entry-client / entry-event).
- * @param {string} name
- * @returns {Promise<any>}
  */
-export declare function resolveComponent(name: any): Promise<any>;
+export declare function resolveComponent(name: any): Promise<ComponentCtor>;
 /**
  * Mount once; later updates are dep patches only (never re-run structure).
- * Requires compiler `__vmzCreate` (production Direct emit — no blueprint fallback).
- * @param {new (props?: object) => any} Component
- * @param {Element} container
- * @param {object} [props]
+ * Requires compiler `__vmzCreate` (production Direct emit ??no blueprint fallback).
  */
-export declare function mount(Component: any, container: any, props?: {}): Promise<any>;
+export declare function mount(Component: any, container: any, props?: any): Promise<any>;
 /**
  * Nested Direct `component` schedules child onMount asynchronously; drain before return
- * so SSR/hydrate callers see post-mount DOM (e.g. UserCard Ada, not Loading…).
- * @param {object} inst
+ * so SSR/hydrate callers see post-mount DOM (e.g. UserCard Ada, not Loading??.
  */
 export declare function settlePendingChildMounts(inst: any): Promise<void>;
-/**
- * @param {new (props?: object) => any} Component
- * @param {object} inst
- */
 export declare function runDirectCreate(Component: any, inst: any): any;
-/** Host API for compiler-emitted `__vmzCreate` (direct path, Program IR B). */
 /**
- * First default `<slot>` owned by this component tree — skip nested `[data-vmz]`
+ * First default `<slot>` owned by this component tree ??skip nested `[data-vmz]`
  * hosts (Button/Link/Empty label slots). `querySelector('slot')` steals those and
  * projects parent siblings into the wrong host (commercial Drawer into Create btn).
- * @param {Element | null | undefined} root
- * @returns {Element | null}
  */
 export declare function findOwnedDefaultSlot(root: any): any;
 export declare const directApi: {
-    /** @type {object | null} */
-    _inst: any;
-    /** @type {Array<{ deps: string[], fn: => any, bindingId?: number|string|null }> | null} */
-    _branchBinds: any;
-    /** @type {Array< => void> | null} */
-    _itemPatches: any;
-    /**
-     * Active keyed-each context (/): item binds + event delegation.
-     * @type {null | {
-     * noteItemBind: (bindingId: number|string|null, deps: string[], fn: => void) => void,
-     * needDelegate: (type: string) => void,
-     * }}
-     */
-    _eachCtx: any;
-    /** @type {null | {
-     * el: (tag: string) => Element,
-     * text: (value?: any) => Text,
-     * componentHost?: (name: string) => HTMLElement | null,
-     * enter?: (node: Element) => boolean,
-     * leave?: () => void,
-     * scopeDepth?: () => number,
-     * rewindScope?: (depth: number) => void,
-     * beginBranchScope?: () => () => void,
-     * }} */
-    _resumeAdopt: any;
+    _inst: DirectInstance | null;
+    _branchBinds: Array<{
+        deps: string[];
+        fn: PatchFn;
+        bindingId?: BindingId;
+    }> | null;
+    _itemPatches: PatchFn[] | null;
+    _eachCtx: EachCtx | null;
+    _resumeAdopt: ResumeAdoptCtx | null;
     el(tag: any): any;
-    text(value: any): any;
-    /** Push adopted node's private resume pool for depth-first child create. */
-    adoptEnter(node: any): any;
+    text(value: any): Text;
+    adoptEnter(node: any): boolean;
     adoptLeave(): void;
     frag(): DocumentFragment;
+    comment(value: any): Comment;
+    insertBefore(parent: any, node: any, ref: any): void;
+    removeNode(node: any): void;
+    /**
+     * Register a generated per-binding patch (0.2.0). No generic get/cf interpreter.
+     */
+    trackPatch(inst: any, deps: any, patch: any, bindingId?: any): void;
+    untrackPatch(inst: any, deps: any, patch: any, bindingId?: any): void;
+    disposeTree(root: any): void;
     attr(el: any, name: any, value: any): void;
+    mergeClass(...parts: any[]): string;
+    mergeStyle(...parts: any[]): string;
     on(el: any, type: any, handler: any): void;
     /**
      * Bind a named instance method (no arrow / Function#toString).
      * Learns `skipFlush` after a sync invocation that schedules no dirty work
      * (stride / transpose self-apply DOM).
-     * @param {Element} el
-     * @param {string} type
-     * @param {string} methodName
-     * @param {{ skipFlush?: boolean } | null | undefined} [opts]
      */
     onMethod(el: any, type: any, methodName: any, opts: any): void;
-    /**
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string[]} deps
-     * @param {() => any} get
-     * @param {Text} textNode
-     * @param {{ stable: string[], branches: Array<{ cond?: => any, deps: string[] }> } | null | undefined} [cf]
-     */
-    bindText(inst: any, bindingId: any, deps: any, get: any, textNode: any, cf: any): void;
-    /**
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string[]} deps
-     * @param {() => any} get
-     * @param {Element} el
-     * @param {string} name
-     * @param {{ stable: string[], branches: Array<{ cond?: => any, deps: string[] }> } | null | undefined} [cf]
-     */
-    bindAttr(inst: any, bindingId: any, deps: any, get: any, el: any, name: any, cf: any): void;
     /**
      * Specialized single-field attr bind (0.1.29): compile-time field name, no generic get closure in artifact.
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string} fieldName
-     * @param {Element} el
-     * @param {string} name
      */
     specFieldAttr(inst: any, bindingId: any, fieldName: any, el: any, name: any): void;
     /**
      * Specialized single-field text bind (0.1.29): compile-time field name in generated artifact.
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string} fieldName
-     * @param {Text} textNode
      */
     specFieldText(inst: any, bindingId: any, fieldName: any, textNode: any): void;
     setHtml(el: any, value: any): void;
-    /**
-     * Trusted HTML binding (`html={expr}`). Author/plugin responsibility.
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string[]} deps
-     * @param {() => any} get
-     * @param {Element} el
-     * @param {{ stable: string[], branches: Array<{ cond?: => any, deps: string[] }> } | null | undefined} [cf]
-     */
-    bindHtml(inst: any, bindingId: any, deps: any, get: any, el: any, cf: any): void;
+    bindHtml(inst: any, bindingId: any, deps: any, get: any, el: any): void;
     /**
      * Nested component (sync Direct child or island schedule).
-     * @param {object} hostInst
-     * @param {string | Function} nameOrCtor — PascalCase tag string, or static Ctor import
-     * @param {Record<string, any>} props
-     * @param {string | null} client
      */
     component(hostInst: any, nameOrCtor: any, props: any, client: any): any;
     /**
-     * Subscribe to a child component event (`@submit` → event name `submit`).
-     * Orthogonal to function props (`:on-submit` → prop `onSubmit`).
-     * @param {HTMLElement} hostEl
-     * @param {string} eventName
-     * @param {(ev?: any, ...rest: any[]) => any} handler
+     * Subscribe to a child component event (`@submit` ??event name `submit`).
+     * Orthogonal to function props (`:on-submit` ??prop `onSubmit`).
      */
     onComponentEvent(hostEl: any, eventName: any, handler: any): void;
     /**
      * Keep nested Direct child props live with parent field writes.
-     * @param {object} hostInst
-     * @param {HTMLElement} hostEl
-     * @param {string} propName
-     * @param {string[]} deps
-     * @param {() => any} get
      */
     bindComponentProp(hostInst: any, hostEl: any, propName: any, deps: any, get: any): void;
     /**
      * Project parent children into nested Direct component default `<slot>`.
      * Uses {@link findOwnedDefaultSlot} so nested Button/Link slots are not stolen.
-     * @param {HTMLElement} hostEl
-     * @param {Node} node
      */
     projectDefaultSlot(hostEl: any, node: any): void;
-    /**
-     * Direct if/else — comment anchors (no empty `span[data-vmz-if]` layout box).
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string[]} deps
-     * @param {Array<{ cond?: => any, create: (api: typeof directApi) => Node }>} branches
-     * @param {number|string|null} [regionId]
-     */
-    ifBlock(inst: any, bindingId: any, deps: any, branches: any, regionId?: any): DocumentFragment;
-    /**
-     * Direct keyed each — no blueprint `kind: "each"` dispatch.
-     * /: Set/Map + Fragment batch insert; item-local binds; host field dispatch; event delegate.
-     * @param {object} inst
-     * @param {number|string|null} bindingId
-     * @param {string[]} deps
-     * @param {{ as?: string, list: => any, key?: (box: {item:any,index:number}) => any, createItem: (api: typeof directApi, box: {item:any,index:number}) => Node }} spec
-     * @param {number|string|null} [regionId]
-     */
-    eachBlock(inst: any, bindingId: any, deps: any, spec: any, regionId?: any): DocumentFragment;
 };
 /**
  * Function prop wire: only `onXxx` camelCase is a handler prop.
- * Component `@event` must never normalize here — that channel is `onComponentEvent`.
- * @param {unknown} name
- * @returns {string | null}
+ * Component `@event` must never normalize here ??that channel is `onComponentEvent`.
  */
 export declare function eventPropHandlerName(name: any): string;
 /**
  * Dispatch a component event to parent subscribers registered via `onComponentEvent`.
  * Installed on every Direct instance as `inst.emit`.
- * @param {object} inst
- * @param {string} eventName
- * @param {...any} payload
  */
 export declare function emitComponentEvent(inst: any, eventName: any, ...payload: any[]): void;
 export declare function isEventPropName(name: any): boolean;
-/** HTML boolean attributes: presence means true; `false`/`null` must remove the attr. */
 export declare const BOOLEAN_HTML_ATTRS: Set<string>;
-/**
- * @param {Element} el
- * @param {string} name
- * @param {any} value
- */
 export declare function applyDomAttr(el: any, name: any, value: any): void;
 export declare function stripFns(obj: any): {};
 /**
  * Snapshot plain state/prop field values for Island HMR (session).
- * @param {object} inst
- * @returns {Record<string, unknown> | null}
  */
 export declare function snapshotInstanceState(inst: any): {};
-/**
- * @param {object} inst
- * @param {Record<string, unknown> | null | undefined} state
- */
 export declare function applyPreservedState(inst: any, state: any): void;
 /**
  * Tear down binders and stop patches. Safe to call more than once.
  * Field writes after destroy no longer update DOM (values may still change).
  *: also dispose owned DOM trees (child __vmzInst / region __vmzDispose).
- * @param {object} inst
  */
 export declare function destroy(inst: any): void;
 /**
  *: walk a DOM subtree and run lifetime dispose hooks + nested instance destroy.
  * Does not mark the *calling* parent destroyed; safe from destroy(inst).
- * @param {Node | null | undefined} root
  */
 export declare function disposeDomTree(root: any): void;
 export declare function scheduleClient(strategy: any, fn: any): void;
-/** @param {string} strategy */
 export declare function isEventEntryStrategy(strategy: any): boolean;
 export declare function scheduleClientOn(el: any, strategy: any, fn: any): void;
 /**
  * AsyncTask cancel protocol (first slice): keyed generation + AbortSignal.
  * Superseded runs and `destroy(inst)` abort prior work; stale results must not apply.
- * @param {object} inst
- * @param {string} key
- * @param {(signal: AbortSignal, meta: { generation: number }) => any | Promise<any>} fn
- * @returns {Promise<any>}
  */
 export declare function __vmzRunTask(inst: any, key: any, fn: any): Promise<any>;
-/** Abort all keyed tasks on an instance (also called from destroy). */
 export declare function __vmzCancelTasks(inst: any): void;
-/** @returns {'pending'|'success'|'error'|'cancelled'|null} */
 export declare function __vmzTaskStatus(inst: any, key: any): any;
-export declare function createInstance(Component: any, props?: {}): any;
+export declare function createInstance(Component: any, props?: any): any;
 /**
  * Mark a plain object as intentionally shared across ownership boundaries.
- * @param {any} value
  */
 export declare function __vmzAllowShared(value: any): any;
 /**
  * Take exclusive ownership intent: clear multi-owner registry for this object.
  * Subsequent field assigns re-register from the assigning instance only.
- * @param {any} value
  */
 export declare function __vmzTakeShared(value: any): any;
-/**
- * @returns {Array<{ kind: string, message: string }>}
- */
 export declare function __vmzSharedCrossComponentDiagnostics(): any[];
 export declare function __vmzSharedCrossComponentDiagnosticsReset(): void;
 /**
  * Read a nested path under a field root (for compound / update expansion).
- * @param {any} inst
- * @param {string} root
- * @param {string[]} segs
  */
 export declare function __vmzReadPath(inst: any, root: any, segs: any): any;
 /**
  * Short-circuit logical path assign (`||=` / `&&=` / `??=`).
- * @param {any} inst
- * @param {string} root
- * @param {string[]} segs
- * @param {'||'|'&&'|'??'} kind
- * @param {any} rhs
  */
 export declare function __vmzWritePathLogical(inst: any, root: any, segs: any, kind: any, rhs: any): any;
 export declare function __vmzWritePath(inst: any, root: any, segs: any, value: any): any;
 /**
  * Array-item leaf write without segs array alloc (`rows[i].label = v`).
- * @param {any} inst
- * @param {string} root
- * @param {string|number} idx
- * @param {string} leaf
- * @param {any} value
  */
 export declare function __vmzWritePathItem(inst: any, root: any, idx: any, leaf: any, value: any): any;
 /**
  * In-place two-index swap on an owned list field (WriteBarrier Slice 5).
  * Prefers eachBlock O(1) DOM transpose hook; otherwise schedules a list replace.
- * @param {any} inst
- * @param {string} root
- * @param {number|string} ia
- * @param {number|string} ib
  */
 export declare function __vmzListTranspose(inst: any, root: any, ia: any, ib: any): void;
 /**
- * Compound leaf write (`rows[i].label += x`) — one item touch, no separate ReadPath.
- * @param {any} inst
- * @param {string} root
- * @param {string[]} segs
- * @param {string} op
- * @param {any} rhs
+ * Compound leaf write (`rows[i].label += x`) ??one item touch, no separate ReadPath.
  */
 export declare function __vmzWritePathCompound(inst: any, root: any, segs: any, op: any, rhs: any): any;
 /**
  * Array-item compound without segs array alloc (`rows[i].label += x`).
- * @param {any} inst
- * @param {string} root
- * @param {string|number} idx
- * @param {string} leaf
- * @param {string} op
- * @param {any} rhs
  */
 export declare function __vmzWritePathCompoundItem(inst: any, root: any, idx: any, leaf: any, op: any, rhs: any): any;
 /**
  * Stride compound over an owned array (`for (i=start; i<n; i+=step) arr[i].leaf op= rhs`).
  * Mutates + applies DOM in one pass when eachBlock leaf hook is installed (update-every-Nth).
- * @param {any} inst
- * @param {string} root
- * @param {string} leaf
- * @param {string} op
- * @param {any} rhs
- * @param {number|string} start
- * @param {number|string} step
  */
 export declare function __vmzArrayItemCompoundStride(inst: any, root: any, leaf: any, op: any, rhs: any, start: any, step: any): void;
 /**
- * Compiler-inserted array mutator barrier (push/pop/splice/…).
+ * Compiler-inserted array mutator barrier (push/pop/splice/??.
  * Applies the mutator on the plain array and schedules a structural notice
- * at `root` + `baseSegs` (empty baseSegs → field replace).
+ * at `root` + `baseSegs` (empty baseSegs ??field replace).
  *
- * @param {any} inst
- * @param {string} root
- * @param {string[]} baseSegs
- * @param {string} method
- * @param {any[]} args
  */
 export declare function __vmzArrayMutate(inst: any, root: any, baseSegs: any, method: any, args: any): any;
 /**
  * WriteBarrier: true when value is an owned plain object with path barriers (no Proxy).
- * @param {any} value
  */
 export declare function __vmzIsWriteBarrierOwned(value: any): boolean;
 /**
  * True when value is the Proxy wrapper from array (or residual) reactive wrap.
- * @param {any} value
  */
 export declare function __vmzIsReactiveProxy(value: any): boolean;
-/** @param {object} inst */
 export declare function flushPending(inst: any): any;
 /**
  * True when the container already has meaningful DOM (SSR / resume shell).
- * @param {Element} el
  */
 export declare function hasMeaningfulChild(el: any): boolean;