rune-lab 0.3.0 → 0.4.0

package/dist/state/exchange-rate.svelte.js

@@ -0,0 +1,145 @@
+// sdk/state/src/exchange-rate.svelte.ts
+import { getContext } from "svelte";
+import { convertAmount, convertMoney, createMoney, CURRENCY_MAP, 
+// Phase 2: ConversionStrategies from sdk/core
+resolveRate, scaledRate, toMoneySnapshot, } from "@internal/core";
+import { RUNE_LAB_CONTEXT } from "./context.ts";
+export class ExchangeRateStore {
+    #rates = $state({});
+    #baseCurrency = $state("USD");
+    /**
+     * The current exchange rates relative to the base currency.
+     */
+    get rates() {
+        return this.#rates;
+    }
+    /**
+     * The base currency all rates are relative to.
+     */
+    get baseCurrency() {
+        return this.#baseCurrency;
+    }
+    /**
+     * Returns true if exchange rates have been loaded.
+     */
+    get hasRates() {
+        return Object.keys(this.#rates).length > 0;
+    }
+    /**
+     * Set exchange rates from a human-readable float map.
+     * @param base - The base currency code (e.g., "USD")
+     * @param rawRates - A map of currency codes to float rates (e.g., { MXN: 17.23 })
+     */
+    setRates(base, rawRates) {
+        const nextRates = {};
+        for (const [code, rate] of Object.entries(rawRates)) {
+            nextRates[code] = scaledRate(rate, 4);
+        }
+        this.#baseCurrency = base;
+        this.#rates = nextRates;
+    }
+    /**
+     * Directly set pre-scaled rates.
+     */
+    setScaledRates(base, rates) {
+        this.#baseCurrency = base;
+        this.#rates = rates;
+    }
+    /**
+     * Resolves the exchange rate between two currencies.
+     * Returns a ScaledRate representing how many units of toCode are in 1 unit of fromCode.
+     */
+    getRate(fromCode, toCode) {
+        if (fromCode === toCode)
+            return 1;
+        const fromCurrency = CURRENCY_MAP[fromCode];
+        const toCurrency = CURRENCY_MAP[toCode];
+        if (!fromCurrency || !toCurrency)
+            return undefined;
+        if (!this.hasRates)
+            return undefined;
+        try {
+            // 1 unit of fromCode (major unit)
+            const oneUnit = Math.pow(Array.isArray(fromCurrency.base)
+                ? fromCurrency.base[0]
+                : fromCurrency.base, fromCurrency.exponent);
+            const currentRates = this.#rates;
+            const currentBase = this.#baseCurrency;
+            const sourceMoney = createMoney(oneUnit, fromCode);
+            let targetMoney;
+            if (fromCode === currentBase) {
+                // Direct: base → target
+                targetMoney = convertMoney(sourceMoney, toCode, currentRates);
+            }
+            else if (toCode === currentBase) {
+                // Inverse: target → base
+                const rateToBase = currentRates[fromCode];
+                if (!rateToBase)
+                    return undefined;
+                const r = resolveRate(rateToBase);
+                targetMoney = convertMoney(sourceMoney, toCode, {
+                    [toCode]: scaledRate(1 / r, 6),
+                });
+            }
+            else {
+                // Triangular: source → base → target
+                const rateToBase = currentRates[fromCode];
+                const rateToTarget = currentRates[toCode];
+                if (!rateToBase || !rateToTarget)
+                    return undefined;
+                const r1 = resolveRate(rateToBase);
+                const r2 = resolveRate(rateToTarget);
+                targetMoney = convertMoney(sourceMoney, toCode, {
+                    [toCode]: scaledRate(r2 / r1, 6),
+                });
+            }
+            const snapshot = toMoneySnapshot(targetMoney);
+            return {
+                amount: snapshot.amount,
+                scale: snapshot.scale,
+            };
+        }
+        catch (_err) {
+            return undefined;
+        }
+    }
+    /**
+     * Internal conversion logic that handles triangulation through base currency.
+     */
+    convertAmount(amount, fromCode, toCode) {
+        if (fromCode === toCode)
+            return amount;
+        if (!this.hasRates)
+            return amount;
+        // Direct: Base → Target
+        if (fromCode === this.#baseCurrency) {
+            return convertAmount(amount, fromCode, toCode, this.#rates);
+        }
+        // Inverse: Target → Base
+        if (toCode === this.#baseCurrency) {
+            const rateToBase = this.#rates[fromCode];
+            if (!rateToBase)
+                return amount;
+            const r = resolveRate(rateToBase);
+            const inverseRate = scaledRate(1 / r, 6);
+            return convertAmount(amount, fromCode, toCode, {
+                [toCode]: inverseRate,
+            });
+        }
+        // Triangulation: From → Base → To
+        const amountInBase = this.convertAmount(amount, fromCode, this.#baseCurrency);
+        return this.convertAmount(amountInBase, this.#baseCurrency, toCode);
+    }
+}
+/**
+ * Factory to create the ExchangeRateStore.
+ */
+export function createExchangeRateStore() {
+    return new ExchangeRateStore();
+}
+/**
+ * Consumer to retrieve the ExchangeRateStore from context.
+ */
+export function getExchangeRateStore() {
+    return getContext(RUNE_LAB_CONTEXT.exchangeRate);
+}

package/dist/state/exchange-rate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/state/exchange-rate.test.js

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+import { ExchangeRateStore } from "./exchange-rate.svelte.ts";
+import { createCurrencyStore } from "./currency.svelte.ts";
+import { inMemoryDriver } from "./persistence/drivers.ts";
+import { RUNE_LAB_CONTEXT } from "./context.ts";
+import { createLanguageStore } from "./language.svelte.ts";
+// Mock useMoney since it uses getContext and other stores
+vi.mock("./composables/useMoney.ts", () => ({
+    useMoney: () => ({
+        format: (amount, code, unit) => `${amount} ${code ?? 'USD'}`
+    })
+}));
+describe("ExchangeRateStore", () => {
+    it("should initialize with default base", () => {
+        const store = new ExchangeRateStore();
+        expect(store.baseCurrency).toBe("USD");
+        expect(store.hasRates).toBe(false);
+    });
+    it("should set and retrieve rates", () => {
+        const store = new ExchangeRateStore();
+        store.setRates("USD", { MXN: 17.23, EUR: 0.91 });
+        expect(store.hasRates).toBe(true);
+        expect(store.baseCurrency).toBe("USD");
+        const rateToMxn = store.getRate("USD", "MXN");
+        expect(rateToMxn).toEqual({ amount: 17230000, scale: 6 });
+    });
+    it("should handle inverse rates", () => {
+        const store = new ExchangeRateStore();
+        store.setRates("USD", { MXN: 20 });
+        const rateToBase = store.getRate("MXN", "USD");
+        expect(rateToBase).toEqual({ amount: 5000000, scale: 8 });
+    });
+    it("should handle triangulation (cross-rates)", () => {
+        const store = new ExchangeRateStore();
+        store.setRates("USD", { MXN: 20, EUR: 0.5 });
+        const rateMxnToEur = store.getRate("MXN", "EUR");
+        expect(rateMxnToEur).toEqual({ amount: 2500000, scale: 8 });
+    });
+});
+describe("CurrencyStore Integration", () => {
+    it("should convert amount when ExchangeRateStore is wired", () => {
+        const exchangeRateStore = new ExchangeRateStore();
+        exchangeRateStore.setRates("USD", { MXN: 20 });
+        const currencyStore = createCurrencyStore({ exchangeRateStore, driver: inMemoryDriver });
+        expect(currencyStore.canConvert).toBe(true);
+        const converted = currencyStore.convertAmount(10000, "USD", "MXN");
+        expect(converted).toBe(200000);
+    });
+    it("should return original amount if no rates available", () => {
+        const exchangeRateStore = new ExchangeRateStore();
+        const currencyStore = createCurrencyStore({ exchangeRateStore, driver: inMemoryDriver });
+        expect(currencyStore.canConvert).toBe(false);
+        const converted = currencyStore.convertAmount(10000, "USD", "MXN");
+        expect(converted).toBe(10000);
+    });
+});
+describe("useMoneyFilter", () => {
+    // Simple test for logic, skipping full component mount for brevity
+    it("matches() should work with conversion", () => {
+        const exchangeRateStore = new ExchangeRateStore();
+        exchangeRateStore.setRates("USD", { MXN: 20 });
+        const currencyStore = createCurrencyStore({ exchangeRateStore, driver: inMemoryDriver });
+        // Manual mock of context for the composable
+        // In a real test we'd use render() from @testing-library/svelte
+        const mockContext = new Map();
+        mockContext.set(RUNE_LAB_CONTEXT.currency, currencyStore);
+        mockContext.set(RUNE_LAB_CONTEXT.exchangeRate, exchangeRateStore);
+        mockContext.set(RUNE_LAB_CONTEXT.language, createLanguageStore({ driver: inMemoryDriver }));
+        // We can't easily call useMoneyFilter outside component without more setup
+        // but we can verify the matches logic in CurrencyStore
+        const amountInMxn = 1000000; // 10,000 MXN
+        const amountInUsd = currencyStore.convertAmount(amountInMxn, "MXN", "USD");
+        expect(amountInUsd).toBe(50000); // 500 USD
+    });
+});

package/dist/state/index.d.ts

@@ -1,19 +1,26 @@
-export { RUNE_LAB_CONTEXT } from "./context";
-export { useRuneLab } from "./composables/useRuneLab";
-export type { RuneLabContext } from "./composables/useRuneLab";
-export { usePersistence } from "./composables/usePersistence";
-export { useMoney } from "./composables/useMoney";
-export { cookieDriver, createCookieDriver, createInMemoryDriver, inMemoryDriver, localStorageDriver, sessionStorageDriver, } from "./persistence/drivers";
-export { type AppData, AppStore, createAppStore, getAppStore, } from "./app.svelte";
-export { createLayoutStore, getLayoutStore, LayoutStore, type NavigationItem, type NavigationSection, type WorkspaceItem, } from "./layout.svelte";
-export { ApiStore, type ConnectionState, createApiStore, getApiStore, } from "./api.svelte";
-export { createLanguageStore, getLanguageStore, type Language, } from "./language.svelte";
-export { createCurrencyStore, type Currency, type CurrencyStore, type CurrencyStoreOptions, getCurrencyStore, } from "./currency.svelte";
-export { createToastStore, getToastStore, ToastStore } from "./toast.svelte";
-export { type Command, CommandStore, createCommandStore, getCommandStore, } from "./commands.svelte";
-export { createShortcutStore, getShortcutStore, LAYOUT_SHORTCUTS, type ShortcutEntry, shortcutListener, type ShortcutMeta, ShortcutStore, } from "./shortcuts.svelte";
-export { createThemeStore, getThemeStore, type Theme, type ThemeStoreOptions, } from "./theme.svelte";
-export { type ConfigItem, type ConfigStore, type ConfigStoreOptions, createConfigStore, } from "./createConfigStore.svelte";
-export { createToastBridge, notify } from "./toast-bridge";
-export { type CartEntry, type CartStore, type CartStoreConfig, createCartStore, getCartStore, } from "./cart.svelte";
-export { type AuthConfig, createSessionStore, getSessionStore, type Session, SessionStore, type User, } from "./auth/index";
+export { RUNE_LAB_CONTEXT } from "./context.ts";
+export { useRuneLab } from "./composables/useRuneLab.ts";
+export type { RuneLabContext } from "./composables/useRuneLab.ts";
+export { usePersistence } from "./composables/usePersistence.ts";
+export { useMoney } from "./composables/useMoney.ts";
+export { useMoneyFilter } from "./composables/useMoneyFilter.ts";
+export type { MoneyFilterOptions } from "./composables/useMoneyFilter.ts";
+export { useShortcuts } from "./composables/useShortcuts.ts";
+export { cookieDriver, createCookieDriver, createInMemoryDriver, inMemoryDriver, localStorageDriver, sessionStorageDriver, } from "./persistence/drivers.ts";
+export { getDriverContext, resolveDriver, setDriverContext, } from "./persistence/provider.ts";
+export { clearRegistry, getAllRegisteredStores, getRegisteredStore, registerStore, STORE_REGISTRY, unregisterStore, } from "./registry/index.ts";
+export type { StoreFactory, StoreRegistryEntry } from "./registry/types.ts";
+export { type AppData, AppStore, createAppStore, getAppStore, } from "./app.svelte.ts";
+export { createLayoutStore, getLayoutStore, LayoutStore, type NavigationItem, type NavigationSection, type WorkspaceItem, } from "./layout.svelte.ts";
+export { ApiStore, type ConnectionState, createApiStore, getApiStore, } from "./api.svelte.ts";
+export { createLanguageStore, getLanguageStore, type Language, } from "./language.svelte.ts";
+export { createCurrencyStore, type Currency, type CurrencyStore, type CurrencyStoreOptions, getCurrencyStore, } from "./currency.svelte.ts";
+export { createExchangeRateStore, ExchangeRateStore, getExchangeRateStore, } from "./exchange-rate.svelte.ts";
+export { createToastStore, getToastStore, ToastStore } from "./toast.svelte.ts";
+export { type Command, CommandStore, createCommandStore, getCommandStore, } from "./commands.svelte.ts";
+export { createShortcutStore, getShortcutStore, LAYOUT_SHORTCUTS, type ShortcutEntry, shortcutListener, type ShortcutMeta, ShortcutStore, } from "./shortcuts.svelte.ts";
+export { createThemeStore, getThemeStore, type Theme, type ThemeStoreOptions, } from "./theme.svelte.ts";
+export { type ConfigStore, type ConfigStoreOptions, createConfigStore, } from "./createConfigStore.svelte.ts";
+export { createToastBridge, notify } from "./toast-bridge.ts";
+export { type CartEntry, type CartStore, type CartStoreConfig, createCartStore, getCartStore, } from "./cart.svelte.ts";
+export { type AuthConfig, createSessionStore, getSessionStore, type Session, SessionStore, type User, } from "./auth/index.ts";

package/dist/state/index.js

@@ -1,25 +1,32 @@
 // sdk/state/src/index.ts
 // Unified public barrel for @internal/state
 // ── Context ───────────────────────────────────────────────────────────────────
-export { RUNE_LAB_CONTEXT } from "./context";
+export { RUNE_LAB_CONTEXT } from "./context.ts";
 // ── Composables ───────────────────────────────────────────────────────────────
-export { useRuneLab } from "./composables/useRuneLab";
-export { usePersistence } from "./composables/usePersistence";
-export { useMoney } from "./composables/useMoney";
+export { useRuneLab } from "./composables/useRuneLab.ts";
+export { usePersistence } from "./composables/usePersistence.ts";
+export { useMoney } from "./composables/useMoney.ts";
+export { useMoneyFilter } from "./composables/useMoneyFilter.ts";
+export { useShortcuts } from "./composables/useShortcuts.ts";
 // ── Persistence Drivers ───────────────────────────────────────────────────────
-export { cookieDriver, createCookieDriver, createInMemoryDriver, inMemoryDriver, localStorageDriver, sessionStorageDriver, } from "./persistence/drivers";
+export { cookieDriver, createCookieDriver, createInMemoryDriver, inMemoryDriver, localStorageDriver, sessionStorageDriver, } from "./persistence/drivers.ts";
+// ── Driver Provider (Phase 2) ─────────────────────────────────────────────────
+export { getDriverContext, resolveDriver, setDriverContext, } from "./persistence/provider.ts";
+// ── Store Registry (Phase 2) ──────────────────────────────────────────────────
+export { clearRegistry, getAllRegisteredStores, getRegisteredStore, registerStore, STORE_REGISTRY, unregisterStore, } from "./registry/index.ts";
 // Stores
-export { AppStore, createAppStore, getAppStore, } from "./app.svelte";
-export { createLayoutStore, getLayoutStore, LayoutStore, } from "./layout.svelte";
-export { ApiStore, createApiStore, getApiStore, } from "./api.svelte";
-export { createLanguageStore, getLanguageStore, } from "./language.svelte";
-export { createCurrencyStore, getCurrencyStore, } from "./currency.svelte";
-export { createToastStore, getToastStore, ToastStore } from "./toast.svelte";
-export { CommandStore, createCommandStore, getCommandStore, } from "./commands.svelte";
-export { createShortcutStore, getShortcutStore, LAYOUT_SHORTCUTS, shortcutListener, ShortcutStore, } from "./shortcuts.svelte";
-export { createThemeStore, getThemeStore, } from "./theme.svelte";
-export { createConfigStore, } from "./createConfigStore.svelte";
-export { createToastBridge, notify } from "./toast-bridge";
-export { createCartStore, getCartStore, } from "./cart.svelte";
+export { AppStore, createAppStore, getAppStore, } from "./app.svelte.ts";
+export { createLayoutStore, getLayoutStore, LayoutStore, } from "./layout.svelte.ts";
+export { ApiStore, createApiStore, getApiStore, } from "./api.svelte.ts";
+export { createLanguageStore, getLanguageStore, } from "./language.svelte.ts";
+export { createCurrencyStore, getCurrencyStore, } from "./currency.svelte.ts";
+export { createExchangeRateStore, ExchangeRateStore, getExchangeRateStore, } from "./exchange-rate.svelte.ts";
+export { createToastStore, getToastStore, ToastStore } from "./toast.svelte.ts";
+export { CommandStore, createCommandStore, getCommandStore, } from "./commands.svelte.ts";
+export { createShortcutStore, getShortcutStore, LAYOUT_SHORTCUTS, shortcutListener, ShortcutStore, } from "./shortcuts.svelte.ts";
+export { createThemeStore, getThemeStore, } from "./theme.svelte.ts";
+export { createConfigStore, } from "./createConfigStore.svelte.ts";
+export { createToastBridge, notify } from "./toast-bridge.ts";
+export { createCartStore, getCartStore, } from "./cart.svelte.ts";
 // ── Auth ──────────────────────────────────────────────────────────────────────
-export { createSessionStore, getSessionStore, SessionStore, } from "./auth/index";
+export { createSessionStore, getSessionStore, SessionStore, } from "./auth/index.ts";

package/dist/state/language.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type ConfigStore } from "./createConfigStore.svelte";
+import { type ConfigStore } from "./createConfigStore.svelte.ts";
 /**
  * Language configuration
  * Represents a supported language in the application
@@ -47,18 +47,11 @@ export declare const LANGUAGES: readonly [{
     readonly code: "vi";
     readonly flag: "🇻🇳";
 }];
-import type { PersistenceDriver } from "rune-lab/core";
+import type { PersistenceDriver } from "@internal/core";
 export interface LanguageStoreOptions {
     driver?: PersistenceDriver | (() => PersistenceDriver | undefined);
     onLocaleChange?: (code: string) => void;
     locales?: readonly string[];
 }
-export declare function createLanguageStore(options?: LanguageStoreOptions): {
-    current: string | undefined;
-    available: Language[];
-    set(id: string | undefined): void;
-    get(id: string | undefined): Language | undefined;
-    getProp<K extends keyof Language>(prop: K, id?: string | undefined): Language[K] | undefined;
-    addItems(newItems: Language[]): void;
-};
+export declare function createLanguageStore(options?: LanguageStoreOptions): ConfigStore<Language>;
 export declare function getLanguageStore(): ConfigStore<Language>;

package/dist/state/language.svelte.js

@@ -1,7 +1,7 @@
 // sdk/state/src/language.svelte.ts
-import { createConfigStore, } from "./createConfigStore.svelte";
+import { createConfigStore, } from "./createConfigStore.svelte.ts";
 import { getContext } from "svelte";
-import { RUNE_LAB_CONTEXT } from "./context";
+import { RUNE_LAB_CONTEXT } from "./context.ts";
 export const LANGUAGES = [
     // --- INDOEUROPEAS (Rama Romance / Latín) ---
     { code: "es", flag: "🇲🇽" },
@@ -22,10 +22,9 @@ export const LANGUAGES = [
     { code: "ko", flag: "🇰🇷" },
     { code: "vi", flag: "🇻🇳" },
 ];
+import { resolveDriver } from "./persistence/provider.ts";
 export function createLanguageStore(options) {
-    const driver = typeof options?.driver === "function"
-        ? options.driver()
-        : options?.driver;
+    const driver = resolveDriver(options?.driver);
     const items = options?.locales
         ? LANGUAGES.filter((l) => options.locales.includes(l.code))
         : LANGUAGES;

package/dist/state/layout.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { PersistenceDriver } from "rune-lab/core";
+import type { PersistenceDriver } from "@internal/core";
 export interface WorkspaceItem {
     id: string;
     icon: string;

package/dist/state/layout.svelte.js

@@ -1,6 +1,7 @@
 // src/lib/state/layout.svelte.ts
 import { getContext } from "svelte";
-import { RUNE_LAB_CONTEXT } from "./context";
+import { RUNE_LAB_CONTEXT } from "./context.ts";
+import { resolveDriver } from "./persistence/provider.ts";
 export class LayoutStore {
     workspaces = $state([]);
     activeWorkspaceId = $state(null);
@@ -12,9 +13,8 @@ export class LayoutStore {
     #initialized = false;
     #driver;
     constructor(driver) {
-        // We import locally here or at top-level. We can just fallback to window if undefined,
-        // but better to expect it via inject. The app supplies it in createLayoutStore.
-        this.#driver = (typeof driver === "function" ? driver() : driver);
+        // Use resolveDriver but allow undefined result for SSR/no-driver scenarios
+        this.#driver = driver ? resolveDriver(driver) : undefined;
     }
     init(options) {
         if (this.#initialized)

package/dist/state/persistence/drivers.d.ts

@@ -1,4 +1,4 @@
-import type { PersistenceDriver } from "rune-lab/core";
+import type { PersistenceDriver } from "@internal/core";
 export declare function createInMemoryDriver(): PersistenceDriver;
 export declare const inMemoryDriver: PersistenceDriver;
 export declare const localStorageDriver: PersistenceDriver;

package/dist/state/persistence/drivers.js

@@ -4,7 +4,9 @@ export function createInMemoryDriver() {
     return {
         get: (key) => store.get(key) ?? null,
         set: (key, value) => store.set(key, value),
-        remove: (key) => store.delete(key),
+        remove: (key) => {
+            store.delete(key);
+        },
     };
 }
 export const inMemoryDriver = createInMemoryDriver();
@@ -12,34 +14,34 @@ export const localStorageDriver = {
     get: (key) => {
         if (!browser)
             return null;
-        return window.localStorage.getItem(key);
+        return globalThis.localStorage.getItem(key);
     },
     set: (key, value) => {
         if (!browser)
             return;
-        window.localStorage.setItem(key, value);
+        globalThis.localStorage.setItem(key, value);
     },
     remove: (key) => {
         if (!browser)
             return;
-        window.localStorage.removeItem(key);
+        globalThis.localStorage.removeItem(key);
     },
 };
 export const sessionStorageDriver = {
     get: (key) => {
         if (!browser)
             return null;
-        return window.sessionStorage.getItem(key);
+        return globalThis.sessionStorage.getItem(key);
     },
     set: (key, value) => {
         if (!browser)
             return;
-        window.sessionStorage.setItem(key, value);
+        globalThis.sessionStorage.setItem(key, value);
     },
     remove: (key) => {
         if (!browser)
             return;
-        window.sessionStorage.removeItem(key);
+        globalThis.sessionStorage.removeItem(key);
     },
 };
 export const createCookieDriver = (options = {}) => ({

package/dist/state/persistence/drivers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/state/persistence/drivers.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { createInMemoryDriver, inMemoryDriver } from "./drivers.ts";
+describe("PersistenceDriver Contract Tests", () => {
+    describe("createInMemoryDriver (factory)", () => {
+        it("should return null for missing keys", () => {
+            const driver = createInMemoryDriver();
+            expect(driver.get("nonexistent")).toBeNull();
+        });
+        it("should set and get a value", () => {
+            const driver = createInMemoryDriver();
+            driver.set("key", "value");
+            expect(driver.get("key")).toBe("value");
+        });
+        it("should overwrite existing values", () => {
+            const driver = createInMemoryDriver();
+            driver.set("key", "v1");
+            driver.set("key", "v2");
+            expect(driver.get("key")).toBe("v2");
+        });
+        it("should remove a key", () => {
+            const driver = createInMemoryDriver();
+            driver.set("key", "value");
+            driver.remove("key");
+            expect(driver.get("key")).toBeNull();
+        });
+        it("should not throw when removing a nonexistent key", () => {
+            const driver = createInMemoryDriver();
+            expect(() => driver.remove("nonexistent")).not.toThrow();
+        });
+        it("should handle empty string values", () => {
+            const driver = createInMemoryDriver();
+            driver.set("key", "");
+            expect(driver.get("key")).toBe("");
+        });
+        it("should handle JSON string values", () => {
+            const driver = createInMemoryDriver();
+            const json = JSON.stringify({ theme: "dark", fontSize: 14 });
+            driver.set("settings", json);
+            expect(JSON.parse(driver.get("settings"))).toEqual({
+                theme: "dark",
+                fontSize: 14,
+            });
+        });
+    });
+    describe("Factory isolation", () => {
+        it("should create isolated instances (no cross-contamination)", () => {
+            const driverA = createInMemoryDriver();
+            const driverB = createInMemoryDriver();
+            driverA.set("shared-key", "fromA");
+            driverB.set("shared-key", "fromB");
+            expect(driverA.get("shared-key")).toBe("fromA");
+            expect(driverB.get("shared-key")).toBe("fromB");
+        });
+        it("remove on one instance does not affect another", () => {
+            const driverA = createInMemoryDriver();
+            const driverB = createInMemoryDriver();
+            driverA.set("key", "valueA");
+            driverB.set("key", "valueB");
+            driverA.remove("key");
+            expect(driverA.get("key")).toBeNull();
+            expect(driverB.get("key")).toBe("valueB");
+        });
+    });
+    describe("inMemoryDriver singleton", () => {
+        it("should implement the full PersistenceDriver interface", () => {
+            expect(typeof inMemoryDriver.get).toBe("function");
+            expect(typeof inMemoryDriver.set).toBe("function");
+            expect(typeof inMemoryDriver.remove).toBe("function");
+        });
+        it("should function as a working driver", () => {
+            // Use unique keys to avoid test interference
+            const key = `test-${Date.now()}`;
+            inMemoryDriver.set(key, "singleton-value");
+            expect(inMemoryDriver.get(key)).toBe("singleton-value");
+            inMemoryDriver.remove(key);
+            expect(inMemoryDriver.get(key)).toBeNull();
+        });
+    });
+});

package/dist/state/persistence/provider.d.ts

@@ -0,0 +1,23 @@
+import type { PersistenceDriver } from "@internal/core";
+/**
+ * Resolves a driver input (function or instance) into a concrete PersistenceDriver.
+ * If the input is null/undefined, returns an inMemoryDriver as the Null Object.
+ *
+ * This is the single place where function-form drivers are unwrapped.
+ */
+export declare function resolveDriver(driver?: PersistenceDriver | (() => PersistenceDriver | undefined) | undefined): PersistenceDriver;
+/**
+ * Sets the persistence driver context at the RuneProvider root.
+ * Should be called exactly once, before any store factories run.
+ *
+ * @param driver - A PersistenceDriver instance, a factory function, or undefined.
+ *                 Undefined falls back to inMemoryDriver.
+ */
+export declare function setDriverContext(driver?: PersistenceDriver | (() => PersistenceDriver | undefined)): PersistenceDriver;
+/**
+ * Retrieves the persistence driver from context.
+ * Always returns a concrete PersistenceDriver — never null or undefined.
+ *
+ * @throws Error if called outside a RuneProvider tree (no context set).
+ */
+export declare function getDriverContext(): PersistenceDriver;

package/dist/state/persistence/provider.js

@@ -0,0 +1,43 @@
+// sdk/state/src/persistence/provider.ts
+// Context-based persistence driver injection.
+// Resolves the driver once (handling function-vs-instance duality)
+// and guarantees a concrete PersistenceDriver is always available.
+import { getContext, setContext } from "svelte";
+import { createInMemoryDriver } from "./drivers.ts";
+const DRIVER_CONTEXT_KEY = Symbol("rl:driver-provider");
+/**
+ * Resolves a driver input (function or instance) into a concrete PersistenceDriver.
+ * If the input is null/undefined, returns an inMemoryDriver as the Null Object.
+ *
+ * This is the single place where function-form drivers are unwrapped.
+ */
+export function resolveDriver(driver) {
+    const resolved = typeof driver === "function" ? driver() : driver;
+    return resolved ?? createInMemoryDriver();
+}
+/**
+ * Sets the persistence driver context at the RuneProvider root.
+ * Should be called exactly once, before any store factories run.
+ *
+ * @param driver - A PersistenceDriver instance, a factory function, or undefined.
+ *                 Undefined falls back to inMemoryDriver.
+ */
+export function setDriverContext(driver) {
+    const resolved = resolveDriver(driver);
+    setContext(DRIVER_CONTEXT_KEY, resolved);
+    return resolved;
+}
+/**
+ * Retrieves the persistence driver from context.
+ * Always returns a concrete PersistenceDriver — never null or undefined.
+ *
+ * @throws Error if called outside a RuneProvider tree (no context set).
+ */
+export function getDriverContext() {
+    const driver = getContext(DRIVER_CONTEXT_KEY);
+    if (!driver) {
+        throw new Error("[DriverProvider] getDriverContext() called outside a <RuneProvider> tree. " +
+            "Wrap your application in <RuneProvider> to provide persistence.");
+    }
+    return driver;
+}

package/dist/state/persistence/provider.test.d.ts

@@ -0,0 +1 @@
+export {};