@c9up/aurora 0.1.3

package/dist/hydrate.js

@@ -0,0 +1,379 @@
+/**
+ * Hydration — adopt SSR-rendered HTML in the browser without rebuilding
+ * the DOM.
+ *
+ * `hydrate(container, factory)` runs the same component factory used
+ * server-side, recomputes the slot bindings, and attaches them to the
+ * existing nodes. Where SSR emitted plain text for `${signal}`, hydrate
+ * locates the same text node (via path resolution against the cloned
+ * template) and starts an effect that updates it on signal change.
+ *
+ * Implementation note: we still run `getTemplate(strings)` to know
+ * where each slot lives, then walk the LIVE container tree using the
+ * same path. SSR output must match the shape of the parsed template
+ * for hydration to find the right node — same constraint as React's
+ * hydration mismatch warning.
+ */
+import { readComponentLifecycle } from "./component.js";
+import { getTemplate } from "./html.js";
+import { effect, isSignal } from "./reactive.js";
+import { mount } from "./render.js";
+import { isTemplateResult, } from "./types.js";
+/**
+ * Process-scoped flag so the "reactive nested template not reactive
+ * after hydration" warning fires once, not on every matching slot.
+ * Only reached on LEGACY markup that predates SSR boundary markers
+ * (the markered path keeps the subtree reactive — no warning).
+ */
+let nestedReactiveWarned = false;
+/** @internal Reset the warn-once flag (tests). */
+export function resetHydrateWarnings() {
+    nestedReactiveWarned = false;
+}
+// Boundary-marker comment payloads (kept in sync with ssr.ts).
+const SLOT_START = "$";
+const SLOT_END = "/$";
+/**
+ * Collect every `<!--$-->…<!--/$-->` pair under `container`, ordered by
+ * the start marker's document position. Nesting is resolved with a
+ * stack so an inner pair's start/end never cross an outer pair's.
+ */
+function collectMarkerPairs(container) {
+    // Depth-first, document-order walk. We DON'T use createTreeWalker:
+    // some DOM implementations (happy-dom under vitest) ignore the
+    // numeric `whatToShow` filter and yield nothing. A manual recursion
+    // over childNodes is portable and visits comments in document order,
+    // so the stack pairs each `<!--$-->` with its matching `<!--/$-->`
+    // and the result is already start-ordered (no sort needed).
+    const pairs = [];
+    const stack = [];
+    const visit = (node) => {
+        if (node.nodeType === 8 /* Comment */) {
+            const c = node;
+            if (c.data === SLOT_START) {
+                stack.push(c);
+            }
+            else if (c.data === SLOT_END) {
+                const start = stack.pop();
+                if (start !== undefined)
+                    pairs.push({ start, end: c });
+            }
+            return;
+        }
+        for (let child = node.firstChild; child !== null; child = child.nextSibling) {
+            visit(child);
+        }
+    };
+    visit(container);
+    // `pairs` is in END order (innermost closes first). Sort by start's
+    // document position so consumption matches hydration's
+    // parents-before-children visit order.
+    pairs.sort((a, b) => a.start.compareDocumentPosition(b.start) &
+        4 /* DOCUMENT_POSITION_FOLLOWING */
+        ? -1
+        : 1);
+    return pairs;
+}
+/** Render a value (template / array / scalar) to detached client nodes. */
+function renderValueToNodes(value, cleanups, mountHooks, doc) {
+    if (value === null || value === undefined || value === false)
+        return [];
+    if (Array.isArray(value)) {
+        const out = [];
+        for (const item of value) {
+            out.push(...renderValueToNodes(item, cleanups, mountHooks, doc));
+        }
+        return out;
+    }
+    if (isTemplateResult(value)) {
+        const frag = mount(value, cleanups, [], mountHooks);
+        return Array.from(frag.childNodes);
+    }
+    if (value instanceof Node)
+        return [value];
+    return [doc.createTextNode(String(value))];
+}
+/**
+ * Wire a reactive structured slot (signal/function → nested template or
+ * array) using its SSR boundary-marker pair. The first run hydrates the
+ * initial value against the captured SSR nodes (reusing server markup,
+ * no flash); every subsequent signal change disposes the old subtree
+ * and client-renders the new value into the same `<!--$-->…<!--/$-->`
+ * range — so the DOM stays correct on branch changes instead of going
+ * stale.
+ */
+function hydrateReactiveStructured(fn, pair, cleanups, mountHooks, markerCursor) {
+    const { start, end } = pair;
+    let currentNodes = [];
+    for (let n = start.nextSibling; n !== null && n !== end; n = n.nextSibling) {
+        currentNodes.push(n);
+    }
+    let localCleanups = [];
+    let firstRun = true;
+    const dispose = effect(() => {
+        const next = fn();
+        if (firstRun) {
+            firstRun = false;
+            // Reuse SSR markup: hydrate reactive bindings INSIDE the nested
+            // template against the captured nodes. Inner boundary markers
+            // are consumed from the same cursor (document order).
+            if (isTemplateResult(next)) {
+                hydrateTemplateResult(next, currentNodes, localCleanups, mountHooks, markerCursor);
+            }
+            return;
+        }
+        // Signal changed post-hydration: tear down the old subtree's
+        // effects/listeners, drop its nodes, client-render the new value
+        // into the same marker range.
+        for (const d of localCleanups)
+            d();
+        localCleanups = [];
+        for (const n of currentNodes)
+            n.remove();
+        currentNodes = [];
+        const parent = end.parentNode;
+        if (parent === null)
+            return;
+        const fresh = renderValueToNodes(next, localCleanups, mountHooks, markerCursor.doc);
+        for (const n of fresh)
+            parent.insertBefore(n, end);
+        currentNodes = fresh;
+    });
+    cleanups.push(() => {
+        dispose();
+        for (const d of localCleanups)
+            d();
+        localCleanups = [];
+    });
+}
+/**
+ * Adopt SSR markup inside `container`. `factory` is the same function
+ * that was rendered server-side — its output (a TemplateResult tree)
+ * tells hydrate which slots to wire.
+ *
+ * Returns a `Disposer` that detaches every effect and event listener,
+ * leaving the DOM in place.
+ */
+export function hydrate(container, factory) {
+    const cleanups = [];
+    const mountHooks = [];
+    const markerCursor = {
+        pairs: collectMarkerPairs(container),
+        i: 0,
+        doc: container.ownerDocument ?? document,
+    };
+    const result = factory();
+    hydrateTemplateResult(result, Array.from(container.childNodes), cleanups, mountHooks, markerCursor);
+    for (const hook of mountHooks) {
+        try {
+            const teardown = hook();
+            if (typeof teardown === "function")
+                cleanups.push(teardown);
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        for (const c of cleanups.splice(0))
+            c();
+    };
+}
+/**
+ * Hydrate a TemplateResult against a list of live root nodes. The list
+ * is sliced as we consume children — text-slot anchors don't exist in
+ * the SSR output (we inlined the value), so we count text-slot
+ * boundaries by reading the static `strings` between values.
+ */
+function hydrateTemplateResult(result, liveNodes, cleanups, mountHooks, markerCursor) {
+    const lifecycle = readComponentLifecycle(result);
+    if (lifecycle) {
+        for (const hook of lifecycle.mountHooks)
+            mountHooks.push(hook);
+        for (const c of lifecycle.cleanups)
+            cleanups.push(c);
+    }
+    // Hydration walks via the SAME path resolver as render, but against
+    // a synthetic root that mimics the parsed template's child list.
+    const tpl = getTemplate(result.strings);
+    // The live container's children should structurally match the
+    // template's content children. Wrap them in a transient DocumentFragment
+    // for path resolution — DocumentFragment.childNodes is the same view
+    // we walked during parse.
+    const syntheticRoot = {
+        childNodes: liveNodes,
+    };
+    for (let i = 0; i < tpl.slots.length; i++) {
+        const slot = tpl.slots[i];
+        const liveNode = resolvePathLive(syntheticRoot, slot.path, liveNodes);
+        if (!liveNode) {
+            // Path missed in the live DOM — SSR markup diverges from the
+            // parsed template's shape. Surfacing the mismatch beats silent
+            // dead bindings: a stale slot doesn't update, but the developer
+            // has no clue why until they hit print-line debugging.
+            if (typeof console !== "undefined") {
+                console.warn(`[aurora] hydration mismatch: slot ${i} (${slot.kind}) path ${slot.path.join(".")} not found in live DOM — SSR markup may diverge from the client template (did you forget to rerender after a server change?)`);
+            }
+            continue;
+        }
+        hydrateSlot(slot, liveNode, result.values[i], cleanups, mountHooks, markerCursor);
+    }
+}
+/**
+ * Resolve a slot's path against the LIVE DOM. The first index of the
+ * path indexes into `liveNodes` directly (since we packaged them in a
+ * synthetic root); subsequent indices walk the child node list normally.
+ *
+ * Text-slot paths point to a comment marker that doesn't exist in
+ * hydration markup — we tolerate the miss and return null.
+ */
+function resolvePathLive(_root, path, rootNodes) {
+    if (path.length === 0)
+        return null;
+    let node = rootNodes[path[0]] ?? null;
+    for (let i = 1; node && i < path.length; i++) {
+        node = node.childNodes[path[i]] ?? null;
+    }
+    return node;
+}
+function hydrateSlot(slot, node, value, cleanups, mountHooks, markerCursor) {
+    switch (slot.kind) {
+        case "text":
+            hydrateTextSlot(node, value, cleanups, mountHooks, markerCursor);
+            return;
+        case "attr":
+            hydrateAttrSlot(slot, node, value, cleanups);
+            return;
+        case "boolean-attr":
+            hydrateBooleanAttrSlot(slot, node, value, cleanups);
+            return;
+        case "prop":
+            hydratePropSlot(slot, node, value, cleanups);
+            return;
+        case "event":
+            hydrateEventSlot(slot, node, value, cleanups);
+            return;
+    }
+}
+/**
+ * Hydrate a text slot. SSR inlined the value as a text node (or skipped
+ * it for null/false/undefined). We locate the **first text node sibling
+ * preceding the path's terminal index** — that's where SSR wrote the
+ * value — and wire an effect that overwrites its `data` on changes.
+ *
+ * For reactive values (signals/functions), the effect updates the
+ * existing text node in place. For nested TemplateResults, we
+ * recursively hydrate against the captured sibling range.
+ */
+function hydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCursor) {
+    // The path lands on the comment marker that EXISTS in the parsed
+    // template but not in SSR output. Hydration walks the live siblings
+    // to find the text node that holds the SSR value.
+    // Strategy: the comment was located at child index N inside its
+    // parent; SSR wrote the value as the immediately-preceding text
+    // node (or nothing for null/false). Live node here is whatever the
+    // path resolution returned — often a text node, sometimes an
+    // element (for nested templates). We rebind in-place.
+    if (isSignal(value) || typeof value === "function") {
+        const fn = value;
+        // First, evaluate eagerly to detect a structured value (nested
+        // TemplateResult / array) — those need a SWAP on change, which
+        // means a node range, which the SSR boundary markers give us.
+        const first = fn();
+        if (isTemplateResult(first) || Array.isArray(first)) {
+            const pair = markerCursor.pairs[markerCursor.i];
+            if (pair !== undefined) {
+                markerCursor.i += 1;
+                hydrateReactiveStructured(fn, pair, cleanups, mountHooks, markerCursor);
+                return;
+            }
+            // LEGACY markup (no boundary markers — produced by an older
+            // SSR build): we can't locate the subtree's range, so we
+            // hydrate once and warn that the subtree won't stay reactive.
+            // Fresh SSR always emits markers, so this path is dead for
+            // matched server/client builds.
+            if (!nestedReactiveWarned && typeof console !== "undefined") {
+                nestedReactiveWarned = true;
+                console.warn("[aurora] a reactive expression hydrated to a nested template but " +
+                    "the SSR markup has no boundary markers — the subtree will not update " +
+                    "on signal changes. Re-render with a current @c9up/aurora SSR build.");
+            }
+            if (isTemplateResult(first)) {
+                hydrateTemplateResult(first, [commentMarker], cleanups, mountHooks, markerCursor);
+            }
+            return;
+        }
+        const textNode = commentMarker.nodeType === 3 /* TEXT */
+            ? commentMarker
+            : commentMarker.previousSibling?.nodeType === 3
+                ? commentMarker.previousSibling
+                : null;
+        if (!textNode)
+            return;
+        const dispose = effect(() => {
+            const v = fn();
+            textNode.data = v == null || v === false ? "" : String(v);
+        });
+        cleanups.push(dispose);
+        return;
+    }
+    if (isTemplateResult(value)) {
+        hydrateTemplateResult(value, [commentMarker], cleanups, mountHooks, markerCursor);
+        return;
+    }
+    // Static value — SSR rendered it once and we don't need to do
+    // anything. The text already lives in the DOM.
+}
+function hydrateAttrSlot(slot, el, value, cleanups) {
+    function apply(v) {
+        if (v === null || v === undefined || v === false) {
+            el.removeAttribute(slot.name);
+        }
+        else if (v === true) {
+            el.setAttribute(slot.name, "");
+        }
+        else {
+            el.setAttribute(slot.name, String(v));
+        }
+    }
+    if (isSignal(value) || typeof value === "function") {
+        const dispose = effect(() => apply(value()));
+        cleanups.push(dispose);
+    }
+    // Static attrs need no hydration — SSR already wrote them.
+}
+function hydrateBooleanAttrSlot(slot, el, value, cleanups) {
+    function apply(v) {
+        if (v)
+            el.setAttribute(slot.name, "");
+        else
+            el.removeAttribute(slot.name);
+    }
+    if (isSignal(value) || typeof value === "function") {
+        const dispose = effect(() => apply(value()));
+        cleanups.push(dispose);
+    }
+}
+function hydratePropSlot(slot, el, value, cleanups) {
+    function apply(v) {
+        el[slot.name] = v;
+    }
+    if (isSignal(value) || typeof value === "function") {
+        const dispose = effect(() => apply(value()));
+        cleanups.push(dispose);
+    }
+    else {
+        apply(value);
+    }
+}
+function hydrateEventSlot(slot, el, value, cleanups) {
+    if (typeof value !== "function")
+        return;
+    const handler = value;
+    el.addEventListener(slot.event, handler);
+    cleanups.push(() => el.removeEventListener(slot.event, handler));
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
+export { component, onMount, onUnmount } from "./component.js";
+export { html, isTemplateResult } from "./html.js";
+export { hydrate } from "./hydrate.js";
+export { type PageFactory, Pages, type PagesConfig, } from "./Pages.js";
+export { batch, effect, isSignal, memo, onCleanup, type ReadSignal, type Signal, signal, untrack, } from "./reactive.js";
+export { type Disposer, render } from "./render.js";
+export { type AuroraHttpContext, type AuroraResponse, type AuroraRouteConfig, auroraRoute, } from "./route.js";
+export { type RenderHttpContext, type RenderPageOptions, type RenderResponse, renderPage, } from "./server/renderPage.js";
+export { type AssetsHttpContext, type AssetsRequest, type AssetsResponse, type ServeAssetsOptions, serveAssets, } from "./server/serveAssets.js";
+export { renderToString } from "./ssr.js";
+export type { TemplateResult } from "./types.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+// ─── Inertia-shape server surface ─────────────────────────────────
+export { AuroraManager } from "./AuroraManager.js";
+export { component, onMount, onUnmount } from "./component.js";
+export { html, isTemplateResult } from "./html.js";
+export { hydrate } from "./hydrate.js";
+export { Pages, } from "./Pages.js";
+export { batch, effect, isSignal, memo, onCleanup, signal, untrack, } from "./reactive.js";
+export { render } from "./render.js";
+export { auroraRoute, } from "./route.js";
+export { renderPage, } from "./server/renderPage.js";
+export { serveAssets, } from "./server/serveAssets.js";
+export { renderToString } from "./ssr.js";

package/dist/reactive.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Reactive core — signals + effects with auto-tracking.
+ *
+ * No proxies, no VDOM. A `signal<T>()` is a single read/write function that
+ * registers itself in the currently-running observer's dependency set when
+ * read, and notifies every dependent observer when written.
+ *
+ * Effects run their callback once eagerly, capture the signals they read,
+ * and re-run whenever any of those signals fires. Effects can return a
+ * cleanup function that runs before the next re-execution and at disposal.
+ */
+import type { EffectCallback } from "./types.js";
+/** Reader-only view of a signal. Returned by `memo()`. */
+export interface ReadSignal<T> {
+    (): T;
+    readonly [SIGNAL_BRAND]: true;
+}
+/** Read-write signal — call with no args to read, with one arg to write. */
+export interface Signal<T> {
+    (): T;
+    (next: T): void;
+    (updater: (prev: T) => T): void;
+    readonly [SIGNAL_BRAND]: true;
+}
+/**
+ * Brand symbol so consumers can distinguish a signal from a plain function
+ * without instanceof. Exposed only via the `isSignal` guard — never call
+ * sites need to import this directly.
+ */
+export declare const SIGNAL_BRAND: unique symbol;
+/**
+ * Create a writable signal seeded with `initial`. Reads register the
+ * current observer; writes notify every observer that previously read.
+ *
+ * Optional `{ equals }` swaps the default `Object.is` check — return
+ * `true` to skip notifying observers (the new value is "the same").
+ */
+export declare function signal<T>(initial: T, options?: {
+    equals?: (a: T, b: T) => boolean;
+}): Signal<T>;
+/**
+ * @internal Observer-count test seam for the untrack-leak invariant: a
+ * read inside `untrack()` must NOT add an entry to a signal's observer
+ * Set. Returns -1 for a value that isn't a tracked signal.
+ */
+export declare function observerCount(sig: object): number;
+/** Runtime guard — distinguishes a signal accessor from any other callable. */
+export declare function isSignal<T = unknown>(value: unknown): value is Signal<T>;
+/**
+ * Run `fn` immediately and every time a signal it reads changes. Returns a
+ * dispose function — call it to stop the effect and run any pending
+ * cleanup.
+ *
+ * Inside `fn`, return another function to register cleanup that runs
+ * before the next execution AND at disposal. Multiple cleanups can also
+ * be registered via `onCleanup()`.
+ */
+export declare function effect(fn: EffectCallback): () => void;
+/**
+ * Register a cleanup callback against the currently-running effect.
+ * No-op when called outside an effect — same contract as Solid's
+ * `onCleanup`, more permissive than React's hook-only access.
+ */
+export declare function onCleanup(fn: () => void): void;
+/**
+ * Defer notifications until `fn` returns. Multiple writes to the same
+ * signal coalesce into a single observer re-run, and writes across
+ * signals re-run each affected observer at most once.
+ */
+export declare function batch<T>(fn: () => T): T;
+/**
+ * Read signals inside `fn` without registering them as dependencies of
+ * the current observer. Useful when an effect needs the current value of
+ * a signal but should not re-run when it changes.
+ */
+export declare function untrack<T>(fn: () => T): T;
+/**
+ * Derived read-only signal — `fn` re-runs when any signal it reads
+ * changes, and the latest return value is cached + handed out via the
+ * returned accessor. Cleanups inside `fn` (via `onCleanup`) run on every
+ * recomputation.
+ */
+export declare function memo<T>(fn: () => T): ReadSignal<T>;