@gomani/adaptive

Network-adaptive rendering as a first-class reactive primitive for Gomani — responsive design for the network, not the viewport.

Network quality is just another signal (P4). A component declares a full path and a lean path, and the framework selects: on the server (zero JS) from the request's Save-Data header and the persistent data-saver cookie; on the client from the Network Information API or a measured sampler. The user always holds an overriding data-saver control that trumps inference.

Authoring

import { Adaptive, tier } from '@gomani/adaptive';

<Adaptive
  full={<HeroWithArtwork />} // capable connections
  lite={<HeroTextOnly />} // constrained / data-saver
/>;

// Or map the quality to anything:
const cols = tier((q) => (q.tier === 'lite' ? 1 : 3));

Only the chosen variant is rendered to HTML, so the other costs nothing. Placed in a static region it is server-decided (zero JS); placed inside an island it re-evaluates against the client signal.

How the tier is decided

Defensive by construction — any single "constrained" signal drops to lite, and the user's override wins. The default is full (the rich path) with a drop to lite only on evidence of constraint, because the two most common browsers expose no Network Information API.

| Priority | Signal | Result | | -------- | --------------------------------------------- | ------ | | 1 | Data-saver override (on / off) | forces | | 2 | Save-Data: on | lite | | 3 | effectiveType ∈ {slow-2g, 2g, 3g} | lite | | 4 | measured downlink < 1.5 Mbps, or RTT > 500 ms | lite | | 5 | (default) | full |

The data-saver control

// Client-only APIs live at the `/client` subpath, so the main entry stays server-safe (no DOM).
import { setDataSaver, initClientQuality } from '@gomani/adaptive/client';

setDataSaver('on'); // persist + reload → the server serves lean everywhere
initClientQuality(); // opt-in: detect + keep the signal current + persist the tier for the server

setDataSaver writes a cookie the server reads, so the choice persists across requests and drives the zero-JS server decision. initClientQuality runs the measured sampler and persists the detected tier for the next request — progressive refinement without blocking the first paint.

License

MIT © Venancio Gomani / Kwacha Kulture.