0141. Links reach the router through the shell, other sites open in the system, and a dev server reloads the app on a phone
- Status: Accepted (Mik, 16 Nov 2026), with
sms:kept and plain http allowed in debug builds only. - Date: 2026-11-14
- Decided by: Mik (the adapter contract additions, the preview app); integrator (built on the recommendation meanwhile)
- Planning item: none
Context
On a phone, a link to the app (a universal link, an App Link, the app's own scheme) must open the right screen whether the app was closed or running, and sign-in's magic links need the whole address. An href to another site did nothing on native (the engine had no way to leave the app). The environment values the web build sets as __duolith_environment were never set on native. And trying a change on a phone meant rebuilding the app.
Decision
- The shell hands links over whole. Android (intent filters with
autoVerify, a singleTask activity) and iOS (scene URL contexts and web-browsing user activities) pass only links on the manifest's domains or in its scheme (decision 0140), as thelinkglobal prop when the link started the app and as theduolithLinkglobal event while it runs. - The adapter contract grows (
packages/engine/adapter.d.ts):initialLink(),listenForLinks(listener),shellEnvironment()andopenExternal(url).@duolith/client/nativeroutes each link to its path (linkPath: an https link's path, query and fragment; a scheme link's host and path) and exposesonLink(listener)andlastLink()for code that needs the address, such as sign-in. This is the contract agreed with sign-in: it reads the magic link fromonLink/lastLink, and its return address is an https link on a link domain, or the app's scheme. - Other sites open in the system: an
hrefwith a scheme callsopenExternal, which isopenUrlon the DuolithShell module (AndroidACTION_VIEWwithCATEGORY_BROWSABLE, iOSUIApplication.open). Only http, https, mailto, tel and sms are opened, checked in the engine and again in each shell:javascript:must never run,file:stops an Android app, and an app's own scheme is a path in it. Anhrefwritten as text, or as one string in braces, with another scheme fails the build (E0170);sms:joins the link addresses on every target so the lists are one. - Environment values: the native build writes the
DUOLITH_PUBLIC_*variables of its environment, by their camel-case names, into the app's file (duolith-app.json); the shell passes them as theenvironmentglobal prop, and the client sets__duolith_environmentfrom it. - **
duolith dev --target android|ios [--host]** builds, bundles and serves/main.lynx.bundle,/duolith-app.jsonand a WebSocket at/_duolith/socketthat sends{"type":"reload"}after each rebuild (or{"type":"error"}), from the Duolith command with no extra dependency (a small RFC 6455 server). A debug build of the shell given the address (-Pduolith.devServer, theduolithDevServerextra or launch argument) loads from it and reloads the bundle on the message; release builds never do. The socket takes a connection with noOrigin(a shell) or the server's own; each write has a time limit, and none is made while the served state is locked. A link that arrives before the app's file is fetched waits for it; the newest such link is the one the app opens on. With--hostit listens on the network and prints a QR code of the address. - The preview app (
native/preview-app) is the shell with a scan screen and no app of its own, asdev.duolith.preview: it reuses the shell's code and resources, and opens the scanned address. The dev server's page offersduolith-preview://open?server=<address>for phones whose own camera scanned the code; since any page can send that link, the preview app asks before it opens the app a link names.
Alternatives considered
| Option | Why not |
|---|---|
| The shell navigates itself (passing only a path) | Sign-in needs the whole address; the router already knows the routes |
A DuolithShell.onLink callback registered from the bundle | A global prop and a global event are how the shells already talk to the engine (back, effects), and they reach the bundle before its first frame |
| Lynx's own dev tools and the Lynx Explorer app for previews | Explorer loads a bundle URL but knows nothing of Duolith's effects and shell modules; the preview app is the real shell |
| A third-party WebSocket or QR crate stack for the dev server | Kept to qrcode and sha1_smol; the server is a few dozen lines and tested with a headless client |
Consequences
- The engine's adapter and the client gained exports; the in-browser tests (
native-shell-in-browser.test.ts) drive them through a stand-in DuolithShell module. - The preview app cannot carry an app's name, icon, link domains or unusual permissions; those need the shell's own debug build.
- Mik to confirm: the adapter additions, the
duolithLinkandlinknames, plain http to the computer in debug builds (cleartext allowed only in debug builds on Android, the shell's and the preview app's; the iOS preview app allows local networking always and arbitrary loads only in its Debug build), and publishing the preview app to the stores later.