@teincfood/core 0.9.23 → 0.9.24

package/dist/db/operations.d.ts

@@ -74,6 +74,37 @@ export declare function insertOrder(db: SQLiteDatabase, order: import("../types/
     hlc?: string;
 }): Promise<void>;
 export declare function getOrderById(db: SQLiteDatabase, businessId: string, idOrNumber: string): Promise<import("../types/api/seller.api").SellerOrder | null>;
+/**
+ * Local intent for an order that still has unsynced work in `sync_jobs`.
+ *
+ * While a command is queued the device's intent must win over the server
+ * copy: a pull that lands before the command syncs would otherwise revert a
+ * queued accept (or a queued cash payment) back to the server's older state.
+ *
+ * `status` is the target status of the LAST queued transition, `isPaid` is
+ * true when a cash confirmation is still queued.
+ */
+export interface PendingOrderIntent {
+    status: string | null;
+    isPaid: boolean;
+    hasPending: boolean;
+}
+export declare function getPendingOrderIntent(db: SQLiteDatabase, businessId: string, orderId: string): Promise<PendingOrderIntent>;
+/**
+ * Write a server order into the local read model.
+ *
+ * Unlike `insertOrder` (which is HLC-guarded for local/LAN writes), the
+ * server copy is authoritative: it always overwrites the row. The only
+ * exception is an order with unsynced local work — its status and payment
+ * stay as the device intended until the queued command is acknowledged.
+ *
+ * The HLC is taken from the server's own `updated_at` so device clock skew
+ * can never make a fresh server state look stale.
+ */
+export declare function upsertServerOrder(db: SQLiteDatabase, order: import("../types/api/seller.api").SellerOrder, opts?: {
+    preserveStatus?: boolean;
+    preservePayment?: boolean;
+}): Promise<void>;
 export declare function listOrders(db: SQLiteDatabase, businessId: string, filters?: {
     status?: string;
     q?: string;

package/dist/db/operations.js

@@ -2,6 +2,11 @@
  * Low-level SQLite operations for the command outbox and event journal.
  */
 import { syncLogger } from "../utils/sync-logger";
+import { getQueuedStatus } from "../utils/order-transitions";
+/** Target status a queued command will produce on the server. */
+function queuedStatusOf(commandType) {
+    return getQueuedStatus(commandType);
+}
 export async function insertCommand(db, input) {
     const { command, status = "pending" } = input;
     const now = new Date().toISOString();
@@ -245,6 +250,56 @@ export async function getOrderById(db, businessId, idOrNumber) {
     const row = await db.getFirstAsync(`SELECT * FROM orders WHERE business_id = ? AND (id = ? OR order_number = ?) LIMIT 1;`, businessId, idOrNumber, idOrNumber);
     return row ? orderRowToSellerOrder(row) : null;
 }
+export async function getPendingOrderIntent(db, businessId, orderId) {
+    const empty = { status: null, isPaid: false, hasPending: false };
+    try {
+        const rows = await db.getAllAsync(`SELECT command_type FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND status = 'pending' ORDER BY created_at ASC, rowid ASC;`, businessId, orderId);
+        if (!rows.length)
+            return empty;
+        let status = null;
+        let isPaid = false;
+        for (const row of rows) {
+            const commandType = row.command_type ?? "";
+            const target = queuedStatusOf(commandType);
+            if (target)
+                status = target;
+            if (commandType === "payment:confirm_cash" || commandType === "order:confirm_cash") {
+                isPaid = true;
+            }
+        }
+        return { status, isPaid, hasPending: true };
+    }
+    catch {
+        return empty;
+    }
+}
+/**
+ * Write a server order into the local read model.
+ *
+ * Unlike `insertOrder` (which is HLC-guarded for local/LAN writes), the
+ * server copy is authoritative: it always overwrites the row. The only
+ * exception is an order with unsynced local work — its status and payment
+ * stay as the device intended until the queued command is acknowledged.
+ *
+ * The HLC is taken from the server's own `updated_at` so device clock skew
+ * can never make a fresh server state look stale.
+ */
+export async function upsertServerOrder(db, order, opts = {}) {
+    if (!order?.id || !order?.business_id)
+        return;
+    const existing = await getOrderById(db, order.business_id, order.id);
+    const status = opts.preserveStatus && existing ? existing.status : order.status;
+    const payment = opts.preservePayment && existing ? existing.payment : order.payment;
+    const hlc = order.hlc ??
+        order.updated_at ??
+        order.inserted_at ??
+        new Date().toISOString();
+    const updatedAt = order.updated_at ?? order.inserted_at;
+    await db.runAsync(`INSERT INTO orders (id, business_id, order_number, callout_number, status, order_type, is_pos, items, subtotal_minor, total_minor, tax_minor, tax_lines, payment, customer_name, customer_phone, pos_payment_method, delivery_id, business, user, inserted_at, updated_at, hlc)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET business_id=excluded.business_id, order_number=excluded.order_number, callout_number=excluded.callout_number, status=excluded.status, order_type=excluded.order_type, is_pos=excluded.is_pos, items=excluded.items, subtotal_minor=excluded.subtotal_minor, total_minor=excluded.total_minor, tax_minor=excluded.tax_minor, tax_lines=excluded.tax_lines, payment=excluded.payment, customer_name=excluded.customer_name, customer_phone=excluded.customer_phone, pos_payment_method=excluded.pos_payment_method, delivery_id=excluded.delivery_id, business=excluded.business, user=excluded.user, updated_at=excluded.updated_at, hlc=excluded.hlc, sync_failed_at=NULL, sync_error=NULL;`, order.id, order.business_id, order.order_number, order.callout_number, status, order.order_type, order.is_pos ? 1 : 0, JSON.stringify(order.items ?? []), order.subtotal_minor ?? 0, order.total_minor ?? 0, order.tax_minor ?? 0, JSON.stringify(order.tax_lines ?? []), JSON.stringify(payment), order.customer_name, order.customer_phone, order.pos_payment_method, order.delivery_id, order.business ? JSON.stringify(order.business) : null, order.user ? JSON.stringify(order.user) : null, order.inserted_at, updatedAt, hlc);
+    notifyDbChange(order.business_id, "orders");
+}
 export async function listOrders(db, businessId, filters, page = 1, pageSize = 20) {
     const where = ["business_id = ?"];
     const args = [businessId];

package/dist/domain/orders/service.js

@@ -101,7 +101,13 @@ export async function createLocalOrder(businessId, input) {
     if (!dd)
         throw new Error("No device number leased (99 max) — connect online once to lease DD");
     const id = (input.id ?? input.command_id ?? generateUUID());
-    const orderNumber = input.order_number?.toString() ?? generateOrderNumberForBusiness(businessId);
+    // Order numbers must be real strings. A non-string value used to be
+    // coerced with `.toString()`, which wrote "[object Object]" into the local
+    // DB and broke every lookup for that order.
+    const rawOrderNumber = input.order_number;
+    const orderNumber = typeof rawOrderNumber === "string" && /^[A-Za-z0-9-]{1,32}$/.test(rawOrderNumber)
+        ? rawOrderNumber
+        : generateOrderNumberForBusiness(businessId);
     const callout = parseInt(orderNumber.split("-")[2] ?? "0", 10) || 0;
     // Use client-provided timestamps for offline-first sync so records created
     // while offline retain their original creation time.
@@ -195,10 +201,19 @@ export async function transitionLocalOrder(businessId, orderId, action) {
     }
     try {
         const now = new Date().toISOString();
-        const jobId = generateUUID();
-        await db.runAsync(`INSERT OR IGNORE INTO sync_jobs (id, business_id, command_type, entity_id, payload, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?);`, jobId, businessId, `order:${action}`, orderId, JSON.stringify({ action, orderId }), now, now);
-        syncLogger.debug("DomainOrders", "transition sync_jobs enqueued", { businessId, orderId, action, jobId });
-        void drainOne(businessId, orderId).catch((e) => syncLogger.debug("DomainOrders", "drainOne after transition caught", { err: String(e) }));
+        const commandType = `order:${action}`;
+        // Coalesce duplicates: the same transition queued twice (double tap,
+        // replay) must not be sent to the backend twice.
+        const duplicate = await db.getFirstAsync(`SELECT id FROM sync_jobs WHERE business_id = ? AND entity_id = ? AND command_type = ? AND status = 'pending' LIMIT 1;`, businessId, orderId, commandType);
+        if (!duplicate) {
+            const jobId = generateUUID();
+            await db.runAsync(`INSERT OR IGNORE INTO sync_jobs (id, business_id, command_type, entity_id, payload, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 'pending', ?, ?);`, jobId, businessId, commandType, orderId, JSON.stringify({ action, orderId }), now, now);
+            syncLogger.debug("DomainOrders", "transition sync_jobs enqueued", { businessId, orderId, action, jobId });
+            void drainOne(businessId, orderId).catch((e) => syncLogger.debug("DomainOrders", "drainOne after transition caught", { err: String(e) }));
+        }
+        else {
+            syncLogger.debug("DomainOrders", "transition already queued — job not duplicated", { businessId, orderId, action, jobId: duplicate.id });
+        }
     }
     catch (e) {
         syncLogger.debug("DomainOrders", "transition enqueue fail", { err: String(e) });
@@ -215,15 +230,12 @@ export async function listLocalOrders(businessId, filters, page = 1, pageSize =
     const db = await openSyncDatabase();
     const res = await listOrders(db, businessId, filters, page, pageSize);
     if (res.total === 0) {
-        // blank-screen: snapshot fallback already tried — if still empty and online, fetch from cloud now so listing populates without manual refresh
+        // Cold device (no local rows yet): fetch in the BACKGROUND. Blocking the
+        // render on a multi-page network pull froze the screen for seconds on a
+        // fresh terminal; the pull writes to SQLite and the reconciliation
+        // bridge refreshes the list when it lands.
         if (isOnline() && canBusinessSync(businessId)) {
-            try {
-                await pullRemoteOrders(businessId);
-            }
-            catch { }
-            const afterPull = await listOrders(db, businessId, filters, page, pageSize);
-            if (afterPull.total > 0)
-                return afterPull;
+            void pullRemoteOrders(businessId).catch((e) => syncLogger.debug("DomainOrders", "background pull failed", { businessId, err: String(e) }));
         }
         // filtered miss — still try backfill re-read
         if (!filters || Object.keys(filters).length === 0) {

package/dist/hooks/delivery.hooks.d.ts

@@ -36,10 +36,10 @@ export declare function useBusinessDeliveriesQuery(enabled?: boolean, filters?:
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/query-core").FetchNextPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/query-core").FetchPreviousPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
@@ -70,10 +70,10 @@ export declare function useBusinessDeliveriesQuery(enabled?: boolean, filters?:
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/query-core").FetchNextPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/query-core").FetchPreviousPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
@@ -105,10 +105,10 @@ export declare function useBusinessDeliveriesQuery(enabled?: boolean, filters?:
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/query-core").FetchNextPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/query-core").FetchPreviousPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
@@ -138,10 +138,10 @@ export declare function useBusinessDeliveriesQuery(enabled?: boolean, filters?:
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/query-core").FetchNextPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/query-core").FetchPreviousPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
@@ -172,10 +172,10 @@ export declare function useBusinessDeliveriesQuery(enabled?: boolean, filters?:
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/query-core").FetchNextPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/query-core").FetchPreviousPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     isFetchNextPageError: boolean;
@@ -206,10 +206,10 @@ export declare function useBusinessDeliveriesQuery(enabled?: boolean, filters?:
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: import("@tanstack/react-query").RefetchOptions) => Promise<import("@tanstack/react-query").QueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchStatus: import("@tanstack/react-query").FetchStatus;
-    fetchNextPage: (options?: import("@tanstack/react-query").FetchNextPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
-    fetchPreviousPage: (options?: import("@tanstack/react-query").FetchPreviousPageOptions) => Promise<import("@tanstack/react-query").InfiniteQueryObserverResult<import("@tanstack/react-query").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchStatus: import("@tanstack/query-core").FetchStatus;
+    fetchNextPage: (options?: import("@tanstack/query-core").FetchNextPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
+    fetchPreviousPage: (options?: import("@tanstack/query-core").FetchPreviousPageOptions) => Promise<import("@tanstack/query-core").InfiniteQueryObserverResult<import("@tanstack/query-core").InfiniteData<ListPage<BusinessDelivery>, unknown>, Error>>;
     hasNextPage: boolean;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;

package/dist/hooks/realtime-stubs.d.ts

@@ -1,28 +1,35 @@
 /**
- * Realtime invalidation hooks — bridge Phoenix WebSocket events into the
- * Sync Engine so useSyncReconciliation fires and React Query caches refresh.
+ * Realtime invalidation hooks.
  *
- * Both hooks are idempotent-safe and can be called from multiple screens.
- * Invalidations are debounced: a reconnect/replay burst can deliver dozens
+ * The cloud → local event path now has a single owner: the global realtime
+ * bridge (`src/realtime/realtime-bridge.ts`), mounted once per app. It
+ * publishes every cloud event through the Sync Engine, and
+ * `useSyncReconciliation` reacts by journaling the event, patching the
+ * offline read model, invalidating the affected caches (debounced, 400 ms)
+ * and relaying the event to LAN peers.
+ *
+ * `useOrderRealtimeUpdates` used to be mounted per screen (POS, Orders,
+ * Kitchen, Display). That meant every mounted screen processed the same
+ * event — duplicated persistence, duplicated invalidations, duplicated
+ * fetches — and every screen that did NOT mount it (Dashboard, Settings)
+ * never saw another terminal's order at all. It is kept as a no-op so
+ * existing call sites keep compiling; new code must not use it.
+ *
+ * Invalidations stay coalesced: a reconnect/replay burst can deliver dozens
  * of events at once, and an immediate invalidate-per-event forces repeated
- * full re-renders of boards/grids — a major CPU spike source on low-power
- * POS hardware. Coalescing into one invalidation per ~400ms window keeps
- * the UI fresh without the render storm.
+ * full re-renders of boards/grids — a major CPU spike on low-power POS
+ * hardware. One invalidation per ~400 ms window keeps the UI fresh without
+ * the render storm.
  */
 /**
- * Subscribe to real-time order events and invalidate all queries under the
- * given root key prefix (e.g. ['seller'], ['pos'], ['kiosk']).
- *
- * Each event is also persisted to the durable offline read model so order
- * history and states survive a restart while offline, and published through
- * the Sync Engine so useSyncReconciliation + LAN relay fire without polling.
- *
- * Call once per screen that needs live updates (POS, Orders, Kitchen, etc.).
+ * @deprecated Mount the global bridge once at the app root instead
+ * (`useRealtimeInvalidation` or `useSyncReconciliation`). Kept as a no-op
+ * so legacy call sites remain source-compatible.
  */
-export declare function useOrderRealtimeUpdates(rootKey: readonly string[]): void;
+export declare function useOrderRealtimeUpdates(_rootKey: readonly string[]): void;
 /**
- * Global realtime invalidation — currently handled entirely by
- * useOrderRealtimeUpdates + useSyncReconciliation. Kept as a no-op for
- * backward compatibility with any lingering call sites.
+ * Global realtime invalidation — mounts the single app-wide Phoenix
+ * subscription. Pair with `useSyncReconciliation` (which reacts to the
+ * published events) at the app root.
  */
 export declare function useRealtimeInvalidation(): void;

package/dist/hooks/realtime-stubs.js

@@ -1,133 +1,38 @@
 /**
- * Realtime invalidation hooks — bridge Phoenix WebSocket events into the
- * Sync Engine so useSyncReconciliation fires and React Query caches refresh.
+ * Realtime invalidation hooks.
  *
- * Both hooks are idempotent-safe and can be called from multiple screens.
- * Invalidations are debounced: a reconnect/replay burst can deliver dozens
- * of events at once, and an immediate invalidate-per-event forces repeated
- * full re-renders of boards/grids — a major CPU spike source on low-power
- * POS hardware. Coalescing into one invalidation per ~400ms window keeps
- * the UI fresh without the render storm.
- */
-import { useEffect } from "react";
-import { useQueryClient } from "@tanstack/react-query";
-import { orderEventsService } from "../realtime/order-events.service";
-import { orderSnapshotsService } from "../sync/order-snapshots.service";
-import { syncEngine } from "../sync/engine";
-import { generateEventId } from "../utils/uuid";
-import { getAppInstanceId } from "../adapters/devices";
-import { getActiveBusiness } from "../adapters/business";
-import { openSyncDatabase } from "../db/connection";
-import { getOrderById } from "../db/operations";
-const INVALIDATE_DEBOUNCE_MS = 400;
-const UNKNOWN_ORDER_PULL_DEBOUNCE_MS = 1500;
-/**
- * Subscribe to real-time order events and invalidate all queries under the
- * given root key prefix (e.g. ['seller'], ['pos'], ['kiosk']).
+ * The cloud → local event path now has a single owner: the global realtime
+ * bridge (`src/realtime/realtime-bridge.ts`), mounted once per app. It
+ * publishes every cloud event through the Sync Engine, and
+ * `useSyncReconciliation` reacts by journaling the event, patching the
+ * offline read model, invalidating the affected caches (debounced, 400 ms)
+ * and relaying the event to LAN peers.
  *
- * Each event is also persisted to the durable offline read model so order
- * history and states survive a restart while offline, and published through
- * the Sync Engine so useSyncReconciliation + LAN relay fire without polling.
+ * `useOrderRealtimeUpdates` used to be mounted per screen (POS, Orders,
+ * Kitchen, Display). That meant every mounted screen processed the same
+ * event — duplicated persistence, duplicated invalidations, duplicated
+ * fetches — and every screen that did NOT mount it (Dashboard, Settings)
+ * never saw another terminal's order at all. It is kept as a no-op so
+ * existing call sites keep compiling; new code must not use it.
  *
- * Call once per screen that needs live updates (POS, Orders, Kitchen, etc.).
+ * Invalidations stay coalesced: a reconnect/replay burst can deliver dozens
+ * of events at once, and an immediate invalidate-per-event forces repeated
+ * full re-renders of boards/grids — a major CPU spike on low-power POS
+ * hardware. One invalidation per ~400 ms window keeps the UI fresh without
+ * the render storm.
  */
-export function useOrderRealtimeUpdates(rootKey) {
-    const queryClient = useQueryClient();
-    useEffect(() => {
-        let timer;
-        const pendingOrderIds = new Set();
-        const pending = { rootKey: false };
-        const ownDeviceId = getAppInstanceId();
-        const flush = () => {
-            timer = undefined;
-            if (pending.rootKey)
-                queryClient.invalidateQueries({ queryKey: rootKey });
-            for (const oid of pendingOrderIds) {
-                queryClient.invalidateQueries({ queryKey: [...rootKey, "order", oid] });
-            }
-            pendingOrderIds.clear();
-            pending.rootKey = false;
-        };
-        const unsub = orderEventsService.onOrderUpdates((event) => {
-            pending.rootKey = true;
-            if (event.order_id)
-                pendingOrderIds.add(event.order_id);
-            const payload = { ...event };
-            // Delivery events carry no business_id — the socket already filtered by
-            // business, so stamp the active one for read-model patching.
-            if (!payload.business_id && !payload.businessId) {
-                try {
-                    const bid = getActiveBusiness()?.id;
-                    if (bid)
-                        payload.business_id = bid;
-                }
-                catch { }
-            }
-            const domainEvent = {
-                event_id: payload.event_id ?? generateEventId(),
-                event_type: event.type,
-                event_version: payload.event_version ?? "1.0",
-                timestamp: payload.timestamp ?? new Date().toISOString(),
-                device_id: payload.device_id ?? ownDeviceId,
-                user_id: payload.user_id ?? "system",
-                entity_id: event.order_id ?? "",
-                payload,
-            };
-            // Persist to durable offline read model (entity_snapshots table).
-            orderSnapshotsService.persistOrderEvent(domainEvent, "cloud").catch(() => { });
-            // order.created from another terminal is summary-only (no full body):
-            // invalidate alone can't surface it because SQLite has no row. Pull
-            // once (debounced) when the order is unknown locally. Event-driven —
-            // no polling.
-            if (event.type === "order.created" && event.order_id) {
-                const bid = payload.business_id;
-                if (bid) {
-                    void (async () => {
-                        try {
-                            const db = await openSyncDatabase();
-                            const known = await getOrderById(db, bid, event.order_id);
-                            if (!known)
-                                scheduleUnknownOrderPull(bid);
-                        }
-                        catch { }
-                    })();
-                }
-            }
-            // Publish through the Sync Engine so useSyncReconciliation + LAN relay
-            // fire without waiting for the next poll.
-            try {
-                syncEngine.publish(domainEvent);
-            }
-            catch { }
-            if (!timer)
-                timer = setTimeout(flush, INVALIDATE_DEBOUNCE_MS);
-        });
-        return () => {
-            if (timer)
-                clearTimeout(timer);
-            unsub();
-        };
-    }, [queryClient, rootKey]);
-}
+import { useGlobalRealtimeBridge } from "../realtime/realtime-bridge";
 /**
- * Debounced pull for remotely-created orders (one timer per business).
- * Module-level so bursts across screens coalesce into a single pull.
+ * @deprecated Mount the global bridge once at the app root instead
+ * (`useRealtimeInvalidation` or `useSyncReconciliation`). Kept as a no-op
+ * so legacy call sites remain source-compatible.
  */
-const unknownOrderPullTimers = new Map();
-function scheduleUnknownOrderPull(businessId) {
-    if (unknownOrderPullTimers.has(businessId))
-        return;
-    const t = setTimeout(() => {
-        unknownOrderPullTimers.delete(businessId);
-        void import("../sync/sync-jobs.service")
-            .then((m) => m.pullRemoteOrders(businessId))
-            .catch(() => { });
-    }, UNKNOWN_ORDER_PULL_DEBOUNCE_MS);
-    unknownOrderPullTimers.set(businessId, t);
-}
+export function useOrderRealtimeUpdates(_rootKey) { }
 /**
- * Global realtime invalidation — currently handled entirely by
- * useOrderRealtimeUpdates + useSyncReconciliation. Kept as a no-op for
- * backward compatibility with any lingering call sites.
+ * Global realtime invalidation — mounts the single app-wide Phoenix
+ * subscription. Pair with `useSyncReconciliation` (which reacts to the
+ * published events) at the app root.
  */
-export function useRealtimeInvalidation() { }
+export function useRealtimeInvalidation() {
+    useGlobalRealtimeBridge();
+}