@heshammesalam/heshjs 0.0.0-stage → 0.2.0

package/dist/router/index.js

@@ -0,0 +1,258 @@
+import { signal, batch } from '../reactivity/index.js';
+function segments(path) { return path.split('/').filter(Boolean); }
+function validate(routes, ancestors = new Set()) {
+    const siblings = new Set();
+    for (const route of routes) {
+        if (/[?#]/.test(route.path))
+            throw new Error(`Route paths cannot contain query/hash: ${route.path}`);
+        const parts = segments(route.path);
+        const signature = parts.map(p => p.startsWith(':') ? ':' : p).join('/');
+        if (siblings.has(signature))
+            throw new Error(`Duplicate sibling route: ${route.path}`);
+        siblings.add(signature);
+        const names = new Set(ancestors);
+        parts.forEach((p, i) => {
+            if (p === '*' && (i !== parts.length - 1 || route.children?.length))
+                throw new Error('Wildcard must end a leaf route');
+            if (p.startsWith(':')) {
+                const name = p.slice(1);
+                if (!/^[a-zA-Z_][a-zA-Z\d_]*$/.test(name) || names.has(name) || ['__proto__', 'prototype', 'constructor'].includes(name))
+                    throw new Error(`Invalid or duplicate route param: ${name}`);
+                names.add(name);
+            }
+        });
+        validate(route.children ?? [], names);
+    }
+}
+function find(routes, parts, at = 0, params = {}) {
+    const ordered = [...routes].sort((a, b) => {
+        const aa = segments(a.path), bb = segments(b.path);
+        for (let i = 0; i < Math.max(aa.length, bb.length); i++) {
+            const rank = (p) => p === '*' ? 0 : p?.startsWith(':') ? 1 : p ? 2 : 0.5;
+            const diff = rank(bb[i]) - rank(aa[i]);
+            if (diff)
+                return diff;
+        }
+        return 0;
+    });
+    for (const record of ordered) {
+        const own = { ...params };
+        let cursor = at, matched = true;
+        for (const part of segments(record.path)) {
+            if (part === '*') {
+                own['wildcard'] = parts.slice(cursor).join('/');
+                cursor = parts.length;
+                break;
+            }
+            const actual = parts[cursor++];
+            if (actual === undefined) {
+                matched = false;
+                break;
+            }
+            if (part.startsWith(':'))
+                own[part.slice(1)] = actual;
+            else if (part !== actual) {
+                matched = false;
+                break;
+            }
+        }
+        if (!matched)
+            continue;
+        const entry = { record, params: own };
+        const children = find(record.children ?? [], parts, cursor, own);
+        if (children)
+            return [entry, ...children];
+        if (cursor === parts.length)
+            return [entry];
+    }
+    return undefined;
+}
+export function createRouter(options) {
+    validate(options.routes);
+    const browser = options.window ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!browser)
+        throw new Error('createRouter requires a browser Window');
+    const report = options.onError ?? ((error) => console.error(error));
+    const location = signal(makeLocation(new URL(browser.location.href), {}));
+    let root, active = [], fallback;
+    let transitioning = false;
+    let generation = 0;
+    const notFoundRecord = options.notFound ? { path: '*', module: options.notFound } : undefined;
+    function makeLocation(url, params) {
+        return Object.freeze({ url: new URL(url), pathname: url.pathname, params: Object.freeze({ ...params }), query: new URLSearchParams(url.search), hash: url.hash });
+    }
+    function render(url) {
+        if (!root)
+            throw new Error('Start the router before navigating');
+        if (transitioning)
+            throw new Error('Navigation during module mounting is not supported');
+        transitioning = true;
+        try {
+            let entries;
+            try {
+                entries = find(options.routes, segments(url.pathname).map(decodeURIComponent));
+            }
+            catch (error) {
+                if (!(error instanceof URIError))
+                    throw error;
+            }
+            if (!entries && notFoundRecord)
+                entries = [{ record: notFoundRecord, params: {} }];
+            entries ??= [];
+            let keep = 0;
+            while (keep < active.length && keep < entries.length && active[keep].record === entries[keep].record && JSON.stringify(active[keep].params) === JSON.stringify(entries[keep].params))
+                keep++;
+            const removed = active.splice(keep);
+            const errors = [];
+            for (const item of removed.reverse()) {
+                try {
+                    item.instance.dispose();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            fallback?.remove();
+            fallback = undefined;
+            if (errors.length)
+                throw new AggregateError(errors, 'Route cleanup failed');
+            const added = [];
+            try {
+                for (let i = keep; i < entries.length; i++) {
+                    const entry = entries[i];
+                    const parent = active.at(-1);
+                    const outlet = parent ? parent.instance.outlet : root;
+                    if (!outlet)
+                        throw new Error(`Parent module ${parent.record.path} must render Outlet()`);
+                    const instance = entry.record.module.attach(outlet, makeLocation(url, entry.params), parent?.instance.context, { onError: report });
+                    const item = { ...entry, instance };
+                    active.push(item);
+                    added.push(item);
+                }
+            }
+            catch (error) {
+                active.splice(keep);
+                for (const item of added.reverse()) {
+                    try {
+                        item.instance.dispose();
+                    }
+                    catch (cleanupError) {
+                        report(cleanupError);
+                    }
+                }
+                throw error;
+            }
+            if (!entries.length) {
+                fallback = root.ownerDocument.createElement('p');
+                fallback.setAttribute('role', 'status');
+                fallback.textContent = 'Page not found';
+                root.appendChild(fallback);
+            }
+            batch(() => {
+                for (const item of active)
+                    item.instance.update(makeLocation(url, item.params));
+                location.set(makeLocation(url, entries.at(-1)?.params ?? {}));
+            });
+        }
+        finally {
+            transitioning = false;
+        }
+    }
+    function navigate(to, navigation = {}) {
+        if (!root)
+            throw new Error('Start the router before navigating');
+        const url = new URL(to, browser.location.href);
+        if (!['http:', 'https:'].includes(url.protocol) || url.origin !== browser.location.origin)
+            throw new Error('Router navigation requires a same-origin HTTP(S) URL');
+        if (url.href === browser.location.href)
+            return;
+        render(url);
+        browser.history[navigation.replace ? 'replaceState' : 'pushState'](null, '', url.href);
+    }
+    const popstate = () => {
+        try {
+            if (location.get().url.href !== browser.location.href)
+                render(new URL(browser.location.href));
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    const click = (event) => {
+        if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey)
+            return;
+        const target = event.target;
+        const anchor = target?.closest?.('a[href]');
+        if (!anchor || anchor.hasAttribute('download') || anchor.hasAttribute('data-hesh-reload') || (anchor.getAttribute('target') && anchor.getAttribute('target').toLowerCase() !== '_self'))
+            return;
+        const href = anchor.getAttribute('href');
+        if (href.startsWith('#'))
+            return;
+        let url;
+        try {
+            url = new URL(href, browser.document.baseURI);
+        }
+        catch {
+            return;
+        }
+        if (!['http:', 'https:'].includes(url.protocol) || url.origin !== browser.location.origin)
+            return;
+        if (url.pathname === browser.location.pathname && url.search === browser.location.search && url.hash)
+            return;
+        event.preventDefault();
+        try {
+            navigate(url.href);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    function stop() {
+        if (transitioning)
+            throw new Error('Cannot stop the router during module mounting');
+        browser.document.removeEventListener('click', click);
+        browser.removeEventListener('popstate', popstate);
+        browser.removeEventListener('hashchange', popstate);
+        const old = active;
+        active = [];
+        root = undefined;
+        generation++;
+        fallback?.remove();
+        fallback = undefined;
+        const errors = [];
+        for (const item of old.reverse()) {
+            try {
+                item.instance.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length)
+            throw new AggregateError(errors, 'Router cleanup failed');
+    }
+    return {
+        location: { get: location.get }, navigate, stop,
+        start(parent) {
+            if (root)
+                throw new Error('Router is already started');
+            if (parent.ownerDocument !== browser.document)
+                throw new Error('Router root must belong to its Window');
+            const started = ++generation;
+            root = parent;
+            try {
+                render(new URL(browser.location.href));
+            }
+            catch (error) {
+                stop();
+                throw error;
+            }
+            browser.document.addEventListener('click', click);
+            browser.addEventListener('popstate', popstate);
+            browser.addEventListener('hashchange', popstate);
+            return () => { if (generation === started)
+                stop(); };
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAiB,MAAM,wBAAwB,CAAC;AAatE,SAAS,QAAQ,CAAC,IAAY,IAAc,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACrF,SAAS,QAAQ,CAAC,MAA8B,EAAE,YAAY,IAAI,GAAG,EAAU;IAC7E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACrG,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxE,IAAI,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACvF,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACjC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACrB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;YACvH,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBACxB,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,IAAI,EAAE,CAAC,CAAC;gBACvL,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC;IACxC,CAAC;AACH,CAAC;AACD,SAAS,IAAI,CAAC,MAA8B,EAAE,KAAe,EAAE,EAAE,GAAG,CAAC,EAAE,SAAiC,EAAE;IACxG,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACxC,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACxD,MAAM,IAAI,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YAClF,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAAC,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;QAChE,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;IACH,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;QAAC,IAAI,MAAM,GAAG,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;QAC3D,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBAAC,GAAG,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;gBAAC,MAAM;YAAC,CAAC;YACpG,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBAAC,OAAO,GAAG,KAAK,CAAC;gBAAC,MAAM;YAAC,CAAC;YACrD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;iBACjD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBAAC,OAAO,GAAG,KAAK,CAAC;gBAAC,MAAM;YAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QACjE,IAAI,QAAQ;YAAE,OAAO,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,CAAC;QAC1C,IAAI,MAAM,KAAK,KAAK,CAAC,MAAM;YAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvF,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7E,MAAM,QAAQ,GAAG,MAAM,CAAgB,YAAY,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACzF,IAAI,IAAsB,EAAE,MAAM,GAAa,EAAE,EAAE,QAAiC,CAAC;IACrF,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,cAAc,GAA4B,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACvH,SAAS,YAAY,CAAC,GAAQ,EAAE,MAA8B;QAC5D,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACpK,CAAC;IACD,SAAS,MAAM,CAAC,GAAQ;QACtB,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACjE,IAAI,aAAa;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACzF,aAAa,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC;YACH,IAAI,OAA4B,CAAC;YACjC,IAAI,CAAC;gBAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC;YAAC,CAAC;YACvF,OAAO,KAAK,EAAE,CAAC;gBAAC,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;oBAAE,MAAM,KAAK,CAAC;YAAC,CAAC;YAChE,IAAI,CAAC,OAAO,IAAI,cAAc;gBAAE,OAAO,GAAG,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;YACnF,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,GAAG,CAAC,CAAC;YACb,OAAO,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAE,CAAC,MAAM,KAAK,OAAO,CAAC,IAAI,CAAE,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAE,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAE,CAAC,MAAM,CAAC;gBAAE,IAAI,EAAE,CAAC;YACjM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,MAAM,GAAc,EAAE,CAAC;YAC7B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;gBAAC,IAAI,CAAC;oBAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;gBAAC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAAC,CAAC;YAAC,CAAC;YAChH,QAAQ,EAAE,MAAM,EAAE,CAAC;YAAC,QAAQ,GAAG,SAAS,CAAC;YACzC,IAAI,MAAM,CAAC,MAAM;gBAAE,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;YAC5E,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;oBAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC7B,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;oBACtD,IAAI,CAAC,MAAM;wBAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAO,CAAC,MAAM,CAAC,IAAI,uBAAuB,CAAC,CAAC;oBAC1F,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;oBACpI,MAAM,IAAI,GAAG,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC;oBACpC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtC,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACpB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;oBAAC,IAAI,CAAC;wBAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;oBAAC,CAAC;oBAAC,OAAO,YAAY,EAAE,CAAC;wBAAC,MAAM,CAAC,YAAY,CAAC,CAAC;oBAAC,CAAC;gBAAC,CAAC;gBACvH,MAAM,KAAK,CAAC;YACd,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBACpB,QAAQ,GAAG,IAAI,CAAC,aAAc,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;gBAClD,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAAC,QAAQ,CAAC,WAAW,GAAG,gBAAgB,CAAC;gBAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC/G,CAAC;YACD,KAAK,CAAC,GAAG,EAAE;gBACT,KAAK,MAAM,IAAI,IAAI,MAAM;oBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;gBAChF,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;YAChE,CAAC,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YAAC,aAAa,GAAG,KAAK,CAAC;QAAC,CAAC;IACtC,CAAC;IACD,SAAS,QAAQ,CAAC,EAAU,EAAE,aAAoC,EAAE;QAClE,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,EAAE,OAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,OAAQ,CAAC,QAAQ,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QACpK,IAAI,GAAG,CAAC,IAAI,KAAK,OAAQ,CAAC,QAAQ,CAAC,IAAI;YAAE,OAAO;QAChD,MAAM,CAAC,GAAG,CAAC,CAAC;QACZ,OAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1F,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,CAAC;YAAC,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,OAAQ,CAAC,QAAQ,CAAC,IAAI;gBAAE,MAAM,CAAC,IAAI,GAAG,CAAC,OAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAAC,CAAC;QACxG,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IAClC,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,CAAC,KAAiB,EAAE,EAAE;QAClC,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ;YAAE,OAAO;QAC7H,MAAM,MAAM,GAAG,KAAK,CAAC,MAAwB,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAE,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;YAAE,OAAO;QACjM,MAAM,IAAI,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO;QACjC,IAAI,GAAQ,CAAC;QACb,IAAI,CAAC;YAAC,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,OAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO;QAAC,CAAC;QACzE,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,OAAQ,CAAC,QAAQ,CAAC,MAAM;YAAE,OAAO;QACnG,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAQ,CAAC,QAAQ,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,OAAQ,CAAC,QAAQ,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI;YAAE,OAAO;QAC/G,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,IAAI,CAAC;YAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IAC9D,CAAC,CAAC;IACF,SAAS,IAAI;QACX,IAAI,aAAa;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACpF,OAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACtD,OAAQ,CAAC,mBAAmB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACnD,OAAQ,CAAC,mBAAmB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QACrD,MAAM,GAAG,GAAG,MAAM,CAAC;QAAC,MAAM,GAAG,EAAE,CAAC;QAAC,IAAI,GAAG,SAAS,CAAC;QAClD,UAAU,EAAE,CAAC;QACb,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,GAAG,SAAS,CAAC;QACzC,MAAM,MAAM,GAAc,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;YAAC,IAAI,CAAC;gBAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YAAC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAAC,CAAC;QAAC,CAAC;QAC5G,IAAI,MAAM,CAAC,MAAM;YAAE,MAAM,IAAI,cAAc,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI;QAC/C,KAAK,CAAC,MAAY;YAChB,IAAI,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACvD,IAAI,MAAM,CAAC,aAAa,KAAK,OAAQ,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;YACzG,MAAM,OAAO,GAAG,EAAE,UAAU,CAAC;YAC7B,IAAI,GAAG,MAAM,CAAC;YACd,IAAI,CAAC;gBAAC,MAAM,CAAC,IAAI,GAAG,CAAC,OAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAAC,CAAC;YAChD,OAAO,KAAK,EAAE,CAAC;gBAAC,IAAI,EAAE,CAAC;gBAAC,MAAM,KAAK,CAAC;YAAC,CAAC;YACtC,OAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACnD,OAAQ,CAAC,gBAAgB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;YAChD,OAAQ,CAAC,gBAAgB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;YAClD,OAAO,GAAG,EAAE,GAAG,IAAI,UAAU,KAAK,OAAO;gBAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { signal, batch, type Disposer } from '../reactivity/index.js';\nimport type { AppModule, MountedModule, RouteLocation } from '../hmvc/index.js';\nexport type { RouteLocation } from '../hmvc/index.js';\nexport interface RouteRecord { path: string; module: AppModule; children?: readonly RouteRecord[] }\nexport interface RouterOptions {\n  routes: readonly RouteRecord[];\n  window?: Window;\n  notFound?: AppModule;\n  onError?: (error: unknown) => void;\n}\ninterface Entry { record: RouteRecord; params: Record<string, string> }\ninterface Active extends Entry { instance: MountedModule }\n\nfunction segments(path: string): string[] { return path.split('/').filter(Boolean); }\nfunction validate(routes: readonly RouteRecord[], ancestors = new Set<string>()): void {\n  const siblings = new Set<string>();\n  for (const route of routes) {\n    if (/[?#]/.test(route.path)) throw new Error(`Route paths cannot contain query/hash: ${route.path}`);\n    const parts = segments(route.path);\n    const signature = parts.map(p => p.startsWith(':') ? ':' : p).join('/');\n    if (siblings.has(signature)) throw new Error(`Duplicate sibling route: ${route.path}`);\n    siblings.add(signature);\n    const names = new Set(ancestors);\n    parts.forEach((p, i) => {\n      if (p === '*' && (i !== parts.length - 1 || route.children?.length)) throw new Error('Wildcard must end a leaf route');\n      if (p.startsWith(':')) {\n        const name = p.slice(1);\n        if (!/^[a-zA-Z_][a-zA-Z\\d_]*$/.test(name) || names.has(name) || ['__proto__', 'prototype', 'constructor'].includes(name)) throw new Error(`Invalid or duplicate route param: ${name}`);\n        names.add(name);\n      }\n    });\n    validate(route.children ?? [], names);\n  }\n}\nfunction find(routes: readonly RouteRecord[], parts: string[], at = 0, params: Record<string, string> = {}): Entry[] | undefined {\n  const ordered = [...routes].sort((a, b) => {\n    const aa = segments(a.path), bb = segments(b.path);\n    for (let i = 0; i < Math.max(aa.length, bb.length); i++) {\n      const rank = (p?: string) => p === '*' ? 0 : p?.startsWith(':') ? 1 : p ? 2 : 0.5;\n      const diff = rank(bb[i]) - rank(aa[i]); if (diff) return diff;\n    }\n    return 0;\n  });\n  for (const record of ordered) {\n    const own = { ...params }; let cursor = at, matched = true;\n    for (const part of segments(record.path)) {\n      if (part === '*') { own['wildcard'] = parts.slice(cursor).join('/'); cursor = parts.length; break; }\n      const actual = parts[cursor++];\n      if (actual === undefined) { matched = false; break; }\n      if (part.startsWith(':')) own[part.slice(1)] = actual;\n      else if (part !== actual) { matched = false; break; }\n    }\n    if (!matched) continue;\n    const entry = { record, params: own };\n    const children = find(record.children ?? [], parts, cursor, own);\n    if (children) return [entry, ...children];\n    if (cursor === parts.length) return [entry];\n  }\n  return undefined;\n}\n\nexport function createRouter(options: RouterOptions) {\n  validate(options.routes);\n  const browser = options.window ?? (typeof window !== 'undefined' ? window : undefined);\n  if (!browser) throw new Error('createRouter requires a browser Window');\n  const report = options.onError ?? ((error: unknown) => console.error(error));\n  const location = signal<RouteLocation>(makeLocation(new URL(browser.location.href), {}));\n  let root: Node | undefined, active: Active[] = [], fallback: HTMLElement | undefined;\n  let transitioning = false;\n  let generation = 0;\n  const notFoundRecord: RouteRecord | undefined = options.notFound ? { path: '*', module: options.notFound } : undefined;\n  function makeLocation(url: URL, params: Record<string, string>): RouteLocation {\n    return Object.freeze({ url: new URL(url), pathname: url.pathname, params: Object.freeze({ ...params }), query: new URLSearchParams(url.search), hash: url.hash });\n  }\n  function render(url: URL): void {\n    if (!root) throw new Error('Start the router before navigating');\n    if (transitioning) throw new Error('Navigation during module mounting is not supported');\n    transitioning = true;\n    try {\n      let entries: Entry[] | undefined;\n      try { entries = find(options.routes, segments(url.pathname).map(decodeURIComponent)); }\n      catch (error) { if (!(error instanceof URIError)) throw error; }\n      if (!entries && notFoundRecord) entries = [{ record: notFoundRecord, params: {} }];\n      entries ??= [];\n      let keep = 0;\n      while (keep < active.length && keep < entries.length && active[keep]!.record === entries[keep]!.record && JSON.stringify(active[keep]!.params) === JSON.stringify(entries[keep]!.params)) keep++;\n      const removed = active.splice(keep);\n      const errors: unknown[] = [];\n      for (const item of removed.reverse()) { try { item.instance.dispose(); } catch (error) { errors.push(error); } }\n      fallback?.remove(); fallback = undefined;\n      if (errors.length) throw new AggregateError(errors, 'Route cleanup failed');\n      const added: Active[] = [];\n      try {\n        for (let i = keep; i < entries.length; i++) {\n          const entry = entries[i]!;\n          const parent = active.at(-1);\n          const outlet = parent ? parent.instance.outlet : root;\n          if (!outlet) throw new Error(`Parent module ${parent!.record.path} must render Outlet()`);\n          const instance = entry.record.module.attach(outlet, makeLocation(url, entry.params), parent?.instance.context, { onError: report });\n          const item = { ...entry, instance };\n          active.push(item); added.push(item);\n        }\n      } catch (error) {\n        active.splice(keep);\n        for (const item of added.reverse()) { try { item.instance.dispose(); } catch (cleanupError) { report(cleanupError); } }\n        throw error;\n      }\n      if (!entries.length) {\n        fallback = root.ownerDocument!.createElement('p');\n        fallback.setAttribute('role', 'status'); fallback.textContent = 'Page not found'; root.appendChild(fallback);\n      }\n      batch(() => {\n        for (const item of active) item.instance.update(makeLocation(url, item.params));\n        location.set(makeLocation(url, entries.at(-1)?.params ?? {}));\n      });\n    } finally { transitioning = false; }\n  }\n  function navigate(to: string, navigation: { replace?: boolean } = {}): void {\n    if (!root) throw new Error('Start the router before navigating');\n    const url = new URL(to, browser!.location.href);\n    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== browser!.location.origin) throw new Error('Router navigation requires a same-origin HTTP(S) URL');\n    if (url.href === browser!.location.href) return;\n    render(url);\n    browser!.history[navigation.replace ? 'replaceState' : 'pushState'](null, '', url.href);\n  }\n  const popstate = () => {\n    try { if (location.get().url.href !== browser!.location.href) render(new URL(browser!.location.href)); }\n    catch (error) { report(error); }\n  };\n  const click = (event: MouseEvent) => {\n    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;\n    const target = event.target as Element | null;\n    const anchor = target?.closest?.('a[href]');\n    if (!anchor || anchor.hasAttribute('download') || anchor.hasAttribute('data-hesh-reload') || (anchor.getAttribute('target') && anchor.getAttribute('target')!.toLowerCase() !== '_self')) return;\n    const href = anchor.getAttribute('href')!;\n    if (href.startsWith('#')) return;\n    let url: URL;\n    try { url = new URL(href, browser!.document.baseURI); } catch { return; }\n    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== browser!.location.origin) return;\n    if (url.pathname === browser!.location.pathname && url.search === browser!.location.search && url.hash) return;\n    event.preventDefault();\n    try { navigate(url.href); } catch (error) { report(error); }\n  };\n  function stop(): void {\n    if (transitioning) throw new Error('Cannot stop the router during module mounting');\n    browser!.document.removeEventListener('click', click);\n    browser!.removeEventListener('popstate', popstate);\n    browser!.removeEventListener('hashchange', popstate);\n    const old = active; active = []; root = undefined;\n    generation++;\n    fallback?.remove(); fallback = undefined;\n    const errors: unknown[] = [];\n    for (const item of old.reverse()) { try { item.instance.dispose(); } catch (error) { errors.push(error); } }\n    if (errors.length) throw new AggregateError(errors, 'Router cleanup failed');\n  }\n  return {\n    location: { get: location.get }, navigate, stop,\n    start(parent: Node): Disposer {\n      if (root) throw new Error('Router is already started');\n      if (parent.ownerDocument !== browser!.document) throw new Error('Router root must belong to its Window');\n      const started = ++generation;\n      root = parent;\n      try { render(new URL(browser!.location.href)); }\n      catch (error) { stop(); throw error; }\n      browser!.document.addEventListener('click', click);\n      browser!.addEventListener('popstate', popstate);\n      browser!.addEventListener('hashchange', popstate);\n      return () => { if (generation === started) stop(); };\n    }\n  };\n}\n"]}

package/dist/vite/index.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare function hesh(): Plugin;

package/dist/vite/index.js

@@ -0,0 +1,22 @@
+import { compile } from '../compiler/index.js';
+export function hesh() {
+    let production = false;
+    return {
+        name: 'heshjs', enforce: 'pre',
+        config() { return { appType: 'spa' }; },
+        configResolved(config) { production = config.command === 'build'; },
+        transform(source, id) {
+            if (!id.endsWith('.hesh'))
+                return;
+            const result = compile(source, { filename: id, development: !production });
+            return { code: result.code, map: null };
+        },
+        handleHotUpdate(context) {
+            if (context.file.endsWith('.hesh')) {
+                context.server.ws.send({ type: 'full-reload' });
+                return [];
+            }
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,MAAM,UAAU,IAAI;IAClB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,OAAO;QACL,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK;QAC9B,MAAM,KAAK,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QACvC,cAAc,CAAC,MAAM,IAAI,UAAU,GAAG,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC;QACnE,SAAS,CAAC,MAAM,EAAE,EAAE;YAClB,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,OAAO;YAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC;YAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;QAC1C,CAAC;QACD,eAAe,CAAC,OAAO;YACrB,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAAC,OAAO,EAAE,CAAC;YAAC,CAAC;QACrG,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { Plugin } from 'vite';\nimport { compile } from '../compiler/index.js';\nexport function hesh(): Plugin {\n  let production = false;\n  return {\n    name: 'heshjs', enforce: 'pre',\n    config() { return { appType: 'spa' }; },\n    configResolved(config) { production = config.command === 'build'; },\n    transform(source, id) {\n      if (!id.endsWith('.hesh')) return;\n      const result = compile(source, { filename: id, development: !production });\n      return { code: result.code, map: null };\n    },\n    handleHotUpdate(context) {\n      if (context.file.endsWith('.hesh')) { context.server.ws.send({ type: 'full-reload' }); return []; }\n    }\n  };\n}\n"]}

package/docs/grammar.md

@@ -0,0 +1,65 @@
+# Milestone 1 language (v0.1)
+
+The grammar is deliberately smaller than the product roadmap. Source is UTF-8.
+Whitespace and JavaScript comments separate tokens. Identifiers follow JavaScript
+identifier rules. Strings and numbers follow JavaScript lexical rules.
+
+```ebnf
+module      = { importDecl | view } ;
+view        = [ "export" ], [ "default" ], "view", Identifier, "{", { statement }, "}" ;
+statement   = state | constant | element ;
+state       = Identifier, "=", expression, ";" ;
+constant    = "const", Identifier, "=", expression, ";" ;
+element     = Identifier, "(", [ expression, [ ",", [ "async" ], handler ] ], ")",
+              ( ";" | "{", { element }, "}", [ ";" ] ) ;
+handler     = "{", { javascriptStatement }, "}" ;
+```
+
+`importDecl` is an ESM import. Expressions and event bodies are parsed with
+TypeScript's JavaScript parser, never evaluated by the compiler. Type annotations
+inside `.hesh` are rejected; use `.ts` modules for typed logic. Imports must precede
+views. Each file may export multiple named views and at most one default view.
+
+`count = 0;` declares component-local state; a second declaration is an error.
+State is a shallow signal: assignment and `++`, `--`, compound assignments trigger
+updates. `items.push(x)` and `object.field = x` do **not** notify; assign a new array
+or object instead. Constants are immutable bindings, not deeply frozen objects.
+Initializers execute once per mount in declaration order. There is no derived
+declaration yet. State references in text expressions become tracked reads.
+
+`button("+", { count++; });` has an explicit click block inside its argument list.
+A block after `)` contains children, eliminating event/child ambiguity. Event code
+is ordinary JavaScript, with `event` available, lexical local variables, functions,
+and optional `async`. Synchronous and asynchronous errors go to mount's `onError`
+callback (default: `console.error`). Cleanup removes listeners. Async continuations
+are not canceled on unmount; applications must cancel their own async work.
+
+Double-quoted strings can interpolate `{expression}`; `"Count: {count}"` becomes
+a sequence of text parts. Braces inside strings use `\{` and `\}`. Interpolation
+expressions may contain nested braces, strings and comments. Single quotes and
+backtick literals use standard JavaScript semantics, without Hesh interpolation.
+The initial lexical envelope does not support backtick `${...}` substitutions or
+regular-expression literals; move these into imported JS/TS
+helpers. Double-quoted Hesh strings support ordinary single-character escapes;
+use single quotes for Unicode/hex escape sequences. Destructuring assignment and
+logical compound assignment to component bindings are rejected. For `for…of` or
+`for…in`, declare a local iteration variable and assign state inside the body.
+
+Lowercase names identify native HTML elements. `text` maps to `span`, `card`,
+`row`, `stack`, `grid` to `div`, `image` to `img`, and `link` to `a`. Use a native
+element name for anything else; custom elements use `element("x-widget")` only in
+the public DOM API, not yet in `.hesh`. Unknown uppercase references are errors;
+uppercase view calls mount a locally declared or imported component, with no props
+in this milestone. Views have no parameter syntax yet. Children of a component
+call and click blocks on components are rejected rather than silently discarded.
+
+`input(name);` binds a writable state identifier bidirectionally using `input`
+events and its string value. `image(url);` binds a safe `src`. Other values become
+text via `String(value ?? "")`, never HTML. Generic attributes are available in the
+DOM API; declarative attribute syntax is deferred. Event closures may shadow state
+identifiers; lexical resolution preserves those local bindings. Globals and imports
+retain ordinary JavaScript behavior. Unknown unbound names are compile errors.
+
+No conditionals, keyed lists, styles, props, TypeScript syntax, slots, or top-level
+JavaScript statements are accepted by this grammar. Future syntax requires a
+versioned grammar change and tests. Unsupported input produces source diagnostics.

package/docs/hmvc.md

@@ -0,0 +1,134 @@
+# Building an HMVC single-page application
+
+Requires HeshJS 0.2.0. New JavaScript/TypeScript projects use this structure:
+
+```text
+src/
+  main.js                 # starts the router (.ts for TypeScript)
+  app.js                  # explicit route tree
+  modules/
+    shell/
+      model.js
+      controller.js
+      View.hesh
+      Navigation.js
+      module.js
+    home/
+      model.js
+      controller.js
+      View.hesh
+      module.js
+      modules/
+        detail/           # independent nested MVC triad
+          model.js
+          controller.js
+          View.hesh
+          module.js
+    about/                # same MVC structure
+    notFound/             # same MVC structure
+```
+
+This is an application architecture. Compiler, parser and runtime packages stay
+separate infrastructure packages; they are not model/view/controller folders.
+
+## Define a module
+
+```js
+// model.js
+import { signal } from '@heshammesalam/heshjs';
+export const createModel = () => ({ count: signal(0) });
+
+// controller.js
+export const createController = (model, context) => ({
+  count: model.count,
+  increment: () => model.count.set(model.count.get() + 1),
+  id: () => context.route.get().params.id
+});
+```
+
+```hesh
+// View.hesh
+import { useController, Outlet } from '@heshammesalam/heshjs/hmvc';
+export default view Counter {
+  const controller = useController();
+  h1("Count: {controller.count.get()}");
+  button("+", { controller.increment(); });
+  Outlet();
+}
+```
+
+```js
+// module.js
+import { defineModule } from '@heshammesalam/heshjs/hmvc';
+import { createModel } from './model.js';
+import { createController } from './controller.js';
+import View from './View.hesh';
+export const counterModule = defineModule({ model: createModel, controller: createController, view: View });
+```
+
+Factories run once per mounted instance. Use `onCleanup` from HeshJS in factories
+to dispose your subscriptions/resources. Do not call factories at import time if
+their state should be instance-local. `useController`, `useModel` and `useModule`
+are synchronous mount-time accessors. Capture the result in your view; events use
+the captured controller. A controller receives `context.parent` for explicit access
+to the parent module's model/controller. No global store or dependency injection
+container is required. Generic `useController<MyController>()` is available in TS
+view/helper modules, while `.hesh` remains JavaScript without full type checking.
+
+## Declare the route hierarchy
+
+```js
+import { createRouter } from '@heshammesalam/heshjs/router';
+// Import the modules declared by your application.
+export const router = createRouter({ routes: [
+  { path: '/', module: shellModule, children: [
+    { path: '', module: homeModule, children: [
+      { path: 'counter/:id', module: detailModule }
+    ] },
+    { path: 'about', module: aboutModule },
+    { path: '*', module: notFoundModule }
+  ] }
+] });
+
+const dispose = router.start(document.querySelector('#app'));
+router.navigate('/counter/42?from=home');
+router.navigate('/about', { replace: true });
+// dispose() or router.stop() releases all modules and router listeners.
+```
+
+Parents with child routes must render one `Outlet()`. Layout state and DOM stay
+mounted when navigating between their children. Leaving a parent resets its state
+on the next visit. Changes to that module's path parameters recreate the module
+and descendants. Query/hash changes update its reactive `context.route.get()`
+without recreating matching instances. A parent's params contain only parameters
+matched up to that parent; `router.location.get()` contains the deepest match.
+
+Ordinary same-origin anchor clicks update browser history without document reload.
+Use DOM APIs for anchor attributes for now; declarative attribute syntax is not yet
+part of Hesh grammar. The starter's Navigation component is an example. External,
+download, modifier-key and non-self-target links retain browser behavior. Set
+`data-hesh-reload` on an anchor to opt out. Back/forward and initial deep URLs work.
+There is no base-path option yet; deploy at the origin root or define prefixed routes.
+
+Unmatched URLs use `notFound`, a `*` route, or a safe built-in text message.
+`onError` receives navigation/event errors. Programmatic navigation throws errors
+to its caller. Setup must be synchronous. On setup failure new instances are
+disposed, but previously removed children are not restored. Guards, lazy loading,
+async controllers, server authorization and SSR are not implemented.
+
+## Serve deep links in production
+
+Vite dev/preview use SPA fallback. Production hosts must return index.html for
+application paths. The client router cannot fix an HTTP 404 served before JS loads.
+
+For nginx, inside your site's configuration:
+
+```nginx
+location / {
+  try_files $uri $uri/ /index.html;
+}
+```
+
+The scaffold includes `public/_redirects` containing `/* /index.html 200` for hosts
+that support that convention. Configure asset/API routes separately on your host.
+This project does not modify your deployment server automatically.

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@heshammesalam/heshjs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "An experimental independent reactive UI framework with brace-based .hesh components",
+  "author": "Hesham",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/heshjs/index.js",
+  "types": "./dist/heshjs/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/heshjs/index.d.ts", "import": "./dist/heshjs/index.js" },
+    "./reactivity": { "types": "./dist/reactivity/index.d.ts", "import": "./dist/reactivity/index.js" },
+    "./dom": { "types": "./dist/dom/index.d.ts", "import": "./dist/dom/index.js" },
+    "./parser": { "types": "./dist/parser/index.d.ts", "import": "./dist/parser/index.js" },
+    "./compiler": { "types": "./dist/compiler/index.d.ts", "import": "./dist/compiler/index.js" },
+    "./vite": { "types": "./dist/vite/index.d.ts", "import": "./dist/vite/index.js" },
+    "./router": { "types": "./dist/router/index.d.ts", "import": "./dist/router/index.js" },
+    "./hmvc": { "types": "./dist/hmvc/index.d.ts", "import": "./dist/hmvc/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "src", "docs", "README.md"],
+  "engines": { "node": ">=22.12.0" },
+  "dependencies": { "typescript": "~5.9.3" },
+  "peerDependencies": { "vite": "^7.2.2" },
+  "peerDependenciesMeta": { "vite": { "optional": true } },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" }
+}
+