@ikeboy003/cart 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# @ikeboy003/cart
+
+Headless cart primitive. **Local-first cart state + a configurable durable sync
+path.** Import the engine, inject config, design your own UI. The library knows
+nothing about any POS, payment provider, store, framework, or item kind — like
+`postgrest-rs`, behaviour comes from config, not baked-in business logic.
+
+## Install
+
+```sh
+npm i @ikeboy003/cart
+```
+
+## Use
+
+```ts
+import { createCart, httpSync } from "@ikeboy003/cart";
+
+const cart = createCart({
+  namespace: "plane-things",                 // scopes storage keys + cart id
+  storage: localStorage,                      // or memory / custom Storage
+  sync: httpSync({ endpoint: "/api/cart" }),  // your durable write path
+  debounceMs: 400,
+});
+
+cart.add({ id: "tee:L", quantity: 1, priceCents: 3199, title: "Formation Tee" });
+cart.count;          // 1
+cart.subtotalCents;  // 3199
+await cart.flush();  // force the durable mirror current (call before checkout)
+```
+
+React (separate entry, optional):
+
+```tsx
+import { CartProvider, useCart } from "@ikeboy003/cart/react";
+
+<CartProvider namespace="plane-things" sync={httpSync({ endpoint: "/api/cart" })}>
+  <App />
+</CartProvider>;
+
+const { items, count, subtotalCents, add, remove, updateQuantity, clear, flush } = useCart();
+```
+
+## What it does (and only this)
+
+local cart state · `add` · `remove` · `updateQuantity` · `count` / `subtotalCents`
+· debounced sync · `flush` · `restore` from storage + durable · the
+`CartSyncAdapter` interface.
+
+It does **not** know about Square, Toast, Stripe, Cloudflare/D1, auth,
+fulfillment, or item kind. Those are the app's concern.
+
+## Line shape
+
+The minimum for cart mechanics is `{ id, quantity, priceCents }`; `title`/`sku`
+are optional and `metadata` passes through untouched. The engine is generic, so
+map your product into a typed line and keep type-safety end to end:
+
+```ts
+type MerchLine = CartItem & { metadata: { variationId: string; team: string } };
+const cart = createCart<MerchLine>({ namespace: "plane-things", /* … */ });
+```
+
+## When does sync happen
+
+1. **Every mutation** → `localStorage` synchronously (the live cart, zero latency).
+2. **Durable push** → coalesced ~`debounceMs` after the last change, **plus** a
+   forced flush on `visibilitychange: hidden` / `pagehide` (so the backend is
+   current before the tab closes / checkout). `keepalive` lets that final PUT
+   land during unload.
+3. **`restore()`** → pulls from the durable store once when the local cart is
+   empty (returning / cross-device). Local wins when both exist.
+
+## The flow it slots into
+
+```text
+frontend cart (this lib)
+  -> durable cart row        (your sync adapter; usually Cloudflare D1)
+  -> checkout / payment
+  -> payment webhook
+  -> graft pipeline looks up the durable cart
+  -> creates merchant/POS records   (Square today, Toast tomorrow — swappable)
+```
+
+The durable row is the bridge. The app owns the `/api/cart` route (writes
+whatever store it uses) and the post-payment pipeline. This package owns only
+the left edge.
+
+## Sync adapter
+
+`httpSync` posts to an app route:
+
+```text
+PUT  {endpoint}            body: CartSnapshot        -> 2xx   (upsert)
+GET  {endpoint}?id=&namespace=                       -> { items } | 404
+```
+
+Implement `CartSyncAdapter` yourself to target anything else (direct DB client,
+KV, IndexedDB, …) — `push(snapshot)` / `pull(id, namespace)`.

package/dist/engine.d.ts

@@ -0,0 +1,60 @@
+import type { CartItem, CartSnapshot, CreateCartOptions } from "./types.js";
+export declare class CartEngine<TItem extends CartItem = CartItem> {
+    readonly namespace: string;
+    private lines;
+    private readonly cartId;
+    private readonly listeners;
+    private readonly storage;
+    private readonly sync?;
+    private readonly debounceMs;
+    private flushTimer;
+    private hideHandler?;
+    /** Stable reference returned from getSnapshot until lines actually change. */
+    private snapshotRef;
+    constructor(opts: CreateCartOptions<TItem>);
+    get id(): string;
+    private loadId;
+    private loadLines;
+    private persistLocal;
+    subscribe: (fn: () => void) => (() => void);
+    /** Stable identity between mutations — safe for `useSyncExternalStore`. */
+    getSnapshot: () => TItem[];
+    private emit;
+    private commit;
+    /** Add a line. Merges by `id` (quantities sum). Defaults quantity to 1. */
+    add(item: TItem): void;
+    /** Set an exact quantity. `<= 0` removes the line. */
+    updateQuantity(id: string, quantity: number): void;
+    remove(id: string): void;
+    clear(): void;
+    get items(): TItem[];
+    get count(): number;
+    get subtotalCents(): number;
+    snapshot(): CartSnapshot<TItem>;
+    /** Seed from the durable store when the local cart is empty (cross-device). */
+    restore(): Promise<void>;
+    private schedulePush;
+    private push;
+    /**
+     * Force the durable mirror current NOW. Call before checkout so the order
+     * reads a definitely-current cart; also runs automatically on tab-hide.
+     */
+    flush(): Promise<void>;
+    /** Detach lifecycle listeners (call when tearing the engine down). */
+    dispose(): void;
+}
+/**
+ * Create a configured cart engine. The only required option is `namespace`;
+ * pass a `sync` adapter to enable the durable mirror.
+ *
+ * ```ts
+ * const cart = createCart({
+ *   namespace: "plane-things",
+ *   storage: localStorage,
+ *   sync: httpSync({ endpoint: "/api/cart" }),
+ *   debounceMs: 400,
+ * });
+ * ```
+ */
+export declare function createCart<TItem extends CartItem = CartItem>(opts: CreateCartOptions<TItem>): CartEngine<TItem>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EAEZ,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAuBpB,qBAAa,UAAU,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,8EAA8E;IAC9E,OAAO,CAAC,WAAW,CAAe;gBAEtB,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC;IAyB1C,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,SAAS;IAWjB,OAAO,CAAC,YAAY;IAMpB,SAAS,GAAI,IAAI,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAGxC;IAEF,2EAA2E;IAC3E,WAAW,QAAO,KAAK,EAAE,CAAqB;IAE9C,OAAO,CAAC,IAAI;IAOZ,OAAO,CAAC,MAAM;IAOd,2EAA2E;IAC3E,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IActB,sDAAsD;IACtD,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAYlD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxB,KAAK,IAAI,IAAI;IAMb,IAAI,KAAK,IAAI,KAAK,EAAE,CAEnB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,QAAQ,IAAI,YAAY,CAAC,KAAK,CAAC;IAW/B,+EAA+E;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAc9B,OAAO,CAAC,YAAY;YASN,IAAI;IASlB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B,sEAAsE;IACtE,OAAO,IAAI,IAAI;CAQhB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,EAC1D,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAC7B,UAAU,CAAC,KAAK,CAAC,CAEnB"}

package/dist/engine.js

@@ -0,0 +1,231 @@
+// The headless cart engine. Framework-agnostic. Mutations write storage
+// synchronously (the live cart is never behind), then schedule a debounced
+// durable push; a forced flush runs on tab-hide and can be called before
+// checkout. Observable via subscribe/getSnapshot so any UI (React's
+// useSyncExternalStore, or otherwise) can bind to it.
+const itemsKey = (ns) => `cart:${ns}:items`;
+const idKey = (ns) => `cart:${ns}:id`;
+function safeLocalStorage() {
+    try {
+        return typeof localStorage !== "undefined" ? localStorage : null;
+    }
+    catch {
+        // Access can throw (privacy mode, sandboxed iframe) — degrade to memory.
+        return null;
+    }
+}
+function defaultNewId() {
+    try {
+        if (typeof crypto !== "undefined" && crypto.randomUUID)
+            return crypto.randomUUID();
+    }
+    catch {
+        /* fall through */
+    }
+    return `c_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+}
+export class CartEngine {
+    constructor(opts) {
+        this.lines = [];
+        this.listeners = new Set();
+        this.flushTimer = null;
+        /** Stable reference returned from getSnapshot until lines actually change. */
+        this.snapshotRef = [];
+        // ---- observation -------------------------------------------------------
+        this.subscribe = (fn) => {
+            this.listeners.add(fn);
+            return () => this.listeners.delete(fn);
+        };
+        /** Stable identity between mutations — safe for `useSyncExternalStore`. */
+        this.getSnapshot = () => this.snapshotRef;
+        this.namespace = opts.namespace;
+        this.storage = opts.storage === undefined ? safeLocalStorage() : opts.storage;
+        this.sync = opts.sync;
+        this.debounceMs = opts.debounceMs ?? 400;
+        const mint = opts.newId ?? defaultNewId;
+        this.cartId = this.loadId(mint);
+        this.lines = this.loadLines();
+        this.snapshotRef = this.lines;
+        // Hard-guarantee the durable copy lands before the tab goes away (close,
+        // navigate, mobile background). `visibilitychange→hidden` is the reliable
+        // cross-browser signal; `pagehide` covers bfcache.
+        if (typeof document !== "undefined" && this.sync) {
+            this.hideHandler = () => {
+                if (document.visibilityState === "hidden")
+                    void this.flush();
+            };
+            document.addEventListener("visibilitychange", this.hideHandler);
+            window.addEventListener("pagehide", this.hideHandler);
+        }
+    }
+    // ---- identity / persistence (restore from storage) ---------------------
+    get id() {
+        return this.cartId;
+    }
+    loadId(mint) {
+        const existing = this.storage?.getItem(idKey(this.namespace));
+        if (existing)
+            return existing;
+        const id = mint();
+        this.storage?.setItem(idKey(this.namespace), id);
+        return id;
+    }
+    loadLines() {
+        const raw = this.storage?.getItem(itemsKey(this.namespace));
+        if (!raw)
+            return [];
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    persistLocal() {
+        this.storage?.setItem(itemsKey(this.namespace), JSON.stringify(this.lines));
+    }
+    emit() {
+        this.snapshotRef = this.lines;
+        for (const fn of this.listeners)
+            fn();
+    }
+    // ---- mutations ---------------------------------------------------------
+    commit(next) {
+        this.lines = next;
+        this.persistLocal(); // synchronous: the live cart is never behind
+        this.emit();
+        this.schedulePush(); // durable mirror, coalesced
+    }
+    /** Add a line. Merges by `id` (quantities sum). Defaults quantity to 1. */
+    add(item) {
+        const qty = item.quantity ?? 1;
+        if (qty <= 0)
+            return;
+        const i = this.lines.findIndex((l) => l.id === item.id);
+        if (i >= 0) {
+            const next = this.lines.slice();
+            const existing = next[i];
+            next[i] = { ...existing, ...item, quantity: existing.quantity + qty };
+            this.commit(next);
+        }
+        else {
+            this.commit([...this.lines, { ...item, quantity: qty }]);
+        }
+    }
+    /** Set an exact quantity. `<= 0` removes the line. */
+    updateQuantity(id, quantity) {
+        if (quantity <= 0) {
+            this.remove(id);
+            return;
+        }
+        const i = this.lines.findIndex((l) => l.id === id);
+        if (i < 0)
+            return;
+        const next = this.lines.slice();
+        next[i] = { ...next[i], quantity };
+        this.commit(next);
+    }
+    remove(id) {
+        const next = this.lines.filter((l) => l.id !== id);
+        if (next.length !== this.lines.length)
+            this.commit(next);
+    }
+    clear() {
+        if (this.lines.length)
+            this.commit([]);
+    }
+    // ---- derived -----------------------------------------------------------
+    get items() {
+        return this.lines;
+    }
+    get count() {
+        return this.lines.reduce((n, l) => n + l.quantity, 0);
+    }
+    get subtotalCents() {
+        return this.lines.reduce((n, l) => n + l.priceCents * l.quantity, 0);
+    }
+    snapshot() {
+        return {
+            id: this.cartId,
+            namespace: this.namespace,
+            items: this.lines,
+            updatedAt: Date.now(),
+        };
+    }
+    // ---- durable sync ------------------------------------------------------
+    /** Seed from the durable store when the local cart is empty (cross-device). */
+    async restore() {
+        if (!this.sync || this.lines.length > 0)
+            return;
+        try {
+            const remote = await this.sync.pull(this.cartId, this.namespace);
+            if (remote && remote.length && this.lines.length === 0) {
+                this.lines = remote;
+                this.persistLocal();
+                this.emit();
+            }
+        }
+        catch {
+            // Offline / store down → keep the local cart. Non-fatal by design.
+        }
+    }
+    schedulePush() {
+        if (!this.sync)
+            return;
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.push();
+        }, this.debounceMs);
+    }
+    async push() {
+        if (!this.sync)
+            return;
+        try {
+            await this.sync.push(this.snapshot());
+        }
+        catch {
+            // Durable mirror lagged; local is source of truth, next change retries.
+        }
+    }
+    /**
+     * Force the durable mirror current NOW. Call before checkout so the order
+     * reads a definitely-current cart; also runs automatically on tab-hide.
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.push();
+    }
+    /** Detach lifecycle listeners (call when tearing the engine down). */
+    dispose() {
+        if (this.hideHandler && typeof document !== "undefined") {
+            document.removeEventListener("visibilitychange", this.hideHandler);
+            window.removeEventListener("pagehide", this.hideHandler);
+        }
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.listeners.clear();
+    }
+}
+/**
+ * Create a configured cart engine. The only required option is `namespace`;
+ * pass a `sync` adapter to enable the durable mirror.
+ *
+ * ```ts
+ * const cart = createCart({
+ *   namespace: "plane-things",
+ *   storage: localStorage,
+ *   sync: httpSync({ endpoint: "/api/cart" }),
+ *   debounceMs: 400,
+ * });
+ * ```
+ */
+export function createCart(opts) {
+    return new CartEngine(opts);
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,yEAAyE;AACzE,oEAAoE;AACpE,sDAAsD;AAStD,MAAM,QAAQ,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC;AACpD,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;AAE9C,SAAS,gBAAgB;IACvB,IAAI,CAAC;QACH,OAAO,OAAO,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU;YAAE,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;IACD,OAAO,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,MAAM,OAAO,UAAU;IAcrB,YAAY,IAA8B;QAXlC,UAAK,GAAY,EAAE,CAAC;QAEX,cAAS,GAAG,IAAI,GAAG,EAAc,CAAC;QAI3C,eAAU,GAAyC,IAAI,CAAC;QAEhE,8EAA8E;QACtE,gBAAW,GAAY,EAAE,CAAC;QAsDlC,2EAA2E;QAE3E,cAAS,GAAG,CAAC,EAAc,EAAgB,EAAE;YAC3C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACvB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC;QAEF,2EAA2E;QAC3E,gBAAW,GAAG,GAAY,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC;QA3D5C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QAC9E,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,GAAG,CAAC;QACzC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC;QAExC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC;QAE9B,yEAAyE;QACzE,0EAA0E;QAC1E,mDAAmD;QACnD,IAAI,OAAO,QAAQ,KAAK,WAAW,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACjD,IAAI,CAAC,WAAW,GAAG,GAAG,EAAE;gBACtB,IAAI,QAAQ,CAAC,eAAe,KAAK,QAAQ;oBAAE,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/D,CAAC,CAAC;YACF,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAChE,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,2EAA2E;IAE3E,IAAI,EAAE;QACJ,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAEO,MAAM,CAAC,IAAkB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC9D,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;QACjD,OAAO,EAAE,CAAC;IACZ,CAAC;IAEO,SAAS;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC5D,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,MAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9E,CAAC;IAYO,IAAI;QACV,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC;QAC9B,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,SAAS;YAAE,EAAE,EAAE,CAAC;IACxC,CAAC;IAED,2EAA2E;IAEnE,MAAM,CAAC,IAAa;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,6CAA6C;QAClE,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,4BAA4B;IACnD,CAAC;IAED,2EAA2E;IAC3E,GAAG,CAAC,IAAW;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC/B,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO;QACrB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAU,CAAC;YAClC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,GAAG,GAAG,EAAE,CAAC;YACtE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,cAAc,CAAC,EAAU,EAAE,QAAgB;QACzC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QACD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAI,IAAI,CAAC,CAAC,CAAW,EAAE,QAAQ,EAAE,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,CAAC,EAAU;QACf,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,2EAA2E;IAE3E,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,QAAQ;QACN,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,MAAM;YACf,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACtB,CAAC;IACJ,CAAC;IAED,2EAA2E;IAE3E,+EAA+E;IAC/E,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO;QAChD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YACjE,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;gBACpB,IAAI,CAAC,YAAY,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO;QACvB,IAAI,IAAI,CAAC,UAAU;YAAE,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,OAAO;QACvB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC9B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAED,sEAAsE;IACtE,OAAO;QACL,IAAI,IAAI,CAAC,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;YACxD,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YACnE,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC3D,CAAC;QACD,IAAI,IAAI,CAAC,UAAU;YAAE,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CACxB,IAA8B;IAE9B,OAAO,IAAI,UAAU,CAAQ,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/http-sync.d.ts

@@ -0,0 +1,18 @@
+import type { CartItem, CartSyncAdapter } from "./types.js";
+export interface HttpSyncOptions {
+    /** Route that owns the durable store. Default `/api/cart`. */
+    endpoint?: string;
+    /** Static extra headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Optional bearer token, attached ONLY when it resolves to a non-empty value
+     * — so the cart is guest-first (no token → anonymous request the route accepts)
+     * and authed when a user is signed in (token → route can tag the owner). Can be
+     * sync or async (e.g. read a session). Never required.
+     */
+    getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+    /** Injectable fetch (default global). */
+    fetch?: typeof fetch;
+}
+export declare function httpSync<TItem extends CartItem = CartItem>(opts?: HttpSyncOptions): CartSyncAdapter<TItem>;
+//# sourceMappingURL=http-sync.d.ts.map

package/dist/http-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-sync.d.ts","sourceRoot":"","sources":["../src/http-sync.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAgB,eAAe,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IAChF,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,wBAAgB,QAAQ,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,EACxD,IAAI,GAAE,eAAoB,GACzB,eAAe,CAAC,KAAK,CAAC,CAkCxB"}

package/dist/http-sync.js

@@ -0,0 +1,44 @@
+// HTTP sync adapter — the default durable write path. The browser can't touch a
+// server store directly, so it speaks to an app route (which owns the binding:
+// D1, turso, KV, whatever). Keeps the engine platform-agnostic — swap the
+// endpoint's implementation without touching the lib.
+//
+// Wire contract (the app implements both at `endpoint`):
+//   PUT  {endpoint}            body: CartSnapshot           -> 2xx (upsert)
+//   GET  {endpoint}?id={id}&namespace={ns}                 -> { items: CartItem[] } | 404
+export function httpSync(opts = {}) {
+    const endpoint = opts.endpoint ?? "/api/cart";
+    const doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const base = { "content-type": "application/json", ...opts.headers };
+    // Resolve per-request so a token that appears mid-session (user logs in) is
+    // picked up without recreating the adapter. Guest path: returns `base` as-is.
+    async function headers() {
+        const token = opts.getToken ? await opts.getToken() : null;
+        return token ? { ...base, authorization: `Bearer ${token}` } : base;
+    }
+    return {
+        async push(snapshot) {
+            // `keepalive` lets the tab-hide flush finish after the page starts
+            // unloading — the browser equivalent of sendBeacon for a PUT with a body.
+            const res = await doFetch(endpoint, {
+                method: "PUT",
+                headers: await headers(),
+                body: JSON.stringify(snapshot),
+                keepalive: true,
+            });
+            if (!res.ok)
+                throw new Error(`cart push ${res.status}`);
+        },
+        async pull(id, namespace) {
+            const url = `${endpoint}?id=${encodeURIComponent(id)}&namespace=${encodeURIComponent(namespace)}`;
+            const res = await doFetch(url, { headers: await headers() });
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`cart pull ${res.status}`);
+            const body = (await res.json());
+            return body.items ?? null;
+        },
+    };
+}
+//# sourceMappingURL=http-sync.js.map

package/dist/http-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-sync.js","sourceRoot":"","sources":["../src/http-sync.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,+EAA+E;AAC/E,0EAA0E;AAC1E,sDAAsD;AACtD,EAAE;AACF,yDAAyD;AACzD,4EAA4E;AAC5E,0FAA0F;AAoB1F,MAAM,UAAU,QAAQ,CACtB,OAAwB,EAAE;IAE1B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,WAAW,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAErE,4EAA4E;IAC5E,8EAA8E;IAC9E,KAAK,UAAU,OAAO;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3D,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,QAA6B;YACtC,mEAAmE;YACnE,0EAA0E;YAC1E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE;gBAClC,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE,MAAM,OAAO,EAAE;gBACxB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC;gBAC9B,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1D,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAU,EAAE,SAAiB;YACtC,MAAM,GAAG,GAAG,GAAG,QAAQ,OAAO,kBAAkB,CAAC,EAAE,CAAC,cAAc,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;YAClG,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,OAAO,EAAE,EAAE,CAAC,CAAC;YAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,IAAI,CAAC;YACpC,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YACxD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwB,CAAC;YACvD,OAAO,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { CartEngine, createCart } from "./engine.js";
+export { httpSync, type HttpSyncOptions } from "./http-sync.js";
+export type { CartItem, CartSnapshot, CartSyncAdapter, CreateCartOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// @ikeboy003/cart — headless cart primitive.
+// Core (framework-agnostic) + the default HTTP sync adapter. The React binding
+// is a separate entry (`@ikeboy003/cart/react`) so server / non-React code can
+// use the engine without React.
+export { CartEngine, createCart } from "./engine.js";
+export { httpSync } from "./http-sync.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,+EAA+E;AAC/E,+EAA+E;AAC/E,gCAAgC;AAEhC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAwB,MAAM,gBAAgB,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,20 @@
+import { type ReactNode } from "react";
+import type { CartItem, CreateCartOptions } from "./types.js";
+export interface CartProviderProps<TItem extends CartItem = CartItem> extends CreateCartOptions<TItem> {
+    children: ReactNode;
+}
+export declare function CartProvider<TItem extends CartItem = CartItem>({ children, ...opts }: CartProviderProps<TItem>): import("react").JSX.Element;
+export declare function useCart<TItem extends CartItem = CartItem>(): {
+    cartId: string;
+    items: TItem[];
+    count: number;
+    /** Subtotal in cents. */
+    subtotalCents: number;
+    add: (item: TItem) => void;
+    remove: (id: string) => void;
+    updateQuantity: (id: string, quantity: number) => void;
+    clear: () => void;
+    /** Force the durable mirror current — call before navigating to checkout. */
+    flush: () => Promise<void>;
+};
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAOA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAK9D,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CAClE,SAAQ,iBAAiB,CAAC,KAAK,CAAC;IAChC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,EAAE,EAC9D,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,iBAAiB,CAAC,KAAK,CAAC,+BAc1B;AAED,wBAAgB,OAAO,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;;;;IAiBrD,yBAAyB;;gBAEb,KAAK;iBACJ,MAAM;yBACE,MAAM,YAAY,MAAM;;IAE7C,6EAA6E;;EAGhF"}

package/dist/react.js

@@ -0,0 +1,43 @@
+// Optional React binding — `CartProvider` + `useCart`. Headless: it exposes cart
+// state and actions, no markup. You design the drawer, the add button, the
+// checkout page. Imported separately (`@ikeboy003/cart/react`) so non-React /
+// server code can use the engine without pulling React in.
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useSyncExternalStore, } from "react";
+import { CartEngine } from "./engine.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const EngineContext = createContext(null);
+export function CartProvider({ children, ...opts }) {
+    // One engine per mount, keyed by namespace (effectively stable).
+    const engine = useMemo(() => new CartEngine(opts), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [opts.namespace]);
+    useEffect(() => {
+        void engine.restore();
+        return () => engine.dispose();
+    }, [engine]);
+    return _jsx(EngineContext.Provider, { value: engine, children: children });
+}
+export function useCart() {
+    const engine = useContext(EngineContext);
+    if (!engine)
+        throw new Error("useCart must be used inside <CartProvider>");
+    const items = useSyncExternalStore(engine.subscribe, engine.getSnapshot, engine.getSnapshot);
+    const count = items.reduce((n, l) => n + l.quantity, 0);
+    const subtotalCents = items.reduce((n, l) => n + l.priceCents * l.quantity, 0);
+    return {
+        cartId: engine.id,
+        items,
+        count,
+        /** Subtotal in cents. */
+        subtotalCents,
+        add: (item) => engine.add(item),
+        remove: (id) => engine.remove(id),
+        updateQuantity: (id, quantity) => engine.updateQuantity(id, quantity),
+        clear: () => engine.clear(),
+        /** Force the durable mirror current — call before navigating to checkout. */
+        flush: () => engine.flush(),
+    };
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,2EAA2E;AAC3E,8EAA8E;AAC9E,2DAA2D;AAE3D,YAAY,CAAC;;AAEb,OAAO,EACL,aAAa,EACb,UAAU,EACV,SAAS,EACT,OAAO,EACP,oBAAoB,GAErB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,8DAA8D;AAC9D,MAAM,aAAa,GAAG,aAAa,CAAyB,IAAI,CAAC,CAAC;AAOlE,MAAM,UAAU,YAAY,CAAoC,EAC9D,QAAQ,EACR,GAAG,IAAI,EACkB;IACzB,iEAAiE;IACjE,MAAM,MAAM,GAAG,OAAO,CACpB,GAAG,EAAE,CAAC,IAAI,UAAU,CAAQ,IAAI,CAAC;IACjC,uDAAuD;IACvD,CAAC,IAAI,CAAC,SAAS,CAAC,CACjB,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,KAAC,aAAa,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YAAG,QAAQ,GAA0B,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,MAAM,MAAM,GAAG,UAAU,CAAC,aAAa,CAA6B,CAAC;IACrE,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAE3E,MAAM,KAAK,GAAG,oBAAoB,CAChC,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,WAAW,CACnB,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAE/E,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,EAAE;QACjB,KAAK;QACL,KAAK;QACL,yBAAyB;QACzB,aAAa;QACb,GAAG,EAAE,CAAC,IAAW,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACtC,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,cAAc,EAAE,CAAC,EAAU,EAAE,QAAgB,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,QAAQ,CAAC;QACrF,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;QAC3B,6EAA6E;QAC7E,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The minimum a line needs for cart mechanics: a stable `id`, a `quantity`, and
+ * a `priceCents` (so count/subtotal work). Everything else is optional or rides
+ * in `metadata` untouched — the app maps its product shape onto this. The engine
+ * is generic over the line type, so a site can extend this with typed fields and
+ * keep full type-safety end to end.
+ */
+export interface CartItem {
+    id: string;
+    quantity: number;
+    priceCents: number;
+    title?: string;
+    sku?: string;
+    /** Opaque passthrough — variationId, options, anything the POS pipeline reads. */
+    metadata?: Record<string, unknown>;
+}
+/** The whole cart at a moment — the unit a sync adapter pushes/pulls. */
+export interface CartSnapshot<TItem extends CartItem = CartItem> {
+    /** Anonymous cart id (uuid), minted client-side, persisted in storage. */
+    id: string;
+    /** App-chosen scope (e.g. a site/store name). Opaque to the lib. */
+    namespace: string;
+    items: TItem[];
+    /** Epoch ms of the last local mutation — lets a durable store keep newest-wins. */
+    updatedAt: number;
+}
+/**
+ * Configurable durable write path — the equivalent of postgrest-rs's connection
+ * string. The engine calls `push` (debounced + on flush/tab-hide) and `pull`
+ * (on `restore()` when local is empty). The lib ships an HTTP adapter; an app
+ * can pass any implementation. Throwing is non-fatal: the local cart is the
+ * source of truth and the next change retries.
+ */
+export interface CartSyncAdapter<TItem extends CartItem = CartItem> {
+    push(snapshot: CartSnapshot<TItem>): Promise<void>;
+    pull(id: string, namespace: string): Promise<TItem[] | null>;
+}
+/** Config passed at import — nothing brand-specific is baked in. */
+export interface CreateCartOptions<TItem extends CartItem = CartItem> {
+    /** Scopes the storage keys + cart id, and is carried in the snapshot. */
+    namespace: string;
+    /** Persistence. Defaults to localStorage; pass `null` for in-memory only. */
+    storage?: Storage | null;
+    /** Durable mirror. Omit for local-only. */
+    sync?: CartSyncAdapter<TItem>;
+    /** Coalesce window for durable pushes (ms). Default 400. */
+    debounceMs?: number;
+    /** Id minter. Default `crypto.randomUUID`. */
+    newId?: () => string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAC7D,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAChE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;CAC9D;AAED,oEAAoE;AACpE,MAAM,WAAW,iBAAiB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAClE,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,18 @@
+// @ikeboy003/cart — headless cart primitive. "postgrest-rs for carts": import
+// the engine, inject config (namespace, storage, sync), design your own UI.
+//
+// The library knows NOTHING about Square / Toast / Stripe / D1 / Cloudflare /
+// auth / fulfillment / item kind. Those are the app's concern. The proven flow
+// the primitive slots into:
+//
+//   frontend cart (this lib)
+//     -> durable cart row (app's sync adapter; usually D1)
+//     -> checkout / payment
+//     -> payment webhook
+//     -> graft pipeline looks up the durable cart
+//     -> creates merchant/POS records (Square, Toast, ...  — swappable sink)
+//
+// The lib owns only the left edge: local cart state + a configurable durable
+// write path. Everything right of the durable row is runtime/config.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,4EAA4E;AAC5E,EAAE;AACF,8EAA8E;AAC9E,+EAA+E;AAC/E,4BAA4B;AAC5B,EAAE;AACF,6BAA6B;AAC7B,2DAA2D;AAC3D,4BAA4B;AAC5B,yBAAyB;AACzB,kDAAkD;AAClD,6EAA6E;AAC7E,EAAE;AACF,6EAA6E;AAC7E,qEAAqE"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ikeboy003/cart",
+  "version": "0.1.0",
+  "description": "Headless cart primitive: local-first state + a configurable durable sync path. Framework-agnostic core, optional React binding. No POS/payment/store logic baked in.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "files": ["dist", "src"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": ["cart", "ecommerce", "headless", "local-first"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "typescript": "^5.5.0"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,260 @@
+// The headless cart engine. Framework-agnostic. Mutations write storage
+// synchronously (the live cart is never behind), then schedule a debounced
+// durable push; a forced flush runs on tab-hide and can be called before
+// checkout. Observable via subscribe/getSnapshot so any UI (React's
+// useSyncExternalStore, or otherwise) can bind to it.
+
+import type {
+  CartItem,
+  CartSnapshot,
+  CartSyncAdapter,
+  CreateCartOptions,
+} from "./types.js";
+
+const itemsKey = (ns: string) => `cart:${ns}:items`;
+const idKey = (ns: string) => `cart:${ns}:id`;
+
+function safeLocalStorage(): Storage | null {
+  try {
+    return typeof localStorage !== "undefined" ? localStorage : null;
+  } catch {
+    // Access can throw (privacy mode, sandboxed iframe) — degrade to memory.
+    return null;
+  }
+}
+
+function defaultNewId(): string {
+  try {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) return crypto.randomUUID();
+  } catch {
+    /* fall through */
+  }
+  return `c_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export class CartEngine<TItem extends CartItem = CartItem> {
+  readonly namespace: string;
+
+  private lines: TItem[] = [];
+  private readonly cartId: string;
+  private readonly listeners = new Set<() => void>();
+  private readonly storage: Storage | null;
+  private readonly sync?: CartSyncAdapter<TItem>;
+  private readonly debounceMs: number;
+  private flushTimer: ReturnType<typeof setTimeout> | null = null;
+  private hideHandler?: () => void;
+  /** Stable reference returned from getSnapshot until lines actually change. */
+  private snapshotRef: TItem[] = [];
+
+  constructor(opts: CreateCartOptions<TItem>) {
+    this.namespace = opts.namespace;
+    this.storage = opts.storage === undefined ? safeLocalStorage() : opts.storage;
+    this.sync = opts.sync;
+    this.debounceMs = opts.debounceMs ?? 400;
+    const mint = opts.newId ?? defaultNewId;
+
+    this.cartId = this.loadId(mint);
+    this.lines = this.loadLines();
+    this.snapshotRef = this.lines;
+
+    // Hard-guarantee the durable copy lands before the tab goes away (close,
+    // navigate, mobile background). `visibilitychange→hidden` is the reliable
+    // cross-browser signal; `pagehide` covers bfcache.
+    if (typeof document !== "undefined" && this.sync) {
+      this.hideHandler = () => {
+        if (document.visibilityState === "hidden") void this.flush();
+      };
+      document.addEventListener("visibilitychange", this.hideHandler);
+      window.addEventListener("pagehide", this.hideHandler);
+    }
+  }
+
+  // ---- identity / persistence (restore from storage) ---------------------
+
+  get id(): string {
+    return this.cartId;
+  }
+
+  private loadId(mint: () => string): string {
+    const existing = this.storage?.getItem(idKey(this.namespace));
+    if (existing) return existing;
+    const id = mint();
+    this.storage?.setItem(idKey(this.namespace), id);
+    return id;
+  }
+
+  private loadLines(): TItem[] {
+    const raw = this.storage?.getItem(itemsKey(this.namespace));
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? (parsed as TItem[]) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private persistLocal(): void {
+    this.storage?.setItem(itemsKey(this.namespace), JSON.stringify(this.lines));
+  }
+
+  // ---- observation -------------------------------------------------------
+
+  subscribe = (fn: () => void): (() => void) => {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  };
+
+  /** Stable identity between mutations — safe for `useSyncExternalStore`. */
+  getSnapshot = (): TItem[] => this.snapshotRef;
+
+  private emit(): void {
+    this.snapshotRef = this.lines;
+    for (const fn of this.listeners) fn();
+  }
+
+  // ---- mutations ---------------------------------------------------------
+
+  private commit(next: TItem[]): void {
+    this.lines = next;
+    this.persistLocal(); // synchronous: the live cart is never behind
+    this.emit();
+    this.schedulePush(); // durable mirror, coalesced
+  }
+
+  /** Add a line. Merges by `id` (quantities sum). Defaults quantity to 1. */
+  add(item: TItem): void {
+    const qty = item.quantity ?? 1;
+    if (qty <= 0) return;
+    const i = this.lines.findIndex((l) => l.id === item.id);
+    if (i >= 0) {
+      const next = this.lines.slice();
+      const existing = next[i] as TItem;
+      next[i] = { ...existing, ...item, quantity: existing.quantity + qty };
+      this.commit(next);
+    } else {
+      this.commit([...this.lines, { ...item, quantity: qty }]);
+    }
+  }
+
+  /** Set an exact quantity. `<= 0` removes the line. */
+  updateQuantity(id: string, quantity: number): void {
+    if (quantity <= 0) {
+      this.remove(id);
+      return;
+    }
+    const i = this.lines.findIndex((l) => l.id === id);
+    if (i < 0) return;
+    const next = this.lines.slice();
+    next[i] = { ...(next[i] as TItem), quantity };
+    this.commit(next);
+  }
+
+  remove(id: string): void {
+    const next = this.lines.filter((l) => l.id !== id);
+    if (next.length !== this.lines.length) this.commit(next);
+  }
+
+  clear(): void {
+    if (this.lines.length) this.commit([]);
+  }
+
+  // ---- derived -----------------------------------------------------------
+
+  get items(): TItem[] {
+    return this.lines;
+  }
+
+  get count(): number {
+    return this.lines.reduce((n, l) => n + l.quantity, 0);
+  }
+
+  get subtotalCents(): number {
+    return this.lines.reduce((n, l) => n + l.priceCents * l.quantity, 0);
+  }
+
+  snapshot(): CartSnapshot<TItem> {
+    return {
+      id: this.cartId,
+      namespace: this.namespace,
+      items: this.lines,
+      updatedAt: Date.now(),
+    };
+  }
+
+  // ---- durable sync ------------------------------------------------------
+
+  /** Seed from the durable store when the local cart is empty (cross-device). */
+  async restore(): Promise<void> {
+    if (!this.sync || this.lines.length > 0) return;
+    try {
+      const remote = await this.sync.pull(this.cartId, this.namespace);
+      if (remote && remote.length && this.lines.length === 0) {
+        this.lines = remote;
+        this.persistLocal();
+        this.emit();
+      }
+    } catch {
+      // Offline / store down → keep the local cart. Non-fatal by design.
+    }
+  }
+
+  private schedulePush(): void {
+    if (!this.sync) return;
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.flushTimer = setTimeout(() => {
+      this.flushTimer = null;
+      void this.push();
+    }, this.debounceMs);
+  }
+
+  private async push(): Promise<void> {
+    if (!this.sync) return;
+    try {
+      await this.sync.push(this.snapshot());
+    } catch {
+      // Durable mirror lagged; local is source of truth, next change retries.
+    }
+  }
+
+  /**
+   * Force the durable mirror current NOW. Call before checkout so the order
+   * reads a definitely-current cart; also runs automatically on tab-hide.
+   */
+  async flush(): Promise<void> {
+    if (this.flushTimer) {
+      clearTimeout(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.push();
+  }
+
+  /** Detach lifecycle listeners (call when tearing the engine down). */
+  dispose(): void {
+    if (this.hideHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.hideHandler);
+      window.removeEventListener("pagehide", this.hideHandler);
+    }
+    if (this.flushTimer) clearTimeout(this.flushTimer);
+    this.listeners.clear();
+  }
+}
+
+/**
+ * Create a configured cart engine. The only required option is `namespace`;
+ * pass a `sync` adapter to enable the durable mirror.
+ *
+ * ```ts
+ * const cart = createCart({
+ *   namespace: "plane-things",
+ *   storage: localStorage,
+ *   sync: httpSync({ endpoint: "/api/cart" }),
+ *   debounceMs: 400,
+ * });
+ * ```
+ */
+export function createCart<TItem extends CartItem = CartItem>(
+  opts: CreateCartOptions<TItem>,
+): CartEngine<TItem> {
+  return new CartEngine<TItem>(opts);
+}

package/src/http-sync.ts

@@ -0,0 +1,64 @@
+// HTTP sync adapter — the default durable write path. The browser can't touch a
+// server store directly, so it speaks to an app route (which owns the binding:
+// D1, turso, KV, whatever). Keeps the engine platform-agnostic — swap the
+// endpoint's implementation without touching the lib.
+//
+// Wire contract (the app implements both at `endpoint`):
+//   PUT  {endpoint}            body: CartSnapshot           -> 2xx (upsert)
+//   GET  {endpoint}?id={id}&namespace={ns}                 -> { items: CartItem[] } | 404
+
+import type { CartItem, CartSnapshot, CartSyncAdapter } from "./types.js";
+
+export interface HttpSyncOptions {
+  /** Route that owns the durable store. Default `/api/cart`. */
+  endpoint?: string;
+  /** Static extra headers merged into every request. */
+  headers?: Record<string, string>;
+  /**
+   * Optional bearer token, attached ONLY when it resolves to a non-empty value
+   * — so the cart is guest-first (no token → anonymous request the route accepts)
+   * and authed when a user is signed in (token → route can tag the owner). Can be
+   * sync or async (e.g. read a session). Never required.
+   */
+  getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+  /** Injectable fetch (default global). */
+  fetch?: typeof fetch;
+}
+
+export function httpSync<TItem extends CartItem = CartItem>(
+  opts: HttpSyncOptions = {},
+): CartSyncAdapter<TItem> {
+  const endpoint = opts.endpoint ?? "/api/cart";
+  const doFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  const base = { "content-type": "application/json", ...opts.headers };
+
+  // Resolve per-request so a token that appears mid-session (user logs in) is
+  // picked up without recreating the adapter. Guest path: returns `base` as-is.
+  async function headers(): Promise<Record<string, string>> {
+    const token = opts.getToken ? await opts.getToken() : null;
+    return token ? { ...base, authorization: `Bearer ${token}` } : base;
+  }
+
+  return {
+    async push(snapshot: CartSnapshot<TItem>): Promise<void> {
+      // `keepalive` lets the tab-hide flush finish after the page starts
+      // unloading — the browser equivalent of sendBeacon for a PUT with a body.
+      const res = await doFetch(endpoint, {
+        method: "PUT",
+        headers: await headers(),
+        body: JSON.stringify(snapshot),
+        keepalive: true,
+      });
+      if (!res.ok) throw new Error(`cart push ${res.status}`);
+    },
+
+    async pull(id: string, namespace: string): Promise<TItem[] | null> {
+      const url = `${endpoint}?id=${encodeURIComponent(id)}&namespace=${encodeURIComponent(namespace)}`;
+      const res = await doFetch(url, { headers: await headers() });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`cart pull ${res.status}`);
+      const body = (await res.json()) as { items?: TItem[] };
+      return body.items ?? null;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+// @ikeboy003/cart — headless cart primitive.
+// Core (framework-agnostic) + the default HTTP sync adapter. The React binding
+// is a separate entry (`@ikeboy003/cart/react`) so server / non-React code can
+// use the engine without React.
+
+export { CartEngine, createCart } from "./engine.js";
+export { httpSync, type HttpSyncOptions } from "./http-sync.js";
+export type {
+  CartItem,
+  CartSnapshot,
+  CartSyncAdapter,
+  CreateCartOptions,
+} from "./types.js";

package/src/react.tsx

@@ -0,0 +1,72 @@
+// Optional React binding — `CartProvider` + `useCart`. Headless: it exposes cart
+// state and actions, no markup. You design the drawer, the add button, the
+// checkout page. Imported separately (`@ikeboy003/cart/react`) so non-React /
+// server code can use the engine without pulling React in.
+
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { CartEngine } from "./engine.js";
+import type { CartItem, CreateCartOptions } from "./types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const EngineContext = createContext<CartEngine<any> | null>(null);
+
+export interface CartProviderProps<TItem extends CartItem = CartItem>
+  extends CreateCartOptions<TItem> {
+  children: ReactNode;
+}
+
+export function CartProvider<TItem extends CartItem = CartItem>({
+  children,
+  ...opts
+}: CartProviderProps<TItem>) {
+  // One engine per mount, keyed by namespace (effectively stable).
+  const engine = useMemo(
+    () => new CartEngine<TItem>(opts),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [opts.namespace],
+  );
+
+  useEffect(() => {
+    void engine.restore();
+    return () => engine.dispose();
+  }, [engine]);
+
+  return <EngineContext.Provider value={engine}>{children}</EngineContext.Provider>;
+}
+
+export function useCart<TItem extends CartItem = CartItem>() {
+  const engine = useContext(EngineContext) as CartEngine<TItem> | null;
+  if (!engine) throw new Error("useCart must be used inside <CartProvider>");
+
+  const items = useSyncExternalStore(
+    engine.subscribe,
+    engine.getSnapshot,
+    engine.getSnapshot, // server snapshot: stable empty array
+  );
+
+  const count = items.reduce((n, l) => n + l.quantity, 0);
+  const subtotalCents = items.reduce((n, l) => n + l.priceCents * l.quantity, 0);
+
+  return {
+    cartId: engine.id,
+    items,
+    count,
+    /** Subtotal in cents. */
+    subtotalCents,
+    add: (item: TItem) => engine.add(item),
+    remove: (id: string) => engine.remove(id),
+    updateQuantity: (id: string, quantity: number) => engine.updateQuantity(id, quantity),
+    clear: () => engine.clear(),
+    /** Force the durable mirror current — call before navigating to checkout. */
+    flush: () => engine.flush(),
+  };
+}

package/src/types.ts

@@ -0,0 +1,70 @@
+// @ikeboy003/cart — headless cart primitive. "postgrest-rs for carts": import
+// the engine, inject config (namespace, storage, sync), design your own UI.
+//
+// The library knows NOTHING about Square / Toast / Stripe / D1 / Cloudflare /
+// auth / fulfillment / item kind. Those are the app's concern. The proven flow
+// the primitive slots into:
+//
+//   frontend cart (this lib)
+//     -> durable cart row (app's sync adapter; usually D1)
+//     -> checkout / payment
+//     -> payment webhook
+//     -> graft pipeline looks up the durable cart
+//     -> creates merchant/POS records (Square, Toast, ...  — swappable sink)
+//
+// The lib owns only the left edge: local cart state + a configurable durable
+// write path. Everything right of the durable row is runtime/config.
+
+/**
+ * The minimum a line needs for cart mechanics: a stable `id`, a `quantity`, and
+ * a `priceCents` (so count/subtotal work). Everything else is optional or rides
+ * in `metadata` untouched — the app maps its product shape onto this. The engine
+ * is generic over the line type, so a site can extend this with typed fields and
+ * keep full type-safety end to end.
+ */
+export interface CartItem {
+  id: string;
+  quantity: number;
+  priceCents: number;
+  title?: string;
+  sku?: string;
+  /** Opaque passthrough — variationId, options, anything the POS pipeline reads. */
+  metadata?: Record<string, unknown>;
+}
+
+/** The whole cart at a moment — the unit a sync adapter pushes/pulls. */
+export interface CartSnapshot<TItem extends CartItem = CartItem> {
+  /** Anonymous cart id (uuid), minted client-side, persisted in storage. */
+  id: string;
+  /** App-chosen scope (e.g. a site/store name). Opaque to the lib. */
+  namespace: string;
+  items: TItem[];
+  /** Epoch ms of the last local mutation — lets a durable store keep newest-wins. */
+  updatedAt: number;
+}
+
+/**
+ * Configurable durable write path — the equivalent of postgrest-rs's connection
+ * string. The engine calls `push` (debounced + on flush/tab-hide) and `pull`
+ * (on `restore()` when local is empty). The lib ships an HTTP adapter; an app
+ * can pass any implementation. Throwing is non-fatal: the local cart is the
+ * source of truth and the next change retries.
+ */
+export interface CartSyncAdapter<TItem extends CartItem = CartItem> {
+  push(snapshot: CartSnapshot<TItem>): Promise<void>;
+  pull(id: string, namespace: string): Promise<TItem[] | null>;
+}
+
+/** Config passed at import — nothing brand-specific is baked in. */
+export interface CreateCartOptions<TItem extends CartItem = CartItem> {
+  /** Scopes the storage keys + cart id, and is carried in the snapshot. */
+  namespace: string;
+  /** Persistence. Defaults to localStorage; pass `null` for in-memory only. */
+  storage?: Storage | null;
+  /** Durable mirror. Omit for local-only. */
+  sync?: CartSyncAdapter<TItem>;
+  /** Coalesce window for durable pushes (ms). Default 400. */
+  debounceMs?: number;
+  /** Id minter. Default `crypto.randomUUID`. */
+  newId?: () => string;
+}