@c9up/aurora 0.1.3

package/src/Pages.ts

@@ -0,0 +1,164 @@
+/**
+ * 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";
+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 class Pages {
+	readonly root: string;
+	readonly urlPrefix: string;
+	readonly extension: string;
+
+	private readonly registry = new Map<string, PageFactory>();
+
+	constructor(config: PagesConfig) {
+		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<P>(name: string, factory: PageFactory<P>): void {
+		this.registry.set(name, factory as PageFactory);
+	}
+
+	/**
+	 * 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: string): Promise<PageFactory> {
+		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: { default?: unknown };
+		try {
+			mod = (await import(urlHref)) as { default?: unknown };
+		} catch (err) {
+			throw new Error(
+				`[aurora] page "${name}" not found at ${absolute} — ${
+					(err as Error).message
+				}`,
+			);
+		}
+		if (typeof mod.default !== "function") {
+			throw new Error(
+				`[aurora] page "${name}" must default-export a factory function`,
+			);
+		}
+		return mod.default as 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 {
+		assertSafeName(name);
+		return `${this.urlPrefix}/${name}${this.extension}`;
+	}
+}
+
+function assertSafeName(name: string): void {
+	if (
+		name.length === 0 ||
+		name.startsWith("/") ||
+		name.startsWith("\\") ||
+		name.includes("..") ||
+		name.includes("\0")
+	) {
+		throw new Error(`[aurora] illegal page name: ${JSON.stringify(name)}`);
+	}
+}

package/src/component.ts

@@ -0,0 +1,138 @@
+/**
+ * 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";
+
+/**
+ * Active component context. `onMount` / `onUnmount` push into it so a
+ * surrounding `render()` can dispose everything when the component
+ * unmounts. The stack lets `component()` nest safely.
+ */
+interface ComponentContext {
+	/** Cleanup functions to run at unmount. `onUnmount` pushes here. */
+	readonly cleanups: Disposer[];
+	/** Mount hooks queued via `onMount` — flushed after setup returns. */
+	readonly mountHooks: Array<EffectCallback>;
+}
+
+const contextStack: ComponentContext[] = [];
+
+function activeContext(): ComponentContext {
+	const ctx = contextStack[contextStack.length - 1];
+	if (!ctx) {
+		throw new Error(
+			"[aurora] onMount / onUnmount called outside component() — only valid inside a component setup function.",
+		);
+	}
+	return ctx;
+}
+
+/**
+ * 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 function component<P = Record<string, never>>(
+	setup: (props: P) => TemplateResult,
+): (props?: P) => TemplateResult {
+	return (props?: P) => {
+		const ctx: ComponentContext = {
+			cleanups: [],
+			mountHooks: [],
+		};
+		contextStack.push(ctx);
+		try {
+			const result = setup((props ?? ({} as P)) as P);
+			return wrapWithLifecycle(result, ctx);
+		} finally {
+			contextStack.pop();
+		}
+	};
+}
+
+/**
+ * Stitch the component context onto the returned TemplateResult so the
+ * outer renderer can flush mount hooks + register unmount cleanups
+ * automatically when this slot is mounted / removed.
+ *
+ * The mechanism is a `Symbol`-keyed handoff: the renderer's text-slot
+ * path (which handles nested TemplateResults) checks for this property
+ * and forwards the lifecycle.
+ */
+const COMPONENT_LIFECYCLE: unique symbol = Symbol.for("aurora:component");
+
+interface ComponentLifecycle {
+	mountHooks: ReadonlyArray<EffectCallback>;
+	cleanups: Disposer[];
+}
+
+function wrapWithLifecycle(
+	result: TemplateResult,
+	ctx: ComponentContext,
+): TemplateResult {
+	(result as { [COMPONENT_LIFECYCLE]?: ComponentLifecycle })[
+		COMPONENT_LIFECYCLE
+	] = {
+		mountHooks: ctx.mountHooks,
+		cleanups: ctx.cleanups,
+	};
+	return result;
+}
+
+/**
+ * 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 function readComponentLifecycle(
+	result: TemplateResult,
+): ComponentLifecycle | undefined {
+	return (result as { [COMPONENT_LIFECYCLE]?: ComponentLifecycle })[
+		COMPONENT_LIFECYCLE
+	];
+}
+
+// ─── Lifecycle ────────────────────────────────────────────────────
+
+/**
+ * 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 function onMount(fn: EffectCallback): void {
+	const ctx = activeContext();
+	ctx.mountHooks.push(fn);
+}
+
+/**
+ * Schedule a callback to run when the component unmounts. Equivalent
+ * to the cleanup return of `onMount` but available without a paired
+ * mount action.
+ */
+export function onUnmount(fn: () => void): void {
+	const ctx = activeContext();
+	ctx.cleanups.push(fn);
+}

package/src/html.ts

@@ -0,0 +1,296 @@
+/**
+ * Tagged-template HTML parser.
+ *
+ *   html`<button @click="${onClick}">${count}</button>`
+ *
+ * returns a `TemplateResult`. The first call with a given `strings` array
+ * compiles a `Template` (parsed `<template>` element + slot descriptors)
+ * and caches it; subsequent calls reuse the compiled artefact and only
+ * pair it with fresh `values`.
+ *
+ * The parser is intentionally minimal — it supports text interpolation
+ * (`>${x}<`), attribute interpolation (`attr="${x}"` and multi-slot
+ * `class="a ${x} b ${y}"`), boolean attributes (`?disabled="${x}"`), DOM
+ * properties (`.value="${x}"`), and event listeners (`@click="${fn}"`).
+ * No custom directives, no fragments-in-attribute-name, no comment-only
+ * placeholders.
+ */
+
+import {
+	type AttrSlot,
+	type BooleanAttrSlot,
+	type EventSlot,
+	isTemplateResult,
+	type PropSlot,
+	type Slot,
+	TEMPLATE_RESULT_BRAND,
+	type Template,
+	type TemplateResult,
+	type TextSlot,
+} from "./types.js";
+
+const TEMPLATE_CACHE = new WeakMap<TemplateStringsArray, Template>();
+
+/** Sentinel inserted at every `${...}` site. Read back during the walk. */
+const MARKER = "__aurora_slot_";
+
+/** Marker comment that takes a child slot inside a text region. */
+const TEXT_NODE_MARKER = `<!--${MARKER}-->`;
+
+/** Markup-friendly placeholder for slots inside attribute values. */
+function attrPlaceholder(i: number): string {
+	return `${MARKER}${i}__`;
+}
+
+/**
+ * Build the HTML string + remember which slots landed where. The classifier
+ * runs on the concatenated string; once we know each slot is either a
+ * text-region slot or an attribute-region slot, we emit the correct
+ * placeholder so the DOM parser doesn't choke (e.g. a `<!---->` comment
+ * cannot live inside an attribute value).
+ */
+interface RawSlot {
+	region: "text" | "attribute";
+}
+
+function classifySlots(strings: readonly string[]): RawSlot[] {
+	const result: RawSlot[] = [];
+	let insideTag = false;
+	let insideComment = false;
+	for (let i = 0; i < strings.length - 1; i++) {
+		const segment = strings[i];
+		for (let j = 0; j < segment.length; j++) {
+			if (insideComment) {
+				// Comments swallow everything (including stray `<` / `>`) up
+				// to the literal `-->` terminator; without this guard a
+				// `<!-- > -->` literal would flip the tag scanner mid-stride.
+				if (
+					segment[j] === "-" &&
+					segment[j + 1] === "-" &&
+					segment[j + 2] === ">"
+				) {
+					insideComment = false;
+					j += 2;
+				}
+				continue;
+			}
+			if (
+				!insideTag &&
+				segment[j] === "<" &&
+				segment[j + 1] === "!" &&
+				segment[j + 2] === "-" &&
+				segment[j + 3] === "-"
+			) {
+				insideComment = true;
+				j += 3;
+				continue;
+			}
+			const ch = segment[j];
+			if (!insideTag && ch === "<") insideTag = true;
+			else if (insideTag && ch === ">") insideTag = false;
+		}
+		result.push({ region: insideTag ? "attribute" : "text" });
+	}
+	return result;
+}
+
+/**
+ * Build the HTML markup to feed the `<template>` element.
+ *
+ * Slots in text regions are replaced with a `<!--__aurora_slot_-->` comment
+ * that survives DOM parsing. Slots in attribute regions are replaced with a
+ * unique string token like `__aurora_slot_3__` that the post-parse walk
+ * detects when scanning attribute values.
+ */
+function buildMarkup(
+	strings: readonly string[],
+	classification: readonly RawSlot[],
+): string {
+	let out = strings[0];
+	for (let i = 0; i < classification.length; i++) {
+		out +=
+			classification[i].region === "text"
+				? TEXT_NODE_MARKER
+				: attrPlaceholder(i);
+		out += strings[i + 1];
+	}
+	return out;
+}
+
+/**
+ * Walk the parsed fragment and collect a slot descriptor for every
+ * placeholder we emitted. The walk is depth-first, child-by-child, and
+ * records the integer path so `render()` can re-walk a clone without any
+ * string parsing.
+ */
+function collectSlots(
+	root: HTMLTemplateElement,
+	classification: readonly RawSlot[],
+): Slot[] {
+	const slots: Slot[] = [];
+	let slotIndex = 0;
+
+	// Classify one marker-bearing attribute into slot(s): `@event`, `?boolean`,
+	// `.prop`, or a (possibly multi-slot) regular attribute. Pushes the slot(s)
+	// and queues the attribute for removal from the inert template.
+	function classifyAttribute(
+		attr: Attr,
+		path: number[],
+		toRemove: string[],
+	): void {
+		const value = attr.value;
+		if (!value.includes(MARKER)) return;
+		const localPath = [...path];
+		if (attr.name.startsWith("@")) {
+			const slot: EventSlot = {
+				kind: "event",
+				path: localPath,
+				event: attr.name.slice(1),
+			};
+			slots.push(slot);
+			slotIndex++;
+			toRemove.push(attr.name);
+			return;
+		}
+		if (attr.name.startsWith("?")) {
+			const slot: BooleanAttrSlot = {
+				kind: "boolean-attr",
+				path: localPath,
+				name: attr.name.slice(1),
+			};
+			slots.push(slot);
+			slotIndex++;
+			toRemove.push(attr.name);
+			return;
+		}
+		if (attr.name.startsWith(".")) {
+			const slot: PropSlot = {
+				kind: "prop",
+				path: localPath,
+				name: attr.name.slice(1),
+			};
+			slots.push(slot);
+			slotIndex++;
+			toRemove.push(attr.name);
+			return;
+		}
+		// Regular attribute — may host one or more slots inline with static text.
+		// Strip the placeholder version (the renderer re-applies via setAttribute)
+		// so the inert template never carries the `__aurora_slot_0__` artefact.
+		const parts = value.split(/__aurora_slot_(\d+)__/);
+		// Even indices = static text, odd = slot indices. One slot with no
+		// surrounding static text → a "pure" attr slot; else carry static parts.
+		if (parts.length === 3 && parts[0] === "" && parts[2] === "") {
+			const slot: AttrSlot = { kind: "attr", path: localPath, name: attr.name };
+			slots.push(slot);
+			slotIndex++;
+		} else {
+			// Multi-slot attribute. Each slot points at the same `staticParts`
+			// array; consumers re-join on every update.
+			const staticParts: string[] = [];
+			const slotCountInThisAttr = (parts.length - 1) / 2;
+			for (let i = 0; i < parts.length; i += 2) {
+				staticParts.push(parts[i]);
+			}
+			for (let i = 0; i < slotCountInThisAttr; i++) {
+				const slot: AttrSlot = {
+					kind: "attr",
+					path: localPath,
+					name: attr.name,
+					staticParts,
+					staticPartIndex: i,
+				};
+				slots.push(slot);
+				slotIndex++;
+			}
+		}
+		toRemove.push(attr.name);
+	}
+
+	function visit(node: Node, path: number[]): void {
+		// Process children FIRST in reverse so a comment-marker we're about
+		// to remove never invalidates the index of a later sibling. But text
+		// slots also bring the node into existence — handle them with a
+		// stable path captured up front.
+		if (node.nodeType === 8 /* Comment */) {
+			const data = (node as Comment).data;
+			if (data === MARKER) {
+				if (slotIndex >= classification.length) return;
+				const cls = classification[slotIndex];
+				if (cls.region !== "text") {
+					throw new Error(
+						`[aurora] internal classification mismatch at slot ${slotIndex}`,
+					);
+				}
+				const slot: TextSlot = { kind: "text", path: [...path] };
+				slots.push(slot);
+				slotIndex++;
+			}
+			return;
+		}
+		if (node.nodeType === 1 /* Element */) {
+			const el = node as Element;
+			// Scan attributes — multiple slots can share one attribute.
+			// Collect attrs to remove AFTER iteration (mutating during it
+			// shifts indices on some DOM implementations).
+			const toRemove: string[] = [];
+			for (const attr of Array.from(el.attributes)) {
+				classifyAttribute(attr, path, toRemove);
+			}
+			for (const name of toRemove) el.removeAttribute(name);
+		}
+		// Recurse into children with their indices.
+		let childIndex = 0;
+		let child = node.firstChild;
+		while (child) {
+			const nextSibling: ChildNode | null = child.nextSibling;
+			visit(child, [...path, childIndex]);
+			child = nextSibling;
+			childIndex++;
+		}
+	}
+
+	visit(root.content, []);
+	return slots;
+}
+
+function compile(strings: TemplateStringsArray): Template {
+	const classification = classifySlots(strings);
+	const markup = buildMarkup(strings, classification);
+	const tpl = document.createElement("template");
+	tpl.innerHTML = markup;
+	const slots = collectSlots(tpl, classification);
+	return { element: tpl, slots };
+}
+
+/**
+ * Compile (and cache) the template for the given strings array. Exposed
+ * for the renderer + the SSR path; apps stick to `html`.
+ */
+export function getTemplate(strings: TemplateStringsArray): Template {
+	let cached = TEMPLATE_CACHE.get(strings);
+	if (!cached) {
+		cached = compile(strings);
+		TEMPLATE_CACHE.set(strings, cached);
+	}
+	return cached;
+}
+
+/**
+ * Tagged-template entrypoint. The `strings` array is reference-stable per
+ * source location (TC39 guarantee), so caching by reference is safe and
+ * O(1) on the hot render path.
+ */
+export function html(
+	strings: TemplateStringsArray,
+	...values: unknown[]
+): TemplateResult {
+	const result: TemplateResult = {
+		strings,
+		values,
+		[TEMPLATE_RESULT_BRAND]: true,
+	};
+	return result;
+}
+
+export { isTemplateResult };