@tallyui/pos 0.1.0 → 2.0.0

package/src/sale/use-sale.ts

@@ -0,0 +1,337 @@
+import { useEffect, useRef, useState } from 'react';
+import type { ProductTraits, ServerCapabilities, StoreSettings } from '@tallyui/core';
+import { createOrderBuilder, type Discount, type Order } from '../order';
+import { finalizeOrder, type PosOrder } from '../pos-order';
+import { useTax } from '../tax';
+import { recordRegisterFact, stampSession, type RegisterSessionCollection } from '../register';
+import { createLogger } from '../logging';
+import type { CatalogueEntry } from './catalogue';
+import { addEntryToCart, CartError } from './cart';
+
+/** Logs a throw from onSaleCompleted for a confirmed pending completion newSale() has abandoned (Continue): nothing else would ever surface it. */
+export const saleLogger = createLogger('sale');
+
+export type SaleStage = { kind: 'cart' } | { kind: 'tender'; method: 'cash' | 'external' }
+  | { kind: 'receipt'; order: Order; posOrder: PosOrder };
+/** TallyUI finalizeOrder's refusal below order.create v2 (c19a203), shown when the discount is applied; finalize stays the backstop. */
+export const DISCOUNTS_UNSUPPORTED = 'finalize: discounts are not supported by the server yet (order.create v2)';
+/** Every sale change refuses with this while a completion is pending (see `complete()`). */
+export const SALE_SAVING = 'This sale is being saved. Retry to finish it.';
+/**
+ * How often a hung save re-asks `isStored`, while the order is built and its save is still in flight
+ * and unconfirmed: an app whose tender has no New sale control while saving (the Front desk,
+ * 2026-09-28) never re-asks otherwise, so the cashier could only wait for a hung post-insert step.
+ * `useSale`'s `hungSaveCheckMs` overrides this; that option is tests only.
+ */
+export const HUNG_SAVE_CHECK_MS = 5000;
+
+/** Call under a `TaxProvider`: its tax context and the settings' currency price every sale. */
+export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
+  registerId: string; cashierRef: string; capabilities?: ServerCapabilities;
+  /**
+   * When set, `complete()` stamps the finalized order with this session before `onSaleCompleted`.
+   * `complete()` runs after the money is taken, so a refused stamp (the session closed or went
+   * missing) never stops the sale: it goes on to `onSaleCompleted` and the receipt with
+   * `lateSessionId` instead of `sessionId`, and a `late-sale` register fact is recorded (ADR-032).
+   * The session stamped is the one in force when the tender started (`startTender`), pinned for that
+   * tender: this option going undefined mid-tender (the session closed) doesn't skip the stamp. A
+   * tender that pinned none, with a session here at `complete()`, stamps it and logs a warning.
+   */
+  session?: { id: string; sessions: RegisterSessionCollection };
+  onSaleCompleted?: (posOrder: PosOrder) => Promise<void> | void;
+  /**
+   * Asked after `onSaleCompleted` throws, or on a `newSale()` refused mid-save: whether that order is confirmed stored
+   * (medusapos: `useOrderOutbox`'s `isStored`). Only a true answer sets `canContinue`; without it, a failed save offers Retry only.
+   */
+  isStored?: (posOrder: PosOrder) => Promise<boolean>;
+  /** Tests only: overrides HUNG_SAVE_CHECK_MS, so a test can shrink the hung-save poll's interval. */
+  hungSaveCheckMs?: number;
+}) {
+  const taxContext = useTax();
+  const madeWith = useRef({ taxContext, currency: settings.currency });
+  const [builder, setBuilder] = useState(() => createOrderBuilder({ currency: settings.currency, taxContext }));
+  const [order, setOrder] = useState(() => builder.getSnapshot());
+  const [stage, setStage] = useState<SaleStage>({ kind: 'cart' });
+  const [error, setError] = useState<string | null>(null);
+  // The pending completion: the order complete() built for this tender attempt. The ref is read
+  // synchronously by complete() and the lock; `saving` mirrors it (true from complete()'s entry) for rendering.
+  const pending = useRef<{ order: Order; posOrder: PosOrder } | null>(null);
+  const [saving, setSaving] = useState(false);
+  // The session pinned by startTender for this tender (`undefined` inside: none); null until a tender starts.
+  const tenderSession = useRef<{ session: typeof opts.session } | null>(null);
+  // The pending completion isStored confirmed stored after its save failed; `canContinue` mirrors it for
+  // rendering. `attempts` counts complete() attempts, so a confirmation that lands after a new one is dropped.
+  const confirmed = useRef<{ order: Order; posOrder: PosOrder } | null>(null);
+  const [canContinue, setCanContinue] = useState(false);
+  const attempts = useRef(0);
+  // The hung-save poll (at most one at a time): deliver() arms it while a completion's save is in
+  // flight, and it, confirm() and unmount all clear it.
+  const hungSaveTimer = useRef<ReturnType<typeof setInterval> | null>(null);
+  // Guards overlapping isStored checks (#161 review), per completion: a tick skips only while its own
+  // completion's check is already in flight, so an isStored slower than the interval never has more
+  // than one check running at once for that completion. Scoped to the completion (not a bare boolean)
+  // so a completion whose isStored never settles can never block a later sale's own poll (#161 follow-up).
+  const checking = useRef<{ order: Order; posOrder: PosOrder } | null>(null);
+  function clearHungSaveTimer() {
+    if (hungSaveTimer.current !== null) { clearInterval(hungSaveTimer.current); hungSaveTimer.current = null; }
+  }
+  function confirm(completion: { order: Order; posOrder: PosOrder } | null) {
+    confirmed.current = completion;
+    setCanContinue(!!completion);
+    clearHungSaveTimer();
+  }
+  // The complete() call in flight, and the stage as of the last render or receipt, both read synchronously.
+  const inFlight = useRef<Promise<void> | null>(null);
+  const stageNow = useRef(stage);
+  stageNow.current = stage;
+  /** True, with SALE_SAVING shown, from complete()'s entry (inFlight) through a pending retry: the sale can't change. */
+  function locked() {
+    const active = !!(inFlight.current || pending.current);
+    if (active) setError(SALE_SAVING);
+    return active;
+  }
+  useEffect(() => {
+    const subscription = builder.order$.subscribe(setOrder);
+    return () => subscription.unsubscribe();
+  }, [builder]);
+  // New tax settings or currency wait until the sale is idle (an empty cart), then start a new sale on them:
+  // a sale in progress (lines, tender or receipt) finishes on the settings it started with (a money rule).
+  const idle = stage.kind === 'cart' && !order.lineItems.length;
+  useEffect(() => {
+    if (idle && (madeWith.current.taxContext !== taxContext || madeWith.current.currency !== settings.currency)) result.newSale();
+  });
+  // A screen that unmounts (medusapos: Sign out) mid-save must still leave a trace of the loss.
+  useEffect(() => () => {
+    clearHungSaveTimer();
+    if (pending.current || inFlight.current) {
+      saleLogger.error('useSale unmounted with a save pending or in flight',
+        { orderId: pending.current?.posOrder.id, stage: stageNow.current.kind });
+    }
+  }, []);
+
+  function setTender(tender: { method: 'cash' | 'external'; amountMinor: number; reference?: string } | null) {
+    if (locked()) return;
+    const previous = builder.getSnapshot().payments[0];
+    if (previous) builder.removePayment(previous.id);
+    if (tender) builder.addPayment(tender);
+    setError(null);
+  }
+
+  /** Asks `isStored`; Continue is offered only once it confirms, for this attempt, with the completion still pending. */
+  function checkStored(completion: { order: Order; posOrder: PosOrder }) {
+    const attempt = attempts.current;
+    const isStored = opts.isStored; // a throw, even a synchronous one, counts as not stored
+    if (!isStored) return;
+    checking.current = completion;
+    void Promise.resolve(completion.posOrder).then(isStored).catch(() => false).then((stored) => {
+      if (stored === true && attempts.current === attempt && pending.current === completion) confirm(completion);
+    }).finally(() => { if (checking.current === completion) checking.current = null; });
+  }
+
+  /** Hands a pending completion to `onSaleCompleted`; the outcome applies only if it wasn't abandoned meanwhile. */
+  async function deliver(completion: { order: Order; posOrder: PosOrder }) {
+    clearHungSaveTimer();
+    // Re-asks isStored every HUNG_SAVE_CHECK_MS while this save is in flight and unconfirmed, so a hung
+    // post-insert step (no throw, no resolve) still offers Continue with no user action. Its own
+    // `timer` handle is cleared below only while it's still the current one, so a late settle from an
+    // attempt a newer sale has already superseded can never cut off that newer sale's poll (#161 review).
+    const timer = opts.isStored ? setInterval(() => {
+      if (checking.current === completion) return;
+      if (pending.current === completion && inFlight.current && confirmed.current !== completion) checkStored(completion);
+      else if (hungSaveTimer.current === timer) clearHungSaveTimer();
+    }, opts.hungSaveCheckMs ?? HUNG_SAVE_CHECK_MS) : null;
+    hungSaveTimer.current = timer;
+    try {
+      await opts.onSaleCompleted?.(completion.posOrder);
+    } catch (error) {
+      if (hungSaveTimer.current === timer) clearHungSaveTimer();
+      const message = error instanceof Error ? error.message : String(error);
+      // Logged whatever the mount state and whether or not it's still pending (#150 review): a screen
+      // unmounted mid-save (medusapos Sign out) must never lose a throw silently. Skipped only once the
+      // order is confirmed stored, since a later throw on a known-safe order needs no fresh alarm.
+      if (confirmed.current !== completion) {
+        saleLogger.error('onSaleCompleted failed', { orderId: completion.posOrder.id, error: message });
+      }
+      if (pending.current === completion) {
+        setError(`The sale could not be saved: ${message}`);
+        checkStored(completion);
+      }
+      return;
+    }
+    if (hungSaveTimer.current === timer) clearHungSaveTimer();
+    if (pending.current !== completion) return;
+    pending.current = null;
+    confirm(null);
+    setSaving(false);
+    setError(null);
+    stageNow.current = { kind: 'receipt', order: completion.order, posOrder: completion.posOrder };
+    setStage(stageNow.current);
+  }
+
+  /**
+   * Runs one complete() attempt, unless one is in flight or the receipt shows. The in-flight promise is
+   * set before the attempt's first await, so a second call (a double tap) shares it and never builds a
+   * second order. `.finally` clears `inFlight` only if it still holds this attempt's own promise.
+   */
+  function once(attempt: () => Promise<void>): Promise<void> {
+    if (!inFlight.current && stageNow.current.kind !== 'receipt') {
+      const mine: Promise<void> = attempt().finally(() => { if (inFlight.current === mine) inFlight.current = null; });
+      inFlight.current = mine;
+    }
+    return inFlight.current ?? Promise.resolve();
+  }
+
+  const result = {
+    order, stage, error, idle,
+    /** A completion is pending (see `complete()`): the sale is locked, and the UI offers Retry. */
+    saving,
+    /** The failed save's order is confirmed stored (see `isStored`): the UI also offers Continue (`continueSale()`). */
+    canContinue,
+    add(entry: CatalogueEntry<any>, traits: ProductTraits<any>) {
+      if (locked()) return;
+      try {
+        addEntryToCart(builder, entry, traits, madeWith.current.currency);
+        setError(null);
+      } catch (error) {
+        if (!(error instanceof CartError)) throw error;
+        setError(error.message);
+      }
+    },
+    setQuantity(lineId: string, quantity: number) { if (!locked()) builder.updateQuantity(lineId, quantity); },
+    remove(lineId: string) { if (!locked()) builder.removeItem(lineId); },
+    /** A line's discount, or the order's without a line; returns the refusal to show, or null once applied. */
+    applyDiscount(lineId: string | null, discount: Discount): string | null {
+      if (locked()) return SALE_SAVING;
+      if ((opts.capabilities?.orderCreate ?? 1) < 2) return DISCOUNTS_UNSUPPORTED;
+      const applied = (snapshot: Order) => lineId === null ? snapshot.discounts
+        : snapshot.lineItems.find((line) => line.id === lineId)?.discounts ?? [];
+      const before = new Set(applied(builder.getSnapshot()).map((entry) => entry.id));
+      if (lineId === null) builder.applyOrderDiscount(discount);
+      else builder.applyLineDiscount(lineId, discount);
+      // TallyUI caps a fixed amount at what is left; refuse it instead of showing more off than comes off.
+      const added = applied(builder.getSnapshot()).find((entry) => !before.has(entry.id));
+      if (added?.type === 'fixed' && added.amountMinor < added.value) {
+        builder.removeDiscount(added.id);
+        return `The discount is more than the ${lineId === null ? 'order' : 'line'}`;
+      }
+      return null;
+    },
+    removeDiscount(id: string) { if (!locked()) builder.removeDiscount(id); },
+    /**
+     * Pins `options.session` for this tender when given, else the rendered `session` option. Pass the
+     * session `useRegisterSession`'s `requireSaleSession()` returned: the rendered one can lag a session
+     * opened just before (#170 race). A repeat call mid-tender keeps the first pin.
+     */
+    startTender(method: 'cash' | 'external', options?: { session?: { id: string; sessions: RegisterSessionCollection } }) {
+      if (locked()) return;
+      const current = builder.getSnapshot();
+      if (!current.lineItems.length) return;
+      tenderSession.current ??= { session: options?.session ?? opts.session }; // a repeat call mid-tender keeps the pin
+      setTender(method === 'external' ? { method, amountMinor: current.totalMinor } : null);
+      setStage({ kind: 'tender', method });
+    },
+    setTender,
+    cancelTender() {
+      if (locked()) return;
+      setTender(null);
+      tenderSession.current = null;
+      setStage({ kind: 'cart' });
+    },
+    /**
+     * Finalizes the tender, stamps the session (see `session`), hands the order to `onSaleCompleted`,
+     * then shows the receipt. `saving` turns true and the sale locks (every change sets SALE_SAVING)
+     * from this call's entry, not only once the order is built; a refused finalize unlocks it again,
+     * with the refusal's error. Idempotent for one tender attempt (DECISIONS, ADR-052): once the order
+     * is built, that order is the sale, kept as the pending completion, because `onSaleCompleted` may
+     * already have stored it before failing. If `onSaleCompleted` throws, the error is set and the tender stays;
+     * calling `complete()` again reuses the pending completion exactly (the same `id`, `commandId`
+     * and `createdAt`, no new stamp and no second late-sale fact) and hands it to `onSaleCompleted`
+     * again, so that must accept an order it already stored (as `useOrderOutbox.record` does). The
+     * pending completion is cleared once `onSaleCompleted` resolves, or by `newSale()`. A call while
+     * another is in flight returns that call's promise, and a call on the receipt does nothing.
+     */
+    complete: () => once(async () => {
+      attempts.current++;
+      confirm(null);
+      if (pending.current) return deliver(pending.current);
+      setSaving(true);
+      const current = builder.getSnapshot();
+      let posOrder: PosOrder;
+      try {
+        posOrder = finalizeOrder(current, { registerId: opts.registerId, cashierRef: opts.cashierRef, capabilities: opts.capabilities });
+      } catch (error) {
+        setSaving(false);
+        setError((error as Error).message);
+        return;
+      }
+      // The tender's pinned session; opts.session only for a complete() with no startTender (setTender from the cart),
+      // or when the tender pinned none but a session has rendered since (the backstop, warned: see startTender).
+      const session = tenderSession.current?.session ?? opts.session;
+      if (tenderSession.current && !tenderSession.current.session && session) {
+        try {
+          saleLogger.warn('the tender started before its session rendered; pass the confirmed session to startTender',
+            { orderId: posOrder.id, sessionId: session.id });
+        } catch {
+          // A failing sink must never lose the sale.
+        }
+      }
+      if (session) {
+        try {
+          posOrder = await stampSession(posOrder, session.id, session.sessions);
+        } catch {
+          // The money is taken: keep the sale, outside every closure (ADR-032, late sale).
+          const { sessionId: _unstamped, ...unstamped } = posOrder;
+          posOrder = { ...unstamped, lateSessionId: session.id };
+          try {
+            // useSale knows the cashier only by ref, so the actor carries no display name.
+            recordRegisterFact({ kind: 'late-sale', orderId: posOrder.id, sessionId: session.id, registerId: opts.registerId,
+              actor: { id: opts.cashierRef, name: '' } });
+          } catch {
+            // The logger calls the app's sinks unguarded; a failing sink must never lose the sale.
+          }
+        }
+      }
+      pending.current = { order: current, posOrder };
+      return deliver(pending.current);
+    }),
+    /**
+     * Starts a new, empty sale. Refused with SALE_SAVING, changing nothing, while a save is still
+     * building or stamping (nothing yet to ask `isStored` about), and while a pending completion
+     * exists and isn't confirmed stored — the ways out are Retry (`complete()`) or Continue, once
+     * `canContinue` (the Front desk, 2026-09-27; #149 review). So an app that doesn't pass `isStored`
+     * gets Retry only after a failed save. A refusal while a save is still delivering its order asks
+     * `isStored` afresh, so a hung save whose order is stored can still offer Continue. Past those, it
+     * abandons a confirmed pending completion (never handed to `onSaleCompleted` again: it's stored; a
+     * save still in flight carries on in the background, a throw logged at error) and starts the new
+     * sale outright — from the receipt, or an idle cart, there's nothing pending to abandon. Abandoning
+     * clears the screen, never the record (the Front desk, 2026-09-25). `newSale()` never deletes,
+     * updates or requeues `pos_orders` itself.
+     */
+    newSale() {
+      if (inFlight.current && !pending.current) return setError(SALE_SAVING);
+      if (pending.current && confirmed.current !== pending.current) {
+        if (inFlight.current) checkStored(pending.current);
+        return setError(SALE_SAVING);
+      }
+      confirm(null); pending.current = null;
+      inFlight.current = null;
+      tenderSession.current = null;
+      setSaving(false);
+      madeWith.current = { taxContext, currency: settings.currency };
+      const next = createOrderBuilder({ currency: settings.currency, taxContext });
+      setBuilder(next);
+      setOrder(next.getSnapshot());
+      setStage({ kind: 'cart' });
+      setError(null);
+    },
+    /**
+     * Continue after a failed save whose order is confirmed stored (`canContinue`): exactly `newSale()`.
+     * The order stays pending in the outbox, which will send it; it isn't handed to `onSaleCompleted` again, and
+     * its receipt is not shown. Otherwise does nothing.
+     */
+    continueSale() {
+      if (pending.current && confirmed.current === pending.current) result.newSale();
+    },
+  };
+  return result;
+}

package/src/store-settings/index.ts

@@ -0,0 +1,5 @@
+export { resolveStoreSettings } from './resolve-store-settings';
+export type { StoreSettingsResolution, ResolveStoreSettingsOptions } from './resolve-store-settings';
+export { withPricingContext, taxProviderProps } from './map-store-settings';
+export { useStoreSettings } from './use-store-settings';
+export type { StoreSettingsState } from './use-store-settings';

package/src/store-settings/map-store-settings.ts

@@ -0,0 +1,13 @@
+import type { StoreSettings, SyncContext } from '@tallyui/core';
+import type { TaxProviderProps } from '../tax';
+
+/** The replication's context with the settings' opaque pricing context; the key is left out when the settings have none. */
+export function withPricingContext(context: SyncContext, settings: StoreSettings): SyncContext {
+  const { pricingContext: _previous, ...rest } = context;
+  return settings.pricingContext ? { ...rest, pricingContext: settings.pricingContext } : rest;
+}
+
+/** `<TaxProvider>`'s props from the same settings, so its tax inclusivity matches the connector's. */
+export function taxProviderProps(settings: StoreSettings): Omit<TaxProviderProps, 'children'> {
+  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax };
+}

package/src/store-settings/resolve-store-settings.ts

@@ -0,0 +1,65 @@
+import { StoreSettingsError } from '@tallyui/core';
+import type { StoreSettings, StoreSettingsChoice, StoreSettingsChoices, SyncContext, TallyConnector } from '@tallyui/core';
+
+export type StoreSettingsResolution =
+  | { status: 'ready'; settings: StoreSettings; choice?: StoreSettingsChoice }
+  | { status: 'choose'; choices: StoreSettingsChoices; initial?: StoreSettingsChoice }
+  | { status: 'unsupported' }; // the connector has no storeSettings: the app uses its own configuration
+
+export interface ResolveStoreSettingsOptions {
+  connector: TallyConnector;
+  context: SyncContext;
+  /** The app's stored choice for this store (its own settings; TallyUI never stores it). */
+  loadChoice: () => StoreSettingsChoice | undefined | Promise<StoreSettingsChoice | undefined>;
+  saveChoice: (choice: StoreSettingsChoice) => void | Promise<void>;
+  /** A save that throws after a successful resolve: the pick is asked again next launch. */
+  onSaveError?: (error: unknown) => void;
+}
+
+/**
+ * Narrows `tried` to what `choices` actually offers: a field is dropped only when its own list
+ * is offered and no longer contains it (a deleted region, say); a field whose list isn't
+ * offered passes through unresolved, since only the other parts were ambiguous
+ * (`StoreSettingsChoiceScreen`, #96, relies on that to resubmit it unchanged). A deleted region
+ * can't loop forever: it's dropped once regions are offered, and otherwise the connector's own
+ * default already resolved it.
+ */
+function narrowInitial(tried: StoreSettingsChoice, choices: StoreSettingsChoices): StoreSettingsChoice | undefined {
+  const region = !choices.regions || choices.regions.some((r) => r.id === tried.region) ? tried.region : undefined;
+  const country = !choices.countries || (tried.country !== undefined && choices.countries.includes(tried.country)) ? tried.country : undefined;
+  const channel = !choices.channels || choices.channels.some((c) => c.id === tried.channel) ? tried.channel : undefined;
+  const initial = { ...(region !== undefined && { region }), ...(country !== undefined && { country }), ...(channel !== undefined && { channel }) };
+  return Object.keys(initial).length > 0 ? initial : undefined;
+}
+
+/**
+ * Reads the store settings with the app's choice (TV4). A `choice` argument (a new pick from
+ * the choice screen) wins over the stored one and is saved only once it resolves; a stored
+ * choice is never re-saved. `choice_required` (including a stale stored choice) gives
+ * `choose`, with the tried choice narrowed to what's offered as `initial`, so the screen
+ * pre-selects what still matches. Any other error, `failed` included, is rethrown unchanged.
+ */
+export async function resolveStoreSettings(
+  options: ResolveStoreSettingsOptions,
+  choice?: StoreSettingsChoice,
+): Promise<StoreSettingsResolution> {
+  const { connector, context, loadChoice, saveChoice, onSaveError } = options;
+  if (!connector.storeSettings) return { status: 'unsupported' };
+
+  // A throw, sync or async, is no stored choice; it never bricks the till.
+  const tried = choice ?? (await Promise.resolve().then(loadChoice).catch(() => undefined));
+  let settings: StoreSettings;
+  try {
+    settings = await connector.storeSettings(context, tried);
+  } catch (error) {
+    if (error instanceof StoreSettingsError && error.code === 'choice_required') {
+      const offered = error.choices ?? {};
+      const initial = tried && narrowInitial(tried, offered);
+      return { status: 'choose', choices: offered, ...(initial && { initial }) };
+    }
+    throw error;
+  }
+  // A save that fails doesn't block the till either: the settings already resolved.
+  if (choice) await Promise.resolve().then(() => saveChoice(choice)).catch((error) => onSaveError?.(error));
+  return { status: 'ready', settings, ...(tried && { choice: tried }) };
+}

package/src/store-settings/use-store-settings.ts

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { StoreSettings, StoreSettingsChoice, StoreSettingsChoices } from '@tallyui/core';
+import { resolveStoreSettings } from './resolve-store-settings';
+import type { ResolveStoreSettingsOptions } from './resolve-store-settings';
+
+export type StoreSettingsState =
+  | { state: 'loading' }
+  | { state: 'ready'; settings: StoreSettings; choice?: StoreSettingsChoice }
+  | { state: 'choose'; choices: StoreSettingsChoices; initial?: StoreSettingsChoice; choose: (choice: StoreSettingsChoice) => void }
+  | { state: 'error'; error: unknown; retry: () => void }
+  | { state: 'unsupported' };
+
+// One object, so re-entering loading while already loading doesn't re-render.
+const LOADING: StoreSettingsState = { state: 'loading' };
+
+/**
+ * Resolves the store settings on mount, and again when `connector` or `context` changes by
+ * identity (a store switch), so memoise both; the last request wins. `loadChoice` and
+ * `saveChoice` are read when a request starts, so inline functions don't trigger a re-resolve.
+ *
+ * ```tsx
+ * const store = useStoreSettings({ connector, context, loadChoice, saveChoice });
+ * if (store.state === 'choose')
+ *   return <StoreSettingsChoiceScreen choices={store.choices} initial={store.initial} onSubmit={store.choose} />;
+ * if (store.state !== 'ready') return <Loading />; // or an error with store.retry, or the app's own config when unsupported
+ * const syncContext = withPricingContext(context, store.settings); // for the replication
+ * return <TaxProvider {...taxProviderProps(store.settings)}>{children}</TaxProvider>;
+ * ```
+ */
+export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSettingsState {
+  const { connector, context } = options;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const requestRef = useRef(0);
+  const [state, setState] = useState<StoreSettingsState>(LOADING);
+
+  // `from`, when given, is the request that created the `choose`/`retry` calling this: a call
+  // arriving after a store switch made that request stale is ignored, so it can't apply an old
+  // pick to the new store.
+  const resolve = useCallback((choice?: StoreSettingsChoice, from?: number) => {
+    if (from !== undefined && from !== requestRef.current) return;
+    const request = ++requestRef.current;
+    const current = () => request === requestRef.current;
+    setState(LOADING);
+    resolveStoreSettings(optionsRef.current, choice).then(
+      (result) => {
+        if (!current()) return;
+        if (result.status === 'ready') setState({ state: 'ready', settings: result.settings, choice: result.choice });
+        else if (result.status === 'choose')
+          setState({ state: 'choose', choices: result.choices, initial: result.initial, choose: (pick) => resolve(pick, request) });
+        else setState({ state: 'unsupported' });
+      },
+      // A retry keeps the choice that failed: a new pick is saved only once it resolves.
+      (error: unknown) => {
+        if (current()) setState({ state: 'error', error, retry: () => resolve(choice, request) });
+      },
+    );
+  }, []);
+
+  useEffect(() => {
+    resolve();
+    // Discards the in-flight result on a store switch or unmount.
+    return () => {
+      requestRef.current += 1;
+    };
+  }, [connector, context, resolve]);
+
+  return state;
+}

package/src/tax/exact.ts

@@ -0,0 +1,155 @@
+/** Micro-minor-units per minor unit. */
+export const MICROS_PER_MINOR = 1_000_000n;
+
+/** Converts a plain decimal percentage with at most four fractional digits to safe integer ppm. */
+export function ratePpmFromPercent(percent: number | string): number {
+  const value = String(percent);
+  const match = /^(\d+)(?:\.(\d{1,4}))?$/.exec(value);
+  if (!match || match[0] !== value) {
+    throw new RangeError('Percent must be a plain decimal with at most four fractional digits');
+  }
+  const ratePpm = BigInt(match[1]) * 10000n + BigInt((match[2] ?? '').padEnd(4, '0'));
+  if (ratePpm > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError('Rate must be a safe integer');
+  }
+  return Number(ratePpm);
+}
+
+/**
+ * Exact exclusive tax, or inclusive tax rounded half away from zero to a micro-minor-unit.
+ * Throws RangeError unless amount and rate are safe integers and rate is non-negative.
+ */
+export function taxMicros(amountMinor: number, ratePpm: number, pricesIncludeTax: boolean): bigint {
+  if (!Number.isSafeInteger(amountMinor) || !Number.isSafeInteger(ratePpm) || ratePpm < 0) {
+    throw new RangeError('Amount must be a safe integer and rate a non-negative safe integer');
+  }
+  const tax = BigInt(amountMinor) * BigInt(ratePpm);
+  if (!pricesIncludeTax) return tax;
+
+  const numerator = tax * MICROS_PER_MINOR;
+  const denominator = MICROS_PER_MINOR + BigInt(ratePpm);
+  const sign = numerator < 0n ? -1n : 1n;
+  return sign * ((sign * numerator + denominator / 2n) / denominator);
+}
+
+/** Rounds micro-minor-units to integer minor units, half away from zero. */
+export function roundMicrosToMinor(micros: bigint): number {
+  const sign = micros < 0n ? -1n : 1n;
+  const minor = sign * ((sign * micros + MICROS_PER_MINOR / 2n) / MICROS_PER_MINOR);
+  if (minor < -BigInt(Number.MAX_SAFE_INTEGER) || minor > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError('Rounded amount must be a safe integer');
+  }
+  return Number(minor);
+}
+
+export interface TaxLineInput {
+  unitPriceMinor: number; // integer, may be negative (returns)
+  quantity: number;       // integer >= 1
+  ratePpm: number;        // integer >= 0
+}
+
+export interface OrderTaxTotals {
+  subtotalMinor: number;  // excl. tax
+  taxMinor: number;       // rounded once
+  totalMinor: number;     // incl. tax
+  lineTaxMicros: bigint[]; // exact, one per input line, same order
+}
+
+/**
+ * Sums tax on each unit price × quantity and rounds once for the order.
+ * Exclusive: total = subtotal + tax. Inclusive: subtotal = total − tax.
+ * Empty orders return zeros and an empty lineTaxMicros.
+ * Throws RangeError for unsafe integer inputs or totals, negative rates, or quantity < 1.
+ */
+export function computeOrderTax(lines: TaxLineInput[], pricesIncludeTax: boolean): OrderTaxTotals {
+  let amountTotal = 0n;
+  let taxTotal = 0n;
+  const lineTaxMicros: bigint[] = [];
+
+  for (const line of lines) {
+    if (!Number.isSafeInteger(line.quantity) || line.quantity < 1) {
+      throw new RangeError('Quantity must be a safe integer >= 1');
+    }
+    let tax = taxMicros(line.unitPriceMinor, line.ratePpm, false) * BigInt(line.quantity);
+    const amount = BigInt(line.unitPriceMinor) * BigInt(line.quantity);
+    if (pricesIncludeTax) {
+      const numerator = tax * MICROS_PER_MINOR;
+      const denominator = MICROS_PER_MINOR + BigInt(line.ratePpm);
+      const sign = numerator < 0n ? -1n : 1n;
+      tax = sign * ((sign * numerator + denominator / 2n) / denominator);
+    }
+    amountTotal += amount;
+    taxTotal += tax;
+    lineTaxMicros.push(tax);
+  }
+
+  const taxMinor = taxTotal / MICROS_PER_MINOR
+    + BigInt(roundMicrosToMinor(taxTotal % MICROS_PER_MINOR));
+  const subtotalMinor = pricesIncludeTax ? amountTotal - taxMinor : amountTotal;
+  const totalMinor = pricesIncludeTax ? amountTotal : amountTotal + taxMinor;
+  for (const value of [subtotalMinor, taxMinor, totalMinor]) {
+    if (value < -BigInt(Number.MAX_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new RangeError('Order totals must be safe integers');
+    }
+  }
+  return {
+    subtotalMinor: Number(subtotalMinor),
+    taxMinor: Number(taxMinor),
+    totalMinor: Number(totalMinor),
+    lineTaxMicros,
+  };
+}
+
+export interface RateTaxLine {
+  label: string;
+  code?: string;
+  ratePpm: number;
+  netMinor: number;
+  amountMinor: number;
+}
+
+/**
+ * Groups each line's stacked tax rates (ADR-040: each independently taxes the line's full
+ * tax-free base) by `code`+`ratePpm`, floors each group's exact tax to minor units, then
+ * distributes `orderTaxMinor` minus that floor sum by largest remainder (ties to the higher rate)
+ * so the rates sum to exactly `orderTaxMinor`. A line's `netMinor` is in its OWN tax mode
+ * (`taxInclusive`): an inclusive line's net already contains its tax, so its tax-free base is
+ * `netMinor − roundMicrosToMinor(Σ its taxMicros)`; an exclusive line's base is `netMinor` as is.
+ * Shared by a receipt's tax summary and a Z report's per-rate breakdown.
+ */
+export function taxLinesByRate(
+  lines: readonly {
+    netMinor: number;
+    taxInclusive: boolean;
+    taxLines: readonly { code?: string; ratePpm: number; taxMicros: string }[];
+  }[],
+  orderTaxMinor: number,
+  taxLabels?: Record<number, string>,
+): RateTaxLine[] {
+  const byRate = new Map<string, { code?: string; ratePpm: number; micros: bigint; netMinor: number }>();
+  for (const line of lines) {
+    const lineTaxMicros = line.taxLines.reduce((sum, tax) => sum + BigInt(tax.taxMicros), 0n);
+    const base = line.taxInclusive ? line.netMinor - roundMicrosToMinor(lineTaxMicros) : line.netMinor;
+    for (const tax of line.taxLines) {
+      const key = JSON.stringify([tax.code ?? '', tax.ratePpm]);
+      const existing = byRate.get(key);
+      byRate.set(key, {
+        code: tax.code, ratePpm: tax.ratePpm,
+        micros: (existing?.micros ?? 0n) + BigInt(tax.taxMicros),
+        netMinor: (existing?.netMinor ?? 0) + base,
+      });
+    }
+  }
+  const groups = Array.from(byRate.values()).map(({ code, ratePpm, micros, netMinor }) => {
+    const floor = micros / MICROS_PER_MINOR - (micros < 0n && micros % MICROS_PER_MINOR !== 0n ? 1n : 0n);
+    return {
+      line: { label: taxLabels?.[ratePpm] ?? `Tax ${ratePpm / 10000}%`, code, ratePpm, netMinor, amountMinor: Number(floor) },
+      remainder: micros - floor * MICROS_PER_MINOR,
+    };
+  });
+  const leftover = orderTaxMinor - groups.reduce((sum, group) => sum + group.line.amountMinor, 0);
+  const ranked = [...groups].sort((a, b) =>
+    a.remainder === b.remainder ? b.line.ratePpm - a.line.ratePpm : a.remainder > b.remainder ? -1 : 1);
+  for (const group of ranked.slice(0, leftover)) group.line.amountMinor += 1;
+  return groups.map((group) => group.line);
+}

package/src/tax/index.ts

@@ -1,4 +1,5 @@
-export { calculateTax, extractTax, addTax } from './calculate';
+export { MICROS_PER_MINOR, ratePpmFromPercent, taxMicros, roundMicrosToMinor, computeOrderTax, taxLinesByRate } from './exact';
+export type { TaxLineInput, OrderTaxTotals, RateTaxLine } from './exact';
 export { TaxProvider, useTax } from './tax-provider';
 export type { TaxProviderProps } from './tax-provider';
-export type { TaxResult, TaxRateMap, TaxContext } from './types';
+export type { TaxRateMap, TaxContext } from './types';