@c9up/aurora 0.1.21 → 0.1.23

package/dist/browser.d.ts

@@ -31,10 +31,14 @@ export interface WebStorageOptions {
     area?: StorageArea;
 }
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -45,13 +49,31 @@ export declare class WebStorage {
     constructor(options?: WebStorageOptions);
     /** The on-disk key for `key`, namespaced by the configured prefix. */
     fullKey(key: string): string;
-    get<T>(key: string): T | null;
-    set(key: string, value: unknown): void;
+    /**
+     * Read the raw string at `key` — a thin, SSR-safe pass-through over
+     * `localStorage.getItem` (returns `null` on the server or a missing key).
+     * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+     * structured values.
+     */
+    get(key: string): string | null;
+    /**
+     * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+     * errors are swallowed — best-effort). No encoding, like
+     * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+     */
+    set(key: string, value: string): void;
+    /**
+     * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+     * missing key, or malformed JSON. Pair with {@link setJSON}.
+     */
+    getJSON<T>(key: string): T | null;
+    /** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+    setJSON(key: string, value: unknown): void;
     /** Whether `key` is present (and not the server). */
     has(key: string): boolean;
     remove(key: string): void;
-    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
-    getOrSet<T>(key: string, factory: () => T): T;
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
+    getOrSet(key: string, factory: () => string): string;
     /** Keys in this store, prefix stripped. Empty array during SSR. */
     keys(): string[];
     /** Remove this store's keys. With no prefix this clears the whole area. */

package/dist/browser.js

@@ -29,10 +29,14 @@ export function reload() {
     }
 }
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -56,31 +60,53 @@ export class WebStorage {
     fullKey(key) {
         return this.#prefix + key;
     }
+    /**
+     * Read the raw string at `key` — a thin, SSR-safe pass-through over
+     * `localStorage.getItem` (returns `null` on the server or a missing key).
+     * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+     * structured values.
+     */
     get(key) {
         const backend = this.#backend();
         if (!backend)
             return null;
-        const raw = backend.getItem(this.fullKey(key));
-        if (raw === null)
-            return null;
-        try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return null;
-        }
+        return backend.getItem(this.fullKey(key));
     }
+    /**
+     * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+     * errors are swallowed — best-effort). No encoding, like
+     * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+     */
     set(key, value) {
         const backend = this.#backend();
         if (!backend)
             return;
         try {
-            backend.setItem(this.fullKey(key), JSON.stringify(value));
+            backend.setItem(this.fullKey(key), value);
         }
         catch {
             // QuotaExceededError / Safari private mode — best-effort write.
         }
     }
+    /**
+     * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+     * missing key, or malformed JSON. Pair with {@link setJSON}.
+     */
+    getJSON(key) {
+        const raw = this.get(key);
+        if (raw === null)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+    setJSON(key, value) {
+        this.set(key, JSON.stringify(value));
+    }
     /** Whether `key` is present (and not the server). */
     has(key) {
         const backend = this.#backend();
@@ -91,7 +117,7 @@ export class WebStorage {
     remove(key) {
         this.#backend()?.removeItem(this.fullKey(key));
     }
-    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
     getOrSet(key, factory) {
         const existing = this.get(key);
         if (existing !== null)
@@ -148,11 +174,12 @@ export const session = new WebStorage({ area: "session" });
  */
 export function persistedSignal(key, initial, options = {}) {
     const store = new WebStorage(options);
-    const stored = store.get(key);
+    const stored = store.getJSON(key);
     const sig = signal(stored !== null ? stored : initial);
     // Mirror every change back to storage; runs once immediately, then on change.
+    // JSON so any T (object, number, boolean, string) round-trips.
     effect(() => {
-        store.set(key, sig());
+        store.setJSON(key, sig());
     });
     if ((options.crossTab ?? true) &&
         (options.area ?? "local") === "local" &&

package/dist/live.d.ts

@@ -1,60 +1,20 @@
 /**
- * Live components — server-resident reactive UI. The state lives on the server
- * as ordinary aurora signals; this module turns a fine-grained signal change
- * into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering the
- * whole component. That precision — each signal already knows which template
- * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ * `@c9up/aurora/live` barrel — the whole Live surface behind ONE subpath.
  *
- * This is the transport-agnostic CORE (Stage 1): mount a session, render its
- * initial HTML, dispatch events that mutate signals, and drain / subscribe to
- * the patches produced. Wiring patches over `@c9up/relay` (SSE down, POST up)
- * and the thin client applier live in later stages.
+ * The transport-agnostic core (`mountLiveSession` + its types) lives in
+ * `./liveSession.js`; the transport stack (broadcast / client / registry /
+ * router / server) builds on it. Re-exporting everything here keeps the niche
+ * surface behind a single subpath and keeps the main `.` barrel lean (it no
+ * longer eager-pulls these into every browser graph), consistent with how
+ * `./ssr`, `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
  *
- * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`, so it
- * sits in the main barrel alongside the rest of aurora's runtime.
+ * The core lives in a SEPARATE module (not inline here) so the transport files
+ * import it directly from `./liveSession.js` rather than through this barrel —
+ * which would otherwise form an import cycle (barrel → transport → barrel).
  */
-import type { TemplateResult } from "./types.js";
-/** A precise per-slot update: slot index (positional in the template) + value. */
-export interface SlotPatch {
-    slot: number;
-    value: string;
-}
-/** A live component: its reactive view + named event handlers that mutate it. */
-export interface LiveComponentDefinition {
-    /** The reactive view. Slots reading signals become live-patchable. */
-    view: TemplateResult;
-    /**
-     * Event handlers, by name. A client interaction (`@click="increment"`)
-     * dispatches one of these; it mutates the component's signals, which the
-     * patch tracker turns into a `{slot, value}` patch.
-     */
-    handlers?: Record<string, (payload?: unknown) => void>;
-}
-/** A mounted live component instance — one per connected client session. */
-export interface LiveSession {
-    /** Initial server-side render (the first full-HTML response). */
-    renderToString(): string;
-    /** Run a named handler (mutates signals); emits a patch for the batch. */
-    dispatch(event: string, payload?: unknown): void;
-    /** Collect + clear the patches accumulated since the last drain (pull model). */
-    drainPatches(): SlotPatch[];
-    /**
-     * Subscribe to patches as they are produced (push model — what the relay
-     * transport hooks into). Use `onPatch` OR `drainPatches`, not both.
-     */
-    onPatch(listener: (patch: SlotPatch[]) => void): () => void;
-    /** Stop every effect — call on client disconnect to free the session. */
-    dispose(): void;
-}
-/**
- * Mount a live session from a definition factory. Call once per connected
- * client: the factory's signals become that session's private state. To SHARE
- * state across sessions, close the factory over a signal created OUTSIDE it —
- * every session then reads the same signal and patches on its change.
- */
-export declare function mountLiveSession(factory: () => LiveComponentDefinition): LiveSession;
 export { connectPatches, type LiveStore, liveStore, type RelayBroadcaster, } from "./liveBroadcast.js";
 export { buildLiveTransport, type LiveClientOptions, type LiveClientTransport, type LiveHttpPoster, liveClient, type RelaySubscribeClient, } from "./liveClient.js";
 export { createLiveRegistry, type LiveRegistry, type LiveSessionHandle, } from "./liveRegistry.js";
 export { createLiveRouter, type LiveMount, type LiveRouter, } from "./liveRouter.js";
 export { DEFAULT_LIVE_EVENT_PATH, type LiveHttpContext, type LiveHttpRouter, type WireLiveEventsOptions, wireLiveEvents, } from "./liveServer.js";
+export { type LiveComponentDefinition, type LiveSession, mountLiveSession, type SlotPatch, } from "./liveSession.js";

package/dist/live.js

@@ -1,108 +1,20 @@
 /**
- * Live components — server-resident reactive UI. The state lives on the server
- * as ordinary aurora signals; this module turns a fine-grained signal change
- * into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering the
- * whole component. That precision — each signal already knows which template
- * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ * `@c9up/aurora/live` barrel — the whole Live surface behind ONE subpath.
  *
- * This is the transport-agnostic CORE (Stage 1): mount a session, render its
- * initial HTML, dispatch events that mutate signals, and drain / subscribe to
- * the patches produced. Wiring patches over `@c9up/relay` (SSE down, POST up)
- * and the thin client applier live in later stages.
+ * The transport-agnostic core (`mountLiveSession` + its types) lives in
+ * `./liveSession.js`; the transport stack (broadcast / client / registry /
+ * router / server) builds on it. Re-exporting everything here keeps the niche
+ * surface behind a single subpath and keeps the main `.` barrel lean (it no
+ * longer eager-pulls these into every browser graph), consistent with how
+ * `./ssr`, `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
  *
- * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`, so it
- * sits in the main barrel alongside the rest of aurora's runtime.
+ * The core lives in a SEPARATE module (not inline here) so the transport files
+ * import it directly from `./liveSession.js` rather than through this barrel —
+ * which would otherwise form an import cycle (barrel → transport → barrel).
  */
-import { effect, isSignal } from "./reactive.js";
-import { renderToString } from "./ssr.js";
-/**
- * Mount a live session from a definition factory. Call once per connected
- * client: the factory's signals become that session's private state. To SHARE
- * state across sessions, close the factory over a signal created OUTSIDE it —
- * every session then reads the same signal and patches on its change.
- */
-export function mountLiveSession(factory) {
-    const { view, handlers = {} } = factory();
-    const listeners = new Set();
-    // slot → latest value. `pending` = current (un-flushed) batch; `buffer` =
-    // accumulated for pull consumers. Both keyed by slot so repeated writes in
-    // one batch collapse to the last value.
-    const pending = new Map();
-    const buffer = new Map();
-    let priming = true;
-    let flushScheduled = false;
-    const flush = () => {
-        flushScheduled = false;
-        if (pending.size === 0)
-            return;
-        const patch = [];
-        for (const [slot, value] of pending) {
-            patch.push({ slot, value });
-            buffer.set(slot, value);
-        }
-        pending.clear();
-        for (const listener of listeners)
-            listener(patch);
-    };
-    const scheduleFlush = () => {
-        if (flushScheduled)
-            return;
-        flushScheduled = true;
-        queueMicrotask(flush);
-    };
-    // One fine-grained effect per reactive slot. The priming run only
-    // subscribes; later runs (a signal changed) record the slot's new value.
-    const stops = view.values.map((value, slot) => {
-        if (!isSignal(value) && typeof value !== "function")
-            return () => { };
-        return effect(() => {
-            const next = String(value());
-            if (priming)
-                return;
-            pending.set(slot, next);
-            scheduleFlush();
-        });
-    });
-    priming = false;
-    return {
-        renderToString: () => renderToString(view),
-        dispatch(event, payload) {
-            const handler = handlers[event];
-            if (!handler)
-                return;
-            handler(payload);
-            flush(); // synchronous — one patch per dispatch (batches the handler's writes)
-        },
-        drainPatches() {
-            flush();
-            const patch = [];
-            for (const [slot, value] of buffer)
-                patch.push({ slot, value });
-            buffer.clear();
-            return patch;
-        },
-        onPatch(listener) {
-            listeners.add(listener);
-            return () => listeners.delete(listener);
-        },
-        dispose() {
-            for (const stop of stops)
-                stop();
-            listeners.clear();
-            pending.clear();
-            buffer.clear();
-        },
-    };
-}
-// ─── `@c9up/aurora/live` barrel ──────────────────────────────────────
-//
-// The Live stack (broadcast / client / registry / router / server) is
-// re-exported here so the whole niche surface lives behind ONE subpath,
-// `@c9up/aurora/live` — keeping the main `.` barrel lean (it no longer
-// eager-pulls these into every browser graph), consistent with how `./ssr`,
-// `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
 export { connectPatches, liveStore, } from "./liveBroadcast.js";
 export { buildLiveTransport, liveClient, } from "./liveClient.js";
 export { createLiveRegistry, } from "./liveRegistry.js";
 export { createLiveRouter, } from "./liveRouter.js";
 export { DEFAULT_LIVE_EVENT_PATH, wireLiveEvents, } from "./liveServer.js";
+export { mountLiveSession, } from "./liveSession.js";

package/dist/liveBroadcast.d.ts

@@ -14,7 +14,7 @@
  * one mutation → one patch computed once → relay fans it out to all subscribers
  * (O(1) compute, O(N) network).
  */
-import { type LiveComponentDefinition, type LiveSession } from "./live.js";
+import { type LiveComponentDefinition, type LiveSession } from "./liveSession.js";
 /**
  * Minimal relay surface aurora needs. The real `@c9up/relay` `Relay` satisfies
  * it (`broadcast(channel, data) → recipient count`); aurora never imports it.

package/dist/liveBroadcast.js

@@ -14,7 +14,7 @@
  * one mutation → one patch computed once → relay fans it out to all subscribers
  * (O(1) compute, O(N) network).
  */
-import { mountLiveSession, } from "./live.js";
+import { mountLiveSession, } from "./liveSession.js";
 /**
  * Pipe a session's patches onto a relay channel as they are produced. Returns
  * an unsubscribe. Each patch becomes one `broadcast(channel, patch)`.

package/dist/liveClient.d.ts

@@ -14,7 +14,7 @@
  * `subscribe` to `@c9up/aurora/relay`'s `relay().subscribe` and `post` to an
  * `HttpClient`. Browser-only (uses the DOM) — part of the client barrel.
  */
-import type { SlotPatch } from "./live.js";
+import type { SlotPatch } from "./liveSession.js";
 import type { TemplateResult } from "./types.js";
 /** The transport the live client needs: a patch subscription + an event POST. */
 export interface LiveClientTransport {

package/dist/liveRegistry.d.ts

@@ -10,7 +10,7 @@
  * `get(id)?.dispatch(...)`; disconnect → `disposeOwner(uid)`. Transport-agnostic
  * and node-free (only `mountLiveSession` + `crypto.randomUUID`, both isomorphic).
  */
-import { type LiveComponentDefinition, type LiveSession } from "./live.js";
+import { type LiveComponentDefinition, type LiveSession } from "./liveSession.js";
 /** A mounted instance: its id, the owner (e.g. relay uid), and the session. */
 export interface LiveSessionHandle {
     id: string;

package/dist/liveRegistry.js

@@ -10,7 +10,7 @@
  * `get(id)?.dispatch(...)`; disconnect → `disposeOwner(uid)`. Transport-agnostic
  * and node-free (only `mountLiveSession` + `crypto.randomUUID`, both isomorphic).
  */
-import { mountLiveSession, } from "./live.js";
+import { mountLiveSession, } from "./liveSession.js";
 /** Create an isolated live-session registry (one per app / per relay instance). */
 export function createLiveRegistry() {
     const defs = new Map();

package/dist/liveSession.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Live components — server-resident reactive UI CORE. The state lives on the
+ * server as ordinary aurora signals; this module turns a fine-grained signal
+ * change into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering
+ * the whole component. That precision — each signal already knows which template
+ * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ *
+ * This is the transport-agnostic core: mount a session, render its initial HTML,
+ * dispatch events that mutate signals, and drain / subscribe to the patches
+ * produced. The transport stack (broadcast / client / registry / router /
+ * server) builds ON this and re-exports through the `./live.js` barrel — kept in
+ * a separate module so those transport files import the core WITHOUT forming an
+ * import cycle back through the barrel.
+ *
+ * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`.
+ */
+import type { TemplateResult } from "./types.js";
+/** A precise per-slot update: slot index (positional in the template) + value. */
+export interface SlotPatch {
+    slot: number;
+    value: string;
+}
+/** A live component: its reactive view + named event handlers that mutate it. */
+export interface LiveComponentDefinition {
+    /** The reactive view. Slots reading signals become live-patchable. */
+    view: TemplateResult;
+    /**
+     * Event handlers, by name. A client interaction (`@click="increment"`)
+     * dispatches one of these; it mutates the component's signals, which the
+     * patch tracker turns into a `{slot, value}` patch.
+     */
+    handlers?: Record<string, (payload?: unknown) => void>;
+}
+/** A mounted live component instance — one per connected client session. */
+export interface LiveSession {
+    /** Initial server-side render (the first full-HTML response). */
+    renderToString(): string;
+    /** Run a named handler (mutates signals); emits a patch for the batch. */
+    dispatch(event: string, payload?: unknown): void;
+    /** Collect + clear the patches accumulated since the last drain (pull model). */
+    drainPatches(): SlotPatch[];
+    /**
+     * Subscribe to patches as they are produced (push model — what the relay
+     * transport hooks into). Use `onPatch` OR `drainPatches`, not both.
+     */
+    onPatch(listener: (patch: SlotPatch[]) => void): () => void;
+    /** Stop every effect — call on client disconnect to free the session. */
+    dispose(): void;
+}
+/**
+ * Mount a live session from a definition factory. Call once per connected
+ * client: the factory's signals become that session's private state. To SHARE
+ * state across sessions, close the factory over a signal created OUTSIDE it —
+ * every session then reads the same signal and patches on its change.
+ */
+export declare function mountLiveSession(factory: () => LiveComponentDefinition): LiveSession;

package/dist/liveSession.js

@@ -0,0 +1,97 @@
+/**
+ * Live components — server-resident reactive UI CORE. The state lives on the
+ * server as ordinary aurora signals; this module turns a fine-grained signal
+ * change into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering
+ * the whole component. That precision — each signal already knows which template
+ * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ *
+ * This is the transport-agnostic core: mount a session, render its initial HTML,
+ * dispatch events that mutate signals, and drain / subscribe to the patches
+ * produced. The transport stack (broadcast / client / registry / router /
+ * server) builds ON this and re-exports through the `./live.js` barrel — kept in
+ * a separate module so those transport files import the core WITHOUT forming an
+ * import cycle back through the barrel.
+ *
+ * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`.
+ */
+import { effect, isSignal } from "./reactive.js";
+import { renderToString } from "./ssr.js";
+/**
+ * Mount a live session from a definition factory. Call once per connected
+ * client: the factory's signals become that session's private state. To SHARE
+ * state across sessions, close the factory over a signal created OUTSIDE it —
+ * every session then reads the same signal and patches on its change.
+ */
+export function mountLiveSession(factory) {
+    const { view, handlers = {} } = factory();
+    const listeners = new Set();
+    // slot → latest value. `pending` = current (un-flushed) batch; `buffer` =
+    // accumulated for pull consumers. Both keyed by slot so repeated writes in
+    // one batch collapse to the last value.
+    const pending = new Map();
+    const buffer = new Map();
+    let priming = true;
+    let flushScheduled = false;
+    const flush = () => {
+        flushScheduled = false;
+        if (pending.size === 0)
+            return;
+        const patch = [];
+        for (const [slot, value] of pending) {
+            patch.push({ slot, value });
+            buffer.set(slot, value);
+        }
+        pending.clear();
+        for (const listener of listeners)
+            listener(patch);
+    };
+    const scheduleFlush = () => {
+        if (flushScheduled)
+            return;
+        flushScheduled = true;
+        queueMicrotask(flush);
+    };
+    // One fine-grained effect per reactive slot. The priming run only
+    // subscribes; later runs (a signal changed) record the slot's new value.
+    const stops = view.values.map((value, slot) => {
+        if (!isSignal(value) && typeof value !== "function")
+            return () => { };
+        return effect(() => {
+            const next = String(value());
+            if (priming)
+                return;
+            pending.set(slot, next);
+            scheduleFlush();
+        });
+    });
+    priming = false;
+    return {
+        renderToString: () => renderToString(view),
+        dispatch(event, payload) {
+            const handler = handlers[event];
+            if (!handler)
+                return;
+            handler(payload);
+            flush(); // synchronous — one patch per dispatch (batches the handler's writes)
+        },
+        drainPatches() {
+            flush();
+            const patch = [];
+            for (const [slot, value] of buffer)
+                patch.push({ slot, value });
+            buffer.clear();
+            return patch;
+        },
+        onPatch(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        dispose() {
+            for (const stop of stops)
+                stop();
+            listeners.clear();
+            pending.clear();
+            buffer.clear();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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",

package/src/browser.ts

@@ -50,10 +50,14 @@ export interface WebStorageOptions {
 }
 
 /**
- * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ * SSR-safe key/value store over `localStorage` / `sessionStorage`.
  *
- * - Values are JSON-serialised; reads return `null` on the server, on a missing
- *   key, or on malformed JSON.
+ * - {@link get} / {@link set} are a thin pass-through — raw strings, no JSON,
+ *   exactly like the native `localStorage` API (so a token round-trips as-is,
+ *   not double-encoded). {@link getJSON} / {@link setJSON} are the opt-in
+ *   variants for structured values.
+ * - Reads return `null` on the server or a missing key (`getJSON` also on
+ *   malformed JSON).
  * - Writes swallow quota / private-mode errors so a full store never crashes
  *   the app (best-effort).
  * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
@@ -80,28 +84,52 @@ export class WebStorage {
 		return this.#prefix + key;
 	}
 
-	get<T>(key: string): T | null {
+	/**
+	 * Read the raw string at `key` — a thin, SSR-safe pass-through over
+	 * `localStorage.getItem` (returns `null` on the server or a missing key).
+	 * No JSON: what you {@link set} is what you get. Use {@link getJSON} for
+	 * structured values.
+	 */
+	get(key: string): string | null {
 		const backend = this.#backend();
 		if (!backend) return null;
-		const raw = backend.getItem(this.fullKey(key));
-		if (raw === null) return null;
-		try {
-			return JSON.parse(raw) as T;
-		} catch {
-			return null;
-		}
+		return backend.getItem(this.fullKey(key));
 	}
 
-	set(key: string, value: unknown): void {
+	/**
+	 * Write the raw string `value` at `key` (SSR no-op; quota / private-mode
+	 * errors are swallowed — best-effort). No encoding, like
+	 * `localStorage.setItem`. Use {@link setJSON} for objects/arrays/etc.
+	 */
+	set(key: string, value: string): void {
 		const backend = this.#backend();
 		if (!backend) return;
 		try {
-			backend.setItem(this.fullKey(key), JSON.stringify(value));
+			backend.setItem(this.fullKey(key), value);
 		} catch {
 			// QuotaExceededError / Safari private mode — best-effort write.
 		}
 	}
 
+	/**
+	 * Read `key` and JSON-parse it into `T`. Returns `null` on the server, a
+	 * missing key, or malformed JSON. Pair with {@link setJSON}.
+	 */
+	getJSON<T>(key: string): T | null {
+		const raw = this.get(key);
+		if (raw === null) return null;
+		try {
+			return JSON.parse(raw) as T;
+		} catch {
+			return null;
+		}
+	}
+
+	/** JSON-serialise `value` and store it at `key`. Pair with {@link getJSON}. */
+	setJSON(key: string, value: unknown): void {
+		this.set(key, JSON.stringify(value));
+	}
+
 	/** Whether `key` is present (and not the server). */
 	has(key: string): boolean {
 		const backend = this.#backend();
@@ -113,9 +141,9 @@ export class WebStorage {
 		this.#backend()?.removeItem(this.fullKey(key));
 	}
 
-	/** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
-	getOrSet<T>(key: string, factory: () => T): T {
-		const existing = this.get<T>(key);
+	/** Read `key`, or compute + persist `factory()` on a miss, returning the string. */
+	getOrSet(key: string, factory: () => string): string {
+		const existing = this.get(key);
 		if (existing !== null) return existing;
 		const value = factory();
 		this.set(key, value);
@@ -183,12 +211,13 @@ export function persistedSignal<T>(
 	options: PersistedSignalOptions = {},
 ): Signal<T> {
 	const store = new WebStorage(options);
-	const stored = store.get<T>(key);
+	const stored = store.getJSON<T>(key);
 	const sig = signal<T>(stored !== null ? stored : initial);
 
 	// Mirror every change back to storage; runs once immediately, then on change.
+	// JSON so any T (object, number, boolean, string) round-trips.
 	effect(() => {
-		store.set(key, sig());
+		store.setJSON(key, sig());
 	});
 
 	if (

package/src/live.ts

@@ -1,143 +1,18 @@
 /**
- * Live components — server-resident reactive UI. The state lives on the server
- * as ordinary aurora signals; this module turns a fine-grained signal change
- * into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering the
- * whole component. That precision — each signal already knows which template
- * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ * `@c9up/aurora/live` barrel — the whole Live surface behind ONE subpath.
  *
- * This is the transport-agnostic CORE (Stage 1): mount a session, render its
- * initial HTML, dispatch events that mutate signals, and drain / subscribe to
- * the patches produced. Wiring patches over `@c9up/relay` (SSE down, POST up)
- * and the thin client applier live in later stages.
+ * The transport-agnostic core (`mountLiveSession` + its types) lives in
+ * `./liveSession.js`; the transport stack (broadcast / client / registry /
+ * router / server) builds on it. Re-exporting everything here keeps the niche
+ * surface behind a single subpath and keeps the main `.` barrel lean (it no
+ * longer eager-pulls these into every browser graph), consistent with how
+ * `./ssr`, `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
  *
- * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`, so it
- * sits in the main barrel alongside the rest of aurora's runtime.
+ * The core lives in a SEPARATE module (not inline here) so the transport files
+ * import it directly from `./liveSession.js` rather than through this barrel —
+ * which would otherwise form an import cycle (barrel → transport → barrel).
  */
 
-import { effect, isSignal } from "./reactive.js";
-import { renderToString } from "./ssr.js";
-import type { TemplateResult } from "./types.js";
-
-/** A precise per-slot update: slot index (positional in the template) + value. */
-export interface SlotPatch {
-	slot: number;
-	value: string;
-}
-
-/** A live component: its reactive view + named event handlers that mutate it. */
-export interface LiveComponentDefinition {
-	/** The reactive view. Slots reading signals become live-patchable. */
-	view: TemplateResult;
-	/**
-	 * Event handlers, by name. A client interaction (`@click="increment"`)
-	 * dispatches one of these; it mutates the component's signals, which the
-	 * patch tracker turns into a `{slot, value}` patch.
-	 */
-	handlers?: Record<string, (payload?: unknown) => void>;
-}
-
-/** A mounted live component instance — one per connected client session. */
-export interface LiveSession {
-	/** Initial server-side render (the first full-HTML response). */
-	renderToString(): string;
-	/** Run a named handler (mutates signals); emits a patch for the batch. */
-	dispatch(event: string, payload?: unknown): void;
-	/** Collect + clear the patches accumulated since the last drain (pull model). */
-	drainPatches(): SlotPatch[];
-	/**
-	 * Subscribe to patches as they are produced (push model — what the relay
-	 * transport hooks into). Use `onPatch` OR `drainPatches`, not both.
-	 */
-	onPatch(listener: (patch: SlotPatch[]) => void): () => void;
-	/** Stop every effect — call on client disconnect to free the session. */
-	dispose(): void;
-}
-
-/**
- * Mount a live session from a definition factory. Call once per connected
- * client: the factory's signals become that session's private state. To SHARE
- * state across sessions, close the factory over a signal created OUTSIDE it —
- * every session then reads the same signal and patches on its change.
- */
-export function mountLiveSession(
-	factory: () => LiveComponentDefinition,
-): LiveSession {
-	const { view, handlers = {} } = factory();
-	const listeners = new Set<(patch: SlotPatch[]) => void>();
-	// slot → latest value. `pending` = current (un-flushed) batch; `buffer` =
-	// accumulated for pull consumers. Both keyed by slot so repeated writes in
-	// one batch collapse to the last value.
-	const pending = new Map<number, string>();
-	const buffer = new Map<number, string>();
-	let priming = true;
-	let flushScheduled = false;
-
-	const flush = (): void => {
-		flushScheduled = false;
-		if (pending.size === 0) return;
-		const patch: SlotPatch[] = [];
-		for (const [slot, value] of pending) {
-			patch.push({ slot, value });
-			buffer.set(slot, value);
-		}
-		pending.clear();
-		for (const listener of listeners) listener(patch);
-	};
-
-	const scheduleFlush = (): void => {
-		if (flushScheduled) return;
-		flushScheduled = true;
-		queueMicrotask(flush);
-	};
-
-	// One fine-grained effect per reactive slot. The priming run only
-	// subscribes; later runs (a signal changed) record the slot's new value.
-	const stops = view.values.map((value, slot) => {
-		if (!isSignal(value) && typeof value !== "function") return () => {};
-		return effect(() => {
-			const next = String((value as () => unknown)());
-			if (priming) return;
-			pending.set(slot, next);
-			scheduleFlush();
-		});
-	});
-	priming = false;
-
-	return {
-		renderToString: () => renderToString(view),
-		dispatch(event, payload) {
-			const handler = handlers[event];
-			if (!handler) return;
-			handler(payload);
-			flush(); // synchronous — one patch per dispatch (batches the handler's writes)
-		},
-		drainPatches() {
-			flush();
-			const patch: SlotPatch[] = [];
-			for (const [slot, value] of buffer) patch.push({ slot, value });
-			buffer.clear();
-			return patch;
-		},
-		onPatch(listener) {
-			listeners.add(listener);
-			return () => listeners.delete(listener);
-		},
-		dispose() {
-			for (const stop of stops) stop();
-			listeners.clear();
-			pending.clear();
-			buffer.clear();
-		},
-	};
-}
-
-// ─── `@c9up/aurora/live` barrel ──────────────────────────────────────
-//
-// The Live stack (broadcast / client / registry / router / server) is
-// re-exported here so the whole niche surface lives behind ONE subpath,
-// `@c9up/aurora/live` — keeping the main `.` barrel lean (it no longer
-// eager-pulls these into every browser graph), consistent with how `./ssr`,
-// `./relay`, `./rpc` and `./hydrate` are already subpath-gated.
 export {
 	connectPatches,
 	type LiveStore,
@@ -169,3 +44,9 @@ export {
 	type WireLiveEventsOptions,
 	wireLiveEvents,
 } from "./liveServer.js";
+export {
+	type LiveComponentDefinition,
+	type LiveSession,
+	mountLiveSession,
+	type SlotPatch,
+} from "./liveSession.js";

package/src/liveBroadcast.ts

@@ -20,7 +20,7 @@ import {
 	type LiveSession,
 	mountLiveSession,
 	type SlotPatch,
-} from "./live.js";
+} from "./liveSession.js";
 
 /**
  * Minimal relay surface aurora needs. The real `@c9up/relay` `Relay` satisfies

package/src/liveClient.ts

@@ -16,8 +16,8 @@
  */
 
 import { hydrate } from "./hydrate.js";
+import type { SlotPatch } from "./liveSession.js";
 import { isSignal } from "./reactive.js";
-import type { SlotPatch } from "./live.js";
 import type { TemplateResult } from "./types.js";
 
 /** The transport the live client needs: a patch subscription + an event POST. */
@@ -67,7 +67,11 @@ export function liveClient(opts: LiveClientOptions): () => void {
 		const target = event.target;
 		if (!(target instanceof Element)) return;
 		const el = target.closest("[data-live-click]");
-		if (el) opts.transport.post(opts.mount.id, el.getAttribute("data-live-click") ?? "");
+		if (el)
+			opts.transport.post(
+				opts.mount.id,
+				el.getAttribute("data-live-click") ?? "",
+			);
 	};
 	opts.container.addEventListener("click", onClick);
 

package/src/liveRegistry.ts

@@ -15,7 +15,7 @@ import {
 	type LiveComponentDefinition,
 	type LiveSession,
 	mountLiveSession,
-} from "./live.js";
+} from "./liveSession.js";
 
 /** A mounted instance: its id, the owner (e.g. relay uid), and the session. */
 export interface LiveSessionHandle {

package/src/liveSession.ts

@@ -0,0 +1,133 @@
+/**
+ * Live components — server-resident reactive UI CORE. The state lives on the
+ * server as ordinary aurora signals; this module turns a fine-grained signal
+ * change into a PRECISE per-slot patch (`{slot, value}`) instead of re-rendering
+ * the whole component. That precision — each signal already knows which template
+ * slot it feeds — is the angle that beats HTML-diffing live-view libraries.
+ *
+ * This is the transport-agnostic core: mount a session, render its initial HTML,
+ * dispatch events that mutate signals, and drain / subscribe to the patches
+ * produced. The transport stack (broadcast / client / registry / router /
+ * server) builds ON this and re-exports through the `./live.js` barrel — kept in
+ * a separate module so those transport files import the core WITHOUT forming an
+ * import cycle back through the barrel.
+ *
+ * Node-free / isomorphic: uses only `signal`/`effect`/`renderToString`.
+ */
+
+import { effect, isSignal } from "./reactive.js";
+import { renderToString } from "./ssr.js";
+import type { TemplateResult } from "./types.js";
+
+/** A precise per-slot update: slot index (positional in the template) + value. */
+export interface SlotPatch {
+	slot: number;
+	value: string;
+}
+
+/** A live component: its reactive view + named event handlers that mutate it. */
+export interface LiveComponentDefinition {
+	/** The reactive view. Slots reading signals become live-patchable. */
+	view: TemplateResult;
+	/**
+	 * Event handlers, by name. A client interaction (`@click="increment"`)
+	 * dispatches one of these; it mutates the component's signals, which the
+	 * patch tracker turns into a `{slot, value}` patch.
+	 */
+	handlers?: Record<string, (payload?: unknown) => void>;
+}
+
+/** A mounted live component instance — one per connected client session. */
+export interface LiveSession {
+	/** Initial server-side render (the first full-HTML response). */
+	renderToString(): string;
+	/** Run a named handler (mutates signals); emits a patch for the batch. */
+	dispatch(event: string, payload?: unknown): void;
+	/** Collect + clear the patches accumulated since the last drain (pull model). */
+	drainPatches(): SlotPatch[];
+	/**
+	 * Subscribe to patches as they are produced (push model — what the relay
+	 * transport hooks into). Use `onPatch` OR `drainPatches`, not both.
+	 */
+	onPatch(listener: (patch: SlotPatch[]) => void): () => void;
+	/** Stop every effect — call on client disconnect to free the session. */
+	dispose(): void;
+}
+
+/**
+ * Mount a live session from a definition factory. Call once per connected
+ * client: the factory's signals become that session's private state. To SHARE
+ * state across sessions, close the factory over a signal created OUTSIDE it —
+ * every session then reads the same signal and patches on its change.
+ */
+export function mountLiveSession(
+	factory: () => LiveComponentDefinition,
+): LiveSession {
+	const { view, handlers = {} } = factory();
+	const listeners = new Set<(patch: SlotPatch[]) => void>();
+	// slot → latest value. `pending` = current (un-flushed) batch; `buffer` =
+	// accumulated for pull consumers. Both keyed by slot so repeated writes in
+	// one batch collapse to the last value.
+	const pending = new Map<number, string>();
+	const buffer = new Map<number, string>();
+	let priming = true;
+	let flushScheduled = false;
+
+	const flush = (): void => {
+		flushScheduled = false;
+		if (pending.size === 0) return;
+		const patch: SlotPatch[] = [];
+		for (const [slot, value] of pending) {
+			patch.push({ slot, value });
+			buffer.set(slot, value);
+		}
+		pending.clear();
+		for (const listener of listeners) listener(patch);
+	};
+
+	const scheduleFlush = (): void => {
+		if (flushScheduled) return;
+		flushScheduled = true;
+		queueMicrotask(flush);
+	};
+
+	// One fine-grained effect per reactive slot. The priming run only
+	// subscribes; later runs (a signal changed) record the slot's new value.
+	const stops = view.values.map((value, slot) => {
+		if (!isSignal(value) && typeof value !== "function") return () => {};
+		return effect(() => {
+			const next = String((value as () => unknown)());
+			if (priming) return;
+			pending.set(slot, next);
+			scheduleFlush();
+		});
+	});
+	priming = false;
+
+	return {
+		renderToString: () => renderToString(view),
+		dispatch(event, payload) {
+			const handler = handlers[event];
+			if (!handler) return;
+			handler(payload);
+			flush(); // synchronous — one patch per dispatch (batches the handler's writes)
+		},
+		drainPatches() {
+			flush();
+			const patch: SlotPatch[] = [];
+			for (const [slot, value] of buffer) patch.push({ slot, value });
+			buffer.clear();
+			return patch;
+		},
+		onPatch(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		dispose() {
+			for (const stop of stops) stop();
+			listeners.clear();
+			pending.clear();
+			buffer.clear();
+		},
+	};
+}