@tallyui/pos 2.0.0 → 3.0.0-next.1

package/src/sale/use-sale.ts

@@ -1,7 +1,9 @@
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
 import type { ProductTraits, ServerCapabilities, StoreSettings } from '@tallyui/core';
-import { createOrderBuilder, type Discount, type Order } from '../order';
+import { createOrderBuilder, type CustomerSummary, type Discount, type Order, type SentOrder } from '../order';
 import { finalizeOrder, type PosOrder } from '../pos-order';
+import { MESSAGE_NAME_MAX, referenceError, referenceReason, withSentForm } from '../pos-order/finalize';
+import { CUSTOMER_REFUSALS, customerRefusal, cutText, PAYLOAD_STRING_MAX } from '../pos-order/command';
 import { useTax } from '../tax';
 import { recordRegisterFact, stampSession, type RegisterSessionCollection } from '../register';
 import { createLogger } from '../logging';
@@ -12,7 +14,7 @@ import { addEntryToCart, CartError } from './cart';
 export const saleLogger = createLogger('sale');
 
 export type SaleStage = { kind: 'cart' } | { kind: 'tender'; method: 'cash' | 'external' }
-  | { kind: 'receipt'; order: Order; posOrder: PosOrder };
+  | { kind: 'receipt'; order: SentOrder; 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()`). */
@@ -49,16 +51,26 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
 }) {
   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 [rendered, setBuilder] = useState(() => createOrderBuilder({ currency: settings.currency, taxContext }));
+  // The live builder, which every mutator reads (#301): newSale() sets it before setBuilder(next) renders, so a
+  // call from an older render never reaches a discarded builder. The state only moves the `order` subscription.
+  const builderNow = useRef(rendered);
+  const [order, setOrder] = useState(() => rendered.getSnapshot());
   const [stage, setStage] = useState<SaleStage>({ kind: 'cart' });
-  const [error, setError] = useState<string | null>(null);
+  const [saleError, setError] = useState<string | null>(null);
+  // App configuration is checked on every render (so on mount and on each change), by finalize's own rule, which
+  // stays the backstop: while it's bad, `error` shows it and complete() refuses, before the first sale's money.
+  const configError = referenceError('cashierRef', opts.cashierRef) ?? referenceError('registerId', opts.registerId);
   // 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);
+  // While a completion is pending (a failed save), its own error comes first: Retry still delivers it.
+  const error = saving && saleError ? saleError : configError ?? saleError;
   // 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 id, at the tender, of the payment whose terminal reference setTender dropped; null when none was dropped.
+  const droppedReference = useRef<string | 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);
@@ -90,15 +102,40 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     if (active) setError(SALE_SAVING);
     return active;
   }
+  // newSale()'s body (see its doc comment for the guards): `newSale()` is `resetSale(null)`.
+  function resetSale(customer: CustomerSummary | null) {
+    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;
+    droppedReference.current = null;
+    setSaving(false);
+    madeWith.current = { taxContext, currency: settings.currency };
+    const next = createOrderBuilder({ currency: settings.currency, taxContext });
+    if (customer !== null) next.setCustomer(customer);
+    builderNow.current = next;
+    setBuilder(next);
+    setOrder(next.getSnapshot());
+    setStage({ kind: 'cart' });
+    setError(null);
+  }
   useEffect(() => {
-    const subscription = builder.order$.subscribe(setOrder);
+    const subscription = rendered.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:
+  }, [rendered]);
+  // New tax settings or currency wait until the sale is idle (an empty cart), then start a new sale keeping its customer:
   // 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 layout effect, on live idleness (#301): it runs inside the settings' commit, before any tap can be handled, and
+  // the rendered `idle` would miss a line added since this render (it would then be dropped with the old builder).
+  useLayoutEffect(() => {
+    const live = builderNow.current.getSnapshot();
+    const liveIdle = stageNow.current.kind === 'cart' && !live.lineItems.length && !inFlight.current && !pending.current;
+    if (liveIdle && (madeWith.current.taxContext !== taxContext || madeWith.current.currency !== settings.currency)) resetSale(live.customer ?? null);
   });
   // A screen that unmounts (medusapos: Sign out) mid-save must still leave a trace of the loss.
   useEffect(() => () => {
@@ -111,10 +148,21 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
 
   function setTender(tender: { method: 'cash' | 'external'; amountMinor: number; reference?: string } | null) {
     if (locked()) return;
+    // A terminal reference finalize would refuse is dropped as it's entered, never the payment (the money is
+    // taken): the tender applies without it, with a message that doesn't block complete() and a
+    // localWarnings entry on the stored order naming the payment whose reference was dropped.
+    const reason = referenceReason(tender?.reference);
+    const dropped = reason && (reason === 'nul' ? 'it contains a NUL character' : `it is over ${PAYLOAD_STRING_MAX} characters`);
+    const kept = tender && dropped ? { method: tender.method, amountMinor: tender.amountMinor } : tender;
+    const builder = builderNow.current;
     const previous = builder.getSnapshot().payments[0];
     if (previous) builder.removePayment(previous.id);
-    if (tender) builder.addPayment(tender);
-    setError(null);
+    const paymentId = kept ? builder.addPayment(kept) : null;
+    droppedReference.current = dropped ? paymentId : null;
+    setError(dropped && `The terminal's payment reference couldn't be kept (${dropped}); the payment is recorded without it.`);
+    try {
+      if (dropped) saleLogger.warn("the terminal's payment reference was dropped", { reason: dropped, method: tender!.method });
+    } catch { /* a failing sink must never lose the tender */ }
   }
 
   /** Asks `isStored`; Continue is offered only once it confirms, for this attempt, with the completion still pending. */
@@ -161,10 +209,11 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     if (hungSaveTimer.current === timer) clearHungSaveTimer();
     if (pending.current !== completion) return;
     pending.current = null;
+    droppedReference.current = null;
     confirm(null);
     setSaving(false);
     setError(null);
-    stageNow.current = { kind: 'receipt', order: completion.order, posOrder: completion.posOrder };
+    stageNow.current = { kind: 'receipt', order: withSentForm(completion.order, completion.posOrder), posOrder: completion.posOrder };
     setStage(stageNow.current);
   }
 
@@ -189,20 +238,32 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
     canContinue,
     add(entry: CatalogueEntry<any>, traits: ProductTraits<any>) {
       if (locked()) return;
+      const builder = builderNow.current;
       try {
-        addEntryToCart(builder, entry, traits, madeWith.current.currency);
+        const known = new Set(builder.getSnapshot().lineItems.map((line) => line.id));
+        const lineId = addEntryToCart(builder, entry, traits, madeWith.current.currency);
+        // A new line whose id or v3 tax code finalize would refuse is taken off at once, in finalize's
+        // message shape; finalize stays the backstop.
+        const line = builder.getSnapshot().lineItems.find((item) => item.id === lineId && !known.has(item.id));
+        const name = line && `"${cutText(line.name, MESSAGE_NAME_MAX)}"`;
+        const taxLines = line && (opts.capabilities?.orderCreate ?? 1) >= 3 ? line.taxLines : [];
+        const refused = line && [line.variantId !== undefined ? referenceError(`${name}: the variant id`, line.variantId)
+          : referenceError(`${name}: the product id`, line.productId),
+        ...taxLines.map((tax) => referenceError(`${name}: the tax code`, tax.code))].find((message) => message !== null);
+        if (refused) { builder.removeItem(lineId); return setError(refused); }
         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); },
+    setQuantity(lineId: string, quantity: number) { if (!locked()) builderNow.current.updateQuantity(lineId, quantity); },
+    remove(lineId: string) { if (!locked()) builderNow.current.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 builder = builderNow.current;
       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));
@@ -216,7 +277,16 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
       }
       return null;
     },
-    removeDiscount(id: string) { if (!locked()) builder.removeDiscount(id); },
+    removeDiscount(id: string) { if (!locked()) builderNow.current.removeDiscount(id); },
+    /** the picked customer reaches the server as order.create v3's customer.customerId */
+    setCustomer(customer: CustomerSummary | null) {
+      if (locked()) return;
+      // A searched customer's email or id the server would refuse never reaches the sale; the customer stays as it was.
+      const refused = customer && customerRefusal(customer);
+      if (refused) return setError(refused);
+      builderNow.current.setCustomer(customer);
+      setError((current) => current !== null && CUSTOMER_REFUSALS.includes(current) ? null : current); // any other error stays
+    },
     /**
      * 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
@@ -224,7 +294,7 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
      */
     startTender(method: 'cash' | 'external', options?: { session?: { id: string; sessions: RegisterSessionCollection } }) {
       if (locked()) return;
-      const current = builder.getSnapshot();
+      const current = builderNow.current.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);
@@ -248,17 +318,20 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
      * 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.
+     * another is in flight returns that call's promise, and a call on the receipt does nothing. While
+     * `cashierRef` or `registerId` is out of bounds (shown as `error`), a call does nothing either,
+     * unless it's the Retry of a pending completion, which was built with the options as they were.
      */
-    complete: () => once(async () => {
+    complete: () => configError && !pending.current && !inFlight.current ? Promise.resolve() : once(async () => {
       attempts.current++;
       confirm(null);
       if (pending.current) return deliver(pending.current);
       setSaving(true);
-      const current = builder.getSnapshot();
+      const current = builderNow.current.getSnapshot();
       let posOrder: PosOrder;
       try {
-        posOrder = finalizeOrder(current, { registerId: opts.registerId, cashierRef: opts.cashierRef, capabilities: opts.capabilities });
+        posOrder = finalizeOrder(current, { registerId: opts.registerId, cashierRef: opts.cashierRef, capabilities: opts.capabilities,
+          ...(droppedReference.current ? { localWarnings: [{ code: 'payment_reference_dropped', paymentId: droppedReference.current }] } : {}) });
       } catch (error) {
         setSaving(false);
         setError((error as Error).message);
@@ -307,23 +380,7 @@ export function useSale(settings: Pick<StoreSettings, 'currency'>, opts: {
      * 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);
-    },
+    newSale() { resetSale(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

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

@@ -7,7 +7,12 @@ export function withPricingContext(context: SyncContext, settings: StoreSettings
   return settings.pricingContext ? { ...rest, pricingContext: settings.pricingContext } : rest;
 }
 
-/** `<TaxProvider>`'s props from the same settings, so its tax inclusivity matches the connector's. */
+/**
+ * `<TaxProvider>`'s props from the same settings, so its tax inclusivity, rounding and rate codes match the store's. `custom`
+ * rounding passes none, the default (#287). An explicit `rounding` prop after the spread still wins, since JSX
+ * applies props in order; so `<TaxProvider {...taxProviderProps(s)} rounding={undefined}>` wipes the store's rounding.
+ */
 export function taxProviderProps(settings: StoreSettings): Omit<TaxProviderProps, 'children'> {
-  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax };
+  const rounding = settings.taxRounding?.granularity === 'custom' ? undefined : settings.taxRounding;
+  return { ratesPpm: settings.taxRatesPpm, pricesIncludeTax: settings.pricesIncludeTax, ...(rounding && { rounding }), ...(settings.taxRateCodes && { rateCodes: settings.taxRateCodes }) };
 }

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

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-import type { StoreSettings, StoreSettingsChoice, StoreSettingsChoices } from '@tallyui/core';
+import type { StoreSettings, StoreSettingsChoice, StoreSettingsChoices, TaxRounding } from '@tallyui/core';
 import { resolveStoreSettings } from './resolve-store-settings';
 import type { ResolveStoreSettingsOptions } from './resolve-store-settings';
 
@@ -7,16 +7,45 @@ 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: 'error'; error: unknown; retry: () => void; nextRetryAt?: number }
   | { state: 'unsupported' };
 
 // One object, so re-entering loading while already loading doesn't re-render.
 const LOADING: StoreSettingsState = { state: 'loading' };
 
+export class StoreCapabilitiesUnavailableError extends Error {
+  constructor(cause?: unknown) {
+    super('Store capabilities unavailable', { cause });
+    this.name = 'StoreCapabilitiesUnavailableError';
+  }
+}
+
+// Exponential retry for unknown rounding: 5 seconds, doubling up to 5 minutes.
+const INITIAL_RETRY_MS = 5_000;
+const MAX_RETRY_MS = 5 * 60_000;
+
+// The store's taxRounding (#324): the context's capabilities, else one read of the connector's.
+function readTaxRounding({ connector, context }: ResolveStoreSettingsOptions): Promise<TaxRounding | undefined> {
+  if (context.capabilities) return Promise.resolve(context.capabilities.taxRounding);
+  if (!connector.storeSettings || !connector.capabilities) return Promise.resolve(undefined);
+  const read = connector.capabilities;
+  return Promise.resolve().then(() => read(context)).then(
+    (capabilities) => {
+      if (!capabilities) throw new StoreCapabilitiesUnavailableError();
+      return capabilities.taxRounding;
+    },
+    (cause) => { throw new StoreCapabilitiesUnavailableError(cause); },
+  );
+}
+
 /**
  * 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.
+ * The ready settings carry the store's `taxRounding` from the capabilities, so `taxProviderProps` passes it on (#324).
+ * The capabilities are read beside the settings, before `ready`, so each resolve emits the settings once, with the
+ * rounding already known: no later change of `settings` holds a sale.
+ * Unknown rounding keeps settings unresolved and retries by itself; show "Can't reach the store's settings yet. Retrying…" while `nextRetryAt` is set.
  *
  * ```tsx
  * const store = useStoreSettings({ connector, context, loadChoice, saveChoice });
@@ -32,27 +61,42 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
   const optionsRef = useRef(options);
   optionsRef.current = options;
   const requestRef = useRef(0);
+  const retryTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const retryDelayRef = useRef(INITIAL_RETRY_MS);
   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) => {
+  // pick to the new store. `known`, when given, is the rounding that request already read, so
+  // a pick doesn't read it again.
+  const resolve = useCallback((choice?: StoreSettingsChoice, from?: number, known?: Promise<TaxRounding | undefined>) => {
     if (from !== undefined && from !== requestRef.current) return;
+    clearTimeout(retryTimerRef.current);
     const request = ++requestRef.current;
     const current = () => request === requestRef.current;
     setState(LOADING);
-    resolveStoreSettings(optionsRef.current, choice).then(
-      (result) => {
+    const rounding = known ?? readTaxRounding(optionsRef.current);
+    Promise.all([resolveStoreSettings(optionsRef.current, choice), rounding]).then(
+      ([result, taxRounding]) => {
         if (!current()) return;
-        if (result.status === 'ready') setState({ state: 'ready', settings: result.settings, choice: result.choice });
+        retryDelayRef.current = INITIAL_RETRY_MS;
+        if (result.status === 'ready')
+          setState({ state: 'ready', settings: taxRounding ? { ...result.settings, taxRounding } : result.settings, choice: result.choice });
         else if (result.status === 'choose')
-          setState({ state: 'choose', choices: result.choices, initial: result.initial, choose: (pick) => resolve(pick, request) });
+          setState({ state: 'choose', choices: result.choices, initial: result.initial, choose: (pick) => resolve(pick, request, rounding) });
         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) });
+        if (!current()) return;
+        const retry = () => resolve(choice, request);
+        if (error instanceof StoreCapabilitiesUnavailableError) {
+          const delay = retryDelayRef.current;
+          const nextRetryAt = Date.now() + delay;
+          retryDelayRef.current = Math.min(delay * 2, MAX_RETRY_MS);
+          retryTimerRef.current = setTimeout(retry, delay);
+          setState({ state: 'error', error, retry, nextRetryAt });
+        } else setState({ state: 'error', error, retry });
       },
     );
   }, []);
@@ -61,6 +105,8 @@ export function useStoreSettings(options: ResolveStoreSettingsOptions): StoreSet
     resolve();
     // Discards the in-flight result on a store switch or unmount.
     return () => {
+      clearTimeout(retryTimerRef.current);
+      retryDelayRef.current = INITIAL_RETRY_MS;
       requestRef.current += 1;
     };
   }, [connector, context, resolve]);

package/src/tax/exact.ts

@@ -1,6 +1,11 @@
+import type { TaxRounding } from '@tallyui/core';
+
 /** Micro-minor-units per minor unit. */
 export const MICROS_PER_MINOR = 1_000_000n;
 
+/** What an absent `TaxRounding` means (#287): the till's only rounding before #287a. */
+export const DEFAULT_TAX_ROUNDING = { granularity: 'per_order', mode: 'half_away_from_zero' } as const satisfies TaxRounding;
+
 /** 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);
@@ -32,10 +37,19 @@ export function taxMicros(amountMinor: number, ratePpm: number, pricesIncludeTax
   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);
+/** #287: `half_up` is Math.round's rule, Vendure's DefaultMoneyStrategy (default-money-strategy.js:19-21). */
+export type RoundingMode = 'half_away_from_zero' | 'half_up';
+
+/** `n / d` (d > 0) rounded to an integer in `mode`, exactly; the modes differ only on exact negative halves. */
+export function roundRatio(n: bigint, d: bigint, mode: RoundingMode = 'half_away_from_zero'): bigint {
+  if (mode === 'half_away_from_zero' && n < 0n) return -roundRatio(-n, d, mode);
+  const a = 2n * n + d, b = 2n * d; // floor(n / d + 1/2)
+  return a / b - (a < 0n && a % b !== 0n ? 1n : 0n);
+}
+
+/** Rounds micro-minor-units to integer minor units, half away from zero unless `mode` says otherwise. */
+export function roundMicrosToMinor(micros: bigint, mode?: RoundingMode): number {
+  const minor = roundRatio(micros, MICROS_PER_MINOR, mode);
   if (minor < -BigInt(Number.MAX_SAFE_INTEGER) || minor > BigInt(Number.MAX_SAFE_INTEGER)) {
     throw new RangeError('Rounded amount must be a safe integer');
   }
@@ -108,6 +122,54 @@ export interface RateTaxLine {
   amountMinor: number;
 }
 
+type TaxedLine = { netMinor: number; discountMinor?: number; taxInclusive: boolean; taxLines: readonly { code?: string; ratePpm: number; taxMicros: string }[] };
+
+/**
+ * A `per_line_items` or `per_rate_group_items` store's figures (#287) as @vendure/core 3.7.3 computes them; undefined
+ * otherwise. `baseMinor` (the subtotal) is Σ each item's rounded net, `rates` the tax by `code`+`ratePpm`, summing to
+ * `taxMinor`; the total is their sum. Vendure's rounding is `half_up`. vendurepos scores the #38 set with this.
+ */
+export function roundedTaxByRate(lines: readonly TaxedLine[], rounding?: TaxRounding) {
+  if (rounding?.granularity !== 'per_line_items' && rounding?.granularity !== 'per_rate_group_items') return undefined;
+  // Known gap (#287): Vendure's inclusive per_rate_group_items total can differ from the shelf prices, which the display
+  // can't show until it has a rounding row (#310), so an order with any inclusive line keeps per_order's figures and rows.
+  if (rounding.granularity === 'per_rate_group_items' && lines.some((line) => line.taxInclusive)) return undefined;
+  const { granularity, mode } = rounding;
+  const rates = new Map<string, { code?: string; ratePpm: number; netMinor: bigint; amountMinor: bigint }>();
+  let baseMinor = 0n;
+  // vendurepos posts each line undiscounted (A) and its discountMinor as its own −D surcharge in the line's mode with
+  // the line's tax lines (vendurepos/app order-create.service.ts:654-663); a return line's negative D is its cap, not an item.
+  const items = lines.flatMap((line) => (line.discountMinor ?? 0) > 0
+    ? [{ ...line, netMinor: line.netMinor + line.discountMinor! }, { ...line, netMinor: -line.discountMinor! }] : [line]);
+  for (const line of items) {
+    const net = BigInt(line.netMinor);
+    const ratePpm = BigInt(line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0));
+    // Each item's net is rounded first, at the sum of its rates (order-line.entity.js:121-122): an inclusive item's
+    // netPriceOf(gross) (:193-196, :249-251; surcharge.entity.js:33-38; tax-utils.js:16-17), an exclusive one's as it is.
+    const base = line.taxInclusive ? roundRatio(net * MICROS_PER_MINOR, MICROS_PER_MINOR + ratePpm, mode) : net;
+    // per_line_items: the item's tax is its rounded gross less that net (:201-204, :259-261; surcharge.entity.js:36-38;
+    // default-order-tax-calculation-strategy.js:22-29): round(net × r) exclusive, gross − net inclusive.
+    const lineTax = line.taxInclusive ? net - base : roundRatio(net * ratePpm, MICROS_PER_MINOR, mode);
+    let left = lineTax;
+    baseMinor += base;
+    line.taxLines.forEach((tax, index) => {
+      // Vendure's key is the rate's name and value (order-level-tax-calculation-strategy.js:103).
+      const key = JSON.stringify([tax.code ?? '', tax.ratePpm]);
+      const row = rates.get(key) ?? { code: tax.code, ratePpm: tax.ratePpm, netMinor: 0n, amountMinor: 0n };
+      // per_line_items, stacked rates: each rate's share of the item's tax, rounded (default-order-tax-calculation-strategy.js:51-66),
+      // the last rate taking the rest so the rows sum to the tax. per_rate_group_items: each rate takes the whole net, and
+      // a −D item joins its line's group (order-level-tax-calculation-strategy.js:88-91, :98-115).
+      const share = index === line.taxLines.length - 1 ? left : ratePpm === 0n ? 0n : roundRatio(lineTax * BigInt(tax.ratePpm), ratePpm, mode);
+      left -= share;
+      rates.set(key, { ...row, netMinor: row.netMinor + base, amountMinor: row.amountMinor + share });
+    });
+  }
+  const rows = [...rates.values()].map((row) => ({ ...row, netMinor: Number(row.netMinor), amountMinor: Number(
+    // per_rate_group_items: round(Σ net × r) once per group, and the order's tax is their sum (:35-49, :56).
+    granularity === 'per_rate_group_items' ? roundRatio(row.netMinor * BigInt(row.ratePpm), MICROS_PER_MINOR, mode) : row.amountMinor) }));
+  return { baseMinor: Number(baseMinor), taxMinor: rows.reduce((sum, row) => sum + row.amountMinor, 0), rates: rows };
+}
+
 /**
  * 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
@@ -115,17 +177,18 @@ export interface RateTaxLine {
  * 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.
+ * Shared by a receipt's tax summary and a Z report's per-rate breakdown. That is `per_order`'s split; a `per_line_items` or
+ * `per_rate_group_items` order's rows are `roundedTaxByRate`'s (#287).
  */
 export function taxLinesByRate(
-  lines: readonly {
-    netMinor: number;
-    taxInclusive: boolean;
-    taxLines: readonly { code?: string; ratePpm: number; taxMicros: string }[];
-  }[],
+  lines: readonly TaxedLine[],
   orderTaxMinor: number,
   taxLabels?: Record<number, string>,
+  rounding?: TaxRounding,
 ): RateTaxLine[] {
+  const label = (ratePpm: number) => taxLabels?.[ratePpm] ?? `Tax ${ratePpm / 10000}%`;
+  const rounded = roundedTaxByRate(lines, rounding);
+  if (rounded) return rounded.rates.map(({ code, ratePpm, netMinor, amountMinor }) => ({ label: label(ratePpm), code, ratePpm, netMinor, amountMinor }));
   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);
@@ -143,7 +206,7 @@ export function taxLinesByRate(
   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) },
+      line: { label: label(ratePpm), code, ratePpm, netMinor, amountMinor: Number(floor) },
       remainder: micros - floor * MICROS_PER_MINOR,
     };
   });

package/src/tax/index.ts

@@ -1,5 +1,5 @@
 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 { TaxProvider, useTax, taxLogger } from './tax-provider';
 export type { TaxProviderProps } from './tax-provider';
 export type { TaxRateMap, TaxContext } from './types';

package/src/tax/tax-provider.tsx

@@ -1,28 +1,50 @@
 import { createContext, useContext, useMemo } from 'react';
 import type { ReactNode } from 'react';
+import type { TaxRounding } from '@tallyui/core';
 import type { TaxContext } from './types';
+import { createLogger } from '../logging';
+
+export const taxLogger = createLogger('tax');
 
 const TaxCtx = createContext<TaxContext | null>(null);
 
 export interface TaxProviderProps {
   ratesPpm: Record<string, number>;
   pricesIncludeTax: boolean;
+  /** `ServerCapabilities.taxRounding` (#287); a change restarts an idle sale under it. */
+  rounding?: TaxRounding;
+  /** Tax class → the backend's rate name, for `per_rate_group_items`'s grouping (#287). */
+  rateCodes?: Record<string, string>;
   children: ReactNode;
 }
 
-export function TaxProvider({ ratesPpm, pricesIncludeTax, children }: TaxProviderProps) {
+export function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, children }: TaxProviderProps) {
   const value = useMemo<TaxContext>(
     () => {
       if (Object.values(ratesPpm).some((rate) => !Number.isSafeInteger(rate) || rate < 0)) {
         throw new RangeError('TaxProvider: rates must be integer ppm');
       }
+      const unknown = new Set<string>();
       return {
-        getTaxRatePpm: (taxClass) =>
-          (taxClass === undefined ? undefined : ratesPpm[taxClass]) ?? ratesPpm.default ?? 0,
+        getTaxRatePpm: (taxClass) => {
+          if (taxClass !== undefined && Object.hasOwn(ratesPpm, taxClass)) return ratesPpm[taxClass];
+          // A class the store's rates don't key is taxed at the default rate; warn once per class and rate map.
+          if (taxClass !== undefined && !unknown.has(taxClass)) {
+            unknown.add(taxClass);
+            taxLogger.warn('No tax rate for this tax class; using the default rate', { taxClass });
+          }
+          return ratesPpm.default ?? 0;
+        },
+        // The name of the rate getTaxRatePpm picks: the class's own, else the default's.
+        getTaxRateCode: (taxClass) => {
+          const key = taxClass !== undefined && Object.hasOwn(ratesPpm, taxClass) ? taxClass : 'default';
+          return rateCodes && Object.hasOwn(rateCodes, key) ? rateCodes[key] : undefined;
+        },
         pricesIncludeTax,
+        ...(rounding ? { rounding } : {}),
       };
     },
-    [ratesPpm, pricesIncludeTax],
+    [ratesPpm, pricesIncludeTax, rounding, rateCodes],
   );
 
   return <TaxCtx.Provider value={value}>{children}</TaxCtx.Provider>;

package/src/tax/types.ts

@@ -1,3 +1,5 @@
+import type { TaxRounding } from '@tallyui/core';
+
 /** Tax rates as integer parts per million (19% = 190000). */
 export type TaxRateMap = {
   default: number;
@@ -7,5 +9,9 @@ export type TaxRateMap = {
 export interface TaxContext {
   /** Tax rate for a tax class as integer parts per million (19% = 190000); the default class when omitted or unknown. */
   getTaxRatePpm(taxClass?: string): number;
+  /** The backend's name for that class's rate, when mapped: a `per_rate_group_items` store groups by name and value (#287). */
+  getTaxRateCode?(taxClass?: string): string | undefined;
   pricesIncludeTax: boolean;
+  /** The store's tax rounding strategy (#287); absent means `per_order`, half away from zero. */
+  rounding?: TaxRounding;
 }