# zelvior-runtime
[](https://www.npmjs.com/package/zelvior-runtime)
[](./LICENSE)
Dependency-free, adaptive browser runtime for lazy-loading, scheduling, and
self-tuning performance based on live device/browser conditions. **~20.5KB
minified, ~7.3KB gzipped core bundle, zero runtime dependencies.**
> **Version note:** this package is at v0.14.0 locally. v0.8.0-v0.10.0
> added six new zero-coupling modules (`tier`, `raf`, `idle`, `resize`,
> `intersect`, `paint`), an IndexedDB-first `storage` module, an es5
> `zelvior.legacy.js` build target, and `Z.lite` — an opt-in, default-off
> visual-simplification mode. v0.11.0 added `zelvior-runtime/security`
> (client-side hardening: sanitization, URL-safety, clickjacking,
> prototype-pollution freezing, CSRF tokens) and encryption-at-rest for
> `storage` via `createEncryptedStore`. v0.12.0 added real battery-aware
> tuning to `Adaptive`. v0.13.0 added (and v0.14.0 removed —
> see below) `forcePassiveScrolling()`. **v0.14.0** replaced it with
> `createAdaptiveScroll()` (a narrower, opt-in adaptive scroll listener,
> not a global listener patch — see that module's section below);
> added `zelvior-runtime/privacy` and `zelvior-runtime/cookies`; added
> `"sideEffects": false` for real bundler tree-shaking (see the new
> Tree-shaking subsection); and fixed a real, three-times-repeated bug
> where bare `navigator`/`matchMedia` references silently picked up
> Node.js's own global `navigator` instead of the page's — see
> CHANGELOG.md for the full account. Core bundle size is unaffected by
> v0.13.0/v0.14.0 (`scroll`/`privacy`/`cookies` are all separate
> zero-coupling modules) — it grew from ~19.4KB → ~20.5KB minified in
> v0.12.0 (~7.0KB → ~7.3KB gzipped, from the battery feature) and has
> stayed there since. See the exact, regenerated-on-every-build sizes in
> the Modules section and Benchmarks below, and CHANGELOG.md for what
> changed in each release.
> **About `npm WARN Zelvior No description`/`No repository field`/etc.:**
> if you see these while running `npm install zelvior-runtime`, they are
> **not about this package** (which has all four fields — check
> `package.json` yourself). Older npm (6.x) auto-creates a stub
> `package.json` in your current directory when none exists, and warns
> about *that* stub. Run `npm init -y` first, or install inside an
> existing project, to avoid seeing them.
## Contents
- [Install](#install)
- [CDN (no build step, no install)](#cdn-no-build-step-no-install)
- [Quick API](#quick-api)
- [Modules (standalone, zero-coupling)](#modules-standalone-zero-coupling)
- [Subsystems](#subsystems)
- [Formats](#formats)
- [Browser support](#browser-support)
- [Benchmarks](#benchmarks)
- [TypeScript](#typescript)
- [Testing](#testing)
- [Security](#security)
- [Landing page](#landing-page)
- [Documentation](#documentation)
- [Building from source](#building-from-source)
- [License](#license)
## Install
```bash
npm install zelvior-runtime
pnpm add zelvior-runtime
yarn add zelvior-runtime
bun add zelvior-runtime
```
```js
import Zelvior from 'zelvior-runtime';
Zelvior.enable();
```
```js
// CommonJS
const Zelvior = require('zelvior-runtime');
Zelvior.enable();
```
## CDN (no build step, no install)
```html
```
```html
```
```html
```
JSPM: `https://jspm.dev/zelvior-runtime` resolves the same `exports` map.
No code changes are required between the npm import, the CommonJS require,
and the `
```
(that exact snippet was checked against the live CDN before being used
here — `curl`/fetch confirmed jsDelivr serves real content for this
package, not a 404 placeholder.)
## Documentation
- [ARCHITECTURE.md](./ARCHITECTURE.md) — subsystem internals and data flow
- [PERFORMANCE.md](./PERFORMANCE.md) — full audit log: every defect found, why it mattered, and the fix
- [CHANGELOG.md](./CHANGELOG.md) — version history (v0.7.0: real connection-awareness added to `Adaptive`, new `zelvior-runtime/net` module for request dedup/caching/preconnect — honestly scoped, does not "speed up the internet")
## Building from source
```bash
git clone https://github.com/zelvior/zelvior-runtime.git
cd zelvior-runtime
npm install
npm run build # runs build.mjs → writes dist/ + BUNDLE_SIZES.md
```
`src/zelvior.js` is the single ESM source of truth; `build.mjs` (esbuild)
produces all six `dist/` variants plus `dist/zelvior.d.ts` from it. There is
no other source file and no other build step.
### You almost certainly do not need to do this
`dist/` ships prebuilt in every npm release and in this tarball. If you just
want to **use** the runtime, `npm install zelvior-runtime` (or unpack this
tarball) and import/require/`