0101. The device effects, and how each says a platform cannot
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-14
- Decided by: wave 5 implementer, domain B (internal only)
- Planning item: WP11 (platform effects), sub-briefs wp11-20 to wp11-37
Context
A complete mobile framework gives an app location, the clipboard, biometrics, contacts, a file and media picker, the network state, the app badge, motion sensors and the compass, the keyboard, device information, an in-app browser, store reviews, screen settings, sound recording, the calendar, a barcode scanner, speech, and App Tracking Transparency. @duolith/effects had none of them. Each must work on the web, Android and iOS, and where a platform cannot do one, the app must find out: never a silent no-op (decision 0050's rule for every effect).
Three choices had to be made for all eighteen at once: their names, how each says "this platform cannot", and which mistakes the build catches.
Decision
Names. Each effect is a named export of @duolith/effects, as the others are. Three names differ from the plain word, to keep clear of names an app already has:
- the network state is
connection, sincenetworkis the runtime's (@duolith/client's offline switch); - the screen settings are
display, sincescreenis both the<screen>element and the browser'swindow.screen; - recording is
recorder, a thing with astate, ascamerais.
Unavailable, by effect. Every device effect has available (or supports(feature), canSpeak, canListen) and unavailableReason, a sentence the page can show, read before anything is called. Then:
| Where it cannot | How it says so | Why |
|---|---|---|
| Review on the web | request() resolves "unavailable" | Asking is a hope, not a need: the app shows its own feedback link |
| Badge on Android, and on the web outside an installed app | set() resolves "unavailable" | Android has no icon count; a tab has no icon |
| Tracking on Android and the web | "not-needed" | There is nothing to ask; an app that branches on "authorized" must see this is not a refusal |
| Display brightness on the web, orientation lock where not allowed | "unavailable" | The app keeps working; it is a setting |
| Calendar on the web | "handed-off" (an .ics download) | The event leaves the app; the user may still decline it |
| Contacts, listening, a sensor, the picker on iOS 13 | E0222 with the reason | The call has no outcome to give |
| The scanner without BarcodeDetector (Safari, Firefox) | E0425, loudly | A camera that never reads anything is worse than a clear failure |
| A platform failure | the effect's own code, E0420 to E0430 | duolith explain says what to do |
At build time. browser.open("…") with an address written as text that is not an absolute http or https one fails the build with E0420, in the script block and in markup expressions, under whatever name browser is imported as. iOS's SFSafariViewController stops the app on any other address, and a javascript: address must never run. An address built when the app runs is checked then, with the same code.
Permissions. The effect asks through permissions, the first time it needs one, never the page. Where the system's picker shares only what the user picks (contacts on iOS, the photo picker, Android's code scanner), none is asked. The build writes the declarations for the effects the app imports: Info.plist keys, Android permissions, features and <queries>, and the web's Permissions-Policy features (web/permissions-policy.txt, for the host to send).
Replaceable platforms. Each device effect has use(platform) and a mock (mockLocation to mockTracking, and mockPermissions), for tests and for examples that run in a desktop browser.
Alternatives considered
| Option | Why not |
|---|---|
| Refuse to build for a target that cannot do an effect (as E0202 does for effects not built yet) | Every effect here is built for every target; what a device lacks (a compass, a store, Firefox's recognition) is known only when the app runs |
| Always resolve "unavailable", never fail | contacts.pick() resolving undefined on Firefox reads as "the user closed the picker", which is the silent no-op this rule forbids |
network, screen and recording as names | They clash with the runtime's network, the <screen> element and window.screen |
| Check written addresses for every effect that takes one | Only browser.open has an address that can crash a platform; links have E0170 already |
Consequences
- A page can always show why something is missing before the user presses anything, and a press never does nothing.
- The E0420 check reads only addresses written where they are used. One held in a top-level
const, as decision 0099 reads paths, is checked when the app runs; extending the check to such consts is a follow-up. - On iOS, the brightness is the device's until it locks; the effect puts the level it found back when the app clears it.
- Swift for the eighteen effects has not been compiled, and all of them need a device run (native/DEVICE-CHECKLIST.md).