@vmz/core 0.0.4 → 0.1.0

package/dist/dom-core.d.ts

@@ -0,0 +1,337 @@
+/**
+ * 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.
+ */
+/** @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 }}
+ */
+export declare function __vmzTraceSnapshot(): {
+    schema: string;
+    events: any[];
+    status: string;
+};
+/** @returns {typeof precision} */
+export declare function __vmzPrecisionSnapshot(): {
+    enabled: boolean;
+    writes: number;
+    bindingEvals: number;
+    patchExecs: number;
+    domCreates: number;
+    domMoves: number;
+    domRemoves: number;
+    componentExecs: number;
+    writesByRoot: any;
+    bindingEvalsByDep: any;
+    patchesByDep: any;
+    bindingEvalsByBinding: any;
+    patchesByBinding: any;
+};
+export declare function noteDomCreate(): void;
+/** @param {Record<string, any>} map */
+export declare function registerComponents(map: any): void;
+/** Sync registry lookup (SSR serialize / client). */
+export declare function getRegisteredComponent(name: any): any;
+/**
+ * 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>;
+/**
+ * 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]
+ */
+export declare function mount(Component: any, container: any, props?: {}): 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
+ */
+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). */
+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;
+    el(tag: any): any;
+    text(value: any): Text;
+    frag(): DocumentFragment;
+    attr(el: any, name: any, value: any): void;
+    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;
+    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;
+    /**
+     * Nested component (sync Direct child or island schedule).
+     * @param {object} hostInst
+     * @param {string} name
+     * @param {Record<string, any>} props
+     * @param {string | null} client
+     */
+    component(hostInst: any, name: any, props: any, client: any): HTMLDivElement;
+    /**
+     * 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>`.
+     * @param {HTMLElement} hostEl
+     * @param {Node} node
+     */
+    projectDefaultSlot(hostEl: any, node: any): void;
+    /**
+     * Direct if/else — no blueprint `kind: "if"` dispatch.
+     * @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): HTMLSpanElement;
+    /**
+     * 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;
+};
+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;
+/**
+ * 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
+ */
+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/…).
+ * Applies the mutator on the plain array and schedules a structural notice
+ * 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;