@c9up/aurora 0.1.15 → 0.1.17

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/hydrate.js

@@ -358,29 +358,11 @@ function hydrateSlot(slot, node, value, cleanups, mountHooks, markerCursor) {
     }
 }
 /**
- * Hydrate a text slot. SSR inlined the value as a text node (or skipped
- * it for null/false/undefined). We locate the **first text node sibling
- * preceding the path's terminal index** — that's where SSR wrote the
- * value — and wire an effect that overwrites its `data` on changes.
- *
- * For reactive values (signals/functions), the effect updates the
- * existing text node in place. For nested TemplateResults, we
- * recursively hydrate against the captured sibling range.
- */
-/**
- * First text node inside a marker pair's range, or a fresh empty one inserted
- * before the end marker (when the SSR value was empty → no text node yet).
+ * Hydrate a text slot against its SSR boundary-marker pair. A reactive slot
+ * (signal/function) always goes through the swap-capable structured path so a
+ * value that changes type (scalar ↔ template ↔ array) re-renders correctly; a
+ * direct template/array adopts its SSR range once; a static scalar is left as-is.
  */
-function reactiveTextNode(pair) {
-    for (let n = pair.start.nextSibling; n !== null && n !== pair.end; n = n.nextSibling) {
-        if (n.nodeType === 3 /* TEXT */)
-            return n;
-    }
-    const doc = pair.end.ownerDocument ?? document;
-    const fresh = doc.createTextNode("");
-    pair.end.parentNode?.insertBefore(fresh, pair.end);
-    return fresh;
-}
 function hydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCursor) {
     // Every text slot is SSR-wrapped in a <!--$-->…<!--/$--> pair, and its path
     // resolves (via collapseMarkerRanges) to the start marker. Consume the
@@ -395,39 +377,32 @@ function hydrateTextSlot(commentMarker, value, cleanups, mountHooks, markerCurso
     const reactiveFn = isSignal(value) || typeof value === "function"
         ? value
         : null;
-    const current = reactiveFn ? reactiveFn() : value;
-    // Structured value (nested template / array): reactive → swap on change;
-    // direct → adopt the SSR range once (inner bindings wired against it).
-    if (isTemplateResult(current) || Array.isArray(current)) {
-        if (reactiveFn) {
-            hydrateReactiveStructured(reactiveFn, pair, cleanups, mountHooks, markerCursor);
-            return;
-        }
+    // Reactive slot — its value TYPE can change across renders (scalar ↔ template
+    // ↔ array), e.g. `${() => collapsed() ? '' : html`<span>…</span>`}`. Always
+    // use the swap-capable structured path: its effect re-renders the value
+    // (whatever type) into the marker range via renderValueToNodes. Locking a
+    // reactive slot to a scalar text-node effect (based on its FIRST value) would
+    // String() a later template/array into "[object Object]".
+    if (reactiveFn) {
+        hydrateReactiveStructured(reactiveFn, pair, cleanups, mountHooks, markerCursor);
+        return;
+    }
+    // Non-reactive (direct) value — adopt the SSR range once.
+    if (isTemplateResult(value) || Array.isArray(value)) {
         const range = [];
         for (let n = pair.start.nextSibling; n !== null && n !== pair.end; n = n.nextSibling) {
             range.push(n);
         }
-        if (isTemplateResult(current)) {
-            hydrateTemplateResult(current, range, cleanups, mountHooks, markerCursor);
+        if (isTemplateResult(value)) {
+            hydrateTemplateResult(value, range, cleanups, mountHooks, markerCursor);
         }
-        else if (Array.isArray(current)) {
-            // Direct (non-reactive) array — hydrate each item so its inner marker
-            // pairs are consumed and the cursor stays aligned (same as a reactive
-            // array's first run).
-            hydrateArrayItems(current, range, cleanups, mountHooks, markerCursor);
+        else if (Array.isArray(value)) {
+            // Direct array — hydrate each item so its inner marker pairs are
+            // consumed and the cursor stays aligned.
+            hydrateArrayItems(value, range, cleanups, mountHooks, markerCursor);
         }
-        return;
-    }
-    // Scalar: a reactive scalar updates the range's text node on change; a static
-    // scalar is already rendered between the markers (nothing to wire).
-    if (reactiveFn) {
-        const textNode = reactiveTextNode(pair);
-        const dispose = effect(() => {
-            const v = reactiveFn();
-            textNode.data = v == null || v === false ? "" : String(v);
-        });
-        cleanups.push(dispose);
     }
+    // else: static scalar — already rendered between the markers.
 }
 /**
  * Pre-marker fallback — best-effort hydration when the SSR markup carries no

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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/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/hydrate.ts

@@ -481,33 +481,11 @@ function hydrateSlot(
 }
 
 /**
- * Hydrate a text slot. SSR inlined the value as a text node (or skipped
- * it for null/false/undefined). We locate the **first text node sibling
- * preceding the path's terminal index** — that's where SSR wrote the
- * value — and wire an effect that overwrites its `data` on changes.
- *
- * For reactive values (signals/functions), the effect updates the
- * existing text node in place. For nested TemplateResults, we
- * recursively hydrate against the captured sibling range.
- */
-/**
- * First text node inside a marker pair's range, or a fresh empty one inserted
- * before the end marker (when the SSR value was empty → no text node yet).
+ * Hydrate a text slot against its SSR boundary-marker pair. A reactive slot
+ * (signal/function) always goes through the swap-capable structured path so a
+ * value that changes type (scalar ↔ template ↔ array) re-renders correctly; a
+ * direct template/array adopts its SSR range once; a static scalar is left as-is.
  */
-function reactiveTextNode(pair: MarkerPair): Text {
-	for (
-		let n = pair.start.nextSibling;
-		n !== null && n !== pair.end;
-		n = n.nextSibling
-	) {
-		if (n.nodeType === 3 /* TEXT */) return n as Text;
-	}
-	const doc = pair.end.ownerDocument ?? document;
-	const fresh = doc.createTextNode("");
-	pair.end.parentNode?.insertBefore(fresh, pair.end);
-	return fresh;
-}
-
 function hydrateTextSlot(
 	commentMarker: Node,
 	value: unknown,
@@ -536,21 +514,26 @@ function hydrateTextSlot(
 		isSignal(value) || typeof value === "function"
 			? (value as () => unknown)
 			: null;
-	const current = reactiveFn ? reactiveFn() : value;
 
-	// Structured value (nested template / array): reactive → swap on change;
-	// direct → adopt the SSR range once (inner bindings wired against it).
-	if (isTemplateResult(current) || Array.isArray(current)) {
-		if (reactiveFn) {
-			hydrateReactiveStructured(
-				reactiveFn,
-				pair,
-				cleanups,
-				mountHooks,
-				markerCursor,
-			);
-			return;
-		}
+	// Reactive slot — its value TYPE can change across renders (scalar ↔ template
+	// ↔ array), e.g. `${() => collapsed() ? '' : html`<span>…</span>`}`. Always
+	// use the swap-capable structured path: its effect re-renders the value
+	// (whatever type) into the marker range via renderValueToNodes. Locking a
+	// reactive slot to a scalar text-node effect (based on its FIRST value) would
+	// String() a later template/array into "[object Object]".
+	if (reactiveFn) {
+		hydrateReactiveStructured(
+			reactiveFn,
+			pair,
+			cleanups,
+			mountHooks,
+			markerCursor,
+		);
+		return;
+	}
+
+	// Non-reactive (direct) value — adopt the SSR range once.
+	if (isTemplateResult(value) || Array.isArray(value)) {
 		const range: ChildNode[] = [];
 		for (
 			let n = pair.start.nextSibling;
@@ -559,27 +542,15 @@ function hydrateTextSlot(
 		) {
 			range.push(n as ChildNode);
 		}
-		if (isTemplateResult(current)) {
-			hydrateTemplateResult(current, range, cleanups, mountHooks, markerCursor);
-		} else if (Array.isArray(current)) {
-			// Direct (non-reactive) array — hydrate each item so its inner marker
-			// pairs are consumed and the cursor stays aligned (same as a reactive
-			// array's first run).
-			hydrateArrayItems(current, range, cleanups, mountHooks, markerCursor);
+		if (isTemplateResult(value)) {
+			hydrateTemplateResult(value, range, cleanups, mountHooks, markerCursor);
+		} else if (Array.isArray(value)) {
+			// Direct array — hydrate each item so its inner marker pairs are
+			// consumed and the cursor stays aligned.
+			hydrateArrayItems(value, range, cleanups, mountHooks, markerCursor);
 		}
-		return;
-	}
-
-	// Scalar: a reactive scalar updates the range's text node on change; a static
-	// scalar is already rendered between the markers (nothing to wire).
-	if (reactiveFn) {
-		const textNode = reactiveTextNode(pair);
-		const dispose = effect(() => {
-			const v = reactiveFn();
-			textNode.data = v == null || v === false ? "" : String(v);
-		});
-		cleanups.push(dispose);
 	}
+	// else: static scalar — already rendered between the markers.
 }
 
 /**

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.