@c9up/aurora 0.1.16 → 0.1.18

package/dist/AuroraManager.d.ts

@@ -22,6 +22,13 @@ export interface AuroraManagerConfig {
      * Override only if you want to serve a custom build.
      */
     auroraDistRoot?: string;
+    /**
+     * Filesystem path to `@c9up/comet`'s `dist/`. Defaults to the dist of the
+     * installed (optional-peer) `@c9up/comet` — resolved automatically so the
+     * RPC client's `import '@c9up/comet'` works in the no-bundler browser with
+     * zero app wiring. Left unserved when comet isn't installed (no RPC).
+     */
+    cometDistRoot?: string;
     /**
      * URL prefix the asset routes mount under. The aurora runtime is served
      * from `<assetsPrefix>/aurora/*` and the app's pages from
@@ -41,6 +48,10 @@ export declare class AuroraManager {
     readonly auroraAssetPath: string;
     /** Mount path for the app's pages — `<assetsPrefix>/pages`. */
     readonly pageAssetPath: string;
+    /** Mount path for the RPC client's `@c9up/comet` runtime — `<assetsPrefix>/comet`. */
+    readonly cometAssetPath: string;
+    /** Resolved `@c9up/comet` dist dir, or `null` when comet isn't installed. */
+    readonly cometDistRoot: string | null;
     constructor(config: AuroraManagerConfig);
     /**
      * SSR + hydrate + ship the document. The importmap default points
@@ -59,4 +70,10 @@ export declare class AuroraManager {
      * `GET /_assets/pages/*`.
      */
     pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void>;
+    /**
+     * Handler for `@c9up/comet`'s runtime (the RPC client). Mount on
+     * `GET <cometAssetPath>/*`. Returns `null` when comet isn't installed —
+     * the provider then skips the route (no RPC, nothing to serve).
+     */
+    cometAssetsHandler(): ((ctx: AssetsHttpContext) => Promise<void>) | null;
 }

package/dist/AuroraManager.js

@@ -15,8 +15,21 @@ 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";
+import { packageAssetDir, serveAssets, } from "./server/serveAssets.js";
 const DEFAULT_AURORA_DIST = resolvePath(dirname(fileURLToPath(import.meta.url)), "../dist");
+/**
+ * Resolve `@c9up/comet`'s dist dir, or `null` when it isn't installed. comet is
+ * aurora's OPTIONAL peer (only present when the app uses RPC), so a missing one
+ * is expected — aurora then simply doesn't serve it or add it to the importmap.
+ */
+function resolveCometDist() {
+    try {
+        return packageAssetDir("@c9up/comet");
+    }
+    catch {
+        return null;
+    }
+}
 /** Normalize an asset prefix: ensure a leading slash, drop trailing slashes. */
 function normalizePrefix(prefix) {
     const withLead = prefix.startsWith("/") ? prefix : `/${prefix}`;
@@ -31,10 +44,16 @@ export class AuroraManager {
     auroraAssetPath;
     /** Mount path for the app's pages — `<assetsPrefix>/pages`. */
     pageAssetPath;
+    /** Mount path for the RPC client's `@c9up/comet` runtime — `<assetsPrefix>/comet`. */
+    cometAssetPath;
+    /** Resolved `@c9up/comet` dist dir, or `null` when comet isn't installed. */
+    cometDistRoot;
     constructor(config) {
         this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/_assets");
         this.auroraAssetPath = `${this.assetsPrefix}/aurora`;
         this.pageAssetPath = `${this.assetsPrefix}/pages`;
+        this.cometAssetPath = `${this.assetsPrefix}/comet`;
+        this.cometDistRoot = config.cometDistRoot ?? resolveCometDist();
         // Pages serve their compiled JS from the same prefix unless the app
         // pins an explicit urlPrefix.
         this.pages = new Pages({
@@ -54,6 +73,12 @@ export class AuroraManager {
             ...options,
             importmap: {
                 "@c9up/aurora": `${this.auroraAssetPath}/index.js`,
+                // Auto-map @c9up/comet when installed so `@c9up/aurora/rpc`'s bare
+                // `import '@c9up/comet'` resolves in the no-bundler browser — no
+                // app-side importmap wiring. Omitted when comet isn't present.
+                ...(this.cometDistRoot
+                    ? { "@c9up/comet": `${this.cometAssetPath}/index.js` }
+                    : {}),
                 ...options?.importmap,
             },
         });
@@ -72,4 +97,14 @@ export class AuroraManager {
     pageAssetsHandler() {
         return serveAssets({ root: this.pages.root });
     }
+    /**
+     * Handler for `@c9up/comet`'s runtime (the RPC client). Mount on
+     * `GET <cometAssetPath>/*`. Returns `null` when comet isn't installed —
+     * the provider then skips the route (no RPC, nothing to serve).
+     */
+    cometAssetsHandler() {
+        return this.cometDistRoot
+            ? serveAssets({ root: this.cometDistRoot })
+            : null;
+    }
 }

package/dist/AuroraProvider.js

@@ -67,6 +67,13 @@ export default class AuroraProvider {
         // `/_assets`) — set `config.aurora.assetsPrefix` to change the scheme.
         router.get(`${manager.auroraAssetPath}/*`, adaptHandler(manager.auroraAssetsHandler()));
         router.get(`${manager.pageAssetPath}/*`, adaptHandler(manager.pageAssetsHandler()));
+        // Serve @c9up/comet's runtime so the RPC client's bare `import
+        // '@c9up/comet'` resolves in the browser. Skipped when comet isn't
+        // installed (optional peer — the app doesn't use RPC).
+        const cometHandler = manager.cometAssetsHandler();
+        if (cometHandler) {
+            router.get(`${manager.cometAssetPath}/*`, adaptHandler(cometHandler));
+        }
     }
     async ready() { }
     async shutdown() { }

package/dist/browser.d.ts

@@ -131,16 +131,64 @@ export interface CookieOptions {
     /** Restrict to HTTPS. */
     secure?: boolean;
 }
+/**
+ * Install the SSR cookie seed (`name → value`). Called by `renderPage` from its
+ * `cookies` allowlist; the hydrate bootstrap does NOT call it (the browser reads
+ * `document.cookie`). Replaces any previous seed.
+ */
+export declare function setCookieStore(values: Record<string, string>): void;
+/** The currently-installed SSR cookie seed (mainly for tests/introspection). */
+export declare function getCookieStore(): Record<string, string>;
 /**
  * SSR-safe cookie accessor — the one store {@link WebStorage} can't cover, for
- * values the server also reads. Reads return `null` during SSR; writes are a
- * no-op. Names and values are URL-encoded.
+ * values the server also reads. In the browser reads/writes hit
+ * `document.cookie`; during SSR reads come from the {@link setCookieStore} seed
+ * and writes are a no-op. Names and values are URL-encoded.
  */
 export declare const cookie: {
     get(name: string): string | null;
     set(name: string, value: string, options?: CookieOptions): void;
     remove(name: string, options?: Pick<CookieOptions, "path" | "domain">): void;
 };
+/**
+ * Maps a typed value to and from the string a cookie stores. Pass one to
+ * {@link cookieState} for non-string state (booleans, enums, JSON).
+ */
+export interface CookieCodec<T> {
+    /** Parse the raw cookie string into `T`. */
+    parse(raw: string): T;
+    /** Serialize `T` into the raw cookie string. */
+    serialize(value: T): string;
+}
+/** Codec for a boolean cookie, stored as `"1"` / `"0"`. */
+export declare const booleanCookie: CookieCodec<boolean>;
+/**
+ * Codec for a JSON-serializable value. A parse failure (malformed cookie) is
+ * surfaced by returning `fallback`, so a tampered cookie never throws mid-render.
+ */
+export declare function jsonCookie<T>(fallback: T): CookieCodec<T>;
+/**
+ * A {@link Signal} backed by a cookie — the isomorphic counterpart to
+ * {@link persistedSignal}. It is seeded from the cookie (the
+ * {@link setCookieStore} request seed during SSR, `document.cookie` in the
+ * browser) and persists every change back to the cookie via a reactive
+ * `effect`. Because the same seed is visible on both sides, a page renders the
+ * SAME markup server- and client-side — no hydration mismatch, no flash of the
+ * default state (e.g. a sidebar that animates open→collapsed on every load).
+ *
+ * Use {@link cookieSignal} for string state; pass a {@link CookieCodec} here for
+ * booleans/enums/JSON (e.g. {@link booleanCookie}). Created inside a component's
+ * setup, the persistence effect is disposed with it.
+ *
+ * Read it at the TOP of a page (before any `await`) so the SSR seed is current —
+ * see {@link setCookieStore}.
+ */
+export declare function cookieState<T>(name: string, initial: T, codec: CookieCodec<T>, options?: CookieOptions): Signal<T>;
+/**
+ * A {@link Signal} backed by a string cookie — {@link cookieState} with an
+ * identity codec, for the common case where the value is already a string.
+ */
+export declare function cookieSignal(name: string, initial: string, options?: CookieOptions): Signal<string>;
 /** Async clipboard access. Methods return `false`/`null` when unavailable. */
 export declare const clipboard: {
     /** Copy `text`. Returns whether it succeeded. */

package/dist/browser.js

@@ -289,15 +289,43 @@ export function queryParam(key) {
     }
     return sig;
 }
+/**
+ * SSR seed of the request's cookies — a `name → value` map installed by
+ * `renderPage` (server-side) before a page renders, so {@link cookie.get} and
+ * {@link cookieSignal} can read the SAME values during SSR that the browser
+ * will read from `document.cookie` after hydration. Without it the server has
+ * no view of the request cookies and renders default UI state → a flash /
+ * mismatch on hydration (the classic collapsed-sidebar flicker).
+ *
+ * Module-global by necessity (the page factory reads it ambiently). It is set
+ * synchronously immediately before the synchronous render, so read your cookie
+ * signals at the TOP of a page (before any `await`) to avoid a cross-request
+ * race under concurrent async page factories. In the browser it is unused —
+ * {@link cookie.get} reads `document.cookie` directly there.
+ */
+let cookieSeed = {};
+/**
+ * Install the SSR cookie seed (`name → value`). Called by `renderPage` from its
+ * `cookies` allowlist; the hydrate bootstrap does NOT call it (the browser reads
+ * `document.cookie`). Replaces any previous seed.
+ */
+export function setCookieStore(values) {
+    cookieSeed = { ...values };
+}
+/** The currently-installed SSR cookie seed (mainly for tests/introspection). */
+export function getCookieStore() {
+    return { ...cookieSeed };
+}
 /**
  * SSR-safe cookie accessor — the one store {@link WebStorage} can't cover, for
- * values the server also reads. Reads return `null` during SSR; writes are a
- * no-op. Names and values are URL-encoded.
+ * values the server also reads. In the browser reads/writes hit
+ * `document.cookie`; during SSR reads come from the {@link setCookieStore} seed
+ * and writes are a no-op. Names and values are URL-encoded.
  */
 export const cookie = {
     get(name) {
         if (typeof document === "undefined")
-            return null;
+            return cookieSeed[name] ?? null;
         const prefix = `${encodeURIComponent(name)}=`;
         for (const part of document.cookie.split("; ")) {
             if (part.startsWith(prefix)) {
@@ -330,6 +358,65 @@ export const cookie = {
         this.set(name, "", { ...options, maxAge: 0, expires: new Date(0) });
     },
 };
+/** Codec for a boolean cookie, stored as `"1"` / `"0"`. */
+export const booleanCookie = {
+    parse: (raw) => raw === "1" || raw === "true",
+    serialize: (value) => (value ? "1" : "0"),
+};
+/**
+ * Codec for a JSON-serializable value. A parse failure (malformed cookie) is
+ * surfaced by returning `fallback`, so a tampered cookie never throws mid-render.
+ */
+export function jsonCookie(fallback) {
+    return {
+        parse: (raw) => {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return fallback;
+            }
+        },
+        serialize: (value) => JSON.stringify(value),
+    };
+}
+/**
+ * A {@link Signal} backed by a cookie — the isomorphic counterpart to
+ * {@link persistedSignal}. It is seeded from the cookie (the
+ * {@link setCookieStore} request seed during SSR, `document.cookie` in the
+ * browser) and persists every change back to the cookie via a reactive
+ * `effect`. Because the same seed is visible on both sides, a page renders the
+ * SAME markup server- and client-side — no hydration mismatch, no flash of the
+ * default state (e.g. a sidebar that animates open→collapsed on every load).
+ *
+ * Use {@link cookieSignal} for string state; pass a {@link CookieCodec} here for
+ * booleans/enums/JSON (e.g. {@link booleanCookie}). Created inside a component's
+ * setup, the persistence effect is disposed with it.
+ *
+ * Read it at the TOP of a page (before any `await`) so the SSR seed is current —
+ * see {@link setCookieStore}.
+ */
+export function cookieState(name, initial, codec, options = {}) {
+    const raw = cookie.get(name);
+    const sig = signal(raw === null ? initial : codec.parse(raw));
+    // Mirror every change back to the cookie. Runs once immediately (a no-op
+    // write during SSR, where `cookie.set` bails) then on each change.
+    effect(() => {
+        cookie.set(name, codec.serialize(sig()), options);
+    });
+    return sig;
+}
+const stringCookie = {
+    parse: (raw) => raw,
+    serialize: (value) => value,
+};
+/**
+ * A {@link Signal} backed by a string cookie — {@link cookieState} with an
+ * identity codec, for the common case where the value is already a string.
+ */
+export function cookieSignal(name, initial, options = {}) {
+    return cookieState(name, initial, stringCookie, options);
+}
 // ─── Clipboard & Web Share ───────────────────────────────────────────
 /** Async clipboard access. Methods return `false`/`null` when unavailable. */
 export const clipboard = {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
-export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
+export type { CookieCodec, CookieOptions, PersistedSignalOptions, ShareData, StorageArea, WebStorageOptions, WindowSize, } from "./browser.js";
+export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forward, getCookieStore, hash, jsonCookie, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, setCookieStore, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { type ClassValue, clsx, cn, twMerge } from "./cn.js";
 export type { Command } from "./command.js";
 export { command } from "./command.js";
@@ -19,7 +19,6 @@ export { DEFAULT_LIVE_EVENT_PATH, type LiveHttpContext, type LiveHttpRouter, typ
 export { batch, effect, isSignal, memo, onCleanup, type ReadSignal, type Signal, signal, untrack, } from "./reactive.js";
 export { type Disposer, render } from "./render.js";
 export { type AuroraHttpContext, type AuroraResponse, type AuroraRouteConfig, auroraRoute, } from "./route.js";
-export { createRpcClient, isRpcError, type RpcCall, type RpcClient, type RpcClientOptions, RpcError, type RpcResult, } from "./rpc.js";
 export { renderToString } from "./ssr.js";
 export type { TemplateResult } from "./types.js";
 export { getRouteManifest, setRouteManifest, urlFor } from "./url.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { back, clipboard, cookie, forward, hash, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
+export { back, booleanCookie, clipboard, cookie, cookieSignal, cookieState, forward, getCookieStore, hash, jsonCookie, mediaQuery, navigate, online, persistedSignal, prefersDark, queryParam, redirect, reload, replace, session, setCookieStore, share, storage, visibility, WebStorage, windowSize, } from "./browser.js";
 export { clsx, cn, twMerge } from "./cn.js";
 export { command } from "./command.js";
 export { component, onMount, onUnmount } from "./component.js";
@@ -15,6 +15,5 @@ export { DEFAULT_LIVE_EVENT_PATH, wireLiveEvents, } from "./liveServer.js";
 export { batch, effect, isSignal, memo, onCleanup, signal, untrack, } from "./reactive.js";
 export { render } from "./render.js";
 export { auroraRoute, } from "./route.js";
-export { createRpcClient, isRpcError, RpcError, } from "./rpc.js";
 export { renderToString } from "./ssr.js";
 export { getRouteManifest, setRouteManifest, urlFor } from "./url.js";

package/dist/rpc.d.ts

@@ -1,17 +1,6 @@
-/**
- * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
- * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
- * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
- * headers, and timeouts.
- *
- *   const rpc = createRpcClient()                          // POST /rpc, same-origin
- *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
- *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
- *
- * Pairs with aurora's `command()` for reactive calls:
- *   const validate = command((p) => rpc.call('task.validate', p))
- */
 import { HttpClient } from "./http.js";
+export { isRpcError, type RpcCall, type RpcCallOptions, type RpcClient, RpcError, type RpcResult, } from "@c9up/comet";
+import type { RpcClient } from "@c9up/comet";
 export interface RpcClientOptions {
     /** Endpoint path. Default `/rpc` (matches RpcProvider's default). */
     url?: string;
@@ -20,36 +9,8 @@ export interface RpcClientOptions {
     /** Default headers — only used when no `http` client is supplied. */
     headers?: Record<string, string>;
 }
-/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
-export declare class RpcError extends Error {
-    readonly code: number;
-    readonly data?: unknown;
-    constructor(code: number, message: string, data?: unknown);
-}
-/** Type guard for {@link RpcError}. */
-export declare function isRpcError(value: unknown): value is RpcError;
-/** One call in a batch. `parse` optionally validates that call's result (cast-free). */
-export interface RpcCall<T = unknown> {
-    method: string;
-    params?: unknown;
-    parse?: (data: unknown) => T;
-}
-/** A settled batch entry — the result, or the JSON-RPC error for that call. */
-export type RpcResult<T = unknown> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: RpcError;
-};
-export interface RpcClient {
-    /**
-     * Call one method. Returns the result, or throws {@link RpcError} on a
-     * JSON-RPC error. Pass `parse` to validate the result at runtime (and skip
-     * the unchecked `T` assertion).
-     */
-    call<T = unknown>(method: string, params?: unknown, parse?: (data: unknown) => T): Promise<T>;
-    /** Send a JSON-RPC batch. Returns one settled entry per call, in request order. */
-    batch(calls: RpcCall[]): Promise<RpcResult[]>;
-}
+/**
+ * Create a JSON-RPC client bound to aurora's HttpClient transport. Inherits the
+ * supplied (or a fresh) HttpClient's base URL, auth headers, and timeouts.
+ */
 export declare function createRpcClient(options?: RpcClientOptions): RpcClient;

package/dist/rpc.js

@@ -1,97 +1,29 @@
 /**
- * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
- * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
- * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
- * headers, and timeouts.
+ * Browser JSON-RPC 2.0 client for Ream's RPC endpoint — aurora's thin binding
+ * over the agnostic {@link https://github.com/C9up/comet | @c9up/comet} client.
+ * It wires aurora's {@link HttpClient} (base URL, auth headers, timeouts) as
+ * comet's transport, and re-exports the protocol surface so call sites keep
+ * importing everything from `@c9up/aurora`.
  *
- *   const rpc = createRpcClient()                          // POST /rpc, same-origin
- *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
- *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
+ *   const rpc = createRpcClient()                              // POST /rpc, same-origin
+ *   const result = await rpc.call('task.validate', { id })     // typed via call<T>()
+ *   const user = await rpc.call('user.find', { id }, { parse: isUser }) // validated, cast-free
+ *   await rpc.call('slow.op', p, { signal: ac.signal })        // abortable
  *
  * Pairs with aurora's `command()` for reactive calls:
  *   const validate = command((p) => rpc.call('task.validate', p))
  */
+import { createRpcClient as createCometRpcClient } from "@c9up/comet";
 import { HttpClient } from "./http.js";
-/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
-export class RpcError extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.name = "RpcError";
-        this.code = code;
-        this.data = data;
-    }
-}
-/** Type guard for {@link RpcError}. */
-export function isRpcError(value) {
-    return value instanceof RpcError;
-}
-function isObject(value) {
-    return typeof value === "object" && value !== null;
-}
-/** Turn a JSON-RPC `error` member into an {@link RpcError}. */
-function toRpcError(error) {
-    if (isObject(error) &&
-        typeof error.code === "number" &&
-        typeof error.message === "string") {
-        return new RpcError(error.code, error.message, error.data);
-    }
-    return new RpcError(-32603, "Malformed JSON-RPC error envelope", error);
-}
+export { isRpcError, RpcError, } from "@c9up/comet";
+/**
+ * Create a JSON-RPC client bound to aurora's HttpClient transport. Inherits the
+ * supplied (or a fresh) HttpClient's base URL, auth headers, and timeouts.
+ */
 export function createRpcClient(options = {}) {
     const http = options.http ?? new HttpClient({ headers: options.headers });
-    const url = options.url ?? "/rpc";
-    let nextId = 0;
-    return {
-        async call(method, params, parse) {
-            const id = ++nextId;
-            const res = await http.post(url, {
-                jsonrpc: "2.0",
-                method,
-                params,
-                id,
-            });
-            if (!isObject(res)) {
-                throw new RpcError(-32603, `Malformed JSON-RPC response for "${method}"`);
-            }
-            if (res.error !== undefined)
-                throw toRpcError(res.error);
-            // Result boundary — the same unchecked `T` assertion HttpClient uses,
-            // with `parse` as the cast-free, runtime-validated escape hatch.
-            return parse ? parse(res.result) : res.result;
-        },
-        async batch(calls) {
-            if (calls.length === 0)
-                return [];
-            const requests = calls.map((c, index) => ({
-                jsonrpc: "2.0",
-                method: c.method,
-                params: c.params,
-                id: index, // index = request position; responses are matched back by id
-            }));
-            const res = await http.post(url, requests);
-            if (!Array.isArray(res)) {
-                throw new RpcError(-32603, "Malformed JSON-RPC batch response");
-            }
-            const byId = new Map();
-            for (const item of res)
-                if (isObject(item))
-                    byId.set(item.id, item);
-            return calls.map((c, index) => {
-                const envelope = byId.get(index);
-                if (!envelope) {
-                    return {
-                        ok: false,
-                        error: new RpcError(-32603, `No response for "${c.method}"`),
-                    };
-                }
-                if (envelope.error !== undefined) {
-                    return { ok: false, error: toRpcError(envelope.error) };
-                }
-                const value = c.parse ? c.parse(envelope.result) : envelope.result;
-                return { ok: true, value };
-            });
-        },
-    };
+    return createCometRpcClient({
+        url: options.url,
+        transport: (url, body, { signal }) => http.post(url, body, { signal }),
+    });
 }

package/dist/server/renderPage.d.ts

@@ -66,5 +66,17 @@ export interface RenderPageOptions {
      * in SSR and the browser. Omit if the app doesn't use `urlFor`.
      */
     routes?: Record<string, string>;
+    /**
+     * Allowlist of cookie names to seed into the SSR cookie store so a page can
+     * read them during render via aurora's `cookieSignal` / `cookie.get` — the
+     * server then renders the SAME UI state the browser will (no hydration flash
+     * of the default, e.g. a sidebar animating open→collapsed on every load).
+     *
+     * Only the NAMED cookies are read (from `ctx.request`); they are NOT
+     * serialized into the page — the browser reads them from `document.cookie`.
+     * NEVER list a session / signed / encrypted / `httpOnly` cookie here: those
+     * must stay server-only. Use plain, JS-readable cookies for UI state.
+     */
+    cookies?: string[];
 }
 export declare function renderPage<P>(ctx: RenderHttpContext, pages: Pages, name: string, props: P, options?: RenderPageOptions): Promise<void>;

package/dist/server/renderPage.js

@@ -22,13 +22,36 @@
  *     </script>
  *   </body>
  */
+import { setCookieStore } from "../browser.js";
 import { renderToString } from "../ssr.js";
 import { setRouteManifest } from "../url.js";
+function isCookieReadable(request) {
+    return (typeof request === "object" &&
+        request !== null &&
+        "cookie" in request &&
+        typeof request.cookie === "function");
+}
+/** Read the allowlisted cookies off the request into a `name → value` seed. */
+function readRequestCookies(request, names) {
+    if (!isCookieReadable(request))
+        return {};
+    const seed = {};
+    for (const name of names) {
+        const value = request.cookie(name);
+        if (value !== null)
+            seed[name] = value;
+    }
+    return seed;
+}
 export async function renderPage(ctx, pages, name, props, options = {}) {
     // 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 factory = await pages.resolve(name);
     // The factory must be invoked the SAME way client-side for hydrate
     // to find matching slots — `Page(props)` is the contract.

package/dist/server/serveAssets.d.ts

@@ -9,6 +9,17 @@
  * and writes to `ctx.response`. Any context that satisfies
  * `AssetsHttpContext` (Ream, AdonisJS, anything duck-typed) works.
  */
+/**
+ * Absolute dist directory of an installed package — for mounting its pre-built
+ * ESM as browser assets (`serveAssets({ root: packageAssetDir('@c9up/x') })`).
+ *
+ * Uses `import.meta.resolve`, which honours the package's `exports` `import`
+ * condition — so it works for `@c9up/*` import-only packages where
+ * `createRequire().resolve()` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` (their
+ * `exports` carry no `require` condition, and `main` is ignored once `exports`
+ * exists). Throws if the package isn't installed/resolvable.
+ */
+export declare function packageAssetDir(specifier: string): string;
 export interface AssetsRequest {
     /**
      * Read the wildcard `*` segment of the matched route. Most routers

package/dist/server/serveAssets.js

@@ -10,7 +10,21 @@
  * `AssetsHttpContext` (Ream, AdonisJS, anything duck-typed) works.
  */
 import { readFile, realpath } from "node:fs/promises";
-import { extname, join, resolve as resolvePath, sep } from "node:path";
+import { dirname, extname, join, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Absolute dist directory of an installed package — for mounting its pre-built
+ * ESM as browser assets (`serveAssets({ root: packageAssetDir('@c9up/x') })`).
+ *
+ * Uses `import.meta.resolve`, which honours the package's `exports` `import`
+ * condition — so it works for `@c9up/*` import-only packages where
+ * `createRequire().resolve()` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` (their
+ * `exports` carry no `require` condition, and `main` is ignored once `exports`
+ * exists). Throws if the package isn't installed/resolvable.
+ */
+export function packageAssetDir(specifier) {
+    return dirname(fileURLToPath(import.meta.resolve(specifier)));
+}
 const CONTENT_TYPES = {
     ".js": "text/javascript; charset=utf-8",
     ".mjs": "text/javascript; charset=utf-8",

package/dist/server.d.ts

@@ -1,4 +1,4 @@
 export { AuroraManager, type AuroraManagerConfig } from "./AuroraManager.js";
 export { type PageFactory, Pages, type PagesConfig } from "./Pages.js";
 export { type RenderHttpContext, type RenderPageOptions, type RenderResponse, renderPage, } from "./server/renderPage.js";
-export { type AssetsHttpContext, type AssetsRequest, type AssetsResponse, type ServeAssetsOptions, serveAssets, } from "./server/serveAssets.js";
+export { type AssetsHttpContext, type AssetsRequest, type AssetsResponse, packageAssetDir, type ServeAssetsOptions, serveAssets, } from "./server/serveAssets.js";

package/dist/server.js

@@ -7,4 +7,4 @@
 export { AuroraManager } from "./AuroraManager.js";
 export { Pages } from "./Pages.js";
 export { renderPage, } from "./server/renderPage.js";
-export { serveAssets, } from "./server/serveAssets.js";
+export { packageAssetDir, serveAssets, } from "./server/serveAssets.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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",
@@ -34,17 +34,26 @@
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "import": "./dist/rpc.js"
     }
   },
   "peerDependencies": {
+    "@c9up/comet": "^0.1.0",
     "@c9up/ream": "^0.1.0"
   },
   "peerDependenciesMeta": {
+    "@c9up/comet": {
+      "optional": true
+    },
     "@c9up/ream": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@c9up/comet": "^0.1.0",
     "@types/node": "^22.19.15",
     "@vitest/browser": "4.1.6",
     "@vitest/browser-playwright": "^4.1.9",

package/src/AuroraManager.ts

@@ -20,7 +20,11 @@ import {
 	type RenderPageOptions,
 	renderPage,
 } from "./server/renderPage.js";
-import { type AssetsHttpContext, serveAssets } from "./server/serveAssets.js";
+import {
+	type AssetsHttpContext,
+	packageAssetDir,
+	serveAssets,
+} from "./server/serveAssets.js";
 
 export interface AuroraManagerConfig {
 	pages: PagesConfig;
@@ -30,6 +34,13 @@ export interface AuroraManagerConfig {
 	 * Override only if you want to serve a custom build.
 	 */
 	auroraDistRoot?: string;
+	/**
+	 * Filesystem path to `@c9up/comet`'s `dist/`. Defaults to the dist of the
+	 * installed (optional-peer) `@c9up/comet` — resolved automatically so the
+	 * RPC client's `import '@c9up/comet'` works in the no-bundler browser with
+	 * zero app wiring. Left unserved when comet isn't installed (no RPC).
+	 */
+	cometDistRoot?: string;
 	/**
 	 * URL prefix the asset routes mount under. The aurora runtime is served
 	 * from `<assetsPrefix>/aurora/*` and the app's pages from
@@ -46,6 +57,19 @@ const DEFAULT_AURORA_DIST = resolvePath(
 	"../dist",
 );
 
+/**
+ * Resolve `@c9up/comet`'s dist dir, or `null` when it isn't installed. comet is
+ * aurora's OPTIONAL peer (only present when the app uses RPC), so a missing one
+ * is expected — aurora then simply doesn't serve it or add it to the importmap.
+ */
+function resolveCometDist(): string | null {
+	try {
+		return packageAssetDir("@c9up/comet");
+	} catch {
+		return null;
+	}
+}
+
 /** Normalize an asset prefix: ensure a leading slash, drop trailing slashes. */
 function normalizePrefix(prefix: string): string {
 	const withLead = prefix.startsWith("/") ? prefix : `/${prefix}`;
@@ -61,11 +85,17 @@ export class AuroraManager {
 	readonly auroraAssetPath: string;
 	/** Mount path for the app's pages — `<assetsPrefix>/pages`. */
 	readonly pageAssetPath: string;
+	/** Mount path for the RPC client's `@c9up/comet` runtime — `<assetsPrefix>/comet`. */
+	readonly cometAssetPath: string;
+	/** Resolved `@c9up/comet` dist dir, or `null` when comet isn't installed. */
+	readonly cometDistRoot: string | null;
 
 	constructor(config: AuroraManagerConfig) {
 		this.assetsPrefix = normalizePrefix(config.assetsPrefix ?? "/_assets");
 		this.auroraAssetPath = `${this.assetsPrefix}/aurora`;
 		this.pageAssetPath = `${this.assetsPrefix}/pages`;
+		this.cometAssetPath = `${this.assetsPrefix}/comet`;
+		this.cometDistRoot = config.cometDistRoot ?? resolveCometDist();
 		// Pages serve their compiled JS from the same prefix unless the app
 		// pins an explicit urlPrefix.
 		this.pages = new Pages({
@@ -91,6 +121,12 @@ export class AuroraManager {
 			...options,
 			importmap: {
 				"@c9up/aurora": `${this.auroraAssetPath}/index.js`,
+				// Auto-map @c9up/comet when installed so `@c9up/aurora/rpc`'s bare
+				// `import '@c9up/comet'` resolves in the no-bundler browser — no
+				// app-side importmap wiring. Omitted when comet isn't present.
+				...(this.cometDistRoot
+					? { "@c9up/comet": `${this.cometAssetPath}/index.js` }
+					: {}),
 				...options?.importmap,
 			},
 		});
@@ -111,4 +147,15 @@ export class AuroraManager {
 	pageAssetsHandler(): (ctx: AssetsHttpContext) => Promise<void> {
 		return serveAssets({ root: this.pages.root });
 	}
+
+	/**
+	 * Handler for `@c9up/comet`'s runtime (the RPC client). Mount on
+	 * `GET <cometAssetPath>/*`. Returns `null` when comet isn't installed —
+	 * the provider then skips the route (no RPC, nothing to serve).
+	 */
+	cometAssetsHandler(): ((ctx: AssetsHttpContext) => Promise<void>) | null {
+		return this.cometDistRoot
+			? serveAssets({ root: this.cometDistRoot })
+			: null;
+	}
 }

package/src/AuroraProvider.ts

@@ -101,6 +101,13 @@ export default class AuroraProvider {
 			`${manager.pageAssetPath}/*`,
 			adaptHandler(manager.pageAssetsHandler()),
 		);
+		// Serve @c9up/comet's runtime so the RPC client's bare `import
+		// '@c9up/comet'` resolves in the browser. Skipped when comet isn't
+		// installed (optional peer — the app doesn't use RPC).
+		const cometHandler = manager.cometAssetsHandler();
+		if (cometHandler) {
+			router.get(`${manager.cometAssetPath}/*`, adaptHandler(cometHandler));
+		}
 	}
 
 	async ready(): Promise<void> {}

package/src/browser.ts

@@ -384,14 +384,45 @@ export interface CookieOptions {
 	secure?: boolean;
 }
 
+/**
+ * SSR seed of the request's cookies — a `name → value` map installed by
+ * `renderPage` (server-side) before a page renders, so {@link cookie.get} and
+ * {@link cookieSignal} can read the SAME values during SSR that the browser
+ * will read from `document.cookie` after hydration. Without it the server has
+ * no view of the request cookies and renders default UI state → a flash /
+ * mismatch on hydration (the classic collapsed-sidebar flicker).
+ *
+ * Module-global by necessity (the page factory reads it ambiently). It is set
+ * synchronously immediately before the synchronous render, so read your cookie
+ * signals at the TOP of a page (before any `await`) to avoid a cross-request
+ * race under concurrent async page factories. In the browser it is unused —
+ * {@link cookie.get} reads `document.cookie` directly there.
+ */
+let cookieSeed: Record<string, string> = {};
+
+/**
+ * Install the SSR cookie seed (`name → value`). Called by `renderPage` from its
+ * `cookies` allowlist; the hydrate bootstrap does NOT call it (the browser reads
+ * `document.cookie`). Replaces any previous seed.
+ */
+export function setCookieStore(values: Record<string, string>): void {
+	cookieSeed = { ...values };
+}
+
+/** The currently-installed SSR cookie seed (mainly for tests/introspection). */
+export function getCookieStore(): Record<string, string> {
+	return { ...cookieSeed };
+}
+
 /**
  * SSR-safe cookie accessor — the one store {@link WebStorage} can't cover, for
- * values the server also reads. Reads return `null` during SSR; writes are a
- * no-op. Names and values are URL-encoded.
+ * values the server also reads. In the browser reads/writes hit
+ * `document.cookie`; during SSR reads come from the {@link setCookieStore} seed
+ * and writes are a no-op. Names and values are URL-encoded.
  */
 export const cookie = {
 	get(name: string): string | null {
-		if (typeof document === "undefined") return null;
+		if (typeof document === "undefined") return cookieSeed[name] ?? null;
 		const prefix = `${encodeURIComponent(name)}=`;
 		for (const part of document.cookie.split("; ")) {
 			if (part.startsWith(prefix)) {
@@ -422,6 +453,91 @@ export const cookie = {
 	},
 };
 
+/**
+ * Maps a typed value to and from the string a cookie stores. Pass one to
+ * {@link cookieState} for non-string state (booleans, enums, JSON).
+ */
+export interface CookieCodec<T> {
+	/** Parse the raw cookie string into `T`. */
+	parse(raw: string): T;
+	/** Serialize `T` into the raw cookie string. */
+	serialize(value: T): string;
+}
+
+/** Codec for a boolean cookie, stored as `"1"` / `"0"`. */
+export const booleanCookie: CookieCodec<boolean> = {
+	parse: (raw) => raw === "1" || raw === "true",
+	serialize: (value) => (value ? "1" : "0"),
+};
+
+/**
+ * Codec for a JSON-serializable value. A parse failure (malformed cookie) is
+ * surfaced by returning `fallback`, so a tampered cookie never throws mid-render.
+ */
+export function jsonCookie<T>(fallback: T): CookieCodec<T> {
+	return {
+		parse: (raw) => {
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return fallback;
+			}
+		},
+		serialize: (value) => JSON.stringify(value),
+	};
+}
+
+/**
+ * A {@link Signal} backed by a cookie — the isomorphic counterpart to
+ * {@link persistedSignal}. It is seeded from the cookie (the
+ * {@link setCookieStore} request seed during SSR, `document.cookie` in the
+ * browser) and persists every change back to the cookie via a reactive
+ * `effect`. Because the same seed is visible on both sides, a page renders the
+ * SAME markup server- and client-side — no hydration mismatch, no flash of the
+ * default state (e.g. a sidebar that animates open→collapsed on every load).
+ *
+ * Use {@link cookieSignal} for string state; pass a {@link CookieCodec} here for
+ * booleans/enums/JSON (e.g. {@link booleanCookie}). Created inside a component's
+ * setup, the persistence effect is disposed with it.
+ *
+ * Read it at the TOP of a page (before any `await`) so the SSR seed is current —
+ * see {@link setCookieStore}.
+ */
+export function cookieState<T>(
+	name: string,
+	initial: T,
+	codec: CookieCodec<T>,
+	options: CookieOptions = {},
+): Signal<T> {
+	const raw = cookie.get(name);
+	const sig = signal<T>(raw === null ? initial : codec.parse(raw));
+
+	// Mirror every change back to the cookie. Runs once immediately (a no-op
+	// write during SSR, where `cookie.set` bails) then on each change.
+	effect(() => {
+		cookie.set(name, codec.serialize(sig()), options);
+	});
+
+	return sig;
+}
+
+const stringCookie: CookieCodec<string> = {
+	parse: (raw) => raw,
+	serialize: (value) => value,
+};
+
+/**
+ * A {@link Signal} backed by a string cookie — {@link cookieState} with an
+ * identity codec, for the common case where the value is already a string.
+ */
+export function cookieSignal(
+	name: string,
+	initial: string,
+	options: CookieOptions = {},
+): Signal<string> {
+	return cookieState(name, initial, stringCookie, options);
+}
+
 // ─── Clipboard & Web Share ───────────────────────────────────────────
 
 /** Async clipboard access. Methods return `false`/`null` when unavailable. */

package/src/index.ts

@@ -5,6 +5,7 @@
 // this barrel is what lets a browser bundle import the client primitives without
 // the bundler dragging Node built-ins through the import graph.
 export type {
+	CookieCodec,
 	CookieOptions,
 	PersistedSignalOptions,
 	ShareData,
@@ -14,10 +15,15 @@ export type {
 } from "./browser.js";
 export {
 	back,
+	booleanCookie,
 	clipboard,
 	cookie,
+	cookieSignal,
+	cookieState,
 	forward,
+	getCookieStore,
 	hash,
+	jsonCookie,
 	mediaQuery,
 	navigate,
 	online,
@@ -28,6 +34,7 @@ export {
 	reload,
 	replace,
 	session,
+	setCookieStore,
 	share,
 	storage,
 	visibility,
@@ -116,15 +123,6 @@ export {
 	type AuroraRouteConfig,
 	auroraRoute,
 } from "./route.js";
-export {
-	createRpcClient,
-	isRpcError,
-	type RpcCall,
-	type RpcClient,
-	type RpcClientOptions,
-	RpcError,
-	type RpcResult,
-} from "./rpc.js";
 export { renderToString } from "./ssr.js";
 export type { TemplateResult } from "./types.js";
 export { getRouteManifest, setRouteManifest, urlFor } from "./url.js";

package/src/rpc.ts

@@ -1,18 +1,32 @@
 /**
- * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
- * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
- * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
- * headers, and timeouts.
+ * Browser JSON-RPC 2.0 client for Ream's RPC endpoint — aurora's thin binding
+ * over the agnostic {@link https://github.com/C9up/comet | @c9up/comet} client.
+ * It wires aurora's {@link HttpClient} (base URL, auth headers, timeouts) as
+ * comet's transport, and re-exports the protocol surface so call sites keep
+ * importing everything from `@c9up/aurora`.
  *
- *   const rpc = createRpcClient()                          // POST /rpc, same-origin
- *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
- *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
+ *   const rpc = createRpcClient()                              // POST /rpc, same-origin
+ *   const result = await rpc.call('task.validate', { id })     // typed via call<T>()
+ *   const user = await rpc.call('user.find', { id }, { parse: isUser }) // validated, cast-free
+ *   await rpc.call('slow.op', p, { signal: ac.signal })        // abortable
  *
  * Pairs with aurora's `command()` for reactive calls:
  *   const validate = command((p) => rpc.call('task.validate', p))
  */
+import { createRpcClient as createCometRpcClient } from "@c9up/comet";
 import { HttpClient } from "./http.js";
 
+export {
+	isRpcError,
+	type RpcCall,
+	type RpcCallOptions,
+	type RpcClient,
+	RpcError,
+	type RpcResult,
+} from "@c9up/comet";
+
+import type { RpcClient } from "@c9up/comet";
+
 export interface RpcClientOptions {
 	/** Endpoint path. Default `/rpc` (matches RpcProvider's default). */
 	url?: string;
@@ -22,124 +36,15 @@ export interface RpcClientOptions {
 	headers?: Record<string, string>;
 }
 
-/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
-export class RpcError extends Error {
-	readonly code: number;
-	readonly data?: unknown;
-	constructor(code: number, message: string, data?: unknown) {
-		super(message);
-		this.name = "RpcError";
-		this.code = code;
-		this.data = data;
-	}
-}
-
-/** Type guard for {@link RpcError}. */
-export function isRpcError(value: unknown): value is RpcError {
-	return value instanceof RpcError;
-}
-
-/** One call in a batch. `parse` optionally validates that call's result (cast-free). */
-export interface RpcCall<T = unknown> {
-	method: string;
-	params?: unknown;
-	parse?: (data: unknown) => T;
-}
-
-/** A settled batch entry — the result, or the JSON-RPC error for that call. */
-export type RpcResult<T = unknown> =
-	| { ok: true; value: T }
-	| { ok: false; error: RpcError };
-
-export interface RpcClient {
-	/**
-	 * Call one method. Returns the result, or throws {@link RpcError} on a
-	 * JSON-RPC error. Pass `parse` to validate the result at runtime (and skip
-	 * the unchecked `T` assertion).
-	 */
-	call<T = unknown>(
-		method: string,
-		params?: unknown,
-		parse?: (data: unknown) => T,
-	): Promise<T>;
-	/** Send a JSON-RPC batch. Returns one settled entry per call, in request order. */
-	batch(calls: RpcCall[]): Promise<RpcResult[]>;
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
-/** Turn a JSON-RPC `error` member into an {@link RpcError}. */
-function toRpcError(error: unknown): RpcError {
-	if (
-		isObject(error) &&
-		typeof error.code === "number" &&
-		typeof error.message === "string"
-	) {
-		return new RpcError(error.code, error.message, error.data);
-	}
-	return new RpcError(-32603, "Malformed JSON-RPC error envelope", error);
-}
-
+/**
+ * Create a JSON-RPC client bound to aurora's HttpClient transport. Inherits the
+ * supplied (or a fresh) HttpClient's base URL, auth headers, and timeouts.
+ */
 export function createRpcClient(options: RpcClientOptions = {}): RpcClient {
 	const http = options.http ?? new HttpClient({ headers: options.headers });
-	const url = options.url ?? "/rpc";
-	let nextId = 0;
-
-	return {
-		async call<T>(
-			method: string,
-			params?: unknown,
-			parse?: (data: unknown) => T,
-		): Promise<T> {
-			const id = ++nextId;
-			const res = await http.post<unknown>(url, {
-				jsonrpc: "2.0",
-				method,
-				params,
-				id,
-			});
-			if (!isObject(res)) {
-				throw new RpcError(
-					-32603,
-					`Malformed JSON-RPC response for "${method}"`,
-				);
-			}
-			if (res.error !== undefined) throw toRpcError(res.error);
-			// Result boundary — the same unchecked `T` assertion HttpClient uses,
-			// with `parse` as the cast-free, runtime-validated escape hatch.
-			return parse ? parse(res.result) : (res.result as T);
-		},
-
-		async batch(calls: RpcCall[]): Promise<RpcResult[]> {
-			if (calls.length === 0) return [];
-			const requests = calls.map((c, index) => ({
-				jsonrpc: "2.0",
-				method: c.method,
-				params: c.params,
-				id: index, // index = request position; responses are matched back by id
-			}));
-			const res = await http.post<unknown>(url, requests);
-			if (!Array.isArray(res)) {
-				throw new RpcError(-32603, "Malformed JSON-RPC batch response");
-			}
-			const byId = new Map<unknown, Record<string, unknown>>();
-			for (const item of res) if (isObject(item)) byId.set(item.id, item);
-			return calls.map((c, index) => {
-				const envelope = byId.get(index);
-				if (!envelope) {
-					return {
-						ok: false,
-						error: new RpcError(-32603, `No response for "${c.method}"`),
-					};
-				}
-				if (envelope.error !== undefined) {
-					return { ok: false, error: toRpcError(envelope.error) };
-				}
-				const value = c.parse ? c.parse(envelope.result) : envelope.result;
-				return { ok: true, value };
-			});
-		},
-	};
+	return createCometRpcClient({
+		url: options.url,
+		transport: (url, body, { signal }) =>
+			http.post<unknown>(url, body, { signal }),
+	});
 }

package/src/server/renderPage.ts

@@ -23,6 +23,7 @@
  *   </body>
  */
 
+import { setCookieStore } from "../browser.js";
 import type { Pages } from "../Pages.js";
 import { renderToString } from "../ssr.js";
 import { setRouteManifest } from "../url.js";
@@ -71,6 +72,46 @@ export interface RenderPageOptions {
 	 * in SSR and the browser. Omit if the app doesn't use `urlFor`.
 	 */
 	routes?: Record<string, string>;
+	/**
+	 * Allowlist of cookie names to seed into the SSR cookie store so a page can
+	 * read them during render via aurora's `cookieSignal` / `cookie.get` — the
+	 * server then renders the SAME UI state the browser will (no hydration flash
+	 * of the default, e.g. a sidebar animating open→collapsed on every load).
+	 *
+	 * Only the NAMED cookies are read (from `ctx.request`); they are NOT
+	 * serialized into the page — the browser reads them from `document.cookie`.
+	 * NEVER list a session / signed / encrypted / `httpOnly` cookie here: those
+	 * must stay server-only. Use plain, JS-readable cookies for UI state.
+	 */
+	cookies?: string[];
+}
+
+/** A request that can read a cookie by name — the structural slice we need. */
+interface CookieReadableRequest {
+	cookie(name: string): string | null;
+}
+
+function isCookieReadable(request: unknown): request is CookieReadableRequest {
+	return (
+		typeof request === "object" &&
+		request !== null &&
+		"cookie" in request &&
+		typeof request.cookie === "function"
+	);
+}
+
+/** Read the allowlisted cookies off the request into a `name → value` seed. */
+function readRequestCookies(
+	request: unknown,
+	names: string[],
+): Record<string, string> {
+	if (!isCookieReadable(request)) return {};
+	const seed: Record<string, string> = {};
+	for (const name of names) {
+		const value = request.cookie(name);
+		if (value !== null) seed[name] = value;
+	}
+	return seed;
 }
 
 export async function renderPage<P>(
@@ -84,6 +125,13 @@ export async function renderPage<P>(
 	// 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 factory = await pages.resolve(name);
 	// The factory must be invoked the SAME way client-side for hydrate
 	// to find matching slots — `Page(props)` is the contract.

package/src/server/serveAssets.ts

@@ -11,7 +11,22 @@
  */
 
 import { readFile, realpath } from "node:fs/promises";
-import { extname, join, resolve as resolvePath, sep } from "node:path";
+import { dirname, extname, join, resolve as resolvePath, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Absolute dist directory of an installed package — for mounting its pre-built
+ * ESM as browser assets (`serveAssets({ root: packageAssetDir('@c9up/x') })`).
+ *
+ * Uses `import.meta.resolve`, which honours the package's `exports` `import`
+ * condition — so it works for `@c9up/*` import-only packages where
+ * `createRequire().resolve()` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` (their
+ * `exports` carry no `require` condition, and `main` is ignored once `exports`
+ * exists). Throws if the package isn't installed/resolvable.
+ */
+export function packageAssetDir(specifier: string): string {
+	return dirname(fileURLToPath(import.meta.resolve(specifier)));
+}
 
 const CONTENT_TYPES: Record<string, string> = {
 	".js": "text/javascript; charset=utf-8",

package/src/server.ts

@@ -17,6 +17,7 @@ export {
 	type AssetsHttpContext,
 	type AssetsRequest,
 	type AssetsResponse,
+	packageAssetDir,
 	type ServeAssetsOptions,
 	serveAssets,
 } from "./server/serveAssets.js";