@c9up/aurora 0.1.3

package/dist/reactive.js

@@ -0,0 +1,217 @@
+/**
+ * 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.
+ */
+/**
+ * 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 const SIGNAL_BRAND = Symbol.for("aurora:signal");
+// `undefined` entries are untrack() sentinels — a read while one is on
+// top sees "no active observer" and registers no dependency.
+const observerStack = [];
+let batchDepth = 0;
+const pendingNotifications = new Set();
+function activeObserver() {
+    return observerStack[observerStack.length - 1];
+}
+/**
+ * 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 function signal(initial, options) {
+    const node = {
+        value: initial,
+        observers: new Set(),
+        equals: options?.equals ?? Object.is,
+    };
+    function accessor(...args) {
+        if (args.length === 0) {
+            const obs = activeObserver();
+            if (obs) {
+                node.observers.add(obs);
+                obs.dependencies.add(node);
+            }
+            return node.value;
+        }
+        const arg = args[0];
+        const next = typeof arg === "function"
+            ? arg(node.value)
+            : arg;
+        if (node.equals(node.value, next))
+            return;
+        node.value = next;
+        // Snapshot observers before iteration — an effect's run() may
+        // dispose itself (or peers) and mutate the live Set during the
+        // loop, which would skip notifications under for…of semantics.
+        const toNotify = [...node.observers];
+        if (batchDepth > 0) {
+            for (const eff of toNotify)
+                pendingNotifications.add(eff);
+            return;
+        }
+        for (const eff of toNotify) {
+            if (!eff.disposed)
+                eff.run();
+        }
+    }
+    accessor[SIGNAL_BRAND] = true;
+    signalNodes.set(accessor, node);
+    return accessor;
+}
+/**
+ * Test-only registry mapping a signal accessor to its backing node, so
+ * `observerCount` can assert the observer Set doesn't leak. A WeakMap
+ * keeps it off the public accessor surface and never retains a disposed
+ * signal.
+ */
+const signalNodes = new WeakMap();
+/**
+ * @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 function observerCount(sig) {
+    const node = signalNodes.get(sig);
+    return node ? node.observers.size : -1;
+}
+/** Runtime guard — distinguishes a signal accessor from any other callable. */
+export function isSignal(value) {
+    return (typeof value === "function" &&
+        value[SIGNAL_BRAND] === true);
+}
+/**
+ * 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 function effect(fn) {
+    const eff = {
+        dependencies: new Set(),
+        cleanups: [],
+        disposed: false,
+        run() {
+            if (this.disposed)
+                return;
+            runCleanups(this);
+            detach(this);
+            observerStack.push(this);
+            try {
+                const teardown = fn();
+                if (typeof teardown === "function")
+                    this.cleanups.push(teardown);
+            }
+            finally {
+                observerStack.pop();
+            }
+        },
+        dispose() {
+            if (this.disposed)
+                return;
+            this.disposed = true;
+            runCleanups(this);
+            detach(this);
+        },
+    };
+    eff.run();
+    return () => eff.dispose();
+}
+/**
+ * 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 function onCleanup(fn) {
+    const obs = activeObserver();
+    if (obs)
+        obs.cleanups.push(fn);
+}
+/**
+ * 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 function batch(fn) {
+    batchDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        batchDepth--;
+        if (batchDepth === 0) {
+            const toRun = [...pendingNotifications];
+            pendingNotifications.clear();
+            for (const eff of toRun) {
+                if (!eff.disposed)
+                    eff.run();
+            }
+        }
+    }
+}
+/**
+ * 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 function untrack(fn) {
+    // Push an `undefined` sentinel rather than a dummy Effect. A dummy
+    // gets `add()`-ed into every signal's `observers` Set on read and is
+    // never detached, leaking dead entries that grow each write. With
+    // `undefined` on top, `activeObserver()` returns undefined and reads
+    // register nothing — the actual "untracked" semantics.
+    observerStack.push(undefined);
+    try {
+        return fn();
+    }
+    finally {
+        observerStack.pop();
+    }
+}
+/**
+ * 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 function memo(fn) {
+    const internal = signal(undefined);
+    effect(() => {
+        internal(fn());
+    });
+    const reader = (() => internal());
+    reader[SIGNAL_BRAND] = true;
+    return reader;
+}
+function runCleanups(eff) {
+    if (eff.cleanups.length === 0)
+        return;
+    const queued = eff.cleanups.splice(0, eff.cleanups.length);
+    for (const cleanup of queued) {
+        try {
+            cleanup();
+        }
+        catch {
+            /* swallow — cleanup errors must not block sibling cleanups */
+        }
+    }
+}
+function detach(eff) {
+    for (const dep of eff.dependencies)
+        dep.observers.delete(eff);
+    eff.dependencies.clear();
+}

package/dist/relay.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Browser-side relay helper — hides the EventSource + POST handshake
+ * Ream's `@c9up/relay` package expects.
+ *
+ *   import { relay } from '@c9up/aurora/relay'
+ *
+ *   relay().subscribe(`project/${id}`, (ev) => {
+ *     console.log('received', ev)
+ *   })
+ *
+ * One EventSource per page (a singleton inside this module). All
+ * subscribe calls fan out to its uid. The connection re-opens after
+ * the browser auto-reconnect; subscriptions are re-applied.
+ *
+ * This module is browser-only. It's shipped via aurora's pre-built
+ * `dist/` and imported through the same importmap that maps
+ * `@c9up/aurora`. Node-side code that pulls it will trip on
+ * `EventSource` being undefined.
+ */
+export interface RelayClient {
+    subscribe<E>(channel: string, handler: (event: E) => void): () => void;
+    close(): void;
+}
+export interface RelayOptions {
+    /** SSE endpoint. Defaults to `/__relay/events`. */
+    sseUrl?: string;
+    /** Subscribe POST endpoint. Defaults to `/__relay/subscribe`. */
+    subscribeUrl?: string;
+    /** Optional bearer token (for guarded relay routes). */
+    bearer?: string;
+}
+/**
+ * Configure the relay endpoints + bearer. Call once at boot if you
+ * need to override the defaults. Multiple calls overwrite — last call
+ * wins.
+ */
+export declare function configureRelay(options: RelayOptions): void;
+/**
+ * Lazily-opened EventSource bound to a single page lifetime. Returns
+ * the same client across calls — duplicate `relay()` calls share the
+ * underlying connection.
+ */
+export declare function relay(): RelayClient;

package/dist/relay.js

@@ -0,0 +1,144 @@
+/**
+ * Browser-side relay helper — hides the EventSource + POST handshake
+ * Ream's `@c9up/relay` package expects.
+ *
+ *   import { relay } from '@c9up/aurora/relay'
+ *
+ *   relay().subscribe(`project/${id}`, (ev) => {
+ *     console.log('received', ev)
+ *   })
+ *
+ * One EventSource per page (a singleton inside this module). All
+ * subscribe calls fan out to its uid. The connection re-opens after
+ * the browser auto-reconnect; subscriptions are re-applied.
+ *
+ * This module is browser-only. It's shipped via aurora's pre-built
+ * `dist/` and imported through the same importmap that maps
+ * `@c9up/aurora`. Node-side code that pulls it will trip on
+ * `EventSource` being undefined.
+ */
+const STATE = {
+    sse: null,
+    uid: null,
+    channels: new Map(),
+    pending: [],
+};
+let CONFIG = {
+    sseUrl: "/__relay/events",
+    subscribeUrl: "/__relay/subscribe",
+    bearer: "",
+};
+/**
+ * Configure the relay endpoints + bearer. Call once at boot if you
+ * need to override the defaults. Multiple calls overwrite — last call
+ * wins.
+ */
+export function configureRelay(options) {
+    CONFIG = {
+        sseUrl: options.sseUrl ?? CONFIG.sseUrl,
+        subscribeUrl: options.subscribeUrl ?? CONFIG.subscribeUrl,
+        bearer: options.bearer ?? CONFIG.bearer,
+    };
+}
+/**
+ * Lazily-opened EventSource bound to a single page lifetime. Returns
+ * the same client across calls — duplicate `relay()` calls share the
+ * underlying connection.
+ */
+export function relay() {
+    if (!STATE.sse) {
+        open();
+    }
+    return CLIENT;
+}
+const CLIENT = {
+    subscribe(channel, handler) {
+        let handlers = STATE.channels.get(channel);
+        if (!handlers) {
+            handlers = new Set();
+            STATE.channels.set(channel, handlers);
+        }
+        const adapted = handler;
+        handlers.add(adapted);
+        // Subscribe over POST as soon as we have a uid. If the SSE is
+        // still mid-handshake, queue the call and flush on `connected`.
+        const doSubscribe = () => {
+            postSubscribe(channel).catch((err) => {
+                console.warn(`[aurora/relay] subscribe to ${channel} failed:`, err);
+            });
+        };
+        if (STATE.uid)
+            doSubscribe();
+        else
+            STATE.pending.push(doSubscribe);
+        // Detacher — only removes the local listener. The server-side
+        // subscription stays open; closing it would interrupt other
+        // listeners on the same channel.
+        return () => {
+            handlers?.delete(adapted);
+        };
+    },
+    close() {
+        if (STATE.sse) {
+            STATE.sse.close();
+            STATE.sse = null;
+        }
+        STATE.uid = null;
+        STATE.channels.clear();
+        STATE.pending.length = 0;
+    },
+};
+function open() {
+    const sse = new EventSource(CONFIG.sseUrl);
+    STATE.sse = sse;
+    sse.addEventListener("connected", (ev) => {
+        const data = safeJson(ev.data);
+        if (data && typeof data.uid === "string") {
+            STATE.uid = data.uid;
+            const queue = STATE.pending.splice(0);
+            for (const fn of queue)
+                fn();
+        }
+    });
+    sse.onmessage = (ev) => {
+        const data = safeJson(ev.data);
+        if (!data || typeof data.channel !== "string")
+            return;
+        const handlers = STATE.channels.get(data.channel);
+        if (!handlers)
+            return;
+        for (const handler of handlers) {
+            try {
+                handler(data);
+            }
+            catch (err) {
+                console.warn(`[aurora/relay] listener for ${data.channel} threw:`, err);
+            }
+        }
+    };
+}
+async function postSubscribe(channel) {
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (CONFIG.bearer)
+        headers.authorization = `Bearer ${CONFIG.bearer}`;
+    const res = await fetch(CONFIG.subscribeUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ uid: STATE.uid, channel }),
+    });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}`);
+    }
+}
+function safeJson(raw) {
+    if (typeof raw !== "string")
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Render a `TemplateResult` to the DOM and keep it reactive.
+ *
+ * `render(template, container)` clones the parsed `<template>`, walks to
+ * each slot, attaches the corresponding value (with `effect()` for any
+ * reactive expression), and appends the result to the container. The
+ * returned dispose function tears down every effect and removes the
+ * mounted nodes.
+ */
+import { type EffectCallback, type TemplateResult } from "./types.js";
+export type Disposer = () => void;
+/**
+ * Mount a TemplateResult into `container`. Returns a `Disposer` that
+ * stops every reactive effect and removes the mounted nodes. Calling it
+ * twice is a no-op.
+ */
+export declare function render(result: TemplateResult, container: Element | DocumentFragment): Disposer;
+/**
+ * Build a fragment for a TemplateResult and register cleanups.
+ *
+ * @internal Exported so `hydrate.ts` can client-render a reactive
+ * nested-template subtree when the signal changes after hydration
+ * (the swap path — see `hydrateTextSlot`).
+ */
+export declare function mount(result: TemplateResult, cleanups: Disposer[], mounted: ChildNode[], mountHooks: Array<EffectCallback>): DocumentFragment;