Clarifies 0235: peripherals are the client’s
own hardware; devices are principals in identity.
Context
Retail and attendance clients need local hardware: receipt printers, barcode scanners, cash drawers, card readers and QR kiosks. The owner accepted the defaults on 2026-10-20 night: browser device APIs first, no native modules on day one, and device presets for the first two kits.Decision
- Package.
@stackra/peripherals(experience category) provides the peripheral ports, and the thin browser implementations of them. - Web APIs first. Browser device APIs (WebUSB, WebHID, Web Bluetooth, Web NFC where available) are used first. No native module is added on day one.
- Native on evidence. A native module is added only when a measured requirement is not met by the Web APIs, and each one needs its own ADR.
- Presets. Device presets are profiles in
@stackra/peripherals:- the POS kit for Retail OS: ESC/POS receipt printer, HID barcode scanner and cash drawer;
- the attendance kit for Academorix: NFC or card reader and a QR scanner kiosk. More presets follow the same form.
- Separate from devices. A peripheral is hardware the client uses. A device is a principal in identity (ADR 0235).
Consequences
- A kiosk works in a browser before any installer exists.
- A new preset is a profile, not new code.
Enforcement
planned — each preset has a test against a recorded device fixture; the validator rejects a native module added without an ADR reference.Supersedes and sources
Supersedes: none. Clarifies: 0235. Sources: desktop and PWA owner decision (defaults and device presets,stackra-decisions-2026-10-19.md L954, 2026-10-20 night); plan section 2.3.