# framebudget

> framebudget is a TypeScript library for the browser that decides, per device, which visual effects a site can afford. It measures how much of each 16.7 ms frame a device really has and allows only the effects that fit, so slow phones never stutter and fast phones keep everything.

- Install with `npm install framebudget`. ESM only, with type declarations, MIT license. `react` is an optional peer dependency, needed only for `framebudget/react`.
- Entry points: `framebudget` (the `budget` object, `configure`, `createBudget`, `Tier`, `defaultCalibration`), `framebudget/boot` (`bootScript`, `createBootScript`), `framebudget/react` (`useBudget`, `useTier`, `BudgetProvider`), `framebudget/panel` (`mountPanel`).
- An inline boot script runs a 2 ms CPU benchmark before the first paint and writes the decision on `<html>` as `data-framebudget` (the tier) and `data-framebudget-effects` (the allowed effects), so CSS can gate effects with `html[data-framebudget-effects~="parallax"]`.
- Each effect has a score threshold (100 is the reference phone), a relative frame cost, and optional `motion` and `data` flags. A runtime governor watches real frame gaps and steps the most expensive effects down. Local learning remembers effects that stuttered on the device.
- On the server, `budget.allows()` answers `false` and the tier is `Lite`. Telemetry is off by default, has no default endpoint, and is never sent under Global Privacy Control or Save-Data.

## Docs

- [API reference](https://framebudget.dev/api): every export, the boot script, effects and tiers, simulating a device, the governor, calibration, telemetry, the React hooks and the diagnostics panel.
- [Full documentation in Markdown](https://framebudget.dev/llms-full.txt): install, boot script, usage, API, effects, tiers, benchmark, governor, learning, calibration, React, telemetry and privacy, in one file.
- [README on GitHub](https://github.com/framebudget/core#readme): the same documentation, next to the source.

## Examples

- [Live demo](https://framebudget.dev/): the landing page is itself built with framebudget. Its device simulator calls `budget.simulate(score)` so the page really changes per device.

## Optional

- [Source code](https://github.com/framebudget/core): TypeScript, MIT license.
- [Privacy on framebudget.dev](https://framebudget.dev/privacy): what the site's own telemetry collects and how to opt out.