@tallyui/pos 0.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/pos",
-  "version": "0.1.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Shared POS business logic for Tally UI — tax, orders, payments, discounts, receipts",
   "main": "./dist/index.js",
@@ -15,25 +15,36 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-helper.ts"
   ],
   "license": "MIT",
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TallyUI/tallyui.git",
+    "directory": "packages/pos"
   },
   "peerDependencies": {
-    "@tallyui/core": "workspace:*",
+    "@tallyui/core": "2.0.0",
     "react": ">=18",
     "rxdb": ">=16",
     "rxjs": ">=7"
   },
   "devDependencies": {
-    "@tallyui/core": "workspace:*",
+    "@tallyui/core": "2.0.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "rxdb": "16.21.1",
-    "rxjs": "7.8.2"
+    "rxjs": "7.8.2",
+    "@tallyui/connector-medusa": "2.0.0",
+    "@tallyui/connector-woocommerce": "2.0.0",
+    "@tallyui/database": "2.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}

package/src/currency/currency-provider.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, useMemo, useCallback } from 'react';
 import type { ReactNode } from 'react';
-import { formatCurrency } from './format-currency';
+import { formatMoney, type Money } from '@tallyui/core';
 
 interface CurrencyContext {
   currencyCode: string;
@@ -20,13 +20,21 @@ export function CurrencyProvider({ currencyCode, locale, children }: CurrencyPro
   return <CurrencyCtx.Provider value={value}>{children}</CurrencyCtx.Provider>;
 }
 
-export function useCurrencyFormatter(): (amount: number) => string {
+export function useCurrencyFormatter(): (money: Money) => string {
   const ctx = useContext(CurrencyCtx);
   if (!ctx) {
     throw new Error('useCurrencyFormatter() must be used within a <CurrencyProvider>');
   }
   return useCallback(
-    (amount: number) => formatCurrency(amount, ctx.currencyCode, ctx.locale),
-    [ctx.currencyCode, ctx.locale],
+    (money: Money) => formatMoney(money, ctx.locale) ?? `${money.amount} ${money.currency}`,
+    [ctx.locale],
   );
 }
+
+export function useCurrencyCode(): string {
+  const ctx = useContext(CurrencyCtx);
+  if (!ctx) {
+    throw new Error('useCurrencyCode() must be used within a <CurrencyProvider>');
+  }
+  return ctx.currencyCode;
+}

package/src/currency/index.ts

@@ -1,3 +1,2 @@
-export { formatCurrency } from './format-currency';
-export { CurrencyProvider, useCurrencyFormatter } from './currency-provider';
+export { CurrencyProvider, useCurrencyFormatter, useCurrencyCode } from './currency-provider';
 export type { CurrencyProviderProps } from './currency-provider';

package/src/index.ts

@@ -3,27 +3,40 @@ export { createLogger, consoleSink, callbackSink } from './logging';
 export type { Logger, LogSink, LogEntry, LogLevel } from './logging';
 
 // Currency
-export { formatCurrency, CurrencyProvider, useCurrencyFormatter } from './currency';
+export { CurrencyProvider, useCurrencyFormatter, useCurrencyCode } from './currency';
 export type { CurrencyProviderProps } from './currency';
 
 // Tax
-export { calculateTax, extractTax, addTax, TaxProvider, useTax } from './tax';
+export { TaxProvider, useTax } from './tax';
+export { MICROS_PER_MINOR, ratePpmFromPercent, taxMicros, roundMicrosToMinor, computeOrderTax, taxLinesByRate } from './tax';
+export type { TaxLineInput, OrderTaxTotals, RateTaxLine } from './tax';
 export type { TaxProviderProps } from './tax';
-export type { TaxResult, TaxRateMap, TaxContext } from './tax';
+export type { TaxRateMap, TaxContext } from './tax';
+
+// Store settings
+export { resolveStoreSettings, useStoreSettings, withPricingContext, taxProviderProps } from './store-settings';
+export type { StoreSettingsResolution, ResolveStoreSettingsOptions, StoreSettingsState } from './store-settings';
+
+// RxDB reads past the query cache, and live lists that can't leave it stale (RxDB 16.21.1 bug 4)
+export { readFresh, countFresh, watchFresh } from './rxdb';
 
 // Repository
 export { createRepository } from './repository';
 export type { Repository } from './repository';
 
 // Order
-export { createOrderBuilder, createOrderManager } from './order';
+export { createOrderBuilder, createOrderManager, allocateOrderDiscount } from './order';
 export type { OrderBuilder, OrderBuilderOptions } from './order';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order';
 export type {
   Order,
   LineItem,
+  LineTaxLine,
+  AddLineInput,
   Discount,
   AppliedDiscount,
+  DisplayTotals,
+  DisplayLine,
   Payment,
   CustomerSummary,
   PaymentMethod,
@@ -32,3 +45,31 @@ export type {
 // Receipt
 export { buildReceiptData } from './receipt';
 export type { ReceiptData, ReceiptLineItem, ReceiptConfig } from './receipt';
+
+// Product
+export { searchProducts, withStockOverlay, getProductStock, stockOverlay$, stockOverlayAsOf$ } from './product';
+
+// Sale
+export { useSale, DISCOUNTS_UNSUPPORTED, SALE_SAVING, saleLogger, addEntryToCart, CartError, catalogueEntries, findEntryByCode, variantPriceLabel } from './sale';
+export type { SaleStage, CatalogueEntry } from './sale';
+
+export { uuidv7, finalizeOrder, toOrderCreateEnvelope, posOrderSchema, posOrderCollection, addPosOrderCollection, PosOrderOpenClosedError, posOrdersLogger, getDeviceId, needsAttention, sameSale, OrderContentMismatchError } from './pos-order';
+export type { PosOrderSyncStatus, PosOrderLine, PosOrderPayment, PosOrder, FinalizeOptions } from './pos-order';
+export { createHttpCommandTransport, createOrderOutbox, useOrderOutbox, outboxLogger } from './outbox';
+export type { HttpTransportOptions, OrderOutboxOptions, OrderOutbox, TransportOutcome, CommandTransport, OutboxState, UseOrderOutboxOptions, UseOrderOutboxResult } from './outbox';
+export { tenderReducer, initTenderState, initialTenderState, appliedMinor, changeMinor, quickTenderedAmounts, evenSplitShareMinor, activePlan, planLegs, MAX_TENDER_MINOR } from './tender';
+export type { PaymentTransport, TenderView, TenderLineId, TenderPlan, SplitTab, TenderState, TenderKey, TenderAction, PlanLeg } from './tender';
+
+// Register
+export { normalizeAmount, isServerDecimal, movementFieldError, deriveExpected, parseMinor, validAmount, countVariance, overThreshold, closeNeedsApproval, denominationTotal, varianceText, denominations } from './register';
+export type { MovementType, LedgerRow, Movement } from './register';
+export { registerSessionSchema, registerSessionCollection, cashMovementSchema, closureSchema } from './register';
+export type { RegisterSession, CashMovement, Closure } from './register';
+export { mintUuid, readRegister, ensureRegister, observeRegister$, getBoundRegisterId, readBoundRegister, bindRegister, unbindRegister, nextSaleCounter, mintClosureNumber, advancePerpetual } from './register';
+export type { RegisterHost, RegisterCounters, RegisterBucket, RegisterStore, RegisterDocument } from './register';
+export { RegisterSessionRequiredError, RegisterSessionClosedError, RegisterMovementStrandedError, openSessionSelector, requireOpenSession, stampSession, openSession, startCounting, backToSelling, closeSession, recordMovement, voidMovement, writeClosure } from './register';
+export type { RegisterSessionCollection, CashMovementCollection, ClosureCollection } from './register';
+export { deriveSettled, exportCsv, labelKeys, clampClosureScope, selectClosureRows } from './register';
+export type { Correction, RecordedFigures, ClosureScope } from './register';
+export { minorToDecimal, formatClosureDate, buildClosureDocument, buildXReportDocument, registerFactsLogger, recordRegisterFact, type ClosureContext, type Actor, type RegisterFact } from './register';
+export { useRegisterSession, RegisterTenderInProgressError, RegisterSessionAlreadyOpenError, RegisterCloseIncompleteError, RegisterApprovalRequiredError, type UseRegisterSessionOptions } from './register';

package/src/order/allocate-order-discount.ts

@@ -0,0 +1,34 @@
+/**
+ * Splits an order discount across lines in proportion to each line's pre-order-discount amount,
+ * in its own tax mode (ADR-062), with largest-remainder rounding to the minor unit.
+ *
+ * - The shares sum exactly to `totalMinor`, and no share exceeds its line's amount.
+ * - Leftover units go to the largest remainders; ties go to the earlier line, so the result is deterministic.
+ * - A line with a zero or negative amount gets 0.
+ *
+ * Throws RangeError unless every input is a safe integer and 0 ≤ totalMinor ≤ Σ positive amounts.
+ */
+export function allocateOrderDiscount(lineAmountsMinor: readonly number[], totalMinor: number): number[] {
+  if (!Number.isSafeInteger(totalMinor) || totalMinor < 0 || !lineAmountsMinor.every(Number.isSafeInteger)) {
+    throw new RangeError('Amounts must be safe integers and the discount non-negative');
+  }
+  const weights = lineAmountsMinor.map((amount) => BigInt(Math.max(0, amount)));
+  const weightTotal = weights.reduce((sum, weight) => sum + weight, 0n);
+  const total = BigInt(totalMinor);
+  if (total > weightTotal) throw new RangeError('Order discount exceeds the lines it applies to');
+  if (total === 0n) return weights.map(() => 0);
+
+  // BigInt keeps total × weight exact however large the order is.
+  const shares = weights.map((weight) => (total * weight) / weightTotal);
+  const remainders = weights.map((weight) => (total * weight) % weightTotal);
+  let leftover = total - shares.reduce((sum, share) => sum + share, 0n);
+  const ranked = remainders.map((_, index) => index)
+    .sort((a, b) => remainders[a] === remainders[b] ? a - b : remainders[a] > remainders[b] ? -1 : 1);
+  // Each leftover unit goes to a line with a non-zero remainder, whose share is still below its amount.
+  for (const index of ranked) {
+    if (leftover === 0n) break;
+    shares[index] += 1n;
+    leftover -= 1n;
+  }
+  return shares.map(Number);
+}

package/src/order/index.ts

@@ -1,12 +1,17 @@
 export { createOrderBuilder } from './order-builder';
+export { allocateOrderDiscount } from './allocate-order-discount';
 export type { OrderBuilder, OrderBuilderOptions } from './order-builder';
 export { createOrderManager } from './order-manager';
 export type { OrderManager, OrderManagerOptions, ParkedOrderSummary } from './order-manager';
 export type {
   Order,
   LineItem,
+  LineTaxLine,
+  AddLineInput,
   Discount,
   AppliedDiscount,
+  DisplayTotals,
+  DisplayLine,
   Payment,
   CustomerSummary,
   PaymentMethod,

package/src/order/order-builder.ts

@@ -1,7 +1,8 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
-import type { ProductTraits } from '@tallyui/core';
+import { resolvePrice, type ProductTraits } from '@tallyui/core';
 import type { TaxContext } from '../tax/types';
-import { calculateTax } from '../tax/calculate';
+import { taxMicros, roundMicrosToMinor } from '../tax/exact';
+import { allocateOrderDiscount } from './allocate-order-discount';
 import type {
   Order,
   LineItem,
@@ -9,6 +10,7 @@ import type {
   AppliedDiscount,
   Payment,
   CustomerSummary,
+  AddLineInput,
 } from './types';
 
 let nextId = 0;
@@ -16,6 +18,40 @@ function uid(): string {
   return `${Date.now()}-${++nextId}`;
 }
 
+function roundHalfAway(n: number): number {
+  return Math.sign(n) * Math.round(Math.abs(n));
+}
+
+/** The settlement totals of recalculated lines; the display figures derive from them (ADR-063). */
+function sumLines(lines: LineItem[]): { subtotalMinor: number; taxMinor: number; totalMinor: number } {
+  const netMinor = lines.reduce((sum, li) => sum + li.netMinor, 0);
+  const lineTaxMicros = lines.reduce((sum, li) => sum + BigInt(li.taxMicros), 0n);
+  const exclusiveTaxMicros = lines.reduce((sum, li) => li.taxInclusive ? sum : sum + BigInt(li.taxMicros), 0n);
+  const taxMinor = roundMicrosToMinor(lineTaxMicros);
+  // Each line pays in its own mode: an inclusive line its gross, an exclusive line its net plus tax.
+  // The totals sum the lines as recalculated; nothing is subtracted after tax.
+  const linesTotal = netMinor + roundMicrosToMinor(exclusiveTaxMicros);
+  return { subtotalMinor: linesTotal - taxMinor, taxMinor, totalMinor: Math.max(0, linesTotal) };
+}
+
+/** An own-mode amount on a line, in the display mode, converted on its own at the line's rates (ADR-063). */
+function toDisplayMode(line: LineItem, amountMinor: number, displayInclusive: boolean): number {
+  if (line.taxInclusive === displayInclusive) return amountMinor;
+  const ratePpm = line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0);
+  const taxMinor = roundMicrosToMinor(taxMicros(amountMinor, ratePpm, line.taxInclusive));
+  return line.taxInclusive ? amountMinor - taxMinor : amountMinor + taxMinor;
+}
+
+/**
+ * The display residue's guard (ADR-063); throws when the arithmetic is wrong rather than rounded. With no converted
+ * line it's exactly 0 (Σ gross = Σ net + Σ discounts). Otherwise each of the n non-zero rounded conversions is off by
+ * at most half a cent, and the order-level tax rounding by at most one more, so |residue| ≤ ⌊n/2⌋ + 1.
+ */
+export function assertDisplayResidue(residue: number, convertedLines: number, conversions: number): void {
+  const bound = convertedLines === 0 ? 0 : Math.floor(conversions / 2) + 1;
+  if (Math.abs(residue) > bound) throw new Error(`Display residue ${residue} exceeds its bound of ${bound} (ADR-063)`);
+}
+
 export interface OrderBuilderOptions {
   currency: string;
   taxContext: TaxContext;
@@ -25,6 +61,7 @@ export interface OrderBuilderOptions {
 export interface OrderBuilder {
   order$: Observable<Order>;
   addProduct(doc: any, traits: ProductTraits, options?: { variantId?: string; quantity?: number }): string;
+  addLine(input: AddLineInput): string;
   updateQuantity(lineId: string, quantity: number): void;
   removeItem(lineId: string): void;
   applyLineDiscount(lineId: string, discount: Discount): void;
@@ -39,7 +76,8 @@ export interface OrderBuilder {
 }
 
 export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
-  const { currency, taxContext } = options;
+  const { taxContext } = options;
+  const currency = options.currency.toUpperCase();
   const orderId = options.id ?? uid();
 
   let lineItems: LineItem[] = [];
@@ -51,81 +89,156 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
 
   const subject = new BehaviorSubject<Order>(buildOrder());
 
-  function recalculateLine(line: LineItem): LineItem {
-    const gross = line.price * line.quantity;
-
-    // Recompute discount amounts from current gross
-    const recalcedDiscounts = line.discounts.map((d) => ({
-      ...d,
-      amount: computeDiscountAmount(d, gross),
-    }));
-
-    const discountAmount = recalcedDiscounts.reduce((sum, d) => sum + d.amount, 0);
-    const afterDiscount = gross - discountAmount;
-    const tax = calculateTax(afterDiscount, line.taxRate, taxContext.pricesIncludeTax);
+  /** Stored lines carry no order share; buildOrder recalculates each with its allocated share (ADR-062). */
+  function recalculateLine(line: LineItem, orderDiscountMinor = 0): LineItem {
+    const grossMinor = line.unitPriceMinor * line.quantity;
+
+    // Each amount is what that discount actually removed, capped at what's left, matching buildOrder's order-discount path (ADR-062).
+    let remaining = grossMinor;
+    const recalcedDiscounts = line.discounts.map((d) => {
+      const amountMinor = Math.min(remaining, computeDiscountAmount(d, d.type === 'percentage' ? grossMinor : remaining));
+      remaining -= amountMinor;
+      return { ...d, amountMinor };
+    });
+
+    // The order share never exceeds what the line discounts leave (allocateOrderDiscount's bound).
+    const lineDiscountMinor = Math.min(grossMinor, recalcedDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
+    const discountMinor = lineDiscountMinor + orderDiscountMinor;
+    const netMinor = grossMinor - discountMinor;
+    const combinedRate = line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0);
+    // Tax in the line's own mode, from its own unit price × quantity: never re-tax a rounded base.
+    const inclusiveTax = line.taxInclusive ? taxMicros(netMinor, combinedRate, true) : 0n;
+    let allocatedTax = 0n;
+    const taxLines = line.taxLines.map((tax, index) => {
+      const micros = line.taxInclusive
+        ? index === line.taxLines.length - 1
+          ? inclusiveTax - allocatedTax
+          : combinedRate === 0 ? 0n : inclusiveTax * BigInt(tax.ratePpm) / BigInt(combinedRate)
+        : taxMicros(netMinor, tax.ratePpm, false);
+      allocatedTax += micros;
+      return { ...tax, taxMicros: micros.toString() };
+    });
 
     return {
       ...line,
       discounts: recalcedDiscounts,
-      discountAmount,
-      taxAmount: tax.taxAmount,
-      lineTotal: taxContext.pricesIncludeTax ? afterDiscount : afterDiscount + tax.taxAmount,
+      discountMinor,
+      orderDiscountMinor,
+      netMinor,
+      taxLines,
+      taxMicros: allocatedTax.toString(),
     };
   }
 
   function computeDiscountAmount(discount: Discount, base: number): number {
+    // Clamped here so both line and order discounts can never go negative (a negative
+    // percentage or fixed value would otherwise raise the price instead of lowering it).
     if (discount.type === 'percentage') {
-      return Math.round((base * discount.value) / 100 * 100) / 100;
+      return Math.max(0, roundHalfAway(base * discount.value / 100));
     }
-    return Math.min(discount.value, base);
+    if (!Number.isInteger(discount.value)) throw new RangeError('Fixed discount must be integer minor units');
+    return Math.max(0, Math.min(discount.value, base));
   }
 
   function buildOrder(): Order {
-    const subtotalLines = lineItems.reduce((sum, li) => {
-      const lineGross = li.price * li.quantity - li.discountAmount;
-      if (taxContext.pricesIncludeTax) {
-        const tax = calculateTax(lineGross, li.taxRate, true);
-        return sum + tax.priceExclTax;
+    // Order discounts are pre-tax (ADR-062). The base is the lines' pre-order-discount amounts, each in its
+    // own mode (an inclusive line's shelf amount, an exclusive line's net). A percentage discount is additive:
+    // each is computed on that base, not on what an earlier order discount leaves (WCPOS `next` / WooCommerce
+    // parity). A fixed discount is computed on what remains, as before. Every discount is then capped at what
+    // remains, which decreases as each is applied, and the total is allocated to the lines, which are then
+    // taxed on what is left.
+    const lineAmounts = lineItems.map((li) => li.netMinor);
+    const base = lineAmounts.reduce((sum, amount) => sum + Math.max(0, amount), 0);
+    let remaining = base;
+    const recalcedOrderDiscounts = orderDiscounts.map((d) => {
+      const amountMinor = Math.min(remaining, computeDiscountAmount(d, d.type === 'percentage' ? base : remaining));
+      remaining -= amountMinor;
+      return { ...d, amountMinor };
+    });
+    const shares = allocateOrderDiscount(lineAmounts, recalcedOrderDiscounts.reduce((sum, d) => sum + d.amountMinor, 0));
+    const lines = lineItems.map((li, index) => recalculateLine(li, shares[index]));
+
+    const { subtotalMinor, taxMinor, totalMinor } = sumLines(lines);
+    const discountMinor = lines.reduce((sum, li) => sum + li.discountMinor, 0);
+    // Display figures (ADR-063): every discount the cashier entered, and each line's order share, converted on its own
+    // into the display mode. A line in the display mode shows quantity × unit price; a converted line shows its
+    // converted remaining (netMinor) plus its rows and share, so it's never less than them. The subtotal is derived
+    // from the settlement total, so every sum is exact; the rounding residue goes to the converted lines' amounts,
+    // never to a discount or an unconverted line.
+    const taxInclusive = taxContext.pricesIncludeTax;
+    const figures = lines.map((li) => {
+      // A negative-priced (return) line shows what settlement charges for it (recalculateLine caps it at 0 today),
+      // with no rows: its capped "discounts" are the negative gross cancelled, not money off.
+      const returned = li.unitPriceMinor < 0;
+      const discounts = returned ? [] : li.discounts.map((d) => ({
+        discountId: d.id, ...(d.label !== undefined ? { label: d.label } : {}), amountMinor: toDisplayMode(li, d.amountMinor, taxInclusive),
+      }));
+      const shareMinor = toDisplayMode(li, li.orderDiscountMinor, taxInclusive);
+      const remainingMinor = toDisplayMode(li, li.netMinor, taxInclusive);
+      const amountMinor = li.taxInclusive === taxInclusive && !returned ? li.unitPriceMinor * li.quantity
+        : discounts.reduce((sum, d) => sum + d.amountMinor, remainingMinor + shareMinor);
+      return { line: { lineId: li.id, amountMinor, discounts }, shareMinor, remainingMinor, returned };
+    });
+    const displayLines = figures.map((f) => f.line);
+    const orderDiscountDisplay = figures.reduce((sum, f) => sum + f.shareMinor, 0);
+    const displayDiscount = displayLines.reduce(
+      (sum, line) => line.discounts.reduce((lineSum, d) => lineSum + d.amountMinor, sum), orderDiscountDisplay);
+    const displaySubtotal = (taxInclusive ? totalMinor : totalMinor - taxMinor) + displayDiscount;
+    const residue = displaySubtotal - displayLines.reduce((sum, line) => sum + line.amountMinor, 0);
+    const converted = lines.flatMap((li, index) => li.taxInclusive === taxInclusive ? [] : [index]);
+    const conversions = converted.reduce((count, index) => count + [lines[index].netMinor, lines[index].orderDiscountMinor,
+      ...lines[index].discounts.map((d) => d.amountMinor)].filter((x) => x !== 0).length, 0);
+    assertDisplayResidue(residue, converted.length, conversions);
+    // Largest converted remaining first (ties to the earlier line). A negative residue takes a line down to its rows
+    // and share at most, then moves on: six 2-cent inclusive lines can owe −3 with no line above 2. The spill is a
+    // crash guard; it never fired in a 200k-cart fuzz. Negative-priced (return) lines convert as they are and never
+    // take residue; refunds get their own design.
+    let left = residue;
+    const takers = converted.filter((index) => !figures[index].returned);
+    for (const index of takers.sort((a, b) => figures[b].remainingMinor - figures[a].remainingMinor || a - b)) {
+      if (left === 0) break;
+      const take = left > 0 ? left : Math.max(left, -figures[index].remainingMinor);
+      displayLines[index].amountMinor += take;
+      left -= take;
+    }
+    if (left !== 0) throw new Error(`Display residue ${left} left over with no converted line to take it (ADR-063)`);
+    // Checked here, not only in tests: every figure >= 0, and no line shows less than its own rows and share (lines
+    // with a non-negative gross; a return line's negative amount is its own).
+    if (displayDiscount < 0) throw new Error(`Display discount ${displayDiscount} is negative (ADR-063)`);
+    for (const { line, shareMinor, returned } of figures) {
+      if (returned && line.discounts.length > 0) throw new Error(`Return line ${line.lineId} shows discount rows (ADR-063)`);
+      if (returned) continue;
+      const rows = line.discounts.reduce((sum, d) => sum + d.amountMinor, 0);
+      if (shareMinor < 0 || line.discounts.some((d) => d.amountMinor < 0) || line.amountMinor < rows + shareMinor) {
+        throw new Error(`Display line ${line.lineId} shows ${line.amountMinor}, less than its rows ${rows} and share ${shareMinor} (ADR-063)`);
       }
-      return sum + lineGross;
-    }, 0);
-
-    const subtotal = Math.round(subtotalLines * 100) / 100;
-
-    const recalcedOrderDiscounts = orderDiscounts.map((d) => ({
-      ...d,
-      amount: computeDiscountAmount(d, subtotal),
-    }));
-
-    const discountTotal =
-      lineItems.reduce((sum, li) => sum + li.discountAmount, 0) +
-      recalcedOrderDiscounts.reduce((sum, d) => sum + d.amount, 0);
-
-    const taxTotal = lineItems.reduce((sum, li) => sum + li.taxAmount, 0);
-
-    const total = lineItems.reduce((sum, li) => sum + li.lineTotal, 0) -
-      recalcedOrderDiscounts.reduce((sum, d) => sum + d.amount, 0);
-
-    const roundedTotal = Math.round(total * 100) / 100;
-    const paidAmount = payments.reduce((sum, p) => sum + p.amount, 0);
-    const balanceDue = Math.max(0, Math.round((roundedTotal - paidAmount) * 100) / 100);
-    const changeDue = Math.max(0, Math.round((paidAmount - roundedTotal) * 100) / 100);
+    }
+    const display = {
+      taxInclusive, subtotalMinor: displaySubtotal, discountMinor: displayDiscount, taxMinor, totalMinor,
+      lines: displayLines, orderDiscountMinor: orderDiscountDisplay,
+    };
+    const paidMinor = payments.reduce((sum, p) => sum + p.amountMinor, 0);
+    const balanceDueMinor = Math.max(0, totalMinor - paidMinor);
+    const changeDueMinor = Math.max(0, paidMinor - totalMinor);
 
     return {
       id: orderId,
       status: 'draft',
-      lineItems: [...lineItems],
+      lineItems: lines,
       discounts: recalcedOrderDiscounts,
       payments: [...payments],
       customer,
       note,
-      subtotal,
-      discountTotal: Math.round(discountTotal * 100) / 100,
-      taxTotal: Math.round(taxTotal * 100) / 100,
-      total: roundedTotal,
-      balanceDue,
-      changeDue,
+      subtotalMinor,
+      discountMinor,
+      taxMinor,
+      totalMinor,
+      display,
+      paidMinor,
+      balanceDueMinor,
+      changeDueMinor,
       currency,
+      pricesIncludeTax: taxContext.pricesIncludeTax,
       createdAt: now,
       updatedAt: new Date().toISOString(),
     };
@@ -135,51 +248,83 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     subject.next(buildOrder());
   }
 
+  function addLine(input: AddLineInput): string {
+    const { productId, variantId, unitPrice } = input;
+    const quantity = input.quantity ?? 1;
+    if (unitPrice.currency !== currency) throw new RangeError('Line currency must match ' + currency);
+    if (!Number.isInteger(unitPrice.amount)) throw new RangeError('Price must be integer minor units');
+    if (!Number.isInteger(quantity) || quantity < 1) throw new RangeError('Quantity must be an integer >= 1');
+    const taxRates = input.taxRates ?? [{ ratePpm: taxContext.getTaxRatePpm() }];
+    const taxInclusive = unitPrice.taxInclusive ?? taxContext.pricesIncludeTax;
+
+    const existing = lineItems.find(
+      (li) => li.productId === productId && li.variantId === variantId && li.taxInclusive === taxInclusive
+        && li.unitPriceMinor === unitPrice.amount && li.taxLines.length === taxRates.length
+        && li.taxLines.every((tax, index) => tax.code === taxRates[index].code && tax.ratePpm === taxRates[index].ratePpm),
+    );
+
+    if (existing) {
+      lineItems = lineItems.map((li) =>
+        li.id === existing.id ? recalculateLine({ ...li, quantity: li.quantity + quantity }) : li,
+      );
+      emit();
+      return existing.id;
+    }
+
+    const lineId = uid();
+    const line: LineItem = {
+      id: lineId,
+      productId,
+      variantId,
+      name: input.name,
+      sku: input.sku ?? '',
+      imageUrl: input.imageUrl,
+      unitPriceMinor: unitPrice.amount,
+      quantity,
+      taxLines: taxRates.map((tax) => ({ ...tax, taxMicros: '0' })),
+      discounts: [],
+      discountMinor: 0,
+      orderDiscountMinor: 0,
+      netMinor: 0,
+      taxMicros: '0',
+      taxInclusive,
+      // TV4b derives the store-level flag with Medusa's own precedence (region
+      // preference, then currency), so a disagreement should be rare. It can
+      // still happen, for example when a price preference changes after the
+      // settings were read. Keeping the line in its own mode means the customer
+      // pays exactly the shelf price, as Medusa's checkout would.
+      ...(taxInclusive !== taxContext.pricesIncludeTax
+        ? { priceTaxModeConverted: taxInclusive ? 'inclusive-to-exclusive' as const : 'exclusive-to-inclusive' as const }
+        : {}),
+    };
+
+    lineItems = [...lineItems, recalculateLine(line)];
+    emit();
+    return lineId;
+  }
+
   return {
     order$: subject.asObservable(),
+    addLine,
 
     addProduct(doc, traits, opts) {
       const productId = traits.getId(doc);
-      const variantId = opts?.variantId;
-      const quantity = opts?.quantity ?? 1;
-
-      const existing = lineItems.find(
-        (li) => li.productId === productId && li.variantId === variantId,
-      );
-
-      if (existing) {
-        existing.quantity += quantity;
-        lineItems = lineItems.map((li) =>
-          li.id === existing.id ? recalculateLine(existing) : li,
-        );
-        emit();
-        return existing.id;
-      }
-
-      const priceStr = traits.getPrice(doc);
-      const price = priceStr ? parseFloat(priceStr) : 0;
-      const taxRate = taxContext.getTaxRate();
-
-      const lineId = uid();
-      const line: LineItem = {
-        id: lineId,
+      if (!traits.isSellable(doc)) throw new Error("addProduct: this product isn't sold in this store's channel");
+      const variant = opts?.variantId !== undefined && traits.getVariants
+        ? traits.getVariants(doc, { currency }).find((variant) => variant.id === opts.variantId) : undefined;
+      if (opts?.variantId !== undefined && traits.getVariants && !variant)
+        throw new Error(`Unknown variant ${opts.variantId} for product ${productId}`);
+      const unitPrice = resolvePrice(variant ? variant.prices : traits.getPrices(doc, { currency }), currency)?.current;
+      if (!unitPrice) throw new Error('No price in ' + currency + ' for product ' + productId);
+      return addLine({
         productId,
-        variantId,
+        variantId: opts?.variantId,
         name: traits.getName(doc),
-        sku: traits.getSku(doc) ?? '',
+        sku: variant?.sku ?? traits.getSku(doc),
         imageUrl: traits.getImageUrl(doc),
-        price,
-        quantity,
-        taxRate,
-        taxAmount: 0,
-        discounts: [],
-        discountAmount: 0,
-        lineTotal: 0,
-      };
-
-      lineItems = [...lineItems, recalculateLine(line)];
-      emit();
-      return lineId;
+        unitPrice,
+        quantity: opts?.quantity,
+      });
     },
 
     updateQuantity(lineId, quantity) {
@@ -202,11 +347,11 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
     applyLineDiscount(lineId, discount) {
       lineItems = lineItems.map((li) => {
         if (li.id !== lineId) return li;
-        const base = li.price * li.quantity;
+        const base = li.unitPriceMinor * li.quantity;
         const applied: AppliedDiscount = {
           ...discount,
           id: uid(),
-          amount: computeDiscountAmount(discount, base),
+          amountMinor: computeDiscountAmount(discount, base),
         };
         return recalculateLine({ ...li, discounts: [...li.discounts, applied] });
       });
@@ -217,7 +362,7 @@ export function createOrderBuilder(options: OrderBuilderOptions): OrderBuilder {
       const applied: AppliedDiscount = {
         ...discount,
         id: uid(),
-        amount: 0,
+        amountMinor: computeDiscountAmount(discount, 0),
       };
       orderDiscounts = [...orderDiscounts, applied];
       emit();