Duolith docs

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, since network is the runtime's (@duolith/client's offline switch);
  • the screen settings are display, since screen is both the <screen> element and the browser's window.screen;
  • recording is recorder, a thing with a state, as camera is.

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 cannotHow it says soWhy
Review on the webrequest() 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 appset() 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 13E0222 with the reasonThe call has no outcome to give
The scanner without BarcodeDetector (Safari, Firefox)E0425, loudlyA camera that never reads anything is worse than a clear failure
A platform failurethe effect's own code, E0420 to E0430duolith 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

OptionWhy 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 failcontacts.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 namesThey clash with the runtime's network, the <screen> element and window.screen
Check written addresses for every effect that takes oneOnly 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).