# BigSale HDLKiosk integration

This directory is the compatibility boundary between BigSale/SalesSDK and the
independent `components/HDLKiosk` material.

## Structure

- `index.tsx`: outer composition only; renders device owners, HDLKiosk and the
  embedded payment runtime.
- `hooks/`: template-level React hooks, including stable Host assembly, cart
  presentation, login-module registration and entry preparation feedback.
- `adapter/createHost.ts`: pure Host composition, capabilities and fulfillment
  writer.
- `utils/transactionState.ts`: derives only dispatch-time write/payment
  safety facts; UI receives raw order/catalog/customer fields through `sourceData`.
- `adapter/devicePort.ts`: raw BigSale device sources converted to HDLKiosk ports.
- `adapter/sales/index.ts`: Sales Port entry for direct session, identity,
  fulfillment and payment delegation.
- `adapter/sales/`: substantive catalog, cart and weighted-product modules.
- `utils/`: pure TypeScript helpers for transaction state, scale bridging,
  result normalization and primary weighted-product lookup.
- `BigSaleScaleRuntimeOwner.tsx`: the only React owner of the native
  scale Hook; publishes exclusively through ScaleBridge.
- `payment/`: payment runtime, EFTPOS execution, staff authorization and result
  normalization.
- `HDLKioskIdentityAuthPanel.tsx`: BigSale login/register UI integration.
- `tests/`: all tests and test-only fixtures, grouped by production concern.

## Boundary rules

1. Raw BigSale, SalesSDK and OS objects stop in this directory.
2. HDLKiosk Core receives only contracts from `components/HDLKiosk/app`.
3. UI reads `sourceData` directly; writes use explicit Host operations.
4. `readTransactionState()` is not a UI store. It exists only for a write or
   payment command to re-read current cart/payment/amount facts at dispatch.
5. React-owned capabilities are assembled in `hooks/useBigSaleHDLKioskAdapter`; do
   not add new controller refs to `index.tsx`.
6. Keep one-line delegation in `adapter/sales/index.ts`; split out only logic
   with its own projection, validation or mutation algorithm.
7. Keep production folders free of tests; all test files and fixtures belong
   under `tests/`.