@vmz/core 0.0.0 → 0.0.2

package/README.md

@@ -1,3 +1,48 @@
 # @vmz/core
 
-Placeholder package (0.0.0). Reserved for the VMZ project. Do not depend on this version.
+The browser should not have to rediscover an application's structure after every click. Yet that is the default cost of
+many UI systems: execute components again, compare a virtual tree, and infer which DOM work might be necessary.
+
+`@vmz/core` is the production runtime behind VMZ's alternative. It executes the creation, patch, SSR, resumption, HTTP,
+and lifetime schedules produced by the compiler. When VMZ can prove that a write affects one text binding, one control
+region, or one keyed item, the runtime can update that target directly rather than begin from a whole component tree.
+
+The same idea continues beyond a single browser update. SSR serializes planned regions; resumption attaches only
+reachable state and event entries instead of repeating completed server work; ownership regions give async tasks and
+resources a deterministic end; server and HTTP output stay tied to compiler-visible capabilities.
+
+| Instead of...                      | VMZ runtime work begins from...                       |
+|------------------------------------|-------------------------------------------------------|
+| Re-running a component tree        | A known affected binding or region                    |
+| Reconciling a generic virtual tree | Direct create, patch, switch, or keyed-list work      |
+| Hydrating every rendered component | The event and state entries that are actually reached |
+| Hoping cleanup follows callbacks   | A compiler-known ownership and disposal boundary      |
+
+For application authors, this mostly stays out of sight: write VMZ source and let the compiler generate the plan.
+`@vmz/core` matters when you care about the kind of runtime your product ships: small in responsibility, direct in
+execution, and able to account for why its work exists. 🌱
+
+## The hot path VMZ is aiming for
+
+```text
+state write
+  -> known dependency edge
+  -> affected computation or region
+  -> direct patch / switch / reconcile
+```
+
+There is no default detour through “execute every component that might matter, build virtual nodes, then compare them.” If analysis must widen, it widens to a safe region and should preserve the reason.
+
+## More than DOM updates
+
+- **Transactions:** related writes can settle before dependent work runs.
+- **Ownership:** branches, list items, resources, and tasks have a known lifetime.
+- **Cancellation:** an obsolete navigation or async generation cannot write into new state.
+- **Resumption:** the browser attaches to server-produced work at the smallest reachable boundary.
+- **Zero-JS delivery:** pages with no interactive requirement do not need an eager framework shell.
+
+The runtime should not grow a second compiler made of reflection, string dependencies, or generic proxies. Its quality comes from faithfully executing the generated plan while keeping the production surface focused.
+
+## License
+
+MIT

package/dist/dom.d.ts

@@ -0,0 +1,206 @@
+/**
+ * VMZ DOM / SSR runtime — precise patches, no VDOM diff.
+ *
+ * Design: 规划设计/vmz/04 · Gate 3 (no production `render()`)
+ *
+ * Direct components expose `__vmzCreate` / `__vmzSerialize` / `__vmzPlan`.
+ * Mount, SSR, hydrate, and resume all run that same schedule.
+ * 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;
+/**
+ * X5 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;
+};
+/** @param {Record<string, any>} map */
+export declare function registerComponents(map: any): void;
+/**
+ * @param {new (props?: object) => any} Component
+ * @param {object} [props]
+ */
+export declare function renderToString(Component: any, props?: {}): Promise<any>;
+/**
+ * Stream SSR via the same Direct serialize schedule as `renderToString`.
+ * Yields HTML chunks (open tag → children → close). Joining chunks equals `renderToString`.
+ * Supports AbortSignal for cancel; consumers should respect backpressure (await between chunks).
+ * @param {new (props?: object) => any} Component
+ * @param {object} [props]
+ * @param {{ signal?: AbortSignal }} [opts]
+ * @returns {AsyncGenerator<string, void, void>}
+ */
+export declare function renderToStream(Component: any, props?: {}, opts?: {}): AsyncGenerator<any, void, unknown>;
+/**
+ * Mount once; later updates are dep patches only (never re-run structure).
+ * Requires compiler `__vmzCreate` (Gate 3 — 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>;
+/**
+ * Snapshot plain state/prop field values for Island HMR (N4.3).
+ * @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;
+/**
+ * L5: attach to existing Island DOM without re-running construct structure or onMount.
+ * Consumes ResumeEntry product (`data-vmz-resume`) derived from the same Execution Plan.
+ * @param {new (props?: object) => any} Component
+ * @param {HTMLElement} container
+ * @param {{ props?: object, state?: Record<string, unknown>, strategy?: string } | null} [slice]
+ */
+export declare function resume(Component: any, container: any, slice?: any): Promise<any>;
+/**
+ * Resume all `[data-vmz-island]` hosts (prefer ResumeEntry / EventEntry over mount).
+ * Event strategy islands wait for the DOM event before attach (lazy EventEntry).
+ * @param {ParentNode} [root]
+ */
+export declare function resumeIslands(root?: Document): void;
+/**
+ * EventEntry attach: only wire `client:event` / `client:event:*` islands.
+ * Idle/load/visible ResumeEntries are left alone (static shell can defer framework work).
+ * @param {ParentNode} [root]
+ */
+export declare function attachEventEntries(root?: Document): void;
+/**
+ * @param {new (props?: object) => any} Component
+ * @param {HTMLElement} container
+ * @param {object} [props]
+ * @param {{ preserveState?: boolean | Record<string, unknown>, skipOnMount?: boolean }} [opts]
+ */
+export declare function hydrate(Component: any, container: any, props?: {}, opts?: {}): Promise<any>;
+/**
+ * Tear down binders and stop patches. Safe to call more than once.
+ * Field writes after destroy no longer update DOM (values may still change).
+ * L4: also dispose owned DOM trees (child __vmzInst / region __vmzDispose).
+ * @param {object} inst
+ */
+export declare function destroy(inst: any): void;
+/**
+ * L4: 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;
+/**
+ * @param {ParentNode} [root]
+ */
+export declare function hydrateIslands(root?: Document): void;
+export declare function scheduleClient(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;
+/**
+ * Mark a plain object as intentionally shared across ownership boundaries.
+ * Suppresses cross-component shared diagnostics (规划设计/vmz/13 §7.3).
+ * @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;
+/**
+ * Compiler-inserted path write barrier (规划设计/vmz/13 §7.3).
+ * Mutates a plain owned object/array and schedules the same path notice Proxy would.
+ *
+ * Root-array index assigns (`tags[0] = x`) notify as field replace (structural),
+ * matching the transitional Proxy wrapArray behavior.
+ * Shared multi-owner: writing through one field notifies all owners of the same raw object.
+ *
+ * @param {any} inst
+ * @param {string} root field root
+ * @param {string[]} segs path under root (non-empty); dynamic indices already String(...)'d
+ * @param {any} value
+ */
+export declare function __vmzWritePath(inst: any, root: any, segs: any, value: any): any;
+/**
+ * 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;
+/**
+ * L4 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): Promise<void>;