plass-ui 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,674 @@
 
 > This package's history. The Flutter package keeps its own at [`packages/flutter/CHANGELOG.md`](https://github.com/jooy2/plass-ui/blob/main/packages/flutter/CHANGELOG.md), because the two version independently.
 
+## 1.4.0 (2026-09-05)
+
+### Added
+
+- **`PlWindowPane`.** A window, drawn the way one of eight systems draws it, with anything at all inside it.
+
+  It is not a real window and does not pretend to be one: there is no desktop, no z-order and no dock. What it is is a _frame that behaves_ — the title bar drags, the corners resize, the three buttons are real buttons with real names — so a screenshot of an app, a demo of a feature or a piece of a landing page can be shown as the thing it will be rather than as a picture of it.
+
+  **Nothing here is transformed.** A dragged window moves on `left`/`top` and a resized one changes `width`/`height`, which keeps the text inside it at whole pixels through both gestures: a `translate()` would resample every glyph in the window for the length of the drag, which is exactly what the house rule against transforming a surface exists to prevent.
+
+  `os` covers `macos`, `macosx` (Aqua), the five Windows the title bar actually changed on, and `linux`. Which buttons a window has is the caller's decision; what order they sit in is the system's. `minimize` rolls the window up to its title bar rather than sending it anywhere, because a page has nowhere to send it — the content stays in the tree, marked inert.
+
+  `size` scales the chrome and nothing else, which makes this the third component after `PlBox` and `PlMockup` where the ladder is not a control height. Left out, `active` works itself out: a window is in front until another one on the page is pressed or takes the focus, and a click on the page _around_ them changes nothing.
+
+  Nothing drawn is a copy of any of those systems: a bar, a border and three buttons at the proportions they used, and no mark, wordmark or icon belonging to anyone else.
+
+- **`internal/drag`**, the scaffold every pointer drag needs and none of the arithmetic: three listeners, a `data-dragging`, the document's text selection taken for the length of the gesture, and a teardown an unmount can call.
+
+- **Four words in `PlassLabels`** — `minimize`, `maximize`, `restore` and `resizeWindow` — translated in all six locale bundles.
+
+- **`PlMockup`.** A device with a screen you can put anything on: a phone, a tablet, a monitor or a laptop, with the system's own bars drawn on it.
+
+  **The screen is a real viewport at the device's own resolution** — an `md` phone is 390 by 844 — and the whole device is then scaled once to whatever room it has been given. So the content inside is laid out against a _screen_ rather than against the page: a 390-pixel column wraps where it would wrap on a phone, and the mockup can be 200 pixels wide without the content knowing.
+
+  That scale is the one `transform` in the library. The rule it excepts is about controls, where a scale resamples the label under the pointer pressing it; nothing here is pressed, and the scale is set once from the space available rather than changing on an interaction.
+
+  `size` sets the **resolution** rather than a height or a type scale — the second component after `PlBox` where the ladder means something other than a control height. The system's bars each take their own space rather than covering the content, because a caller putting a screenshot in a mockup wants all of the screenshot; the cut-out is the exception, being a real hole in the glass, and is drawn whether or not `systemUi` is on.
+
+  `bezel="none"` is no hardware at all rather than a thinner frame, and `finish` is fixed colours rather than theme tokens: a graphite phone is graphite on a page switched to dark. Landscape turns the screen, the bezel and the cut-out together; a desktop ignores it, because its stand does not turn.
+
+  The reference data — five resolutions per device, three shells, six systems' worth of chrome — lives in `internal/mockup`, for the reason `internal/chart` does.
+
+- **`PlTimelineChart`.** Work against time — a row per thing, a bar per stretch of it.
+
+  The two axes are a set of rows and a calendar, which makes this a `PlBarChart` turned on its side with the baseline taken away: every bar starts where its own data says rather than at zero, so what the chart is about is _when_ rather than _how much_. It is not `PlTimeline`, which is a list of steps and draws no axis at all.
+
+  A row takes `PlassTimelineSeries`, whose data are spans rather than values. There is **no legend and no `hidden`**: the rows are the category axis, already named down the side, and a twenty-entry legend restating them is not a filter anyone wants.
+
+  Overlapping spans on one row are moved onto lanes of their own, by the greedy interval packing every scheduler uses. A row with no overlaps stays in a single lane, so the common row is exactly as thick as it was. Lanes are assigned in _start_ order but stored against the span's original index, because that is the order the arrow keys walk and a layout decision must not reshuffle it.
+
+  A span is cut to the plot rather than to the data: a bar that runs past a pinned `min` stops at the edge and says there is more of it off the side, where one drawn past the edge would say the axis is wrong. A zero-width span keeps a hairline, so a milestone is still something on the row. Both ends round, unlike a bar chart — neither end of a span is a zero.
+
+  The table under it is a row per span rather than the usual grid, because two rows of a Gantt have no columns in common.
+
+- **`PlassTimelinePoint`** and **`PlassTimelineSeries`** in `src/types.ts`.
+
+- **`PlHeatmapChart`.** A magnitude per cell, coloured rather than measured.
+
+  Two shapes of one idea. A `grid` is for two categorical axes and one magnitude — which hour of which day, which cohort in which week — where a bar chart of the same data would be forty bars nobody can scan. A `treemap` is for parts of a whole with more parts than a `PlPieChart` can hold, and it is the same component because the data is the same shape: a row of a heatmap and a group of a treemap are both a named series of named magnitudes.
+
+  **Colour here encodes size and not identity**, so it comes off a one-hue ramp rather than the categorical palette. One ladder covers the whole chart rather than one per row, because the colour of a cell has to mean the same number wherever it is — which is the entire promise a heatmap makes.
+
+  `scale="diverging"` is for a value with a _middle_ that means something. It is read from that middle rather than from the bottom, and both arms reach as far as the further one, so a set running from −2 to +40 does not paint every negative the deepest blue there is.
+
+  The treemap packing is squarified rather than sliced: a slice-and-dice treemap of twenty values ends in slivers a pixel wide, and a sliver's area is unreadable however exact it is. A tile's area is its share, so a negative value stays in the table and off the picture.
+
+  A label that does not fit its cell is dropped rather than clipped — a missing label sends the reader to the tooltip and a clipped one sends them nowhere.
+
+- **`PlGaugeChart`.** One number on a scale that is known in advance, drawn as a dial.
+
+  It is a `PlMeter` bent into an arc, and the two are deliberately the same idea in two shapes: `value`, `min`, `max` and `thresholds` mean exactly what they mean there, so a page can move a reading from a bar to a dial without changing what it says. It is **not** a `PlPieChart` with `shape="semi"` — a pie is parts of a whole and every slice is a category, while this is one value against a scale and the unfilled arc is the rest of the dial rather than a second category.
+
+  `sweep` is degrees opened symmetrically about twelve o'clock: `180` for a dashboard tile, `270` for the instrument shape, `360` for a ring. The dial is sized against the box rather than assuming a circle, because how far it reaches _below_ its centre depends on the sweep — which is what keeps a wide, short card from drawing a thin band with an empty half above it.
+
+  The reading is **real text rather than a label painted into the drawing**, so it can be selected and found, and its size is solved against the room the hole actually leaves rather than fixed: `38` and `10,000%` are the same prop. The arc travels to a new value as a _length_ — a stroke's drawn fraction — because an outline is not a property CSS can transition, and a dial that scaled would resample the numbers written across it.
+
+  `ticks` is off by default. A gauge on a dashboard is read as a proportion, and rim marks are for an instrument somebody takes a number off. `showRange` is dropped past 330° whatever it says, because by then the two ends have come within a label's width of each other.
+
+- **`PlassThreshold`**, in `src/types.ts`, and the band rule behind it in `internal/threshold`. `PlMeter` and `PlGaugeChart` now read the same list the same way, which is what stops a quota turning `danger` on a bar but not on the dial beside it. `PlMeterThreshold` is unchanged as a name — it is an alias of the new one, so nothing a caller imports has moved.
+
+- **`PlSparkline`.** A chart with everything taken away except the shape.
+
+  No axes, no grid, no legend, no tooltip. It is not a small chart, it is a different thing: a word-sized picture that goes inside a sentence, beside a `PlStat`, or in a table cell, and says which way something has been going. Every number it could label is one the surrounding text already has, which is why it labels none of them.
+
+  `shape` is `line` for a trend, `area` for a quantity or `bar` for a count of discrete things — the same three sentences the full charts say, at a size where nothing else is being said at all.
+
+  **It scales itself to its own range, so the strip is always full.** That is what makes it readable at twenty pixels tall, and it is also the trap: two of them side by side are on two different scales, so the one that climbs more steeply may be the smaller number. `min` and `max` are how a row of them becomes small multiples instead.
+
+  `baseline` draws a rule across the strip and is pulled into the range if it sits outside the data. `endDot` marks the last point that is _a point_, not the last slot; bars do not take it, because a bar already ends where it ends. The colour is given directly rather than off the palette — one series and no legend leaves nothing to hand out.
+
+  Without a `label` the strip is taken off the accessibility tree entirely, because an unlabelled image announced as an image is noise beside text that already has the numbers. With one it is a named `role="img"` and the values are written out beside it.
+
+- **`PlScatterChart`.** Two numbers per point, and whether they move together.
+
+  Both axes measure, which makes this the only chart in the library with no categories: there is no column a mark belongs to and no order the points could be shuffled out of. A point with a `z` is drawn as a bubble and one without it as a dot, so a scatter and a bubble chart are the same component reading the same data.
+
+  A `z` is an **area** and not a radius. Encoded as a radius, a value twice as large draws a mark four times the size; the square root keeps the ink proportional to the number. One scale covers the whole chart and is taken over every series including the hidden ones, so switching a legend entry off does not resize the rest. Bubbles paint largest first, because a small one inside a big one is otherwise invisible and the usual fix — half alpha everywhere — would undo the contrast the palette was solved for.
+
+  `shape="auto"` draws circles while colour alone can carry identity and switches to a shape per series from the fourth on. **That threshold is measured against this library's own palette, not inherited**: taking the first three slots, the closest pair under deuteranopia is ΔE 64 on the light sheet and 51 on the dark one; add the fourth and those fall to 4.9 and 2.8. A series carrying its own `color` does not count against it.
+
+  The table under the chart is a row per point rather than the usual grid — two points that are both the fifth of their series have nothing to do with each other, and a shared row would invent a relationship. Its columns take the axis labels, falling back to `x`, `y` and `z`.
+
+- **`PlPieChart`.** Parts of a whole, at a glance.
+
+  The narrowest chart in the library and the easiest one to misuse. An angle is a poor thing to compare — two slices within a few percent of each other are indistinguishable, and a reader cannot rank six of them — so the pie is right for exactly one question: _is one of these most of it?_ Anything finer, and anything past six slices, is a `PlBarChart`.
+
+  It takes **one list of slices rather than a list of series**, because that is what a pie is: the slices are the entities here, so each takes a palette slot of its own and the legend lists them. The colour follows the slice and not its size, so a chart that is refiltered or resorted keeps every category the colour it had.
+
+  A `null` and a zero are both left undrawn. Neither has an angle, and a slice of no width is a slice a reader cannot point at.
+
+  `shape` is `pie`, `donut` or `semi`. A `semi` takes the **whole** height as its radius rather than half of it, because it only draws the top half — reserving room for the bottom would leave a blank band under the chart — and its centre then sits half a radius below the middle, which is what puts the arc in the middle of the tile.
+
+  `valueLabels="all"` writes each slice's **share** and not its value: a share is what a pie is a picture of, and the value is one hover away. A label wider than the slice it belongs to is dropped rather than clipped, so it can never end up sitting over the neighbour it would then be labelling. The gap between two slices is a constant on screen rather than in the data, so it subtends a wider angle on a small pie than on a large one.
+
+  The plot is a tab stop and the arrow keys walk the slices, with the value announced in a live region as the focus moves. Everything else — the legend, the tooltip panel and the hidden table — is the same frame every other chart uses.
+
+- **`PlBarChart`.** Lengths, compared.
+
+  A bar says _how much_, and it says it by being longer — which is the whole reason its axis starts at zero and cannot be talked out of it. Crop the scale and a bar twice as long stops meaning twice as much, and the reader has no way to know it happened.
+
+  A `null` is a gap and the bar is simply **not drawn**, which matters more here than anywhere: a zero-length bar and a missing bar are the same picture, and only one of them is honest.
+
+  `orientation="horizontal"` is the right answer whenever the category names are words — it has a whole column for them where a vertical chart has the width of one bar — and everything swaps with it: which band each axis reserves, which way the grid and the crosshair run, and which end of a bar is rounded.
+
+  Grouped bars answer "which series is bigger here"; stacked bars answer "what is this total made of". They are different questions and the chart should be asked only one of them at a time. **The gap between two stacked segments is taken off the far end of each**, so the stack still totals the right length and the seam is the sheet showing through rather than a line drawn on it — a border around a bar is ink that is not data. The two arms accumulate separately, so a series that dips does not shorten the one above it, and the baseline is redrawn _over_ the bars because every one of them starts there.
+
+  `rounded` cuts the corners off the **data** end only: a rounded foot makes the axis look scalloped.
+
+- **`PlAreaChart`.** A line with the space under it filled — which changes what the chart is about.
+
+  A line says where a value went. An area says how much of something there _was_, and stacked it says how that amount was made up. That is the whole test for reaching for it instead of a `PlLineChart`: if the quantity does not add up to anything — a temperature, a rate, a score — the fill under it is decoration, and a chart with two of them is two washes fighting.
+
+  Unstacked bands are a **wash fading downward**, so two of them overlapping stay readable and the line along the top is what carries the value. Stacked bands take a flatter, opaquer tint, because there the fill _is_ the mark and a band that faded out would have no bottom edge — and a stacked band is deliberately **not** also given a line along its top, since a stroke between two marks is ink that is not data.
+
+  `stacked="full"` normalises every category to a hundred, so the chart stops being about size and starts being about **share**. The normalising is a change to the _data_ rather than to the drawing, which is what lets the axis, the tooltip and the table all agree that the number is a share — and the tooltip still carries the number the caller passed, because a chart that can only tell you percentages has thrown the data away.
+
+  **The baseline is always zero**, which is the one axis rule it does not share with the line chart: an area's fill is its magnitude, so a cropped scale makes the band's thickness meaningless.
+
+  Measured with `npm run size`: **−0.1 kB on the whole library** and nothing anywhere else. The component is forty lines on top of the frame and the line painter that shipped with `PlLineChart`; the difference is compression noise, and it is what the foundation was for.
+
+- **`PlLineChart`, and the foundation every chart after it stands on.** A value against time, or against anything else with an order to it.
+
+  The line is the mark that says _change_: it claims the space between two points is a journey rather than two separate facts, which is true of a temperature and false of four product categories.
+
+  **A `null` is a gap and never a zero** — a sensor that was offline, a month that has not closed yet. The line breaks across it, and a point with a gap either side is drawn as a dot rather than dropped. A chart that renders missing data as zero reports an outage as a collapse; `connectNulls` bridges it and should stay off unless the gap is an artefact of collection.
+
+  `curve="smooth"` is a **monotone cubic and not a spline**. A plain spline overshoots between two close points, so a series that never goes below zero draws a curve that does: a chart is allowed to be curved and it is not allowed to show a value that is not in the data.
+
+  **The value axis leaves zero out, and a bar chart's will not.** A line encodes a _position_, so cropping the scale moves every point by the same amount and the shape survives; a bar encodes a _length_, which stops meaning anything the moment it starts from 98.
+
+  The palette is **eight hues in a fixed order** — `--plass-chart-1` through `-8` — and it is the one place in the library where a colour is not a semantic role: a series is an entity, not a severity. Every slot clears 4:1 on the light surface and 4.9:1 on the dark one, and adjacent pairs are at least 10.4 apart in OKLab under simulated protanopia and deuteranopia, which is the pair that touches in a stack or a legend. Slot one is the page's own `primary`, so a one-series chart looks like it belongs. **Slots follow a series' index in the array it was passed**, never its position among the visible ones: a reader who learned that Europe is blue has learned something a filter is not allowed to take back. There are also a five-step sequential ramp and a five-step diverging one, for a mark whose colour is a magnitude rather than an identity.
+
+  Two internals arrive with it and are the reason the next eight charts are small. `internal/chart.ts` is the arithmetic — scales, nice numbers, band scales, path building, colour — and knows nothing about React or SVG. `internal/chart-frame.tsx` is everything a chart draws that is _not_ its marks: the axes, the grid, the crosshair, the legend, the tooltip, the empty state, the hidden table a screen reader reads instead of the picture, and the measurement that turns a percentage width into the pixels an SVG needs.
+
+  One new label, `chart`, in all seven packs.
+
+  Measured with `npm run size`: **+8.4 kB on the whole library and +0.0 kB on all four other scenarios** — the foundation is most of it, and the eight charts after this one pay for it once.
+
+- **`PlGallery`.** A set of pictures, arranged — four layouts, captions, a pointer treatment and an optional lightbox, with everything but the arrangement identical across all four.
+
+  `grid` is a contact sheet: every tile the gallery's own ratio, whatever shape the file is. `masonry` keeps each picture's proportion and stacks the columns. `justified` keeps the proportions **and** fills every row to the edge — the only arrangement where nothing is cropped and no space is left over. `quilted` is a grid whose tiles span more than one cell, packed densely so a tile too wide for the space left drops to the next row that fits it and a later, narrower one fills the hole.
+
+  **Nothing is measured.** Every layout runs off the item's own `ratio`, so a wall of forty photographs is right in the frame the browser first paints and never reflows as the files arrive — the bargain `PlImage`'s `ratio` makes, one level up.
+
+  A masonry **deals across before it deals down**. CSS `columns` fills the first column top to bottom before it starts the second, so a set numbered 1 to 12 reads down the left edge and the first three pictures a reader meets are stacked on top of each other. The dealing is in `internal/gallery.ts` because the Dart build needs the same answers: a masonry with two orders is a masonry whose order means nothing.
+
+  `caption` is `below`, `overlay` or `hover`, and a tile with no words draws none whatever it says — a row with one caption and three gaps is worse than a row with none. `hover` is `lift`, `dim` or `zoom`, and `zoom` is the design language's named exception to the no-transform rule: what moves is a photograph inside a frame that stays exactly where it was, with no text on it to resample.
+
+  `preview` opens a lightbox with the rest of the set an arrow key away, behind a `React.lazy` so a wall of thumbnails costs nothing for a viewer nobody opened. It is deliberately not a `PlCarousel` — no autoplay, no wrap, and the arrows stop at the ends rather than looping back to a photograph the reader has already seen.
+
+  A tile is a button only when pressing it does something, and its name is the picture's own words plus where it sits — "A harbour — 1 of 6". `itemLabel` is how that sentence is written in another language, and it is a callback rather than a string with slots because the word order differs. One new label, `gallery`, in all seven packs.
+
+  Measured with `npm run size`: **+4.0 kB on the whole library**. The four narrower scenarios moved too, by 0.2 to 1.9 kB, and none of them contains a line of gallery code — checked against esbuild's own metafile. A second lazily-loaded module changes how the bundler splits the chunk the entry pulls in, which is also why `scripts/size.mjs` changed in this commit: it now builds with splitting on and counts the entry chunk plus every chunk statically reachable from it, rather than inlining every `import()` whether or not the module that made it survived tree-shaking.
+
+- **`PlCodeBlock`.** A viewer for one line of code or a thousand — a bar over it, numbers down the side, a prompt in front of every line, and twelve palettes to read it in.
+
+  Everything it draws above the code is optional and off one prop each, because the same component has to be a snippet inside a sentence — no bar, no numbers, no chrome — and the full transcript at the top of a README.
+
+  **It is the one surface in the library that is not made of glass.** Every other sheet here is translucent and takes the page's colour family; this one paints its own opaque ground and refuses the family entirely, because the palette is the subject rather than the setting. A Dracula block tinted `primary` would be a Dracula block nobody chose.
+
+  Twelve themes: four the house's — `dark`, which is the default and the one that is not a preference, since code has been read on a dark ground since terminals; `light`; `auto`, the opt-in for a block that would rather follow the page; and `mono`, which has no hue in it at all and carries the structure by weight — and eight ports kept at the hex they were published in. `theme` takes **any string**, so a `[data-code-theme='ours']` block of custom properties is a theme with nothing to register and nothing to import. Sixteen slots, five of them derived from the other two.
+
+  **The line numbers and the prompt are generated content**, and that is the whole point of drawing them that way: a `$` a reader drags across and pastes into their shell is a `$` their shell chokes on. Neither can be selected, found by find-in-page, or copied.
+
+  **`highlight.js` is the package's second runtime dependency**, and it is reached only through a dynamic import — the core plus one module per language, thirty-five of them, never the package root. A page that imports `PlCodeBlock` and never highlights anything downloads none of it, and a page that highlights TypeScript downloads the core and TypeScript and not the other thirty-four. It is a real `dependencies` entry rather than an optional peer because a specifier a bundler cannot resolve fails the _whole_ build, not just the part that would have used it. Dart is in the built-in set, which highlight.js's own "common" list leaves out and half of this project's pages are written in.
+
+  Five new labels — `copy`, `copied`, `copyFailed`, `raw` and `code` — in all seven packs.
+
+  Measured with `npm run size`: **+3.2 kB on the whole library and +0.0 kB on all four other scenarios**. The grammars are not in that number and are not meant to be: they are chunks an `import()` fetches, one language at a time, and `scripts/size.mjs` now bundles with splitting on and counts only the chunk a page loads to render.
+
+- **`PlTreeSelect`.** A value chosen out of a hierarchy rather than out of a list — a `PlTree` behind the same field every other picker wears.
+
+  It is the two of them composed and almost nothing else. The trigger is `PickerShell`, the popup is a `PlTree` with a `PlTextField` over it, and what the component adds is the arithmetic between them: which nodes a query keeps, which branches that opens, and which of the ids coming back out of the tree are answers rather than roads.
+
+  **`selectableBranches` is off by default**, which is the shape most of these trees actually have: the branches are the taxonomy and the leaves are the answers, and a "Europe" held alongside "France" is usually a data model nobody meant. A node's own `selectable` overrides it either way, and a branch that cannot be chosen still opens and closes — pressing it is how you get at what is under it.
+
+  Which is why **turning a branch press down is not the same as clearing**. A single-value tree hands back exactly one id, so treating an unusable one as an empty answer would empty the field every time somebody opened a folder. The press is dropped and what is held stays held.
+
+  `searchable` keeps every match **and every ancestor of one**. A tree filtered to bare matches is a list, and a list of leaves is exactly what a tree was chosen over — a "Seoul" with nothing above it does not say which taxonomy it came out of. Every branch the filter kept is opened, since a match folded inside a shut parent is a match nobody was shown, and emptying the field hands the folds back to the reader untouched. The fold is `internal/search`'s, so `jose` finds `José` here exactly as it does in a `PlCommandPalette`.
+
+  `multiple` keeps every node a press adds and leaves the popup up, because a picker that shut after the first of several answers would have to be reopened for each of the rest. `format` writes the trigger however the caller likes, and `name` puts one `<input type="hidden">` on the page per held id.
+
+  No new label: `search`, `empty` and `clear` were already words this library says.
+
+  Measured with `npm run size`: **+0.9 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlTour`.** A guided walk over a page that already exists — the three things a new reader has to be shown once, pointed at where they actually are.
+
+  It is `PlHowToSteps` turned inside out. That component puts the instructions _in_ the page and the reader follows them; this one leaves the page as it is and stands over it. So a step **says what it is about** rather than describing it: what a tour points at is already on screen, and a second copy inside the card is a second copy to keep in step.
+
+  **The dimming takes the pointer and the light does not**, and the whole component rests on it. The scrim is one layer over the viewport with the target cut out of it as a **clip** rather than as a painted hole, and a clipped-away region is not hit-tested — so the reader can use the control being pointed at and nothing else. That is the difference between a tour and a dialog with a picture of a control in it, and it falls out of the geometry rather than being a second mechanism that has to agree with it.
+
+  The same clip is why the dimming can **blur**. A hole drawn as a box shadow or as four rectangles around the target can only paint a colour; a clipped layer carries a `backdrop-filter`, so the page around the light is out of focus as well as dark — this library's own material rather than a grey wash over it.
+
+  `target` takes a **ref, a selector or a getter**, and the ref is the one to reach for: a selector is a string that stops matching the moment somebody renames a class, and the tour would go on running with the hole over an empty piece of background. The selector is offered because it is the only form that works for an element the page did not render.
+
+  Escape, the ×, Skip and Done are the only ways out. A press outside the card is ignored and so is the focus leaving it, because using the page is exactly what a tour is for. `open` and `step` are each controllable on their own, `onFinish` runs before the tour closes — which is where "this reader has seen it" goes — and the component remembers nothing itself.
+
+  The counter is **two numbers rather than a sentence**: "3 of 7" is a string that has to be translated and a word order that differs by language, and the count itself does not. One new label, `skip`, in all seven packs.
+
+  Measured with `npm run size`: **+1.5 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlDataTable`.** A table that owns its rows: it sorts them, narrows them to what was typed, hands them out a page at a time and remembers which of them are ticked.
+
+  `PlTable` stays exactly what it was, and the split is not a size decision. A table whose every column is a `render` callback is the one component in this library a React Server Component has to be able to render, and reading a context would take that away — so the component that has to remember four things between renders is a second component rather than a prop on the first.
+
+  **Below the columns they are the same grid.** The measured widths, the hover band, the rule between rows, the pinned header and every inline style that keeps a host stylesheet's `td { border: 1px solid }` off them now live in `internal/table.ts`, and both components draw out of it. Two copies of that is how the rows under a sorted table end up a shade off the rows under a plain one.
+
+  **Sort, search, selection and page are each uncontrolled by default and controllable one at a time.** That is what lets one component cover both of the tables people build: the ordinary one is `columns` and `rows`, and a table backed by a server is the same markup with `manual` and four handlers. Nothing in between changes shape.
+
+  **Sorting rotates ascending, descending, then back to the order the rows arrived in.** That third press is the part most tables leave out and it is the one that matters: the arrival order is usually the order the server chose, and a table that can never be put back has thrown it away. The mark is drawn faintly on every sortable heading rather than appearing under the pointer, because a heading that only looks pressable once you are on it is a heading nobody presses. Values are compared as what they are, text with `localeCompare` — sorting by code point puts every capitalised word above every lower-case one — and **nothing sorts last in both directions**, because a blank in a column of amounts is not the smallest amount.
+
+  A column's `value` is what the sort and the search see, where `render` is what the reader sees. Most columns need neither; the moment a cell is _drawn_ rather than printed the two come apart, and a total column printing `$1,240.00` sorts as a string that puts `$89` after it.
+
+  **The selection hands back rows from every page**, not from the page on screen, and the header box goes indeterminate when part of a page is chosen — a half-filled page under a plain unticked box reads as the opposite of what is true. Shift extends the range in the order the rows are _currently_ in, which is what a reader dragging down a sorted page means by "these". A chosen row carries `aria-selected` as well as the tint, and a press on the tick is not also a press on the row.
+
+  `aria-sort` goes on the **heading**, not on the button inside it: the heading is what a screen reader reads on entering a cell in that column. The sort control is a bare `<button>` wearing the heading's own type, because a `PlButton` there would be a control on a control — a background, a radius and a height inside a cell whose job is to sit flush against the rule under it.
+
+  Four things it deliberately does not do, and the page says so rather than leaving them to be looked for: it does not virtualize (the honest answer is `paging="pages"`, which is also the only shape that works when the rows are being fetched), it does not drag-resize or reorder columns (both need somewhere to persist what the reader dragged), it does not export (the application's data and the application's filename — `toolbar` is where the button goes), and it sorts on one column (a sort three keys deep is a query the reader cannot see).
+
+  One new label, `selectRow`, in all seven packs.
+
+  Measured with `npm run size`: **+2.8 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **Locale bundles: the library's own words, translated.** Every component that says something of its own — a close button's name, a pager's landmark, the line an empty list shows — now reads from one set of sixty-four strings, and seven translations of that set ship with the package.
+
+  ```tsx
+  import { PlassProvider } from 'plass-ui';
+  import { ko } from 'plass-ui/locales';
+
+  <PlassProvider locale="ko-KR" labels={ko}>
+    <App />
+  </PlassProvider>;
+  ```
+
+  `de`, `en`, `es`, `fr`, `ja`, `ko` and `zhHans`. The list is short on purpose: a pack is worth shipping once somebody who reads the language has read it.
+
+  **Each pack is a named export from its own module rather than an entry in a `locales['ko']` table.** A lookup would be the shorter API and the wrong one, because for a key to be found in a table the table has to be in the build — a French application would ship the Korean strings, the Japanese strings and the rest. An import ships one, and an application that switches language while it runs imports the packs it offers and picks between them, which is what it already does for its own copy.
+
+  **A key is a meaning, not a component.** `close` is the × on a modal, a drawer, a popover and a toast, and it is translated once. A key exists per component only where the word genuinely differs: `paginationNext` moves by a page and `carouselNext` moves by a slide, so a language that distinguishes those has somewhere to put the distinction.
+
+  `PlassLabels` widens what used to be the pickers' own `PlassPickerLabels`, which had already grown past the pickers; the twenty-five components that were carrying their own English string now take it from the set. Nothing about the precedence changed — the component's own prop still wins, a partial `labels` still leaves the rest English — so an application that named its words by hand keeps working exactly as it did.
+
+  Measured with `npm run size`: **+0.7 kB on the five overlays and +0.8 kB on the whole library**, which is the registry being shared rather than inlined; `PlButton` and `PlTypography` alone are unchanged. A pack is about **0.9 kB gzipped** and is only in the build if it was imported.
+
+- **Three hooks: `usePlDisclosure`, `usePlElementSize` and `usePlOnScreen`.** Each of them is a piece of machinery the library already ran on internally, and each is public because the hand-written version has a decision in it that is easy to get wrong.
+
+  **`usePlDisclosure`** is one boolean and the four callbacks that change it. It is worth a hook rather than a snippet for one reason: written by hand it is a `useState` _plus three arrow functions that are new on every render_, and an inline `() => setOpen(false)` handed to a memoised trigger defeats the memo it was handed to. Every callback here is stable, `onToggle` included, because it uses the updater form rather than `!open`. The names are the props — `setOpen` fits `onOpenChange` exactly — so the ordinary use is two lines.
+
+  **`usePlElementSize`** adds two things to a `ResizeObserver`. The **first measurement** is taken in a layout effect rather than waiting for the observer, whose first callback arrives after a frame has been painted — a component that laid itself out from `0 × 0` for that frame flashes. And it reports the **content box**: the room actually left inside the element once its padding has been taken off, where a hand-written version nearly always reports `getBoundingClientRect()` or `borderBoxSize` and gets a number that includes the padding and the border.
+
+  **`usePlOnScreen`** has `once` **on** by default. The question a caller almost always has is "has this been seen yet" rather than "is it on screen right now", and a hook that kept answering the second one would re-render a page of lazily loaded pictures every time the reader scrolled past any of them. It answers `false` before it knows, which is safe for both of its uses, and `true` where there is no `IntersectionObserver`, because a picture that never loads is worse than one that loads early.
+
+  Measured with `npm run size`: **+0.4 kB on the whole library and +0.0 kB on all four other scenarios**, the three of them together.
+
+- **`PlAnimateSplit`.** A line of text arriving one part at a time. The other effects tell themselves off across their **children**, which a line of text does not have — so this one makes them, and hands the set to exactly the same `stagger` machinery a `PlAnimateFade` around a list of `<li>`s uses. `effect`, `stagger`, `durationStep` and `reverse` all mean what they mean everywhere else; the component is the splitting and nothing more.
+
+  **`by="character"` is not safe in every script**, and the page says so rather than leaving it to be discovered. A character part breaks the shaping between letters: Arabic stops joining, Devanagari conjuncts come apart, and an emoji built out of several code points is cut into its pieces. `word` has none of those problems and is the default.
+
+  **The gaps are not parts.** Whitespace is never given an entrance of its own — animating the space between two words is nothing arriving — and it does not take a step of the stagger with it either, so the second word starts one step after the first rather than two. That is why this component reaches for `useAnimationRun` directly rather than `useAnimateElement`, which is the arrangement `internal/animate.ts` already describes for the components that have to understand their own children.
+
+  Each part is `inline-block`, because a transform does not apply to a non-replaced inline element and a slide would otherwise fade without moving.
+
+  **A screen reader is told the line, once.** The parts are hidden from the accessibility tree and the whole line sits beside them, which is what stops a split headline being read out one word — or one letter — at a time: the defect this pattern is known for everywhere it appears without it.
+
+  Measured with `npm run size`: **+0.4 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlAnimateScramble`.** A line of text resolving out of noise, and the second of the two effects that animate **content** rather than a box.
+
+  **The noise is made of the line's own characters.** Every scrambler that ships with a default alphabet ships an English one, and over a Korean, Greek or Arabic headline that is not a word resolving — it is a different script flickering where a word is about to be, and a reader watching their own language arrive out of somebody else's is watching a bug. Shuffling the line's own glyphs is right in every script and costs nothing; it also keeps the line's colour and width steady, because every frame is drawn out of exactly the characters the finished line is made of. `characters` overrides it for the caller who genuinely wants a terminal look.
+
+  It settles **left to right** rather than at random — a word arriving is something a reader can follow, and a reader who looks away and back has not lost their place — and **whitespace is never scrambled**, because the gaps between words are what keeps a line of noise looking like a sentence.
+
+  The redraw is stepped at `tick`, 45ms by default, rather than taken every frame. At sixty a second a line of changing glyphs strobes, which is unpleasant to look at and is exactly the flicker a reader with a sensitivity to it must never be handed.
+
+  It takes a `string` rather than a node for the reason `PlAnimateCounter` takes a number, waits to be seen for the same reason, and tells a screen reader the line once and never the noise.
+
+  Measured with `npm run size`: **+0.5 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlAnimateCounter`.** A number counting up to what it is — the one effect in the group that animates **content** rather than a box.
+
+  **It is not a keyframe, and the reason is formatting.** A registered custom property and a CSS `counter()` tick a number perfectly well, and that would be the neater implementation; what they cannot do is put a thousands separator in one, or a currency symbol, or fold 1,200,000 into `1.2M`. A counter that cannot be formatted is a counter nobody can put on a dashboard, so the frame loop decides only which number is being drawn and `Intl.NumberFormat` decides what it looks like. `easing` is a **function** here for the same reason: there is no CSS animation running to hand a string to.
+
+  **`trigger` defaults to `visible`**, and it is the one component in the library that does not start on mount. An entrance played off screen has still delivered its content; a count that ran off screen delivered a number that was already sitting there, which is the one thing a counter cannot afford — being watched is the whole point of it.
+
+  **A screen reader is told the answer, once.** The ticking figure is hidden from the accessibility tree and the final number sits beside it in a clipped span, because a number changing sixty times a second in that tree is either silence or sixty announcements and neither of those is the figure. Until the count starts, what is shown is the number it will count _from_ — the same rule every keyframe here follows about its own first frame — so nothing claims a value it has not reached.
+
+  Changing `value` counts again from wherever the last one landed, so a figure that updates on a timer needs nothing said to it.
+
+  Measured with `npm run size`: **+0.3 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlAnimateShake`.** A refusal. The one effect in the set that is a **response** rather than an entrance — what a form does when the password was wrong again, what a locked control does when it is pressed — so it starts held still, where every other effect here starts on mount.
+
+  **`replay` is the prop it exists around, and it is a new shape in the animation API.** A refusal can happen twice, and `play` — being a boolean — cannot say "again": replaying with it means toggling off and on, which is two renders for one event and a piece of state whose only job is to be flipped back. A value that has _changed_ is the closest React has to an event, and the count of failed attempts a form already keeps is exactly that value. It never plays on the first render, because a shake that shook itself on mount would be answering an event that has not happened.
+
+  It lands **exactly where it started** — three shudders either side of home and back to nothing. That matters more here than anywhere else in the group, because this is the one effect a caller will run over content that is still being typed into, and a field left a few pixels off its label would be a worse defect than the error it was reporting.
+
+  It is not in `PlassAnimation`, for `PlAnimateFloat`'s reason: that union is the set of ways content can arrive, and a response is not an arrival.
+
+  The page says the thing the component cannot enforce. **A reader who asked for less motion sees none of it**, so whatever the refusal is saying has to be said in text as well — the field's own `error` and `invalid` — and the shake is emphasis, never the message.
+
+  Measured with `npm run size`: **+0.2 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlAnimateFloat`.** Content drifting gently, and not going anywhere. It is the odd one out in the group and the page says so: every other effect here is an **entrance**, played once when content arrives, and this one never finishes.
+
+  Three things follow from that. It repeats **infinitely** by default, because one drift out and back is a nudge and nobody asks for a nudge. It has **no `mode`**, because the cycle is symmetric and running a symmetric cycle backwards is the same cycle. And it is **not in `PlassAnimation`**.
+
+  That last one is the decision worth recording. The union is the set of ways content can _arrive_, and an object literal does not tree-shake per key — so every component importing the effect map pays for each row whether or not it uses it. An endless drift is not an arrival and is a row nothing else could ever want, which is exactly the line the `PlAnimateReveal` entry drew when it joined the union. It runs its own keyframe instead.
+
+  The cycle is home, out, home, so however many times it runs it ends where it started: a float stopped mid-cycle would leave the element permanently a few pixels out of place, which reads as a layout bug rather than as an effect that ended.
+
+  `easing` defaults to `ease-in-out`, and it is **the one component in the library that does not take the house curve**. The house curve is an entrance's — fast out of the gate, slow into place — and a drift with it lurches at each end of the cycle instead of turning around, because there is no gate: the element is already there and is only breathing.
+
+  Measured with `npm run size`: **+0.2 kB on the whole library and +0.0 kB on all four other scenarios**, which is what staying out of the union bought.
+
+- **`PlHowToSteps` and `PlHowToStep`.** Instructions, numbered, with what to do under each one. Three components in the library now put things in order and the difference is not the drawing: a `PlStepper` and a `PlTimeline` both say **where you are** — one in a process the reader is moving through now, the other in a sequence that has already happened — and this one says **what to do**.
+
+  That is the shape everything else follows from: **every step's body is open at once.** Somebody following instructions reads ahead, goes back a step, and works at their own pace, so a guide that showed one step at a time would be hiding the answer to "what am I about to be asked for".
+
+  It is also why `active` is **optional** here. A guide that claimed to know how far a reader had got would be guessing; it is for the guide that genuinely knows, such as a setup wizard reporting what it has already done.
+
+  `numbered` is on by default, because "do this, then this" is an order and the number is how a reader finds their place again after looking away. Off — usually with `connector="none"` — is a checklist, which has no order. An `icon` replaces the number in the disc and keeps the step's place in it: a step never takes an index, the guide numbers its children as it walks them, and a conditional step that rendered nothing does not take a number with it.
+
+  It is a real `<ol>` of `<li>`s, and that is the accessibility of it. A screen reader announces "list, five items, item two" on its own — the position a heading per step would only approximate — so the numbers a reader sees are the ones the list carries.
+
+  The bullet, the halo and the connector come from `internal/steps.ts`, the same table the stepper and the timeline draw from, because a haloed bullet must not mean two things in one library.
+
+  Measured with `npm run size`: **+0.6 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlFloatingActionButton`.** The one action a screen is about, floating over it. It is a `PlButton` in a corner and everything that makes it one is the button's — the three materials, the elevation ladder, the pointer light, `loading`, `readOnly`, `disabled`. What it adds is the pinning, the shape, and one rule.
+
+  **`label` is required and is always the accessible name.** A floating button is a disc with a mark in it nine times out of ten, and `extended` decides only whether the words are _also_ drawn — never whether they exist. An icon-only button with no name is the single most common accessibility defect this pattern ships with, and a required prop is the only fix that survives review.
+
+  The icon-only form is a **disc**, which is `PlIconButton`'s deliberate exception to the radius rule: the flat run along a control's edge is there for a line of text to sit on, and a glyph has no line of text. The extended form is **not a pill** for exactly that reason — it has words along its edge, so it takes the house fillet like every other labelled control.
+
+  `elevation` defaults to **3**, the top of the ladder, and unlike every other default in the library that is not a compromise: this is the one control that genuinely floats over the content rather than resting on it. `size` defaults to `lg`, one step up from a button's, because it is a target for a thumb.
+
+  The insets are **logical and inline**: `corner` is `start`/`end` as everywhere, so the button crosses the screen under RTL with everything else, and an inline declaration is the one form that wins over a utility deterministically — which a caller's `offset` needs, being a value rather than a class. `floating={false}` keeps the shape and the shadow and drops the positioning.
+
+  The page says the two things a component cannot enforce: **one per screen**, because two primary actions is none; and that it covers content, so a scrolling list needs room at its end for the row underneath it.
+
+  Measured with `npm run size`: **+0.1 kB on the whole library**, because it is a `PlButton` and a `PlIconButton` and nothing else.
+
+- **`PlAnchor`.** A table of contents that follows the reader down the page. Anyone can draw a list of links; what is worth writing once is deciding **which one is lit**, and the rule is not the obvious one.
+
+  The lit row is the last heading whose top has **passed the reading line** — not whichever heading happens to be visible. Three can be on screen at once, and the one a reader is inside is the highest of them that is already above them. That is why the tracking is a measurement rather than an `IntersectionObserver`: an observer answers "is it visible", and the question here is "which one did I pass last".
+
+  Two ends are handled separately, and both are what a hand-rolled version gets wrong. **Above the first heading nothing is lit**, because the reader has not reached a section and lighting the first row before they arrive is a claim about where they are. **At the very bottom the last row is lit** whatever the measurement says, because a short final section never reaches the line and a list without this goes dead exactly where a reader is looking for it.
+
+  `offset` is where that line sits — the height of whatever is pinned over the page. Without it a heading goes on counting as the _next_ one after it has slid out of sight behind a sticky header, so the list sits a section behind the reader for the bar's whole height.
+
+  The headings arrive as a **flat array** rather than as children, which is the opposite of most of this library: a table of contents is generated, and generators produce a flat list in document order with a level on each entry. It stays flat, deliberately — real documents skip levels, so a nesting built from that list would be a guess at a shape nobody wrote.
+
+  Only where there is something to scroll: a page that fits on the screen is always at its own bottom, and lighting the last row there would say a reader had reached the end before they had read anything.
+
+  It measures at most once per frame, because scroll fires far more often than a page paints and the answer cannot change between two paints. The lit row carries `aria-current="location"` — where the reader is _within_ the document, and not `page` — with a rule down its leading edge, so colour is never the only thing saying where they are.
+
+  Measured with `npm run size`: **+0.6 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlDataList` and `PlDataListItem`.** A list of labels and the values that go with them — the panel every detail screen ends with, and the whole reason it is a component is the **markup**. It is a real `<dl>` with real `<dt>`s and `<dd>`s, each pair grouped in a `<div>`, which the HTML specification allows and which is what lets a row be laid out side by side without giving up the grouping that makes it a pair.
+
+  **A details panel built as a two-column table is the mistake this replaces**, and it is not a styling one: a table claims a row-and-column relationship that is not there, so a reader navigating it by cell is told there are two columns of data when there is a column of names and a column of values. One thing and its fields is a description list; many things with the same fields is a `PlTable`; a run of items of the same kind is a `PlList`.
+
+  The label column is a **fixed width** rather than the width of the longest label, which is what makes two panels on one screen line up and what stops a value moving when somebody renames a field. `labelWidth` takes any length, and `'12ch'` is usually the right one — a label column is measured in characters and no ladder of `rem` can spell that.
+
+  `divider` rules between the rows and **only** between them: a line above the first or below the last would be a box drawn around a list that has no box.
+
+  The rows are children rather than data, unlike a `PlTable`'s columns. A details panel is written out once and read in source order, and every value in it is a different shape — a chip, a date, an avatar, a link — so a data array would be an array of `render` functions.
+
+  Measured with `npm run size`: **+0.4 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlAppLogo`.** A product's mark and its name beside it. The whole component is the **framing**, and the default is the answer project after project gets wrong: `bare` draws the artwork as it was given, at the height `size` asks for and whatever width that comes to.
+
+  That is the default because most marks already have a frame. A mark drawn with its own background, its own margin, or the product's name set into it is finished artwork — putting it on a plate gives it two edges, and cropping it to a circle cuts the name in half. `plate` and `circle` are for a mark drawn as a bare glyph, which cannot sit next to anything else until it has been given an edge, and a plate insets the artwork to about seventy percent of the tile rather than filling it: the margin every app icon has.
+
+  It is **not a `PlAvatar`**, and the page says why. An avatar is a picture of a person or a thing, always a circle or a fillet, with initials behind it when the picture does not arrive, because there is always something to draw. A logo is artwork the product owns: it has no fallback worth inventing, and its shape is a decision somebody already made — which is why the shape is a prop here and a house rule there.
+
+  **With a `name`, the mark is taken off the accessibility tree.** The wordmark beside it already says what the product is called, and a picture that says it again is a screen reader reading the name twice. Without one the mark speaks, through an `alt` whose empty default is a real answer.
+
+  `variant` and `color` are read only when there is a plate: a bare mark is the product's own artwork and the library does not tint it. `render={<a href="/" />}` makes it the way home, which is nearly always what a logo is.
+
+  Measured with `npm run size`: **+0.5 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlHoverCard`.** A preview of what is behind a link, shown when the pointer rests on it. The library now has all three floating surfaces, and the pages tell them apart by **what opens them and what a reader can do once they are open** rather than by how they look — all three are the same sheet. A tooltip names the thing under the pointer and nothing in it can be reached; a hover card previews what is behind it and the pointer can move _onto_ it; a popover was asked for, stays until it is dismissed, and can be typed into.
+
+  **The rule that decides whether it is the right component at all is written on the page: nothing may live only in here.** A card that opens on hover does not open for a finger, so a link, a button or a fact that exists nowhere else is one that every touch reader misses. Everything inside is a preview of something already reachable — which is what makes it safe to have, and why it needs no dismiss button, no focus trap and no scroll lock.
+
+  **The delays are the component.** `delay` is 600ms and deliberately long: a card that opens the moment a pointer crosses a link opens on every link a reader passes on the way somewhere else, which turns a page of prose into a page that flinches. `closeDelay` is 300ms and cannot be zero — the gap between the trigger and the card has no pointer in it, so a card that closed the instant the pointer left could never be reached, and reaching it is the whole difference from a tooltip.
+
+  It opens on **keyboard focus** as well as on hover, so a reader tabbing along a paragraph of links gets the same preview a pointer would. The trigger is rendered rather than wrapped, so a link keeps its `href`, its styling and its place in the tab order. The sheet is a `PlPopover`'s, one `size` rung wider at every step: a popover is a detail beside a control, and a preview squeezed to the width of a hint is a preview nobody reads.
+
+  Base UI's `PreviewCard` owns the anchoring, the flip at the window edge, the two delays and the dismissal.
+
+  Measured with `npm run size`: **+3.4 kB on the whole library and +0.0 kB on all four other scenarios** — the primitive, paid for only where the component is.
+
+- **`PlScrollArea`.** A bounded box that scrolls, with the library's own scrollbar in it. The reason to reach for it over `overflow: auto` is the **bar**: a platform scrollbar is either an overlay that vanishes the moment the content stops moving or a strip of permanent grey furniture, and neither of them belongs beside a translucent sheet. The thumb is `--plass-track`, the same neutral ink a `PlSlider`'s rail and a progress groove are cut in, and the lane is overlaid so drawing it costs the content no width.
+
+  **It is not a `PlScrollZone`, and the pages say which is which.** A scroll zone is the other answer to the same fact — content that runs off the end of its box — and it takes the bar away entirely, fades the end that still has something behind it and adds a pair of buttons. That is right for a strip of tabs or chips, where a bar under one line of labels is heavier than the labels. A scroll area is right for a panel of content, where the bar is the honest signal and where a reader wants to know **how far through** they are, which a fade cannot say. There is deliberately no fade here for the same reason: two signals for one fact, one measured and one not, is one more than the box needs.
+
+  **`height` is a prop rather than a class**, which is the one API decision worth stating: a vertical scroll area has to be bounded by something or there is nothing for the content to overflow, so it is the measurement without which the component does nothing at all. `maxHeight` is the ceiling form for a panel that should shrink to short content; `width` and `maxWidth` are the pair for a horizontal one.
+
+  `orientation` takes `both`, which draws a lane on each edge with a corner in the join. `scrollbars` is `auto` — while the pointer is over the box or the content is moving — or `always`, which is right more often than it looks: for a panel whose whole point is that there is more below, a bar that appears on hover is a signal nobody standing back from the screen ever sees.
+
+  `label` is worth giving and the reason is not obvious. **A scrollable box is a tab stop when nothing inside it is focusable**, because somebody using a keyboard has to be able to scroll it, and a landing point with no name is announced as nothing at all. With a name it is a region; without one it claims no landmark, deliberately, because an unnamed region is something a screen reader lists as "region" and nothing else.
+
+  Base UI's `ScrollArea` owns the behaviour: the overlay measurement, the thumb's size and position, the drag, and making the viewport a tab stop exactly while there is something to scroll.
+
+  Measured with `npm run size`: **+4.7 kB on the whole library and +0.0 kB on all four other scenarios** — the Base UI primitive, which is the largest of the ones the library imports and is paid for only by the pages that import this component.
+
+- **`PlMeter`.** A quantity inside a range, drawn as a bar. It is cut out of the same groove as a `PlProgressLinear` and it is deliberately not one, because the difference decides which to reach for: **progress is something advancing, and a meter is something already known.** Disk used, seats taken, a password's strength, how full a battery is — none of them is going anywhere on its own.
+
+  That follows into the API and into the semantics. `value` is **required** and there is no sweep, because a meter with nothing to report is not a meter but a bar that should not have been drawn yet; and the role is `meter` rather than `progressbar`, since telling somebody a static figure is in progress is telling them to wait for something that will never finish.
+
+  **`thresholds` is the prop it exists for.** Bands of `{ from, color }`, where the highest `from` at or below the value wins — read rather than walked, so the order they were written in does not matter — and `from` is in the meter's own **units** rather than a percentage. A quota bar that turns amber at three quarters and red at ninety percent says something a fixed colour cannot, and the colour comes from the value rather than from the moment somebody was looking. The page pairs it with `showValue` every time it appears: a band is a second way of saying how full something is and must never be the only one.
+
+  Base UI's `Meter` owns the semantics — the role, the range attributes, `aria-valuetext`, the formatting and the fill width — the same way its `Progress` owns a progress bar's, so what is left here is the material: the groove is `--plass-track` and the fill the family's gradient, travelling on the width. A value outside the range is clamped on both halves, the bar and the announced value together, so what is read out and what is on screen never disagree.
+
+  Measured with `npm run size`: **+1.0 kB on the whole library and +0.0 kB on all four other scenarios**, the Base UI primitive included.
+
+- **`PlPortal`.** Children rendered somewhere else in the document. It is `createPortal` plus the three things a library has to add, and the first is the only real reason to reach for it.
+
+  **It carries `plass-portal`.** Every surface the library already sends through a portal — a modal, a drawer, a menu, a popover, a tooltip, a toast — lands with that class on it, because a portalled subtree leaves whatever element a host had scoped its CSS reset to and the class is how that host finds it again. A caller's own portal without it was the one subtree on the page the reset missed.
+
+  **It renders nothing until it has mounted.** There is no `document` on a server, so the HTML that ships never contains a portalled subtree and neither does the hydrating render. That is what a portal _is_ rather than a limitation to work around, and the page says so: anything that has to be in the server's HTML does not belong in one.
+
+  **`container` is resolved after mount**, which is what lets it be a **ref**. The element a portal targets is usually one React has not created yet at the moment the prop is written, so a ref is `null` and a `getElementById` finds nothing; reading the prop during render would get the wrong answer every time. An element and a `DocumentFragment` are taken as they are, a function is called, and anything that resolves to nothing falls back to `document.body` rather than dropping the children.
+
+  What it does **not** carry is the colour scheme, and that is written down rather than left to be discovered. The stylesheet answers to a `.dark` or a `[data-theme]` on an _ancestor_, and a portal to the body has left every ancestor it had. The library's own popups have the same gap and the same fix: point `container` at an element inside the theme. React context does cross a portal — the tree it is read from is the React one — so a `PlassProvider` above still decides `size`, `color`, `density` and `locale`.
+
+  It is **React-only**: an `overflow: hidden` ancestor and a stacking context that cannot be escaped from the inside are DOM problems, and Flutter's answer is the `Overlay` every app already has.
+
+  Measured with `npm run size`: **+0.1 kB on the whole library and +0.0 kB on all four other scenarios**.
+
+- **`PlFlex`.** A row or a column and the gap between the things in it — the layout box with no arithmetic in it. A [PlGrid](https://plass.cdget.com/components/layout/grid) divides a row into twelve columns and needs a `PlGridItem` to take them; a [PlStack](https://plass.cdget.com/components/layout/stack) overlaps what it is handed. This one only decides which way its children run.
+
+  **`direction` is responsive and resolves in CSS**, which is the reason it is worth a component rather than three Tailwind classes. `direction` takes `{ xs: 'vertical', md: 'horizontal' }`, a form that stacks on a phone and lines up on a laptop, decided by the stylesheet: one `--p-dir-*` slot per rung the caller named, cascaded by the same `@variant` blocks a grid's columns already ride. So a server renders it correctly at every width, dragging a window costs no re-render, and no listener is installed. It is also the only way to say that in a project that imports `plass-ui/styles.css` and has no Tailwind of its own.
+
+  `reverse` folds into that same slot instead of taking one of its own, and that is why it is deliberately not responsive: one custom property carries the whole answer, so a breakpoint changes the axis without having to restate which end it starts from. It is a **painting order** and moves nothing in the document — what a screen reader reads and what the Tab key walks is unchanged — so it is for an arrangement and never for content whose order is the information.
+
+  `wrap` defaults to **`false`**, unlike a `PlGrid`'s. That is what a flex box already does, and the opposite default would silently reflow a toolbar somebody had sized to fit.
+
+  The two gutters are now declared for `.plass-grid` and `.plass-flex` together rather than copied. They are one question asked by two components — the space _between_ the things in a box — and `spacing` is the same Tailwind scale on both, so a flex box's gap and a grid's gutter of `4` are the same `1rem`.
+
+  It is **React-only**, and that is not an omission: `Row`, `Column` and `Wrap` are already in `package:flutter/widgets.dart` and already take a `spacing`. The half worth having in Dart is the responsive axis, and that is a `LayoutBuilder` rather than a widget. The component page shows it.
+
+  Measured with `npm run size`: **+0.2 kB on the whole library and +0.0 kB on all four other scenarios**, because nothing else imports it.
+
+- **`PlHeader` and `PlFooter` hold their content to the same measure a `PlContainer` does, from one implementation.** All three took a `maxWidth` on "`PlContainer`'s ladder" and all three carried their own copy of it — three tables that could disagree, and a bar whose measure did not line up with the container under it is a page with a visible seam down one edge. There is one ladder now, in `internal/responsive.ts`, and all three take the same type: a rung, any CSS length, a number of pixels, or `none`, responsive, resolved in CSS.
+
+- **Six components turn with the window.** `orientation` on `PlPanes`, `PlTabs`, `PlScrollZone`, `PlTimeline` and `PlStepper`, and `direction` on `PlStack`, all take a responsive value: `orientation` takes `{ xs: 'vertical', md: 'horizontal' }` and a tab bar is a column on a phone and a row on a laptop.
+
+  **These resolve in JavaScript rather than in CSS, and that is not an oversight.** An orientation decides which DOM a component builds, which `aria-orientation` it claims and which way its arrow keys walk; no stylesheet can do any of that. So they pay what every JavaScript answer about width pays — a server renders the `xs` entry and the browser corrects it on hydration — which is exactly why `PlContainer`'s `maxWidth`, which only decides style, does **not** come this way. The line is written down in `internal/responsive.ts` and on the [breakpoints](https://plass.cdget.com/design/breakpoints) page.
+
+  **A bare value subscribes to nothing.** `useMediaQuery(null)` is a hook that installs no listener, so the four queries are only asked when there is a map to answer with: twenty tab bars that never change shape install no listeners between them. Measured — 0 for `orientation="vertical"`, 4 for a map.
+
+- **`PlShow`.** Content at some widths and not others — `from`, `until`, or both as a band. It decides in **CSS**, which is the whole component rather than an implementation note: a media query answered in JavaScript is `false` on a server and on the first frame a browser renders, so a `useMediaQuery` and a ternary draw the wrong half of a responsive layout and then throw it away. That is a flash on every page load, not an edge case. It is also the only way to gate on width for a project that imports `plass-ui/styles.css` and has no Tailwind of its own — there is no `md:hidden` to reach for there.
+
+  **It is not a box.** While showing it is `display: contents`, so its children take part in the surrounding layout exactly as they would have without it: a gate inside a flex row does not become a flex item. Which also means a `className` carrying a margin or a width lands on nothing — put your own element inside.
+
+  What it costs is that **both halves are in the document**. Hiding is `display: none`, which takes the subtree off the accessibility tree and out of the tab order, so nothing is read out twice and nothing is drawn — but both were rendered and both were sent. Right for two arrangements of the same content; wrong for a subtree that fetches, is expensive, or must not mount at all, and `usePlBreakpointValue` is what mounts exactly one of those at the cost of a server rendering the `xs` answer.
+
+  `until` is **exclusive**, so `until="md"` on one element and `from="md"` on another are the two halves of one decision with no width that draws both and none that draws neither. There is no `xs` bound — everything is at or above the bottom rung, so it would mean "always" and "never" — and there is no `PlHide`, because `until` is already the inverse of `from`.
+
+- **A `PlContainer`'s `maxWidth` is responsive, and takes any length.** `maxWidth` takes `{ xs: 'none', md: 'lg' }` and narrows a page as the window widens, and `maxWidth="72ch"` is the measure a paragraph actually wants — the five rungs are `rem` and no ladder of `rem` can spell a measure in _characters_. A number is pixels; the rungs are unchanged.
+
+  It resolves in **CSS**, not in JavaScript, and that is the part worth knowing: one `--p-maxw-*` slot per rung the caller named, cascaded by the same `@variant` blocks the grid uses. So the first paint a server sends is already right at every width, and a window being dragged costs no re-render. Measured in a browser: `none` at 500px, `1024px` at 900px, `72ch` at 1400px, from one declaration.
+
+  The machinery moved out of `internal/grid.ts` into `internal/responsive.ts` with it, since it now has a second user. That file also writes down **where a responsive value can be resolved and where it cannot**: a value that only decides style belongs in CSS, and a value that decides structure — an orientation changes the DOM, the ARIA and the arrow keys — has to be JavaScript and pays the server's `xs` first render for it.
+
+- **The breakpoint ladder is written down once, and a project can move it.** Every width in the library now comes from Tailwind's own `--breakpoint-*` theme, so one line moves both halves of it:
+
+  ```css
+  @theme {
+    --breakpoint-md: 50rem;
+  }
+  ```
+
+  The reason it takes an arrangement rather than a prop is worth stating: **a media query's condition cannot read a custom property.** `@media (width >= var(--x))` is not valid CSS, so no provider and no runtime value can move a breakpoint the stylesheet decides at. What the CSS half can do is resolve the theme at _build_ time, which is what `@variant` does — `PlGrid`'s four cascade blocks were hand-written `@media (width >= 48rem)` literals and are `@variant md` now. Measured: a `@theme` override moves a `@variant` block to 50rem and leaves a hand-written one at 48.
+
+  The JavaScript half asks `matchMedia`, where a breakpoint is a **value** rather than a condition — so it can read the same answer off the document. `--plass-breakpoint-sm` … `--plass-breakpoint-xl` are four new tokens carrying exactly that, each falling back to Tailwind's default so they are still right on a server, on a first paint before the CSS has arrived, and on the precompiled `plass-ui/styles.css` where our values are baked in. `usePlBreakpoint` and a `PlSidebar`'s `collapseBelow` both read them, and `internal/breakpoints.ts` is the one place that does.
+
+  A new package test fails the build if a width is ever written out by hand again, which is the failure that would otherwise be invisible: a page whose `md:` utilities change at one width and whose `PlGrid` changes at another still renders, still passes every component test, and is simply wrong on a laptop.
+
+- **`PlAnimateReveal`.** Content uncovered behind a moving edge, and the only entrance in the set where **nothing moves and no colour changes**. A fade changes the ink, a slide changes the position, a grow changes the size; this changes how much of the element is drawn and leaves every pixel it has drawn exactly where it will finally be. That is what makes it the effect for anything whose _position is the information_ — a heading over the paragraph it belongs to, a divider between two sections, a chart's plot area, a column of figures that must not be read from the wrong place.
+
+  It is a `clip-path: inset()` rather than a mask or an `overflow` wrapper, and both alternatives were considered. A mask brings a gradient that has to be kept in step with the direction; a wrapper puts a second element into the layout, which is exactly what an effect for something positional must not do. `inset(0)` already means "nothing is cut off", so the to-state is the element's own natural one rather than a number somebody had to choose — and the page around it never learns that anything happened.
+
+  `from` is physical — `top`, `right`, `bottom`, `left` — as `PlassSide` is everywhere, and `mode="out"` closes from whichever edge it opened towards. **`fade` is off by default**, alone among the effects that offer it: fading a reveal asks for two entrances at once, and the reason to have reached for this one is usually that the first was the problem. It takes `stagger` and `timeline="view"` like the other five.
+
+  **The union it joined cost nothing**, which was the thing to check before adding to it. `reveal` is a seventh row in `PlassAnimation` and in the class map that backs it, and an object literal does not tree-shake per key — so every component importing that map pays for the row whether or not it uses the effect. Measured with `npm run size`: **+0.2 kB on the whole library and +0.0 kB on all four other scenarios**, because nothing outside the `PlAnimate*` family imports the map at all. An effect that was not an entrance — an endless drift, a response to a rejection — would not have gone in it.
+
+- **`timeline="view"` hands an effect to the reader's scroll position.** Two CSS declarations behind an `@supports` give every keyframe in the library a scroll-linked mode: the effect stops being something that happens at a moment and becomes something that tracks where the element sits in the scrollport, so scrolling back up plays it backwards and a reader who stops halfway leaves it halfway. There is no new component and there should not be — this changes what _advances_ an effect, not what the effect is.
+
+  Four settings stop meaning anything and are **ignored** rather than half-working: `duration`, `delay` and `repeat` belong to a clock, and so does the whole idea of a `trigger`, since the scroll position is the trigger. That last one is load-bearing rather than tidy — an effect held `paused` waiting to be scrolled into view shows its own first frame and nothing else, however far it is scrolled — so a scroll-linked effect is always let go. `paused` still works, because that is a caller saying "hold it" rather than "wait for something". `range` replaces `duration`: an `animation-range` as CSS writes it, defaulting to `entry 0% cover 45%`, which finishes while the element is still arriving rather than when it reaches the middle of the screen.
+
+  **A browser with no `animation-timeline` gets one clock-driven run**, which is what the `@supports` is for: degraded is allowed, blank is not. The slots are written only when a caller asks for `view`, so the default costs nothing — `auto` is what the property already resolves to, and writing it into every inline style would be the same answer a hundred times. On the same six effects `stagger` is on and absent from the same four, because `animation-timeline` is a property of the element the keyframe runs on. **+0.1 kB on the whole library.**
+
+- **Six effects can now be told off across their children.** `stagger` is milliseconds added to each child's delay, `durationStep` is the same for its duration, and `reverse` starts from the end of the set — on `PlAnimateFade`, `PlAnimateGrow`, `PlAnimateSlide`, `PlAnimateZoom`, `PlAnimateRotate` and `PlAnimateBlink`. `stagger` defaults to `0`, which plays the box, so nothing that exists changes.
+
+  **There is deliberately no `PlAnimateStagger`.** A stagger is a _differential_ rather than an effect, and a wrapper would be a second way to spell something all six can already say — the same rule that keeps a `Pulse` (`blink` + `alternate`) and a `Bounce` (`grow` + `alternate`) out of the library. Turning it on takes the animation **off the root entirely**: eight children fading in under a box that is also fading in is the same content faded twice, and the second one is not free.
+
+  The four effects that already read their children do not take these and cannot — a marquee lays its children down twice, a headline swaps between them, a typewriter counts their graphemes, and a lighting keeps its motion on a pseudo-element, which there is no way to put on somebody else's child. `PlAnimateAppear` has had the same three props under the same names since it existed and **now runs on the same code**: `animateChildren` and `staggerSlots` moved into `internal/animate.ts`, because two implementations of "one after another" would be two opinions about the arithmetic. It gains `durationStep` on the way past.
+
+  The effect is written onto the children themselves rather than onto wrappers, so a row of `<li>`s stays a row of `<li>`s and a grid's cells stay its direct children; the cost is that a child has to accept a `className` and a `style`. The `transform-origin` a `PlAnimateGrow` was given travels with it, since that property is not inherited and a staggered grow would otherwise unfold every child from its own middle. **+0.2 kB on the whole library**, nothing on any component that does not import an effect.
+
+### Fixed
+
+- **The chart frame carried nine slot names this package does not declare.** Ported from the library the frame came from, renamed to the `--plass-` prefix, and never checked against anything: `--plass-grain`, `--plass-sheen`, `--plass-panel-press`, `--plass-plate-glass` and `--plass-disabled-fg` have no Plass equivalent under those names, and `--plass-chart-gap` was simply never written down. Nothing failed. An unresolvable `var()` computes to `none` in a `stroke` and to nothing at all in a shorthand, so what shipped was a **tooltip panel with no glass, no shadow and a `currentColor` border**, a legend whose switched-off entries were the same ink as the rest, and a line chart whose markers had no ring cut out of them.
+
+  The panel is now the sheet a `PlSelect`'s popup is, which is what it should always have been — a floating readout and a floating list are the same material. A switched-off legend entry is the muted ink with a line through it and its swatch keeps its own colour at 40%, which is what the Flutter build already drew. `--plass-chart-gap` is declared as the surface, and `PlassToken` names it.
+
+  **Two checks were added so this cannot ship again.** `test/package/tokens.test.ts` now asserts that every `--plass-*` a source file reads is declared in `styles.css` — the two checks already there compared the type against the stylesheet, so a token appearing in neither, which is exactly this case, agreed with itself. And `test/styles/standalone.test.tsx`, the one file in the suite that loads real CSS, now renders a chart and asserts that no `fill` or `stroke` on it computes to `none`. That catches the other half: a token that _is_ declared but resolves to nothing because its declaration sits under a selector no chart matches. Neither test asserts a shade.
+
+- **The chart frame's focus ring and legend hover were unstyled.** Three of the ported frame's colour slots kept the names they had in the library they came from — `--n-soft`, `--n-ring` and `--n-line` — and nothing in this package declares any of them. A `var()` that cannot be resolved takes an `outline` shorthand down with it, so **the focus ring on a chart's plot and on every legend button was simply absent**: the plot is a tab stop, and a tab stop a keyboard reader cannot see is the accessibility failure the ring exists to prevent. The legend's hover tint was gone with it, and the tooltip panel's hairline fell back to `currentColor`, which drew the border in ink. All three now read the slots a `PlBox` actually sets — `--p-soft`, `--p-ring` and the glass hairline.
+
+- **A chart ignored the `size` and `locale` a `PlassProvider` set.** `CartesianChart` took both as plain props with hard-coded fallbacks, so a provider that put the whole page on `sm` left every chart at `md`, and one that named a locale still got the reader's own number formatting on the axis. It resolves both from the defaults now. `density` deliberately does not go through it: the box resolves that one itself, and the single chart that needs it for arithmetic reads it directly.
+
+- **A read-only `PlSelect` opened its popup again.** Base UI 1.8 redefined `readOnly` on a select to mean "nothing in the popup can be chosen" and lets it open regardless; every other picker in this library promises that a read-only control's popup does not open at all, and a select that opened beside a date picker that did not is the form that looks assembled rather than designed. `PlSelect` now holds the popup's open state itself and keeps it shut while `readOnly` — held rather than passed conditionally, so a field unlocked while it is on screen does not switch between controlled and uncontrolled underneath Base UI. An open the lock swallowed is dropped rather than remembered: recorded, it would spring the popup open the moment the read-only lifted, so a form that unlocks a section would drop a menu over it at nobody's asking.
+
+- **A chart's grid, axis rules and baseline were invisible.** `internal/chart-frame` draws all three with `var(--plass-chart-grid)`, `var(--plass-chart-axis)` and `var(--plass-chart-baseline)`, and none of the three was ever declared — an unresolvable `var()` on a `stroke` computes to `none`, so `PlLineChart` and `PlAreaChart` shipped with no gridlines, no axis rule and no baseline at all. The faint horizontal lines visible in the docs were the demo canvas's own background showing through the translucent sheet.
+
+  The three are declared now, derived rather than picked so a project that re-tones its border moves the grid with it: the grid is the border at 70%, the axis is the border, and the baseline — which is where a bar starts from and where zero is, a fact about the data rather than furniture — is the muted foreground at 35%. `PlassToken` names them, which is what the package test that caught the omission checks.
+
+- **A `PlTree`'s branch dropped in and vanished rather than opening.** It was the last fold in the library that did not travel: an accordion, a collapsible and a pill all move a height over 260ms, and this one swapped its rows in and out between two frames — under the twisty that had just been pressed, which is exactly where a reader is looking. The branch is a Base UI `Collapsible` now, written with the two lines a `PlCollapsible`'s panel is written with.
+
+  Folds nest exactly, which is the part worth checking rather than assuming: Base UI sizes an idle-open panel `auto` and only measures a pixel height for the length of the transition, so an outer branch contains an inner one opening inside it frame for frame with nothing to catch up to. Measured in a browser — 192px, then 224px with an inner branch open, with the outer at `auto` throughout.
+
+  The cost is that **a shut branch's rows are built and not mounted**, because rows dropped from the document on the frame the twisty turns have nothing to travel. React discards the elements, so it is a cost of building rather than of rendering, and `children: undefined` until a branch is opened is the answer for a tree with hundreds of closed folders in it. The Flutter build does not pay it — a fold there takes a callback — and the [tree](https://plass.cdget.com/components/display/tree) page says so. **+0.3 kB on the whole library** and nothing at all on a bundle that does not import `PlTree`, measured with `npm run size`: the primitive was already on the graph for `PlAccordion` and `PlCollapsible`.
+
+- **A `PlSlider`'s thumb teleported to any value nobody dragged it to.** An arrow key, a press on the rail, a value set from outside — the thumb was in one place on one frame and somewhere else on the next, on the one control whose whole subject is _where along here_. It travels over the house duration now, and the run behind it fills at the same rate.
+
+  **Nothing at all while the pointer is down.** A thumb that eased towards a finger would be a thumb lagging behind it, which reads as the control being slow rather than as the motion being smooth, so `data-dragging` zeroes the duration on both parts. The properties are `inset-inline-start` / `bottom` and the indicator's `width` — the ones Base UI writes the value into — rather than a `translate`, which is why this does not bend the [no-transform rule](https://plass.cdget.com/design/design-language#controls-do-not-move): nothing is shifted off its own place, because the thing being moved is the value.
+
+- **A `PlTree`'s twisty jumped between its two angles.** It carried the house transition and nothing else, and the house transition deliberately has no `rotate` in it — so on a span whose only colour is a constant it was a transition of nothing at all. The turn names itself now, the way an accordion's and a select's chevrons already do. It matters more here than the size of it suggests: the twisty is the only thing on a row that says whether the branch is open, and every other chevron in the library turns.
+
+- **A tick and a radio dot arrived whole, on the frame the box filled.** Both were the last state change in the library still expressed as a swap: the mark was there or it was not, on a control whose whole job is to answer a click, and the mark is the part a reader is looking at.
+
+  Neither is scaled into place, because [controls do not move](https://plass.cdget.com/design/design-language#controls-do-not-move) and that rule is not bent for the small parts. **A tick draws itself along its own path** — the stroke is dashed at exactly its own length and slid out of view by exactly that, so how much of the mark exists is one number, and `pathLength="1"` renormalises the tick and the dash to the same 0-to-1 whatever their real geometry is. **A dot grows out of the middle of its ring** — the ring centres a fixed-size child, so a width and a height are laid out about the same point and nothing outside the ring can be moved by either.
+
+  Both marks are now **kept in the document at nothing** rather than unmounted, because Base UI waits for animations on the indicator itself and not on the `<path>` inside it — an exit would otherwise be cut off on its first frame, and a control that animates one way and cuts the other means two different things by the same click.
+
+- **A `PlSelect` and a `PlCombobox` popup arrived and left between two frames.** Every other floating surface in the library fades — a modal, a drawer, a menu, a tooltip, a popover, a date picker's sheet — and these two were the ones that did not, so the same gesture had two different answers depending on which control the reader was standing on. They fade now, on the same one line the others use.
+
+  Opacity only, which is the point rather than a shortcut: a list that slid or grew in would be dragging its own options across the field they are being read against, and the options are the thing being looked at. Base UI keeps the popup in the document for the length of the ending transition, so a list closes the way it opened instead of vanishing.
+
+- **Three things that were written as fades were not fading.** `opacity` was missing from the house transition's property list, and three states are expressed in this library as an opacity and nothing else: `opacity-50` is what every disabled control looks like, a `PlBackTop` arrives and leaves on `opacity-0`, and a `PlImage` uncovers itself the moment the picture decodes. All three changed between two frames — a button that blinked into the corner of the page, a photograph that replaced its own skeleton, a key that went grey the instant it was disabled.
+
+  It is one word in one array, and the reason it is worth a line here is the rule it restores rather than the size of it: **a value that carries a state has to be in the transition that carries states.** The list is otherwise unchanged, `transform` included — it is still not in it and still should not be.
+
+- **A `PlTabs` bar that scrolls now says so.** The bar has always scrolled when there were more tabs than room — what it could not do was tell anyone. A macOS scrollbar is an overlay that appears while the strip is moving and is invisible the rest of the time, which is every moment a reader is deciding whether there is more to look at; the Windows one is fifteen pixels of permanent furniture under a row of labels. Both are taken away and the ends are faded instead — **only** the end that still has tabs behind it, which is what makes it a signal rather than a decoration. The fade is a `mask-image` rather than two gradient overlays because a bar can sit on anything, and an overlay would have to be painted in the colour of a background the component cannot know; taking the pixels away is right on every surface. It is dropped entirely while a tab inside is showing a focus ring, since focusing a tab scrolls it flush against the edge the fade is strongest at. Measured rather than declared — whether a bar overflows depends on the room it was given, so there is no prop that could answer it — and published as `data-overflow` on the tab list (`none` / `start` / `end` / `both`, in the reader's order) so a page can style against it. **+0.4 kB on the whole library** and nothing at all on a bundle that does not import `PlTabs`, measured with `npm run size`.
+
+- **A `PlScrollZone`'s inline scroll button now stands in its lane instead of hiding in it.** With `buttons="auto"` and the default `inline` placement, the button with nowhere to go was drawn invisible so that its lane would not come and go and resize the strip under the pointer. The lane was right and the emptiness was not: the space is paid for either way, and a reserved empty lane beside a strip does not read as restraint — it reads as odd padding on one side of the box. It is `disabled` and visible now, which is what `buttons="always"` already drew in the same position, so the two settings no longer disagree about what "nowhere to go" looks like. What `auto` decides is whether the strip has scroll buttons at all. An `overlay` button is unchanged and still goes, because there the space costs nothing to give up — **remove a control when its absence is free, disable it when it is not**.
+
+- **A `reversible` `PlSpoiler` changed height when it was opened, and again when it was closed.** The Hide row was drawn only once the spoiler was uncovered, so revealing grew the sheet by the height of a button and covering it again shrank it back — the page moving twice around the control somebody is pressing. The row is built from the start now and merely held invisible and out of reach under the cover, so its space is paid for once. The generalisation is worth keeping: **a control that appears with a state should reserve its space in the other state**, because the space is the part a reader notices.
+
+- **A `ghost` `PlToggle` that was off drew itself as one that was on the moment the pointer arrived.** Its hover was `--p-soft`, and `--p-soft` is exactly what a `ghost` toggle _on_ is painted with — so the two states differed by their ink alone, which is not a difference a reader is going to read. The hover climbs the neutral glass ladder in all three variants now, the same two rungs `solid` and `glass` were already using and the same wash an unselected `PlBottomNavigation` item takes for the same reason. The rule the fix is written to is worth stating, because it is the one a two-state control fails quietly: **a control with two states cannot put the colour family on the false one**, and a hover is still the false state.
+- **The build empties `dist/` before it writes to it.** `tsc` writes and never removes, so a component deleted from `src/` went on being published: `package.json` ships the whole directory and the `./*` export resolves `plass-ui/thing` straight out of it, which means a removed name goes on importing and goes on being typed for everybody but the person who removed it. Two more things read that directory rather than the source — `scripts/build-styles.mjs` writes one `plass-ui/css/*.css` scan manifest per folder it finds under `dist/components`, and `scripts/minify.mjs` counts `@__PURE__` annotations across whatever is there — so a leftover folder was also a stale stylesheet manifest and a count that quietly disagreed with the source it was a count of. None of it failed a build; it failed in somebody else's install. `npm run clean` is the first step of `npm run build` now, and is its own script so it can be run on its own.
+
+### Changed
+
+- **A `PlButtonGroup` and a `PlToggleGroup` draw one run of keys rather than two copies of it.** The squared corners, the hairline overlap and the stacking context each key gets were written out in both components — the same three lists, and two places for the seam to stop lining up. They live in `internal/button-group.ts` now, beside the context both groups already publish. Nothing renders differently.
+
+- **A surface that takes the page now opens at 260ms rather than 150ms.** `PlModal`, `PlDrawer`, `PlOverlay` and `PlCommandPalette` — the sheet and its scrim together, so the two arrive as one thing. `--plass-duration-slow` already existed and was already what a height travels over; it was never applied to the thing it describes best.
+
+  150ms is a key going down. Across the whole window it is not a fade, it is a cut with a hint of blur on it, and a page that changes this completely that fast leaves a reader looking for what moved rather than reading what arrived. The line is written down on the [motion](https://plass.cdget.com/design/design-language#the-second-duration-is-for-what-takes-the-page) page and it is one question: **does the surface take the page, or hang off a control?** A menu, a popover, a tooltip, a select's list and a picker's sheet all still open at 150ms, because they are the size of the control they came from.
+
+  Nothing about the shape of the motion changed. It is still opacity and nothing else, in both directions, on the same curve.
+
+- **`PlStack` replaces `PlAvatarGroup`, and this is a breaking change.** A row of overlapping faces is one arrangement of a pile rather than a component of its own: a deck of cards, a stack of documents, a fan of thumbnails and a row of avatars differ in what is in them, not in how they are laid out. `PlStack` takes whatever it is given and never looks inside.
+
+  **The overlap is real layout, never a transform**, and that is the whole component. A translated pile is laid out one item wide: it paints outside its own box, and every element after it on the page is placed against a size the reader never sees — so it cannot go in a paragraph, a table cell, or a flex row beside a label without pushing something out of place. A negative margin makes the box measure exactly what it draws. Five 32px items at 10px of overlap: **120×32 `horizontal`, 32×120 `vertical`, 120×72 `diagonal`**, measured in a browser with the stylesheet loaded rather than reasoned about.
+
+  That last one is the part most implementations get wrong. **A flow only overlaps on the axis it flows along**, so `diagonal` flows across like `horizontal` does and takes its vertical step per item instead — one fixed offset in a row would put every item at the same height. It is also why `diagonal` is a **fan** and says so: the horizontal advance is `item width − overlap`, and a component that takes arbitrary children does not know that width.
+
+  `max`, `total` and `overlap` carry over unchanged. `overflow` is new and is a **function** — `(n) => <PlAvatar initials={\`+${n}\`} />`— because the hidden count _is_ that item, and a node would have to be handed a number it has no way to work out.`direction`, `front`, `scaleStep`, `opacityStep`, `drop`and`ring`are new. Depth is applied on the standalone`scale`property inside a second box per item, which is not spare: every keyframe in this library that grows or zooms writes`scale`, and on one box an entrance would overwrite the depth on its first frame.
+
+  **What is lost is the group context, and it could not be kept.** `PlAvatarGroup` set `size`, `shape`, `variant`, `color` and `elevation` once for every face; a pile that accepts arbitrary children has no way to know one of them is an avatar. `size` and `color` are axes an application already sets once — put a `PlassProvider` around the stack. The other three belong on the avatar. `PlAvatar` no longer reads a group at all and resolves those five from its own props and the provider.
+
+  `ring` is a boolean and lands on **the element you passed**, so it takes that element's shape: wrap an avatar in something square and the ring is square. The alternative was copying a class onto the children, which stops working the moment one of them is a `PlTooltip`, a fragment, or somebody else's `.map()`. Measured with `npm run size`: **+0.1 kB on the whole library**, and nothing on the four other scenarios.
+
+## 1.3.0 (2026-08-31)
+
+### Added
+
+- **Five fields take a `hotKeys` map.** `PlTextField`, `PlNumberField`, `PlOtpField`, `PlCombobox` and `PlSelect` now bind chords — `hotKeys` takes `{ 'Mod+Enter': save, Escape: cancel }`. What makes it worth a prop rather than an `onKeyDown` — which those five already took and still take — is that the chord is spelled **the way a key cap is spelled**, in the vocabulary [`PlHotKeys`](https://plass.cdget.com/components/display/hot-keys) draws: `Mod` resolves per platform, and `Esc`, `Return`, `Cmd` and `Option` fold onto the same keys their caps do. A shortcut a component displays and a shortcut it binds are now one string rather than two that can drift, which is the argument `PlCommandPalette` made when it bound its own opener — it carried a private copy of the matcher to make it, and that copy is now `internal/keys.ts` with `PlHotKeys` reading its alias table and its platform out of the same file. Three rules hold everywhere: the map sits on the **control** rather than on the stack around it, so a chord is answered by the thing that has the focus; a modifier is checked in **both** directions, so `Enter` does not fire on `Shift+Enter`; and a chord that matches is **consumed** — not reaching the form, the dialog above it, or the browser. Which is why these are chords rather than letters: a field with `{ a: … }` cannot type an `a`. A caller's own `onKeyDown` still runs first and can overrule the map by calling `preventDefault()`. The vocabulary also grew one alias, `NumpadEnter`, so the long spelling reaches the same key its cap does.
+
+- **A `PlDatePicker` can stop at a month or a year.** `precision` is `'day'`, `'month'` or `'year'`, and it is a _floor_: the calendar opens on the grid for that unit and pressing a cell in it answers, so a `month` picker's month grid is the last grid and there is no day grid under it at all. That last part is the point rather than a side effect — a card's expiry is a month, and a control that makes someone answer _which day of December 2027_ is a control that will be answered wrongly. The value stays a `Date`, normalised to the start of what was chosen: the 1st of the month, or the 1st of January, never whichever day or month the cursor happened to be resting on when the year was pressed. Three things follow it without being asked for — the trigger's default `format`, the hidden input's spelling (`YYYY-MM-DD`, then `YYYY-MM` and `YYYY`, which is what a native `<input type="month">` submits), and the footer's shortcut, which reads "This month" or "This year" rather than "Today" and brings two new `labels` entries with it. `minDate` and `maxDate` are then read **at the same precision**: a `minDate` of 15 July leaves July pickable on a `month` picker and hands back 1 July, because a bound on a control that returns a month is a bound on months. `shouldDisableDate` is day-granular and is not consulted at all.
+
+- **`PlVisuallyHidden`.** Content for a screen reader and for nobody else — the rule the library already applies inside a dozen of its own components, spelled once for the caller's own markup. The two obvious ways to hide something are both wrong in the same place: `hidden` and `display: none` take the text off the accessibility tree along with the screen, which is the one thing this exists to avoid, and `opacity: 0` leaves a clickable ghost the size of the words. A one-pixel clipped box is the only form that is absent to a sighted reader and present to every other kind. The ordinary use is naming a control whose whole label is a glyph — mark the glyph `aria-hidden`, or the control ends up with two names — and the other is a live region, which is a `<div>` with an `aria-live` and nothing to draw. `focusable` puts the box back in the flow while anything inside it holds the focus: that is the skip link, and it is the one variation a caller cannot add from outside, because the clip is `position: absolute` and revealing it means making the element `static` again. It answers `:focus-within` rather than `:focus`, since what is tabbed to is almost always the link _inside_ the box rather than the box itself. It is **React-only**, and deliberately: what it works around is a DOM problem, and Flutter's answer is `Semantics` with an `ExcludeSemantics` under it rather than a widget of ours.
+
+- **The media query machinery is public.** `usePlMediaQuery`, `usePlBreakpoint` and `usePlBreakpointValue` are the store a `PlSidebar` has always used to find out that it has become a drawer, given names — new surface rather than new code, which is why they arrive together. `usePlMediaQuery` takes any query and returns a boolean that re-renders when the answer changes; the other two are the same store asked about the ladder, and `usePlBreakpointValue` resolves the **same map shape** a responsive prop on `PlGrid` takes, with the same rule — a bare value applies everywhere, a map applies each entry from its own breakpoint up, and it is `undefined` below every rung the map named rather than a guess at one the caller did not write. The widths are Tailwind's own, and they are asked as media queries rather than measured off `innerWidth`: the ladder is written in `rem`, so a reader who has enlarged their default font size would otherwise get a rung that disagrees with the stylesheet beside it. **The first answer in a browser is the server's answer** — `false`, and `xs` — because `useSyncExternalStore` renders its server snapshot through hydration, which is exactly why the library's own components pair the hook with a CSS class rather than replacing one with the other. Anything that must be right in the first frame belongs in a Tailwind variant; these are for the decisions CSS cannot make, like whether a component is mounted at all. One `MediaQueryList` is now shared per query string across the whole page, where `useCollapsed` used to open one per component. They are exported from the barrel and from a new **`plass-ui/hooks`** subpath, and the documentation has a `Hooks` section to put them in.
+
+- **`usePlReducedMotion`.** The preference the library has always answered on its own behalf, given a name. `prefers-reduced-motion: reduce` is easy to typo and the mistake is silent, which is most of the argument for a hook over a query string. The other part is what the documentation can now say in one place: **"reduced" is not "none"**, and the library's own components disagree with each other on purpose — an entrance is dropped entirely, because an animation that never played has still delivered everything it was carrying, while a `PlProgressCircular` is _slowed_ rather than stopped, because a spinner that stopped would be lying about whether anything is still happening. The store moved with it: `internal/animate.ts` no longer keeps a `matchMedia` of its own, and the query is one more subscription shared through `internal/media.ts` like every other.
+
+- **`usePlHotKeys` binds a chord outside any one control.** The `hotKeys` prop added in this cycle put the vocabulary on a field; this puts it on the page, which is where an application's own shortcuts live and which `PlCommandPalette` has needed since it existed — it carried a private window listener to bind its opener, and now calls the hook like anybody else. The three rules come with it: a modifier is checked in **both** directions, a chord that matches is **consumed**, and — new, and true of the prop as well — an event that is _already_ consumed is left alone, so a field's binding wins over a page's. The interesting default is `whileTyping: false`, and it is narrower than the name suggests: a chord carrying `Mod`, `Ctrl`, `Meta` or `Alt` is answered in a field anyway, because none of them can appear in its value, and so is a key that does nothing to text — `Escape` above all, since a panel that closes on Escape has to close from inside its own form. What is held back is a printable character or one of the keys that edits or moves through text, which is exactly the case worth holding back: a global `/` must not eat the slash out of a URL somebody is typing. Handlers are read fresh on every keystroke, so the map may be written inline and a handler closing over current state is never stale; what re-attaches the listener is the **set of chords** rather than the object's identity. `target` scopes the binding to an element or a ref, and `enabled: false` removes the listener rather than muting the handler — a shortcut that is off should not consume the key from whatever else wanted it.
+
+- **`PlCalendar`.** The grid a `PlDatePicker` opens, on the page. It is not a new calendar — it is the same `internal/calendar.tsx` the four pickers already share, with the trigger and the popup taken away, which is why it arrives with the three views, the roving tab stop and the arrow keys that step the month when they run off an edge already finished. The reason to have both is what each one _is_: a picker is a **field** that happens to open a calendar and belongs in a form beside other fields, and this is a calendar that is not standing in for a field — a booking page, an availability view, a date rail — where the grid is the interface rather than a way of filling one in. So it has no `label`, `description` or `error`, and it keeps `name`, so a plain form can still submit what it holds. `precision` is the same **floor** the picker's is, and the value is normalised to the start of what was chosen. Two props are deliberately absent: there is no `density`, because padding on a grid of forty-two squares is what stops them being squares, and no `readOnly`, because a read-only field still shows a value a reader can select and copy while a calendar has nothing to copy — a grid whose every cell is inert _is_ the disabled one, and `disabled` draws it with the `inert` attribute rather than with a `disabled` on forty-two cells. `autoFocus` is **off**, the opposite of the picker's: a popup has just been opened by somebody who wants to be in it, and a calendar in a page has not.
+
+- **`PlassProvider` sets the defaults once.** Sixty-six components resolved `size`, `color` and `density` from a literal in their own destructuring, which meant an application whose controls are `sm` said so at every call site — not a design decision, transcription. They now resolve from the nearest provider instead, in four layers and in the order a reader would guess: **the component's own prop, then whatever set it is in, then the provider, then the component's own default**. So a `size="lg"` on one button still wins inside a `PlButtonGroup` inside a compact application. Providers nest and **merge**, so a section that says only `density` keeps the `locale` from the one above it. The date vocabulary comes with it — `locale`, `weekStartsOn` and `labels` reach all five date components and `PlNumberField`, and `labels` merges _under_ each component's own so an application can translate the set once and one picker can still say something different.
+
+  **`variant` and `elevation` are deliberately not in it**, and the absence is the load-bearing part. `variant` names what a surface is made of, and a `PlButton` is `solid` while a `PlCard` is `glass` because that is the arrangement rather than an unset default; `elevation` is per-component semantics for the same reason, a control resting **on** the sheet at `1` and a field cut **into** it at `0`. One value for either would not be a default, it would be a flattening. `usePlassDefaults()` reads what is in scope, for a caller's own component that has to line up with the ones around it.
+
+  **`PlTable` is the one component that does not read it**, and stays the one exception it already was: reading a React context would make it a client component, and it is kept out of that graph on purpose, because every one of its columns is a `render` callback and a server component cannot hand a function across the boundary. A new package test asserts the contract from both ends — that a provider produces byte-identical markup to writing the prop, on fourteen components, and that no component takes a style axis without reading the defaults.
+
+  **What it costs**, measured with `npm run size` — a real esbuild bundle of `dist/`, gzipped, React external: **+0.1 kB on a five-component form and +1.9 kB on the whole library**. That is one `useContext` per component plus the resolution lines, and it is paid whether or not a provider is ever rendered, because the read is unconditional. A single `PlButton` is unchanged to the tenth of a kilobyte.
+
+- **`usePlColorScheme` and `PlColorSchemeScript`.** Dark mode already worked — the tokens answer `prefers-color-scheme` and can be forced with `.dark` or `[data-theme]` on any ancestor — and what was missing was everything around a **choice**: somewhere to keep it, something to write it onto `<html>`, and a way to paint it before the first frame. The hook is the first two. `system` is deliberately the absence of a choice rather than a third theme: it removes the attribute and hands the question back to the platform, so a reader who picks it goes back to following their computer rather than being pinned to whatever their computer said at that moment. `toggle` flips from what is **painted**, so the first press on a system-dark page gives light, which is what pressing a toggle means. It writes the attribute **and** the class, and that is not belt and braces: the attribute is what this library's tokens read, and the class is what a consumer's own Tailwind `dark:` utilities read when they are configured against a class — a toggle that moved one and not the other would leave a page half switched. Two toggles on one page share one store and agree with each other, and a second tab that changes the scheme changes this one, because the choice is one the reader made about themselves rather than about a window.
+
+  `PlColorSchemeScript` is the third, and it is the one that has to be a **server component**: React runs after the document is parsed, so a theme applied from an effect is applied one paint too late and the reader has already seen white. It goes in `<head>`, renders nothing but an inline `<script>`, calls no hook and reads no context — a client component here would arrive with the bundle and be too late by definition. `suppressHydrationWarning` on `<html>` is the other half and is not a workaround: the script's whole job is to change that element before React hydrates.
+
+  The stylesheet gained one declaration with them: **`color-scheme`**, stated per theme block. Scrollbars, the caret, a native `<select>` popup and a date input's own calendar are the browser's to paint and none of them is ours to style — they were white on a page forced to dark, which reads as broken rather than themed.
+
+- **`PlConfirmProvider` and `usePlConfirm`.** `await confirm({ title: 'Delete this project?', color: 'danger' })` resolves with the answer, so the branch after a question stays in the handler that asked it. The argument for a hook rather than a component is the same one `PlToastProvider` made: what a caller has at the moment a question is warranted is a **click handler**, not a place in the tree — and without this, adding a confirmation to one button means a piece of state, a `<PlModal>` kept mounted beside it, and the work after the answer torn in half across a callback, repeated at every button that needs one. `alert` is the one-button form and resolves when it has been acknowledged, which is what makes it awaitable in the middle of a sequence.
+
+  Three decisions worth stating. **Cancel holds the focus by default**: a confirm dialog exists to make somebody stop, and an Enter key that lands on the destructive action defeats the whole thing — `initialFocus: 'confirm'` moves it for a question whose yes is the harmless answer. **Questions asked while one is open are queued**, in order, with the sheet's content changing rather than the dialog closing and reopening; the alternative is a promise nobody ever resolves, which is a hung button rather than a visible bug, and a provider that unmounts with questions outstanding resolves them all `false` for the same reason. And **`usePlConfirm` throws outside a provider** rather than answering `false`, because a silent `false` is a delete button that quietly does nothing, which is worse than a missing provider that says so on the first press.
+
+- **`PlStepper` and `PlStep`.** A process the reader is moving through, and where they are in it. It draws the same rail a `PlTimeline` does — and _shares_ it: the bullet ladder, the three states, the connector and the status arithmetic moved into a new `internal/steps.ts` that both components read, because a haloed bullet must not mean two things and two copies of twelve lines are two copies that drift. What differs is what each one is for, which is also the whole of when to reach for which: a timeline **reports** a sequence that already happened and nothing on it can be pressed; a stepper **is** the sequence, its steps are buttons and the current one owns a panel.
+
+  `active` is an **index** rather than a value, exactly as a timeline's is, because a stepper has no selection. `linear` is on by default — the third step of a sign-up cannot be filled in before the second — while a step _behind_ the reader is always reachable, since going back to correct an answer is the whole reason a stepper is not a wizard with one door. Horizontal puts the panel under the rail and **vertical puts each panel inside its own step**, which is the reason to lay one out vertically at all. `status` overrides where the sequence says a step is, for the one that failed validation while the reader was three steps on. And it is deliberately **not** a `role="tablist"`: a tab list owes a keyboard reader one tab stop and arrow keys, and claiming the role without the behaviour is worse than never claiming it — each reachable step is its own tab stop, and a step nobody has reached yet is not a button at all rather than a disabled one.
+
+- **`PlTree`.** A hierarchy opened one branch at a time. It takes its nodes as **data** rather than as children — the opposite of most of this library, and the right way round here for one reason: a tree is recursive, and recursion written in JSX is a component every caller has to write for themselves. `PlTable` takes its columns the same way and for the same reason.
+
+  `expanded` and `selected` are separate arrays and separate questions, because opening a folder is not choosing it. `selection` is `single` by default, `multiple` says so with `aria-multiselectable`, and `none` makes the tree a **browser** rather than a chooser — rows still expand and a click still reports, but nothing stays lit. **`children: []` and `children: undefined` are different things**, visibly: the first is a branch that opens and shows nothing, the second is a leaf with no twisty at all, which is what makes a lazily-loaded tree possible. The keyboard is the ARIA tree pattern and is most of what makes this a tree rather than a nested list — **one tab stop** for the whole thing, following the focus rather than leading it; ↓/↑ walking the rows that are actually visible; → opening a branch and _then_ stepping into it, two presses rather than one, so a reader can open a branch without leaving the row that told them it was there; ← closing it or stepping out to the parent.
+
+- **`PlImage`.** An `<img>` is one tag and it works, so this says what it adds rather than assuming it. Three things: the space is **reserved** before the picture arrives, so the paragraph under it does not move when it does — that is `ratio`, and it is the prop worth reaching for every time, because without it there is nothing to reserve; a failure is **drawn** rather than left as the browser's broken-image glyph and the alt text in a serif nobody chose; and the two are **one state machine**, so a placeholder is never still sitting behind a picture that has loaded, and a changed `src` starts again rather than inheriting the last one's success. The `<img>` stays in the document the whole time, because an `<img>` that is not in the document never loads. `alt` is required and `""` is a real answer rather than a missing one. `preview` opens the picture over the page in a `PlOverlay` and is off by default — a picture that grows when you click it is a promise that there is more of it to see, and most pictures on a page are not making it. There is no gallery component and no next/previous inside the preview, deliberately: a gallery is a list with a state of its own, and it composes out of what is already here.
+
+- **`PlEmpty`.** An empty list, a search that found nothing, a request that failed and a flow that has finished are the **same arrangement** — a mark, a line, a sentence, a way out — which is why they are one component and not four, and why `color` is what tells them apart: `secondary` is "nothing here yet", `danger` is "something went wrong", and `success` is "you are done", which makes the order-confirmed screen without a second component. It draws **no surface**: an empty state is always inside a card, a table or a panel, and a sheet inside a sheet is two sheets — `PlTable`'s `empty` prop takes a node, and this is the node it was waiting for. The part worth getting right is the way out, and it is the reason `actions` is a slot rather than an afterthought: a screen that says "No projects" and stops is a dead end, and the same screen with a "New project" button is the best moment in the whole flow to offer one. It has **no role of its own**, deliberately — `role="status"` belongs on it when the emptiness is the _result_ of something the reader just did, and not on a list that was already empty when the page loaded and has therefore already been read.
+
+- **`PlPopconfirm`.** A question asked where it was raised. The difference from `PlConfirmProvider` is not the words, it is **how much it interrupts** — a modal takes the page away and is right for the question that deserves that, and this appears against the row's own delete button, leaves the rest of the table readable, and puts a reader who changes their mind back exactly where they were. The rule of thumb is what happens if they answer by accident: if they can undo it, this is the one. `color` defaults to `danger` here and to `primary` on a `PlButton`, and that is not an inconsistency — nobody reaches for a popconfirm to ask whether to save.
+
+  `onConfirm` may return a **promise**: the button shows its loading state until it settles, the popup closes only if it _resolves_, and Escape is ignored while it runs, because a request in flight is not something to abandon halfway. A rejection is caught and goes no further, and that is a decision rather than an omission — keeping the question on screen is the whole of what this component owes a failure, and what the failure _means_ belongs to the caller who returned the promise and has the context to raise a toast about it. The focus lands on the **confirming** button, the other way round from the modal and deliberately: a popconfirm is opened _by_ the button it is asking about, so the reader has already said what they want once.
+
+- **`PlBackTop`.** The way back up, once there is a way back up to want. It is **hidden until it is useful**, and that is the whole design rather than a nicety: a button pinned to the corner of every page from the first paint is one more thing covering the content, and on a page short enough not to scroll it is a control that does nothing. While it is out of reach it is `aria-hidden` and out of the tab order rather than merely faded — a control a reader can tab to and cannot see is worse than one that is not there. `target` takes a ref, so a panel that scrolls inside the page gets one of its own, and `floating={false}` keeps the appearing and the scrolling while giving up the corner. The scroll is smooth and **not** under `prefers-reduced-motion`: a page that flies past a reader who asked for less movement is the exact case that setting exists for, so it jumps instead and arrives in the same place. The position is read once on mount as well as on every scroll, so a page restored halfway down — a back navigation, an anchor in the URL — has the button already there.
+
+- **`PlStat`.** One figure, and what has happened to it. A row of these is the top of every dashboard, and the whole of what makes them worth a component rather than three `<div>`s is the **change**: a number on its own says what things are, and a number with a movement beside it says whether that is going anywhere.
+
+  The colour of that movement is decided by `improvesWhen` and **not by the sign**, which is the one thing a naive version of this gets wrong — churn going up is not good news, and a green arrow on it is a dashboard lying to somebody. `value` takes a **node** rather than a number, deliberately: how a figure is written — the currency, the grouping, the decimals, the locale — is the page's decision and `Intl.NumberFormat` already makes it, so a component that took a number would have to guess at all four. The arrow is `aria-hidden` and the sign is in the text, so colour is never the only thing carrying the direction.
+
+- **A `PlPopconfirm`'s two buttons wrap.** They sat in a row that could not break, so a pair of labels translated into anything longer than "Confirm" and "Cancel" ran off the 280px sheet. Found while porting the component to Flutter, where the same arrangement is a layout error rather than a quiet overflow.
+
+### Fixed
+
+- **`dir="rtl"` turned the layout over and left the behaviour behind.** Base UI reads the writing direction from a **React context** and from nowhere else: with no `DirectionProvider` in the tree its `useDirection()` answers `ltr` however the document is written. That decides a `PlSlider`'s arrow keys, the way ←/→ walk a `PlTabs`, a `PlMenubar` or a `PlRadioGroup`, and which physical edge a popup's logical `align` resolves to — so a right-to-left page that set the attribute and stopped **looked** right and **behaved** left to right. Proved with a test before it was believed: `ArrowRight` on a slider at 40 answered 45 in both directions.
+
+  `PlassProvider` now renders that context, and takes the answer **off the document** rather than from a prop — `getComputedStyle(document.documentElement).direction`, watched with one `MutationObserver` for the whole page. A second place to declare the direction is a second place to get it wrong, and the page has already said it. The new `direction` prop is only for the case the document cannot answer: a subtree that runs the other way round from the page it is in, or a server that knows before there is a document to ask. It merges through nested providers like every other default.
+
+  The cost is **+0.3 kB gzipped** on the everything-imported scenario and nothing at all on the four narrower ones, because the provider is only ever reached through the barrel.
+
+- **A `PlAnimateMarquee` delivered its words backwards under RTL.** The strip's flex track had already reversed on its own, and the animation had not — there is no logical `translate`, so the keyframe was still travelling towards the physical left and running the content off the wrong edge. The sign is now a custom property that `[dir='rtl']` flips, which makes it the one right-to-left rule in the library that lives in the stylesheet; the test for it loads the shipped sheet, because no component test loads CSS.
+
+- **Three components ran the wrong way under RTL.** The library has always been written in logical properties, and that turned out to be the easy half — what nobody had was a test, so the three places the rule had been broken had been broken quietly. A **`PlPanes`** handle nudged with the arrow keys moved the boundary _away_ from the key it was pressed with: the drag path read the writing direction and the keyboard path did not, which made the component page's own claim that "the arrow keys follow the writing direction, exactly as a drag does" false. A **`PlSwitch`**'s thumb travelled on `left`, so under RTL it sat at the wrong end of its track and moved the wrong way — every platform's own switch puts off at the inline start, which is the right-hand end. And a **`PlCard`**'s `headerAction` was pushed out with `ml-auto`, landing it on the left of a right-to-left header. `PlDivider`'s vertical rule moved to `border-inline-start` with them; it drew identically either way, and now it is spelled the way everything else is.
+
+  The test that found them is `test/package/rtl.test.tsx`, and it is a contract test rather than a component one for the reason the contract is: RTL is not a feature any component has, it is a rule every component follows, and it breaks one component at a time in a class name nobody looked at twice. It drives a real `dir="rtl"` document for the parts that are decided in JavaScript, and reads every component's source for a physical direction utility that is not on a short list of deliberate exceptions — each of which is a place where the **thing being measured** is physical too (`offsetLeft` for a moving indicator, Base UI's own `data-side` for a tooltip arrow, `PlassSide` for a drawer's edge). Pairing a logical property with a physical measurement is what would actually break the direction.
+
+### Documentation
+
+- **[Right to left](https://plass.cdget.com/design/rtl) is a page.** The support was there and undocumented, which is nearly the same as not having it: a reader evaluating the library had no way to find out. It says what the one-attribute setup is, what flips and what deliberately does not, and names the three places the direction is read in JavaScript and why each one has to be.
+
 ## 1.2.0 (2026-08-30)
 
 ### Added