@c9up/aurora 0.1.25 → 0.1.27

package/src/hydrate.ts

@@ -358,6 +358,12 @@ function hydrateTemplateResult(
 		childNodes: liveNodes,
 	} as unknown as ParentNode;
 
+	// An attribute interpolating several slots — `class="static ${a} ${b}"` — is
+	// ONE attribute value built from all of them plus the static segments in
+	// between. Binding each slot on its own would have the last writer win and
+	// wipe the statics, which is what render.ts already avoids server-side.
+	const multiGroups = new Map<string, MultiAttrGroup>();
+
 	for (let i = 0; i < tpl.slots.length; i++) {
 		const slot = tpl.slots[i];
 		const liveNode = resolvePathLive(syntheticRoot, slot.path, liveNodes);
@@ -373,6 +379,15 @@ function hydrateTemplateResult(
 			}
 			continue;
 		}
+		if (slot.kind === "attr" && slot.staticParts !== undefined) {
+			collectMultiAttr(
+				slot,
+				liveNode as Element,
+				result.values[i],
+				multiGroups,
+			);
+			continue;
+		}
 		hydrateSlot(
 			slot,
 			liveNode,
@@ -382,6 +397,65 @@ function hydrateTemplateResult(
 			markerCursor,
 		);
 	}
+
+	for (const group of multiGroups.values()) {
+		applyMultiAttrGroup(group, cleanups);
+	}
+}
+
+/** One attribute whose value is assembled from several slots. */
+interface MultiAttrGroup {
+	el: Element;
+	name: string;
+	staticParts: readonly string[];
+	values: unknown[];
+}
+
+function collectMultiAttr(
+	slot: AttrSlot,
+	el: Element,
+	value: unknown,
+	groups: Map<string, MultiAttrGroup>,
+): void {
+	if (!slot.staticParts) return;
+	const key = `${slot.name}::${(slot.path as readonly number[]).join(".")}`;
+	let group = groups.get(key);
+	if (!group) {
+		group = { el, name: slot.name, staticParts: slot.staticParts, values: [] };
+		groups.set(key, group);
+	}
+	group.values.push(value);
+}
+
+function applyMultiAttrGroup(
+	group: MultiAttrGroup,
+	cleanups: Disposer[],
+): void {
+	function join(): string {
+		let out = group.staticParts[0] ?? "";
+		for (let i = 0; i < group.values.length; i++) {
+			const v = group.values[i];
+			const resolved =
+				isSignal(v) || typeof v === "function" ? (v as () => unknown)() : v;
+			out += resolved == null || resolved === false ? "" : String(resolved);
+			out += group.staticParts[i + 1] ?? "";
+		}
+		return out;
+	}
+
+	const hasReactive = group.values.some(
+		(v) => isSignal(v) || typeof v === "function",
+	);
+	if (hasReactive) {
+		// SSR already wrote the joined value; re-joining on every tick is what
+		// keeps the statics in place when only one part changes.
+		cleanups.push(
+			effect(() => {
+				group.el.setAttribute(group.name, join());
+			}),
+		);
+	}
+	// Fully static groups need nothing: SSR wrote the final value.
 }
 
 /**

package/src/index.ts

@@ -100,6 +100,7 @@ export {
 } from "./liveRouter.js";
 export {
 	DEFAULT_LIVE_EVENT_PATH,
+	type LiveEventBody,
 	type LiveHttpContext,
 	type LiveHttpRouter,
 	type WireLiveEventsOptions,

package/src/live.ts

@@ -39,6 +39,7 @@ export {
 } from "./liveRouter.js";
 export {
 	DEFAULT_LIVE_EVENT_PATH,
+	type LiveEventBody,
 	type LiveHttpContext,
 	type LiveHttpRouter,
 	type WireLiveEventsOptions,

package/src/liveServer.ts

@@ -29,9 +29,19 @@ export interface LiveHttpContext {
 export interface WireLiveEventsOptions {
 	/** Route path for inbound events (must match the client transport). */
 	path?: string;
+	/**
+	 * Optional per-request guard. Return `false` to reject the event with 403.
+	 * Use this to enforce the same auth/CSRF/owner policy as the page that mounted
+	 * the live session. When omitted, aurora preserves the framework-agnostic
+	 * legacy behavior and expects the host route/middleware to guard the endpoint.
+	 */
+	authorize?: (
+		ctx: LiveHttpContext,
+		body: LiveEventBody,
+	) => boolean | Promise<boolean>;
 }
 
-interface LiveEventBody {
+export interface LiveEventBody {
 	id: string;
 	event: string;
 	payload?: unknown;
@@ -57,13 +67,26 @@ export function wireLiveEvents(
 	options: WireLiveEventsOptions = {},
 ): void {
 	const path = options.path ?? DEFAULT_LIVE_EVENT_PATH;
-	router.post(path, (ctx) => {
+	router.post(path, async (ctx) => {
 		const body = ctx.request.body();
 		if (!isLiveEventBody(body)) {
 			ctx.response.status(400);
 			ctx.response.json({ error: "live event requires { id, event }" });
 			return;
 		}
+		let authorized = true;
+		if (options.authorize) {
+			try {
+				authorized = await options.authorize(ctx, body);
+			} catch {
+				authorized = false;
+			}
+		}
+		if (!authorized) {
+			ctx.response.status(403);
+			ctx.response.json({ error: "forbidden live event" });
+			return;
+		}
 		const handled = live.event(body.id, body.event, body.payload);
 		if (!handled) {
 			ctx.response.status(404);

package/src/relay.ts

@@ -345,7 +345,15 @@ async function postHandshake(url: string, channel: string): Promise<void> {
 function retrieveXsrfToken(): string | null {
 	if (typeof document === "undefined") return null;
 	const match = document.cookie.match(/(?:^|;\s*)XSRF-TOKEN=([^;]*)/);
-	return match ? decodeURIComponent(match[1]) : null;
+	if (!match) return null;
+	try {
+		return decodeURIComponent(match[1]);
+	} catch {
+		// A malformed cookie must not break subscribe/unsubscribe handshakes. The
+		// server will reject an invalid token normally; the client should not throw
+		// before it even sends the request.
+		return match[1];
+	}
 }
 
 function safeJson<T>(raw: unknown): T | null {

package/src/render.ts

@@ -104,10 +104,20 @@ export function mount(
 	// after.
 	const multiGroups = new Map<string, MultiAttrGroup>();
 
+	// Resolve EVERY slot's node before applying any of them. Applying a text
+	// slot inserts nodes into the fragment, which shifts the child indices the
+	// remaining paths were computed against — so a slot sitting after a nested
+	// template (`${Icon()}${label}`) used to resolve to the wrong node, or to
+	// none, and silently never bound. Fragments exist precisely so a component
+	// needs no wrapper element; they must not cost the slots that follow them.
+	const resolved: Array<Node | null> = tpl.slots.map((slot) =>
+		resolvePath(fragment, slot.path),
+	);
+
 	for (let i = 0; i < tpl.slots.length; i++) {
 		const slot = tpl.slots[i];
-		const node = resolvePath(fragment, slot.path);
-		if (node === null) {
+		const node = resolved[i];
+		if (node === null || node === undefined) {
 			// Path didn't resolve — skip this binding rather than crash (see
 			// resolvePath). Degrades to a dead binding; the surrounding render
 			// (and any command driving it) survives.

package/src/route.ts

@@ -72,10 +72,19 @@ const DEFAULT_SHELL = (body: string, entry: string): string =>
 </head>
 <body>
 <div id="aurora-root">${body}</div>
-<script type="module" src="${entry}"></script>
+<script type="module" src="${escapeAttr(entry)}"></script>
 </body>
 </html>`;
 
+function escapeAttr(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
 /**
  * Build a Ream-compatible route handler that SSR-renders the given
  * factory and serves the full HTML document.

package/src/server/renderPage.ts

@@ -23,10 +23,11 @@
  *   </body>
  */
 
-import { setCookieStore } from "../browser.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setCookieStoreReader } from "../browser.js";
 import type { Pages } from "../Pages.js";
 import { renderToString } from "../ssr.js";
-import { setRouteManifest } from "../url.js";
+import { setRouteManifestReader } from "../url.js";
 
 /**
  * Structural slice of the host framework's response. Same shape
@@ -70,6 +71,29 @@ export interface RenderPageOptions {
 	 * targets.
 	 */
 	rootId?: string;
+	/**
+	 * Root element tag for the SSR + hydrated tree. Defaults to `div`.
+	 * Mirrors Inertia's root tag customization (`@inertia({ as: ... })`) while
+	 * keeping aurora independent from a template engine.
+	 */
+	rootTag?: string;
+	/**
+	 * Optional class attribute on the root element. Mirrors
+	 * `@inertia({ class: ... })`.
+	 */
+	rootClass?: string;
+	/**
+	 * Shared props merged into every page render before invoking the page factory.
+	 * Use this for global data such as user, flash and validation errors. A
+	 * function receives the current HTTP context and may be async, matching
+	 * Adonis/Inertia's request middleware `share()` model.
+	 */
+	shared?: SharedProps | SharedPropsResolver;
+	/**
+	 * Asset/version marker serialized with the page payload. Apps can use this to
+	 * detect stale client state when their frontend build changes.
+	 */
+	assetsVersion?: string;
 	/**
 	 * Named-route manifest (`name → path-pattern`) for the isomorphic
 	 * `urlFor()` helper — build it with Ream's `router.namedManifest()`. It is
@@ -92,11 +116,26 @@ export interface RenderPageOptions {
 	cookies?: string[];
 }
 
+export type SharedProps = Record<string, unknown>;
+export type SharedPropsResolver = (
+	ctx: RenderHttpContext,
+) => SharedProps | Promise<SharedProps>;
+
 /** A request that can read a cookie by name — the structural slice we need. */
 interface CookieReadableRequest {
 	cookie(name: string): string | null;
 }
 
+interface RenderScope {
+	cookies: Record<string, string>;
+	routes: Record<string, string>;
+}
+
+const renderScope = new AsyncLocalStorage<RenderScope>();
+
+setCookieStoreReader(() => renderScope.getStore()?.cookies);
+setRouteManifestReader(() => renderScope.getStore()?.routes);
+
 function isCookieReadable(request: unknown): request is CookieReadableRequest {
 	return (
 		typeof request === "object" &&
@@ -127,21 +166,31 @@ export async function renderPage<P>(
 	props: P,
 	options: RenderPageOptions = {},
 ): Promise<void> {
-	// Install the route manifest BEFORE rendering so a page calling `urlFor`
-	// during SSR resolves against the same map the client will get.
-	if (options.routes) setRouteManifest(options.routes);
-
-	// Seed the request's UI cookies so the page reads the SAME state server-side
-	// that the browser will after hydration. Set synchronously right before the
-	// (synchronous) render — read cookie signals at the top of the page.
-	setCookieStore(
-		options.cookies ? readRequestCookies(ctx.request, options.cookies) : {},
+	const scope: RenderScope = {
+		cookies: options.cookies
+			? readRequestCookies(ctx.request, options.cookies)
+			: {},
+		routes: options.routes ?? {},
+	};
+
+	return renderScope.run(scope, () =>
+		renderPageInScope(ctx, pages, name, props, options),
 	);
+}
 
+async function renderPageInScope<P>(
+	ctx: RenderHttpContext,
+	pages: Pages,
+	name: string,
+	props: P,
+	options: RenderPageOptions,
+): Promise<void> {
 	const factory = await pages.resolve(name);
+	const shared = await resolveSharedProps(ctx, options.shared);
+	const pageProps = mergeProps(shared, props);
 	// The factory must be invoked the SAME way client-side for hydrate
 	// to find matching slots — `Page(props)` is the contract.
-	const tree = await factory(props as never);
+	const tree = await factory(pageProps as never);
 	const body = renderToString(tree);
 
 	const importmap = {
@@ -149,6 +198,8 @@ export async function renderPage<P>(
 		...options.importmap,
 	};
 	const rootId = options.rootId ?? "aurora-root";
+	const rootTag = normalizeRootTag(options.rootTag ?? "div");
+	const rootClass = options.rootClass;
 	const lang = options.lang ?? "en";
 	const pageUrl = pages.urlFor(name);
 
@@ -161,13 +212,14 @@ export async function renderPage<P>(
 ${options.headExtra ?? ""}
 </head>
 <body>
-<div id="${escapeAttr(rootId)}">${body}</div>
+<${rootTag}${rootAttrs(rootId, rootClass)}>${body}</${rootTag}>
 <script id="aurora-page-data" type="application/json">${escapeJsonForScript({
 		name,
-		props,
+		props: pageProps,
 		url: pageUrl,
 		rootId,
 		routes: options.routes ?? {},
+		version: options.assetsVersion ?? null,
 	})}</script>
 <script type="module">
 import { hydrate, setRouteManifest } from '@c9up/aurora'
@@ -183,6 +235,40 @@ hydrate(document.getElementById(data.rootId), () => Page(data.props))
 	ctx.response.send(doc);
 }
 
+async function resolveSharedProps(
+	ctx: RenderHttpContext,
+	shared: RenderPageOptions["shared"],
+): Promise<SharedProps> {
+	if (!shared) return {};
+	return typeof shared === "function" ? shared(ctx) : shared;
+}
+
+function mergeProps<P>(shared: SharedProps, props: P): P | SharedProps {
+	if (Object.keys(shared).length === 0) return props;
+	if (isPlainRecord(props)) return { ...shared, ...props };
+	return { ...shared, page: props };
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		Object.getPrototypeOf(value) === Object.prototype
+	);
+}
+
+function normalizeRootTag(tag: string): string {
+	if (/^[a-z][a-z0-9-]*$/i.test(tag)) return tag.toLowerCase();
+	throw new Error(`[aurora] illegal root tag: ${JSON.stringify(tag)}`);
+}
+
+function rootAttrs(id: string, className: string | undefined): string {
+	const attrs = [`id="${escapeAttr(id)}"`];
+	if (className) attrs.push(`class="${escapeAttr(className)}"`);
+	return ` ${attrs.join(" ")}`;
+}
+
 function escapeAttr(value: string): string {
 	return value
 		.replace(/&/g, "&amp;")

package/src/server.ts

@@ -16,6 +16,8 @@ export {
 	type RenderPageOptions,
 	type RenderResponse,
 	renderPage,
+	type SharedProps,
+	type SharedPropsResolver,
 } from "./server/renderPage.js";
 export {
 	type AssetsHttpContext,

package/src/services/main.ts

@@ -26,6 +26,15 @@ export function getAurora(): AuroraManager | undefined {
 
 const aurora: AuroraManager = new Proxy({} as AuroraManager, {
 	get(_target, prop) {
+		// A module loader inspects what it imports before anyone uses it: it reads
+		// `then` to decide whether the namespace is thenable, and various symbols
+		// for interop and formatting. Throwing on those turns a plain
+		// `import { setX } from ".../services/main"` into a crash at import time,
+		// far from any real use. They are not members of what this stands in for,
+		// so answer undefined and let a genuine access be the one that reports.
+		if (typeof prop === "symbol" || prop === "then") {
+			return undefined;
+		}
 		if (!instance) {
 			throw new Error(
 				"[aurora] AuroraManager singleton accessed before AuroraProvider.boot() ran " +

package/src/url.ts

@@ -19,6 +19,23 @@
 
 let manifest: Record<string, string> = {};
 
+type RouteManifestReader = () => Record<string, string> | undefined;
+let routeManifestReader: RouteManifestReader | undefined;
+
+/**
+ * @internal Server-side hook used by `renderPage()` to provide a request-scoped
+ * route manifest without importing Node built-ins from this browser-safe module.
+ */
+export function setRouteManifestReader(
+	reader: RouteManifestReader | undefined,
+): void {
+	routeManifestReader = reader;
+}
+
+function activeManifest(): Record<string, string> {
+	return routeManifestReader?.() ?? manifest;
+}
+
 /**
  * Install the `name → path-pattern` map `urlFor` resolves against (e.g.
  * `{ 'users.show': '/users/:id' }`, from Ream's `router.namedManifest()`).
@@ -31,7 +48,7 @@ export function setRouteManifest(routes: Record<string, string>): void {
 
 /** The currently-installed route manifest (mainly for tests/introspection). */
 export function getRouteManifest(): Record<string, string> {
-	return { ...manifest };
+	return { ...activeManifest() };
 }
 
 /**
@@ -44,9 +61,10 @@ export function urlFor(
 	params?: Record<string, string | number>,
 	query?: Record<string, string | number>,
 ): string {
-	const pattern = manifest[name];
+	const routes = activeManifest();
+	const pattern = routes[name];
 	if (pattern === undefined) {
-		const known = Object.keys(manifest);
+		const known = Object.keys(routes);
 		throw new Error(
 			`[aurora] urlFor: unknown route '${name}'. ${
 				known.length > 0