@vmz/core 0.1.32 → 0.2.1

package/dist/{client-nav.d.ts → browser/client-nav.d.ts}

@@ -1,11 +1,10 @@
 /**
- * Browser client navigation — same-app `<Link>` SPA takeover.
+ * 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 page (retain layout
  * when `data-vmz-layout` is unchanged) or full `#app`, then hydrate.
  */
 /**
- * @param {{
  *   fetchImpl?: typeof fetch,
  *   document?: Document,
  *   history?: History,
@@ -17,7 +16,7 @@
  *   importPage?: (chunkId: string) => Promise<any>,
  * }} [opts]
  */
-export declare function installClientNavigation(opts?: {}): {
+export declare function installClientNavigation(opts?: Record<string, any>): {
     ok: boolean;
     reason: string;
     transitionTo?: undefined;
@@ -25,11 +24,7 @@ export declare function installClientNavigation(opts?: {}): {
     dispose?: undefined;
 } | {
     ok: boolean;
-    transitionTo: (url: any, { replace, fromPop, softFail }?: {
-        replace?: boolean;
-        fromPop?: boolean;
-        softFail?: boolean;
-    }) => Promise<{
+    transitionTo: (url: any, { replace, fromPop, softFail }?: any) => Promise<{
         ok: boolean;
         reason: string;
         href?: undefined;
@@ -48,7 +43,7 @@ export declare function installClientNavigation(opts?: {}): {
         localeId: any;
         reason?: undefined;
     }>;
-    transitionLocale: (toLocale: any, opts?: {}) => Promise<{
+    transitionLocale: (toLocale: any, opts?: any) => Promise<{
         status: string;
         fromLocale: any;
         toLocale: any;
@@ -57,8 +52,4 @@ export declare function installClientNavigation(opts?: {}): {
     dispose(): void;
     reason?: undefined;
 };
-/**
- * @param {string} html
- * @param {Document} doc
- */
 export declare function extractAppHtml(html: any, doc: any): any;

package/dist/{client-nav.js → browser/client-nav.js}

@@ -1,12 +1,10 @@
 /**
- * Browser client navigation — same-app `<Link>` SPA takeover.
+ * 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 page (retain layout
  * when `data-vmz-layout` is unchanged) or full `#app`, then hydrate.
  */
-// @ts-nocheck
 /**
- * @param {{
  *   fetchImpl?: typeof fetch,
  *   document?: Document,
  *   history?: History,
@@ -24,7 +22,6 @@ export function installClientNavigation(opts = {}) {
     const hist = opts.history || win?.history;
     const loc = opts.location || win?.location;
     const fetchImplDefault = opts.fetchImpl || (typeof fetch === 'function' ? fetch.bind(globalThis) : null);
-    /** @type {typeof fetch | null} */
     let fetchImpl = fetchImplDefault;
     if (!doc || !hist || !loc || !fetchImpl) {
         return { ok: false, reason: 'missing document/history/fetch' };
@@ -42,10 +39,8 @@ export function installClientNavigation(opts = {}) {
     catch {
         /* ignore */
     }
-    /** @type {AbortController | null} */
     let inflight = null;
     let navigating = false;
-    /** @type {Map<string, { x: number, y: number }>} */
     const scrollPositions = new Map();
     function destroyInst(inst) {
         if (!inst)
@@ -70,10 +65,8 @@ export function installClientNavigation(opts = {}) {
         });
     }
     /**
-     * Route Transition Plan: restore scroll on popstate; forward nav → hash or top.
+     * Route Transition Plan: restore scroll on popstate; forward nav �?hash or top.
      * Re-applies across frames until scrollHeight can hold the saved Y (hydrate settle).
-     * @param {URL} target
-     * @param {boolean} fromPop
      */
     async function restoreScroll(target, fromPop) {
         if (!win)
@@ -103,7 +96,7 @@ export function installClientNavigation(opts = {}) {
                         break;
                     const docEl = doc.documentElement || doc.body;
                     const maxY = Math.max(0, (docEl?.scrollHeight || 0) - (win.innerHeight || 0));
-                    // Document still short — wait for hydrate/layout to grow scrollHeight.
+                    // Document still short �?wait for hydrate/layout to grow scrollHeight.
                     if (maxY + 2 < saved.y) {
                         await frame();
                         continue;
@@ -128,8 +121,6 @@ export function installClientNavigation(opts = {}) {
     }
     /**
      * Focus the primary page landmark after SPA swap (not a scattered runtime hook).
-     * @param {Element | null} root
-     * @param {URL} target
      */
     function restoreFocus(root, target) {
         if (!root || !doc)
@@ -147,7 +138,7 @@ export function installClientNavigation(opts = {}) {
             el = root;
         if (el === doc.body)
             return null;
-        const focusable = /** @type {HTMLElement} */ (el);
+        const focusable = el;
         if (!focusable.hasAttribute('tabindex') && focusable.tabIndex < 0) {
             focusable.setAttribute('tabindex', '-1');
         }
@@ -155,13 +146,12 @@ export function installClientNavigation(opts = {}) {
             focusable.focus({ preventScroll: true });
         }
         catch {
-            /* ignore — never focus() without preventScroll (would steal restored scrollY) */
+            /* ignore �?never focus() without preventScroll (would steal restored scrollY) */
         }
         return focusable.getAttribute('data-vmz-focus') || focusable.tagName?.toLowerCase() || null;
     }
     /**
      * Apply locale realization attributes from SSR `#app` onto `<html>`.
-     * @param {Element | null} root
      */
     function applyLocaleRealization(root) {
         if (!root || !doc?.documentElement)
@@ -196,7 +186,7 @@ export function installClientNavigation(opts = {}) {
                 signal,
             });
             if (!res.ok) {
-                // LocaleTransition uses softFail — keep current surface (no full assign).
+                // LocaleTransition uses softFail �?keep current surface (no full assign).
                 if (!fromPop && !softFail)
                     loc.assign(target.href);
                 return { ok: false, reason: `http ${res.status}` };
@@ -234,7 +224,6 @@ export function installClientNavigation(opts = {}) {
                     hist.pushState({ vmzClientNav: true }, '', target.href);
             }
             const importChunk = opts.importPage || (async (id) => (await import(/* @vite-ignore */ `/${id}.client.js`)).default);
-            /** @type {Element | null} */
             let liveRoot = root;
             let retainedLayout = false;
             // Apply target LocaleId before hydrate/onMount so `#locales/*` and
@@ -283,7 +272,6 @@ export function installClientNavigation(opts = {}) {
                 liveRoot = fresh;
                 if (chunkId) {
                     const Page = await importChunk(chunkId);
-                    /** @type {any[]} */
                     const layoutCtors = [];
                     for (const id of nextLayout) {
                         layoutCtors.push(await importChunk(id));
@@ -318,12 +306,12 @@ export function installClientNavigation(opts = {}) {
                     retainedLayout,
                     focusTarget,
                     localeId,
-                    // Pending until restoreScroll finishes — never lie as "restored" early (gate race).
+                    // Pending until restoreScroll finishes �?never lie as "restored" early (gate race).
                     scrollMode: 'pending',
                     scrollY: null,
                 };
             }
-            // Wait for hydrate/layout paint before applying scroll — otherwise scrollTo is clamped/reset.
+            // Wait for hydrate/layout paint before applying scroll �?otherwise scrollTo is clamped/reset.
             if (win && typeof win.requestAnimationFrame === 'function') {
                 await new Promise((resolve) => {
                     win.requestAnimationFrame(() => win.requestAnimationFrame(resolve));
@@ -370,16 +358,12 @@ export function installClientNavigation(opts = {}) {
         if (a.hasAttribute('download') || a.getAttribute('target') === '_blank')
             return;
         ev.preventDefault();
-        // Prefer frozen RouteId×LocaleId href table (0.1.30); fall back only when table missing.
+        // Prefer frozen RouteId�LocaleId href table (0.1.30); fall back only when table missing.
         const realized = localizeClickHref(u.pathname + u.search + u.hash, a.getAttribute('data-vmz-route'));
         void transitionTo(realized, {
             replace: a.getAttribute('data-vmz-replace') === 'true',
         });
     }
-    /**
-     * @param {string} href
-     * @param {string | null} [routeId]
-     */
     function localizeClickHref(href, routeId) {
         if (!doc?.documentElement)
             return href;
@@ -430,11 +414,11 @@ export function installClientNavigation(opts = {}) {
         if (!pathname)
             pathname = '/';
         const parts = pathname.split('/').filter(Boolean);
-        // Explicit locale prefix in href = intentional locale (switch/deep-link) — do not rewrite.
+        // Explicit locale prefix in href = intentional locale (switch/deep-link) �?do not rewrite.
         if (parts.length && supported.includes(parts[0])) {
             return `${pathname}${search}${hash}`;
         }
-        // Unprefixed same-app Link → realize with current LocaleId.
+        // Unprefixed same-app Link �?realize with current LocaleId.
         let rest = pathname;
         if (rest.length > 1 && rest.endsWith('/'))
             rest = rest.slice(0, -1);
@@ -452,15 +436,12 @@ export function installClientNavigation(opts = {}) {
     function onPopState() {
         void transitionTo(loc.pathname + loc.search + loc.hash, { fromPop: true });
     }
-    /** @type {number} */
     let localeTransitionGeneration = 0;
     /**
      * Atomic LocaleTransition (browser host slice):
-     * - prefix: validate → realize path → navigate/fetch → commit locale attrs from SSR HTML
-     * - none: validate → Host persist (localStorage+cookie) → commit attrs → reload (v1; no URL rewrite)
+     * - prefix: validate �?realize path �?navigate/fetch �?commit locale attrs from SSR HTML
+     * - none: validate �?Host persist (localStorage+cookie) �?commit attrs �?reload (v1; no URL rewrite)
      * Failure keeps the previous locale surface (no half-page commit).
-     * @param {string} toLocale
-     * @param {{ replace?: boolean, reload?: boolean }} [opts]
      */
     async function transitionLocale(toLocale, opts = {}) {
         const fromLocale = doc.documentElement?.getAttribute('data-locale') || null;
@@ -521,7 +502,7 @@ export function installClientNavigation(opts = {}) {
             return out;
         }
         if (!result?.ok) {
-            // transitionTo does not mutate html locale attrs before success — surface stays fromLocale.
+            // transitionTo does not mutate html locale attrs before success �?surface stays fromLocale.
             const still = doc.documentElement?.getAttribute('data-locale');
             const out = {
                 status: 'rolled_back',
@@ -564,11 +545,8 @@ export function installClientNavigation(opts = {}) {
         return out;
     }
     /**
-     * `routing.strategy: 'none'` — LocaleId is Host preference, not URL.
-     * Persist → commit document attrs + hint → full reload so `#locales/*` re-resolve (I2 v1).
-     * @param {string} toLocale
-     * @param {string | null} fromLocale
-     * @param {{ reload?: boolean }} [opts]
+     * `routing.strategy: 'none'` �?LocaleId is Host preference, not URL.
+     * Persist �?commit document attrs + hint �?full reload so `#locales/*` re-resolve (I2 v1).
      */
     function transitionLocaleNone(toLocale, fromLocale, opts = {}) {
         const STORE_KEY = 'vmz.locale';
@@ -621,9 +599,6 @@ export function installClientNavigation(opts = {}) {
         }
         return out;
     }
-    /**
-     * @returns {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string, locales?: string[] } | null}
-     */
     function readLocaleRouting() {
         const raw = doc.documentElement?.getAttribute('data-vmz-locale-routing');
         if (!raw)
@@ -637,9 +612,6 @@ export function installClientNavigation(opts = {}) {
     }
     /**
      * Re-realize current URL under target LocaleId via frozen href table when present.
-     * @param {string} href
-     * @param {string} localeId
-     * @param {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string, locales?: string[] }} routing
      */
     function realizePathForLocale(href, localeId, routing) {
         let pathname = href;
@@ -685,9 +657,6 @@ export function installClientNavigation(opts = {}) {
         const pathOut = rest === '/' ? `/${localeId}` : `/${localeId}${rest}`;
         return `${pathOut}${search}${hash}`;
     }
-    /**
-     * @returns {Record<string, Record<string, string>> | null}
-     */
     function readLocaleHrefTable() {
         const raw = doc.documentElement?.getAttribute('data-vmz-locale-hrefs');
         if (!raw)
@@ -700,10 +669,6 @@ export function installClientNavigation(opts = {}) {
             return null;
         }
     }
-    /**
-     * @param {string | null | undefined} routeId
-     * @param {string} localeId
-     */
     function lookupFrozenLocaleHref(routeId, localeId) {
         if (!routeId || !localeId)
             return null;
@@ -713,8 +678,6 @@ export function installClientNavigation(opts = {}) {
     }
     /**
      * Reverse-lookup RouteId from frozen table when html lacks data-vmz-route.
-     * @param {string} pathname
-     * @param {string | null} localeId
      */
     function resolveRouteIdFromHrefTable(pathname, localeId) {
         const table = readLocaleHrefTable();
@@ -765,20 +728,12 @@ export function installClientNavigation(opts = {}) {
         },
     };
 }
-/**
- * @param {string | null} raw
- * @returns {string[]}
- */
 function parseLayoutChain(raw) {
     return String(raw || '')
         .split(',')
         .map((s) => s.trim())
         .filter(Boolean);
 }
-/**
- * @param {string[]} a
- * @param {string[]} b
- */
 function layoutChainsEqual(a, b) {
     if (a.length !== b.length)
         return false;
@@ -788,11 +743,6 @@ function layoutChainsEqual(a, b) {
     }
     return true;
 }
-/**
- * @param {Element} root
- * @param {string[]} prevLayout
- * @param {string[]} nextLayout
- */
 function canRetainLayouts(root, prevLayout, nextLayout) {
     if (!layoutChainsEqual(prevLayout, nextLayout))
         return false;
@@ -803,10 +753,6 @@ function canRetainLayouts(root, prevLayout, nextLayout) {
     const insts = root.__vmzLayoutInsts;
     return Array.isArray(insts) && insts.length === nextLayout.length;
 }
-/**
- * @param {Element} root
- * @param {Element} nextApp
- */
 function applyAppAttrs(root, nextApp) {
     for (const name of ['data-vmz-page', 'data-vmz-props', 'data-vmz-layout', 'data-vmz-route', 'data-vmz-locale', 'data-vmz-dir']) {
         const v = nextApp.getAttribute(name);
@@ -816,10 +762,6 @@ function applyAppAttrs(root, nextApp) {
             root.setAttribute(name, v);
     }
 }
-/**
- * @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');

package/dist/browser/direct-api.types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Direct DOM API types for `@vmz/core` browser runtime.
+ */
+export type BindingId = number | string | null;
+export type PatchFn = (this: DirectInstance) => void;
+export type DirectBranchCreate = (api: DirectApi) => Node;
+export type DirectIfBranch = {
+    cond?: PatchFn;
+    create: DirectBranchCreate;
+};
+export type DirectEachSpec = {
+    as?: string;
+    list: PatchFn;
+    key?: PatchFn;
+    createItem: DirectBranchCreate;
+    serializeItem?: DirectBranchCreate;
+};
+export type BinderEntry = {
+    deps: string[];
+    fn: PatchFn;
+    bindingId?: BindingId;
+};
+export type DirtyTrieNode = {
+    [seg: string]: DirtyTrieNode | true | undefined;
+};
+export type ComponentListenerBag = Record<string, Array<(detail?: unknown) => void>>;
+export type VmzPlan = {
+    schema?: string;
+    root_ids?: Array<string | number>;
+    [key: string]: unknown;
+};
+export type TaskStatus = 'pending' | 'success' | 'error' | 'cancelled';
+export type TaskEntry = {
+    generation: number;
+    controller: AbortController | {
+        signal: {
+            aborted: boolean;
+        };
+        abort: () => void;
+    };
+    status: TaskStatus;
+    result?: unknown;
+    error?: unknown;
+    promise?: Promise<unknown>;
+};
+export type DirtyNotice = {
+    type: 'replace';
+    root: string;
+} | {
+    type: 'path';
+    root: string;
+    segs: string[];
+};
+/** Runtime instance shape mounted by Direct create / hydrate / resume. */
+export type DirectInstance = {
+    [key: string]: unknown;
+    __vmzDestroyed?: boolean;
+    __vmzDomRoot?: (Node & {
+        __vmzInst?: DirectInstance | null;
+    }) | null;
+    __vmzFlushTrie?: DirtyTrieNode | null;
+    __vmzFlushScheduled?: boolean;
+    __vmzFlushSync?: boolean;
+    __vmzDirtyTrie?: DirtyTrieNode | null;
+    __vmzDirty?: Set<string>;
+    __vmzDirtyNotices?: DirtyNotice[];
+    __vmzLeafDirty?: Array<{
+        root: string;
+        field: string;
+        idxs: number[];
+    }>;
+    __vmzDrainLeafDirty?: boolean;
+    __vmzBinders?: Record<string, BinderEntry | PatchFn>;
+    __vmzBindings?: Record<string, BinderEntry | PatchFn>;
+    __vmzDepToBindings?: Record<string, Array<string | number>>;
+    __vmzPendingChildMounts?: Array<Promise<unknown>>;
+    __vmzComponentListeners?: ComponentListenerBag;
+    __vmzOnParentProp?: (propName: string, value: unknown) => void;
+    __vmzApplyProps?: (props: object) => void;
+    __vmzTasks?: Record<string, TaskEntry>;
+    __vmzPlan?: VmzPlan | null;
+    __vmzCtor?: ComponentCtorLike | null;
+    __vmzQuiet?: boolean;
+    __vmzEventDepth?: number;
+    __vmzEachApplyLeaf?: unknown;
+    __vmzEachCompoundStride?: unknown;
+    __vmzEachTranspose?: unknown;
+    onMount?: () => void | Promise<void>;
+    onDestroy?: () => void | Promise<void>;
+};
+export type ComponentCtorLike = (new (props?: object) => DirectInstance) & {
+    __vmzDirect?: boolean;
+    __vmzCreate?: (this: DirectInstance, api: DirectApi) => Node;
+    __vmzSerialize?: (this: DirectInstance, api: DirectApi) => unknown;
+    __vmzPlan?: VmzPlan | unknown;
+    __vmzHostBox?: string;
+    __vmzTag?: string;
+    __vmzState?: string[];
+    __vmzProps?: string[];
+    __vmzWBInstalled?: boolean;
+    __vmzCtorAppliesProps?: boolean;
+    name?: string;
+};
+export type DirectEachCtx = {
+    noteItemBind: (bindingId: BindingId, deps: string[], fn: PatchFn) => void;
+    needDelegate: (type: string) => void;
+};
+/** Browser + generated artifact platform surface (0.2.0 thin runtime). */
+export type DirectApi = {
+    _inst: DirectInstance | null;
+    _branchBinds: Array<{
+        deps: string[];
+        fn: PatchFn;
+        bindingId?: BindingId;
+    }> | null;
+    _itemPatches: PatchFn[] | null;
+    _eachCtx: DirectEachCtx | null;
+    _resumeAdopt: null | Record<string, unknown>;
+    el: (tag: string) => Element;
+    text: (value?: unknown) => Text;
+    frag: () => DocumentFragment;
+    comment: (value?: string) => Comment;
+    attr: (el: Element, name: string, value: unknown) => void;
+    mergeClass: (...parts: unknown[]) => string;
+    mergeStyle: (...parts: unknown[]) => string;
+    insertBefore: (parent: Node, node: Node, ref: Node | null) => void;
+    removeNode: (node: Node) => void;
+    trackPatch: (inst: DirectInstance, deps: string[], patch: PatchFn, bindingId?: BindingId) => void;
+    specFieldText: (inst: DirectInstance, bindingId: BindingId, fieldName: string, textNode: Text) => void;
+    specFieldAttr: (inst: DirectInstance, bindingId: BindingId, fieldName: string, el: Element, name: string) => void;
+    on: (el: Element, type: string, handler: EventListener | PatchFn) => void;
+    onMethod: (el: Element, type: string, method: string) => void;
+    onComponentEvent: (el: Element, type: string, method: string) => void;
+    adoptEnter: (node: Element) => boolean;
+    adoptLeave: () => void;
+    projectDefaultSlot: (hostEl: HTMLElement, node: Node) => void;
+    setHtml: (el: Element, value: unknown) => void;
+    bindHtml: (inst: DirectInstance, bindingId: BindingId, deps: string[], get: PatchFn, el: Element) => void;
+    bindComponentProp: (inst: DirectInstance, bindingId: BindingId, deps: string[], get: PatchFn, hostInst: DirectInstance, propName: string) => void;
+    component: (Ctor: ComponentCtorLike | string, props?: object) => HTMLElement;
+};

package/dist/browser/direct-api.types.js

@@ -0,0 +1,4 @@
+/**
+ * Direct DOM API types for `@vmz/core` browser runtime.
+ */
+export {};

package/dist/browser/direct-host-box.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Direct host box model (`ui-direct-host-box`).
+ * Chip hosts opt into `display: contents`; block surfaces keep a real layout box.
+ */
+import type { ComponentCtor } from './dom-core.types.js';
+export declare const INLINE_HOST_CONTENTS: ReadonlySet<string>;
+export declare function resolveDirectHostBox(name: string, Ctor: ComponentCtor | null | undefined): 'contents' | 'block';
+/** Apply host box to a live DOM element (create / hydrate / resume). */
+export declare function applyDirectHostBox(host: HTMLElement, name: string, Ctor: ComponentCtor | null | undefined): void;
+/** SSR attrs fragment for host box (only when contents). */
+export declare function directHostBoxStyleAttr(name: string, Ctor: ComponentCtor | null | undefined): string | null;

package/dist/{direct-host-box.js → browser/direct-host-box.js}

@@ -2,13 +2,7 @@
  * Direct host box model (`ui-direct-host-box`).
  * Chip hosts opt into `display: contents`; block surfaces keep a real layout box.
  */
-/** @type {ReadonlySet<string>} */
 export const INLINE_HOST_CONTENTS = new Set(['Button', 'Badge', 'Link', 'Tag', 'Icon']);
-/**
- * @param {string} name
- * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
- * @returns {'contents' | 'block'}
- */
 export function resolveDirectHostBox(name, Ctor) {
     const explicit = Ctor && typeof Ctor.__vmzHostBox === 'string' ? Ctor.__vmzHostBox : null;
     if (explicit === 'contents' || explicit === 'block')
@@ -17,12 +11,7 @@ export function resolveDirectHostBox(name, Ctor) {
         return 'contents';
     return 'block';
 }
-/**
- * Apply host box to a live DOM element (create / hydrate / resume).
- * @param {HTMLElement} host
- * @param {string} name
- * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
- */
+/** Apply host box to a live DOM element (create / hydrate / resume). */
 export function applyDirectHostBox(host, name, Ctor) {
     if (!host || !host.style)
         return;
@@ -30,12 +19,7 @@ export function applyDirectHostBox(host, name, Ctor) {
         host.style.display = 'contents';
     }
 }
-/**
- * SSR attrs fragment for host box (only when contents).
- * @param {string} name
- * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
- * @returns {string | null}
- */
+/** SSR attrs fragment for host box (only when contents). */
 export function directHostBoxStyleAttr(name, Ctor) {
     return resolveDirectHostBox(name, Ctor) === 'contents' ? 'display:contents' : null;
 }