concertina 0.10.0 → 0.11.0

package/README.md

@@ -12,13 +12,13 @@
   <a href="https://github.com/ryandward/concertina/actions/workflows/ci.yml"><img src="https://github.com/ryandward/concertina/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
 </p>
 
-<p align="center"><b>66 tests</b> &middot; ~900 lines of source &middot; 1 dependency</p>
+<p align="center"><b>92 tests</b> &middot; ~1200 lines of source &middot; 1 dependency</p>
 
 ## The problem
 
-Layout shift happens when the browser changes the size of a box and moves everything else to compensate. A button swaps for a stepper — the text next to it reflows. A spinner becomes a table — the page jumps. An accordion opens — the thing you clicked scrolls off the screen.
+Layout shift happens when the browser changes the size of a box and moves everything else to compensate. A button swaps for a stepper; the text next to it reflows. A spinner becomes a table; the page jumps. An accordion opens; the thing you clicked scrolls off the screen.
 
-The React ecosystem treats this as a state problem. Suspense, skeleton libraries, loading spinners — they model the transition between pending and loaded. They give you a nice-looking placeholder that's a completely different DOM structure from the real content, then act surprised when the swap causes a jump.
+The React ecosystem treats this as a state problem. Suspense, skeleton libraries, loading spinners: they model the transition between pending and loaded. They give you a nice-looking placeholder that's a completely different DOM structure from the real content, then act surprised when the swap causes a jump.
 
 It's not a state problem. It's a **structure problem.** The box changed size because you swapped the structure inside it.
 
@@ -26,309 +26,275 @@ It's not a state problem. It's a **structure problem.** The box changed size bec
 
 Don't swap structures. Swap what's inside them.
 
-Every tool in concertina addresses one of three kinds of instability:
-
-| Kind | What went wrong | Tools |
-|------|-----------------|-------|
-| **Spatial** | The box changed size | StableSlot, Gigbag, useStableSlot |
-| **Temporal** | The content loaded or animated | WarmupLine, Warmup, Glide, useWarmupExit, usePresence |
-| **Positional** | The viewport scrolled unexpectedly | Accordion, pinToScrollTop, useScrollPin |
-
-Structure is the contract. Content is what varies. If you internalize that, the API is obvious. If you don't, no amount of tooling will save you.
-
-## Install
+Concertina gives you three high-level components: **Bellows**, **Hum**, and **Ensemble**. They handle the math so you can focus on the music. CSS is auto-injected on first render. No manual imports needed.
 
 ```bash
 npm install concertina
 ```
 
 ```tsx
-// Stability primitives
-import { StableSlot, Slot, Gigbag, WarmupLine, Glide, useWarmupExit } from "concertina";
+import { Bellows, Slot, Hum, Ensemble } from "concertina";
+// That's it. No CSS import required.
+```
 
-// Accordion (Radix integration) — separate namespace
-import * as Accordion from "concertina/accordion";
+> SSR users: keep `import "concertina/styles.css"` in your server entry. Auto-injection runs on first client render, but SSR needs the styles before that.
+
+---
 
-// Styles
+## Before & after
+
+v0.11.0 replaces manual wiring with musical composition.
+
+**Before (v0.10)**: manual CSS import, boolean wiring, separate warmup plumbing.
+
+```tsx
+import { StableSlot, Slot, Gigbag, Warmup, useWarmupExit } from "concertina";
 import "concertina/styles.css";
+
+function Tabs({ activeTab }) {
+  return (
+    <StableSlot>
+      <Slot active={activeTab === "profile"}>
+        <ProfilePanel />
+      </Slot>
+      <Slot active={activeTab === "settings"}>
+        <SettingsPanel />
+      </Slot>
+    </StableSlot>
+  );
+}
+
+function UserList({ users, loading }) {
+  const { showWarmup, exiting } = useWarmupExit(loading, 150);
+  return (
+    <Gigbag axis="height">
+      {showWarmup ? (
+        <Warmup
+          rows={5}
+          className={exiting ? "concertina-warmup-exiting" : undefined}
+        />
+      ) : (
+        <div>{users.map(u => <UserCard key={u.id} user={u} />)}</div>
+      )}
+    </Gigbag>
+  );
+}
 ```
 
-The main entry exports all stability primitives. The `concertina/accordion` sub-path exports the Radix Accordion wrappers (Root, Item, Content, Header, Trigger, useExpanded) so they live in their own namespace. Both entry points are also available from the main `"concertina"` import for backward compatibility.
+**After (v0.11.0)**: named notes, no CSS import, no plumbing.
 
----
+```tsx
+import { Bellows, Slot, Ensemble } from "concertina";
 
-## Spatial stability
+function Tabs({ activeTab }) {
+  return (
+    <Bellows activeNote={activeTab}>
+      <Slot note="profile"><ProfilePanel /></Slot>
+      <Slot note="settings"><SettingsPanel /></Slot>
+    </Bellows>
+  );
+}
 
-The box changed size. Something swapped, grew, or shrank and everything around it moved.
+function UserList({ users, loading }) {
+  return (
+    <Ensemble
+      items={users}
+      loading={loading}
+      stubCount={5}
+      exitDuration={150}
+      renderItem={(u, i) => <UserCard key={u.id} user={u} />}
+    />
+  );
+}
+```
+
+Same stability guarantees. Half the code. Zero configuration.
+
+---
 
-### StableSlot + Slot
+## Bellows: spatial stability
 
 Two components swap in one slot. An "Add" button becomes a quantity stepper. The stepper is wider. The text next to it jumps left.
 
-The fix: don't swap them. Render both at the same time, in the same grid cell, stacked. The cell sizes to the bigger one. Toggle which one is visible. The box never changes size because both variants are always in there.
+The fix: render both at the same time, in the same grid cell, stacked. The cell sizes to the bigger one. Toggle which one is visible via named notes.
 
 ```tsx
-import { StableSlot, Slot } from "concertina";
-
-<StableSlot axis="width" className="action-slot">
-  <Slot active={!isInCart}>
-    <AddButton />
-  </Slot>
-  <Slot active={isInCart}>
-    <QuantityControl />
-  </Slot>
-</StableSlot>
+import { Bellows, Slot } from "concertina";
+
+<Bellows activeNote={isInCart ? "stepper" : "add"} axis="width">
+  <Slot note="add"><AddButton /></Slot>
+  <Slot note="stepper"><QuantityControl /></Slot>
+</Bellows>
 ```
 
 How it works:
 
-- `display: grid` on the container, `grid-area: 1/1` on all Slots. Everything overlaps in one cell.
-- Inactive Slots get `visibility: hidden` (invisible, still in layout flow) and `inert` (no focus, no clicks, no screen reader).
+- `display: grid` on the container, `grid-area: 1/1` on all Slots. Everything overlaps in one cell (the **chamber**).
+- Inactive Slots get the `inert` attribute: no focus, no clicks, no screen reader. CSS handles `visibility: hidden` and `opacity: 0` via the `[inert]` selector.
 - Each Slot uses `display: flex; flex-direction: column` so content stretches to fill the reserved width.
 - Zero JS measurement. Pure CSS. Works on the first frame.
 
-#### StableSlot props
+The `note` prop identifies a Slot. The parent `activeNote` determines which one is visible. Explicit `active={true|false}` overrides context when you need manual control. A bare `<Slot>` with neither prop defaults to visible.
+
+#### Bellows props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `activeNote` | `string` | | Which Slot to activate by `note` |
 | `axis` | `"width"` \| `"height"` \| `"both"` | `"both"` | Which axis to stabilize |
 | `as` | `ElementType` | `"div"` | HTML element to render |
-| `className` | `string` | | Passed to wrapper |
 
 #### Slot props
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `active` | `boolean` | Controls visibility |
-| `as` | `ElementType` | HTML element to render. Default `"div"`. |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `note` | `string` | | Identifier matched against `activeNote` |
+| `active` | `boolean` | | Manual override (takes precedence over `note`) |
+| `as` | `ElementType` | `"div"` | HTML element to render |
 
-All other HTML attributes are forwarded on both components.
+> `StableSlot` is an alias for `Bellows`. `SlotProps.active` is now optional.
 
 #### Rules for correct behavior
 
-Parent containers must allow content-based sizing. A StableSlot inside `grid-template-columns: 1fr 10rem` is trapped — the fixed column clips it. Use `auto`:
+Parent containers must allow content-based sizing. A Bellows inside `grid-template-columns: 1fr 10rem` is trapped; the fixed column clips it. Use `auto`:
 
 ```css
-/* StableSlot can't do its job in here */
+/* Bellows can't do its job in here */
 grid-template-columns: 1fr 10rem;
 
 /* now it can size itself */
 grid-template-columns: 1fr auto;
 ```
 
-Every independently appearing element needs its own StableSlot. An Undo link that only shows up in one state gets its own wrapper:
-
-```tsx
-<div className="action-column">
-  <StableSlot axis="width">
-    <Slot active={showDeliver}><Button>Deliver</Button></Slot>
-    <Slot active={showCharge}><Button>Charge</Button></Slot>
-  </StableSlot>
-  <StableSlot>
-    <Slot active={showCharge}>
-      <button className="undo-link">Undo</button>
-    </Slot>
-  </StableSlot>
-</div>
-```
-
-A single Slot inside a StableSlot is valid. It reserves the element's space, showing or hiding it without shift.
+Every independently appearing element needs its own Bellows. A single Slot inside a Bellows is valid. It reserves the element's space, showing or hiding it without shift.
 
-### Gigbag
+---
 
-```jsx
-if (loading) return <Spinner />;      // 48px
-if (empty)   return <EmptyMsg />;     // 64px
-return <BigTable data={data} />;      // 500px+
-```
+## Hum: temporal stability for text
 
-Three different structures, three different heights. Every transition jumps.
+A line of text loads from an API. You want a shimmer that's the exact width of the text it replaces. Not `100%`, not a guess.
 
-Gigbag is a container that remembers its largest-ever size via ResizeObserver and will not shrink. Put a spinner in there, then a table, then a spinner again — it stays at the table's height the whole time. Like a guitar case. You don't reshape the case every time you take the guitar out. It also uses `contain: layout style` so internal reflows don't bother the ancestors.
+Hum uses the **Inert Ghost** strategy: it renders your children inside the shimmer but marks them `inert`. The ghost text is invisible but present in the layout, giving the shimmer its intrinsic width. When loading finishes, the ghost is replaced by the real content. No width changes. No shift.
 
 ```tsx
-import { Gigbag, Warmup } from "concertina";
+import { Hum } from "concertina";
 
-<Gigbag axis="height">
-  {loading ? (
-    <Warmup rows={8} columns={3} />
-  ) : (
-    <DataTable data={data} />
-  )}
-</Gigbag>
+<h2>
+  <Hum loading={!user} className="text-xl font-bold">
+    {user?.name}
+  </Hum>
+</h2>
 ```
 
-#### Gigbag props
+The `className` is passed through to the shimmer so `1lh` inherits the correct font metrics. The shimmer is exactly as tall as the text it replaces because `1lh` resolves to the element's computed line-height. Not font-size, not a token, not a guess.
+
+#### Hum props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `axis` | `"width"` \| `"height"` \| `"both"` | `"height"` | Which axis to ratchet |
-| `as` | `ElementType` | `"div"` | HTML element to render |
+| `loading` | `boolean` | | Show shimmer (true) or children (false) |
+| `as` | `ElementType` | `"span"` | HTML element to render |
+| `className` | `string` | | Applied to both shimmer and content states |
 
-### useStableSlot
+> `StableText` is an alias for `Hum`.
 
-For content that changes size unpredictably (prices, names, status messages) where you can't enumerate all variants upfront. This is what Gigbag uses internally. Use it directly when you want a ref-based API instead of a wrapper component.
+---
 
-```tsx
-import { useStableSlot } from "concertina";
+## Ensemble: temporal stability for collections
 
-const slot = useStableSlot({ axis: "width" });
+A list loads from an API. You want shimmer rows while loading, then a smooth transition to real items, and the container must never collapse during the swap.
 
-<div ref={slot.ref} style={slot.style} className="price-amount">
-  {formattedPrice}
-</div>
-```
+Ensemble composes `Gigbag` (size ratchet) + `Warmup` (shimmer grid) + `useWarmupExit` (fade transition) into a single component.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `axis` | `"width"` \| `"height"` \| `"both"` | `"both"` | Which axis to ratchet |
+```tsx
+import { Ensemble } from "concertina";
+
+<Ensemble
+  items={orders}
+  loading={isLoading}
+  stubCount={5}
+  exitDuration={150}
+  renderItem={(order, i) => <OrderRow key={order.id} order={order} />}
+/>
+```
 
-Returns `{ ref, style }`. Attach both to the container element.
+The Gigbag ratchet remembers the largest-ever height. When shimmer rows fade out and real items mount, the container never shrinks below its high-water mark. No jump.
 
----
+#### Ensemble props
 
-## Temporal stability
-
-The content loaded or animated. Something appeared, disappeared, or transitioned between states and the layout jumped during the change.
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `T[]` | Data items to render |
+| `loading` | `boolean` | Show shimmer stubs when true |
+| `renderItem` | `(item: T, index: number) => ReactNode` | Render function for each item |
+| `stubCount` | `number` | Number of shimmer placeholder rows |
+| `exitDuration` | `number` | Exit animation duration in ms (match `--concertina-close-duration`) |
+| `as` | `ElementType` | HTML element to render. Default `"div"` |
 
-### WarmupLine — shimmer that inherits text metrics
+> `StableCollection` is an alias for `Ensemble`.
 
-This is the single most important thing in the library and the easiest to get wrong.
+---
 
-A shimmer line replaces text. It needs to be exactly as tall as the text it replaces. For 17 years, CSS had no unit for "one line of text." `em` is font-size, not line-height. `rem` is the root font-size. `px` is absolute. Every shimmer library picked a number — `height: 0.75em`, `height: 12px`, `height: 1rem` — and it was wrong, because text height is determined by line-height, which is determined by the font styles on the element. A shimmer that invents its own height is a shimmer that shifts layout when the real text arrives.
+## The stability contract
 
-CSS now has the `lh` unit. `1lh` resolves to the element's computed line-height. The shimmer uses `height: 1lh`. That's not a magic number — it's a relative unit that derives its value from the element's styles, the same way `100%` derives its value from the container's size.
+Nothing moves unless you want it to. Three strategies enforce this:
 
-But `1lh` only works if the shimmer has the right styles. A bare `<div className="concertina-warmup-line" />` inherits line-height from its parent. If it's inside a `<span className="text-sm">`, it inherits `text-sm`'s line-height. Correct. But if it's a direct child of a toolbar with no font context, `1lh` resolves against the default line-height. Wrong.
+**Inert Ghost** (Hum): children render inside the shimmer but are marked `inert`. The ghost provides intrinsic width. CSS hides it via `.concertina-warmup-line > [inert] { visibility: hidden }`. The shimmer is exactly as wide as the content it replaces.
 
-**The `WarmupLine` component exists so you can pass the text styles explicitly:**
+**Chamber** (Bellows): all Slots occupy the same CSS grid cell (`grid-area: 1/1`). The grid auto-sizes to the largest child. Inactive Slots are hidden via `[inert]` but remain in the layout flow, contributing their dimensions. The cell never shrinks.
 
-```tsx
-import { WarmupLine } from "concertina";
+**Ratchet** (Gigbag / Ensemble): a ResizeObserver tracks the maximum-ever size and applies it as `min-height` / `min-width`. The container can grow but never shrinks. Swap a spinner for a table; the container stays at the table's height.
 
-// Toolbar — no parent provides text styles, so pass them directly
-{loading
-  ? <WarmupLine className="text-sm text-stone flex-1" />
-  : <span className="text-sm text-stone">{count} customers</span>
-}
+---
 
-// Grid cell — parent wrapper provides text styles via inheritance
-<span className="table-val-primary">
-  {row._warmup
-    ? <div className="concertina-warmup-line" />
-    : row.name
-  }
-</span>
-```
+## Zero configuration
 
-In grid cells, the shimmer inherits from its wrapper (wrapper-once pattern). In standalone contexts like toolbars, pass the same `className` you'd put on the text element. The shimmer's `1lh` resolves against those styles and matches the text exactly.
+CSS is auto-injected via `useInsertionEffect` on first render. A `<style data-concertina>` tag is added to `<head>` once, idempotently. No build plugin, no import statement, no configuration.
 
-**Width** comes from the container, not the shimmer. In a grid cell, the column definition provides width. In a flex toolbar, pass `flex-1` so the shimmer fills the available space. The shimmer never invents a width — it fills whatever its context provides.
+The injection is SSR-safe: it checks `typeof document` and no-ops on the server. For SSR/SSG, keep `import "concertina/styles.css"` in your entry point so styles exist before hydration.
 
-> **vs. GitHub Primer's `SkeletonText`**
->
-> Primer uses `height: var(--font-size)` plus ~70 lines of manual leading math via CSS custom properties. It requires a `size` prop mapped to design tokens (`'bodyMedium'`, `'titleLarge'`). Each token is a hand-maintained record of font-size, line-height, and letter-spacing for that tier.
->
-> Concertina uses `height: 1lh` — one CSS declaration. `lh` is a relative unit that resolves to the element's computed line-height. Pass text styles via `className` and the shimmer inherits the correct metrics. No token mapping, no manual math, no `size` prop to keep in sync.
->
-> **Trade-off:** `lh` requires modern browsers (Chrome 109+, Firefox 120+, Safari 16.4+). Primer supports older browsers. If you need IE or pre-2023 Safari, Primer's approach is the right one. If your audience is on modern browsers, `1lh` eliminates an entire category of maintenance.
+---
 
-### The stub-data pattern
+## Lower-level tools
 
-Gigbag + Warmup works for flat containers. But when your content renders through structured components — an accordion with `Root > Item > Trigger > Content`, or a data table with cell wrappers — a separate loading skeleton is a different DOM structure. Different wrappers, different padding, different height. The swap from skeleton to real content shifts layout.
+The components above compose these building blocks. Use them directly when you need custom behavior.
 
-This is where the core principle applies directly. Don't build a separate loading path. **Pass placeholder data through the same render path as real data.**
+### Gigbag
 
-Create stub objects with the same shape as your real data, marked with a `_warmup` flag. Pass them to the same component that renders real data. Each cell renders shimmer or content inside the same wrapper:
+Size-reserving container. Remembers its largest-ever height (or width, or both) and never shrinks. Uses `contain: layout style` to isolate internal reflow.
 
 ```tsx
-// Stub data — same shape as real rows
-const STUB_ROWS = Array.from({ length: 8 }, (_, i) => ({
-  _warmup: true as const,
-  id: `warmup-${i}`,
-  name: null,
-  items: [],
-}));
-
-// Cell renderer — wrapper defined once, content varies inside it
-cell: ({ row }) => (
-  <span className="table-val-primary">
-    {row.original._warmup
-      ? <div className="concertina-warmup-line" />
-      : row.original.name
-    }
-  </span>
-)
-```
-
-#### The wrapper-once rule
-
-The wrapper is the structural contract — it determines padding, font-size, line-height, and therefore the cell's height. Define it once. Put the ternary inside it. Never write the wrapper in two branches.
+import { Gigbag, Warmup } from "concertina";
 
-```tsx
-// WRONG — wrapper duplicated, will drift apart silently
-if (row.original._warmup) {
-  return <span className="table-val-money"><div className="concertina-warmup-line" /></span>;
-}
-return <span className="table-val-money">${total}</span>;
-
-// RIGHT — wrapper defined once, content switches inside it
-<span className="table-val-money">
-  {row.original._warmup
-    ? <div className="concertina-warmup-line" />
-    : `$${total}`
-  }
-</span>
+<Gigbag axis="height">
+  {loading ? <Warmup rows={8} columns={3} /> : <DataTable data={data} />}
+</Gigbag>
 ```
 
-#### TypeScript enforcement
+### WarmupLine
 
-A discriminated union guarantees you check `_warmup` before accessing real data:
+Single shimmer line. Uses `height: 1lh`, where the CSS `lh` unit resolves to the element's computed line-height. Pass `className` to apply the same text styles as the content this shimmer stands in for.
 
-```ts
-type WarmupRow = { _warmup: true; id: string };
-type RealRow = { _warmup?: never; id: string; name: string; items: Item[] };
-type Row = WarmupRow | RealRow;
+```tsx
+import { WarmupLine } from "concertina";
 
-function renderCell(row: Row) {
-  return (
-    <span className="table-val-primary">
-      {row._warmup
-        ? <div className="concertina-warmup-line" />
-        : row.name  // TS narrows to RealRow here
-      }
-    </span>
-  );
-}
+<span className="text-sm text-stone">
+  {loading ? <WarmupLine className="text-sm text-stone" /> : `${count} items`}
+</span>
 ```
 
-TypeScript prevents you from forgetting the branch. The wrapper-once pattern prevents you from forgetting the wrapper. Use both.
-
-### useWarmupExit
-
-Manages the warmup-to-content transition. When `loading` goes from true to false, holds the warmup state for one animation cycle so shimmer lines can fade out before real content mounts.
+### Warmup
 
-```tsx
-import { useWarmupExit } from "concertina";
-
-const warmup = useWarmupExit(loading);
-const rows = warmup.showWarmup ? STUB_ROWS : realData;
-
-<div className={warmup.exiting ? "concertina-warmup-exiting" : undefined}>
-  {rows.map(row => /* same render path */)}
-</div>
-```
+Shimmer grid. Renders `rows` (x `columns`) animated bones.
 
-| Return | Type | Description |
-|--------|------|-------------|
-| `showWarmup` | `boolean` | True during loading AND exit animation — use for data selection |
-| `exiting` | `boolean` | True only during exit animation — use for CSS class |
+| Prop | Type | Description |
+|------|------|-------------|
+| `rows` | `number` | Number of placeholder rows (required) |
+| `columns` | `number` | Columns per row (optional) |
 
 ### Glide
 
-`{show && <Panel />}`. The panel is either in the DOM or it's not. When it enters, everything below shoves down in a single frame. When it leaves, everything snaps back.
-
-Glide wraps conditional content with enter/exit CSS animations and delays unmount until the exit animation finishes.
+Enter/exit animation wrapper. Delays unmount until the exit animation finishes.
 
 ```tsx
 import { Glide } from "concertina";
@@ -338,45 +304,9 @@ import { Glide } from "concertina";
 </Glide>
 ```
 
-When `show` goes true, children mount with a `concertina-glide-entering` class. When `show` goes false, they get `concertina-glide-exiting` and stay in the DOM until the animation finishes. Then they unmount for real.
-
-#### Glide props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `show` | `boolean` | | Whether the content is visible |
-| `as` | `ElementType` | `"div"` | HTML element to render |
+### Theming
 
-#### Customizing Glide timing
-
-```css
-.concertina-glide {
-  --concertina-glide-duration: 300ms;
-  --concertina-glide-height: 2000px; /* max-height ceiling for the animation */
-}
-```
-
-### Warmup grid
-
-For flat containers where the stub-data pattern is overkill. Renders `rows x columns` animated shimmer bones.
-
-```tsx
-import { Gigbag, Warmup } from "concertina";
-
-<Gigbag axis="height">
-  {loading ? <Warmup rows={8} columns={3} /> : <DataTable data={data} />}
-</Gigbag>
-```
-
-#### Warmup props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `rows` | `number` | `3` | Number of placeholder rows |
-| `columns` | `number` | `1` | Columns per row |
-| `as` | `ElementType` | `"div"` | HTML element to render |
-
-#### Theming
+All visual properties are CSS custom properties:
 
 ```css
 .concertina-warmup-line {
@@ -384,41 +314,45 @@ import { Gigbag, Warmup } from "concertina";
   --concertina-warmup-line-color: #e5e7eb;
   --concertina-warmup-line-highlight: #f3f4f6;
 }
-.concertina-warmup-bone {
-  --concertina-warmup-bone-gap: 0.125rem;
-  --concertina-warmup-bone-padding: 0.375rem 0.5rem;
-}
 .concertina-warmup {
   --concertina-warmup-gap: 0.75rem;
 }
+.concertina-glide {
+  --concertina-glide-duration: 300ms;
+}
+.concertina-content {
+  --concertina-open-duration: 200ms;
+  --concertina-close-duration: 150ms;
+}
 ```
 
-### Composing spatial + temporal
+---
 
-Gigbag and Glide solve different problems and they compose:
+## Advanced primitives
 
-```tsx
-{/* a form that animates in/out and doesn't collapse during re-renders */}
-<Glide show={isEditing}>
-  <Gigbag axis="height">
-    <EditForm />
-  </Gigbag>
-</Glide>
-```
+> These hooks are **deprecated** in favor of the components above. They remain exported for power users who need direct control.
+
+| Hook | Use component instead |
+|------|-----------------------|
+| `useStableSlot` | `<Gigbag>` or `<Bellows>` |
+| `useWarmupExit` | `<Ensemble>` |
+| `usePresence` | `<Glide>` |
+| `useTransitionLock` | `<Root>` (accordion) |
+| `useSize` | `<Gigbag>` |
+| `useConcertina` | `<Root>` (accordion) |
+
+All hooks are still importable from `"concertina"`. They have `@deprecated` JSDoc tags so your editor will show strikethrough.
 
 ---
 
 ## Positional stability
 
-The viewport scrolled unexpectedly. You opened an accordion item and the thing you clicked scrolled off the screen.
-
 ### Accordion
 
-Wraps Radix Accordion with scroll pinning, animation suppression during switches, and per-item memoization via `useSyncExternalStore`. The accordion components live in their own sub-path so they have a clear namespace:
+Wraps Radix Accordion with scroll pinning and animation suppression. Lives in its own sub-path:
 
 ```tsx
 import * as Accordion from "concertina/accordion";
-import "concertina/styles.css";
 
 <Accordion.Root className="my-accordion">
   {items.map((item) => (
@@ -434,127 +368,11 @@ import "concertina/styles.css";
 
 When you switch between items, the new one pins to the top of the scroll container. Animations are suppressed during the switch and restored after paint.
 
-`useExpanded(id)` is a per-item expansion hook. Only re-renders when this specific item's boolean flips:
-
-```tsx
-import { useExpanded } from "concertina/accordion";
-
-function MyItem({ item }) {
-  const expanded = useExpanded(item.id);
-  // only re-renders when this specific item opens/closes
-}
-```
-
-#### Customizing accordion animation
-
-```css
-.concertina-content {
-  --concertina-open-duration: 300ms;
-  --concertina-close-duration: 200ms;
-}
-```
-
-If items near the bottom can't scroll to the top, add `padding-bottom: 50vh` to the scroll container.
-
-#### Legacy hook API
-
-For cases where you need to manage Radix Accordion directly:
-
-```tsx
-import { useConcertina } from "concertina/accordion";
-import * as RadixAccordion from "@radix-ui/react-accordion";
-
-const { rootProps, getItemRef } = useConcertina();
-
-<RadixAccordion.Root type="single" collapsible {...rootProps}>
-  <RadixAccordion.Item value="a" ref={getItemRef("a")}>
-    ...
-  </RadixAccordion.Item>
-</RadixAccordion.Root>
-```
-
-| Property | Type | Description |
-|---|---|---|
-| `rootProps` | `object` | Spread onto `Accordion.Root`. Contains `value`, `onValueChange`, `data-switching`. |
-| `getItemRef` | `(id: string) => RefCallback` | Attach to each `Accordion.Item` |
-| `value` | `string` | Currently expanded item (empty string when collapsed) |
-| `switching` | `boolean` | True during a switch between items |
+`useExpanded(id)` is a per-item expansion hook. It only re-renders when this specific item's boolean flips.
 
 ### pinToScrollTop
 
-Scrolls an element to the top of its nearest scrollable ancestor. Only touches `scrollTop` on that one container — never cascades to the viewport, which matters on mobile where `scrollIntoView` pulls the whole page. Automatically accounts for sticky headers.
-
-```tsx
-import { pinToScrollTop } from "concertina";
-
-pinToScrollTop(element);
-```
-
----
-
-## Primitives reference
-
-Lower-level hooks extracted from the components above. Use these when you need to compose your own stability solutions.
-
-### useTransitionLock
-
-Suppresses CSS transitions during batched state changes. Sets a flag synchronously (batched with state updates in React 18), auto-clears after paint.
-
-```tsx
-import { useTransitionLock } from "concertina";
-
-const { locked, lock } = useTransitionLock();
-
-const handleChange = (newValue) => {
-  lock();
-  setValue(newValue);
-};
-
-<div data-locked={locked || undefined}>
-  {/* CSS: [data-locked] .animated { transition-duration: 0s } */}
-</div>
-```
-
-### usePresence
-
-Mount/unmount state machine for enter/exit animations. This is what Glide uses internally.
-
-```tsx
-import { usePresence } from "concertina";
-
-const { mounted, phase, onAnimationEnd } = usePresence(show);
-// phase: "entering" | "entered" | "exiting"
-
-{mounted && (
-  <div className={`panel panel-${phase}`} onAnimationEnd={onAnimationEnd}>
-    {children}
-  </div>
-)}
-```
-
-### useSize
-
-Raw border-box size observation via ResizeObserver. Reports every resize — no ratchet, no policy. Use this when you need the actual current size for your own logic (breakpoints, conditional rendering, animations).
-
-```tsx
-import { useSize } from "concertina";
-
-const { ref, size } = useSize();
-
-<div ref={ref}>
-  {size.width > 600 ? <WideLayout /> : <NarrowLayout />}
-</div>
-```
-
-### useScrollPin
-
-Runs `pinToScrollTop` inside `useLayoutEffect` — after React commits the DOM but before the browser paints. Use this when a state change moves content and you need to correct scroll position synchronously.
-
-```tsx
-import { useScrollPin } from "concertina";
-
-useScrollPin(() => itemRefs.get(activeId), [activeId]);
-```
+Scrolls an element to the top of its nearest scrollable ancestor. Only touches `scrollTop` on that one container. Never cascades to the viewport. Automatically accounts for sticky headers.
 
 ---
 
@@ -562,29 +380,35 @@ useScrollPin(() => itemRefs.get(activeId), [activeId]);
 
 | Problem | Tool |
 |---------|------|
-| Two variants swap in one slot | StableSlot + Slot |
-| Text changes width unpredictably | useStableSlot (or CSS `tabular-nums` for numbers) |
+| Two variants swap in one slot | Bellows + Slot |
+| Line of text loading from API | Hum |
+| List loading from API | Ensemble |
 | Spinner replaced by loaded content | Gigbag + Warmup |
-| Accordion/table loading skeleton | Stub data through same render path + WarmupLine |
+| Accordion/table shimmer rows | Stub data + WarmupLine (wrapper-once pattern) |
 | Panel mounts/unmounts conditionally | Glide |
-| Shimmer lines that match text height | WarmupLine (uses `1lh`) |
-| Shimmer-to-content exit animation | useWarmupExit |
 | Accordion with scroll pinning | Accordion.Root + Item + Content |
-| Custom scroll correction | pinToScrollTop or useScrollPin |
 
 ---
 
-## Roadmap
+## Browser support
+
+Concertina targets modern browsers. The minimum floor is set by `1lh` (CSS line-height unit):
 
-Stability problems concertina could address in future versions:
+- Chrome 109+
+- Firefox 120+
+- Safari 17.2+
 
-- **Scroll anchoring** — When content above a target element changes (items prepended, banners inserted), maintain scroll position relative to the target. CSS `overflow-anchor` is inconsistent across browsers and doesn't cover programmatic insertions.
+The `inert` attribute shipped before `1lh` in every browser. No polyfills. No fallbacks. No bloat.
 
-- **Media reservation** — Reserve space for images/video before load via `aspect-ratio`. A thin wrapper that accepts `width`/`height` from an API response and prevents CLS. The browser's native `width`/`height` attributes help but don't cover dynamic aspect ratios or art-directed responsive images.
+---
+
+## Roadmap
 
-- **Focus stability** — When DOM mutations remove the focused element, trap focus to the nearest surviving ancestor instead of resetting to `<body>`. The `inert` attribute on inactive Slots partially addresses this for StableSlot, but general-purpose focus recovery during list reorders or filtered views is unsolved.
+- **Scroll anchoring**: maintain scroll position when content above a target changes.
+- **Media reservation**: reserve space for images/video via `aspect-ratio` before load.
+- **Focus stability**: trap focus to nearest surviving ancestor when DOM mutations remove the focused element.
 
-These are proposals, not commitments. If any of these would unblock your project, open an issue.
+These are proposals, not commitments. If any would unblock your project, open an issue.
 
 ## License