rune-lab 0.2.2 → 0.3.0

package/README.md

@@ -140,6 +140,45 @@ also scan the `rune-lab` dist output:
 > component classes used by `rune-lab` will be included in your build and theme
 > switching will work across library components and your own code alike.
 
+## Money & Currency
+
+Rune Lab provides a robust, Dinero.js-backed money layer that handles precision
+arithmetic and locale-aware formatting.
+
+### MoneyDisplay
+
+```svelte
+<script>
+  import { MoneyDisplay } from "rune-lab";
+</script>
+
+<!-- Minor units (default): $150.00 -->
+<MoneyDisplay amount={15000} currency="USD" />
+
+<!-- Major units: $150.00 -->
+<MoneyDisplay amount={150} unit="major" currency="USD" />
+
+<!-- Compact notation: $1.2M -->
+<MoneyDisplay amount={1200000} unit="major" compact />
+
+<!-- Null handling with fallback: "—" -->
+<MoneyDisplay amount={null} fallback="N/A" />
+```
+
+### MoneyInput
+
+A masked input that prevents floating-point precision errors by working
+exclusively with integers.
+
+```svelte
+<script>
+  import { MoneyInput } from "rune-lab";
+  let price = $state(150.00);
+</script>
+
+<MoneyInput bind:amount={price} unit="major" currency="USD" />
+```
+
 ## Persistence Drivers
 
 Rune Lab provides built-in drivers to remember user preferences (like theme,

package/dist/core/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./internal/message-resolver";
 export * from "./persistence/types";
+export * from "./money/index";
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/core/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAE5C,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sdk/core/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC;AAE5C,cAAc,qBAAqB,CAAC;AAEpC,cAAc,eAAe,CAAC"}

package/dist/core/index.js

@@ -1,2 +1,3 @@
 export * from "./internal/message-resolver";
 export * from "./persistence/types";
+export * from "./money/index";

package/dist/core/money/index.d.ts

@@ -0,0 +1,2 @@
+export { addMoney, createMoney, CURRENCY_MAP, type Dinero, type DineroCurrency, formatAmount, formatMoney, type ISO4217Code, multiplyMoney, registerCurrency, safeAmount, subtractMoney, toMinorUnit, } from "./money";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/money/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sdk/core/src/money/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,YAAY,EACZ,WAAW,EACX,KAAK,WAAW,EAChB,aAAa,EACb,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,WAAW,GACZ,MAAM,SAAS,CAAC"}

package/dist/core/money/index.js

@@ -0,0 +1,2 @@
+// sdk/core/src/money/index.ts
+export { addMoney, createMoney, CURRENCY_MAP, formatAmount, formatMoney, multiplyMoney, registerCurrency, safeAmount, subtractMoney, toMinorUnit, } from "./money";

package/dist/core/money/money.d.ts

@@ -0,0 +1,57 @@
+import { type Dinero, type DineroCurrency } from "dinero.js";
+/**
+ * Map of ISO 4217 currency codes to Dinero currency objects
+ */
+export declare const CURRENCY_MAP: Record<string, DineroCurrency<number>>;
+/**
+ * Derived type of all built-in ISO 4217 currency codes.
+ * Enables IDE autocomplete while allowing any string for dynamic currencies.
+ */
+export type ISO4217Code = keyof typeof CURRENCY_MAP;
+/**
+ * Register a new currency in CURRENCY_MAP atomically.
+ * Ensures the core registry and any store-level registries stay in sync.
+ */
+export declare function registerCurrency(code: string, currency: DineroCurrency<number>): void;
+/**
+ * Normalizes an unknown input into a valid integer for Dinero.js.
+ * Exported so consumers can apply the same defensive coercion.
+ */
+export declare function safeAmount(amount: unknown): number;
+/**
+ * Converts a major-unit amount (e.g., pesos) to a minor-unit integer (e.g., centavos).
+ * Uses the currency's exponent from CURRENCY_MAP.
+ */
+export declare function toMinorUnit(amount: unknown, currencyCode: ISO4217Code | string): number;
+/**
+ * Create a Dinero monetary value from an amount.
+ * @param amount - Amount (normalized internally via safeAmount)
+ * @param currencyCode - ISO 4217 currency code (e.g., "USD")
+ */
+export declare function createMoney(amount: unknown, currencyCode: ISO4217Code | string): Dinero<number>;
+/**
+ * Format a Dinero value as a locale-aware string
+ * @param money - Dinero monetary value
+ * @param locale - BCP 47 locale string (e.g., "en-US", "es-MX")
+ * @param currencyCode - ISO 4217 code for Intl.NumberFormat (e.g., "USD")
+ */
+export declare function formatMoney(money: Dinero<number>, locale?: string, currencyCode?: string): string;
+/**
+ * Format a raw amount as a locale-aware currency string.
+ * Convenience wrapper around createMoney + formatMoney.
+ */
+export declare function formatAmount(amount: unknown, currencyCode: ISO4217Code | string, locale?: string): string;
+/**
+ * Add two monetary values (must be same currency)
+ */
+export declare function addMoney(a: Dinero<number>, b: Dinero<number>): Dinero<number>;
+/**
+ * Subtract two monetary values (must be same currency)
+ */
+export declare function subtractMoney(a: Dinero<number>, b: Dinero<number>): Dinero<number>;
+/**
+ * Multiply a monetary value by a factor
+ */
+export declare function multiplyMoney(money: Dinero<number>, factor: number): Dinero<number>;
+export type { Dinero, DineroCurrency };
+//# sourceMappingURL=money.d.ts.map

package/dist/core/money/money.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../../src/sdk/core/src/money/money.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,MAAM,EAEX,KAAK,cAAc,EAYpB,MAAM,WAAW,CAAC;AAEnB;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAY/D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAEpD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,GAC/B,IAAI,CAEN;AA2BD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,OAAO,EACf,YAAY,EAAE,WAAW,GAAG,MAAM,GACjC,MAAM,CAUR;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,OAAO,EACf,YAAY,EAAE,WAAW,GAAG,MAAM,GACjC,MAAM,CAAC,MAAM,CAAC,CAQhB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EACrB,MAAM,GAAE,MAAgB,EACxB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAeR;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,YAAY,EAAE,WAAW,GAAG,MAAM,EAClC,MAAM,GAAE,MAAgB,GACvB,MAAM,CAGR;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EACjB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,GAChB,MAAM,CAAC,MAAM,CAAC,CAEhB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,EACjB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,GAChB,MAAM,CAAC,MAAM,CAAC,CAEhB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,CAAC,CAEhB;AAGD,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC"}

package/dist/core/money/money.js

@@ -0,0 +1,132 @@
+// sdk/core/src/money/money.ts
+// Framework-agnostic money utilities using Dinero.js v2
+// Consumers should never import Dinero directly — these helpers encapsulate it.
+import { add as dineroAdd, AED, BRL, CAD, CNY, dinero, EUR, GBP, INR, JPY, KRW, multiply as dineroMultiply, MXN, subtract as dineroSubtract, toDecimal, 
+// ISO 4217 currency definitions
+USD, } from "dinero.js";
+/**
+ * Map of ISO 4217 currency codes to Dinero currency objects
+ */
+export const CURRENCY_MAP = {
+    USD,
+    EUR,
+    MXN,
+    JPY,
+    KRW,
+    CNY,
+    AED,
+    GBP,
+    CAD,
+    BRL,
+    INR,
+};
+/**
+ * Register a new currency in CURRENCY_MAP atomically.
+ * Ensures the core registry and any store-level registries stay in sync.
+ */
+export function registerCurrency(code, currency) {
+    CURRENCY_MAP[code] = currency;
+}
+/**
+ * Normalizes an unknown input into a valid finite number.
+ * Handles null, undefined, bigints, and SurrealDB Decimal objects via toString().
+ */
+function toNumber(amount) {
+    if (amount === null || amount === undefined)
+        return 0;
+    if (typeof amount === "number")
+        return Number.isFinite(amount) ? amount : 0;
+    if (typeof amount === "bigint")
+        return Number(amount);
+    // Handle SurrealDB Decimal (which has a toString method) or other objects
+    if (typeof amount === "object") {
+        try {
+            // SurrealDB Decimal.toString() returns a numeric string
+            const str = String(amount);
+            const parsed = parseFloat(str);
+            return Number.isFinite(parsed) ? parsed : 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    const coerced = Number(amount);
+    return Number.isFinite(coerced) ? coerced : 0;
+}
+/**
+ * Normalizes an unknown input into a valid integer for Dinero.js.
+ * Exported so consumers can apply the same defensive coercion.
+ */
+export function safeAmount(amount) {
+    return Math.round(toNumber(amount));
+}
+/**
+ * Converts a major-unit amount (e.g., pesos) to a minor-unit integer (e.g., centavos).
+ * Uses the currency's exponent from CURRENCY_MAP.
+ */
+export function toMinorUnit(amount, currencyCode) {
+    const currency = CURRENCY_MAP[currencyCode];
+    if (!currency) {
+        throw new Error(`Unknown currency code: ${currencyCode}. Register it first via registerCurrency().`);
+    }
+    const base = Array.isArray(currency.base) ? currency.base[0] : currency.base;
+    const factor = Math.pow(Number(base), Number(currency.exponent));
+    return Math.round(toNumber(amount) * factor);
+}
+/**
+ * Create a Dinero monetary value from an amount.
+ * @param amount - Amount (normalized internally via safeAmount)
+ * @param currencyCode - ISO 4217 currency code (e.g., "USD")
+ */
+export function createMoney(amount, currencyCode) {
+    const currency = CURRENCY_MAP[currencyCode];
+    if (!currency) {
+        throw new Error(`Unknown currency code: ${currencyCode}. Register it first via registerCurrency().`);
+    }
+    return dinero({ amount: safeAmount(amount), currency });
+}
+/**
+ * Format a Dinero value as a locale-aware string
+ * @param money - Dinero monetary value
+ * @param locale - BCP 47 locale string (e.g., "en-US", "es-MX")
+ * @param currencyCode - ISO 4217 code for Intl.NumberFormat (e.g., "USD")
+ */
+export function formatMoney(money, locale = "en-US", currencyCode) {
+    return toDecimal(money, ({ value, currency }) => {
+        const code = currencyCode ??
+            Object.entries(CURRENCY_MAP).find(([, c]) => c.code === currency.code)?.[0] ??
+            currency.code;
+        return new Intl.NumberFormat(locale, {
+            style: "currency",
+            currency: code,
+            minimumFractionDigits: currency.exponent,
+            maximumFractionDigits: currency.exponent,
+        }).format(Number(value));
+    });
+}
+/**
+ * Format a raw amount as a locale-aware currency string.
+ * Convenience wrapper around createMoney + formatMoney.
+ */
+export function formatAmount(amount, currencyCode, locale = "en-US") {
+    const money = createMoney(amount, currencyCode);
+    return formatMoney(money, locale, currencyCode);
+}
+/**
+ * Add two monetary values (must be same currency)
+ */
+export function addMoney(a, b) {
+    return dineroAdd(a, b);
+}
+/**
+ * Subtract two monetary values (must be same currency)
+ */
+export function subtractMoney(a, b) {
+    return dineroSubtract(a, b);
+}
+/**
+ * Multiply a monetary value by a factor
+ */
+export function multiplyMoney(money, factor) {
+    return dineroMultiply(money, factor);
+}

package/dist/index.d.ts

@@ -2,10 +2,4 @@ export * from "rune-lab/core";
 export * from "rune-lab/state";
 export * from "rune-lab/ui";
 
-export {
-  cookieDriver,
-  localStorageDriver,
-  sessionStorageDriver,
-} from "rune-lab/state";
-
 export declare const version: () => string;

package/dist/index.js

@@ -2,10 +2,4 @@ export * from "rune-lab/core";
 export * from "rune-lab/state";
 export * from "rune-lab/ui";
 
-export {
-  cookieDriver,
-  localStorageDriver,
-  sessionStorageDriver,
-} from "rune-lab/state";
-
-export const version = () => "0.2.2";
+export const version = () => "0.3.0";

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

@@ -25,9 +25,16 @@ export declare class AppStore {
     homepage: string;
     customIcons: Record<string, string>;
     /**
-     * Initialize app store with metadata
+     * Initialize app store with metadata.
+     *
+     * @contract init() is idempotent. Call it once at app startup via RuneProvider.
+     * Subsequent calls are silently ignored to maintain stability across SSR/CSR cycles.
      */
     init(data: Partial<AppData>): void;
+    /**
+     * @internal Test-only. Resets initialization guard.
+     */
+    __reset(): void;
     /**
      * Get full app information object
      */

package/dist/state/app.svelte.js

@@ -18,7 +18,10 @@ export class AppStore {
     customIcons = $state({});
     #initialized = false;
     /**
-     * Initialize app store with metadata
+     * Initialize app store with metadata.
+     *
+     * @contract init() is idempotent. Call it once at app startup via RuneProvider.
+     * Subsequent calls are silently ignored to maintain stability across SSR/CSR cycles.
      */
     init(data) {
         if (this.#initialized) {
@@ -43,6 +46,12 @@ export class AppStore {
             this.homepage = data.homepage;
         this.#initialized = true;
     }
+    /**
+     * @internal Test-only. Resets initialization guard.
+     */
+    __reset() {
+        this.#initialized = false;
+    }
     /**
      * Get full app information object
      */

package/dist/state/auth/index.d.ts

@@ -0,0 +1,2 @@
+export type { AuthConfig, Session, User } from "./types";
+export { createSessionStore, getSessionStore, SessionStore, } from "./session.svelte";

package/dist/state/auth/index.js

@@ -0,0 +1,2 @@
+// sdk/state/src/auth/index.ts
+export { createSessionStore, getSessionStore, SessionStore, } from "./session.svelte";

package/dist/state/auth/session.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { Session, User } from "./types";
+/**
+ * SessionStore — reactive authentication state.
+ *
+ * Once Better-Auth is fully integrated, this store will:
+ * - Initialize from the Better-Auth client SDK
+ * - Manage session lifecycle (login, logout, refresh)
+ * - Expose the current user + session tokens
+ * - Fire onSessionChange callbacks
+ *
+ * For now, it provides the interface contract that consuming apps
+ * and other rune-lab components (UserAvatar, UserProfile) can code against.
+ */
+export declare class SessionStore {
+    /** Whether authentication has been checked (vs. loading) */
+    isReady: boolean;
+    /** Whether a user is currently authenticated */
+    isAuthenticated: boolean;
+    /** Current user (null when logged out) */
+    user: User | null;
+    /** Current session (null when logged out) */
+    session: Session | null;
+    /**
+     * Initialize the session — placeholder for Better-Auth client setup
+     */
+    init(): Promise<void>;
+    /**
+     * Log in — placeholder
+     */
+    login(_credentials: {
+        email: string;
+        password: string;
+    }): Promise<boolean>;
+    /**
+     * Log out — placeholder
+     */
+    logout(): Promise<void>;
+}
+export declare function createSessionStore(): SessionStore;
+export declare function getSessionStore(): SessionStore;

package/dist/state/auth/session.svelte.js

@@ -0,0 +1,57 @@
+// sdk/state/src/auth/session.svelte.ts
+// SessionStore — manages authentication state via Svelte 5 runes.
+// This is a SKELETON — full Better-Auth wiring is deferred to a dedicated spec.
+import { getContext } from "svelte";
+import { RUNE_LAB_CONTEXT } from "../context";
+/**
+ * SessionStore — reactive authentication state.
+ *
+ * Once Better-Auth is fully integrated, this store will:
+ * - Initialize from the Better-Auth client SDK
+ * - Manage session lifecycle (login, logout, refresh)
+ * - Expose the current user + session tokens
+ * - Fire onSessionChange callbacks
+ *
+ * For now, it provides the interface contract that consuming apps
+ * and other rune-lab components (UserAvatar, UserProfile) can code against.
+ */
+export class SessionStore {
+    /** Whether authentication has been checked (vs. loading) */
+    isReady = $state(false);
+    /** Whether a user is currently authenticated */
+    isAuthenticated = $state(false);
+    /** Current user (null when logged out) */
+    user = $state(null);
+    /** Current session (null when logged out) */
+    session = $state(null);
+    /**
+     * Initialize the session — placeholder for Better-Auth client setup
+     */
+    async init() {
+        // TODO: Wire Better-Auth client.getSession() here
+        this.isReady = true;
+    }
+    /**
+     * Log in — placeholder
+     */
+    async login(_credentials) {
+        // TODO: Wire Better-Auth client.signIn.email() here
+        console.warn("SessionStore.login() is a stub — implement Better-Auth integration");
+        return false;
+    }
+    /**
+     * Log out — placeholder
+     */
+    async logout() {
+        // TODO: Wire Better-Auth client.signOut() here
+        this.user = null;
+        this.session = null;
+        this.isAuthenticated = false;
+    }
+}
+export function createSessionStore() {
+    return new SessionStore();
+}
+export function getSessionStore() {
+    return getContext(RUNE_LAB_CONTEXT.session);
+}

package/dist/state/auth/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal user representation for rune-lab's auth layer.
+ * Consuming apps can extend this with domain-specific fields.
+ */
+export interface User {
+    id: string;
+    name: string;
+    email: string;
+    avatar_url?: string;
+    role?: string;
+}
+/**
+ * Active session information
+ */
+export interface Session {
+    user: User;
+    accessToken: string;
+    expiresAt: Date;
+}
+/**
+ * Auth configuration passed to RuneProvider
+ */
+export interface AuthConfig {
+    /** Better-Auth client instance */
+    client?: any;
+    /** Callback when session changes (login, logout, expiry) */
+    onSessionChange?: (session: Session | null) => void;
+    /** Routes that require authentication */
+    protectedRoutes?: string[];
+}

package/dist/state/auth/types.js

@@ -0,0 +1,3 @@
+// sdk/state/src/auth/types.ts
+// Core auth types — framework-agnostic interfaces
+export {};

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

@@ -0,0 +1,64 @@
+import type { PersistenceDriver } from "rune-lab/core";
+/**
+ * Configuration for creating a CartStore
+ */
+export interface CartStoreConfig<T> {
+    /** Extract a unique identifier from an item */
+    idExtractor: (item: T) => string;
+    /** Extract the price (in minor units / cents) from an item */
+    priceExtractor: (item: T) => number;
+    /** Optional persistence driver for cart recovery */
+    driver?: PersistenceDriver;
+    /** Storage key for persistence */
+    storageKey?: string;
+}
+export interface CartEntry<T> {
+    item: T;
+    qty: number;
+}
+/**
+ * Generic cart store factory.
+ * Works with any item type via extractors.
+ *
+ * **Note**: Consumers must call `setContext(RUNE_LAB_CONTEXT.cart, store)` manually
+ * since CartStore is app-specific (needs `idExtractor` and `priceExtractor`).
+ * RuneProvider can optionally wire it via `config.cart`.
+ *
+ * Usage:
+ *   const cart = createCartStore<Property>({
+ *     idExtractor: (p) => p.id,
+ *     priceExtractor: (p) => p.price,
+ *   });
+ *   cart.add(someProperty);
+ *   cart.totalPrice; // sum of all items * qty in minor units
+ */
+export declare function createCartStore<T>(config: CartStoreConfig<T>): {
+    /** All cart entries */
+    readonly items: CartEntry<T>[];
+    /** Total number of items (sum of quantities) */
+    readonly totalItems: number;
+    /** Total price in minor units */
+    readonly totalPrice: number;
+    /** Whether the cart is empty */
+    readonly isEmpty: boolean;
+    /** Add an item (or increment quantity if already present) */
+    add(item: T, qty?: number): void;
+    /** Remove an item entirely */
+    remove(id: string): void;
+    /** Update the quantity of an item (removes if qty ≤ 0) */
+    updateQty(id: string, qty: number): void;
+    /** Clear all items */
+    clear(): void;
+    /** Check if an item is in the cart */
+    has(id: string): boolean;
+    /** Get a specific entry by ID */
+    getEntry(id: string): CartEntry<T> | undefined;
+};
+/** Return type of createCartStore for context typing */
+export type CartStore<T = unknown> = ReturnType<typeof createCartStore<T>>;
+/**
+ * Get CartStore from Svelte context.
+ * Only works if the consuming app has called setContext(RUNE_LAB_CONTEXT.cart, store)
+ * or passed a cart config to RuneProvider.
+ */
+export declare function getCartStore<T = unknown>(): CartStore<T>;

package/dist/state/cart.svelte.js

@@ -0,0 +1,122 @@
+// sdk/state/src/cart.svelte.ts
+// Generic cart store factory — business-agnostic add/remove/total pattern.
+import { getContext } from "svelte";
+import { RUNE_LAB_CONTEXT } from "./context";
+import { DEV } from "esm-env";
+/**
+ * Generic cart store factory.
+ * Works with any item type via extractors.
+ *
+ * **Note**: Consumers must call `setContext(RUNE_LAB_CONTEXT.cart, store)` manually
+ * since CartStore is app-specific (needs `idExtractor` and `priceExtractor`).
+ * RuneProvider can optionally wire it via `config.cart`.
+ *
+ * Usage:
+ *   const cart = createCartStore<Property>({
+ *     idExtractor: (p) => p.id,
+ *     priceExtractor: (p) => p.price,
+ *   });
+ *   cart.add(someProperty);
+ *   cart.totalPrice; // sum of all items * qty in minor units
+ */
+export function createCartStore(config) {
+    const { idExtractor, priceExtractor, driver, storageKey = "cart", } = config;
+    // Internal entries store — using a plain array for correct serialization
+    let _entries = $state([]);
+    /** Lookup by ID */
+    function _findIndex(id) {
+        return _entries.findIndex((e) => idExtractor(e.item) === id);
+    }
+    /** @internal Persist current state (Map serialized as Array) */
+    function _persist() {
+        if (!driver)
+            return;
+        try {
+            const data = _entries.map((entry) => ({
+                id: idExtractor(entry.item),
+                qty: entry.qty,
+            }));
+            driver.set(storageKey, JSON.stringify(data));
+        }
+        catch {
+            // Persistence is best-effort
+        }
+    }
+    return {
+        /** All cart entries */
+        get items() {
+            return _entries;
+        },
+        /** Total number of items (sum of quantities) */
+        get totalItems() {
+            let total = 0;
+            for (const entry of _entries)
+                total += entry.qty;
+            return total;
+        },
+        /** Total price in minor units */
+        get totalPrice() {
+            let total = 0;
+            for (const entry of _entries) {
+                total += priceExtractor(entry.item) * entry.qty;
+            }
+            return total;
+        },
+        /** Whether the cart is empty */
+        get isEmpty() {
+            return _entries.length === 0;
+        },
+        /** Add an item (or increment quantity if already present) */
+        add(item, qty = 1) {
+            const id = idExtractor(item);
+            const idx = _findIndex(id);
+            if (idx >= 0) {
+                _entries[idx] = { ..._entries[idx], qty: _entries[idx].qty + qty };
+            }
+            else {
+                _entries = [..._entries, { item, qty }];
+            }
+            _persist();
+            if (DEV)
+                console.log(`🛒 Added ${id} (qty: ${qty})`);
+        },
+        /** Remove an item entirely */
+        remove(id) {
+            _entries = _entries.filter((e) => idExtractor(e.item) !== id);
+            _persist();
+        },
+        /** Update the quantity of an item (removes if qty ≤ 0) */
+        updateQty(id, qty) {
+            if (qty <= 0) {
+                this.remove(id);
+                return;
+            }
+            const idx = _findIndex(id);
+            if (idx >= 0) {
+                _entries[idx] = { ..._entries[idx], qty };
+                _persist();
+            }
+        },
+        /** Clear all items */
+        clear() {
+            _entries = [];
+            _persist();
+        },
+        /** Check if an item is in the cart */
+        has(id) {
+            return _findIndex(id) >= 0;
+        },
+        /** Get a specific entry by ID */
+        getEntry(id) {
+            return _entries.find((e) => idExtractor(e.item) === id);
+        },
+    };
+}
+/**
+ * Get CartStore from Svelte context.
+ * Only works if the consuming app has called setContext(RUNE_LAB_CONTEXT.cart, store)
+ * or passed a cart config to RuneProvider.
+ */
+export function getCartStore() {
+    return getContext(RUNE_LAB_CONTEXT.cart);
+}