Duolith docs

0057. A load directive makes a placed component an island

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: none (WP12)

Context

Parts of a screen below the fold, or that need a press first, should not cost anything until they are needed. The glossary calls such a part an island: "a unit of a screen that loads, updates and fails on its own".

Decision

Any placed component accepts load="visible" | "idle" | "interaction", besides its props. It is then an island:

DirectiveBuilt when
visibleIt comes within 200 px of the viewport
idleThe browser is next idle, within two seconds at most
interactionIt is pointed at, pressed or focused; until then its skeleton is a button named "Load" to keyboards and assistive technology

Until then its skeleton holds its place: the shape this placement had the last time it was shown (decision 0059), or one block. Building it means running its script and building its view, inside its own boundary (decision 0058): if it throws, a fallback with Try again replaces only it.

On the web, an island's code is its own module, downloaded only when its directive fires: the compiler leaves out the page's import of a component that the page places only with load= and does not name in its script or in any other markup expression, and the template gives the island the module's address. The runtime imports it then, and its skeleton stays until it arrives. The page downloads each island module once: every placement of it, and every remount, shares that download and the component it gave. A download that fails is the island's failure: its fallback shows, and Try again downloads it afresh. Browsers keep a module that failed as failed for the life of the page, under its address, so the retry imports the island's module at a new address of the app's own origin (the same path with a ?retry=N query), which the strict Content-Security-Policy allows (decision 0150); copying modules to blob: addresses would need the policy loosened. The modules it imports keep their addresses, so the island shares the page's state. A module it imports that failed stays failed until the page reloads, and a retry that meets one says so and asks for a reload. A later placement of an island whose download failed tries afresh too. A component the page also places without load=, or names elsewhere, keeps its import, and its islands only wait to run. When pages are rendered ahead of time, the same directives will say when an island's server-rendered markup hydrates.

load written as an expression is E0244 (the directive is fixed at build time); an unknown directive is E0241. The directives are listed in spec/language/elements.yaml (loads).

Native (updated): built in the engine adapter (packages/engine/src/island.tsx). emit-native writes a component with load= as an Island whose content is built only once its directive fires; until then it shows a boundary skeleton, at the island's remembered height (decision 0059). idle builds once the screen has drawn, interaction on a tap of the skeleton (labelled "Load", a button to assistive technology; a finger that lands on it to scroll builds nothing), and visible when Lynx's exposure event (binduiappear) says the skeleton is within 200 points of the screen. In a list, each row's island is its own: its remembered shape and its exposure id are the placement's name with the row's key (rows.ts). Lynx for Web tests all three.

Alternatives considered

OptionWhy not
client:visible (Astro's spelling)There is no server/client split in a Duolith page yet; load says what changes
An <island> wrapper elementEvery island is a component in practice, and the wrapper would add a level of markup
load as a prop the component declaresEvery component would have to declare it; it is the placing file's decision
Ship the island's code with the page and defer only its scriptThe download is most of what an island saves on a slow network

Consequences

A component cannot declare a prop called load; the name is the directive's.