npm - @c9up/aurora - Versions diffs - 0.1.3 - Mend

@c9up/aurora 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

package/LICENSE +21 -0
package/README.md +36 -0
package/dist/AuroraManager.d.ts +44 -0
package/dist/AuroraManager.js +47 -0
package/dist/AuroraProvider.d.ts +52 -0
package/dist/AuroraProvider.js +145 -0
package/dist/Pages.d.ts +78 -0
package/dist/Pages.js +116 -0
package/dist/component.d.ts +55 -0
package/dist/component.js +97 -0
package/dist/html.d.ts +30 -0
package/dist/html.js +246 -0
package/dist/hydrate.d.ts +29 -0
package/dist/hydrate.js +379 -0
package/dist/index.d.ts +12 -0
package/dist/index.js +12 -0
package/dist/reactive.d.ts +83 -0
package/dist/reactive.js +217 -0
package/dist/relay.d.ts +43 -0
package/dist/relay.js +144 -0
package/dist/render.d.ts +25 -0
package/dist/render.js +283 -0
package/dist/route.d.ts +64 -0
package/dist/route.js +49 -0
package/dist/server/renderPage.d.ts +62 -0
package/dist/server/renderPage.js +83 -0
package/dist/server/serveAssets.d.ts +43 -0
package/dist/server/serveAssets.js +89 -0
package/dist/services/main.d.ts +18 -0
package/dist/services/main.js +31 -0
package/dist/ssr.d.ts +22 -0
package/dist/ssr.js +179 -0
package/dist/types.d.ts +78 -0
package/dist/types.js +15 -0
package/package.json +69 -0
package/src/AuroraManager.ts +76 -0
package/src/AuroraProvider.ts +187 -0
package/src/Pages.ts +164 -0
package/src/component.ts +138 -0
package/src/html.ts +296 -0
package/src/hydrate.ts +518 -0
package/src/index.ts +43 -0
package/src/reactive.ts +265 -0
package/src/relay.ts +171 -0
package/src/render.ts +378 -0
package/src/route.ts +96 -0
package/src/server/renderPage.ts +135 -0
package/src/server/serveAssets.ts +135 -0
package/src/services/main.ts +40 -0
package/src/ssr.ts +179 -0
package/src/types.ts +97 -0

package/dist/services/main.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/**
+ * Default `AuroraManager` singleton — Adonis-style:
+ *
+ *   import aurora from '@c9up/aurora/services/main'
+ *
+ *   await aurora.render(ctx, 'ProjectPage', { project, tasks })
+ *
+ * Populated either by `AuroraProvider.boot()` (when the app uses
+ * `() => import('@c9up/aurora/provider')`) or by the app itself via
+ * `setAurora(myManager)`.
+ */
+import type { AuroraManager } from "../AuroraManager.js";
+/** @internal Bind the singleton (called by AuroraProvider or by the app). */
+export declare function setAurora(value: AuroraManager): void;
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export declare function getAurora(): AuroraManager | undefined;
+declare const aurora: AuroraManager;
+export default aurora;

package/dist/services/main.js ADDED Viewed

@@ -0,0 +1,31 @@
+/**
+ * Default `AuroraManager` singleton — Adonis-style:
+ *
+ *   import aurora from '@c9up/aurora/services/main'
+ *
+ *   await aurora.render(ctx, 'ProjectPage', { project, tasks })
+ *
+ * Populated either by `AuroraProvider.boot()` (when the app uses
+ * `() => import('@c9up/aurora/provider')`) or by the app itself via
+ * `setAurora(myManager)`.
+ */
+let instance;
+/** @internal Bind the singleton (called by AuroraProvider or by the app). */
+export function setAurora(value) {
+    instance = value;
+}
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getAurora() {
+    return instance;
+}
+const aurora = new Proxy({}, {
+    get(_target, prop) {
+        if (!instance) {
+            throw new Error("[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +
+                "or `setAurora(myManager)` was called. Wire one of them first.");
+        }
+        const value = Reflect.get(instance, prop, instance);
+        return typeof value === "function" ? value.bind(instance) : value;
+    },
+});
+export default aurora;

package/dist/ssr.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * Server-side rendering — produces an HTML string from a `TemplateResult`
+ * without ever touching the DOM.
+ *
+ * Reads each slot's value eagerly (signals get a one-shot snapshot,
+ * functions are invoked, nested TemplateResults recurse). Event handlers
+ * are dropped server-side; hydration re-binds them once the markup
+ * lands in the browser.
+ */
+import { type TemplateResult } from "./types.js";
+declare const VOID_ELEMENTS: Set<string>;
+/**
+ * Stringify a TemplateResult into HTML. Returns the markup ready to be
+ * shipped over the wire — no surrounding `<html>`/`<head>`/`<body>`
+ * unless the template includes them.
+ *
+ * The function walks the `strings` array directly; it does NOT depend
+ * on the DOM-side template cache, so it works in any JS runtime (Node,
+ * Cloudflare Workers, Bun, Deno).
+ */
+export declare function renderToString(result: TemplateResult): string;
+export { VOID_ELEMENTS };

package/dist/ssr.js ADDED Viewed

@@ -0,0 +1,179 @@
+/**
+ * Server-side rendering — produces an HTML string from a `TemplateResult`
+ * without ever touching the DOM.
+ *
+ * Reads each slot's value eagerly (signals get a one-shot snapshot,
+ * functions are invoked, nested TemplateResults recurse). Event handlers
+ * are dropped server-side; hydration re-binds them once the markup
+ * lands in the browser.
+ */
+import { isSignal } from "./reactive.js";
+import { isTemplateResult } from "./types.js";
+const VOID_ELEMENTS = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "keygen",
+    "link",
+    "meta",
+    "source",
+    "track",
+    "wbr",
+]);
+/**
+ * Stringify a TemplateResult into HTML. Returns the markup ready to be
+ * shipped over the wire — no surrounding `<html>`/`<head>`/`<body>`
+ * unless the template includes them.
+ *
+ * The function walks the `strings` array directly; it does NOT depend
+ * on the DOM-side template cache, so it works in any JS runtime (Node,
+ * Cloudflare Workers, Bun, Deno).
+ */
+export function renderToString(result) {
+    return stringifyTemplateResult(result);
+}
+function stringifyTemplateResult(result) {
+    const { strings, values } = result;
+    let out = "";
+    // When a segment ends with a directive (` @click="`, ` ?disabled="`,
+    // ` .value="`), we drop the directive prefix from that segment, skip
+    // the matching value, and consume the closing `"` from the next
+    // segment. This three-step coordination is why the loop holds a
+    // `pendingClosingQuote` flag.
+    let pendingClosingQuote = false;
+    for (let i = 0; i < strings.length; i++) {
+        let segment = strings[i];
+        if (pendingClosingQuote) {
+            segment = segment.replace(/^"/, "");
+            pendingClosingQuote = false;
+        }
+        const directiveMatch = segment.match(/\s([@?.][\w-]+)="$/);
+        const skipValue = directiveMatch !== null;
+        if (directiveMatch) {
+            segment = segment.slice(0, segment.length - directiveMatch[0].length);
+            pendingClosingQuote = true;
+        }
+        out += segment;
+        if (i < values.length && !skipValue) {
+            const value = values[i];
+            const inAttr = isInsideAttribute(out);
+            if (!inAttr && isReactiveStructuredSlot(value)) {
+                // Reactive text slot whose value is a nested template /
+                // array — wrap the rendered content in boundary markers so
+                // hydration can locate the exact node range and SWAP it when
+                // the signal changes client-side. Without these markers a
+                // nested-template slot hydrates once and then goes stale
+                // (no way to find where the subtree starts/ends). Scalar
+                // reactive slots (`${signal}` → text) are NOT wrapped: their
+                // hydration updates the text node in place, no range needed.
+                out += `<!--${SLOT_START}-->`;
+                out += stringifyValue(value, false);
+                out += `<!--${SLOT_END}-->`;
+            }
+            else {
+                out += stringifyValue(value, inAttr);
+            }
+        }
+    }
+    return out;
+}
+/** Boundary-marker comment payloads (kept in sync with hydrate.ts). */
+const SLOT_START = "$";
+const SLOT_END = "/$";
+/**
+ * True when `value` is a reactive expression (signal / function) whose
+ * current evaluation is a structured node payload (a nested
+ * TemplateResult, or an array). These are the slots that can SWAP their
+ * subtree on a client-side change and therefore need boundary markers
+ * for hydration to find the range. A reactive slot resolving to a
+ * scalar (string / number) is updated in place and needs no markers.
+ */
+function isReactiveStructuredSlot(value) {
+    if (!isSignal(value) && typeof value !== "function")
+        return false;
+    let evaluated;
+    try {
+        evaluated = isSignal(value)
+            ? value()
+            : value();
+    }
+    catch {
+        return false;
+    }
+    return isTemplateResult(evaluated) || Array.isArray(evaluated);
+}
+/**
+ * Returns true if the position at the end of `htmlSoFar` lives inside
+ * the value region of an HTML tag (between `<` and `>`). The check
+ * walks backwards from the end, which is the smallest hint we need to
+ * decide between text-region and attribute-region escaping.
+ */
+function isInsideAttribute(htmlSoFar) {
+    for (let i = htmlSoFar.length - 1; i >= 0; i--) {
+        const c = htmlSoFar.charCodeAt(i);
+        if (c === 60 /* '<' */)
+            return true;
+        if (c === 62 /* '>' */)
+            return false;
+    }
+    return false;
+}
+function stringifyValue(value, inAttribute) {
+    if (value === null || value === undefined || value === false)
+        return "";
+    if (value === true)
+        return inAttribute ? "" : "true";
+    if (isSignal(value))
+        return stringifyValue(value(), inAttribute);
+    if (typeof value === "function") {
+        // In attribute position: directive handlers (`@click`, `?disabled`,
+        // `.prop`) have already been stripped by `stripDirectiveBefore`.
+        // A function reaching this point is a reactive-expression text
+        // slot (`${() => ...}`), which we evaluate eagerly server-side.
+        try {
+            return stringifyValue(value(), inAttribute);
+        }
+        catch {
+            return "";
+        }
+    }
+    if (Array.isArray(value)) {
+        let out = "";
+        for (const item of value)
+            out += stringifyValue(item, inAttribute);
+        return out;
+    }
+    if (isTemplateResult(value))
+        return stringifyTemplateResult(value);
+    // Plain value — escape HTML entities (text) or attribute special
+    // characters (attribute value).
+    return inAttribute ? escapeAttr(String(value)) : escapeText(String(value));
+}
+function escapeText(s) {
+    return s
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+function escapeAttr(s) {
+    // Escape BOTH quote styles: the engine doesn't force double-quoted
+    // attributes (the classifier only tracks `<`/`>`), so a template author
+    // writing `id='${x}'` must still be safe — without escaping `'` a value
+    // like `' onmouseover='alert(1)` would break out of a single-quoted
+    // attribute. `>` isn't strictly required inside a quoted value but is
+    // escaped to stay safe under stray scanners that hunt tag boundaries
+    // before resolving the quote context.
+    return s
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+// VOID_ELEMENTS exported for downstream tooling (hydration heuristics).
+export { VOID_ELEMENTS };

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * Shared types for aurora templates.
+ *
+ * A `TemplateResult` is what `html\`...\`` returns. It carries the raw
+ * pieces (strings, values) and a stable reference to the parsed
+ * `Template` (memoised by `strings`). Templates are framework-internal —
+ * apps only ever see `TemplateResult`.
+ */
+/**
+ * A lifecycle/effect callback that runs and OPTIONALLY returns a cleanup
+ * function — exactly React's `EffectCallback = () => void | (() => void)`.
+ *
+ * The `void` member of the return union is load-bearing: it is what makes a
+ * plain `() => {}` (whose return type is `void`) assignable here. Replacing it
+ * with `(() => void) | undefined` makes every void-returning callback a type
+ * error (a `() => void` is NOT assignable to `() => (() => void) | undefined`).
+ * So `noConfusingVoidType` is suppressed once, at this single definition,
+ * instead of being worked around at ~15 call sites with broken types.
+ */
+export type EffectCallback = () => void | (() => void);
+/** Slot descriptor — where a `${value}` lives inside a parsed template. */
+export type SlotKind = "text" | "attr" | "event" | "boolean-attr" | "prop";
+/**
+ * Path to the binding point inside the cloned template. Each step is a
+ * child index. We never walk by query selectors because attribute and text
+ * placements would need synthetic markers in markup an app provided.
+ */
+export type NodePath = readonly number[];
+export interface TextSlot {
+    kind: "text";
+    path: NodePath;
+}
+export interface AttrSlot {
+    kind: "attr";
+    path: NodePath;
+    name: string;
+    /**
+     * When the attribute interpolates more than one `${...}` slot, every
+     * slot shares the same `name` and the static segments are stored under
+     * `staticParts`. The render step joins them back together each tick.
+     */
+    staticParts?: readonly string[];
+    staticPartIndex?: number;
+}
+export interface EventSlot {
+    kind: "event";
+    path: NodePath;
+    event: string;
+}
+export interface BooleanAttrSlot {
+    kind: "boolean-attr";
+    path: NodePath;
+    name: string;
+}
+export interface PropSlot {
+    kind: "prop";
+    path: NodePath;
+    name: string;
+}
+export type Slot = TextSlot | AttrSlot | EventSlot | BooleanAttrSlot | PropSlot;
+/** Compiled artefact — produced once per unique `strings` array. */
+export interface Template {
+    /**
+     * A `<template>` element whose `content` fragment is cloned on every
+     * render. Cloning is much cheaper than re-parsing the HTML string.
+     */
+    readonly element: HTMLTemplateElement;
+    /** Slot descriptors in source order (same order as the `${...}` values). */
+    readonly slots: readonly Slot[];
+}
+/** Tagged-template return value — what `html\`\`` produces. */
+export interface TemplateResult {
+    readonly strings: TemplateStringsArray;
+    readonly values: readonly unknown[];
+    readonly [TEMPLATE_RESULT_BRAND]: true;
+}
+export declare const TEMPLATE_RESULT_BRAND: unique symbol;
+export declare function isTemplateResult(value: unknown): value is TemplateResult;

package/dist/types.js ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * Shared types for aurora templates.
+ *
+ * A `TemplateResult` is what `html\`...\`` returns. It carries the raw
+ * pieces (strings, values) and a stable reference to the parsed
+ * `Template` (memoised by `strings`). Templates are framework-internal —
+ * apps only ever see `TemplateResult`.
+ */
+export const TEMPLATE_RESULT_BRAND = Symbol.for("aurora:template-result");
+export function isTemplateResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[TEMPLATE_RESULT_BRAND] ===
+            true);
+}

package/package.json ADDED Viewed

@@ -0,0 +1,69 @@
+{
+  "name": "@c9up/aurora",
+  "version": "0.1.3",
+  "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/AuroraProvider.d.ts",
+      "import": "./dist/AuroraProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    },
+    "./relay": {
+      "types": "./dist/relay.d.ts",
+      "import": "./dist/relay.js"
+    },
+    "./ssr": {
+      "types": "./dist/ssr.d.ts",
+      "import": "./dist/ssr.js"
+    },
+    "./hydrate": {
+      "types": "./dist/hydrate.d.ts",
+      "import": "./dist/hydrate.js"
+    }
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "happy-dom": "^15.11.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/aurora.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/AuroraManager.ts ADDED Viewed

@@ -0,0 +1,76 @@
+/**
+ * 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, type PagesConfig } from "./Pages.js";
+import {
+	type RenderHttpContext,
+	type RenderPageOptions,
+	renderPage,
+} from "./server/renderPage.js";
+import { type AssetsHttpContext, serveAssets } 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;
+}
+const DEFAULT_AURORA_DIST = resolvePath(
+	dirname(fileURLToPath(import.meta.url)),
+	"../dist",
+);
+export class AuroraManager {
+	readonly pages: Pages;
+	readonly auroraDistRoot: string;
+	constructor(config: AuroraManagerConfig) {
+		this.pages = new Pages(config.pages);
+		this.auroraDistRoot = config.auroraDistRoot ?? DEFAULT_AURORA_DIST;
+	}
+	/**
+	 * SSR + hydrate + ship the document.
+	 */
+	render(
+		ctx: RenderHttpContext,
+		name: string,
+		props: unknown,
+		options?: RenderPageOptions,
+	): Promise<void> {
+		return renderPage(ctx, this.pages, name, props, options);
+	}
+	/**
+	 * Handler for aurora's pre-built ESM runtime. Mount on
+	 * `GET /_assets/aurora/*`.
+	 */
+	auroraAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void> {
+		return serveAssets({ root: this.auroraDistRoot });
+	}
+	/**
+	 * Handler for the app's pages directory. Mount on
+	 * `GET /_assets/pages/*`.
+	 */
+	pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void> {
+		return serveAssets({ root: this.pages.root });
+	}
+}

package/src/AuroraProvider.ts ADDED Viewed

@@ -0,0 +1,187 @@
+/**
+ * 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, type AuroraManagerConfig } from "./AuroraManager.js";
+import { auroraRoute } from "./route.js";
+import type {
+	AssetsHttpContext,
+	AssetsRequest,
+	AssetsResponse,
+} from "./server/serveAssets.js";
+import { setAurora } from "./services/main.js";
+import { renderToString } from "./ssr.js";
+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;
+}
+interface ReamRouter {
+	get(
+		path: string,
+		handler: (ctx: AssetsHttpContext) => Promise<void> | void,
+	): unknown;
+}
+export default class AuroraProvider {
+	constructor(protected app: AuroraAppContext) {}
+	register(): void {
+		this.app.container.singleton(AuroraManager, () => {
+			const raw = this.app.config.get<AuroraManagerConfig>("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>(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(): Promise<void> {
+		// Force-resolve so `setAurora` runs even if the app never
+		// touches the singleton from a preload.
+		const manager = this.app.container.resolve<AuroraManager>(AuroraManager);
+		setAurora(manager);
+	}
+	async start(): Promise<void> {
+		// 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: { default: ReamRouter };
+		try {
+			routerMod = await import(routerSpecifier);
+		} catch (err) {
+			if (isModuleNotFound(err)) return;
+			throw err;
+		}
+		const manager = this.app.container.resolve<AuroraManager>(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(): Promise<void> {}
+	async 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(
+		raw: AuroraManagerConfig | undefined,
+	): AuroraManagerConfig {
+		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 },
+		};
+	}
+	private readAppRoot(): string {
+		try {
+			const raw = this.app.container.resolve<unknown>("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: (ctx: AssetsHttpContext) => Promise<void>,
+): (ctx: {
+	request: AssetsRequest;
+	response: AssetsResponse;
+}) => Promise<void> {
+	return (ctx) => handler(ctx);
+}
+/** Node's ERR_MODULE_NOT_FOUND surfaces on an Error subclass with `code`. */
+function isModuleNotFound(err: unknown): boolean {
+	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: unknown): boolean {
+	return (
+		err instanceof Error &&
+		err.message.includes("Router accessed before initialization")
+	);
+}