@madojs/mado 0.5.0

package/dist/src/html/template.js

@@ -0,0 +1,119 @@
+/**
+ * Template instantiation + public `html\`\`` tag + `render()`.
+ *
+ * Data flow:
+ *   html`...`              → TemplateResult { strings, values }
+ *   parseTemplate(strings) → ParsedTemplate { template, bindings }   (cached by strings)
+ *   instantiate(result)    → InstantiatedTemplate { fragment, nodes, update, dispose }
+ *   render(result, host)   → clones or reuses instance in host
+ *
+ * Only the glue lives here: parser and bindings are in neighbour files.
+ */
+import { warnOnce } from "../diagnostics.js";
+import { parseTemplate, resolvePath, } from "./parser.js";
+import { bindAttr, bindChild, createChildState, disposeChildState, } from "./bindings.js";
+/**
+ * `html\`<div>${value}</div>\`` → template descriptor.
+ *
+ * By itself renders and parses NOTHING — this simply captures
+ * { strings, values } from the tagged-template literal. The heavy work
+ * (parsing + cloning) happens on the first `render()` /
+ * `instantiate()` call and is cached by `strings` identity.
+ */
+export function html(strings, ...values) {
+    return { _mado: true, strings, values };
+}
+/**
+ * Create a ready template instance: clones the pre-parsed template,
+ * resolves all BindingSpec → concrete DOM nodes of the clone, binds
+ * initial values. The returned object is self-contained: update(values)
+ * patches only what actually changed, dispose() cleans up effects
+ * and removes nodes from the DOM.
+ *
+ * Exported (not only used from render()) so that
+ * keyed `each` reconciliation can manage instance lifetimes directly.
+ */
+export function instantiate(result) {
+    const parsed = parseTemplate(result.strings);
+    const fragment = parsed.template.content.cloneNode(true);
+    const disposers = [];
+    const childStates = new Map();
+    const attrBound = new Map();
+    // Resolve all BindingSpec.path → concrete nodes of the cloned
+    // fragment. This is done ONCE, in the instance creation phase.
+    for (const b of parsed.bindings) {
+        if (b.type === "child") {
+            const parent = resolvePath(fragment, b.path);
+            const placeholder = parent.childNodes[b.childIndex];
+            childStates.set(b.id, createChildState(placeholder));
+        }
+        else {
+            const el = resolvePath(fragment, b.path);
+            attrBound.set(b.id, { el, spec: b });
+        }
+    }
+    const update = (values) => {
+        // Before each update unsubscribe from the previous pass's subscriptions.
+        // This is needed because one of the values might have been a signal
+        // but now is not (or vice versa), and we need a fresh re-subscribe.
+        for (const d of disposers.splice(0))
+            d();
+        for (const b of parsed.bindings) {
+            if (b.type === "child") {
+                const st = childStates.get(b.id);
+                bindChild(st, values[b.slot], disposers, instantiate);
+            }
+            else {
+                const ab = attrBound.get(b.id);
+                bindAttr(ab.el, ab.spec, values, disposers);
+            }
+        }
+    };
+    update(result.values);
+    const nodes = [...fragment.childNodes];
+    return {
+        fragment,
+        nodes,
+        update,
+        dispose() {
+            for (const d of disposers.splice(0))
+                d();
+            for (const st of childStates.values())
+                disposeChildState(st);
+            for (const n of nodes)
+                n.parentNode?.removeChild(n);
+        },
+        _strings: result.strings,
+    };
+}
+// ---------- Public render ----------
+const rendered = new WeakMap();
+/**
+ * Render a TemplateResult into a container.
+ *
+ * Semantics:
+ *   - first call → instantiate + appendChild;
+ *   - repeated call with the same tagged literal (same strings identity) →
+ *     update(values), DOM is not recreated;
+ *   - repeated call with a different literal → dispose old + new instantiate.
+ *
+ * Container can be either an Element or a ShadowRoot (used
+ * in component() for rendering into a shadow tree).
+ */
+export function render(result, container) {
+    const existing = rendered.get(container);
+    if (existing && existing.nodes[0]?.parentNode === container) {
+        if (existing._strings === result.strings) {
+            existing.update(result.values);
+            return;
+        }
+        existing.dispose();
+    }
+    if (!existing && container.childNodes.length > 0) {
+        warnOnce("render-unmanaged-dom", "render() called on a container with existing DOM that was not created by Mado. It will remain alongside the new render output.");
+    }
+    const inst = instantiate(result);
+    container.appendChild(inst.fragment);
+    rendered.set(container, inst);
+}
+//# sourceMappingURL=template.js.map

package/dist/src/html/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/html/template.ts"],"names":[],"mappings":"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"}

package/dist/src/html.d.ts

@@ -0,0 +1,16 @@
+/**
+ * html module entry point. The implementation lives in `./html/`:
+ *
+ *   ./html/parser.ts          — state-machine tokenizer + ParsedTemplate cache
+ *   ./html/bindings.ts        — bindChild / bindAttr + keyed each
+ *   ./html/template.ts        — html`` tag, instantiate(), render()
+ *   ./html/template-types.ts  — shared types (TemplateResult, InstantiatedTemplate)
+ *
+ * This file keeps compatibility for internal imports from `"./html.js"`.
+ * The public barrel (`src/index.ts`) also goes through this file.
+ *
+ * If the shell is ever removed, switch imports to `./html/template.js`.
+ * For now it has no runtime cost.
+ */
+export { html, render, instantiate } from "./html/template.js";
+export type { TemplateResult } from "./html/template-types.js";

package/dist/src/html.js

@@ -0,0 +1,16 @@
+/**
+ * html module entry point. The implementation lives in `./html/`:
+ *
+ *   ./html/parser.ts          — state-machine tokenizer + ParsedTemplate cache
+ *   ./html/bindings.ts        — bindChild / bindAttr + keyed each
+ *   ./html/template.ts        — html`` tag, instantiate(), render()
+ *   ./html/template-types.ts  — shared types (TemplateResult, InstantiatedTemplate)
+ *
+ * This file keeps compatibility for internal imports from `"./html.js"`.
+ * The public barrel (`src/index.ts`) also goes through this file.
+ *
+ * If the shell is ever removed, switch imports to `./html/template.js`.
+ * For now it has no runtime cost.
+ */
+export { html, render, instantiate } from "./html/template.js";
+//# sourceMappingURL=html.js.map

package/dist/src/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Mado — public API.
+ *
+ * Import everything from one place:
+ *   import { signal, computed, effect, component, html, router } from '@madojs/mado';
+ *
+ * In the browser: connected via <script type="importmap">.
+ * In Node: via `tsconfig.paths` (resolves to "./src/index.ts").
+ */
+export { signal, computed, effect, untracked, batch, flushSync, } from "./signal.js";
+export type { Signal, Computed, Disposer } from "./signal.js";
+export { html, render } from "./html.js";
+export type { TemplateResult } from "./html.js";
+export { each, list } from "./each.js";
+export { component } from "./component.js";
+export type { ComponentContext, ComponentOptions, SetupFn, StyleInput, } from "./component.js";
+export { css, cssVars, adopt, scopeStyles } from "./css.js";
+export type { CSSResult } from "./css.js";
+export { router, routes, queryParam, prefetchPath, navigate, } from "./router.js";
+export type { RouterApi, RouteHandler, RouteParams, Routes, RoutesMap, RoutesOptions, QueryParam, QuerySignal, } from "./router.js";
+export { page, nested, isPage, isNested } from "./page.js";
+export type { Page, PageContext, PageData, RouteEntry, NestedRoutes, HeadMeta, BakeConfig, } from "./page.js";
+export { applyHead } from "./head.js";
+export { resource, mutation, invalidate, jsonFetcher, HttpError, } from "./resource.js";
+export type { Resource, ResourceOptions, Mutation, MutationOptions, } from "./resource.js";
+export { useForm } from "./forms.js";
+export type { FormApi, FormValues, FormErrors, FieldSchema, Schema, UseFormOptions, } from "./forms.js";
+export { createContext, provide, inject } from "./context.js";
+export type { Context } from "./context.js";
+export { persisted } from "./persisted.js";
+export type { PersistedOptions, PersistedSignal } from "./persisted.js";
+export { lazy } from "./lazy.js";
+export type { LazyOptions } from "./lazy.js";
+export { getCurrentLifecycle, runInLifecycle, createLifecycle, } from "./lifecycle.js";
+export type { Lifecycle, LifecycleHandle } from "./lifecycle.js";

package/dist/src/index.js

@@ -0,0 +1,39 @@
+/**
+ * Mado — public API.
+ *
+ * Import everything from one place:
+ *   import { signal, computed, effect, component, html, router } from '@madojs/mado';
+ *
+ * In the browser: connected via <script type="importmap">.
+ * In Node: via `tsconfig.paths` (resolves to "./src/index.ts").
+ */
+// --- core ---
+export { signal, computed, effect, untracked, batch, flushSync, } from "./signal.js";
+// --- rendering ---
+export { html, render } from "./html.js";
+export { each, list } from "./each.js";
+// --- components ---
+export { component } from "./component.js";
+// --- styles ---
+export { css, cssVars, adopt, scopeStyles } from "./css.js";
+// --- routing ---
+export { router, routes, queryParam, prefetchPath, navigate, } from "./router.js";
+export { page, nested, isPage, isNested } from "./page.js";
+export { applyHead } from "./head.js";
+// --- data ---
+export { resource, mutation, invalidate, jsonFetcher, HttpError, } from "./resource.js";
+// --- forms ---
+export { useForm } from "./forms.js";
+// --- DI ---
+export { createContext, provide, inject } from "./context.js";
+// --- persistence ---
+export { persisted } from "./persisted.js";
+// --- lazy ---
+export { lazy } from "./lazy.js";
+// --- lifecycle (advanced API) ---
+//
+// Normally you don't need this: inside component() the lifecycle is created
+// automatically. Only needed if you want to use resource() or
+// other helpers outside a component and still get cleanup.
+export { getCurrentLifecycle, runInLifecycle, createLifecycle, } from "./lifecycle.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAe;AACf,OAAO,EACL,MAAM,EACN,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,SAAS,GACV,MAAM,aAAa,CAAC;AAGrB,oBAAoB;AACpB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEvC,qBAAqB;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQ3C,iBAAiB;AACjB,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5D,kBAAkB;AAClB,OAAO,EACL,MAAM,EACN,MAAM,EACN,UAAU,EACV,YAAY,EACZ,QAAQ,GACT,MAAM,aAAa,CAAC;AAYrB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAW3D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,eAAe;AACf,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,SAAS,GACV,MAAM,eAAe,CAAC;AAQvB,gBAAgB;AAChB,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAUrC,aAAa;AACb,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG9D,sBAAsB;AACtB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,eAAe;AACf,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,mCAAmC;AACnC,EAAE;AACF,4EAA4E;AAC5E,8DAA8D;AAC9D,2DAA2D;AAC3D,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,gBAAgB,CAAC"}

package/dist/src/lazy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * lazy() — deferred module loading with a reactive placeholder.
+ *
+ * Why: heavy components (charts, code editors, modals)
+ * don't need to be loaded on startup. lazy() gives a TemplateResult function
+ * that returns a fallback until loaded, then the real template.
+ *
+ *   const Chart = lazy(
+ *     () => import('./components/chart.js'),
+ *     { fallback: () => html`<x-spinner/>` },
+ *   );
+ *
+ *   html`<div>${Chart({ data })}</div>`
+ *
+ * Module contract: must default-export a function
+ *   (props) => TemplateResult.
+ *
+ * Loading is cached (one import() per loader reference).
+ */
+import { type TemplateResult } from "./html.js";
+export interface LazyOptions<P> {
+    /** What to show while the module is loading. */
+    fallback?: (props: P) => TemplateResult;
+    /** What to show if the import failed. Default — empty string. */
+    error?: (err: Error, props: P) => TemplateResult;
+}
+type Renderer<P> = (props: P) => TemplateResult;
+/**
+ * Create a lazy component.
+ * Takes a dynamic import, returns a render function.
+ *
+ *   const Modal = lazy(() => import('./modal.js'));
+ *   html`${open() ? Modal({ onClose }) : null}`
+ */
+export declare function lazy<P = unknown>(loader: () => Promise<{
+    default: Renderer<P>;
+}>, options?: LazyOptions<P>): (props: P) => TemplateResult;
+export {};

package/dist/src/lazy.js

@@ -0,0 +1,73 @@
+/**
+ * lazy() — deferred module loading with a reactive placeholder.
+ *
+ * Why: heavy components (charts, code editors, modals)
+ * don't need to be loaded on startup. lazy() gives a TemplateResult function
+ * that returns a fallback until loaded, then the real template.
+ *
+ *   const Chart = lazy(
+ *     () => import('./components/chart.js'),
+ *     { fallback: () => html`<x-spinner/>` },
+ *   );
+ *
+ *   html`<div>${Chart({ data })}</div>`
+ *
+ * Module contract: must default-export a function
+ *   (props) => TemplateResult.
+ *
+ * Loading is cached (one import() per loader reference).
+ */
+import { signal } from "./signal.js";
+import { html } from "./html.js";
+const cache = new WeakMap();
+/**
+ * Create a lazy component.
+ * Takes a dynamic import, returns a render function.
+ *
+ *   const Modal = lazy(() => import('./modal.js'));
+ *   html`${open() ? Modal({ onClose }) : null}`
+ */
+export function lazy(loader, options = {}) {
+    return (props) => {
+        // One signal trigger per call instance; the html binder will resubscribe
+        // when the state changes.
+        const trig = signal(0);
+        const state = ensureLoaded(loader);
+        if (state.state === "loading") {
+            // subscribe: when state transitions to ready/error, trigger trig
+            const wait = waitFor(loader);
+            wait.then(() => trig.update((n) => n + 1), () => trig.update((n) => n + 1));
+        }
+        return html `${() => {
+            trig(); // subscription
+            const s = ensureLoaded(loader);
+            if (s.state === "ready" && s.renderer)
+                return s.renderer(props);
+            if (s.state === "error" && s.err) {
+                return options.error?.(s.err, props) ?? "";
+            }
+            return options.fallback?.(props) ?? "";
+        }}`;
+    };
+}
+function ensureLoaded(loader) {
+    const existing = cache.get(loader);
+    if (existing)
+        return existing;
+    const fresh = { state: "loading" };
+    cache.set(loader, fresh);
+    loader().then((mod) => {
+        fresh.state = "ready";
+        fresh.renderer = mod.default;
+    }, (err) => {
+        fresh.state = "error";
+        fresh.err = err instanceof Error ? err : new Error(String(err));
+    });
+    return fresh;
+}
+function waitFor(loader) {
+    // return the same Promise as ensureLoaded — otherwise we'd create a new one.
+    // The browser actually caches the same module, so the second call returns instantly.
+    return loader();
+}
+//# sourceMappingURL=lazy.js.map

package/dist/src/lazy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../src/lazy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,IAAI,EAAuB,MAAM,WAAW,CAAC;AAiBtD,MAAM,KAAK,GAAG,IAAI,OAAO,EAA8B,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAClB,MAA+C,EAC/C,UAA0B,EAAE;IAE5B,OAAO,CAAC,KAAQ,EAAE,EAAE;QAClB,yEAAyE;QACzE,0BAA0B;QAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,YAAY,CAAI,MAAM,CAAC,CAAC;QAEtC,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC9B,iEAAiE;YACjE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7B,IAAI,CAAC,IAAI,CACP,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAC/B,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAChC,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAA,GAAG,GAAG,EAAE;YACjB,IAAI,EAAE,CAAC,CAAC,eAAe;YACvB,MAAM,CAAC,GAAG,YAAY,CAAI,MAAM,CAAC,CAAC;YAClC,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ;gBAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAChE,IAAI,CAAC,CAAC,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;gBACjC,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YAC7C,CAAC;YACD,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACzC,CAAC,EAAE,CAAC;IACN,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CACnB,MAA+C;IAE/C,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAA2B,CAEzC,CAAC;IACd,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,KAAK,GAAiB,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACjD,KAAK,CAAC,GAAG,CAAC,MAA2B,EAAE,KAA2B,CAAC,CAAC;IACpE,MAAM,EAAE,CAAC,IAAI,CACX,CAAC,GAAG,EAAE,EAAE;QACN,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;QACtB,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC;IAC/B,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;QACf,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;QACtB,KAAK,CAAC,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,CAAC,CACF,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,OAAO,CACd,MAA+C;IAE/C,6EAA6E;IAC7E,qFAAqF;IACrF,OAAO,MAAM,EAAE,CAAC;AAClB,CAAC"}

package/dist/src/lifecycle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Lifecycle context for auto-cleanup of resources inside a component.
+ *
+ * Core idea: when a component-setup runs, we push the current
+ * "lifecycle" — an object with onDispose() — onto a module-local stack.
+ * Any function like resource() that creates long-lived subscriptions
+ * (timers, listeners, network subscriptions) can call getCurrentLifecycle()
+ * and register its own cleanup.
+ *
+ * This avoids leaks on component unmount — without explicitly threading
+ * ComponentContext into every helper.
+ *
+ * Usage:
+ *
+ *   // in component.ts
+ *   runInLifecycle(myLifecycle, () => setup(ctx));
+ *
+ *   // in resource.ts
+ *   const lc = getCurrentLifecycle();
+ *   if (lc) lc.onDispose(() => abort.abort());
+ *   else console.warn('[mado] resource() outside component — cleanup must be manual');
+ */
+import type { Disposer } from "./signal.js";
+export interface Lifecycle {
+    /** Register a cleanup function. Called when the lifecycle is disposed. */
+    onDispose(fn: Disposer): void;
+}
+/**
+ * Return the currently active lifecycle, or null if code runs
+ * outside a component setup.
+ */
+export declare function getCurrentLifecycle(): Lifecycle | null;
+/**
+ * Execute fn with the given lifecycle set. Supports nesting:
+ * the previous lifecycle is restored after fn returns (including exceptions).
+ */
+export declare function runInLifecycle<T>(lc: Lifecycle, fn: () => T): T;
+/**
+ * Create a new lifecycle. Returns the Lifecycle interface and a
+ * dispose() method that runs all registered cleanup callbacks.
+ */
+export interface LifecycleHandle extends Lifecycle {
+    dispose(): void;
+}
+export declare function createLifecycle(): LifecycleHandle;

package/dist/src/lifecycle.js

@@ -0,0 +1,66 @@
+/**
+ * Lifecycle context for auto-cleanup of resources inside a component.
+ *
+ * Core idea: when a component-setup runs, we push the current
+ * "lifecycle" — an object with onDispose() — onto a module-local stack.
+ * Any function like resource() that creates long-lived subscriptions
+ * (timers, listeners, network subscriptions) can call getCurrentLifecycle()
+ * and register its own cleanup.
+ *
+ * This avoids leaks on component unmount — without explicitly threading
+ * ComponentContext into every helper.
+ *
+ * Usage:
+ *
+ *   // in component.ts
+ *   runInLifecycle(myLifecycle, () => setup(ctx));
+ *
+ *   // in resource.ts
+ *   const lc = getCurrentLifecycle();
+ *   if (lc) lc.onDispose(() => abort.abort());
+ *   else console.warn('[mado] resource() outside component — cleanup must be manual');
+ */
+let current = null;
+/**
+ * Return the currently active lifecycle, or null if code runs
+ * outside a component setup.
+ */
+export function getCurrentLifecycle() {
+    return current;
+}
+/**
+ * Execute fn with the given lifecycle set. Supports nesting:
+ * the previous lifecycle is restored after fn returns (including exceptions).
+ */
+export function runInLifecycle(lc, fn) {
+    const prev = current;
+    current = lc;
+    try {
+        return fn();
+    }
+    finally {
+        current = prev;
+    }
+}
+export function createLifecycle() {
+    const disposers = [];
+    return {
+        onDispose(fn) {
+            disposers.push(fn);
+        },
+        dispose() {
+            // reverse order — LIFO, like a stack
+            for (let i = disposers.length - 1; i >= 0; i--) {
+                try {
+                    disposers[i]();
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.error("[mado] cleanup threw:", err);
+                }
+            }
+            disposers.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/src/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH,IAAI,OAAO,GAAqB,IAAI,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAI,EAAa,EAAE,EAAW;IAC1D,MAAM,IAAI,GAAG,OAAO,CAAC;IACrB,OAAO,GAAG,EAAE,CAAC;IACb,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;AACH,CAAC;AAUD,MAAM,UAAU,eAAe;IAC7B,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,OAAO;QACL,SAAS,CAAC,EAAE;YACV,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;QACD,OAAO;YACL,qCAAqC;YACrC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/C,IAAI,CAAC;oBACH,SAAS,CAAC,CAAC,CAAE,EAAE,CAAC;gBAClB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,sCAAsC;oBACtC,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;YACD,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/page.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Page contract — a uniform format for describing a page.
+ *
+ *   // pages/user-profile.ts
+ *   import { page, html, resource, jsonFetcher } from '@madojs/mado';
+ *
+ *   export default page({
+ *     title: ({ id }) => `User #${id}`,
+ *     load:  ({ id }) => resource(() => `/api/users/${id}`, jsonFetcher()),
+ *     view:  ({ params, data }) => html`
+ *       <h1>${() => data?.data()?.name ?? '\u2026'}</h1>
+ *     `,
+ *   });
+ *
+ *   // routes.ts
+ *   import { routes } from '@madojs/mado';
+ *
+ *   export default routes({
+ *     '/users/:id': () => import('./pages/user-profile.js'),
+ *   });
+ *
+ * The contract is strict: exactly three slots — title / load / view.
+ * If a page exports something other than Page — tsc will stop it before build.
+ * "One right way" — as in Rust: fewer branches, fewer bugs.
+ */
+import type { TemplateResult } from "./html.js";
+/** Route params (values from :placeholders). */
+export type RouteParams = Record<string, string>;
+/**
+ * Loaded data. If load returned a Resource — this is `Resource<T>`,
+ * otherwise — a plain value. The view decides what to do with it.
+ */
+export type PageData<D> = D;
+export interface PageContext<P extends RouteParams, D> {
+    /** URL parameters. */
+    params: P;
+    /** Result of load() — usually Resource<T> with data/error/loading. */
+    data: D;
+    /** Current path (as a signal function). */
+    path: () => string;
+    /**
+     * Child view (for layout components).
+     * For regular pages always null.
+     */
+    child: TemplateResult | null;
+}
+/**
+ * Metadata for <head>. Baked into HTML at bake(), and in SPA runtime
+ * updated on the fly on route changes.
+ */
+export interface HeadMeta {
+    /** If set — overrides page.title. */
+    title?: string;
+    description?: string;
+    /** Canonical URL — important for SEO with duplicate content. */
+    canonical?: string;
+    /** OpenGraph for social networks. */
+    og?: {
+        title?: string;
+        description?: string;
+        image?: string;
+        type?: string;
+        url?: string;
+    };
+    /** Twitter Cards (inherits og.* if not set). */
+    twitter?: {
+        card?: "summary" | "summary_large_image";
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+    /** Arbitrary meta tags: { name: 'robots', content: 'index,follow' } */
+    meta?: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+    /** Arbitrary link tags: { rel: 'alternate', href: '/en/...' } */
+    link?: Array<{
+        rel: string;
+        href: string;
+        hreflang?: string;
+    }>;
+    /** JSON-LD structure (Schema.org). Will be inserted as <script type="application/ld+json">. */
+    jsonLd?: unknown;
+}
+/**
+ * Bake configuration: gives the build script enough information
+ * to pre-render static HTML for all instances of a page.
+ */
+export interface BakeConfig<P extends RouteParams, D> {
+    /**
+     * List of all params for which to bake a page.
+     * Return a ready array (may fetch from API).
+     */
+    paths: () => Promise<P[]> | P[];
+    /**
+     * Data for specific params. Must be JSON-serialisable —
+     * it is also embedded in the HTML inside
+     * `<script type="application/json" id="bake">`
+     * and used as `initialData` during hydration.
+     */
+    data: (params: P) => Promise<D> | D;
+    /**
+     * How many seconds before the data is considered stale (for CDN/edge cache).
+     * Optional. Metadata only.
+     */
+    revalidate?: number;
+}
+export interface Page<P extends RouteParams = RouteParams, D = unknown> {
+    readonly _page: true;
+    title?: string | ((params: P) => string);
+    load?: (params: P, baked?: D) => D;
+    view: (ctx: PageContext<P, D>) => TemplateResult;
+    /**
+     * <head> metadata. Receives params and (opt.) data if pre-loaded
+     * via bake.
+     */
+    head?: (params: P, data?: D) => HeadMeta;
+    /**
+     * Static HTML bake config. Used only in the bake script.
+     * Ignored at runtime.
+     */
+    bake?: BakeConfig<P, D>;
+    /**
+     * Local error boundary. Catches errors from view() and load() of this page.
+     * If not set — the global `error` from routes() is used.
+     */
+    errorView?: (err: Error, params: P) => TemplateResult;
+}
+/**
+ * Page factory. A typed wrapper over a plain object —
+ * needed only for type inference and the single "_page" stamp.
+ */
+export declare function page<P extends RouteParams = RouteParams, D = unknown>(spec: Omit<Page<P, D>, "_page">): Page<P, D>;
+export declare const isPage: (v: unknown) => v is Page;
+/**
+ * Manifest entry — what should respond to a path.
+ *   - Page                          → serve immediately, without import (for eager pages)
+ *   - () => Promise<{default:Page}> → lazy via dynamic import
+ *   - NestedRoutes                  → a group with a shared layout
+ *
+ * Using Page<any, any> so that user-defined page<{slug:string}>
+ * can be assigned here (TS disallows Page<{slug:string}> → Page<RouteParams>
+ * due to parameter contravariance).
+ */
+export type AnyPage = Page<any, any>;
+export type RouteEntry = AnyPage | (() => Promise<{
+    default: AnyPage;
+}>) | NestedRoutes;
+export interface NestedRoutes {
+    readonly _nested: true;
+    /** Layout page wrapping children. Will receive child=TemplateResult. */
+    layout?: AnyPage | (() => Promise<{
+        default: AnyPage;
+    }>);
+    /** Sub-routes. Keys are relative ("" , "users", "users/:id"). */
+    routes: Record<string, RouteEntry>;
+}
+export declare function nested(spec: Omit<NestedRoutes, "_nested">): NestedRoutes;
+export declare const isNested: (v: unknown) => v is NestedRoutes;