@c9up/aurora 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @c9up/aurora
+
+> Reactive UI runtime for the Ream framework — tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.
+
+Part of **[Ream](https://github.com/C9up/ream)** — a Rust-powered, AdonisJS-compatible Node.js framework. Independent, publishable package.
+
+## Installation
+
+```bash
+pnpm add @c9up/aurora
+ream configure @c9up/aurora
+```
+
+## Usage
+
+Register the provider in your app, then configure it under `config/aurora.ts`:
+
+```ts
+// reamrc.ts
+providers: [
+  () => import('@c9up/aurora/provider'),
+]
+```
+
+## Entry points
+
+- `@c9up/aurora` — main API
+- `@c9up/aurora/provider` — Ream IoC provider
+- `@c9up/aurora/services/main` — container service accessor
+- `@c9up/aurora/relay` — realtime adapter
+- `@c9up/aurora/ssr` — server-side rendering
+- `@c9up/aurora/hydrate` — client hydration
+
+## License
+
+MIT

package/dist/AuroraManager.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AuroraManager — the singleton behind `@c9up/aurora/services/main`.
+ *
+ *   import aurora from '@c9up/aurora/services/main'
+ *
+ *   async show(ctx) {
+ *     await aurora.render(ctx, 'ProjectPage', { project, tasks })
+ *   }
+ *
+ * The manager pairs a `Pages` registry with the SSR pipeline and the
+ * dist-asset handler. The provider builds it from `config/aurora.ts`;
+ * the app can also instantiate one manually for tests.
+ */
+import { Pages, type PagesConfig } from "./Pages.js";
+import { type RenderHttpContext, type RenderPageOptions } from "./server/renderPage.js";
+import { type AssetsHttpContext } from "./server/serveAssets.js";
+export interface AuroraManagerConfig {
+    pages: PagesConfig;
+    /**
+     * Filesystem path to aurora's pre-built `dist/`. Defaults to the
+     * dist directory shipped with the installed `@c9up/aurora` package.
+     * Override only if you want to serve a custom build.
+     */
+    auroraDistRoot?: string;
+}
+export declare class AuroraManager {
+    readonly pages: Pages;
+    readonly auroraDistRoot: string;
+    constructor(config: AuroraManagerConfig);
+    /**
+     * SSR + hydrate + ship the document.
+     */
+    render(ctx: RenderHttpContext, name: string, props: unknown, options?: RenderPageOptions): Promise<void>;
+    /**
+     * Handler for aurora's pre-built ESM runtime. Mount on
+     * `GET /_assets/aurora/*`.
+     */
+    auroraAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void>;
+    /**
+     * Handler for the app's pages directory. Mount on
+     * `GET /_assets/pages/*`.
+     */
+    pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void>;
+}

package/dist/AuroraManager.js

@@ -0,0 +1,47 @@
+/**
+ * AuroraManager — the singleton behind `@c9up/aurora/services/main`.
+ *
+ *   import aurora from '@c9up/aurora/services/main'
+ *
+ *   async show(ctx) {
+ *     await aurora.render(ctx, 'ProjectPage', { project, tasks })
+ *   }
+ *
+ * The manager pairs a `Pages` registry with the SSR pipeline and the
+ * dist-asset handler. The provider builds it from `config/aurora.ts`;
+ * the app can also instantiate one manually for tests.
+ */
+import { dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Pages } from "./Pages.js";
+import { renderPage, } from "./server/renderPage.js";
+import { serveAssets } from "./server/serveAssets.js";
+const DEFAULT_AURORA_DIST = resolvePath(dirname(fileURLToPath(import.meta.url)), "../dist");
+export class AuroraManager {
+    pages;
+    auroraDistRoot;
+    constructor(config) {
+        this.pages = new Pages(config.pages);
+        this.auroraDistRoot = config.auroraDistRoot ?? DEFAULT_AURORA_DIST;
+    }
+    /**
+     * SSR + hydrate + ship the document.
+     */
+    render(ctx, name, props, options) {
+        return renderPage(ctx, this.pages, name, props, options);
+    }
+    /**
+     * Handler for aurora's pre-built ESM runtime. Mount on
+     * `GET /_assets/aurora/*`.
+     */
+    auroraAssetsHandler() {
+        return serveAssets({ root: this.auroraDistRoot });
+    }
+    /**
+     * Handler for the app's pages directory. Mount on
+     * `GET /_assets/pages/*`.
+     */
+    pageAssetsHandler() {
+        return serveAssets({ root: this.pages.root });
+    }
+}

package/dist/AuroraProvider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * AuroraProvider — registers the AuroraManager singleton and auto-mounts
+ * the two asset routes the browser needs:
+ *
+ *   GET /_assets/aurora/*  → packages/@c9up/aurora/dist/*
+ *   GET /_assets/pages/*   → resources/pages/*
+ *
+ * Config (in `config/aurora.ts`):
+ *
+ *   export default {
+ *     pages: { root: new URL('../resources/pages', import.meta.url).pathname },
+ *   }
+ *
+ * The duck-typed `AuroraAppContext` keeps this provider usable in any
+ * framework with a container — non-Ream hosts get the singleton bindings
+ * and skip the route auto-registration silently.
+ */
+interface AuroraContainer {
+    singleton(token: unknown, factory: () => unknown): void;
+    resolve<T = unknown>(token: unknown): T;
+}
+interface AuroraConfigStore {
+    get<T = unknown>(key: string): T | undefined;
+}
+export interface AuroraAppContext {
+    container: AuroraContainer;
+    config: AuroraConfigStore;
+}
+export default class AuroraProvider {
+    protected app: AuroraAppContext;
+    constructor(app: AuroraAppContext);
+    register(): void;
+    boot(): Promise<void>;
+    start(): Promise<void>;
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+    /**
+     * Resolve the user-supplied config:
+     *   - relative `pages.root` (e.g. `./resources/pages`) is joined to
+     *     the project's `appRoot` URL — same convention `modules.path`
+     *     uses;
+     *   - absolute paths are passed through;
+     *   - missing config falls back to `<appRoot>/resources/pages`.
+     *
+     * `appRoot` is fetched from the container if the host registered
+     * one (Ream does, since v0.x — see Ignitor); other hosts get the
+     * `process.cwd()` fallback.
+     */
+    private resolveConfig;
+    private readAppRoot;
+}
+export {};

package/dist/AuroraProvider.js

@@ -0,0 +1,145 @@
+/**
+ * AuroraProvider — registers the AuroraManager singleton and auto-mounts
+ * the two asset routes the browser needs:
+ *
+ *   GET /_assets/aurora/*  → packages/@c9up/aurora/dist/*
+ *   GET /_assets/pages/*   → resources/pages/*
+ *
+ * Config (in `config/aurora.ts`):
+ *
+ *   export default {
+ *     pages: { root: new URL('../resources/pages', import.meta.url).pathname },
+ *   }
+ *
+ * The duck-typed `AuroraAppContext` keeps this provider usable in any
+ * framework with a container — non-Ream hosts get the singleton bindings
+ * and skip the route auto-registration silently.
+ */
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AuroraManager } from "./AuroraManager.js";
+import { auroraRoute } from "./route.js";
+import { setAurora } from "./services/main.js";
+import { renderToString } from "./ssr.js";
+export default class AuroraProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    register() {
+        this.app.container.singleton(AuroraManager, () => {
+            const raw = this.app.config.get("aurora");
+            const config = this.resolveConfig(raw);
+            const manager = new AuroraManager(config);
+            setAurora(manager);
+            return manager;
+        });
+        this.app.container.singleton("aurora", () => this.app.container.resolve(AuroraManager));
+        // Legacy stateless bindings — kept so existing apps that
+        // `container.resolve('aurora.render')` still get a working
+        // function. New code should use the singleton.
+        this.app.container.singleton("aurora.renderToString", () => renderToString);
+        this.app.container.singleton("aurora.route", () => auroraRoute);
+    }
+    async boot() {
+        // Force-resolve so `setAurora` runs even if the app never
+        // touches the singleton from a preload.
+        const manager = this.app.container.resolve(AuroraManager);
+        setAurora(manager);
+    }
+    async start() {
+        // Asset routes are registered in `start()` — after preloads —
+        // so apps can swap aurora's pages root in a preload if they
+        // wanted to. Non-Ream hosts (no `@c9up/ream/services/router`)
+        // AND pre-`setRouter` boots (router proxy uninit) both
+        // silent-return; ANY other error (slug collision, AuroraManager
+        // crash, factory bug) propagates so real regressions surface
+        // with a stack instead of "the asset routes just stopped
+        // mounting".
+        // Variable specifier so tsc does not statically resolve the optional
+        // `@c9up/ream` peer at build time (keeps aurora agnostic /
+        // standalone-buildable). Resolved to the host router only at runtime
+        // when aurora actually runs inside Ream.
+        const routerSpecifier = "@c9up/ream/services/router";
+        let routerMod;
+        try {
+            routerMod = await import(routerSpecifier);
+        }
+        catch (err) {
+            if (isModuleNotFound(err))
+                return;
+            throw err;
+        }
+        const manager = this.app.container.resolve(AuroraManager);
+        try {
+            routerMod.default.get("/_assets/aurora/*", adaptHandler(manager.auroraAssetsHandler()));
+            routerMod.default.get("/_assets/pages/*", adaptHandler(manager.pageAssetsHandler()));
+        }
+        catch (err) {
+            if (isRouterProxyUninit(err))
+                return;
+            throw err;
+        }
+    }
+    async ready() { }
+    async shutdown() { }
+    /**
+     * Resolve the user-supplied config:
+     *   - relative `pages.root` (e.g. `./resources/pages`) is joined to
+     *     the project's `appRoot` URL — same convention `modules.path`
+     *     uses;
+     *   - absolute paths are passed through;
+     *   - missing config falls back to `<appRoot>/resources/pages`.
+     *
+     * `appRoot` is fetched from the container if the host registered
+     * one (Ream does, since v0.x — see Ignitor); other hosts get the
+     * `process.cwd()` fallback.
+     */
+    resolveConfig(raw) {
+        const appRoot = this.readAppRoot();
+        const userRoot = raw?.pages?.root;
+        const root = typeof userRoot === "string" && userRoot.length > 0
+            ? isAbsolute(userRoot)
+                ? userRoot
+                : resolvePath(appRoot, userRoot)
+            : resolvePath(appRoot, "resources/pages");
+        return {
+            ...(raw ?? {}),
+            pages: { ...(raw?.pages ?? {}), root },
+        };
+    }
+    readAppRoot() {
+        try {
+            const raw = this.app.container.resolve("appRoot");
+            if (raw instanceof URL)
+                return fileURLToPath(raw);
+            if (typeof raw === "string")
+                return raw;
+        }
+        catch {
+            // Host doesn't expose appRoot — fall through.
+        }
+        return process.cwd();
+    }
+}
+/**
+ * Adapter: serveAssets() returns a handler that takes our duck-typed
+ * AssetsHttpContext. Ream's router passes its own HttpContext. The
+ * two are structurally compatible (request.param + response.{status,
+ * header, send}) but TypeScript needs the bridge made explicit.
+ */
+function adaptHandler(handler) {
+    return (ctx) => handler(ctx);
+}
+/** Node's ERR_MODULE_NOT_FOUND surfaces on an Error subclass with `code`. */
+function isModuleNotFound(err) {
+    if (err === null || typeof err !== "object" || !("code" in err))
+        return false;
+    const { code } = err;
+    return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+/** Ream's router proxy throws this exact string before Ignitor wires it. */
+function isRouterProxyUninit(err) {
+    return (err instanceof Error &&
+        err.message.includes("Router accessed before initialization"));
+}

package/dist/Pages.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Page registry — resolves a page NAME (e.g. `"ProjectPage"`) to its
+ * factory function, both server-side (dynamic import from disk) and
+ * client-side (URL on the asset mount).
+ *
+ * Convention: pages live in a configurable root directory, one file
+ * per page, default-exporting a function `(props) => TemplateResult`.
+ *
+ *   resources/pages/
+ *     ProjectPage.js     → name `"ProjectPage"`
+ *     dashboard/Home.js  → name `"dashboard/Home"`
+ *
+ * Sub-paths are allowed; the last `/`-separated segment is the file
+ * stem (with or without the `.js` extension).
+ */
+import type { TemplateResult } from "./types.js";
+/** A page module's default export. Receives props, returns a template. */
+export type PageFactory<P = unknown> = (props: P) => TemplateResult | Promise<TemplateResult>;
+export interface PagesConfig {
+    /**
+     * Absolute filesystem path to the pages directory. The server
+     * imports `${root}/${name}.js` (or `${name}.ts` when transpiled at
+     * runtime by `@swc-node/register`).
+     */
+    root: string;
+    /**
+     * URL prefix the browser uses to fetch a page's compiled JS.
+     * Defaults to `/_assets/pages`. A name `"Foo"` maps to
+     * `${urlPrefix}/Foo.js`.
+     */
+    urlPrefix?: string;
+    /**
+     * File extension to append when neither the source nor the
+     * compiled module ships with one. Defaults to `.js` — Node ESM
+     * resolution requires the explicit extension, and `@swc-node`
+     * transparently handles `.ts` aliases that resolve back to `.js`.
+     */
+    extension?: string;
+}
+/**
+ * `Pages` is a tiny resolver — no caching, no glob, no magic. The
+ * server imports the module dynamically on every render so editors +
+ * `--watch` reloads pick up changes immediately. Apps that want a
+ * pre-registered map (e.g. when pages are bundled into one entry) can
+ * call `register()` to short-circuit the disk lookup.
+ */
+export declare class Pages {
+    readonly root: string;
+    readonly urlPrefix: string;
+    readonly extension: string;
+    private readonly registry;
+    constructor(config: PagesConfig);
+    /**
+     * Pre-register a page factory under `name`, bypassing the disk
+     * lookup. Useful for bundled apps and tests.
+     *
+     * Generic on the props shape so callers can pass a tightly-typed
+     * factory (e.g. `PageFactory<{ name: string }>`) without TS rejecting
+     * the call due to function-parameter contravariance. The factory is
+     * stored as `PageFactory<unknown>` because the registry hands props
+     * back as `unknown` — the renderer JSON.stringifies them either way.
+     */
+    register<P>(name: string, factory: PageFactory<P>): void;
+    /**
+     * Resolve a page name to its factory function. Throws when the
+     * page is neither registered nor importable from disk.
+     *
+     * Path safety: `name` is rejected if it contains `..` segments or
+     * absolute-path markers. The joined path is also checked to live
+     * under `root` — defense in depth against URL-decoding tricks.
+     */
+    resolve(name: string): Promise<PageFactory>;
+    /**
+     * Browser-side URL the importmap (or a `<script src="…">`) should
+     * point at to fetch the same page's compiled JS.
+     */
+    urlFor(name: string): string;
+}

package/dist/Pages.js

@@ -0,0 +1,116 @@
+/**
+ * Page registry — resolves a page NAME (e.g. `"ProjectPage"`) to its
+ * factory function, both server-side (dynamic import from disk) and
+ * client-side (URL on the asset mount).
+ *
+ * Convention: pages live in a configurable root directory, one file
+ * per page, default-exporting a function `(props) => TemplateResult`.
+ *
+ *   resources/pages/
+ *     ProjectPage.js     → name `"ProjectPage"`
+ *     dashboard/Home.js  → name `"dashboard/Home"`
+ *
+ * Sub-paths are allowed; the last `/`-separated segment is the file
+ * stem (with or without the `.js` extension).
+ */
+import { resolve as resolvePath, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * `Pages` is a tiny resolver — no caching, no glob, no magic. The
+ * server imports the module dynamically on every render so editors +
+ * `--watch` reloads pick up changes immediately. Apps that want a
+ * pre-registered map (e.g. when pages are bundled into one entry) can
+ * call `register()` to short-circuit the disk lookup.
+ */
+export class Pages {
+    root;
+    urlPrefix;
+    extension;
+    registry = new Map();
+    constructor(config) {
+        this.root = config.root;
+        this.urlPrefix = (config.urlPrefix ?? "/_assets/pages").replace(/\/$/, "");
+        this.extension = config.extension ?? ".js";
+    }
+    /**
+     * Pre-register a page factory under `name`, bypassing the disk
+     * lookup. Useful for bundled apps and tests.
+     *
+     * Generic on the props shape so callers can pass a tightly-typed
+     * factory (e.g. `PageFactory<{ name: string }>`) without TS rejecting
+     * the call due to function-parameter contravariance. The factory is
+     * stored as `PageFactory<unknown>` because the registry hands props
+     * back as `unknown` — the renderer JSON.stringifies them either way.
+     */
+    register(name, factory) {
+        this.registry.set(name, factory);
+    }
+    /**
+     * Resolve a page name to its factory function. Throws when the
+     * page is neither registered nor importable from disk.
+     *
+     * Path safety: `name` is rejected if it contains `..` segments or
+     * absolute-path markers. The joined path is also checked to live
+     * under `root` — defense in depth against URL-decoding tricks.
+     */
+    async resolve(name) {
+        const preset = this.registry.get(name);
+        if (preset)
+            return preset;
+        assertSafeName(name);
+        const absolute = resolvePath(this.root, `${name}${this.extension}`);
+        if (!absolute.startsWith(this.root + sep) && absolute !== this.root) {
+            throw new Error(`[aurora] page path "${name}" resolves outside the pages root`);
+        }
+        // `pathToFileURL` so Windows + ESM stay happy. Node's ESM
+        // loader caches modules by URL, so a stable URL would freeze
+        // the first-imported version of the page for the whole process
+        // lifetime — pages edited on disk would NOT be picked up even
+        // when the app runs under a file watcher. In dev mode we bust
+        // the URL with the file's mtime so a real change yields a new
+        // cache key and triggers a re-import. In production we keep
+        // the stable URL — page sources don't change post-deploy and
+        // busting per-request would leak memory (each unique URL stays
+        // resident in the ESM loader for the process lifetime).
+        const isDev = process.env.NODE_ENV !== "production";
+        let urlHref = pathToFileURL(absolute).href;
+        if (isDev) {
+            try {
+                const { statSync } = await import("node:fs");
+                urlHref = `${urlHref}?v=${statSync(absolute).mtimeMs}`;
+            }
+            catch {
+                // stat failed → fall back to stable URL; the import below
+                // will surface the underlying ENOENT.
+            }
+        }
+        let mod;
+        try {
+            mod = (await import(urlHref));
+        }
+        catch (err) {
+            throw new Error(`[aurora] page "${name}" not found at ${absolute} — ${err.message}`);
+        }
+        if (typeof mod.default !== "function") {
+            throw new Error(`[aurora] page "${name}" must default-export a factory function`);
+        }
+        return mod.default;
+    }
+    /**
+     * Browser-side URL the importmap (or a `<script src="…">`) should
+     * point at to fetch the same page's compiled JS.
+     */
+    urlFor(name) {
+        assertSafeName(name);
+        return `${this.urlPrefix}/${name}${this.extension}`;
+    }
+}
+function assertSafeName(name) {
+    if (name.length === 0 ||
+        name.startsWith("/") ||
+        name.startsWith("\\") ||
+        name.includes("..") ||
+        name.includes("\0")) {
+        throw new Error(`[aurora] illegal page name: ${JSON.stringify(name)}`);
+    }
+}

package/dist/component.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Component runtime.
+ *
+ *   const Counter = component<{ initial?: number }>(({ initial = 0 }) => {
+ *     const count = signal(initial)
+ *     onMount(() => { document.title = `Count: ${count()}` })
+ *     return html`<button @click="${() => count(count() + 1)}">${count}</button>`
+ *   })
+ *
+ * Setup runs **once** when the component is created (mount time).
+ * `onMount` / `onUnmount` are bound to the per-component context active
+ * during setup, so they see the right cleanup queue when the component
+ * is unmounted later. State lives in plain `signal()` / `memo()` from
+ * `./reactive.js` — there's no separate hook layer, and signals work
+ * both inside and outside a component setup.
+ *
+ * Unlike React, there is no re-render — reactivity is push-based via the
+ * signals the setup function captures. The compiled template is what
+ * actually moves on screen.
+ */
+import type { Disposer } from "./render.js";
+import type { EffectCallback, TemplateResult } from "./types.js";
+/**
+ * Build a component factory. The returned function takes props and
+ * produces a `TemplateResult` that can be rendered or nested inside
+ * another template.
+ *
+ * `component()` does NOT itself mount anything — it composes. The
+ * outermost `render(Component(props), container)` is what mounts.
+ */
+export declare function component<P = Record<string, never>>(setup: (props: P) => TemplateResult): (props?: P) => TemplateResult;
+interface ComponentLifecycle {
+    mountHooks: ReadonlyArray<EffectCallback>;
+    cleanups: Disposer[];
+}
+/**
+ * Internal — extract the lifecycle attachment a `component()` left on a
+ * TemplateResult, if any. The renderer calls this after mounting the
+ * fragment so onMount fires once the DOM is live, and the returned
+ * cleanups bubble into the outer dispose chain.
+ */
+export declare function readComponentLifecycle(result: TemplateResult): ComponentLifecycle | undefined;
+/**
+ * Schedule a callback to run after the component is mounted into the
+ * live document. Returning a function from `onMount` registers it as an
+ * unmount cleanup.
+ */
+export declare function onMount(fn: EffectCallback): void;
+/**
+ * Schedule a callback to run when the component unmounts. Equivalent
+ * to the cleanup return of `onMount` but available without a paired
+ * mount action.
+ */
+export declare function onUnmount(fn: () => void): void;
+export {};