# ResponsiveJS — complete documentation

<!-- https://responsivejs.com/docs/getting-started -->

# Getting started

ResponsiveJS (`r$`) is one model — **`value = f(width)`** — with two halves: *author*
responsive behavior CSS can't express, *verify* the rendered result with measurements.

**Start with the second half.** It costs one command, changes nothing in your codebase, and
tells you something true about a site you already have:

```bash
npx @responsivejs/cli analyze https://your-site.com -w 320,375,768,1024,1280,1920
```

Every width judged: what overflows, which targets miss the WCAG 24px floor, where contrast
fails against the background actually painted, whether the page scrolls sideways on a phone.
Exit `0` pass, `1` violations — so it is a CI gate the moment you want one. Nothing installed,
nothing imported, no decision made.

Liked what it found? [Pin it as a contract](adopting) — still without writing r$ code. Only
then is the authoring half worth its install: it is for the cases CSS genuinely cannot express,
not for replacing CSS you already have.

- [**Adopting r$ in a site you already have**](adopting) — the five-step path, each step
  useful on its own
- [**The tutorial**](tutorial) — the other direction: build a page from nothing, ~30 minutes
- [**Why r$**](why) — "I can write `clamp()` myself", "we have visual regression testing",
  and when *not* to use it
- [**Troubleshooting**](troubleshooting) — by symptom

## What it replaces

| The hack you write today | The r$ construct | What you gain |
| --- | --- | --- |
| A `@media` ladder for every size | `r$.tokens({ '--space-m': r$.fluid(16, 24) })` | Smooth scaling, static `clamp()`, zero JS |
| The burger breakpoint that rots | `r$.geometry('.nav', { wrapped: r$.whenWraps })` | Adapts by *measurement* — add a link, still correct |
| IntersectionObserver sticky-sentinel | `r$.whenStuck()` | One line, no sentinel DOM |
| Resize listeners + manual measuring | `r$.sync`, `r$.ratio`, `r$.fromElement` | Cross-element relations, cleanup included |
| `'mobile'` strings that typo at runtime | `r$.breakpoints({...} as const)` | Names the compiler checks |
| Squinting at three screen sizes | `rjs analyze <url>` | Measured verdict at every width, exit-code gated |
| Screenshot diffing for regressions | `rjs record` / `verify` contracts | The layout's rules as reviewable JSON |

Pick your entry:

| I want to…                                             | Install                                | Start here |
| ------------------------------------------------------ | -------------------------------------- | ---------- |
| Audit a URL right now, zero setup                      | nothing — `npx @responsivejs/cli`      | [§ Audit](#audit-cli) |
| Author responsive behavior (fluid, geometry, tokens)   | `npm i @responsivejs/runtime`          | [§ Authoring](#authoring) |
| Validate/score a page in CI                            | `npm i -D @responsivejs/design @playwright/test` | [§ Validation](#validation) |
| Score a live DOM without any driver                    | `npm i @responsivejs/design`           | [§ Zero-driver](#zero-driver) |
| Pin a layout down as a verifiable contract             | `npm i -D @responsivejs/contract`      | [§ Contracts](#contracts) |
| Use it in React / Vue / Angular                         | `npm i @responsivejs/react` · `/vue` · `/angular` | [§ Adapters](#adapters) |
| Just the math (curves, geometry, WCAG, aesthetics)     | `npm i @responsivejs/core`             | [API: core](api/core) |
| Drive r$ as an AI agent                                | —                                      | [agents docs](agents/validation-reference) |

No bundler? `<script src="…/@responsivejs/runtime/dist/global.js"></script>` gives you the
same `r$` on `window` (~15.5 kB gzip) — CMS pages, plain HTML, live demos.

All packages are ESM-only, zero runtime dependencies (Playwright and axe-core are optional
peers of `design`), Node ≥ 20.19, MPL-2.0.

## Audit (CLI)

```bash
npx @responsivejs/cli analyze https://example.com -w 320,768,1280
# constraints + a11y · exit 0 pass / 1 violations · -f json|sarif · --score adds the heuristic

npx @responsivejs/cli audit https://example.com --vs https://competitor.com
# → one self-contained HTML report: screenshots with violation overlays, side-by-side
```

Driver-pluggable (Playwright, or [agent-browser](https://github.com/vercel-labs/agent-browser)
for any live URL with nothing installed). `verify`/`record` run the contract flow.

→ [CLI reference](api/cli) · [the design guide](guides/validation)

## Authoring

One import, the whole surface behind your editor's autocomplete:

```typescript
import { r$ } from '@responsivejs/runtime';

const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1024 } as const);

r$.tokens({ '--space-m': r$.fluid(16, 24), '--font-hero': r$.fluid(28, 64) });  // clamp() on :root
r$.geometry('.site-nav', { wrapped: r$.whenWraps });   // CSS: .site-nav[data-wrapped] { … }
r$('.cards', { gridTemplateColumns: bp.below('tablet', '1fr', 'repeat(3, 1fr)') });
```

r$ is CSS-first: everything expressible as `clamp()`/`@media` becomes one injected stylesheet;
JS drives only what CSS cannot — non-linear curves, **geometry state** (wrap, overflow,
sticky, truncation), **cross-element dependencies** (`fromElement`, `sync`, `ratio`). Add
`{ container: true, from, to }` to bind a value to the nearest container instead of the
viewport — `from`/`to` are the container's own range, and are required.

→ **[the runtime guide](guides/runtime)** (purposes, gradual examples, the mental
model) · [case studies](guides/case-studies) · [API: runtime](api/runtime) ·
[live example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing)

## Adapters

The constructs are framework-agnostic; the adapters own the **lifecycle**.

```tsx
// React
const ref = useRef<HTMLDivElement>(null);
useResponsive(ref, { padding: r$.fluid(12, 24) });   // applied on mount, disposed on unmount
const isDesktop = useBreakpoint('desktop');
```

```vue
<!-- Vue -->
<script setup>
const card = ref(null);
useResponsive(card, { padding: r$.fluid(12, 24) });
</script>
<template><div ref="card" v-responsive="{ gap: r$.fluid(8, 16) }" /></template>
```

Changing a declaration calls `update()` on the live handle instead of recreating it; React's
StrictMode double-invocation is handled. Angular ships decorator-free helpers (`injectResponsive`,
`injectViewportWidth`, …) that need no compilation step.
→ **[adapters reference](api/adapters)**

## Validation

```typescript
import { test, expect } from '@playwright/test';
import { r$ } from '@responsivejs/design';

test('layout holds at all widths', async ({ page }) => {
    const r = r$(page);
    await r.sweep({ url: 'http://localhost:3000', widths: [320, 768, 1280], selectors: ['h1', '.btn'] });
    r.assert.noOverflow().minSize('.btn', { height: 44 }).monotonic('h1', 'fontSize', 'up');
    expect(r.report().pass).toBe(true);
});
```

Or run the whole oracle in one call — constraints + aesthetic score + a11y (axe):

```typescript
const report = await r$(page).sweep({ ... }).then((r) => r.analyze());
// UnifiedReport: { pass, violations, fixes, scores, summary, … }
```

→ **[the design guide](guides/validation)** (measure → model → judge) ·
[API: design](api/design) · [guide: CI](guides/ci)

## Zero-driver

The browser subpath runs anywhere a DOM exists — no Playwright:

```typescript
import { scoreDOM, analyzeStore, collectStore } from '@responsivejs/design/browser';

const { average, suggestions } = scoreDOM(['main', '.card']);   // 17-metric aesthetic score
const report = analyzeStore(collectStore(['main', '.card']));   // full constraint report
```

Inject it into any page via a driver's `eval` (CDP, agent-browser) — see the
[agents guide](guides/agents).

## Contracts

```typescript
import { contract } from '@responsivejs/contract';
import { verifyContract } from '@responsivejs/design';

const home = contract('home')
    .select('sidebar', '.app-sidebar')
    .assert('noOverflow', undefined, { id: 'no-bleed' })
    .below(768).assert('hidden', { selector: '$sidebar' }, { id: 'sidebar-mobile' })
    .from(768).assert('visible', { selector: '$sidebar' }, { id: 'sidebar-desktop' })
    .build();

const report = await verifyContract(home, page);   // sweep derived from the contract
```

Contracts serialize to JSON (published [schema](https://github.com/AleSaiani/ResponsiveJS/blob/main/packages/contract/schema/design-contract.v1.json)),
travel with the repo, and double as the machine-readable spec agents enforce.

→ [API: contract](api/contract) · [guide: CI](guides/ci)

## Development setup (this repo)

```bash
git clone https://github.com/AleSaiani/ResponsiveJS.git && cd ResponsiveJS
pnpm install
pnpm test        # unit tests, plain Node
pnpm typecheck   # no build needed (source-resolved)
pnpm build       # tsc, topological
pnpm test:e2e    # needs: pnpm --filter @responsivejs/design exec playwright install chromium
```


---

<!-- https://responsivejs.com/docs/adopting -->

# Adopting r$ in a site you already have

The [tutorial](tutorial) builds a page from nothing. This is the other path: you have a
codebase, media queries you did not write, and no appetite for a rewrite. Nothing here asks you
to change a line of CSS until step 4 — and step 4 is optional.

Each step is useful on its own. Stop wherever the value stops.

## Step 1 — Measure what you have (about a minute, nothing installed)

```bash
npx @responsivejs/cli analyze https://your-site.com -w 320,375,768,1024,1280,1920
```

You get every width judged: what overflows, which targets are under the WCAG 24px floor, where
contrast fails against the background actually painted, and — if the page scrolls sideways at
any width — the document's own reach. Exit `0` pass, `1` violations.

If nothing is found, you have learned something real for the price of a minute. If plenty is
found, do not fix it yet: pin it first.

**No browser driver?** `npx @responsivejs/cli doctor` tells you what is available and the exact
install command for what is not.

## Step 2 — Pin today's reality as a contract

```bash
npx @responsivejs/cli init https://your-site.com -o site.contract.json
```

This works on a page that has never heard of r$: the rules that carry most of the value need
neither a construct nor a selector you have to invent. You get a JSON file with the page-wide
rules, plus baselines for the headings and body text it found. Read it — it is meant to be
reviewed, not trusted blindly. Delete rules you disagree with, tighten the ones you care about.

```bash
npx @responsivejs/cli record site.contract.json https://your-site.com   # pin today's curves
```

`record` measures the current type scale and writes it into the contract. From now on, a change
to those curves is a **diff in a reviewed file** rather than a surprise.

## Step 3 — Make it a gate

```yaml
- run: npx @responsivejs/cli verify site.contract.json http://localhost:4173/ -d playwright
```

Run it against the built site, not the dev server. Two rules for keeping the gate trusted:

- **Start from green.** If the audit found twenty violations, do not gate on all twenty on day
  one. Fix, or narrow the contract with `when: { min, max }` ranges, until it passes — a gate
  that is red on arrival gets ignored within a week.
- **Warnings are not failures.** Only errors fail. `✓ 794/799 checks (5 warnings — no errors)`
  is a pass, and the five are worth a look, not a build break.

At this point you have regression protection and have written no r$ code at all. For a lot of
teams this is the whole adoption.

## Step 4 — Replace the breakpoints that actually hurt

Now, and only now, is the runtime worth installing — and even then, one construct at a time.
Start with the breakpoints that keep rotting, not with the ones that work:

```bash
npm i @responsivejs/runtime
```

**The burger that is wrong in German.** A hand-picked `@media (max-width: 843px)` breaks when a
link is added or the site is translated. Replace the number with the measurement:

```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
```
```css
.site-nav[data-wrapped]         { visibility: hidden; height: 0; overflow: hidden; }
.site-nav[data-wrapped] ~ .burger { display: block; }
```

Your CSS keeps owning the appearance; JS only states the fact. And delete the media query —
leaving both means two sources of truth.

**The spacing ladder with three visible jumps.** Three rules become one declaration that
compiles to a `clamp()` and ships as CSS:

```typescript
r$('.card', { padding: r$.fluid(12, 36) });
```

**A component that must answer to its container**, not the window — say how wide that container
gets, which is required and not optional:

```typescript
const panel = { container: true, from: 240, to: 820 };
r$('.card', { fontSize: r$.fluid(15, 26, panel) });
```

Re-run `verify` after each replacement. The contract you pinned in step 2 is now doing the job
it was written for.

## Step 5 — Let the constructs write the rules

Once the page runs the runtime, `init` reads more than the page:

```bash
npx @responsivejs/cli init https://your-site.com -o site.contract.json
```

Every fluid value you declared becomes a `monotonic` + `continuous` rule and a baseline: what
you *declared* becomes what CI *verifies*. Anything not yet expressible as a rule is printed,
never dropped silently.

## What not to do

- **Do not convert every media query.** Most of them are fine. The ones worth replacing are the
  ones that encode a guess about content — how many links fit, whether the text was cut.
- **Do not gate on a contract you have not read.** A generated file is a starting point.
- **Do not chase the aesthetic score.** It is a heuristic, off by default, and no substitute for
  the measurements.

→ [Troubleshooting](troubleshooting) when something does not behave · [Why r$](why) when
someone asks you to justify it.


---

<!-- https://responsivejs.com/docs/tutorial -->

# Tutorial — from empty page to validated, fluid landing

Build a real page with every core construct, one step at a time. Each step: what you're about
to gain, the code, what actually happened, and a checkpoint you can see. At the end you'll
have written the [landing example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing) yourself — *and* pinned it with a
contract so it can never silently regress.

Time: ~30 minutes. Prereqs: Node ≥ 20.19, any bundler (we use vite).

```bash
npm create vite@latest fluid-landing -- --template vanilla-ts
cd fluid-landing && npm i @responsivejs/runtime
```

The page we'll build: a header with logo + nav + (hidden) burger button, a hero, a row of
three cards, a sidebar. Plain HTML — grab the markup from the
[example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing/index.html) or write your own with the same class names.

---

## Step 1 — Kill your breakpoints for sizes: fluid tokens

**What you gain:** spacing and type that scale smoothly with the viewport — no `@media`
ladder, no magic numbers, zero runtime JavaScript for the linear cases.

```typescript
// main.ts
import { r$ } from '@responsivejs/runtime';

r$.tokens({
    '--space-s': r$.fluid(8, 12),
    '--space-m': r$.fluid(16, 24),
    '--space-l': r$.fluid(32, 56),
    '--font-body': r$.fluid(15, 18),
    '--font-hero': r$.fluid(28, 64, { curve: 'exponential' }),
});
```

```css
body    { font-size: var(--font-body); }
.hero h1 { font-size: var(--font-hero); }
.card   { padding: var(--space-m); }
main    { gap: var(--space-l); }
```

**What happened:** every *linear* token compiled to a static `clamp()` on `:root` — open
devtools, look at `<head>`: there's a `<style data-responsivejs>` with
`--space-m: clamp(16px, calc(14.4px + 0.5vw), 24px)`. The browser does all the work. Only
`--font-hero` is JS-maintained, because CSS can't express an exponential curve — that's the
CSS-first contract: **JS only where CSS can't**.

**Checkpoint:** resize the window. Type and spacing flow. There is not a single breakpoint in
what you wrote.

---

## Step 2 — Breakpoints your compiler checks

**What you gain:** where you DO want discrete switches (layout changes regime), the names are
typed — a typo is a compile error, not a production bug.

```typescript
const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1280 } as const);

r$('.cards', {
    gridTemplateColumns: bp.below('tablet', '1fr', 'repeat(3, 1fr)'),
});
```

**What happened:** `as const` lets TypeScript learn your names — try `bp.below('moble', …)`
and watch it fail at compile time. The switch itself emitted a static `@media` block (check
the injected stylesheet again). And `r$.breakpoints` also configured the global domain, so
your Step-1 tokens now span 320→1280.

**Checkpoint:** the cards go 3-up above 768px, stack below it — via CSS the browser runs.

---

## Step 3 — The burger that can't go stale

**What you gain:** the burger appears exactly when the links stop fitting — add a link,
rename one, translate to German: still correct. This is the construct CSS doesn't have.

```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
```

```css
.site-nav[data-wrapped] { visibility: hidden; height: 0; overflow: hidden; }
.site-nav[data-wrapped] ~ .menu-button { display: block; }
```

**What happened:** `whenWraps` *measures* — "does any child start below the first row?" —
and `geometry()` keeps the answer on the DOM as `data-wrapped`, re-measuring on element and
viewport resize. Your CSS styles the fact. Watch it live: keep devtools on the `<nav>` and
drag the window; the attribute appears at exactly the width where the sixth link would fall
to a second row.

**The one rule** (memorize this one): never `display: none` what a predicate measures —
zeroed child rects would flip the state back and it would oscillate. Collapse *keeping
layout*, as above.

**Checkpoint:** narrow → burger. Wide → links. No number anywhere.

---

## Step 4 — Header effects only while actually pinned

**What you gain:** the sticky-header shadow that CSS can't do (there's no `:stuck` selector)
without the IntersectionObserver-sentinel hack.

```typescript
r$.geometry('.site-header', { stuck: r$.whenStuck() });
```

```css
.site-header { position: sticky; top: 0; }
.site-header[data-stuck] { box-shadow: 0 2px 12px rgb(0 0 0 / 0.12); }
```

**Checkpoint:** scroll down → shadow. Back to top → gone.

---

## Step 5 — Relations CSS can't declare

**What you gain:** cross-element dependencies — the class of layout problems you currently
solve with resize listeners and manual measurement (or don't solve at all).

```typescript
// Equal heading heights across the three cards (different parents — grid can't reach):
r$.sync('.card h3', 'height');

// The tagline's type follows the SIDEBAR's width (container queries only see ancestors):
r$('.hero .tagline', {
    fontSize: r$.fluid(14, 18, { domain: r$.fromElement('.sidebar'), from: 200, to: 400 }),
});
```

**What happened:** `sync` measures natural heights and applies the max, re-syncing on resize.
`fromElement` swaps the fluid value's *domain*: instead of the viewport, it reads the
sidebar's width signal (one shared ResizeObserver under the hood).

**Checkpoint:** give one card a longer title — all three headings match. Resize so the
sidebar changes width — the tagline follows *it*, not the window.

---

## Step 6 — Point the oracle at it

**What you gain:** measured proof, not visual gut-check. r$'s other half re-measures your
page at many widths and judges it — overflow, touch targets, contrast, continuity.

```bash
npx @responsivejs/cli analyze http://localhost:5173 -w 320,768,1280
```

(No Playwright in this project? With [agent-browser](https://github.com/vercel-labs/agent-browser)
installed globally, add `-d agent-browser` — the audit needs nothing installed here at all.
It also means you can point the same command at any LIVE url, not just localhost.)

Exit `0` = pass, `1` = violations, each with the exact element, width, measured numbers, and
— where honest — a machine-applicable fix. And because your page runs the runtime, the report
carries **provenance**: each violation on an element a construct controls names that
construct and its call site. `-f json` gives the whole thing machine-readable.

**Checkpoint:** break something on purpose — set `.card { width: 480px }` — and re-run:
`noOverflow @320px .card[0] — right=496 > viewport=320`, with the owning construct if the
runtime styles it.

---

## Step 7 — Pin it: the contract

**What you gain:** the layout's rules as reviewable JSON that travels with the repo — CI
regression without screenshots, and executable instructions for AI agents.

```jsonc
// landing.contract.json
{
    "name": "landing", "version": 1,
    "viewport": { "widths": [320, 768, 1280] },
    "rules": [
        { "assert": "noOverflow", "description": "nothing bleeds out of the viewport" },
        { "assert": "minSize", "args": { "selector": ".cta", "min": { "height": 44 } },
          "description": "the CTA stays comfortably tappable" }
    ],
    "baselines": [{ "selector": ".hero h1", "prop": "fontSize" }]
}
```

```bash
rjs record landing.contract.json http://localhost:5173   # pins today's hero curve
rjs verify landing.contract.json http://localhost:5173   # 0 = holds; drift exits 1
```

**What happened:** `record` measured the hero's real `fontSize = f(width)` curve and wrote it
into the contract; `verify` re-measures and compares within tolerance. Commit the contract;
wire `rjs verify` into CI; your fluid hero can never silently regress again.

(You also could have started with `rjs init http://localhost:5173 -o landing.contract.json` —
because your page runs r$, its constructs *declare* their curves, and `init` turns those
declarations into rules automatically. Hand-written rules and generated ones mix freely.)

---

## What you built

A page with **zero hand-written breakpoints for sizes**, a nav that adapts by *measurement*,
relations CSS can't express — and a machine-checkable spec proving all of it at every width.
Roughly 25 lines of r$.

Where next: the [pattern catalog](guides/case-studies) covers every construct with the
real-world cases this tutorial didn't need · [the runtime guide](guides/runtime) explains
the machinery · [the design guide](guides/validation) goes deep on the oracle ·
[testing](guides/testing) shows how to verify your own usage.


---

<!-- https://responsivejs.com/docs/why -->

# Why r$ — and when not to

The honest version, because you are going to ask anyway.

## "I can write `clamp()` myself"

You can, and for a heading or two you should. r$ compiles a linear `fluid()` to exactly the
`clamp()` you would have written — same Utopia formula, no runtime cost. The reason to declare
it instead of typing it:

- **It answers to a container, not only the viewport.** `{ container: true, from, to }` emits
  `cqi` and the same card is correct in a sidebar, a modal and a phone.
- **It is one declaration, not a scale copied into thirty files.** `r$.tokens` puts the whole
  system in one place and everything downstream reads `var()`.
- **It is machine-readable.** The declaration publishes what it promises, so the other half of
  r$ can check the browser kept that promise, and a report can name *which line* owns a
  violating element. A hand-written `clamp()` tells no-one anything.

If none of those apply to you, write `clamp()`. We would.

## "CSS has container queries now"

It does, and r$ emits `cqi` because of it — container queries made the CSS-first half better,
not redundant. What they still cannot answer:

- *Do these links fit on one row?* — that depends on the children, not on the container.
- *Was this text actually clipped?* — that depends on the rendered glyphs.
- *Is this sticky header currently pinned?* — there is no `:stuck`.
- *Is element A's width inside 25–40% of element B's, where B is not an ancestor?*

Those are measurements, and measurements are what the JS half exists for. Everything else
stays in CSS on purpose.

## "We already have visual regression testing"

Percy, Chromatic and friends answer a different question: *did this change?* They diff pixels
against an approved baseline, and a human decides. That is valuable and orthogonal.

r$ answers *is this wrong?* — with rules that hold at any width, on a page nobody has ever
approved: nothing overflows, targets clear 24px, contrast clears AA against the background
actually painted, a curve never reverses. No baseline to approve, no human in the loop, and a
new page is covered the day it is written. Where a visual diff says "37 screenshots changed",
r$ says "`.cta` is 40×22 at 320px, the WCAG floor is 24×24, here is the fix".

Use both. They fail on different days.

## "axe already checks accessibility"

axe is excellent and r$ runs it for you when it is installed — `analyze` merges its findings.
What r$ adds is the **width sweep and the geometry**: axe checks the DOM as rendered *right
now*, at whatever width the browser happens to be. Touch targets and contrast are properties
of a rendered layout, and layouts change with width. A button that clears 24px on your laptop
can be 40×22 at 320px, and that is exactly the width nobody tested.

r$ also composites contrast against the background *actually painted* behind an element —
semi-transparent chips over a gradient included — which is where naive checks report a pass
they should not.

## "It is another dependency"

The authoring half is optional: you can adopt r$ **without installing anything**, by pointing
the CLI at a URL and committing the contract it generates. That path adds a devDependency to
CI and nothing to your bundle.

If you do author with it: the runtime is ~15.5 kB gzipped as a standalone bundle, and the
common case — linear fluid values — compiles to CSS and ships **zero JavaScript**. What stays
in JS is only what CSS cannot express.

## When not to use it

- **A one-page site you will not touch again.** The gate has no regressions to catch.
- **You have no CI.** Half the value is an exit code nobody will run.
- **A native app, or anything not rendered by a browser.** The oracle measures a real DOM.
- **You need pixel-perfect visual approval.** That is a visual diff tool's job, not ours.

## Where it earns its place

A design system or component library, where a layout regression is invisible until a customer
finds it. A team with CI discipline and no time for manual width-by-width review. And any
codebase where part of the CSS is written by an agent — an agent cannot look at a screenshot
and tell that it is crooked, but it can read an exit code and a measured number.

→ Convinced enough to try? [Measure a page you already have](getting-started) — no install,
about a minute.


---

<!-- https://responsivejs.com/docs/concepts -->

# Concepts — the model in practice

One idea holds the whole lineage together: **the screen is a parametric Cartesian plane**, and
every layout property is a **function of width** — viewport or container.

```
value = f(width)
```

Everything else is one of three uses of that function:

| Use          | Package                | You provide            | You get                        |
| ------------ | ---------------------- | ---------------------- | ------------------------------ |
| **Author**   | `@responsivejs/runtime`| control points + curve | a reactive value / static CSS  |
| **Measure**  | `@responsivejs/design` | a real page            | curves, violations, scores     |
| **Contract** | `@responsivejs/contract`| expectations          | a verifiable, serializable spec|

## The Curve

`Curve = Map<width, value>` — the shared currency. The **analysis half**
(`@responsivejs/core/curve`) asks questions about measured curves: `isMonotonicUp`, `maxJump`,
`discontinuities`, `valueRange`. The **authoring half** (`@responsivejs/core/interpolate`) goes
the other way: control points + interpolation mode → a callable `f(width)`; `sample(f)` turns it
back into a Curve, closing the loop.

```typescript
import { linear, sample } from '@responsivejs/core/interpolate';
import { isMonotonicUp } from '@responsivejs/core/curve';

const f = linear(16, 32, { min: 320, max: 1920 });
isMonotonicUp(sample(f)); // true — author, sample, verify
```

## The Snapshot model

Measurement produces one shape everywhere, regardless of driver:

- **`ElementSnapshot`** — an element at one width: full `Rect` (with derived `right/bottom/
  center/area`), numeric `styles` (font, paddings, margins, radii, z-index…), string `computed`
  (display, colors, overflow…).
- **`ViewportSnapshot`** — all matched elements + parent/child relations at one width.
- **`SnapshotStore`** — snapshots across all measured widths. Query it with `StoreQuery`
  (`at(width)`, `curve(selector, prop)`).

The store is the seam of the whole system: constraints, scores, `analyze()`, and
`verifyContract()` all consume a `SnapshotStore` and don't care where it came from.

## MeasurementSource — drivers are plugins

A driver only needs to set a viewport, measure, and (optionally) evaluate a JS string:

```
browser-native  (zero-driver: the collector runs in-page)
Playwright      (CI — PlaywrightSource)
CDP             (any {send} client — CdpSource; agent-browser, chrome-remote-interface)
```

One in-page collector (`collectPage`) is injected everywhere via `Function.prototype.toString()`,
so all drivers measure identically. The `evaluate` seam is also how axe is injected — a11y works
on every driver, not just Playwright.

## The oracle

`analyze()` merges four judgments into one machine-readable `UnifiedReport`:

1. **Geometry/responsive constraints** — ~27 checks (`noOverflow`, `monotonic`, `touchTarget`…),
   each with a structured `fix` where honest.
2. **Deterministic WCAG contrast** — computed from measured colors (axe's `color-contrast` is
   deliberately disabled: it false-positives on gradients/translucency).
3. **axe** — the rest of WCAG A/AA, when `axe-core` is installed.
4. **Aesthetic score** — 17 metrics (Ngo/Teo/Byrne 2003 + Birkhoff 1933): balance, symmetry,
   rhythm, density, unity…

Severity semantics: `pass` fails only on `error`; `clean` demands zero violations of any kind.

## CSS-first (the authoring rule)

Where CSS can express the function, the runtime **emits CSS and gets out of the way**:

| Value                              | Output                                        |
| ---------------------------------- | --------------------------------------------- |
| `fluid(16, 32)` (linear)           | `clamp(16px, calc(12.8px + 1vw), 32px)`       |
| `fluid([8, 16, 24])`               | per-segment clamps in `@media` blocks         |
| `breakpoint.below/above/match`     | `@media (min-width: …)` blocks                |
| `fluid(16, 32, { container: true, from: 240, to: 820 })` | `clamp(…, … cqi, …)`                        |
| non-linear, colors, strings, lambdas | JavaScript (signals + one rAF write/frame)  |

JavaScript is the fallback, never the default.

## Contracts

A contract freezes intent into data: rules (constraint + args + width range + severity +
authored description), score thresholds, and recorded baselines (`curve` per selector/prop with
tolerance). The registry of 27 constraints is the single source of truth for the TS types, the
validator, the published JSON Schema, and the dispatch onto the engine — a sync test keeps it
honest. Design-system profiles (`material-design-3`, `apple-hig`, …) are rule generators: a
profile embedded in a contract expands to `ds.*` rules at verify time.

## Reactivity (runtime internals)

A minimal internal signal engine, shaped on TC39 Signals (`{get}` / `{get,set}`): pull-based lazy
computeds, equality-gated writes, effects deduped per microtask, and **disposal that removes
every graph edge** — no listener outlives its consumer. One resize listener, one shared
ResizeObserver, refcounted matchMedia — the width hubs are singletons, everything downstream is
derived.


---

<!-- https://responsivejs.com/docs/troubleshooting -->

# Troubleshooting — by symptom

Start from what you are seeing, not from what you think is broken. Every entry names the cause
and the fix; most of these were bugs we shipped ourselves first.

## Authoring

### The value never changes — "the library does nothing"

Almost always a **container-bound value whose range is the viewport's**. `{ container: true }`
changes what is measured, not the range it is measured over, so a card living between 240px and
820px inside a `[320, 1440]` project walked a fifth of its curve. As of `1.0.0-alpha.0` this
is refused at construction:

```
r$: fluid() is bound to its container but never says how wide that container gets,
    so it would interpolate over the viewport breakpoints instead.
    Declare the range: { container: true, from: <narrowest px>, to: <widest px> }
```

Fix: `r$.fluid(15, 26, { container: true, from: 240, to: 820 })`.

If the value is *not* container-bound and still looks frozen, check that the viewport is inside
`[from, to]` — outside the domain a fluid value is clamped, which is correct and looks static.

### An attribute toggles forever, the layout flickers

You are **measuring the element you restyle**. The predicate sets `data-x`, your CSS changes
that element's size, the measurement flips back, forever. Two honest ways out:

- **Collapse keeping layout**: `visibility: hidden; height: 0; overflow: hidden` — never
  `display: none` on what a predicate measures.
- **Measure a probe**: keep a hidden element with the natural dimensions, never restyled, and
  measure that. The table-to-cards demo on the site does exactly this.

Corollary that bites in components: styling the measured element's *children* counts too.
Making pills `flex: 1 1 100%` when their row wraps means they will wrap forever and never come
back — a latch, not an oscillation, and harder to spot. Style something the measurement does
not depend on (`:has()` is useful here).

### A predicate is never true

- `whenWraps` needs **at least two children**; with one it is always `false` by definition.
- `whenTruncated` needs an axis that is actually clipped — `overflow: hidden` or `clip` plus
  content that exceeds it. Without the clipping there is nothing to detect.
- Anything on a `display: none` element measures a zero box and never fires.
- `whenStuck` needs `position: sticky` and a `top`/`bottom` offset to be pinned against.

### Styles vanish after a re-render

The construct was bound to elements that no longer exist. In a component, group the handles and
dispose them with the component:

```typescript
const s = r$.scope();
s.add(r$('.card', { padding: r$.fluid(12, 28) }));
onUnmount(() => s.dispose());
```

For a selector that must keep matching elements as they come and go, use `r$.observe(selector,
map)` — it injects the static half once and manages the JS half per element.

### Server-rendered values are wrong until hydration

The CSS-first half is fully server-renderable — `r$.static(selector, map)` gives you the
stylesheet. The JS half resolves at `config.ssrWidth` until the first client effect, so if a
value matters above the fold, keep it linear so it compiles to `clamp()` and never needs JS.

## The CLI

### "no driver available"

```bash
npx @responsivejs/cli doctor
```

One line per check — Node version, Playwright and its Chromium, agent-browser on `PATH` — with
the exact install command for anything missing, and which driver `auto` will pick. Exit `0`
means at least one driver is usable.

### It passed, but the count says 794/799

Those five are **warnings, not failures**. `pass` means zero *errors*; warnings are things
worth a look that do not break the build (content that overflows inside a scroll container, for
instance). Use `--strict` to fail on them too.

### The contract fails after a design change you meant to make

That is the baseline doing its job: a curve moved. If the change is intended, re-pin it and
commit the diff —

```bash
npx @responsivejs/cli record site.contract.json https://your-site.com
```

— so the new curve is reviewed rather than silently accepted. Do not delete the baseline.

### A rule reports nothing at all

Check the selector matches: a contract whose sweep found no elements would "pass" while
measuring nothing, so r$ fails loudly instead (`a run that performed zero checks`). In
component-scoped stylesheets — CSS modules, Tailwind hashes — prefer stable hooks
(`data-testid`, roles, landmarks) over generated class names.

### The page clearly scrolls sideways but nothing is reported

Fixed in `1.0.0-alpha.0`: the check now compares the document's own horizontal reach against
the viewport, which catches content overflowing *inside* a box whose rect looks fine. If you
are on an earlier build, upgrade.

## Verification results you disagree with

### A contrast violation on something invisible

Elements that are present but not visible in the resting state — `sr-only` clips, `opacity: 0`,
1×1 absolutes — are excluded from contrast and touch-target checks. If you see one reported,
the element is probably visible in a way you did not intend; check it in the browser first.

### A touch-target violation on a link inside a paragraph

WCAG 2.5.8 exempts links flowing inline in prose, and so do we. If one is still reported, the
link is not inline in text — it is a block-level element that happens to be short.

### A contrast pass you do not believe

Contrast is composited against the background **actually painted** behind the element, walking
up through semi-transparent layers. That is deliberately stricter than comparing against the
declared `background-color`, and it is where naive checks report a pass they should not.

## Tests

### Geometry assertions fail in unit tests

happy-dom and jsdom have no layout: every rect is zero, so `whenWraps` and friends cannot work
there. Unit-test the declarations (what the style map contains, what the stylesheet emits) and
put anything that needs real layout in a browser test. See the
[testing guide](guides/testing).

---

Still stuck? Open an issue with the output of `npx @responsivejs/cli doctor` and, if it is a
measurement you disagree with, the JSON report (`-f json`) — it carries the measured numbers,
so the disagreement is about facts rather than impressions.


---

<!-- https://responsivejs.com/docs/index -->

# ResponsiveJS documentation

One page per question — start from what you're trying to do.

| Your question | The page |
| --- | --- |
| **I have a site — is it right?** | **[Getting started](getting-started)** — one command, nothing installed, every width judged |
| **I have a site and want to keep it right** | **[Adopting r$](adopting)** — measure → pin a contract → gate it in CI → only then write constructs |
| Why this and not `clamp()` / Percy / axe? | [Why r$](why) — the honest comparison, and when not to use it |
| Something does not behave | [Troubleshooting](troubleshooting) — by symptom |
| **Teach me — I'll build along** | **[The tutorial](tutorial)** — empty page → fluid, measured, contract-pinned landing in 7 steps (~30 min) |
| How does the model work? | [Concepts](concepts) — `value = f(width)`, snapshots, the oracle, CSS-first |
| **How do I author responsive behavior in JS/TS?** | **[The runtime guide](guides/runtime)** — `r$.`: every construct's purpose, gradual examples, customizing & debugging |
| What's the pattern for MY problem? | [The pattern catalog](guides/case-studies) — every construct on a real problem, organized by what you're building; three unpacked end to end |
| **How do I validate/score a page?** | **[The design guide](guides/validation)** — `r$(page)`: measure → model → judge, `analyze()`, contracts, cutting false positives |
| How do I test all of this? | [Testing responsive behavior](guides/testing) — what's unit-testable vs what needs a browser, patterns and traps |
| How do I wire it into CI? | [CI guide](guides/ci) — pipelines, SARIF, baselines strategy |
| What's the exact signature of X? | API reference: [runtime](api/runtime) · [design](api/design) · [contract](api/contract) · [cli](api/cli) · [core](api/core) · [adapters](api/adapters) |
| How do I use it in React / Vue / Angular? | [Adapters reference](api/adapters) — the lifecycle, per framework |
| I have no build step (CMS, plain HTML) | [`runtime/global`](api/runtime#no-build-step) — one `<script>`, `window.r$` |
| A live page using everything | [Fluid landing example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing) — run it, resize it, read its tutorial |
| The oracle inside DevTools | [The r$ devtool](https://github.com/AleSaiani/ResponsiveJS/blob/main/packages/devtool) — sweep, curve inspector, score HUD, contract recorder (load unpacked) |

**For AI agents** (compact, exact I/O — different documents on purpose):

- [Validation reference](agents/validation-reference) — commands, exit codes, report JSON
  shapes, the 27 constraints, contract skeleton, the fix loop
- [Authoring reference](agents/authoring-reference) — invariants, signatures, construct
  chooser, the minimal correct pattern
- [r$ for AI agents](guides/agents) — the narrative guide: drivers (CDP/eval/agent-browser),
  contracts as instructions

The aesthetic score is grounded in Ngo, Teo & Byrne (2003), *Modelling interface aesthetics*,
and Birkhoff (1933), *Aesthetic Measure* — see [api/core.md](api/core#aesthetics--the-17-metric-score).


---

<!-- https://responsivejs.com/docs/guides/runtime -->

# Using r$ in JavaScript / TypeScript — the runtime guide

This is the guide to `@responsivejs/runtime`: what each API is *for*, how the pieces fit,
and worked examples that grow from one line to a real page. Prefer building along?
The [tutorial](https://github.com/AleSaiani/ResponsiveJS/blob/main/tutorial.md) walks the same ground hands-on. The
[API reference](../api/runtime) has every exact signature; the
[pattern catalog](case-studies) covers every construct on a real problem.

```bash
npm i @responsivejs/runtime
```

```typescript
import { r$ } from '@responsivejs/runtime';
```

Everything in this guide hangs off that one import. Type `r$.` in your editor and the whole
surface autocompletes — values, geometry, tokens, breakpoints. (Named imports of the same
functions exist too — `import { fluid, geometry } from '@responsivejs/runtime'` — use them
when you want maximum tree-shaking; they are literally the same objects.)

## The mental model

r$ treats the screen as a **parametric plane**: every style property is a *function of width*
— `fontSize = f(viewportWidth)`. Instead of enumerating breakpoints ("at 768px switch to
this"), you describe the function, and r$ decides the cheapest correct way to run it:

- if the function is **linear**, it becomes a static CSS `clamp()` — shipped as a stylesheet,
  **zero JavaScript at runtime**;
- if CSS can't express it (curves, geometry, values measured from other elements), r$ drives
  it from one shared, batched reactive graph.

That decision is the **CSS-first contract**, and it's automatic. You write intent; the split
is r$'s job.

## Your first fluid value

```typescript
r$('.hero h1', { fontSize: r$.fluid(24, 48) });
```

What just happened, precisely:

1. `r$.fluid(24, 48)` created a **ResponsiveValue** — a pure description meaning "24px at the
   narrowest breakpoint, 48px at the widest, interpolated linearly in between".
2. `r$(target, map)` applied it. Because this value is linear and the target is a selector,
   r$ *did not* attach a resize listener — it computed the Utopia formula and injected

   ```css
   .hero h1 { font-size: clamp(24px, calc(15.2px + 2.75vw), 48px); }
   ```

   as a `<style data-responsivejs>` tag. Resize all you want: the browser does the work.
3. The call returned a **handle**. Keep it if this code can unmount:

   ```typescript
   const hero = r$('.hero h1', { fontSize: r$.fluid(24, 48) });
   // …later, e.g. on route change:
   hero.dispose();   // removes what it did AND restores pre-existing inline values
   ```

Every r$ construct follows this same shape: *describe → apply → get a disposable handle*.

### Where do 24 and 48 apply? The domain

By default the function's domain is the configured breakpoint range (320→1920 out of the box).
Three ways to control it:

```typescript
r$.fluid(24, 48);                        // over the configured range
r$.fluid(24, 48, { from: 480, to: 1200 }); // explicit domain for this value
r$.configure({ breakpoints: [360, 768, 1440] }); // change the global range (r$.config() reads it back)
```

Below the domain the value clamps to `min`, above it to `max` — a fluid value never
extrapolates.

### Units and other options

The third argument is either a unit string or an options object:

```typescript
r$.fluid(1.5, 3, 'rem');                          // unit
r$.fluid(16, 40, { curve: 'exponential' });       // growth shape — see “Curves”
r$.fluid(16, 24, { container: true, from: 240, to: 820 });   // driven by the nearest container
// from/to are REQUIRED here: they are the container's range, and without them the
// value would interpolate over the viewport breakpoints instead. r$ refuses to build it.
```

`fluid` is polymorphic beyond numbers: `r$.fluid('#666', '#111')` interpolates colors
perceptually (OKLab), `r$.fluid([12, 16, 24])` places one value per configured breakpoint,
`r$.fluid('scale(0.9)', 'scale(1.1)')` interpolates structured strings token by token.

## Breakpoints with names your compiler checks

Magic numbers scattered through code rot. Define them once — `as const` matters, it's what
lets TypeScript learn your names:

```typescript
const bp = r$.breakpoints({ mobile: 360, tablet: 768, desktop: 1280 } as const);
```

That call does two things: configures the global runtime (so `fluid` domains and array values
use your range), and returns an API **typed on your names**:

```typescript
r$('.cards', {
    gridTemplateColumns: bp.below('tablet', '1fr', 'repeat(3, 1fr)'),
});

bp.width('tablet');        // 768
bp.between('mobile', 'desktop', …);
bp.match({ mobile: 14, desktop: 18 });   // largest matching name wins

// bp.below('moble', …)   ← this is a COMPILE error, not a runtime surprise
```

For JS logic (not styles), `bp.matches('tablet')` returns a reactive signal you can read and
subscribe to, with a `dispose` that releases the underlying media-query listener.

Where possible these emit static `@media` blocks — `bp.below('tablet', 'none', 'flex')` costs
zero JavaScript.

## Tokens: the recommended backbone

Styling elements one by one is fine for a hero. For a *system* — spacing scale, type scale,
radii — write the scale once as **custom properties** and let CSS consume it:

```typescript
const theme = r$.tokens({
    '--space-s': r$.fluid(8, 12),
    '--space-m': r$.fluid(16, 24),
    '--font-body': r$.fluid(15, 18),
    '--font-hero': r$.fluid(28, 64, { curve: 'exponential' }),
});
```

```css
.card  { padding: var(--space-m); }
h1     { font-size: var(--font-hero); }
```

Why this is usually better than styling elements directly:

- **One write point.** Linear tokens compile to a single `clamp()` stylesheet on `:root`;
  non-linear ones update one variable from one effect. N elements consume them for free.
- **Inspectable.** Open devtools, look at `:root`, see your whole scale and its current values.
- **Themable.** A theme is just another set of the same variables.
- **Portable.** `theme.css` is the stylesheet (ship it from the server for SSR);
  `theme.toDTCG()` exports the scale as Design Tokens Community Group JSON — with the
  responsive curve sampled per breakpoint under `$extensions` — for Figma/Style Dictionary
  pipelines.

`theme.dynamic` lists which names stayed JS-driven, so you always know what you're paying for.

## Geometry: state CSS can't see

CSS has no selector for *"my children wrapped"*, *"this sticky header is pinned"*, *"this
text is truncated"*. r$'s answer is a family of **predicates** — pure measurements — wired by
`geometry()` into data-attributes your stylesheet reacts to (**JS detects, CSS styles**):

```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
// → <nav data-wrapped> while the links sit on >1 row; CSS does the burger.
```

| Predicate | The fact it maintains | Typical use |
| --- | --- | --- |
| `r$.whenWraps()` | children flow on >1 row | burger menus, toolbar overflow |
| `r$.whenOverflows('x'\|'y'\|'both')` | content exceeds the box | "scroll for more" affordances |
| `r$.whenTruncated()` | text is clipped (ellipsis/clamp active) | show "more" only when needed |
| `r$.whenStuck()` | a sticky element is pinned right now | header shadow, condensed toolbar |
| `r$.linesOf()` | number of rendered text lines | `data-lines="2"` styling |
| `r$.whenCollides(other)` | two elements' boxes overlap | floating UI avoiding content |

Mechanics in brief: boolean facts toggle attribute presence, numeric ones write the value
(`data-lines="3"`); re-measurement is automatic (shared ResizeObserver, viewport resize,
scroll for the scroll-sensitive two); every `measure(el)` is pure and callable one-shot;
handles expose `measure()/pause()/resume()/dispose()`; SSR-inert.

**The one rule**: never `display: none` what a predicate measures — collapse keeping layout
(`visibility: hidden; height: 0; overflow: hidden`), or the state oscillates.

This is taught hands-on in [tutorial steps 3–4](https://github.com/AleSaiani/ResponsiveJS/blob/main/tutorial.md#step-3--the-burger-that-cant-go-stale),
unpacked completely (DOM before/after, the measurement, the test) in the
[deep dives](case-studies#deep-dives), and every predicate has a pattern in the
[catalog](case-studies).

## Cross-element relations

Container queries look **up** the tree; nothing in CSS lets element A react to element B's
size. Three constructs cover the useful cases:

```typescript
// 1. A value whose domain is ANOTHER element's width:
r$('.main-content', {
    fontSize: r$.fluid(14, 18, { domain: r$.fromElement('.sidebar'), from: 200, to: 400 }),
});
// reads: 14px when the sidebar is 200px wide, 18px when it's 400px.

// 2. Equal heights across different parents (where grid/subgrid can't reach):
const heads = r$.sync('.card h3', 'height');   // max natural height wins, re-synced on resize
heads.measure();                               // call after dynamic content changes

// 3. A layout invariant, enforced:
r$.ratio('.sidebar', '.main', { min: 0.2, max: 0.33 });
```

`ratio` deserves a note: it's the same `proportion` constraint the validation oracle *asserts*
in CI — here promoted to runtime *enforcement*. Inside the bounds the layout flows free (the
constraint is removed); outside them the first element's width is pinned to the boundary.

## Responsive or adaptive? Choosing the mechanism

Every responsive decision is one of three kinds — and r$ has one mechanism per kind:

| The property/behavior is… | Mechanism | Examples |
| --- | --- | --- |
| **Continuous** — it can meaningfully take every in-between value | `r$.fluid` (responsive) | sizes, spacing, type, colors, shadows, radii |
| **Discrete by width** — the layout changes *structure* at a threshold | `bp.*` / `whenInRange` / `when` (adaptive) | display, grid templates, flex-direction, component variants |
| **Discrete by geometry** — the trigger is a measured fact, not a width | `r$.geometry` (adaptive) | nav wrapped, header stuck, text truncated |

The test: *does an in-between value mean anything?* A font can be 16.37px — fluid. A sidebar
can't be 37% visible — that's a switch. And if the right moment for the switch is "when it no
longer fits" rather than "at 768px", the trigger is geometric — use a predicate, not a
breakpoint.

### Adaptive by width, concretely

```typescript
const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1280 } as const);

r$('.sidebar', {
    display: bp.below('tablet', 'none', 'block'),          // hide on mobile — static @media
});
r$('.filters', {
    flexDirection: bp.below('tablet', 'column', 'row'),    // stack → row
});
r$('.panel', {
    outline: r$.whenInRange(320, 767, '2px solid red'),    // only inside a range
    padding: r$.when((w) => w > 600 && isCompactMode(), 16, 32),  // arbitrary logic — JS path
});
```

Plain-value branches compile to static `@media`; a `when()` with a lambda stays JS (CSS can't
run your predicate). `bp.below(px, value)` **without** a fallback is max-width-guarded — the
value never leaks above the threshold.

### Mixing the regimes

Branches nest: an adaptive switch can hold fluid values, so each regime stays fluid *inside*
its range —

```typescript
r$('.hero h1', {
    // two regimes, each fluid: tighter curve on mobile, wider on desktop
    fontSize: bp.below('tablet', r$.fluid(24, 32, { to: 767 }), r$.fluid(36, 64, { from: 768 })),
});
```

(Nested `ResponsiveValue` branches resolve correctly and take the JS path.) The complete
per-property examples — backgrounds, shadows, transforms — live in the
[catalog's styling section](case-studies#styling-any-property).

## Lifecycle, testing, SSR

**Handles.** Everything returns one. `dispose()` always un-does exactly what the construct
did — including restoring inline values that existed before it (an inline `font-size` you
had set survives a handle's lifetime). Handles are isolated: two on the same selector own
separate stylesheets and dispose independently. In component frameworks, tie it to unmount:

```typescript
useEffect(() => {
    const h = r$.geometry(ref.current, { wrapped: r$.whenWraps });
    return () => h.dispose();
}, []);
```

**A component usually creates several constructs.** Group them instead of juggling handles:

```typescript
const s = r$.scope();
s.add(r$('.card', { padding: r$.fluid(12, 24) }));
s.add(r$.geometry('.card', { wrapped: r$.whenWraps }));
s.add(r$.sync('.card h3', 'height'));
// …later, one call releases all three, in reverse order:
s.dispose();
```

**Single-page apps: elements come and go.** `r$('.card', …)` binds to the elements that exist
at call time. When a router or a list re-renders them, bind the *selector* instead:

```typescript
const cards = r$.observe('.card', { padding: r$.fluid(12, 24) });
// new .card nodes are picked up automatically; removed ones are released
```

The static half is injected once — CSS already applies to elements that don't exist yet — so
`observe()` only wires the JS half per element. Framework adapters use the same mechanism.

**Testing.** Style writes are batched to one rAF flush per frame; in tests call `r$.flush()`
to drain them synchronously after triggering a resize.

**SSR.** No construct touches `window` at import time, and the CSS-first half is fully
server-renderable. Three ways in, from most to least surgical: `handle.css` (what that one
construct compiled), `r$.tokens(...).css` (the token stylesheet), or `r$.renderStatic()` —
every emission so far, ready to inline into `<head>` so the page is correct before any JS
runs. `r$.static(selector, map)` is the strict variant: it returns `{ css, dispose }` and
throws — on purpose — if the map contains anything that would silently need JS. Geometry
attributes appear on hydration. Under a strict CSP, `r$.configure({ nonce })` puts the nonce
on every injected `<style>`.

## Customizing, extending, seeing inside

r$'s constructs are deliberately small objects — which means every one of them can be
customized, extended, or interrogated.

**Write your own predicate.** A geometry predicate is just `{ measure(el) }` — a function
that answers a question about an element (plus `scroll: true` if scrolling changes the
answer). If r$ doesn't ship the fact you need, define it:

```typescript
const whenPortrait = {
    measure: (el: Element) => {
        const r = el.getBoundingClientRect();
        return r.height > r.width;
    },
};

r$.geometry('.media-card', { portrait: whenPortrait });
// → <div class="media-card" data-portrait> … CSS takes it from there
```

Your predicate gets the exact same re-measurement machinery as the built-ins.

**Rename the attributes.** `r$.geometry(target, states, { prefix: 'data-r-' })` if `data-*`
names could collide with something else in your app.

**React in JS, not just CSS.** Data-attributes are for stylesheets; when *logic* needs the
fact, drop one level to the signal layer the constructs are built on:

```typescript
import { effect, elementSize, viewportWidth, subscribe } from '@responsivejs/runtime';

const { signal: size, dispose } = elementSize(document.querySelector('.sidebar')!);
const stop = effect(() => {
    if (size.get().width < 250) collapseSidebarInYourStateStore();
});

const bp = r$.breakpoints({ tablet: 768 } as const);
const tablet = bp.matches('tablet');
subscribe(tablet.signal, (isTablet) => reloadLighterImages(isTablet));
```

Same sources, same refcounting — a predicate and your effect share one ResizeObserver.

**Escape hatches at every level.** A value that no combinator expresses is one function away:
`r$.custom((width) => myFormula(width))` participates in maps like any fluid. A one-shot
answer without any wiring: `r$.whenWraps().measure(el)`. A forced re-check after you mutated
content: `handle.measure()`.

**Provenance: the closed loop.** Every construct registers itself in a live manifest —
`r$.manifest()` (also `window.__rjs_manifest`) lists what controls the page: construct kind,
target, behavior, best-effort call site, and the **serialized declaration itself** (a
`fluid(16, 32, { curve: 'exponential' })` ships as
`{value:'fluid', min:16, max:32, curve:'exponential'}`). When the validation side measures a
page running the runtime, it ships the manifest with the measurements and annotates
violations with their `owner` — so a report doesn't just say ".nav overflows at 320px", it
says *which construct declared at src/navigation.ts:18 owns .nav*, and when the construct
controls the violating property the fix arrives as a **runtime-patch** (current declaration +
the value that would satisfy the constraint) — an agent patches the construct, not the CSS.
The declarations also power `rjs init <url>`: it generates a design contract *from* your
constructs (fluid → monotonic + continuous + baseline, ratio → proportion, your breakpoints →
the sweep widths) — a regression net you didn't have to write.

**See what r$ is doing.** Three inspection points, all in plain devtools:

- `r$.debug(true)` — logs every resolved value as it's applied (`[r$] .hero font-size @
  400px → 27.5`).
- The injected stylesheets are ordinary `<style data-responsivejs>` tags in `<head>` — open
  one and read the exact `clamp()`/`@media` CSS your values compiled to.
- Tokens live on `:root` — the Styles panel shows every variable and its current value; the
  Elements panel shows geometry's `data-*` attributes appearing and leaving live as you
  resize.

## What it costs

One passive resize listener, one shared ResizeObserver, one capture-phase scroll listener —
total, not per construct; each is refcounted and removed when the last consumer disposes.
Style writes coalesce to one flush per frame. The reactive graph is pull-based (reading a
signal is a property access), and the whole runtime is ~11 kB gzipped with zero dependencies.

## Where next

- [The pattern catalog](case-studies) — every construct on a real problem, three of them
  unpacked end to end (DOM before/after, the measurement, the test).
- [Testing guide](testing) — unit-test the pure half, browser-test the geometric half.
- [Landing example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing) — all of the above on one real page, with the
  hack each construct replaces.
- [API reference](../api/runtime) — every signature, including the signal layer
  (`state`/`computed`/`effect`) the constructs are built on.
- Validating what you authored: [the design guide](validation) — the same
  `value = f(width)` model, measured and asserted from outside.


---

<!-- https://responsivejs.com/docs/guides/case-studies -->

# The pattern catalog — every construct, on a real problem

One pattern per real-world problem, organized by what you're building. Each: the problem, the
construct, what it replaces. New here? Do the [tutorial](https://github.com/AleSaiani/ResponsiveJS/blob/main/tutorial.md) first — it builds a
page with the core patterns. Three of the entries below are also
[unpacked end to end](#deep-dives) (DOM before/after, the measurement, the test).

## Navigation & page chrome

### The burger that appears exactly when needed — `whenWraps`

Replaces: the hand-tuned `@media (max-width: 843px)` that rots when a link is added or the
site is translated.

```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
```
```css
.site-nav[data-wrapped] { visibility: hidden; height: 0; overflow: hidden; }
.site-nav[data-wrapped] ~ .menu-button { display: block; }
```

[Full anatomy below](#deep-dive-1--the-burger-menu-whenwraps). Rule: collapse *keeping
layout* — never `display: none` what a predicate measures.

### Toolbar "More…" overflow — `whenOverflows`

Replaces: guessing how many toolbar buttons fit at which width.

```typescript
r$.geometry('.toolbar', { crowded: r$.whenOverflows() });
```
```css
.toolbar { overflow: hidden; }
.toolbar[data-crowded] ~ .more-menu-button { display: inline-flex; }
```

The "More…" button exists exactly while content exceeds the box.

### Header effects only while pinned — `whenStuck`

Replaces: the IntersectionObserver-sentinel hack. `r$.geometry('.site-header', { stuck:
r$.whenStuck() })` → `.site-header[data-stuck] { box-shadow: …; }` — shadow, condensed logo,
blur: anything, only while actually stuck. [Full anatomy below](#deep-dive-2--header-effects-only-while-pinned-whenstuck).

## Content

### "Read more" only when something was cut — `whenTruncated`

Replaces: character-count heuristics that break with fonts, widths, languages.
`r$.geometry('.excerpt', { truncated: r$.whenTruncated() })` →
`.excerpt[data-truncated] + .read-more { display: inline; }`.
[Full anatomy below](#deep-dive-3--read-more-only-when-truncated-whentruncated).

### Layout that reacts to line count — `linesOf`

Replaces: nothing — this wasn't feasible. A heading that centers when it fits on one line,
left-aligns when it wraps:

```typescript
r$.geometry('.card h2', { lines: r$.linesOf() });   // → data-lines="1" | "2" | …
```
```css
.card h2[data-lines='1'] { text-align: center; }
```

### The carousel scroll affordance — `whenOverflows('x')`

Show the "scroll →" hint only while there IS more content:

```typescript
r$.geometry('.chip-row', { scrollable: r$.whenOverflows('x') });
```
```css
.chip-row[data-scrollable]::after { content: '→'; /* fade gradient, arrow, anything */ }
```

## Relations between elements

### Equal heights across unrelated containers — `sync`

Replaces: subgrid (when the DOM allows it) or hand-rolled measure loops with stale-value
bugs. `r$.sync('.card h3', 'height')` — max natural height wins, re-synced on resize,
restored on dispose. Call `handle.measure()` after swapping content dynamically.

### A layout invariant, enforced — `ratio`

Replaces: hoping the CSS holds. `r$.ratio('.sidebar', '.main', { min: 0.2, max: 0.33 })` —
inside the bounds the layout flows free; outside them the sidebar is pinned to the boundary.
This is the validation constraint `proportion` promoted to runtime *enforcement*: author and
verifier speak the same rule.

### A value driven by ANOTHER element — `fromElement`

Replaces: nothing — container queries only see ancestors.

```typescript
r$('.main-content', {
    fontSize: r$.fluid(14, 18, { domain: r$.fromElement('.sidebar'), from: 200, to: 400 }),
});
```

Master-detail panes, editors whose type tracks the preview pane, anything where element A
answers to element B's size.

### Floating UI that yields to content — `whenCollides`

```typescript
r$.geometry('.floating-cta', { overlapping: r$.whenCollides('.footer') });
```
```css
.floating-cta[data-overlapping] { opacity: 0.15; pointer-events: none; }
```

The FAB fades exactly while it covers the footer — measured, not scripted to scroll offsets.

## Fluid values & the design system

### The type scale with character — curves

Linear is free (static `clamp()`); when linear feels flat, shape the growth:

```typescript
r$.tokens({
    '--font-hero': r$.fluid(28, 64, { curve: 'exponential' }),  // restrained on mobile, dramatic on wide
    '--font-body': r$.fluid(15, 18),                            // linear → zero JS
});
```

### Per-breakpoint values without the ladder — `fluid([...])`

`r$.fluid([12, 16, 24, 32])` places one value per configured breakpoint and interpolates the
segments — the multi-stop scale as one expression, still statically compiled where linear.

### Perceptual color transitions — `fluid(color, color)`

`r$.fluid('#1a1a2e', '#4a4a6a')` interpolates in OKLab — no gray dead-zone in the middle
(the classic sRGB-mix artifact). Backgrounds that lighten as the viewport grows, borders that
soften: `color: r$.fluid('#111', '#555')`.

### Themes and design tokens as a pipeline — `tokens` + DTCG

The scale lives in one place, CSS consumes `var()` everywhere, themes are alternative token
sets — and `handle.toDTCG()` exports the whole system (curves sampled per breakpoint) as
Design Tokens Community Group JSON for Figma/Style Dictionary pipelines. `handle.css` is the
SSR stylesheet.

### Container-aware components — `{ container: true }`

`r$.fluid(14, 18, { container: true, from: 240, to: 820 })` binds to the nearest container instead of the
viewport (static output uses `cqi`; the handle configures `container-type` on the parent,
refcounted). The same card component sizes correctly in a sidebar and in the main column.

**`from`/`to` are required here, and that is deliberate.** `container: true` changes *what is
measured*, not the domain the value is interpolated over. Left implicit it would use your
viewport breakpoints, so a card that lives between 240px and 820px inside a `[320, 1440]`
project would walk a fifth of its own curve — and the symptom is "the library does nothing".
r$ refuses to build such a value and tells you what to write:

```ts
const panel = { container: true, from: 240, to: 820 };   // the container's real range

r$('.card', {
    fontSize: r$.fluid(15, 26, panel),
    padding: r$.fluid(10, 30, panel),
});
```

There is no rule of thumb to remember: if a value is bound to a container, `from`/`to` are the
other half of the declaration, and leaving them out is a construction-time error.

## Styling any property

The style map takes **any** CSS property (camelCase), and `fluid` is polymorphic — numbers,
colors, structured strings. These patterns show the range on real problems.

### The hero that sets a mood — background color ramps

Problem: on a phone the hero must be quiet and readable; on a cinema display it can be
atmospheric. Discrete theme swaps at a breakpoint look like a glitch.

```typescript
r$('.hero', {
    backgroundColor: r$.fluid('#16181d', '#1e2340'),   // deepens as space grows
    color: r$.fluid('#e8e8e8', '#ffffff'),
});
```

Interpolation runs in OKLab — no gray dead-zone mid-ramp (the classic sRGB artifact). Any
color property works: `borderColor`, `outlineColor`, `caretColor`.

### Depth that grows with space — fluid shadows

Problem: design systems scale elevation in steps (sm/md/lg) and pick one per breakpoint;
cards jump between flat and floating. Structured-string interpolation makes elevation
continuous — numbers *and* the shadow color interpolate together:

```typescript
r$('.card', {
    boxShadow: r$.fluid('0 1px 3px rgba(0,0,0,0.30)', '0 16px 48px rgba(0,0,0,0.18)'),
    borderRadius: r$.fluid(8, 16),
});
```

Mobile: tight, dark, close to the surface. Desktop: soft, wide, floating. Same works for
`filter: blur(…)`, `textShadow` — any congruent value string.

### Presence without reflow — fluid transforms

Problem: a decorative element should be subtler on small screens, but animating `width`
causes reflow. Transforms are compositor-only:

```typescript
import { combine, scale, rotate } from '@responsivejs/runtime';

r$('.hero-badge', {
    transform: combine([scale(r$.fluid(0.85, 1.15)), rotate(r$.fluid(-2, -6, 'deg'))]),
});
```

### Density as a system — the dashboard ramp

Problem: dashboards need to be dense on laptops and breathable on big monitors — usually
solved by a "compact mode" toggle users must find. Make density a *function of space*
instead, in one place:

```typescript
r$.tokens({
    '--cell-pad': r$.fluid(6, 14),
    '--row-gap': r$.fluid(4, 10),
    '--font-data': r$.fluid(12.5, 15),
});
```

```css
td { padding: var(--cell-pad); font-size: var(--font-data); }
tr { margin-block: var(--row-gap); }
```

Every table, list and card in the app breathes together — and the whole ramp is one token
block you can hand to design as DTCG.

### Structure switching — the adaptive side

When the change is *structural* (an in-between value means nothing), switch discretely —
plain-value branches compile to static `@media`:

```typescript
const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1280 } as const);

r$('.filters', { flexDirection: bp.below('tablet', 'column', 'row') });
r$('.sidebar', { display: bp.below('tablet', 'none', 'block') });
```

And the regimes mix: a switch's branches can hold fluid values, so each regime stays fluid
inside its range. When to flow vs when to switch — and when the trigger should be geometric
rather than a width — is the [responsive-or-adaptive framework](runtime#responsive-or-adaptive-choosing-the-mechanism)
in the guide.

## Lifecycle & environments

### SPA components — keep the handle

Every construct returns a handle; tie it to unmount and everything is undone *and restored*:

```typescript
useEffect(() => {
    const nav = r$.geometry(ref.current!, { wrapped: r$.whenWraps });
    return () => nav.dispose();
}, []);
```

Note: selectors resolve at creation — for elements mounted later, create the construct in the
component that owns them — or let an [adapter](../api/adapters) do it for you
(React, Vue and Angular bindings own the lifecycle), or `r$.scope()` to release a group at once.

### SSR without flashes — static emission

Linear constructs never needed JS: ship `r$.tokens(...).css` / `r$.static(selector, map).css` as
server-rendered CSS; geometry attributes hydrate on the client (constructs are inert without
`window`). The page is correct before a single byte of JS runs.

---

# Deep dives

Three of the patterns above, unpacked completely: the HTML, what the predicate measures, the
exact DOM before/after, why the CSS is shaped that way, and the test.

## Deep dive 1 — The burger menu (`whenWraps`)

### The situation

A header with a logo, six nav links, and a burger button that should appear **only when the
links no longer fit on one line**:

```html
<header class="site-header">
    <span class="logo">r$</span>
    <nav class="site-nav">
        <a href="/model">Model</a>
        <a href="/authoring">Authoring</a>
        <a href="/validation">Validation</a>
        <a href="/contracts">Contracts</a>
        <a href="/agents">Agents</a>
        <a href="/docs">Docs</a>
    </nav>
    <button class="menu-button" hidden aria-label="Menu">☰</button>
</header>
```

The classic solution is `@media (max-width: 843px)` — where 843 is whatever width the links
happened to overflow at the day you wrote it. Add a link, rename one, translate the site to
German, and 843 is silently wrong.

### What `whenWraps` actually does

`whenWraps` is a **measurement**, nothing more: given an element, it reads the rectangles of
its children and answers one question — *does any child start below the first row?*

```
one row (fits):                    two rows (wrapped):
[Model][Authoring]…[Docs]          [Model][Authoring][Validation]
                                   [Contracts][Agents][Docs]
 all tops equal → false             a child's top ≥ first child's bottom → true
```

You can call it yourself, one-shot, no wiring — this is worth trying in a console to demystify
it:

```typescript
r$.whenWraps().measure(document.querySelector('.site-nav'));   // → true | false
```

### What `geometry()` adds

`geometry()` turns that one-shot measurement into a **maintained fact on the DOM**:

```typescript
r$.geometry('.site-nav', { wrapped: r$.whenWraps });
```

From this line on, r$ re-runs the measurement whenever it could change — the nav resizes
(one shared ResizeObserver), the viewport resizes — and mirrors the answer into an attribute.
Concretely, this is the *only* thing it does to your DOM:

```html
<!-- viewport 1200px: the links fit -->
<nav class="site-nav">…</nav>

<!-- viewport 400px: the links wrapped -->
<nav class="site-nav" data-wrapped>…</nav>
```

No styles are touched, no classes added, nothing hidden. The key you chose (`wrapped`)
becomes the attribute name (`data-wrapped`).

### The CSS reacts

Styling is entirely yours, in the stylesheet, keyed on that attribute:

```css
/* collapsed nav: hidden but STILL LAID OUT (see the rule below) */
.site-nav[data-wrapped] {
    visibility: hidden;
    height: 0;
    overflow: hidden;
}
.site-nav[data-wrapped] ~ .menu-button {
    display: block;
}
```

Why `visibility: hidden; height: 0` and **not** `display: none`: the predicate must keep
measuring the nav to know when to un-wrap. `display: none` gives every child a 0×0 rect, so
the measurement would flip back to "not wrapped", the nav would reappear, wrap again — an
oscillation. Collapsing *while keeping layout* makes the state stable. This is the one rule
of geometry; it will fail loudly in front of you the first time you forget it, and now you
know why.

### Seeing it work

Open the page, open devtools on the `<nav>`, and drag the window narrower: at the exact width
where the sixth link would fall to a second row, `data-wrapped` appears and the burger shows.
Drag wider: it disappears. There is no number anywhere in your code.

### Verifying it in a test

```typescript
await page.setViewportSize({ width: 400, height: 800 });
await page.waitForFunction(() => document.querySelector('.site-nav').hasAttribute('data-wrapped'));

await page.setViewportSize({ width: 1400, height: 900 });
await page.waitForFunction(() => !document.querySelector('.site-nav').hasAttribute('data-wrapped'));
```

(Why `waitForFunction` and not a fixed sleep, and why this must be a real browser and not
happy-dom: see [the testing guide](testing).)

---

## Deep dive 2 — Header effects only while pinned (`whenStuck`)

### The situation

A sticky header that should cast a shadow **only while it is actually stuck** to the top —
not at page load, not while the page is at scroll 0.

CSS can make an element sticky (`position: sticky; top: 0`) but has no selector for "is it
currently pinned". The folklore workaround is an IntersectionObserver watching an invisible
1px sentinel element placed above the header — extra DOM, extra code, easy to break.

### What `whenStuck` measures

For a `position: sticky` element, being "stuck" is a geometric fact: the element sits exactly
at its `top` offset while its parent has scrolled past it. `whenStuck` reads both rectangles
and answers that. Because scrolling changes the answer, this predicate re-measures on scroll
too (a single shared, passive scroll listener — you don't manage it).

```typescript
r$.geometry('.site-header', { stuck: r$.whenStuck() });
```

```html
<!-- at scroll 0 -->            <!-- scrolled down -->
<header class="site-header">    <header class="site-header" data-stuck>
```

```css
.site-header[data-stuck] { box-shadow: 0 2px 12px rgb(0 0 0 / 0.12); }
```

Scroll down → shadow. Scroll back to the top → the attribute leaves, the shadow goes. The
same attribute can drive anything: a condensed logo, a background blur, a border.

### Verifying it

```typescript
await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
await page.waitForFunction(() => document.querySelector('.site-header').hasAttribute('data-stuck'));

await page.evaluate(() => window.scrollTo(0, 0));
await page.waitForFunction(() => !document.querySelector('.site-header').hasAttribute('data-stuck'));
```

One trap from our own test suite: make sure the page is tall enough to scroll at the viewport
you chose — at a wide viewport a short page may not scroll at all, and the test waits forever.

---

## Deep dive 3 — "Read more" only when truncated (`whenTruncated`)

### The situation

Card excerpts clamped to three lines, with a "Read more" link — but the link should exist
**only when something was actually cut off**. Rendering it always is noise; guessing by
character count breaks with different fonts, widths, and languages.

### What `whenTruncated` measures

Truncation is, again, geometry: the content's scroll size exceeds the box's client size *on an
axis whose overflow is clipped* (`hidden`/`clip`). That last condition matters — a scrollable
box overflows too, but nothing is lost, so it does not count as truncated.

```typescript
r$.geometry('.excerpt', { truncated: r$.whenTruncated() });
```

```html
<!-- long text, clamped -->                      <!-- short text, fits -->
<p class="excerpt" data-truncated>…</p>          <p class="excerpt">…</p>
```

```css
.excerpt { display: -webkit-box; -webkit-line-clamp: 3; overflow: hidden; }
.excerpt + .read-more { display: none; }
.excerpt[data-truncated] + .read-more { display: inline; }
```

Resize the card, change the font, translate the copy — the link appears exactly when the
third line ends in an ellipsis, because that is what is being *measured*, not assumed.

### After content changes

Geometry re-measures on resize automatically, but if you swap the excerpt's text from JS the
box size may not change even though the truncation state did. Keep the handle and ask for a
re-measure:

```typescript
const excerpts = r$.geometry('.excerpt', { truncated: r$.whenTruncated() });
// …after injecting new text:
excerpts.measure();
```

---

## The shape all three share

1. **A predicate is a measurement** — a pure function you can call once, in a console, to see
   what it sees.
2. **`geometry()` maintains it** — the measurement re-runs when it could change, and the
   answer lives on the element as a `data-*` attribute. That attribute is the entire API
   between JS and CSS.
3. **CSS owns the styling** — your stylesheet decides what the fact *looks like*.
4. **Tests read the attribute** — the same thing your CSS keys on is the thing you assert.

Next: [how to test all of this](testing) · [every predicate's reference](../api/runtime#geometry--state-from-geometry) ·
[the live example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing) that runs case 1 and 2.


---

<!-- https://responsivejs.com/docs/guides/validation -->

# Validating with r$ — the design guide

This is the guide to `@responsivejs/design`: what the validation side of r$ is for, how
measuring works, and worked examples that grow from five lines to contracts in CI. The
[API reference](../api/design) has every exact signature. Authoring is the other half:
[the runtime guide](runtime).

```bash
npm i -D @responsivejs/design @playwright/test   # Playwright is the default driver
```

## The mental model

The runtime *writes* `value = f(width)`; the design package *reads it back and judges it*.
Three stages, always the same:

1. **Measure** — open the page at several widths and snapshot every element you care about:
   rectangles, computed styles, parent/child relations. This produces a `SnapshotStore` — the
   sampled version of the parametric plane.
2. **Model** — the store makes `f(width)` tangible: for any element and property you can ask
   for its **curve**, the measured function across widths.
3. **Judge** — constraints are equations that must hold at every width (`child.right ≤
   parent.right`, `dFontSize/dWidth ≥ 0`); the score grades composition; a11y checks run on
   the same measurements. The verdict is machine-readable — humans read the console form,
   CI reads the exit code, agents read the JSON.

Nothing downstream of measurement touches the browser again: judging a cached store is pure
math, deterministic, and free to re-run.

## Your first validation

```typescript
import { test, expect } from '@playwright/test';
import { r$ } from '@responsivejs/design';

test('the layout holds', async ({ page }) => {
    const r = r$(page);

    await r.sweep({
        url: 'http://localhost:3000',
        widths: [320, 768, 1280],
        selectors: ['main', 'h1', '.card', '.btn'],
    });

    r.assert.noOverflow().minSize('.btn', { height: 44 });

    expect(r.report().pass).toBe(true);
});
```

What each line really does:

- **`r$(page)`** wraps a Playwright page in a validator. Nothing happens yet.
- **`sweep()`** is the measurement pass: for each width it resizes the viewport, waits for
  layout to settle, and runs r$'s in-page collector over your selectors. Choose widths like
  test cases — the extremes plus wherever your layout changes regime. Choose selectors for
  the elements with *responsibilities* (the nav that must not overflow, the CTA that must be
  tappable) rather than sweeping `*`.
- **`r.assert`** is a chainable **Asserter**. Each call checks one equation at every measured
  width and records violations instead of throwing — you always get the full picture, not the
  first failure.
- **`r.report()`** returns `{ pass, total, passed, failed, violations }`. `failed` counts
  failed *checks* — one check can carry several violations (minSize failing width AND
  height), so `failed ≤ violations.length` and `passed` is never negative. Each violation
  says *what* broke, *where* (`.btn[0]`), *at which width*, and *by how much*
  (`expected`/`actual`).

### Picking constraints

There are 27 (all in the [agents reference](../agents/validation-reference), each a method
on `r.assert`). They fall into families — pick by what the element is responsible for:

```typescript
r.assert
    .noOverflow()                                  // geometry: nothing bleeds out
    .contains('.card', '.card img')                // geometry: children stay inside
    .monotonic('h1', 'fontSize', 'up')             // continuity: text never shrinks as width grows
    .continuous('.sidebar', 'width', 200)          // continuity: no sudden jumps between widths
    .touchTarget('.toolbar button')                // a11y: tappable (24px WCAG floor; pass 44 for platform)
    .contrastRatio('p', 'AA')                      // a11y: measured effective backgrounds
    .proportion('.sidebar', '.main', { min: 0.2, max: 0.33 }); // relations: the ratio holds
```

The continuity family is the distinctive one: it checks the *function*, not a screenshot. A
font that drops from 32px to 18px between 767 and 768px passes every per-width check and
fails `monotonic` — which is exactly the class of bug that slips through visual review.

## The full oracle: `analyze()`

Assertions check what you thought of. `analyze()` runs everything at once — the default
constraint set, the aesthetic score, and axe (when installed):

```typescript
const report = await r.analyze();   // reuses the sweep you already did
```

The `UnifiedReport` adds structure worth knowing:

```jsonc
{
    "pass": false,       // no ERROR-level violations — your CI gate
    "clean": false,      // no violations at all — your polish gate
    "summary": { "errors": 2, "warnings": 3, "info": 0, "byRule": {…}, "byWidth": {…} },
    "violations": [ /* every one, with severity */ ],
    "fixes": [ { "selector": ".cta", "property": "min-height", "value": "44px", "reason": "…", "kind": "exact" } ],
    "scores": { "average": { "overall": 0.62, /* +17 metrics */ } },
    "sources": { "measurement": "playwright", "a11y": "axe" }
}
```

Two gates on purpose: **`pass`** ignores warnings (loop on it — fix errors first), **`clean`**
is zero-anything (chase it when polishing). `fixes` is the apply-verbatim list: only
`kind: "exact"` fixes (concrete CSS that mechanically resolves the measured violation),
deduped across widths. Heuristic fixes — a direction, like *increase contrast* — stay on
their violations, alongside `detail` + `expected/actual` to reason from.

`sources.a11y` tells you whether axe actually ran (`'axe'`), was skipped, or was unavailable —
the report never silently pretends.

## The aesthetic score (experimental)

Seventeen measured metrics with academic lineage (Ngo/Birkhoff — balance, equilibrium,
symmetry, proportion, density, rhythm…), each 0..1, averaged into `overall`. It is
deterministic but **experimental**: elements matched by several selectors are currently
counted once per selector, nested areas sum into density/weight, and the weights are not yet
calibrated against human judgment — treat it as a relative signal subordinate to the
verifiable constraints, never as a gate on its own. How to use it without over-trusting it:

- **Read metrics, not the total.** Each low metric maps to a concrete adjustment: low
  `balance` → visual weight is lopsided; low `proportion` → sizes don't relate harmonically;
  low `density` → cramped or sparse.
- **Compare, don't idolize.** The score shines as a *relative* signal: this variant vs that
  one, this week vs last week (`score: [{ min: 0.6 }]` in a contract pins the floor).
- **Scope it.** On long document pages visual mass concentrates at the top and `equilibrium`
  tanks — score a section (`r.score('.hero')`), not the page.

## Curves: the model made queryable

```typescript
r.at(768).rect('.sidebar');            // one width, one element
r.curve('h1', 'fontSize');             // Map<width, px> — f(width), measured
r.rectCurve('.sidebar', 'width');
```

Curves are what continuity constraints and **baselines** are built on — and your debugging
X-ray: print one and you *see* the function your CSS actually produced.

## Contracts: the spec that travels

Assertions live in test code. A **contract** is the same expectations as reviewable JSON —
versionable, diffable, executable by anyone (CI, the CLI, an agent):

```typescript
import { contract } from '@responsivejs/contract';
import { verifyContract, recordBaseline } from '@responsivejs/design';

const home = contract('home')
    .viewport({ widths: [320, 768, 1280] })
    .select('sidebar', '.app-sidebar')
    .assert('noOverflow', undefined, { id: 'no-bleed', description: 'nothing bleeds out' })
    .below(768).assert('hidden', { selector: '$sidebar' })
    .from(768).assert('visible', { selector: '$sidebar' })
    .baseline('h1', 'fontSize')
    .build();                            // → plain JSON (schema-validated round-trip)

const report = await verifyContract(home, page);   // sweep derived FROM the contract
```

Three things contracts add over inline asserts:

- **Intent.** Every rule carries a `description` — when it fails, the report tells you *why
  the rule exists*, not just that it broke. (This is also what makes contracts executable
  instructions for agents.)
- **Baselines.** `recordBaseline` measures today's curves and pins them into the contract;
  later runs fail if the geometry drifts beyond tolerance. Record → commit → verify: visual
  regression without screenshots.
- **Design-system presets.** `"designSystem": { "profile": "material-design-3" }` expands
  into that system's *measurable* rules — touch minimums, contrast, spacing tokens, radius
  sanity, control heights (also `apple-hig`, `fluent-ui-2`, or your own config). These are
  **validation presets**, not full conformance: they don't yet check type scales, color
  palettes, elevation or per-component specs.

When you outgrow the builder, write the JSON directly — the published
[schema](https://github.com/AleSaiani/ResponsiveJS/blob/main/packages/contract/schema/design-contract.v1.json) validates it, and unknown
names fail at load with did-you-mean suggestions.

And if the page runs the r$ runtime, you don't have to start from a blank file:
`rjs init <url> -o app.contract.json` generates the contract **from your constructs** — each
numeric fluid becomes `monotonic` + `continuous` + a baseline, each `ratio` a `proportion`,
your `r$.breakpoints` the sweep widths. What isn't expressible yet is listed on stderr.
`rjs record` then pins today's curves: the page is held to what it declares.

## Drivers: the seam under everything

`sweep` needs three capabilities: set a viewport, measure, (optionally) evaluate JS — plus
an optional screenshot seam that powers `rjs audit`'s visual reports. That's the whole
`MeasurementSource` interface — and everything above it is driver-neutral:

- **`PlaywrightSource`** — the default, what `r$(page)` uses. For CI.
- **`CdpSource`** — any structural `{ send(method, params) }` client (CDPSession,
  chrome-remote-interface, agent-browser's CDP bridge). No dependency.
- **`EvalSource`** — the lowest bar: if your environment can eval a JS string in the page,
  it can drive r$. Without a viewport-setter it *verifies* the live width rather than lying
  (measurements are never fiction); wrap `chunkedEval` when the transport caps argument
  length.

You care about this when validating where Playwright can't go: a logged-in session in a real
browser, an embedded webview, an agent's browser tool. Same collector, same math — identical
measurements everywhere.

### agent-browser: audits with nothing installed in the project

[Vercel's agent-browser](https://github.com/vercel-labs/agent-browser) deserves its own note,
because it changes *when* you can reach for r$. It's a standalone browser CLI (`npm i -g
agent-browser`) — so the audit needs **no Playwright, no npm install, no config in the target
project**. That unlocks workflows Playwright-in-the-repo can't do:

- **Audit a page you don't have the repo for** — production, a legacy property, a CMS page
  marketing just shipped: `rjs analyze https://example.com -d agent-browser`.
- **Check the competition** — measure any live site's responsive behavior the same way you
  measure yours (mind their terms of service).
- **Try r$ before adopting it** — one global install, one command, a full report; nothing to
  undo if you walk away.
- **A shared browser session** — agent-browser keeps a persistent session (`--session`), so
  repeated audits reuse the same browser instead of cold-starting one per run.

Playwright stays the CI driver (deterministic, versioned with the repo); agent-browser is the
zero-footprint field tool. `-d auto` picks whichever is available.

For no driver at all, the `/browser` subpath runs inside any live DOM:
`analyzeDOM()` is the one-call oracle at the current viewport, `scoreDOM(['main', '.card'])`
scores it — usable from a devtools console or injected by tooling. Two packaged ways in:
`mountOverlay()` drops an `<rjs-overlay>` badge on the page (live counts, grouped findings,
hover-to-highlight, re-measures on resize), and `rjs snippet --bookmarklet` turns the whole
bundle into a bookmark you can click on any site — the overlay appears, zero install.

## CI and the CLI

The `rjs` CLI is this same engine with exit codes: `rjs analyze <url>` (0 pass / 1
violations), `rjs verify <contract> <url>`, `rjs record`. Use the library in Playwright tests
where you already have fixtures; use the CLI where you want zero project setup or a quick
audit of any URL. `-f sarif` feeds code-scanning UIs; `-f json` feeds anything else.

And when the audience is a *person*, not a pipeline: `rjs audit <url>` produces one
self-contained HTML file — screenshots per width with the violation rectangles drawn on
them (from the measured rects), grouped findings, fixes, scores. `--crawl` covers the
same-origin pages, `--vs competitor.com` opens with a side-by-side table. It's the
"here's what's wrong with our site" artifact, generated in one command.

The flags that matter day to day: `-s "main,.card"` (scope selectors — see below), `-w
320,768,1280`, `--strict` (fail on warnings too), `--touch-min 44` (platform touch rule
instead of the WCAG 24px floor), `--scroll` (below-the-fold content), `-d agent-browser`
(audit any live URL with nothing installed in the project).

## Cutting false positives

A report that is mostly noise teaches people to ignore it. Four levers, in order of impact:

- **Scope your selectors.** Audit `main, nav, .content, .cta` — the elements with
  responsibilities — not the whole DOM. This is the single biggest signal/noise lever on
  real-world pages.
- Contrast is computed from **measured effective backgrounds** (transparent ancestors
  resolved to the color actually painted), so what it flags is what users see.
- `noOverflow` distinguishes **naked** overflow (would bleed the page — error) from overflow
  **inside a scroll region** (an `overflow-x: auto` carousel or table wrapper — warning): a
  data table that scrolls by design stops failing your build.
- Touch targets default to WCAG 2.5.8's 24px floor and **exempt inline prose links**; raise
  to platform guidance (`44`/`48`) per rule, per run, or via a design-system profile.
- Gate on `pass` (errors only) in loops and CI; chase `clean` (zero anything) when polishing.

## Determinism, cost, trust

Same store in → same report out: scores and contrast are computed from measured values (axe's
color sampler is deliberately disabled in favor of the deterministic constraint; contrast uses
*effective* backgrounds — transparent ancestors resolved to what users actually see).
Sweeping costs one page-load plus one relayout per width; everything after is pure math, so
re-judging a cached store — or a store shipped as JSON via `storeToJSON` — is free.

## Where next

- [CI guide](ci) — wiring reports into pipelines, SARIF, baselines strategy.
- [Agents reference](../agents/validation-reference) — exact JSON shapes and the fix loop.
- [design API](../api/design) · [contract API](../api/contract).


---

<!-- https://responsivejs.com/docs/guides/testing -->

# Testing responsive behavior

How to test code that uses r$ — what belongs in unit tests, what genuinely needs a browser,
and the patterns (and traps) we learned building r$'s own suite.

## The one decision: does it need layout?

Everything in r$ splits cleanly in two:

- **Pure logic** — values, curves, conditionals, contracts. `ResponsiveValue.resolve(width)`
  is a pure function; no DOM involved. Test it in plain unit tests, instantly.
- **Geometry** — anything that measures the real page: `whenWraps`, `whenStuck`, `sync`,
  overflow checks, the whole validation oracle. **jsdom and happy-dom do not do layout** —
  every element measures 0×0, so a geometry predicate in a DOM emulator returns garbage that
  looks plausible. These tests must run in a real browser.

When in doubt: if the behavior depends on where boxes ended up, it's a browser test.

## Unit-testing your responsive logic (no browser)

Values resolve without any DOM — test your functions as functions:

```typescript
import { describe, it, expect } from 'vitest';
import { r$ } from '@responsivejs/runtime';

describe('the hero scale', () => {
    const size = r$.fluid(24, 48, { from: 320, to: 1280 });

    it('clamps at the domain edges', () => {
        expect(size.resolve(320)).toBe(24);
        expect(size.resolve(1280)).toBe(48);
        expect(size.resolve(200)).toBe(24);    // never extrapolates
    });

    it('is halfway at the domain midpoint', () => {
        expect(size.resolve(800)).toBe(36);
    });
});
```

The same works for conditionals (`bp.below('tablet', 'a', 'b').resolve(500)`) and for any
`custom(fn)` you wrote. If your app builds style maps dynamically, test the *map building* —
pure — and leave the application to a browser test.

Contracts are pure too: `verifyContract(contract, store)` against a hand-built or recorded
store runs in milliseconds with no browser (r$'s own suite does exactly this).

## Browser tests: the patterns

Setup is ordinary Playwright (or the runner you prefer) serving your page. The r$-specific
patterns:

### Assert on what the CSS keys on

Geometry's entire output is data-attributes — so that's what tests read. Resize, then **wait
for the attribute**, never sleep:

```typescript
await page.setViewportSize({ width: 400, height: 800 });
await page.waitForFunction(() => document.querySelector('.site-nav')!.hasAttribute('data-wrapped'));

await page.setViewportSize({ width: 1400, height: 900 });
await page.waitForFunction(() => !document.querySelector('.site-nav')!.hasAttribute('data-wrapped'));
```

`waitForFunction` re-checks until true, absorbing the (deliberate) async between a resize and
the re-measure. A fixed `waitForTimeout` is a flaky version of the same thing.

### Assert on computed styles for tokens and fluid values

```typescript
const hero = await page.evaluate(() =>
    getComputedStyle(document.documentElement).getPropertyValue('--font-hero').trim(),
);
expect(hero).toBe('64px');

const applied = await page.evaluate(() => getComputedStyle(document.querySelector('h1')!).fontSize);
```

For statically-compiled values (linear fluid, breakpoint switches) there is nothing async at
all — the browser applies the stylesheet; read the computed style directly.

### Test state STABILITY, not just state

A geometry state that oscillates (the `display: none` mistake) can look green in a
single-check test and flicker in production. Check it holds across frames:

```typescript
const stable = await page.evaluate(
    () =>
        new Promise<boolean>((resolve) => {
            let frames = 0;
            const check = () => {
                if (!document.querySelector('.site-nav')!.hasAttribute('data-wrapped')) return resolve(false);
                if (++frames >= 5) return resolve(true);
                requestAnimationFrame(check);
            };
            requestAnimationFrame(check);
        }),
);
expect(stable).toBe(true);
```

### Let the oracle do the asserting

For whole-page correctness, don't hand-write twenty assertions — run r$'s validation side as
the judge in the same test:

```typescript
import { r$ } from '@responsivejs/design';   // note: the DESIGN package's r$(page)

const r = r$(page);
await r.sweep({ url, widths: [320, 768, 1280], selectors: ['main', 'nav', '.card', '.cta'] });
r.assert.noOverflow().minSize('.cta', { height: 44 });
expect(r.report().pass).toBe(true);
```

Or from CI without writing a test at all: `rjs analyze <url>` / `rjs verify <contract> <url>`
— exit code 1 fails the build. The contract flow (`record` → commit → `verify`) is visual
regression for geometry, no screenshots involved.

## Traps we hit so you don't

- **The page must actually scroll** before asserting `data-stuck`: at a wide viewport a short
  page has no scrollbar, `scrollTo` does nothing, and the wait times out. Scroll at a narrow
  viewport, or `scrollTo(0, document.body.scrollHeight)`.
- **Serve over HTTP, not `file://`**, when your bundler emits `crossorigin` assets (vite
  does): from `file://` the browser blocks them and your page silently runs with no JS at all
  — everything measures like browser defaults and nothing you assert makes sense.
- **`r$.flush()`** exists for unit-style tests that drive the JS path synchronously (drain
  the batched style writes after an event you dispatched). In real-browser tests you rarely
  need it — prefer `waitForFunction` on the outcome.
- **One-shot measures** are your debugging tool inside a paused test:
  `r$.whenWraps().measure(el)` in `page.evaluate` tells you what the predicate sees *right
  now*, bypassing all wiring.

## Living examples

r$'s own e2e suite uses every pattern above against the [landing example](https://github.com/AleSaiani/ResponsiveJS/blob/main/examples/landing)
— see `packages/runtime/e2e/landing.e2e.test.ts` (constructs, stability check, stuck
round-trip) and `packages/cli/e2e/cli.e2e.test.ts` (the oracle + contract round-trip as test
assertions).


---

<!-- https://responsivejs.com/docs/guides/ci -->

# Guide — responsive regression in CI

Three escalating setups, all built on Playwright.

## 1. Assertions in a test

The quickest start: sweep and assert inline.

```typescript
import { test, expect } from '@playwright/test';
import { r$ } from '@responsivejs/design';

test('pricing page layout', async ({ page }) => {
    const r = r$(page);
    await r.sweep({
        url: '/pricing',
        widths: [320, 768, 1280, 1920],
        selectors: ['h1', '.plan-card', '.cta'],
    });

    r.assert
        .noOverflow()
        .childrenEqualWidth('.plan-grid')
        .minSize('.cta', { height: 44 })
        .breakpointSafe([768, 1280]);

    expect(r.report().pass, r.log('console') && '').toBe(true);
});
```

Tip: `breakpointSafe` re-measures at `bp±1` — add those widths (or use a contract, which does it
for you).

## 2. The full oracle

One call adds the aesthetic score and a11y (when `axe-core` is installed):

```typescript
const report = await r.analyze();          // reuses the sweep
expect(report.pass).toBe(true);            // fails only on error severity
console.log(formatCompact(report));        // r$ PASS E0/W2/I1 (312 checks, 4 widths)
```

Publish machine-readable results to code-scanning ecosystems:

```typescript
import { writeFileSync } from 'node:fs';
import { formatSARIF } from '@responsivejs/design';

writeFileSync('responsive.sarif', formatSARIF(report, { toolVersion: '1.0.0' }));
```

```yaml
# .github/workflows/ci.yml — surfaces violations in the Security tab / PR annotations
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: responsive.sarif }
```

## 3. Contracts (the durable setup)

Freeze expectations in a versioned JSON file next to the code:

```typescript
// tests/contracts/build-home-contract.ts — run once, commit the output
import { writeFileSync } from 'node:fs';
import { contract } from '@responsivejs/contract';

const home = contract('home')
    .viewport({ widths: [320, 768, 1280] })
    .select('nav', '.main-nav')
    .assert('noOverflow', undefined, { id: 'no-bleed' })
    .below(768).assert('hidden', { selector: '$nav' }, { id: 'nav-mobile', description: 'nav collapses to burger' })
    .from(768).assert('visible', { selector: '$nav' }, { id: 'nav-desktop' })
    .score({ min: 0.55 })
    .baseline('$nav', 'width', { px: 4 })
    .build();

writeFileSync('tests/contracts/home.contract.json', JSON.stringify(home, null, 2));
```

The CI test is five lines, forever:

```typescript
import home from './contracts/home.contract.json' with { type: 'json' };
import { verifyContract, formatContractConsole } from '@responsivejs/design';

test('home keeps its design contract', async ({ page }) => {
    await page.goto('/');
    const report = await verifyContract(home, page);
    expect(report.pass, formatContractConsole(report)).toBe(true);
});
```

### Recording baselines

Baselines turn "it looked right when we shipped it" into data:

```typescript
// After an approved visual change — re-pin and commit:
const r = r$(page);
await r.sweep({ url: '/', widths: [320, 768, 1280], selectors: ['.main-nav'] });
const repinned = recordBaseline(home, r.raw);
writeFileSync('tests/contracts/home.contract.json', JSON.stringify(repinned, null, 2));
```

From then on, `verifyContract` fails when the measured curve drifts beyond tolerance — geometric
visual regression without screenshots.

### Editor support

Add the schema for autocomplete and inline validation of contract files:

```json
{ "$schema": "https://raw.githubusercontent.com/AleSaiani/ResponsiveJS/main/packages/contract/schema/design-contract.v1.json" }
```

## Browser installation in CI

```yaml
- run: pnpm exec playwright install --with-deps chromium
```

Unit-level checks (`analyzeStore`, `verifyContract(contract, store)`, all constraint logic) run
in plain Node — no browser needed. Keep the browser job separate from your test matrix.


---

<!-- https://responsivejs.com/docs/guides/agents -->

# Guide — r$ for AI agents (AX)

r$ is built to be the **judgment** in an agent loop: an agent (or its browser tool) is the arm;
`analyze()`/`verifyContract()` are the eyes and the verdict. Everything the oracle emits is
machine-readable: `{ violations, fixes, scores }`.

## The loop

```
render page → measure (any driver) → analyze() → violations + fixes
     ↑                                                  │
     └───────────── apply fix, re-run ─────────────────┘
```

Every `Violation` carries `rule`, `element` (selector), `width`, `detail`, `severity`, and —
where an honest one exists — a structured `fix`:

```json
{ "selector": ".cta", "property": "min-height", "value": "24px", "reason": "touch target minimum" }
```

`UnifiedReport.fixes` is the flattened list. Apply, re-measure, converge.

## Driving from CDP (agent-browser, remote Chrome)

`CdpSource` takes any structural `{ send(method, params) }` client — no dependency. This is how
r$ composes with browser tools like [Vercel's agent-browser](https://github.com/vercel-labs/agent-browser),
Playwright's `CDPSession`, or chrome-remote-interface:

```typescript
import { CdpSource, analyze } from '@responsivejs/design';

const source = new CdpSource(cdpClient);          // agent-browser bridge, CDPSession, CRI…
const report = await analyze({
    source,
    selectors: ['main', 'nav', '.card', 'button'],
    widths: [320, 768, 1280],
    // url omitted → the page you already navigated is measured as-is
});
```

Under the hood the collector is injected as a string via `Runtime.evaluate` — the same collector
every driver uses, so measurements are identical across Playwright, CDP, and in-page runs.

### Driving from a bare `eval` primitive

If all you have is a way to evaluate a JS string in the page — agent-browser's eval, a browser
extension, a REPL over a live tab — `EvalSource` turns it into a full driver:

```typescript
import { EvalSource, analyze } from '@responsivejs/design';

const source = new EvalSource((expr) => yourEval(expr), {
    // optional: wire these when your environment can resize/navigate
    setViewport: (w, h) => yourResize(w, h),
    open: (url) => yourNavigate(url),
});

// Viewport not controllable? Analyze honestly at the live width:
const report = await analyze({
    source,
    selectors: ['main', 'nav', '.card', 'button'],
    widths: [await source.currentWidth()],
});
```

Without a `setViewport` callback the source refuses widths that don't match the real viewport —
measurements never lie. Text transports that return JSON strings are parsed automatically.

Argument-length limits (Windows command lines cap at ~32K; axe injection alone is ~500K) are
solved by composing `chunkedEval`, which stages oversized expressions in-page chunk by chunk:

```typescript
import { EvalSource, chunkedEval, analyze } from '@responsivejs/design';
import { spawn } from 'node:child_process';

// agent-browser CLI as the driver — one isolated session, JSON output.
// Resolve on exit, NOT stream close: the first command spawns the CLI's
// daemon, which inherits the stdio pipes and holds them open forever.
const ab = (...args: string[]) =>
    new Promise<string>((res, rej) => {
        const child = spawn('agent-browser', ['--session', 'rjs', ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
        let out = '';
        child.stdout.on('data', (d) => (out += d));
        child.on('error', rej);
        child.on('exit', (code) => setTimeout(() => (code === 0 ? res(out.trim()) : rej(new Error(out))), 30));
    });
const abEval = async (expr: string) => {
    const res = JSON.parse(await ab('--json', 'eval', expr));
    if (!res.success) throw new Error(res.error);
    return res.data.result;
};

const source = new EvalSource(chunkedEval(abEval), {
    setViewport: async (w, h) => void (await ab('set', 'viewport', String(w), String(h))),
    open: async (url) => void (await ab('open', url)),
});

const report = await analyze({ source, url: 'https://example.com', selectors: ['main', 'nav'], widths: [320, 768, 1280] });
```

This exact composition runs in the repo's e2e suite (`packages/design/e2e/agent-browser.e2e.test.ts`).

For fully manual control the raw pieces are also exported:

```typescript
import { buildCollectExpression, fromWire, analyzeStore } from '@responsivejs/design/browser';

const wire = await yourEval(buildCollectExpression({ selectors: ['main', '.card'] }));
const report = analyzeStore({ snapshots: new Map([[wire.width, fromWire(wire)]]), widths: [wire.width], selectors: ['main', '.card'] });
```

`storeToJSON`/`storeFromJSON` let you ship measurements across process boundaries as plain JSON.

## Contracts as agent instructions

A contract is a task description an agent can execute against: authored intent per rule
(`description`), machine-checkable args, and stable `ruleId`s to correlate.

```typescript
import { verifyContract } from '@responsivejs/design';

const report = await verifyContract(homeContract, page);
for (const v of report.violations) {
    // v.ruleId        → which expectation broke
    // v.ruleDescription → WHY it exists (the authored intent)
    // v.fix           → what to change, when derivable
}
```

Agent workflow: fix what has a `fix`; for the rest, use `detail` + `expected/actual` + the
intent to reason about a patch; re-verify; stop when `report.pass`. After an *approved* visual
change, `recordBaseline` re-pins the geometry so the next run has a fresh reference.

## Practical notes

- **Costs**: axe runs at `[min, max]` widths by default (opt into `'all'`); constraint checks
  and scoring are pure math on the measured store — re-running `analyzeStore` on a cached store
  is free.
- **Severity**: gate on `report.pass` (errors only) for hard loops; use `clean` when the agent
  should also chase warnings/info.
- **a11y**: needs `axe-core` installed and an evaluate-capable source. `sources.a11y` in the
  report tells you whether it ran (`'axe' | 'skipped' | 'unavailable'`).
- **SARIF**: `formatSARIF(report)` when the consumer is a code-scanning pipeline rather than a
  live loop.
- **Determinism**: contrast is computed from measured colors (never axe's sampler); scores are
  deterministic per store — identical inputs give identical reports.


---

<!-- https://responsivejs.com/docs/api/runtime -->

# API — @responsivejs/runtime

The authoring half: reactive `value = f(width)`, CSS-first. Depends only on
`@responsivejs/core`. Subpaths: `/signals`, `/curves`, `/layout`, `/typography`, `/geometry`
(everything is also re-exported from the root).

**The entry point is `r$`** — one callable namespace carrying the everyday authoring surface
(`r$.fluid`, `r$.tokens`, `r$.geometry`, `r$.whenWraps`, `r$.breakpoints`, `r$.sync`, …), so
the editor's autocomplete is the API browser. `responsive` is an alias of the same object (the
historical name). Precisely: every `r$` member exists, plus root named exports for the same
functions and for the lower layers. The namespace is a **superset of the authoring surface**:
transforms, curve sugar, `layout`/`typography` helpers and the measurement signals are all on
`r$.` too. Only module-level internals (`emitCSS`, `injectStyle`, `registerProvenance`) stay
named-export-only.
New to the runtime? Start from the [guide](../guides/runtime), not this reference.

## `r$()` — apply styles

```typescript
r$(target, map): ResponsiveHandle
r$`selector { prop: ${r$.fluid(14, 24)}px }`   // tagged-template form
```

- `target`: selector string, `Element`, `Element[]`, or `NodeList`.
- `map`: `Record<prop, StyleValue>` where a value is a `ResponsiveValue`, a
  `(width) => value` function, or a plain string/number.
- With a selector target and `useMediaQueries` on (default), the map is **split**: statically
  expressible values become one injected `<style data-responsivejs>`; the rest is JS-driven.
- In the tagged-template form a literal suffix that is *just a unit* (`${fluid(14, 24)}px`)
  belongs to the value: it is folded in, so the declaration still compiles to `clamp()`.
  Genuinely mixed content (`${a} solid red`) is a composed string and stays JS-driven — CSS
  has no way to express it.

`ResponsiveHandle`: `elements`, `update(map)`, `pause()`, `resume()`, `dispose()`.
Ownership guarantees: every handle owns a **unique** stylesheet (two `r$('.x', …)` calls never
clobber each other; the cascade goes to the later injection); the inline value present before
the handle's first write to a property is **restored** on dispose; `update(map)` restores
properties the new map no longer contains; `container: true` values acquire
`container-type: inline-size` on the parent through a refcounted owner that never overrides a
user declaration (also on the static path — the stylesheet says `cqi`, the handle provides
the container; with `r$.static()` alone, declaring the container is on you).

### The namespace

| Member | Meaning |
| --- | --- |
| `r$.configure({ breakpoints, defaultUnit='px', useMediaQueries=true, debug, ssrWidth=1024, nonce })` | Change the config (itself reactive — **both** halves of every construct re-emit). `nonce` is copied onto every injected `<style>` for strict CSP. |
| `r$.config(): ResolvedConfig` | Read the config in force (frozen copy). |
| `r$.breakpoints({ mobile: 320, … } as const)` | Define named breakpoints — returns the [typed API](#typed-breakpoints). |
| `r$.tokens({ '--space-md': fluid(8, 16) })` | [Token bridge](#tokens--fluid-custom-properties): fluid custom properties on `:root`. |
| `r$.static(selector, map): { css, dispose }` | CSS-only compilation — throws if anything needs JS. Each call owns its own stylesheet (two static maps for one selector never clobber each other) and can remove it. |
| `r$.dynamic(target, map)` | Skip the static split, drive everything via JS. |
| `r$.observe(selector, map): ObserveHandle` | **SPA**: the selector stays bound as elements come and go. The static half is injected once (CSS already covers future elements); the JS half is wired per element on mount and released on removal. `refresh()` re-scans on demand. |
| `r$.scope(): Scope` | Group handles: `s.add(handle)` returns it unchanged, `s.dispose()` releases everything in reverse order. One call to tear a component down. |
| `r$.renderStatic(): string` | Every stylesheet emitted so far — what a server inlines into `<head>`. |
| `r$.lazy(target, map)` | Apply on first intersection (IntersectionObserver). |
| `r$.batch(fn)` | One signal flush + one style flush for several calls. |
| `r$.memo(map)` | Cache custom-function values per 1px width bucket. |
| `r$.debug(bool)` | Log resolved values on change. |
| `r$.flush()` | Synchronously drain pending style writes (tests). |
| `r$.apply(target, 'text-fluid-sm-xl p-fluid-2-8')` | Utility micro-grammar (`{text\|p\|m\|gap\|bg\|color}-fluid-{from}-{to}`). |
| `r$.manifest()` | The live provenance manifest: every active construct with target, behavior, call site and its serialized declaration (`config`) — also published on `window.__rjs_manifest` for the validation oracle: violations trace back to their owning construct, and `rjs init` generates contracts from it. |

## Values

### `fluid()` — polymorphic

```typescript
fluid(min, max, unit? | opts?)          // numbers → linear (static clamp) or curved (JS)
fluid([8, 16, 24, 32], opts?)           // per-breakpoint multi-segment
fluid('#ff0000', '#0000ff', opts?)      // colors → perceptual OKLab mix (JS)
fluid('scale(0.8)', 'scale(1.2)')       // strings → structural interpolation (JS)
```

`FluidOpts`: `curve` (`'linear' | 'exponential' | 'logarithmic' | EasingName | Bezier`), `unit`,
`container: true` (bind to nearest container; static output uses `cqi` — **requires `from`/`to`**,
see below), `from`/`to` (domain override — defaults to the configured breakpoint range),
`domain: fromElement('.sidebar')`
(cross-element: the value follows that element's width — always JS-driven).

`container: true` **must** come with `from`/`to` (or a `domain` source): it changes what is
measured, not the range it is measured over, so without them the value would interpolate across
your viewport breakpoints and a 240–820px card would walk a fifth of its curve. That failure is
silent and reads as "the library does nothing", so it is a construction-time error instead.

String interpolation requires **structural congruence** (same tokens, literals, units — bare `0`
inherits the other side's unit) and throws a descriptive error otherwise. No fuzzy matching.

### Conditionals

| Function | Static CSS? | Meaning |
| --- | --- | --- |
| `when(pred, a, b?)` / `when([[pred, v], …])` | no | Arbitrary predicate; first match wins. |
| `whenInRange(min, max, value, otherwise?)` | yes* | 2013 heritage; min+max `@media`. |
| `breakpoint.below(ref, a, b?)` | yes* | `ref` is a name or px. Mobile-first emission; without `b` the value is `@media (max-width)`-guarded — it never leaks above the threshold. |
| `breakpoint.above(ref, a, b?)` / `.between(lo, hi, a, b?)` | yes* | |
| `breakpoint.match({ mobile: 14, desktop: 18 })` | yes* | Largest matching breakpoint wins. |

\* static when the branches compile to plain declarations — including nested values:
`breakpoint.above('md', fluid(14, 24))` emits `clamp()` **inside** the `@media` block. A branch
that needs its own media blocks (a per-breakpoint array) cannot nest and stays JS-driven.

### Helpers

- `custom(fn, opts?)` — wrap `(width) => value`; always JS.
- `combine([...])` — space-join parts (transform lists). Static when every part is.
- `scale(v)`, `rotate(v)`, `translate(x, y)`, `translateX(v)`, `translateY(v)`, `skew(x, y?)` — transform
  templates with conventional default units. They compile to static CSS whenever their
  arguments do: `transform: translateX(clamp(…)) scale(clamp(…))` is ordinary CSS.
- `isResponsiveValue(v)` — brand check.

## `/geometry` — state from geometry

The niche CSS still can't select on. **JS detects, CSS styles**: predicates measure facts off
the live DOM; `geometry()` mirrors them into data-attributes for your stylesheets.

```typescript
geometry('.nav', { wrapped: whenWraps, crowded: whenOverflows });
// → <nav data-wrapped>       CSS: .nav[data-wrapped] { /* burger */ }
```

| Predicate | True when | Extra sensitivity |
| --- | --- | --- |
| `whenWraps()` | a child starts below the first row | |
| `whenOverflows(axis?)` | scroll size > client size (`'x'` default, `'y'`, `'both'`) | |
| `whenTruncated()` | content overflows an axis whose overflow is hidden/clip | |
| `whenStuck()` | a `position: sticky` element is currently pinned | scroll |
| `linesOf()` | *(number)* rendered text lines → `data-lines="3"` | |
| `whenCollides(other)` | the rects of the element and `other` overlap | scroll |

Re-measures on element resize (shared ResizeObserver), viewport resize, and scroll for the
scroll-sensitive ones. Every predicate's `measure(el)` is pure and callable one-shot.
**Never `display: none` what a predicate measures** (zeroed rects flip the state back and it
oscillates) — collapse keeping layout: `visibility: hidden; height: 0; overflow: hidden`.
`GeometryHandle`: `elements`, `measure()`, `pause()`, `resume()`, `dispose()` (removes the
attributes). SSR: inert. Bare factories are accepted (`wrapped: whenWraps` ≡ `whenWraps()`).

## Cross-element

- `fromElement(target)` — a fluid **domain**: `fluid(14, 18, { domain: fromElement('.sidebar'),
  from: 200, to: 600 })` makes the value follow the sidebar's width, not the viewport. Honoured
  by every value kind (numbers, per-breakpoint arrays, colors, structural strings, `custom`);
  a `combine()` whose parts follow *different* elements throws, since a combined value has one
  driving width. A source selector that matches nothing throws **at construction**, before any
  stylesheet or provenance entry exists.
- `sync(target, 'height' | 'width')` — equalize a dimension across unrelated containers (max
  natural size wins). Re-measures on viewport resize and `handle.measure()`.
- `ratio(a, b, { min?, max? })` — the design constraint promoted to **enforcement**: keeps
  `width(a)/width(b)` in bounds by constraining `a`, and frees it while the layout complies.

## Typed breakpoints

```typescript
const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1024 } as const);  // defineBreakpoints as named export
bp.below('tablet', 'column', 'row');   // autocompletes; a typo is a COMPILE error
bp.between('mobile', 'desktop', …);
bp.match({ mobile: 14, desktop: 18 });
bp.width('tablet');                    // 768
bp.matches('tablet');                  // reactive { signal, dispose }
bp.names;                              // ['mobile', 'tablet', 'desktop'] (ascending)
```

Also configures the global runtime, so the string-based `breakpoint.*` API keeps working.

## Tokens — fluid custom properties

```typescript
const t = r$.tokens({ '--space-md': fluid(8, 16), '--font-hero': fluid(24, 48, { curve: 'exponential' }) });
```

One write point instead of N styled elements: linear values compile to a static `clamp()`
stylesheet on `:root` (zero JS at runtime); non-linear/conditional/color values update their
variable from ONE viewport effect. The page consumes `var(--space-md)` anywhere — themable,
inspectable, SSR-friendly (`t.css` is the stylesheet to ship). `t.dynamic` lists the JS-driven
names; `t.toDTCG()` exports Design-Tokens-Community-Group JSON (static values verbatim,
responsive curves sampled under `$extensions['design.responsivejs']`); `t.dispose()` removes
everything.

## `/curves` — sugar

`linear`, `exponential`, `logarithmic`, `easeIn`, `easeOut`, `easeInOut`, `cubic(min, max,
bezier)` — each equals `fluid(min, max, { curve })`.

## `/layout`

- `grid.adaptive({ minColumnWidth, maxColumns?, gap? }): StyleMap` — without `maxColumns` it is
  pure CSS (`repeat(auto-fit, minmax(min(Wpx, 100%), 1fr))`); with it, the column count is
  computed per width.
- `space` — geometric spacing scale (`base 8 × ratio 1.5^level`, `space.config()` to change):
  `level(n)`, `inset(v, h?)`, `stack(n)`, `inline(from, to?)`, `fluid(from, to)`, `rhythm(n)`.

## `/typography`

`typography.scale('major-third' | { ratio, base: [min, max] }): TypeScale` — reuses core's
`SCALES`. `size(level)` is a fluid value (`base × ratio^level` at each domain edge);
`lineHeight(level)` eases 1.5 → 1.2 as levels grow (display sizes tighten); `spacing(level)` is
half the size. Unknown names throw with the valid list.

## `/signals` — the reactive engine

TC39-shaped, zero-dep, no DOM:

```typescript
state<T>(initial, equals?): State<T>          // { get(); set(v) }
computed<T>(fn, equals?): Computed<T>         // { get() } — lazy, version-validated, diamond-safe
effect(fn): Disposer                          // runs now, re-runs on change; cleanup via return
subscribe(signal, cb): Disposer               // cb on change (not on subscription)
batch(fn)                                     // defer effects, flush synchronously at exit
untrack(fn)                                   // read without depending
```

Width sources (all SSR-safe, all disposable):

| Function | Backed by |
| --- | --- |
| `viewportWidth(): State<number>` | ONE passive resize listener (lazy singleton). |
| `mediaQuery(q): { signal, dispose }` | Refcounted matchMedia registry. |
| `breakpointSignal(ref)` | `mediaQuery('(min-width: …)')` via named breakpoints. |
| `containerWidth(el): { signal, dispose }` | ONE shared ResizeObserver, refcounted per element. |
| `elementSize(el): { signal, dispose }` | `{width, height}` off the same observer and refcount. |
| `scrollTick(): Computed<number>` | ONE capture-phase scroll listener (nested containers too). |
| `releaseViewportHub()` | Drop every listener/observer and all registries (embedded hosts, SPA teardown). Signals re-arm lazily. |

Every signal the hub hands out is **read-only** (`Computed`): the entries are shared, so a
consumer writing to one would desynchronize every other consumer of the same element.

## Named imports ↔ the namespace

`r$.x` and the named import are the same function — the namespace is a convenience, not a
wrapper. Import names differ in a few places where the bare word would be too generic:

| Named import | Namespace | |
| --- | --- | --- |
| `applyResponsive` | `r$()` | apply a style map |
| `applyDynamic` | `r$.dynamic` | skip the static split, drive everything from JS |
| `staticCSS` | `r$.static` | emit + inject the stylesheet, returns `{ css, dispose }` |
| `applyUtilities` | `r$.apply` | the utility grammar below |
| `parseUtilities` | — | the same grammar, returning a `StyleMap` you can extend |
| `batchWrites` | `r$.batch` | coalesce signal updates *and* style writes into one flush |
| `defineBreakpoints` | `r$.breakpoints` | typed breakpoints |
| `bpWidth(name)` | — | the px of a named breakpoint; throws with the valid names |
| `emittedStyles()` | — | every stylesheet key r$ has injected (tests, SSR audits) |
| `releaseViewportHub()` | `r$.releaseViewportHub` | drop the shared listeners (tests) |

Everything else is spelled the same in both forms.

### The utility grammar — `r$.apply`

`r$.apply(target, spec)` parses a Tailwind-shaped string into a style map, for when a fluid
value is easier to write inline than to declare:

```typescript
r$.apply('.card', 'text-fluid-sm-2xl p-fluid-12-32 bg-fluid-slate50-slate200');
```

Grammar: `{alias}-fluid-{from}-{to}`, where `alias` is `text` · `p` · `m` · `gap` · `bg` ·
`color`. Sizes accept the named scale (`xs sm base lg xl 2xl 3xl`) or raw numbers; colours
accept hex or the named set. Anything it cannot parse throws naming the grammar — no silent
partial application. `parseUtilities(spec)` returns the map instead of applying it, so you can
merge it with hand-written declarations.

## Emission

`emitCSS(selector, map): { css, dynamicRest }` and `injectStyle(css, key)` /
`removeStyle(key)` are exported for build-time use. Linear fluid compiles with the Utopia
formula: `slope = (max−min)/(vMax−vMin)`, `intercept = min − slope·vMin` →
`clamp(lo, calc(intercept + slope·100vw), hi)` (bounds reordered for descending ranges,
`cqi` for containers).

## No build step

`@responsivejs/runtime/global` is the whole runtime as one IIFE (~15.5 kB gzip). Drop it in
with a `<script>` and `window.r$` is the same callable namespace — nothing else changes, the
CSS-first split included:

```html
<script src="https://unpkg.com/@responsivejs/runtime/dist/global.js"></script>
<script>
    r$.tokens({ '--space-m': r$.fluid(16, 24) });   // → clamp() on :root, zero JS after this
    r$.geometry('.site-nav', { wrapped: r$.whenWraps });
</script>
```

For CMS pages, plain HTML, docs demos, and agents injecting the runtime into a page they do
not own. `responsive` is published as an alias of the same object.

## SSR

No `window` access at module level; values resolve at `config.ssrWidth` until hydration.
The CSS-first half is fully server-renderable:

```typescript
r$('.hero', { fontSize: r$.fluid(16, 32) });      // handle.css is its compiled half
r$.tokens({ '--space-m': r$.fluid(16, 24) });     // tokens().css likewise
const sheet = r$.renderStatic();                   // …or every emission at once
// → inline `sheet` into <head> and the page is correct BEFORE any JS runs
```

Under a strict Content-Security-Policy pass `r$.configure({ nonce })`: every injected
`<style>` carries it.


---

<!-- https://responsivejs.com/docs/api/design -->

# API — @responsivejs/design

The validation oracle. Peers (both optional): `@playwright/test` (only the driver needs it),
`axe-core` (only a11y needs it). The `/browser` subpath is driver-free by construction.

## `r$(page)` — the Playwright validator

```typescript
const r = r$(page);                       // ResponsiveValidator
await r.sweep({ url, selectors, widths | from/to/step, height?, scroll?, scrollSteps? });
```

| Member | Meaning |
| --- | --- |
| `r.at(width)` | `WidthQuery` at a measured width (`rect`, `style`, `elements`…). |
| `r.curve(sel, prop)` / `r.rectCurve(sel, prop)` | Property curve across widths. |
| `r.assert` | The `Asserter` (chainable constraints, below). |
| `r.score(parentSelector?)` | `ScoreResult` — 17-metric aesthetics, whole page or subtree. |
| `r.report()` | Constraint `Report`. |
| `r.analyze(opts?)` | The full oracle → `UnifiedReport` (reuses the sweep). |
| `r.log('console' \| 'json' \| 'compact')` | Print the report. |
| `r.resweep({ widths?, selectors? })` | Incremental re-measure, merged. |
| `r.validateDesignSystem(ds, selectors?)` | Apply a DS profile's constraints. |
| `r.measureInteraction(sel)` | Normal/hover/focus snapshots. |
| `r.widths` / `r.raw` | Measured widths / the `SnapshotStore`. |
| `ResponsiveValidator.live(page, { selectors })` | A `LiveValidator` (below). |

## The `Asserter` — 27 chainable constraints

Every check runs at **all** measured widths; violations carry structured `fix` suggestions where
honest. `new Asserter(store)` works on any store (no Playwright).

`noOverflow()` · `contains(parent, child)` · `sameHeight(a, b, tol?)` · `sameLine(a, b)` ·
`minSize(sel, { width?, height? })` · `gapUniform(sel, threshold?)` ·
`monotonic(sel, prop, dir?)` · `continuous(sel, prop, maxJump)` · `proportion(a, b, { min, max })`
· `childrenContained(sel, tol?)` · `childrenEqualWidth(sel, tol?)` · `noZeroHeight(sel)` ·
`touchTarget(sel, min?)` (default 24 = WCAG 2.5.8 AA floor; platform guidance 44–48;
interactive = DOM semantics — native controls/roles/tabindex — or cursor:pointer; inline
targets in prose exempt; unrendered skipped) · `textReadable(sel)` · `contrastRatio(sel, 'AA' | 'AAA')` ·
`borderRadiusValid(sel)` · `zStackOrder(selectors)` · `typographyScale(sel)` ·
`spacingTokens(sel, tokens)` · `aspectRatio(sel, ratio, tol?)` · `focusVisible(sel)` ·
`noHiddenOverflow(sel)` · `alignedToGrid(sel, gridSize)` · `breakpointSafe(breakpoints)` ·
`interactiveSpacing(sel, minGap?)` · `visible(sel)` · `hidden(sel)` — then `report()` / `reset()`.

## `analyze()` — the unified oracle

```typescript
analyze(opts: AnalyzeOptions): Promise<UnifiedReport>
analyzeStore(store, opts?): UnifiedReport          // sync, pure — also on /browser
```

`AnalyzeOptions`: `source` (a `MeasurementSource`) and/or `store` (pre-measured); sweep params
(`url`, `selectors`, `widths`/`from`/`to`/`step`, `height`, `scroll`); `constraints` (config
object or `(assert) => void` escape hatch); `designSystem`; `score` (`{ subtree? } | false`);
`a11y` (`A11yOptions | false`).

Default constraint set (low false-positive): `noOverflow` + `contrastRatio AA` + `touchTarget`
on every analyzed selector. `ConstraintsConfig` toggles each and adds `textReadable`,
`focusVisible`, or anything via `custom(assert)`.

**`UnifiedReport`** extends `Report` with: `clean` (zero violations of any kind — `pass` fails
only on `error` severity), `scores`, `fixes` (`FixSuggestion[]` — only `kind: 'exact'`
entries, deduped by selector+property across widths: the apply-verbatim agent surface),
`widths`, `url`, `sources` (`{ measurement, a11y: 'axe' | 'skipped' | 'unavailable' }`),
`summary` (`errors/warnings/info`, `byRule`, `byWidth`), `durationMs`.

**a11y degradation**: omitted + axe installed → runs; omitted + missing → `'unavailable'`
(silent); explicitly configured + missing → **throws**; no evaluate seam or `a11y: false` →
`'skipped'`. Axe rules are namespaced `axe:<id>`; impact maps critical/serious → error,
moderate → warning, minor → info. `color-contrast` is always disabled (delegated to the
deterministic constraint). `A11yOptions`: `wcagTags`, `disableRules`, `widths: number[] | 'all'`
(default `[min, max]`), `include`, `exclude`.

`mergeReports(base, ...extra)` folds additional plain `Report`s (e.g. a theme token gate) into
one unified report.

## `MeasurementSource` — drivers

```typescript
interface MeasurementSource {
    kind: string;
    open?(url): Promise<void>;
    setViewport(width, height): Promise<void>;
    measure(selectors): Promise<ViewportSnapshot>;
    evaluate?<T>(expression: string): Promise<T>;   // string-only (CDP-compatible)
    close?(): Promise<void>;
}
```

- **`PlaywrightSource(page, { settleMs? })`** — the CI driver.
- **`CdpSource(client, { height?, settleMs?, loadTimeoutMs? })`** — takes any structural
  `{ send(method, params) }` (chrome-remote-interface, Playwright `CDPSession`, agent-browser).
  Measures by injecting the collector via `Runtime.evaluate` (`returnByValue` + `awaitPromise`).
- **`EvalSource(evalFn, { setViewport?, open?, settleMs?, widthTolerance? })`** — the
  lowest-friction adapter: wraps a bare `(expression: string) => Promise<unknown>` primitive
  (agent-browser, extensions, bookmarklet hosts). `setViewport`/`open` are optional callbacks;
  without a viewport setter the source verifies the live width instead of lying about it —
  `currentWidth()` gives you the natural sweep width. String results from text transports are
  JSON-parsed in `measure()`.
- **`sweepSource(source, opts)` / `resweepSource(source, store, opts)`** — the driver-neutral
  sweep loop (scroll support requires the `evaluate` seam). `SourceSweepOptions` makes `url`
  optional: omit it for pre-navigated/attached sources.

## `/browser` — zero-driver

`collectViewport(selectors, { root?, width?, height? })` · `collectStore(...)` ·
`scoreDOM(selectors)` · `analyzeDOM(selectors?, opts?)` (one-call oracle over the live DOM at
the current viewport — defaults to `LANDMARK_SELECTORS`) · `analyzeStore` · `collectPage` /
`buildCollectExpression(args)` (the self-contained in-page collector and its injectable
expression) · `fromWire`/`toWire` · `storeToJSON`/`storeFromJSON` (JSON transport of stores —
Maps don't survive serialization).

**The overlay**: `mountOverlay({ selectors?, touchMin? })` appends an `<rjs-overlay>` badge
(shadow DOM, style-isolated) that shows live E/W counts, expands to the grouped findings,
outlines the offending element on hover, and re-measures on resize. `defineOverlay()`
registers the element without mounting. Both are lazy — safe to import in Node/SSR.

**The IIFE bundle**: `@responsivejs/design/browser-global` is this whole subpath bundled as
a single ~52 kB script exposing `window.rjs` — droppable into any page via `<script>`,
`page.addScriptTag`, or the `rjs snippet` bookmarklet. No module system needed.

## `LiveValidator` — realtime observers

`attach(page, selectors)` · `snapshot(): SnapshotStore` · `resizeTo(width)` ·
`scoreAt(width?)` · `check(): Report` · `detach()`. For continuous scoring while a page changes
(theme builders, devtools). It runs the **same in-page collector** as every other path, so its
measurements are identical — DOM-semantic interactivity, effective backgrounds, overflow
containment and the provenance manifest all included.

## Reporters

`formatConsole` · `formatJSON` (serializes score maps correctly) · `formatCompact` (adds
`E/W/I` counts for unified reports) · `formatSARIF(unified, { toolVersion? })` — SARIF 2.1.0
for code-scanning CI · `formatContractConsole` / `formatContractCompact` /
`formatContractSARIF` (contract rule ids become SARIF rule ids; the authored `description`
rides as each rule's `shortDescription` — see [contract](contract)) · `toSerializable` ·
`renderAuditHTML(pages: PageAudit[], { title? })` — one self-contained HTML document per
audit run: grouped violations, fixes, embedded per-width screenshots with violation
rectangles overlaid from the measured rects; 2+ pages lead with a comparison table.

## Design systems

Bundled profiles (`@responsivejs/design/design-systems/*.json`): `apple-hig`, `fluent-ui-2`,
`material-design-3`. `applyDesignSystem(asserter, ds, selectors?)` applies a
profile's constraints; `designSystemRules(ds, selectors?)` returns the same checks as contract
rules (the two are parity-tested).

## Also exported

Pieces of the pipeline, exported because an agent loop or a custom harness may need them
without going through `analyze()`:

| | |
| --- | --- |
| `contractFromPage(store, { name? })` | the contract ANY page can be held to, from what the sweep found — plus construct-derived rules when the page runs r$ |
| `contractFromManifest(manifest, { name? })` | only the construct-derived half |
| `INIT_SELECTORS` | the candidate selectors `rjs init` sweeps to decide which rules are worth writing |
| `resolveWidths(opts)` | the width list a sweep will actually use (contract → options → defaults) |
| `applicableFixes(report)` | the `exact` fixes only, deduplicated — what a fixer may apply unattended |
| `attachOwnership(report, manifest)` | adds `owner` / `owners` / `via` to violations from the provenance manifest |
| `runAxe(source, opts)` / `normalizeAxeResults(results)` | the a11y pass on its own, and its mapping to r$ severities |
| `compileRule(rule)` | one contract rule → the asserter call it becomes |
| `calibrate(store)` | derives sensible constraint thresholds from a page you consider correct |


---

<!-- https://responsivejs.com/docs/api/contract -->

# API — @responsivejs/contract

The design-contract DSL: the **spec** lives here (types, registry, builder, loader, JSON
Schema); **execution** (`verifyContract`, `recordBaseline`) lives in `@responsivejs/design` and
is re-exported from it.

## The format (version 1)

```jsonc
{
    "version": 1,
    "name": "home",
    "viewport": { "widths": [320, 768, 1280], "height": 900 },     // or from/to/step
    "selectors": { "sidebar": ".app-sidebar" },                     // "$sidebar" aliases
    "designSystem": { "profile": "material-design-3" },             // or inline config
    "rules": [
        {
            "id": "sidebar-mobile",              // stable id (derived if omitted)
            "assert": "hidden",                  // one of the 27 registry constraints
            "args": { "selector": "$sidebar" },  // named args, validated per constraint
            "when": { "max": 767 },              // inclusive width range
            "severity": "error",                 // override (error | warning | info)
            "description": "sidebar collapses on mobile"   // authored intent, shown to agents
        }
    ],
    "score": [{ "min": 0.6, "metrics": { "balance": 0.5 }, "scope": "main", "when": { "min": 768 } }],
    "baselines": [{ "selector": "$sidebar", "prop": "width", "tolerance": { "px": 4 } }]
}
```

JSON Schema: [`schema/design-contract.v1.json`](https://github.com/AleSaiani/ResponsiveJS/blob/main/packages/contract/schema/design-contract.v1.json)
— generated from the registry, drift-tested. Versioning: additive optional fields don't bump
`version`; changed semantics do. Unknown fields and newer versions are rejected with an upgrade
hint.

## Component contracts

A contract sweeps either the **viewport** or a **container**:

```jsonc
{
    "name": "card", "version": 1,
    "container": { "harness": ".story-harness", "widths": [240, 360, 480] },
    "rules": [{ "assert": "noOverflow", "description": "the card never bleeds out of its container" }]
}
```

In container mode the harness element is resized instead of the window, and everything is
measured **inside it, relative to it** — so `noOverflow` compares against the component's
width, not the page's. Container queries respond, because the harness is given
`container-type: inline-size`. `contractSweepPlan()` reports `harness`, and `rjs verify`
switches to a `HarnessSource` automatically: one component, one contract, verifiable in CI
without a page around it.

## The registry

`CONSTRAINT_REGISTRY` — 27 entries, one per Asserter constraint (see
[design](design#the-asserter--27-chainable-constraints)), each declaring named params, types,
and the positional mapping. It is the single source of truth for the TS types
(`ConstraintName`), the runtime validator, the generated schema, and design's dispatch — a sync
test against the real `Asserter` class prevents drift. Also: `CONSTRAINT_NAMES`,
`isConstraintName`.

## Builder

```typescript
contract(name?)                       // → ContractBuilder
    .viewport({ widths: [...] })
    .select('alias', '.selector')     // registers "$alias"
    .use('material-design-3', selectors?)     // embed a DS profile (or inline config)
    .at('*' | { min?, max? })         // scope subsequent asserts (describe-block style)
    .below(768) / .upTo(1024) / .from(768) / .between(a, b)
    .assert(name, args?, { id?, severity?, description? })
    .score({ min?, metrics?, scope?, when? })
    .baseline(selector, prop, tolerance?)
    .build()                          // validated DesignContract (throws ContractValidationError)
    .toJSON()
```

Round-trip guarantee: `parseContract(builder.toJSON())` is the identity.

## Loader

- `parseContract(json | object): DesignContract` — throws `ContractValidationError` with all
  issues formatted.
- `validateContract(input)` — `{ contract, issues: [] }` or `{ contract: null, issues }`;
  each `ContractIssue` is `{ path, message, suggestion? }` with did-you-mean suggestions for
  misspelled constraints, args, and fields.
- `resolveAliases(contract)` — expand `"$alias"` strings (whole-string matches only).

Zero dependencies — the validator is hand-rolled from the registry, not ajv.

## Execution (from `@responsivejs/design`)

```typescript
verifyContract(contract, store): ContractReport               // sync, driver-free
verifyContract(contract, page, { height? }): Promise<...>     // sweeps first
recordBaseline(contract, store): DesignContract               // fills baselines[].curve
contractFromManifest(manifest, { name? }): { contract, skipped }  // constructs → contract
```

`contractFromManifest` is the pure half of `rjs init`: a provenance manifest in, a
loader-valid contract out (fluid → `monotonic` + `continuous` + baseline, ratio →
`proportion`, breakpoints → `viewport.widths`, plus the `noOverflow` default). `skipped`
lists every construct/prop that could not become a rule — report it, never swallow it.

Semantics:

- **Scoping** — each rule runs on a sub-store filtered to its `when` range; an empty range makes
  the rule `skipped: true` (reported, never failing).
- **Attribution** — one `Asserter` per rule: every violation carries `ruleId` and
  `ruleDescription`; `severity` overrides apply per rule.
- **Scores** — thresholds check the average, or every in-range width when `when` is set;
  failures surface both as `ScoreCheckResult` and as synthetic `score.<metric>` violations.
- **Baselines** — recorded curves compared at their exact widths against `{ px?, percent? }`
  tolerance (default 2px); unrecorded baselines report `unrecorded` without failing.
- **Page overload** — selectors and widths are derived from the contract itself (union of all
  selector args + DS selectors + score scopes + baseline selectors; `bp±1` added for
  `breakpointSafe` rules).
- **`pass`** — no `error`-severity violations (warnings/info don't fail).

`ContractReport`: `{ contract, pass, total, passed, failed, rules: RuleResult[], violations:
ContractViolation[], score?, baselines? }` — the flat `violations` list is the single agent
surface.

## The agent loop

1. `verifyContract` → report.
2. For each violation: `ruleId` → look up the rule → read `description` (intent) and the
   violation's `fix` (`{ selector, property, value, reason, kind }` — `kind: 'exact'` is
   apply-verbatim; `'heuristic'` is a direction that needs judgment).
3. Patch, re-verify. `recordBaseline` after an approved visual change re-pins the curves.

## Also exported

| | |
| --- | --- |
| `buildJsonSchema()` | the JSON Schema generated from the registry — the same file committed under `schema/`, so tooling can regenerate instead of vendoring |
| `inRange(width, when)` / `describeRange(when)` | the `when: { min, max }` scoping logic and its human-readable form, for tools that report which rules applied where |


---

<!-- https://responsivejs.com/docs/api/cli -->

# @responsivejs/cli — the `rjs` command line

The zero-setup surface of r$: point it at any URL and get the full oracle — constraints,
aesthetic score, a11y — as console output, JSON, or SARIF. Exit codes make it CI- and
agent-loop-ready: `0` pass, `1` violations, `2` usage/run error.

```
rjs analyze <url>              sweep + oracle (constraints + score + a11y)
rjs audit <url>                one-shot HTML report with screenshots
rjs verify <contract> <url>    execute a design contract against a live page
rjs record <contract> <url>    measure and pin baseline curves into the contract
rjs init <url>                 generate a contract from the page's r$ constructs
rjs snippet                    emit the injectable browser bundle (--bookmarklet)
rjs doctor                     check drivers and environment readiness
```

## Options

| Option | Meaning | Default |
| --- | --- | --- |
| `-d, --driver` | `auto` \| `playwright` \| `agent-browser` | `auto` |
| `-w, --widths` | comma-separated widths (`320,768,1280`) | contract / built-in sweep |
| `-s, --selectors` | comma-separated selectors (analyze) | landmark set |
| `-f, --format` | `console` \| `json` \| `sarif` (contract SARIF carries each rule's authored intent) | `console` |
| `-o, --out` | write the report (or recorded contract) to a file | stdout |
| `--height` | viewport height | `900` |
| `--touch-min` | touch-target minimum px (analyze) | `24` (WCAG AA; platform is 44–48) |
| `--scroll` | scroll-sweep below-the-fold content | off |
| `--no-a11y` | skip axe (analyze) | axe runs when available |
| `--strict` | fail on warnings too (analyze) | errors only |
| `--headed` | show the browser window (playwright) | headless |
| `--vs <url>` | audit a second site side by side (audit) | — |
| `--crawl` | follow same-origin links (audit) | off |
| `--max-pages <n>` | crawl limit (audit) | `5` |
| `--screenshots <dir>` | also write the per-width PNGs to a directory (audit) | embedded only |

## Drivers

- **`playwright`** — chromium via the optional `playwright` / `@playwright/test` peer. The CI
  driver.
- **`agent-browser`** — [Vercel's agent-browser](https://github.com/vercel-labs/agent-browser)
  CLI, found on `PATH` (or via `AGENT_BROWSER_BIN`). Zero npm install in the target project:
  the oracle runs through the CLI's `eval`, with oversized injections (axe) chunked
  automatically. The driver uses an isolated `--session`.
- **`auto`** — playwright if installed, else agent-browser, else a clear install hint.

`rjs doctor` probes all of the above — node version, playwright + chromium, agent-browser —
one line per check with the exact install command for anything missing, and tells you which
driver `auto` will pick. Exit `0` = at least one driver usable, `1` = none.

## `audit` — the report you hand to someone

`rjs audit <url>` is analyze packaged as a deliverable: full oracle + per-width screenshots,
rendered into one **self-contained HTML file** (`rjs-audit.html` by default) — images
embedded, violation rectangles drawn as overlays from the *measured* rects, apply-verbatim
fixes tabled, provenance owners named. Nothing to install for the reader.

- `--crawl` walks same-origin links breadth-first up to `--max-pages` (default 5); pages
  discovered but not audited are reported, never silently dropped.
- `--vs <url>` audits a competitor too — the report leads with a side-by-side table
  (errors, warnings, checks, aesthetic score).
- `--screenshots <dir>` additionally saves the raw PNGs (`<host-path>-<width>.png`).
- Screenshots need a driver with the screenshot seam (playwright and agent-browser both
  have it). Without one the report says so and ships without images; passing
  `--screenshots` explicitly in that case is an error.
- Exit codes as analyze: `0` all pages pass, `1` violations, `--strict` gates on `clean`.

## `init` — the free regression net

On a page that runs `@responsivejs/runtime`, the constructs *declare* their behavior in the
provenance manifest. `rjs init <url> -o app.contract.json` turns those declarations into
rules the oracle verifies: numeric `fluid` on a measurable prop → `monotonic` + `continuous`
+ a baseline; `ratio` bounds → `proportion`; the page's `r$.breakpoints` → the viewport
widths — plus the `noOverflow` default. What can't be expressed yet (geometry, sync, tokens,
element-driven fluids) is listed on stderr, never dropped silently. Then `rjs record` pins
today's curves and `rjs verify` in CI holds the page to its own declarations. Exits 2 when
the page has no manifest.

## `snippet` — the oracle without a terminal

`rjs snippet` emits the browser-global bundle (`window.rjs`, ~52 kB) ready to inject:

- default — a paste-ready `<script>` block that mounts the `<rjs-overlay>` badge;
- `--bookmarklet` — a `javascript:` URL: save it as a bookmark, click it on **any page
  you're looking at**, and the overlay appears with live violation counts, grouped findings
  and element highlighting. Everything is inline — nothing hosted, nothing phoned home.
- `-o <file>` writes instead of printing.

The overlay measures at the *current* viewport and says so — the CLI commands remain the
full-sweep truth.

## `verify` and `record`

The sweep is derived **from the contract itself**: selectors from rule args, widths from
`viewport` (plus `bp±1` for `breakpointSafe`). `record` fills `baselines[].curve` from
measurements and writes the contract back (`--out` to write elsewhere) — the
record-then-assert flow:

```bash
rjs record home.contract.json https://staging.example.com   # pin today's geometry
rjs verify home.contract.json https://pr-42.example.com     # regressions fail with exit 1
```

## Programmatic use

Everything the binary does is exported: `main(argv, io?)` (inject `CliIo` for testing),
`resolveDriver`, `DEFAULT_SELECTORS`.


---

<!-- https://responsivejs.com/docs/api/adapters -->

# API — framework adapters (React · Vue · Angular)

The constructs are framework-agnostic and identical everywhere: `r$.fluid(16, 32)` is the same
value in all three. What an adapter adds is the **lifecycle** — apply when the element exists,
`update()` when the declaration changes, dispose when the component goes away. Nothing else is
wrapped, and nothing is hidden: you can always reach for the runtime directly.

Prefer prose? The lifecycle section of [the runtime guide](../guides/runtime#lifecycle-testing-ssr)
explains *why* handles exist; this page is the signatures.

| | React | Vue | Angular |
| --- | --- | --- | --- |
| package | `@responsivejs/react` | `@responsivejs/vue` | `@responsivejs/angular` |
| peer | react ≥ 18 | vue ≥ 3.4 | @angular/core ≥ 16 |
| style map | `useResponsive(ref, map, deps?)` | `useResponsive(elRef, map \| ref(map))` | `injectResponsive(el, map)` |
| geometry | `useGeometry(ref, states, deps?)` | `useGeometry(elRef, states)` | `injectGeometry(el, states)` |
| tokens | `useTokens(map, deps?)` | `useTokens(map)` | `injectTokens(map)` |
| group | `useScope()` | `useScope()` | `injectScope()` |
| width | `useViewportWidth(): number` | `useViewportWidth(): ShallowRef<number>` | `injectViewportWidth(): Signal<number>` |
| breakpoint | `useBreakpoint(ref): boolean` | `useBreakpoint(ref): ShallowRef<boolean>` | `injectBreakpoint(ref): Signal<boolean>` |
| template form | — | `v-responsive="map"` | *(a 6-line directive in your app — below)* |

## React

```tsx
const ref = useRef<HTMLDivElement>(null);
useResponsive(ref, { padding: r$.fluid(12, 24) });     // → clamp(), zero JS
useGeometry(ref, { wrapped: r$.whenWraps });            // → data-wrapped
const isDesktop = useBreakpoint('desktop');
```

- `deps` follows the `useEffect` convention. Changing them calls `update()` on the **live
  handle** (properties the new map drops are restored) instead of tearing it down.
- `useViewportWidth`/`useBreakpoint` read through `useSyncExternalStore`, so they are
  concurrent-safe and SSR-safe: the server snapshot is `config().ssrWidth`.
- StrictMode's double-invocation does not duplicate constructs.

## Vue

```vue
<script setup lang="ts">
const card = ref<HTMLElement | null>(null);
useResponsive(card, { padding: r$.fluid(12, 24) });
const isDesktop = useBreakpoint('desktop');
</script>

<template>
    <div ref="card" v-responsive="{ gap: r$.fluid(8, 16) }" />
</template>
```

- Pass a `ref(map)` and the handle updates through `watch` when you replace it.
- Template form: `app.use(responsivePlugin)` registers `v-responsive` globally, or import
  `vResponsive` into a component's `directives`. The directive owns the handle across mount,
  update and unmount.

## Angular

The package ships **no decorators on purpose**: it needs no Angular compilation step
(no ng-packagr, no partial-ivy artifacts), so it works from any Angular ≥ 16 app as plain
functions and signals.

```ts
@Component({ selector: 'app-card', standalone: true, template: `<div #card>…</div>` })
export class CardComponent {
    private readonly card = viewChild.required<ElementRef<HTMLElement>>('card');
    readonly width = injectViewportWidth();          // Signal<number>
    readonly isDesktop = injectBreakpoint('desktop'); // Signal<boolean>

    constructor() {
        afterNextRender(() => {
            injectResponsive(this.card().nativeElement, { padding: r$.fluid(12, 24) });
        });
    }
}
```

Every `inject*` helper must run in an injection context and releases on `DestroyRef`. Each has
a DI-free twin — `createResponsive`, `createGeometry`, `createViewportWidth`,
`createBreakpoint` — returning `{ update?, destroy }` for code that owns its own teardown
(and for use outside a constructor, e.g. inside `afterNextRender`).

Want the template form? Six lines in your app, compiled by your own build:

```ts
@Directive({ selector: '[rjsResponsive]', standalone: true })
export class RjsResponsiveDirective implements OnChanges, OnDestroy {
    @Input('rjsResponsive') map: StyleMap = {};
    private binding?: Binding<StyleMap>;
    constructor(private readonly el: ElementRef<HTMLElement>) {}
    ngOnChanges() { this.binding ? this.binding.update(this.map) : (this.binding = createResponsive(this.el, this.map)); }
    ngOnDestroy() { this.binding?.destroy(); }
}
```

## What every adapter guarantees

- **One construct per binding.** An update never stacks a second construct: check
  `r$.manifest()` — it stays at one entry.
- **Full restoration.** Disposal restores inline values that existed before the construct,
  removes injected CSS and geometry attributes, and releases observers.
- **No wrapping of values.** `r$.fluid`, `r$.whenWraps`, `r$.breakpoints` are imported from
  `@responsivejs/runtime` in all three — the adapter never re-exports a parallel API.
- **SSR-safe reads.** Width readers fall back to `config().ssrWidth` when there is no window.

For elements the adapter does not own (a portal, a third-party widget, a list rendered by
another library), reach for `r$.observe(selector, map)` from the runtime: it keeps a selector
bound as elements mount and unmount.


---

<!-- https://responsivejs.com/docs/api/core -->

# API — @responsivejs/core

Pure math, zero dependencies, browser-safe. Every module is a subpath export
(`@responsivejs/core/rect`, …); the root re-exports the data-model types flat and the math
modules as namespaces (`import { rect, curve } from '@responsivejs/core'`).

## `/rect` — geometry

```typescript
interface Rect { x; y; width; height; right; bottom; centerX; centerY; area }
```

| Function | Meaning |
| --- | --- |
| `rect(x, y, w, h): Rect` | Build a Rect with derived fields. |
| `fromDOMRect({x,y,width,height}): Rect` | From a DOMRect-like. |
| `contains(parent, child, tolerance=1)` | Child inside parent. |
| `overlaps(a, b)` / `overlapsVertically(a, b)` | Intersection tests. |
| `distance(a, b)` | Center-to-center distance. |
| `horizontalGap(a, b)` / `verticalGap(a, b)` | Edge-to-edge gaps. |
| `sameHeight(a, b, tol=2)` / `sameWidth(a, b, tol=2)` | Dimension equality. |
| `alignedLeft(a, b, tol=1)` / `alignedTop(a, b, tol=1)` | Edge alignment. |
| `inViewport(r, vw, vh?)` | Fully inside the viewport. |
| `widthRatio(a, b)` | `a.width / b.width`. |

## `/curve` — analysis of measured curves

`Curve = Map<number, number>` (width → value).

| Function | Meaning |
| --- | --- |
| `entries(curve)` | Sorted `[width, value][]`. |
| `isMonotonicUp(curve, tol=0.5)` / `isMonotonicDown` | Never moves against the direction. |
| `maxJump(curve)` | Largest step between adjacent widths. |
| `isContinuous(curve, maxAllowed)` | No jump exceeds the bound. |
| `discontinuities(curve, threshold)` | Every jump above the threshold. |
| `valueRange(curve)` | `{ min, max, range }`. |
| `ratio(a, b)` / `ratioInRange(a, b, min, max)` | Pointwise ratio of two curves. |

## `/interpolate` — authoring (the inverse of `/curve`)

```typescript
type WidthFn = (width: number) => number;
interface Domain { min: number; max: number }        // values clamp outside it
type Bezier = [x1, y1, x2, y2];
type EasingName = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
```

| Function | Meaning |
| --- | --- |
| `linear(min, max, domain): WidthFn` | Straight interpolation. |
| `exponential(min, max, domain, base=4)` | Slow start, fast finish — normalized easing on t (zero-safe endpoints). |
| `logarithmic(min, max, domain, base=4)` | Fast start, slow finish — exact inverse of `exponential`. |
| `eased(min, max, easing, domain)` | Named CSS easing or custom bezier. |
| `cubicBezier(bezier): (t) => number` | Solve a CSS cubic-bezier (Newton + bisection, ~1e-6). |
| `stepped(values, breakpoints)` | Discrete switch, right-open intervals. |
| `piecewise(points, easing?)` | Multi-segment through `[width, value]` control points. |
| `sample(f, widths=DEFAULT_WIDTHS): Curve` | Bridge back to the analysis half. |
| `inverse(f, value, domain): number \| undefined` | Which width produces the value (monotone f only). |
| `progress(width, domain)` | Clamped 0..1 position in the domain. |
| `EASINGS` | The CSS-spec control points per easing name. |

## `/color` — parsing, WCAG, OKLab

| Function | Meaning |
| --- | --- |
| `parseColor(css): RGBA` | hex (3/6/8), `rgb()`/`rgba()` (comma + modern), `hsl()`, `oklch()`, `transparent`. Fallback: opaque black. |
| `relativeLuminance(rgba)` | WCAG 2.1 relative luminance. |
| `contrastRatio(fg, bg): number` | 1–21, alpha-blended. |
| `meetsAA(ratio, largeText=false)` / `meetsAAA` | 4.5/3 and 7/4.5 thresholds. |
| `rgbaToOklab(rgba): OKLab` / `oklabToRgba(oklab): RGBA` | Björn Ottosson's matrices; out-of-gamut clamped per channel. |
| `mixOklab(a, b, t): RGBA` | Perceptual mix (what the runtime uses for color fluid). |
| `formatRgb(rgba): string` | Modern `rgb(r g b / a)` emission. |

## `/typography` — modular scales

| Export | Meaning |
| --- | --- |
| `SCALES` | Named ratios: `minorSecond` 1.067 … `goldenRatio` 1.618. |
| `detectScale(sizes)` | Best-fit `{ base, ratio, name }` for measured font sizes. |
| `fitsScale(sizes, tolerance=0.05)` | Do the sizes fit any known scale? |
| `usesTokens(values, tokens, tolerance=1)` | Are values drawn from a token set? `{ valid, outliers }`. |

## `/aesthetics` — the 17-metric score

`score(input, weights?)` accepts `ScoreInput` (`{ rects, viewport, colors?, fontSizes? }`) and
returns an `AestheticScore` with 15 weighted metrics (`balance`, `equilibrium`, `symmetry`,
`proportion`, `rhythm`, `density`, `regularity`, `simplicity`, `unity`, `homogeneity`,
`sequence`, `cohesion`, `economy`, `colorHarmony`, `typographyHarmony`), plus `birkhoff` and the
weighted `overall` — all 0..1. Each metric is also exported as a standalone function. Grounded in
Ngo, Teo & Byrne (2003), *Modelling interface aesthetics*, and Birkhoff (1933), *Aesthetic Measure*.

## `/types` — the data model

`ElementSnapshot` (selector, index, `Rect`, numeric `styles`, string `computed`) ·
`ViewportSnapshot` (one width) · `SnapshotStore` (all widths) · `Violation` (rule, element,
width, detail, expected/actual, severity, suggestion, `fix`, `owner`/`owners`) ·
`FixSuggestion` (`{ selector, property, value, reason, kind }` with
`kind: 'exact' | 'heuristic' | 'runtime-patch'` — verbatim-applicable, directional, or
patch-the-construct with `construct`/`source`/`change`) · `ProvenanceEntry` (construct,
target, behavior, source, serializable `config`) · `Report` · `SweepOptions` ·
`InteractionSnapshot` · `DEFAULT_WIDTHS` = `[320, 375, 390, 768, 1024, 1280, 1440, 1920, 2560]`.

## `/snapshot` — querying stores

```typescript
const q = new StoreQuery(store);
q.at(1280).rect('h1');                  // Rect | undefined
q.at(1280).style('h1', 'fontSize');     // number | undefined
q.at(1280).elements('.card');           // ElementSnapshot[]
q.curve('h1', 'fontSize');              // Curve across widths (styles or x/y/width/height)
q.rectCurve('h1', 'right');             // Curve over any Rect field
q.computedCurve('h1', 'color');         // Map<width, string>
```

`WidthQuery` (returned by `at()`): `element`, `elements`, `rect`, `rects`, `style`, `children`,
`childRelation`, `computedProp`, `allRects`.


---

<!-- https://responsivejs.com/docs/agents/authoring-reference -->

# Agent reference — authoring with @responsivejs/runtime

Compact rules + exact signatures for writing runtime code. Human-oriented docs:
[runtime guide](../guides/runtime) · [API](../api/runtime).

Entry point: `import { r$ } from '@responsivejs/runtime'` — every function below also exists
as `r$.<name>` (e.g. `r$.fluid`, `r$.geometry`, `r$.whenWraps`); `r$(target, map)` applies.

## Invariants — always hold these

1. **CSS-first**: prefer constructs that compile to static CSS (linear `fluid`, `breakpoint.*`,
   `tokens`). JS drives only what CSS cannot (curves, geometry, cross-element, logic).
2. **Never `display: none` an element a geometry predicate measures** — zeroed child rects flip
   the predicate and the state oscillates. Collapse keeping layout:
   `visibility: hidden; height: 0; overflow: hidden`.
3. **JS detects, CSS styles**: predicates set data-attributes; put the styling in the
   stylesheet (`.nav[data-wrapped] { … }`), never in JS.
4. **Keep handles, dispose on unmount**: every construct returns a handle;
   `handle.dispose()` removes everything it did (effects, observers, CSS, attributes) AND
   restores inline values that existed before the handle touched them.
5. **Prefer `tokens()` over per-element styles** for design-scale values: one write point on
   `:root`, consumed as `var()`.
6. SSR: all constructs are inert without `window`; ship `r$.static().css` / `tokens().css`.

## Signatures

```typescript
// Apply styles (CSS-first split on selector targets)
r$(target, map): ResponsiveHandle          // target: selector | Element | Element[]
r$.dynamic(target, map)                    // force JS path
r$.static(selector, map): {css, dispose}   // CSS only; throws if JS needed
r$.flush()                                 // drain pending writes (tests)

// Values
r$.fluid(min, max, unit? | { curve?, unit?, container?, from?, to?, domain? })
r$.fluid([8, 16, 24, 32], opts?)                      // per-breakpoint segments
r$.fluid('#f00', '#00f')                              // OKLab color mix (JS)
r$.when(pred, a, b?) · r$.whenInRange(min, max, v, else?)
r$.breakpoint.below(ref, a, b?) · .above · .between(lo, hi, a, b?) · .match({name: value})

// Typed breakpoints (returns API typed on YOUR names; typo = compile error)
const bp = r$.breakpoints({ mobile: 320, tablet: 768 } as const);
bp.below('tablet', a, b?) · bp.above · bp.between · bp.match({...}) · bp.width(name)
bp.matches(name): { signal, dispose } · bp.names

// Tokens (fluid custom properties on :root)
const t = r$.tokens({ '--space-m': r$.fluid(16, 24) });
t.css            // static stylesheet (SSR)
t.dynamic        // names that stay JS-driven
t.toDTCG()       // Design-Tokens JSON, curves sampled
t.dispose()

// Geometry predicates → data-attributes
r$.geometry(target, { stateName: predicate }, { prefix? }): GeometryHandle
r$.whenWraps() · r$.whenOverflows('x'|'y'|'both'?) · r$.whenTruncated() · r$.whenStuck()
r$.linesOf()  /* number → data-lines="3" */ · r$.whenCollides(otherSelectorOrElement)
predicate.measure(el)                              // pure one-shot, no reactivity
handle.measure() · handle.pause() · handle.resume() · handle.dispose()

// Cross-element
r$.fromElement(target)                                 // fluid domain: follows THAT element's width
r$.sync(target, 'height'|'width'): { measure, dispose }   // equalize across containers
r$.ratio(a, b, { min?, max? }): { measure, dispose }      // enforce width ratio on a

// Reactivity (TC39-shaped, zero-dep)
state(v) · computed(fn) · effect(fn): dispose · subscribe(sig, cb) · batch(fn) · untrack(fn)
viewportWidth() · containerWidth(el) · elementSize(el) · mediaQuery(q) · scrollTick()
```

## Choosing the construct

| Need | Use | NOT |
| --- | --- | --- |
| Value scales with viewport | `r$.fluid(min, max)` in `tokens()` | resize listeners |
| Value scales with own container | `r$.fluid(…, { container: true, from, to })` | ancestor queries in JS |
| Value follows ANOTHER element | `r$.fluid(…, { domain: r$.fromElement(sel) })` | polling rects |
| Nav collapses when it stops fitting | `r$.geometry` + `r$.whenWraps` | a magic `@media` px |
| Style while sticky is pinned | `r$.geometry` + `r$.whenStuck` | IO sentinel hack |
| "Show more" when clamped | `r$.geometry` + `r$.whenTruncated` | char-count heuristics |
| Equal heights, different parents | `r$.sync(sel, 'height')` | manual measure loops |
| Sidebar/main ratio guarantee | `r$.ratio(a, b, bounds)` | hoping the CSS holds |
| Named responsive switches | `r$.breakpoints(...as const)` + `bp.*` | string names |

## Minimal correct pattern

```typescript
import { r$ } from '@responsivejs/runtime';

const bp = r$.breakpoints({ mobile: 320, tablet: 768, desktop: 1280 } as const);
const tokens = r$.tokens({ '--space-m': r$.fluid(16, 24), '--font-hero': r$.fluid(28, 56) });
const nav = r$.geometry('.site-nav', { wrapped: r$.whenWraps });
const grid = r$('.cards', { gridTemplateColumns: bp.below('tablet', '1fr', 'repeat(3, 1fr)') });

// on unmount:
for (const h of [tokens, nav, grid]) h.dispose();
```

Validate what you authored: `rjs analyze <url>` — see the
[validation reference](validation-reference).


---

<!-- https://responsivejs.com/docs/agents/validation-reference -->

# Agent reference — validation I/O

Exact shapes and decision rules for driving r$ programmatically. Human-oriented docs:
[design guide](../guides/validation).

## Commands

```
rjs analyze <url>  [-d auto|playwright|agent-browser] [-w 320,768,1280] [-s "main,.card"]
                   [-f console|json|sarif] [-o file] [--no-a11y] [--strict] [--scroll]
                   [--touch-min 24] [--height 900]
rjs verify  <contract.json> <url>  [same driver/format/out flags]
rjs record  <contract.json> <url>  [-o other.json]
rjs init    <url>  [-o contract.json]   # generate a contract FROM the page's constructs
rjs audit   <url>  [--vs url] [--crawl] [--max-pages n] [--screenshots dir] [-o report.html]
                                   # human-facing HTML report — prefer analyze -f json for loops
rjs doctor                         # environment readiness: exit 0 = a driver is usable
```

Exit codes — gate on these: `0` pass · `1` violations · `2` usage/run error (bad args, missing
driver, invalid contract). `--strict` makes analyze exit 1 on warnings/info too.

## UnifiedReport (analyze -f json)

```jsonc
{
    "pass": false,          // no ERROR-severity violations (loop gate)
    "clean": false,         // no violations at all (polish gate)
    "total": 46, "passed": 39, "failed": 7,   // failed counts CHECKS (can be < violations.length;
                                              // one check may carry several violations). Never negative.
    "widths": [320, 1280],
    "sources": { "measurement": "playwright|agent-browser|eval|cdp|store", "a11y": "axe|skipped|unavailable" },
    "summary": { "errors": 7, "warnings": 0, "info": 0, "byRule": {"noOverflow": 1}, "byWidth": {"320": 3} },
    "violations": [ /* Violation[] — see below */ ],
    "fixes": [ /* Fix[] — ONLY kind:'exact' entries, deduped by (selector, property)
                  across widths. Safe to apply verbatim, no parsing needed. */ ],
    "scores": { "average": { "overall": 0.57, /* +17 metrics 0..1 */ }, "perWidth": {} },
    "manifest": [ /* ProvenanceEntry[] — present when the page runs @responsivejs/runtime:
                     {id, construct, target, behavior[], source?, config?} — what controls the
                     page. config is the SERIALIZED declaration (e.g. {fontSize: {value:'fluid',
                     min:16, max:32, curve:'exponential'}}) — everything needed to regenerate
                     the construct call. */ ],
    "durationMs": 4200
}
```

### Violation

```jsonc
{
    "rule": "noOverflow",          // or "axe:<id>", "score.<metric>", "baseline"
    "element": ".card[0]",         // selector[index]
    "width": 320,                  // px where it was measured
    "detail": "right=496 > viewport=320",
    "severity": "error|warning|info",   // MISSING severity counts as error
    "expected": 320, "actual": 496,     // when numeric
    "fix": { "selector": ".card", "property": "max-width", "value": "100%", "reason": "…",
             "kind": "exact" },     // exact = apply `selector { property: value }` verbatim;
                                    // heuristic = direction only (value may be a placeholder);
                                    // runtime-patch = see below
    "owner": {                     // PROVENANCE: the runtime construct that owns this element
        "construct": "style",      // style | geometry | tokens | sync | ratio | breakpoints
        "behavior": ["width: fluid"],
        "source": "src/cards.ts:12",  // best-effort call site
        "via": ".site-nav"            // only when the construct owns an ANCESTOR: the manifest
                                      // target that matched (element ".site-nav a[3]" is owned
                                      // through its ".site-nav" construct)
    },
    "owners": [ /* present when SEVERAL constructs own the element — same shape,
                   most specific first; `owner` is always owners[0] */ ]
}
```

### The runtime-patch fix

When the owning construct controls the very property a fix would patch, the fix arrives as
`kind: "runtime-patch"` instead — a CSS patch there would be overwritten by the runtime:

```jsonc
{
    "kind": "runtime-patch",
    "selector": ".hero", "property": "font-size", "value": "14px",
    "construct": "style",
    "source": "src/hero.ts:3",
    "change": {
        "property": "fontSize",
        "current": { "value": "fluid", "min": 10, "max": 28 },  // the declaration as written
        "suggested": "14px"                                     // CSS value that satisfies the constraint
    },
    "reason": "'font-size' is controlled by the style construct at src/hero.ts:3 — …"
}
```

Mechanical recipe: open `source`, find the construct call, recompute its parameters so the
declaration satisfies `suggested` (here: raise the fluid `min` from 10 to 14). Never patch the
CSS for these.

### Agent loop

1. `rjs analyze <url> -f json` (or `verify` against a contract).
2. Apply every `fixes[]` entry verbatim as `selector { property: value }` — the list carries
   only `kind: "exact"` fixes, already deduped. No value parsing, no judgment needed.
3. For `fix.kind: "runtime-patch"`: edit the construct declaration at `fix.source` using
   `fix.change` (current config + the CSS value that would satisfy the constraint). Never
   patch the CSS for these — the runtime would overwrite it.
4. For everything else — violations with `fix.kind: "heuristic"` (a direction, not a patch)
   or no `fix` at all: reason from `detail` + `expected/actual` (+ the
   rule's `ruleDescription` in contract mode — it states WHY the rule exists).
   **If the violation has an `owner`, patch the CONSTRUCT, not the CSS** — same logic as
   runtime-patch, without the precomputed change.
5. Re-run. Stop at exit 0. Never claim success without the exit code.
6. Contract mode, after an APPROVED visual change: `rjs record` re-pins baselines.
7. On a page with constructs but NO contract yet: `rjs init <url> -o app.contract.json`
   generates one FROM the manifest (fluid → monotonic+continuous+baseline, ratio →
   proportion, breakpoints → viewport widths; stderr lists what could not be expressed),
   then `rjs record` pins the curves.

## ContractReport (verify -f json)

```jsonc
{
    "contract": { "name": "home", "version": 1 },
    "pass": true, "total": 6, "passed": 6, "failed": 0,
    "rules": [ { "ruleId": "no-bleed", "assert": "noOverflow", "pass": true, "checks": 3,
                 "skipped": false, "violations": [] } ],
    "violations": [ /* Violation + ruleId + ruleDescription */ ],
    "score": [ /* {metric, min, actual, pass, width?} */ ],
    "baselines": [ /* {selector, prop, pass, unrecorded?, deviations[]} */ ]
}
```

## Contract skeleton

```jsonc
{
    "name": "home", "version": 1,
    "viewport": { "widths": [320, 768, 1280] },          // or {from,to,step}
    "selectors": { "sidebar": ".app-sidebar" },          // $sidebar aliases in args
    "designSystem": { "profile": "material-design-3" },  // apple-hig | fluent-ui-2 | inline config
    "rules": [
        { "assert": "noOverflow", "description": "why this matters", "severity": "error",
          "when": { "max": 767 }, "id": "stable-id" }
    ],
    "score": [{ "min": 0.6 }],
    "baselines": [{ "selector": "h1", "prop": "fontSize", "tolerance": { "px": 2 } }]
}
```

JSON Schema (validate before use):
[`design-contract.v1.json`](https://github.com/AleSaiani/ResponsiveJS/blob/main/packages/contract/schema/design-contract.v1.json).
Unknown assert names / args fail at load with did-you-mean suggestions.

Guarantees: selector-less (global) rules like `noOverflow` sweep a landmark default set —
a contract of only global rules still measures real elements. A run that performed ZERO
checks never passes: it fails with a `contract.noChecks` error violation. Treat that as
"my targets don't exist on this page", not as success.

## The 27 constraints

| assert | args | meaning |
| --- | --- | --- |
| `noOverflow` | — | No element exceeds the viewport width at any measured width. Naked overflow = error; inside a scrollable/clipping ancestor = warning (detail says which). |
| `contains` | parent:selector, child:selector | Child rects stay inside the parent rect. |
| `sameHeight` | a:selector, b:selector, tolerance?:number | Two elements keep equal heights. |
| `sameLine` | a:selector, b:selector | Two elements share the same visual row. |
| `minSize` | selector, min:{width?,height?} | Elements meet minimum dimensions. |
| `gapUniform` | selector, threshold?:number | Spacing between children is uniform. |
| `monotonic` | selector, prop:enum, direction?:enum | A property never moves against the direction as width grows. |
| `continuous` | selector, prop:enum, maxJump:number | No sudden jumps in a property across widths. |
| `proportion` | a, b, bounds:{min,max} | Width ratio a/b stays within bounds. |
| `childrenContained` | selector, tolerance?:number | Direct children stay inside their container. |
| `childrenEqualWidth` | selector, tolerance?:number | Direct children keep equal widths. |
| `noZeroHeight` | selector | Elements never collapse to zero height while having width. |
| `touchTarget` | selector, min?:number | Touch targets ≥ min at mobile widths (default 24, WCAG 2.5.8 AA). Interactive = DOM semantics (native controls, roles, tabindex, not disabled) or cursor:pointer; inline prose links exempt; unrendered (0×0) skipped. |
| `textReadable` | selector | Font size and line-height stay readable. |
| `contrastRatio` | selector, level?:'AA'\|'AAA' | WCAG contrast, measured effective backgrounds. |
| `borderRadiusValid` | selector | Border radii stay consistent with element size. |
| `zStackOrder` | selectors:selector[] | z-index ordering matches the given selector order. |
| `typographyScale` | selector | Font sizes fit a modular scale. |
| `spacingTokens` | selector, tokens:number[] | Spacing values come from the token set. |
| `aspectRatio` | selector, ratio:number, tolerance?:number | Elements keep the given aspect ratio. |
| `focusVisible` | selector | Focusable elements have a visible focus affordance. |
| `noHiddenOverflow` | selector | Content is not silently clipped by overflow:hidden. |
| `alignedToGrid` | selector, gridSize:number | Element positions align to a px grid. |
| `breakpointSafe` | breakpoints:number[] | Layout holds just below and above each breakpoint (bp±1 sampled automatically). |
| `interactiveSpacing` | selector, minGap?:number | Interactive elements keep a minimum gap. |
| `visible` | selector | Present and rendered (display/visibility/area). |
| `hidden` | selector | Absent or not rendered. |

## Library-level (custom loops)

```typescript
import { EvalSource, chunkedEval, analyze, verifyContract, contractSweepPlan } from '@responsivejs/design';
```

- `EvalSource(evalFn, { setViewport?, open? })` — any string-eval primitive becomes a driver;
  wrap `chunkedEval(evalFn)` when the transport caps argument length (Windows ~32K).
- Without `setViewport` the source REFUSES widths that don't match the live viewport
  (`currentWidth()` gives the honest one). Measurements never lie.
- `analyze({ source, url?, selectors, widths, a11y?, constraints? })` → UnifiedReport.
- `contractSweepPlan(contract)` → `{selectors, widths, height?}` to sweep any source, then
  `verifyContract(contract, store)`.
- Determinism: same store in → same report out. Scores and contrast are computed from measured
  values, never sampled.