@vmz/core 0.0.2 → 0.0.4

package/README.md

@@ -31,7 +31,8 @@ state write
   -> 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.
+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
 
@@ -41,7 +42,8 @@ There is no default detour through “execute every component that might matter,
 - **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.
+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
 

package/dist/client-nav.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Browser client navigation — same-app `<Link>` SPA takeover.
+ * Zero-JS still works via real `<a href>`; with JS, intercept same-origin
+ * `a[data-vmz-route]` clicks, pushState, fetch SSR HTML, swap #app, hydrate.
+ */
+/**
+ * @param {{
+ *   fetchImpl?: typeof fetch,
+ *   document?: Document,
+ *   history?: History,
+ *   location?: Location,
+ *   hydrate?: (Ctor: any, root: Element, props: object) => Promise<unknown>,
+ *   hydrateRoute?: (Page: any, root: Element, props: object, layouts?: any[]) => Promise<unknown>,
+ *   destroy?: (inst: object) => void,
+ *   importPage?: (chunkId: string) => Promise<any>,
+ * }} [opts]
+ */
+export declare function installClientNavigation(opts?: {}): {
+    ok: boolean;
+    reason: string;
+    transitionTo?: undefined;
+    dispose?: undefined;
+} | {
+    ok: boolean;
+    transitionTo: (url: any, { replace, fromPop }?: {
+        replace?: boolean;
+        fromPop?: boolean;
+    }) => Promise<{
+        ok: boolean;
+        reason: string;
+        href?: undefined;
+        chunkId?: undefined;
+    } | {
+        ok: boolean;
+        href: string;
+        chunkId: any;
+        reason?: undefined;
+    }>;
+    dispose(): void;
+    reason?: undefined;
+};
+/**
+ * @param {string} html
+ * @param {Document} doc
+ */
+export declare function extractAppHtml(html: any, doc: any): any;

package/dist/client-nav.js

@@ -0,0 +1,186 @@
+/**
+ * Browser client navigation — same-app `<Link>` SPA takeover.
+ * Zero-JS still works via real `<a href>`; with JS, intercept same-origin
+ * `a[data-vmz-route]` clicks, pushState, fetch SSR HTML, swap #app, hydrate.
+ */
+// @ts-nocheck
+/**
+ * @param {{
+ *   fetchImpl?: typeof fetch,
+ *   document?: Document,
+ *   history?: History,
+ *   location?: Location,
+ *   hydrate?: (Ctor: any, root: Element, props: object) => Promise<unknown>,
+ *   hydrateRoute?: (Page: any, root: Element, props: object, layouts?: any[]) => Promise<unknown>,
+ *   destroy?: (inst: object) => void,
+ *   importPage?: (chunkId: string) => Promise<any>,
+ * }} [opts]
+ */
+export function installClientNavigation(opts = {}) {
+    const doc = opts.document || (typeof document !== 'undefined' ? document : null);
+    const win = typeof window !== 'undefined' ? window : null;
+    const hist = opts.history || win?.history;
+    const loc = opts.location || win?.location;
+    const fetchImpl = opts.fetchImpl || (typeof fetch === 'function' ? fetch.bind(globalThis) : null);
+    if (!doc || !hist || !loc || !fetchImpl) {
+        return { ok: false, reason: 'missing document/history/fetch' };
+    }
+    if (win && !win.__vmzBootId) {
+        win.__vmzBootId = `boot-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    }
+    if (win)
+        win.__vmzClientNavInstalled = true;
+    /** @type {AbortController | null} */
+    let inflight = null;
+    let navigating = false;
+    async function transitionTo(url, { replace = false, fromPop = false } = {}) {
+        const target = new URL(url, loc.href);
+        if (target.origin !== loc.origin) {
+            loc.assign(target.href);
+            return { ok: false, reason: 'cross-origin' };
+        }
+        if (inflight)
+            inflight.abort();
+        inflight = new AbortController();
+        const signal = inflight.signal;
+        navigating = true;
+        try {
+            const res = await fetchImpl(target.pathname + target.search, {
+                method: 'GET',
+                headers: { accept: 'text/html', 'x-vmz-client-nav': '1' },
+                signal,
+            });
+            if (!res.ok) {
+                // Fall back to full navigation on hard errors.
+                if (!fromPop)
+                    loc.assign(target.href);
+                return { ok: false, reason: `http ${res.status}` };
+            }
+            const html = await res.text();
+            const nextApp = extractAppHtml(html, doc);
+            if (!nextApp) {
+                if (!fromPop)
+                    loc.assign(target.href);
+                return { ok: false, reason: 'missing #app in response' };
+            }
+            const root = doc.getElementById('app');
+            if (!root) {
+                if (!fromPop)
+                    loc.assign(target.href);
+                return { ok: false, reason: 'missing #app' };
+            }
+            // Dispose previous Direct instance if present.
+            const prev = root.__vmzInst;
+            if (prev && typeof opts.destroy === 'function') {
+                opts.destroy(prev);
+            }
+            else if (prev && win?.vmzDestroy) {
+                win.vmzDestroy(prev);
+            }
+            root.__vmzInst = null;
+            root.outerHTML = nextApp.outerHTML;
+            const fresh = doc.getElementById('app');
+            if (!fresh)
+                return { ok: false, reason: 'swap lost #app' };
+            if (!fromPop) {
+                if (replace)
+                    hist.replaceState({ vmzClientNav: true }, '', target.href);
+                else
+                    hist.pushState({ vmzClientNav: true }, '', target.href);
+            }
+            const chunkId = fresh.getAttribute('data-vmz-page') || '';
+            let props = {};
+            try {
+                const raw = fresh.getAttribute('data-vmz-props');
+                if (raw)
+                    props = JSON.parse(raw);
+            }
+            catch {
+                /* ignore */
+            }
+            if (chunkId) {
+                const importChunk = opts.importPage || (async (id) => (await import(/* @vite-ignore */ `/${id}.client.js`)).default);
+                const Page = await importChunk(chunkId);
+                const layoutChain = (fresh.getAttribute('data-vmz-layout') || '')
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                /** @type {any[]} */
+                const layoutCtors = [];
+                for (const id of layoutChain) {
+                    layoutCtors.push(await importChunk(id));
+                }
+                const dom = await import(/* @vite-ignore */ '/vmz-dom.js');
+                const hydrateRoute = opts.hydrateRoute || dom.hydrateRoute;
+                if (typeof hydrateRoute === 'function') {
+                    await hydrateRoute(Page, fresh, props, layoutCtors);
+                }
+                else {
+                    const hydrate = opts.hydrate || dom.hydrate;
+                    await hydrate(Page, fresh, props);
+                }
+            }
+            if (win) {
+                win.__vmzClientNavCount = (win.__vmzClientNavCount || 0) + 1;
+                win.__vmzLastClientNav = {
+                    href: target.pathname + target.search,
+                    routeId: nextApp.getAttribute?.('data-vmz-route') || null,
+                    chunkId,
+                    bootId: win.__vmzBootId,
+                };
+            }
+            return { ok: true, href: target.pathname + target.search, chunkId };
+        }
+        finally {
+            navigating = false;
+        }
+    }
+    function onClick(ev) {
+        if (navigating)
+            return;
+        if (ev.defaultPrevented)
+            return;
+        if (ev.button !== 0)
+            return;
+        if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey)
+            return;
+        const a = ev.target?.closest?.('a[data-vmz-route][href]');
+        if (!a)
+            return;
+        const href = a.getAttribute('href');
+        if (!href || href.startsWith('#') || /^(mailto|tel|javascript):/i.test(href))
+            return;
+        const u = new URL(href, loc.href);
+        if (u.origin !== loc.origin)
+            return;
+        // Download / new tab
+        if (a.hasAttribute('download') || a.getAttribute('target') === '_blank')
+            return;
+        ev.preventDefault();
+        void transitionTo(u.pathname + u.search + u.hash, {
+            replace: a.getAttribute('data-vmz-replace') === 'true',
+        });
+    }
+    function onPopState() {
+        void transitionTo(loc.pathname + loc.search + loc.hash, { fromPop: true });
+    }
+    doc.addEventListener('click', onClick);
+    win?.addEventListener?.('popstate', onPopState);
+    return {
+        ok: true,
+        transitionTo,
+        dispose() {
+            doc.removeEventListener('click', onClick);
+            win?.removeEventListener?.('popstate', onPopState);
+        },
+    };
+}
+/**
+ * @param {string} html
+ * @param {Document} doc
+ */
+export function extractAppHtml(html, doc) {
+    const parser = new (doc.defaultView?.DOMParser || globalThis.DOMParser)();
+    const parsed = parser.parseFromString(html, 'text/html');
+    return parsed.getElementById('app');
+}

package/dist/dom.d.ts

@@ -1,7 +1,6 @@
 /**
  * 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.
@@ -14,7 +13,7 @@ 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 —
+ * 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 }}
  */
@@ -45,27 +44,46 @@ 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>;
+export declare function renderToString(Component: any, props?: {}, opts?: {}): 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]
+ * @param {{ signal?: AbortSignal, slotHtml?: string }} [opts]
  * @returns {AsyncGenerator<string, void, void>}
  */
 export declare function renderToStream(Component: any, props?: {}, opts?: {}): AsyncGenerator<any, void, unknown>;
+/**
+ * Live-DOM counterpart: first default `<slot>` owned by this tree, not by a nested
+ * `[data-vmz]` component (Button/Link labels, etc.).
+ * @param {Element | null | undefined} root
+ * @returns {Element | null}
+ */
+export declare function findOwnedDefaultSlot(root: any): any;
+/**
+ * Hydrate/mount a file-route page inside an optional layout chain (outer → inner).
+ * Mirrors SSR `slotHtml` wrapping: each layout's owned default slot becomes the
+ * outlet for the next layout or the page. Retains layout instances on `container`
+ * so SPA transitions can dispose only the page host.
+ * @param {new (props?: object) => any} Page
+ * @param {Element} container
+ * @param {object} [props]
+ * @param {Array<new (props?: object) => any>} [layoutCtors] outer → inner
+ * @param {{ preserveState?: boolean | Record<string, unknown>, skipOnMount?: boolean }} [opts]
+ */
+export declare function hydrateRoute(Page: any, container: any, props?: {}, layoutCtors?: any[], opts?: {}): Promise<any>;
 /**
  * Mount once; later updates are dep patches only (never re-run structure).
- * Requires compiler `__vmzCreate` (Gate 3 — no blueprint fallback).
+ * 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>;
 /**
- * Snapshot plain state/prop field values for Island HMR (N4.3).
+ * Snapshot plain state/prop field values for Island HMR (session).
  * @param {object} inst
  * @returns {Record<string, unknown> | null}
  */
@@ -76,7 +94,7 @@ export declare function snapshotInstanceState(inst: any): {};
  */
 export declare function applyPreservedState(inst: any, state: any): void;
 /**
- * L5: attach to existing Island DOM without re-running construct structure or onMount.
+ * resume: 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
@@ -105,12 +123,12 @@ export declare function hydrate(Component: any, container: any, props?: {}, opts
 /**
  * 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).
+ *: 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.
+ *: 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
  */
@@ -135,7 +153,6 @@ export declare function __vmzCancelTasks(inst: any): void;
 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;
@@ -167,7 +184,6 @@ export declare function __vmzReadPath(inst: any, root: any, segs: any): any;
  */
 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),
@@ -193,7 +209,7 @@ export declare function __vmzWritePath(inst: any, root: any, segs: any, value: a
  */
 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).
+ * WriteBarrier: true when value is an owned plain object with path barriers (no Proxy).
  * @param {any} value
  */
 export declare function __vmzIsWriteBarrierOwned(value: any): boolean;