@nexus_js/runtime 0.6.0

package/dist/runes.js

@@ -0,0 +1,155 @@
+/**
+ * Nexus Runes — Fine-grained reactive primitives inspired by Svelte 5.
+ * Zero Virtual DOM. The runtime surgically updates only what changed.
+ */
+// ── Internal tracking context ─────────────────────────────────────────────
+let currentEffect = null;
+let idCounter = 0;
+// ── $state ────────────────────────────────────────────────────────────────
+/**
+ * Creates a reactive signal. Reading `.value` inside an `$effect` or
+ * `$derived` automatically creates a dependency subscription.
+ *
+ * @example
+ * const count = $state(0);
+ * count.value++; // triggers all subscribers
+ */
+export function $state(initial) {
+    const node = {
+        value: initial,
+        subscribers: new Set(),
+        id: idCounter++,
+    };
+    return {
+        get value() {
+            if (currentEffect) {
+                node.subscribers.add(currentEffect);
+                currentEffect.deps.add(node);
+            }
+            return node.value;
+        },
+        set value(next) {
+            if (Object.is(node.value, next))
+                return;
+            node.value = next;
+            // Notify all subscribers synchronously (microtask queue in practice)
+            for (const effect of [...node.subscribers]) {
+                effect.cleanup?.();
+                effect.execute();
+            }
+        },
+    };
+}
+// ── $derived ──────────────────────────────────────────────────────────────
+/**
+ * Creates a computed value that automatically updates when its dependencies
+ * change. Computed lazily — only recalculates when accessed after a change.
+ *
+ * @example
+ * const count = $state(0);
+ * const doubled = $derived(() => count.value * 2);
+ * console.log(doubled.value); // 0
+ * count.value = 5;
+ * console.log(doubled.value); // 10
+ */
+export function $derived(computation) {
+    const signal = $state(computation());
+    let dirty = false;
+    $effect(() => {
+        const next = computation();
+        if (!Object.is(signal.value, next)) {
+            signal.value = next;
+        }
+    });
+    return {
+        get value() {
+            return signal.value;
+        },
+    };
+}
+// ── $effect ───────────────────────────────────────────────────────────────
+/**
+ * Runs a side effect whenever its reactive dependencies change.
+ * Returns a cleanup function to stop tracking.
+ *
+ * @example
+ * const count = $state(0);
+ * $effect(() => {
+ *   document.title = `Count: ${count.value}`;
+ * });
+ */
+export function $effect(fn) {
+    const node = {
+        execute: () => {
+            // Clean up previous subscriptions
+            for (const dep of node.deps) {
+                dep.subscribers.delete(node);
+            }
+            node.deps.clear();
+            const prev = currentEffect;
+            currentEffect = node;
+            try {
+                node.cleanup = fn();
+            }
+            finally {
+                currentEffect = prev;
+            }
+        },
+        cleanup: undefined,
+        deps: new Set(),
+    };
+    node.execute();
+    return () => {
+        node.cleanup?.();
+        for (const dep of node.deps) {
+            dep.subscribers.delete(node);
+        }
+        node.deps.clear();
+    };
+}
+// ── $props ────────────────────────────────────────────────────────────────
+/**
+ * Declares component props with optional defaults.
+ * Props are reactive — parent changes flow down automatically.
+ *
+ * @example
+ * const { name, age = 18 } = $props<{ name: string; age?: number }>();
+ */
+export function $props(defaults = {}) {
+    // In island context, props are injected from the server manifest.
+    // This is a typed accessor with defaults.
+    return new Proxy(defaults, {
+        get(target, key) {
+            return target[key];
+        },
+    });
+}
+// ── Batch updates ─────────────────────────────────────────────────────────
+let batchDepth = 0;
+const pendingEffects = new Set();
+/**
+ * Batches multiple state updates into a single re-render pass.
+ *
+ * @example
+ * batch(() => {
+ *   x.value = 1;
+ *   y.value = 2; // only one re-render happens
+ * });
+ */
+export function batch(fn) {
+    batchDepth++;
+    try {
+        fn();
+    }
+    finally {
+        batchDepth--;
+        if (batchDepth === 0) {
+            for (const effect of pendingEffects) {
+                effect.cleanup?.();
+                effect.execute();
+            }
+            pendingEffects.clear();
+        }
+    }
+}
+//# sourceMappingURL=runes.js.map

package/dist/runes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runes.js","sourceRoot":"","sources":["../src/runes.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Nexus Global State Store — Hydration Miss = 0.
+ *
+ * THE PARADOX:
+ *   Island A (cart) lives in the root layout.
+ *   User adds item → cart.$state updates to [item1, item2].
+ *   User navigates to /checkout.
+ *   The server renders /checkout fresh — it sends cart as [].
+ *   DOM morphing preserves the island element... but what about the state?
+ *
+ * THE SOLUTION:
+ *   A two-layer state synchronization system:
+ *
+ *   Layer 1 — Island Registry:
+ *     Every island that survives navigation keeps its live $state signals.
+ *     The morphing algorithm skips re-hydration for preserved islands,
+ *     so their in-memory $state is never touched. ✓
+ *
+ *   Layer 2 — Cross-navigation Store (this file):
+ *     For islands that DON'T survive navigation (they're in the new page,
+ *     not the shared layout), their last known state is checkpointed
+ *     into this store before navigation. When the new page mounts,
+ *     the store re-injects the state as initial props.
+ *
+ *   Layer 3 — Serialized Snapshot:
+ *     On navigation, the store serializes its state to sessionStorage
+ *     using @nexus_js/serialize (handles Date, Map, Set, BigInt).
+ *     This survives hard refreshes within the same session.
+ *
+ * USAGE:
+ *   // In a cart island — auto-persists across navigation
+ *   const cart = useStore('cart', {
+ *     default: [],
+ *     persist: 'session',  // optional: also write to sessionStorage
+ *   });
+ *
+ *   // cart.value is automatically restored after navigation
+ *   cart.value.push(newItem);
+ *
+ * INJECTION FLOW:
+ *   1. Island registers with store via useStore('cart', ...)
+ *   2. Before navigation: store.snapshot() → serializes to sessionStorage
+ *   3. After navigation: new islands read from store.get('cart')
+ *   4. If value exists in store → use it (no hydration miss)
+ *   5. If not → use server-provided props (normal flow)
+ */
+export interface StoreOptions<T> {
+    default: T;
+    /**
+     * Persistence strategy:
+     *   'memory'  — lives until page close (default)
+     *   'session' — persists in sessionStorage across navigations
+     *   'url'     — encodes in URL hash (shareable, no sensitive data)
+     */
+    persist?: 'memory' | 'session' | 'url';
+    /**
+     * Version token — bump this to invalidate stored state.
+     * Useful after schema changes that break deserialization.
+     */
+    version?: number;
+}
+export interface StoreEntry<T> {
+    value: T;
+    /** Updates the value and notifies subscribers */
+    set: (v: T) => void;
+    /** Resets to the initial default value */
+    reset: () => void;
+}
+/**
+ * Creates or retrieves a store entry by key.
+ * The returned signal is reactive — binding it in an island makes that
+ * island automatically update when any component calls store.set().
+ *
+ * @example
+ * // In cart island
+ * const cart = useStore('cart', { default: [], persist: 'session' });
+ * cart.value.push({ id: 1, name: 'Widget' });
+ *
+ * // In any other island or the navigation system
+ * const cart = useStore('cart', { default: [] });
+ * console.log(cart.value); // [{ id: 1, name: 'Widget' }]
+ */
+export declare function useStore<T>(key: string, opts: StoreOptions<T>): StoreEntry<T>;
+/**
+ * Snapshots the entire store to sessionStorage.
+ * Called by the navigation system BEFORE performing a navigation.
+ * This guarantees that state from any island is preserved across routes.
+ */
+export declare function snapshotStore(): void;
+/**
+ * Reads a value from the store by key.
+ * Used by the navigation system to inject state into new islands.
+ */
+export declare function readStore<T>(key: string): T | undefined;
+/**
+ * Writes a value into the store.
+ * Triggers reactivity for any island bound to this key.
+ */
+export declare function writeStore<T>(key: string, value: T): void;
+/**
+ * Returns a serialized snapshot of all persisted store values.
+ * Embedded by the server into the navigation response payload,
+ * so the new page can initialize islands with correct state.
+ */
+export declare function exportStore(): string;
+/**
+ * Hydrates the store from a server-provided snapshot.
+ * Called on new page initialization before islands mount.
+ */
+export declare function importStore(serialized: string): void;
+/**
+ * Clears all store entries. Useful in tests or on logout.
+ */
+export declare function clearStore(keys?: string[]): void;
+/**
+ * Returns debug info about all active store entries.
+ */
+export declare function storeDebugInfo(): Record<string, {
+    value: unknown;
+    persist: string;
+    hasSignal: boolean;
+}>;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX;;;;;OAKG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;IACvC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC;IACT,iDAAiD;IACjD,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;IACpB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AA4BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA0C7E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAWpC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAKvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAQzD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CASpC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CASpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAahD;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAUD"}

package/dist/store.js

@@ -0,0 +1,267 @@
+/**
+ * Nexus Global State Store — Hydration Miss = 0.
+ *
+ * THE PARADOX:
+ *   Island A (cart) lives in the root layout.
+ *   User adds item → cart.$state updates to [item1, item2].
+ *   User navigates to /checkout.
+ *   The server renders /checkout fresh — it sends cart as [].
+ *   DOM morphing preserves the island element... but what about the state?
+ *
+ * THE SOLUTION:
+ *   A two-layer state synchronization system:
+ *
+ *   Layer 1 — Island Registry:
+ *     Every island that survives navigation keeps its live $state signals.
+ *     The morphing algorithm skips re-hydration for preserved islands,
+ *     so their in-memory $state is never touched. ✓
+ *
+ *   Layer 2 — Cross-navigation Store (this file):
+ *     For islands that DON'T survive navigation (they're in the new page,
+ *     not the shared layout), their last known state is checkpointed
+ *     into this store before navigation. When the new page mounts,
+ *     the store re-injects the state as initial props.
+ *
+ *   Layer 3 — Serialized Snapshot:
+ *     On navigation, the store serializes its state to sessionStorage
+ *     using @nexus_js/serialize (handles Date, Map, Set, BigInt).
+ *     This survives hard refreshes within the same session.
+ *
+ * USAGE:
+ *   // In a cart island — auto-persists across navigation
+ *   const cart = useStore('cart', {
+ *     default: [],
+ *     persist: 'session',  // optional: also write to sessionStorage
+ *   });
+ *
+ *   // cart.value is automatically restored after navigation
+ *   cart.value.push(newItem);
+ *
+ * INJECTION FLOW:
+ *   1. Island registers with store via useStore('cart', ...)
+ *   2. Before navigation: store.snapshot() → serializes to sessionStorage
+ *   3. After navigation: new islands read from store.get('cart')
+ *   4. If value exists in store → use it (no hydration miss)
+ *   5. If not → use server-provided props (normal flow)
+ */
+import { $state, $effect } from './runes.js';
+import { serialize, deserialize } from '@nexus_js/serialize';
+const STORE_SESSION_KEY = '__nx_store__';
+const STORE_VERSION_KEY = '__nx_store_version__';
+const CURRENT_VERSION = 1;
+// ── In-memory signal registry ─────────────────────────────────────────────────
+const signals = new Map();
+const defaults = new Map();
+const persistModes = new Map();
+// ── Initialize from sessionStorage on module load ─────────────────────────────
+let _sessionData = {};
+if (typeof sessionStorage !== 'undefined') {
+    try {
+        const version = sessionStorage.getItem(STORE_VERSION_KEY);
+        if (version && parseInt(version, 10) === CURRENT_VERSION) {
+            const raw = sessionStorage.getItem(STORE_SESSION_KEY) ?? '{}';
+            _sessionData = deserialize(raw);
+        }
+    }
+    catch {
+        _sessionData = {};
+    }
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Creates or retrieves a store entry by key.
+ * The returned signal is reactive — binding it in an island makes that
+ * island automatically update when any component calls store.set().
+ *
+ * @example
+ * // In cart island
+ * const cart = useStore('cart', { default: [], persist: 'session' });
+ * cart.value.push({ id: 1, name: 'Widget' });
+ *
+ * // In any other island or the navigation system
+ * const cart = useStore('cart', { default: [] });
+ * console.log(cart.value); // [{ id: 1, name: 'Widget' }]
+ */
+export function useStore(key, opts) {
+    const persist = opts.persist ?? 'memory';
+    persistModes.set(key, persist);
+    defaults.set(key, opts.default);
+    // Determine initial value (priority: session → url → default)
+    let initial = opts.default;
+    if (persist === 'session' && key in _sessionData) {
+        initial = _sessionData[key];
+    }
+    else if (persist === 'url') {
+        const urlVal = readFromURL(key);
+        if (urlVal !== null)
+            initial = urlVal;
+    }
+    // Reuse existing signal if already registered (cross-island sharing)
+    if (!signals.has(key)) {
+        signals.set(key, $state(initial));
+    }
+    const signal = signals.get(key);
+    // Sync to sessionStorage on every change
+    if (persist === 'session') {
+        $effect(() => {
+            const val = signal.value;
+            _sessionData[key] = val;
+            flushToSession();
+        });
+    }
+    if (persist === 'url') {
+        $effect(() => {
+            writeToURL(key, signal.value);
+        });
+    }
+    return {
+        get value() { return signal.value; },
+        set(v) { signal.value = v; },
+        reset() { signal.value = opts.default; },
+    };
+}
+/**
+ * Snapshots the entire store to sessionStorage.
+ * Called by the navigation system BEFORE performing a navigation.
+ * This guarantees that state from any island is preserved across routes.
+ */
+export function snapshotStore() {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    for (const [key, signal] of signals.entries()) {
+        const mode = persistModes.get(key);
+        if (mode === 'session' || mode === 'url') {
+            _sessionData[key] = signal.value;
+        }
+    }
+    flushToSession();
+}
+/**
+ * Reads a value from the store by key.
+ * Used by the navigation system to inject state into new islands.
+ */
+export function readStore(key) {
+    const signal = signals.get(key);
+    if (signal)
+        return signal.value;
+    if (key in _sessionData)
+        return _sessionData[key];
+    return undefined;
+}
+/**
+ * Writes a value into the store.
+ * Triggers reactivity for any island bound to this key.
+ */
+export function writeStore(key, value) {
+    const existing = signals.get(key);
+    if (existing) {
+        existing.value = value;
+    }
+    else {
+        signals.set(key, $state(value));
+    }
+    _sessionData[key] = value;
+}
+/**
+ * Returns a serialized snapshot of all persisted store values.
+ * Embedded by the server into the navigation response payload,
+ * so the new page can initialize islands with correct state.
+ */
+export function exportStore() {
+    const exportable = {};
+    for (const [key, signal] of signals.entries()) {
+        const mode = persistModes.get(key);
+        if (mode && mode !== 'memory') {
+            exportable[key] = signal.value;
+        }
+    }
+    return serialize(exportable);
+}
+/**
+ * Hydrates the store from a server-provided snapshot.
+ * Called on new page initialization before islands mount.
+ */
+export function importStore(serialized) {
+    try {
+        const data = deserialize(serialized);
+        for (const [key, value] of Object.entries(data)) {
+            writeStore(key, value);
+        }
+    }
+    catch (err) {
+        console.warn('[Nexus Store] Failed to import snapshot:', err);
+    }
+}
+/**
+ * Clears all store entries. Useful in tests or on logout.
+ */
+export function clearStore(keys) {
+    if (keys) {
+        for (const key of keys) {
+            signals.delete(key);
+            delete _sessionData[key];
+        }
+    }
+    else {
+        signals.clear();
+        _sessionData = {};
+        if (typeof sessionStorage !== 'undefined') {
+            sessionStorage.removeItem(STORE_SESSION_KEY);
+        }
+    }
+}
+/**
+ * Returns debug info about all active store entries.
+ */
+export function storeDebugInfo() {
+    const info = {};
+    for (const [key] of signals.entries()) {
+        info[key] = {
+            value: signals.get(key)?.value,
+            persist: persistModes.get(key) ?? 'memory',
+            hasSignal: true,
+        };
+    }
+    return info;
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+let _flushTimer = null;
+function flushToSession() {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    if (_flushTimer)
+        clearTimeout(_flushTimer);
+    _flushTimer = setTimeout(() => {
+        try {
+            sessionStorage.setItem(STORE_VERSION_KEY, String(CURRENT_VERSION));
+            sessionStorage.setItem(STORE_SESSION_KEY, serialize(_sessionData));
+        }
+        catch {
+            // sessionStorage quota exceeded — clear old data
+            sessionStorage.clear();
+        }
+    }, 50);
+}
+function readFromURL(key) {
+    if (typeof location === 'undefined')
+        return null;
+    try {
+        const hash = new URLSearchParams(location.hash.slice(1));
+        const raw = hash.get(`nx_${key}`);
+        return raw ? deserialize(decodeURIComponent(raw)) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeToURL(key, value) {
+    if (typeof location === 'undefined')
+        return;
+    try {
+        const hash = new URLSearchParams(location.hash.slice(1));
+        hash.set(`nx_${key}`, encodeURIComponent(serialize(value)));
+        history.replaceState(null, '', `${location.pathname}${location.search}#${hash.toString()}`);
+    }
+    catch { }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/dist/sync.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Nexus $sync Rune — "The Teleportation Rune"
+ *
+ * Automatically synchronizes client state with:
+ *   - Browser cookies
+ *   - SessionStorage / LocalStorage
+ *   - Server-side DB (via Server Action endpoint)
+ *
+ * Usage:
+ *   // Sync with a cookie (persists across sessions)
+ *   const theme = $sync('theme', { default: 'dark', persist: 'cookie' });
+ *   theme.value = 'light'; // auto-saves to cookie + syncs to server
+ *
+ *   // Sync with DB (calls /_nexus/sync/:key automatically)
+ *   const cart = $sync('cart', { default: [], persist: 'db' });
+ *   cart.value = [...cart.value, newItem]; // writes to DB in background
+ *
+ *   // Optimistic DB sync
+ *   const likes = $sync('post:42:likes', { default: 0, persist: 'db', optimistic: true });
+ *   likes.value++; // UI updates immediately, DB writes in background
+ */
+export type SyncPersistence = 'cookie' | 'session' | 'local' | 'db';
+export interface SyncOptions<T> {
+    default?: T;
+    persist?: SyncPersistence;
+    optimistic?: boolean;
+    /** Debounce writes in ms (default: 300) */
+    debounce?: number;
+    /** Cookie options (when persist: 'cookie') */
+    cookie?: {
+        maxAge?: number;
+        path?: string;
+        secure?: boolean;
+        sameSite?: 'Strict' | 'Lax' | 'None';
+    };
+}
+export interface SyncedSignal<T> {
+    value: T;
+    pending: boolean;
+    error: string | null;
+    /** Force sync with server/storage */
+    refresh: () => Promise<void>;
+}
+/**
+ * Creates a synced reactive signal.
+ * Reads initial value from storage/server, writes back on every change.
+ */
+export declare function $sync<T>(key: string, opts?: SyncOptions<T>): SyncedSignal<T>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpE,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;KACtC,CAAC;CACH;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAID;;;GAGG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAW,CAAC,CAAC,CAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAwDhF"}