qss 0.6.0 → 0.7.0

data/CHANGELOG.md

@@ -3,124 +3,165 @@
 All notable changes to the qss gem. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [Semantic Versioning](https://semver.org/) (before 1.0, minor versions may break the API).
 
-## [0.6.0] - 2026-10-22
-
-Never published as 0.4.3 or 0.5.0; both numbers were used for this same work before it shipped.
-
-### Added
-- `qss-text-size-linear[N]` (N 1 to 96): text that scales in pure proportion to the viewport, `N * 100vw / 1440`, with no
-  floor, no cap and no dampening, for cosmetic text (wordmarks, titles) that should resize like a picture. It uses the
-  same unit as `qss-icon-size[N]`, so it tracks the viewport width, not the canvas. Body copy should keep using
-  `qss-text-size[N]`. The Ruby auditor's below-11 legibility check only reads `qss-text-size[N]`, so it does not apply here.
+Each entry below is written from that release's own vantage point — what problem prompted it, what was tried and
+discarded along the way, and what shipped instead — rather than edited later with knowledge of what came after. A
+rejected approach stays rejected in the entry that rejected it, even where a later entry finds a different answer
+to the same question. For the same story told forward in time, with the full unabridged reasoning, see
+[docs/DESIGN_HISTORY.md](docs/DESIGN_HISTORY.md); this file stays to the point a release note needs.
+
+## Origins (before 0.1.0)
+
+QSS began inside Parapet, a Rails development tool, after a recurring failure: asked to move a sidebar 10px left,
+an AI coding agent would edit a margin, then an `order`, then a `flex-basis` — and something else on the page
+would move. It would report the change as done while the page was visibly broken. The diagnosis mattered: this
+wasn't agents being bad at arithmetic (a single explicit value is easy to edit correctly), it was *ambiguous
+intent-to-mechanism mapping* — "left" is not one property under flex or grid, so the agent has to guess which of
+several plausible ones to touch, and the guess is where it goes wrong. The fix that followed: keep every
+structural value explicit, single-purpose and directly addressable, so an edit always has exactly one target.
+
+The first attempt at that fix was a custom bracket grammar (`pos-x[500]`, `w[240]`) with its own JavaScript parser
+and a whitelist auditor. It didn't hold up: the hand-maintained parser was the actual bug farm (a regex one comma
+could defeat, a whitelist that drifted between client and server), an invented syntax cost agents an unfamiliarity
+tax they didn't pay with plain CSS, and "verified" by the tool that made the change turned out not to mean
+verified at all — repeatedly, a change shipped green with the auditor and tests passing while the page didn't
+actually work, and only a real browser ever caught it. The rebuild that followed kept the structural ideas that
+had held up (one flat canvas, frames that isolate their own layout, overlays routed to a portal instead of a
+`z-index` war, no `!important`) and moved everything else to plain CSS custom properties and real browser
+verification. Extracted as this gem once that rebuild stabilized.
 
-### Changed
-- The `qss-text-size[N]` floor drops from a flat 9px to 5px (`text_scale.floor_px`). With 9px, every N from 1 to 10
-  computed `N * 0.875` below the floor, so `[5]`, `[7]` and `[10]` all rendered at exactly 9px. Now `[5]` floors at 5px
-  and `[7]` and up scale with the canvas (`N * 0.875` is the floor from N = 6), so small sizes are distinct. The cap and
-  `floor_multiplier` are unchanged. A small size on a narrow canvas can now render smaller than before; the auditor's
-  legibility check (below 11, `qss-legibility-override` to waive) is unchanged.
-
-## [0.4.2] - 2026-10-20
+## [0.1.0] - 2026-09-25
 
-### Added
-- A dimension can be declared by an `#id { ... }` rule in a configured tool or host stylesheet, not only by a size
-  class. The implicit-dimension check (red for a `qss` actor, orange for other structural elements) now also reads the
-  actor's own id from `tool_stylesheets`, `host_stylesheets` and `stylesheet_path`: `width`/`inline-size` declares the
-  width, `height`/`block-size` the height, `left`+`right` (or `inset`, `inset-inline`) pin the width, `top`+`bottom`
-  (or `inset`, `inset-block`) pin the height. This is how an actor anchors to another actor's resizable dimension with
-  plain custom properties (`right: var(--bar-w)`), which the bracket classes cannot express. Only unconditional rules
-  count: a rule inside `@media`/`@supports`, a nested rule, or a compound selector (`div#x`, `#x:hover`, `#x.on`)
-  declares the size only sometimes and is ignored, as is a value that sizes nothing (`auto`, `fit-content`, ...).
+First release, extracted from the Parapet project.
 
-## [0.4.1] - 2026-10-20
+The canvas unit (`--qnt`, canvas width / 1000) had spent its whole history being *set by JavaScript* after
+measuring the page — until the day before this release, when it moved to pure CSS (`0.1cqw`, a container query
+unit, registered as a length so it resolves once at the canvas and inherits unchanged). That one change is why the
+compiled stylesheet works with no JavaScript engine at all: previously, the base actor reset outranked every
+compiled utility on CSS specificity, and utilities had only ever worked because the runtime engine re-emitted them
+to win the fight. A render check (headless Chrome, CSS alone, no engine) exists specifically so that fact can
+never go unnoticed again. Also fixed on the way here: an actor's scroll area silently growing to its content's
+full height because nothing required a declared height (now an auditor rule), and the vocabulary settling on
+noun/adjective/attribute (an id is the noun; classes are adjectives; `qss-function`/`qss-relation` are attributes).
 
 ### Added
-- `QSS::Error`, the base of every failure QSS raises on purpose: `ConfigurationError`, `IntegrityError` (and so
-  `CoreIntegrityError`, `ToolIntegrityError`). One `rescue QSS::Error` covers all of them; each means the audit cannot
-  run as configured, not that a view has a finding. `ConfigurationError` is not an `IntegrityError`.
+- Core stylesheet (`qss/qss_core.scss`, compiled `qss/qss_core.css`): utilities on a 1000-unit canvas grid; the unit
+  (`--qnt`, canvas width / 1000) computed by CSS alone (`0.1cqw` of the canvas; the viewport width outside one).
+- Base reset for QSS actors at the canvas id's weight only, so every core utility applies without the JS engine.
+- Neutral `!default` SCSS settings (`qss/_qss_defaults.scss`); a project sets its own before importing core.
+- Optional runtime engine (`qss/qss-engine.js`): rules for uncovered bracket classes, measured element edges.
+- `QSS::QssNativeAuditor`: id grammar (`{qualifier}-{baseObject}`, `QSSObject` custom types) with a per-project
+  registry, `qss-function` / `qss-relation` attributes, explicit dimensions for every actor, unit rules (no raw CSS
+  lengths on QSS structure; rem or % only in foreign content), `!important`, z-index and inline-style checks.
+- `QSS::QssAuditor`: the older class-whitelist auditor.
+- `QSS.configure(root:, config:)`: a project's settings read at runtime; paths resolve against its root.
+- `QSS::Blueprints` (`QSS.grid`, `QSS.object`): layout arithmetic and object blueprints.
+- `QSS::Engine`: Rails engine for the asset pipeline, loaded only when Rails is present.
+- `qss-sync`: writes a project's SCSS settings (`--core` regenerates the gem's own generated sections).
+- `qss-core-render-check`: renders the compiled CSS alone in headless Chrome and checks core utilities.
 
-### Changed
-- A configured stylesheet that is not on disk (`drywall_stylesheet_path`, `stylesheet_path`, or a literal `host_stylesheets` entry)
-  now raises `QSS::ConfigurationError` naming the file. Before, it loaded as an empty stylesheet, so a Tailwind build that had
-  not run yet showed up as a large, misleading `unresolved_class` count. A glob that matches nothing is still just empty.
+## [0.1.1] - 2026-10-05
 
-## [0.4.0] - 2026-10-19
+### Fixed
+- `contain-layout` and `qss-contain-layout` now have a rule (`contain: layout`) in `qss_core.css`. The README
+  documents the class for structural frames and the native auditor mandates it, but the stylesheet never defined it,
+  so a frame that satisfied the auditor received no containment. Anyone already using the class will now get layout
+  containment on those frames: check that absolutely and fixed-positioned descendants still position as expected.
+  Covered by a spec on the compiled stylesheet and by three checks in the browser render check (21 in total).
 
-### Added
-- Three-tier stylesheet audit. The auditor now resolves classes against up to three tiers, and tiers 1 and 2 are
-  integrity-checked and otherwise silent (they surface only as an integrity failure):
-  1. **Core**: the gem's own `qss_core.css`, always known, never configured. `rake compile` marks it DO NOT EDIT and
-     writes `config/integrity.json` (its SHA-256, line endings normalized, plus the gem version); the auditor
-     verifies it before use. A mismatch, a missing file or a manifest from another version raises
-     `QSS::CoreIntegrityError`.
-  2. **Tool**: `auditor.tool_stylesheets`, a dev tool's own compiled chrome (for example Parapet's
-     `qss_application.css`). The tool seals each file when it builds it with the new `qss-seal` executable (or
-     `QSS::Integrity.seal`), which writes `<file>.qss-seal`; `--header` also marks the file DO NOT EDIT. An unsealed or
-     changed file raises `QSS::ToolIntegrityError`.
-  3. **Host**: `auditor.host_stylesheets`, the end consumer's own compiled output, as paths or globs relative to the
-     project root, plus whatever `QSS.configure(host_stylesheets: -> { ... })` returns (evaluated each time the
-     settings are read, in the host's own process). With nothing configured, a Rails host gets
-     `app/assets/builds/*.css`.
-- `QSS::IntegrityError`, the base of both integrity errors, so a host's CI can rescue and report one class.
+## [0.1.2] - 2026-10-05
 
 ### Changed
-- Core's classes are now always known to `unresolved_class`. Before, setting `stylesheet_path` replaced core's
-  stylesheet, so a consumer that listed only its own file lost every core class. `stylesheet_path` and
-  `drywall_stylesheet_path` keep working (`stylesheet_path` counts as a host stylesheet). The Tailwind/QSS boundary
-  check is unchanged and still reads `drywall_stylesheet_path` only.
-
-## [0.3.1] - 2026-10-19
-
-### Fixed
-- The overlay portal root had no base geometry in the compiled stylesheet, so anything portaled into it rendered at
-  the wrong position and size. Every generated utility is scoped `:is(<canvas>, <portal root>) .class`, which only
-  ever matches a descendant of a root, never the root itself, so `qss-absolute qss-inset-0` written on the portal
-  root itself matched nothing; the canvas escapes this through its own unscoped "Root Anchor" rule, and the portal
-  had no equivalent. Measured in a real browser: the root landed in normal flow after the canvas (zero width and
-  height, `top` equal to the viewport height), and a `qss-w[640] qss-pos-r[16]` overlay inside it resolved against
-  that empty box (negative `left`, wrong size). The portal root now gets its own rule by id: `position: fixed;
-  inset: 0` (a viewport-sized layer; placed after the canvas it paints above it with no `z-index`),
-  `container-type: inline-size` with `--qnt` resolved on its children exactly as the canvas does (so qnt-sized
-  overlays measure against the viewport's width, equal to the canvas unit whenever the canvas spans the viewport),
-  `pointer-events: none` on the root and `auto` on its direct children (a viewport-sized transparent layer must not
-  swallow clicks meant for the page), and the same actor reset the canvas gives its actors. That reset moved into a
-  shared mixin (`qss-actor-reset`), so an actor portaled into an overlay is a full Steel Frame actor too.
-  Classes written on the portal root itself still do nothing; its geometry is built in. The engine's runtime rules
-  were already unscoped and needed no change.
-- New real-browser coverage in `rake render_check` (`qss-core-render-check`, now 35 checks): a portal root carrying
-  the documented `qss-absolute qss-inset-0` is asserted to compute a fixed, exactly viewport-sized box, and a
-  qnt-sized overlay inside it to have its real width, height and edge offsets. Run against the 0.3.0 stylesheet, 7 of
-  those checks fail, reproducing the report. The static auditor cannot catch this class of bug, since statically the
-  classes on the portal root look fine.
+- Gem metadata only, no code changes: the summary and description now explain why QSS exists (agents and flex/grid
+  layout, addressable structure, static auditing and its limits, the origin in Parapet), and the gem links to
+  `docs/DESIGN_HISTORY.md` as its documentation. The rubygems.org page reads these from the latest release.
 
-### Changed
-- `config.portal_root` now defaults to `#qss-portal` in `config/grammar.yml` (it was empty), so the shipped stylesheet,
-  the auditors and the engine agree on one default portal id. The compiled core CSS therefore scopes its utilities to
-  `#qss-portal` alongside the canvas and carries the portal rule above. Set it to `""` to build without a portal root.
+## [0.1.3] - 2026-10-17
 
-## [0.3.0] - 2026-10-18
+A last round of structural loose ends closed before the vocabulary itself became the next focus: a size container
+that cannot depend on its content, a 29-percent-dead-class census, an extreme-viewport blind spot, and whether a
+frame's own overflow should be allowed to paint over its neighbors.
 
 ### Added
-- `QSSEngine.auditPositioning()`: an opt-in runtime diagnostic (never run by the pulse) that lists every element whose
-  computed position is `fixed` or `sticky` and that QSS does not own, and logs one console warning per call (pass
-  `{ warn: false }` to silence it). QSS owns positioning, so the only legitimate holders are a Steel Frame actor
-  (`qss`, e.g. `qss-fixed`), anything inside the overlay portal root, content inside `foreign`, and an element in the
-  browser's native top layer (an open modal `<dialog>`, a shown popover). The static auditor cannot see the rest: a
-  Drywall `fixed`/`sticky` utility on an element QSS does not mark only becomes a position once a stylesheet resolves
-  it. `QSSEngine.setPortal(selector)` tells it where the portal root is (default `#qss-portal`). Covered by
-  `rake engine_check`.
+- `QSS::QssNativeAuditor::Dimensions.missing_axes` now recognizes two more ways an axis counts as declared,
+  revisiting a 2026-09-24 deferral now that flex and Tailwind's boundary are settled (DESIGN_HISTORY #12):
+  two opposite insets on the same axis (`pos-x[N]`+`pos-r[N]` for width, `pos-y[N]`+`pos-b[N]` for height -- both
+  edges pinned fixes the size exactly with no width/height class at all), and `flex-1`/`flex-auto` on the flex
+  parent's own main axis (resolved from the parent's `.vertical`/`.flex`/`.horizontal` classes; with no flex
+  parent, or on the cross axis, it still declares nothing -- never guessed). Takes an optional `parent_classes:`
+  keyword, passed by `audit_file` from the actual DOM parent.
+- `QSS::QssNativeAuditor` now checks that every class literally resolves to a rule in the compiled stylesheet, not
+  just that its shape matches a known pattern. The 2026-09-21 census found about 29 percent of real class tokens
+  resolved to no CSS at all while both auditors reported green; this is the guardrail that finding called for,
+  closing the gap. Checks core's own `qss_core.css` by default, or a consumer's own compiled output via the new
+  `auditor.stylesheet_path` config key (following the same pattern as `registry_path`) -- a consumer should point
+  this at what its markup actually renders against. A handful of classes are deliberately CSS-free behavioral
+  flags (`qss`, `foreign`, `qss-legibility-override`, `qss-ergonomic-override`, `qss-payload-override`,
+  `qss-dampen-scaling`, `qss-content-driven`) and are exempt. New finding: `unresolved_class` (red), deduplicated
+  per distinct class per file. Covered by a new spec file (21 examples) plus a configuration spec for the new key.
 
 ### Changed
-- The overlay portal root is now recognised by exact id only: the id configured as `config.portal_root`, or
-  `qss-portal` when none is configured. `config.portal_root` is validated when the settings load (it must be empty or
-  a simple `#id` selector; anything else raises `QSS::ConfigurationError`, and `qss-sync` aborts before generating
-  anything). Removed: the 0.2.0 `portal`-behind-the-project-`id_prefix` form (`app-portal`), the implicit
-  `qss-portal-*` match, and the older `QssAuditor`'s substring match on `portal`. A project that configures
-  `portal_root` to its real element id is unaffected; only one that relied on the implicit matching with
-  `portal_root` unset needs to configure it. New `QSS.validate_portal_root!` and `QSS.portal_id?`.
+- `contain-layout`/`qss-contain-layout` now clip paint by default (`contain: layout paint`, was `contain: layout`
+  alone), so a frame's overflow can no longer bleed into its neighbours -- `contain: layout` isolates layout math
+  but not paint. Anything that needs to visually escape a frame on purpose (tooltips, dropdowns, modals) already
+  has to go through the portal (a `z-index` outside it is its own red violation), so this doesn't reopen that
+  case. New opt-out for the rare frame that wants decorative overflow (a shadow, a hover scale) without the
+  portal: add `qss-paint-override` alongside `contain-layout`/`qss-contain-layout` to restore layout-only
+  containment. Covered by two new specs on the compiled stylesheet and, in the browser render check, a real
+  `elementFromPoint` hit-test proving an overflowing child is actually clipped (and, with the override, actually
+  isn't) -- not just that `getComputedStyle` reports the right `contain` value.
+
+### Fixed
+- `QSS::QssNativeAuditor`'s advice for an unregistered native qualifier (`{qualifier}-{nativeTag}`) no longer
+  suggests dropping the qualifier. Doing so turns the id into a bare native tag, which the auditor itself flags as
+  a separate red `missing_qualifier` violation -- the old advice traded one red finding for another instead of
+  resolving anything. The only advice now given is to register what the qualifier adds to the base object.
+- `--qnt` (the structural unit) is now dampened at the extremes: `clamp(0.39px, 0.1cqw, 3.2px)` instead of plain
+  `0.1cqw`/`0.1vw`. Floor is the qnt value at a 390px CSS viewport width (a real narrow-mobile width regardless of
+  the panel's physical/FHD+/QHD+ resolution, since `cqw`/`vw` only ever see CSS pixels); cap is the qnt value at
+  3200px, just past a maximized 1440p/27" monitor, so ordinary desktop widths (up to ~2560px) scale exactly as
+  before and only genuine ultra-wide/high-resolution canvases or genuine phone-narrow ones are dampened. Past the
+  cap, every structural dimension stays fixed regardless of how much wider the canvas gets -- extra width becomes
+  more usable space, not bigger borders/gaps/padding. Bounds are configurable (`config.dampen_scale` in
+  `grammar.yml`/a consumer's config). Covered by 4 new render-check assertions (25 in total), 2 proving the clamp
+  engages at real extreme widths, not just that the unclamped math is right.
+- Responsive percentage utilities (`qss-{breakpoint}:w-pct[N]`, `h-pct`, `pos-x-pct`, `pos-y-pct`, for every
+  horizontal and vertical breakpoint) now compile to valid CSS. The generator previously interpolated the raw
+  number (`#{$i * 0.1}%`), which Dart Sass renders with a space before the unit (`width: 0.1 %;`), an invalid
+  declaration browsers drop; it now uses `percentage()`, same as the non-responsive `w-pct[N]` rule already did.
+  These rules were also never scoped to `#qss-canvas` like every other utility in the file (missing the
+  `qss-dsl-boost` wrapper), so once valid they would have applied anywhere a host app reused the class name; they
+  are now scoped along with everyone else. Covered by two new specs on the compiled stylesheet, confirmed to fail
+  against the old output and pass against the fix.
 
 ## [0.2.0] - 2026-10-18
 
+The largest decision in the gem's history so far, and a correction rather than new direction: Kraig's original
+intent for QSS, from before any earlier pivot, was never "QSS replaces CSS" — it was QSS for positioning and
+custom element definitions, a real content framework (Tailwind) for standard form elements and common widgets.
+That division was written into Parapet's own project docs but never actually built; over several pivots, the
+hand-authored bracket vocabulary had quietly absorbed the content-styling job too, without anyone deciding that on
+purpose. A direct coverage audit of the compiled stylesheet made the drift concrete: zero `@keyframes`, zero
+gradients, zero native form-control restyling, zero `aspect-ratio`; the pseudo-class/pseudo-element coverage
+committed to a month earlier had never been built; the "a class must resolve to real CSS" guardrail the
+29-percent-dead-class census had called for had never been built either; roughly 32,000 responsive rules were
+still silently emitting invalid CSS.
+
+The reasoning that settled it: two different problems had been treated as one. The founding QSS problem — "move X
+left 10px" breaking under flex/grid — is ambiguous intent-to-mechanism mapping, and QSS's `--qnt` grid and bracket
+utilities actually solve that; it stays. Gradients, animations, native form-control restyling and full
+pseudo-class coverage are not ambiguous-mechanism problems at all — each has exactly one correct CSS mechanism —
+they're a *breadth* problem, and hand-authoring breadth inside QSS's own grammar is the one move that had broken
+every single time it was tried here (a generator gap affecting 786 elements, the 29-percent dead-class census, the
+still-open 32,000-rule bug, `contain-layout` shipping with no implementing rule at all in 0.1.1). Scaling the
+hand-authored surface up to match the full CSS spec would bet on the exact mechanism that kept failing, without
+first closing the verification gap every one of those postmortems had already called for. So: QSS's core stays
+scoped to structure, positioning and the native auditor's governance; a real, content-scanning Tailwind build is
+adopted as a dependency for everything else, where that coverage already exists, is battle-tested, and is
+something agents already have deep training exposure to — the same unfamiliarity-tax argument that killed the
+original custom DSL, now applying in Tailwind's favor instead. The one piece that had to be built, not assumed, to
+make this a real boundary rather than a convention someone could forget: a native-auditor rule that a QSS-marked
+actor may never carry a plain content-framework utility that sets a structural property.
+
 ### Added
 - Every Steel Frame actor (class `qss`) is now its own CSS size container (`container-type: inline-size`, a static
   default in `qss_core.scss`) with a `container-name` derived from its own id, set at runtime by `qss-engine.js`
@@ -178,8 +219,8 @@ Never published as 0.4.3 or 0.5.0; both numbers were used for this same work bef
   `qss-flex-row`/`qss-flex-col`; `spaced` is `qss-justify-between`; `clickable` is `qss-cursor-pointer`; `smooth` is
   `qss-transition-all`. Identity/relational markers that aren't adjectives (`qss`, `group`, `foreign`) are
   unchanged. This restores `QSS-MANIFESTO.md`'s own original grammar (`.qss-pos-x[500]`, `.qss-Button[...]`), which
-  had drifted during the pivots in `docs/DESIGN_HISTORY.md` into a mix of bare and `qss-` spellings for the same
-  rule -- a drift one of core's own comments flagged as "prefix decision still open."
+  had drifted during earlier pivots into a mix of bare and `qss-` spellings for the same rule -- a drift one of
+  core's own comments had flagged as "prefix decision still open."
   A bare, unprefixed vocabulary this close to a content framework's own utility names (`flex`, `absolute`,
   `w-full`, ...) is the exact collision the boundary exists to prevent: a framework compiling its own unprefixed
   utilities couldn't be told apart, in source text, from QSS's own. `qss-engine.js`'s runtime parsing (already
@@ -230,92 +271,221 @@ Never published as 0.4.3 or 0.5.0; both numbers were used for this same work bef
   whatever text sat between two rules, comment included, as selector text for the rule that followed it. Comments
   are now stripped before extraction in both methods.
 
-## [0.1.3] - 2026-10-17
+## [0.3.0] - 2026-10-18
+
+Two follow-ups built the same day 0.2.0 shipped, once a real consumer had started migrating to it. First: 0.2.0
+recognized the overlay portal root three different ways (a configured id, the literal `qss-portal`, or `portal`
+behind the project's own id prefix), and every one of those was a convention an auditor had to guess at — one real
+view had an unrelated `customer-portal` nav flagged by the substring match. Second: the static auditor can see a
+Drywall class that sets `position` only when it resolves against the configured Drywall stylesheet on a frame; a
+plain `fixed`/`sticky` utility sitting on any other element is invisible to a class-shape check, because a class
+name only becomes a position once a stylesheet resolves it — something only the browser actually knows.
 
 ### Added
-- `QSS::QssNativeAuditor::Dimensions.missing_axes` now recognizes two more ways an axis counts as declared,
-  revisiting a 2026-09-24 deferral now that flex and Tailwind's boundary are settled (DESIGN_HISTORY #12):
-  two opposite insets on the same axis (`pos-x[N]`+`pos-r[N]` for width, `pos-y[N]`+`pos-b[N]` for height -- both
-  edges pinned fixes the size exactly with no width/height class at all), and `flex-1`/`flex-auto` on the flex
-  parent's own main axis (resolved from the parent's `.vertical`/`.flex`/`.horizontal` classes; with no flex
-  parent, or on the cross axis, it still declares nothing -- never guessed). Takes an optional `parent_classes:`
-  keyword, passed by `audit_file` from the actual DOM parent.
-- `QSS::QssNativeAuditor` now checks that every class literally resolves to a rule in the compiled stylesheet, not
-  just that its shape matches a known pattern. The 2026-09-21 census found about 29 percent of real class tokens
-  resolved to no CSS at all while both auditors reported green; this is the guardrail that finding called for,
-  closing the gap. Checks core's own `qss_core.css` by default, or a consumer's own compiled output via the new
-  `auditor.stylesheet_path` config key (following the same pattern as `registry_path`) -- a consumer should point
-  this at what its markup actually renders against. A handful of classes are deliberately CSS-free behavioral
-  flags (`qss`, `foreign`, `qss-legibility-override`, `qss-ergonomic-override`, `qss-payload-override`,
-  `qss-dampen-scaling`, `qss-content-driven`) and are exempt. New finding: `unresolved_class` (red), deduplicated
-  per distinct class per file. Covered by a new spec file (21 examples) plus a configuration spec for the new key.
+- `QSSEngine.auditPositioning()`: an opt-in runtime diagnostic (never run by the pulse) that lists every element whose
+  computed position is `fixed` or `sticky` and that QSS does not own, and logs one console warning per call (pass
+  `{ warn: false }` to silence it). QSS owns positioning, so the only legitimate holders are a Steel Frame actor
+  (`qss`, e.g. `qss-fixed`), anything inside the overlay portal root, content inside `foreign`, and an element in the
+  browser's native top layer (an open modal `<dialog>`, a shown popover). The static auditor cannot see the rest: a
+  Drywall `fixed`/`sticky` utility on an element QSS does not mark only becomes a position once a stylesheet resolves
+  it. `QSSEngine.setPortal(selector)` tells it where the portal root is (default `#qss-portal`). Covered by
+  `rake engine_check`.
 
 ### Changed
-- `contain-layout`/`qss-contain-layout` now clip paint by default (`contain: layout paint`, was `contain: layout`
-  alone), so a frame's overflow can no longer bleed into its neighbours -- `contain: layout` isolates layout math
-  but not paint. Anything that needs to visually escape a frame on purpose (tooltips, dropdowns, modals) already
-  has to go through the portal (a `z-index` outside it is its own red violation), so this doesn't reopen that
-  case. New opt-out for the rare frame that wants decorative overflow (a shadow, a hover scale) without the
-  portal: add `qss-paint-override` alongside `contain-layout`/`qss-contain-layout` to restore layout-only
-  containment. Covered by two new specs on the compiled stylesheet and, in the browser render check, a real
-  `elementFromPoint` hit-test proving an overflowing child is actually clipped (and, with the override, actually
-  isn't) -- not just that `getComputedStyle` reports the right `contain` value.
+- The overlay portal root is now recognised by exact id only: the id configured as `config.portal_root`, or
+  `qss-portal` when none is configured. `config.portal_root` is validated when the settings load (it must be empty or
+  a simple `#id` selector; anything else raises `QSS::ConfigurationError`, and `qss-sync` aborts before generating
+  anything). Removed: the 0.2.0 `portal`-behind-the-project-`id_prefix` form (`app-portal`), the implicit
+  `qss-portal-*` match, and the older `QssAuditor`'s substring match on `portal`. A project that configures
+  `portal_root` to its real element id is unaffected; only one that relied on the implicit matching with
+  `portal_root` unset needs to configure it. New `QSS.validate_portal_root!` and `QSS.portal_id?`.
+
+## [0.3.1] - 2026-10-19
+
+The same consumer's migration immediately found a second, worse gap: a portal root configured per 0.3.0's exact-id
+rule had no actual geometry in the compiled stylesheet at all. Every generated utility is scoped
+`:is(<canvas>, <portal root>) .class`, which can only ever match a *descendant* of a root, never the root itself —
+so `qss-absolute qss-inset-0`, written directly on the portal root, matched nothing there. The canvas had always
+escaped this through its own separate, unscoped "Root Anchor" rule; the portal had no equivalent. Neither auditor
+could see it, because statically the classes on the portal root look completely fine — only measuring a real
+browser revealed the root sitting in normal flow after the canvas with zero width and height, and a
+`qss-w[640] qss-pos-r[16]` overlay inside it resolving its position and size against that empty box.
 
 ### Fixed
-- `QSS::QssNativeAuditor`'s advice for an unregistered native qualifier (`{qualifier}-{nativeTag}`) no longer
-  suggests dropping the qualifier. Doing so turns the id into a bare native tag, which the auditor itself flags as
-  a separate red `missing_qualifier` violation -- the old advice traded one red finding for another instead of
-  resolving anything. The only advice now given is to register what the qualifier adds to the base object.
-- `--qnt` (the structural unit) is now dampened at the extremes: `clamp(0.39px, 0.1cqw, 3.2px)` instead of plain
-  `0.1cqw`/`0.1vw`. Floor is the qnt value at a 390px CSS viewport width (a real narrow-mobile width regardless of
-  the panel's physical/FHD+/QHD+ resolution, since `cqw`/`vw` only ever see CSS pixels); cap is the qnt value at
-  3200px, just past a maximized 1440p/27" monitor, so ordinary desktop widths (up to ~2560px) scale exactly as
-  before and only genuine ultra-wide/high-resolution canvases or genuine phone-narrow ones are dampened. Past the
-  cap, every structural dimension stays fixed regardless of how much wider the canvas gets -- extra width becomes
-  more usable space, not bigger borders/gaps/padding. Bounds are configurable (`config.dampen_scale` in
-  `grammar.yml`/a consumer's config). Covered by 4 new render-check assertions (25 in total), 2 proving the clamp
-  engages at real extreme widths, not just that the unclamped math is right.
-- Responsive percentage utilities (`qss-{breakpoint}:w-pct[N]`, `h-pct`, `pos-x-pct`, `pos-y-pct`, for every
-  horizontal and vertical breakpoint) now compile to valid CSS. The generator previously interpolated the raw
-  number (`#{$i * 0.1}%`), which Dart Sass renders with a space before the unit (`width: 0.1 %;`), an invalid
-  declaration browsers drop; it now uses `percentage()`, same as the non-responsive `w-pct[N]` rule already did.
-  These rules were also never scoped to `#qss-canvas` like every other utility in the file (missing the
-  `qss-dsl-boost` wrapper), so once valid they would have applied anywhere a host app reused the class name; they
-  are now scoped along with everyone else. Covered by two new specs on the compiled stylesheet, confirmed to fail
-  against the old output and pass against the fix.
+- The overlay portal root had no base geometry in the compiled stylesheet, so anything portaled into it rendered at
+  the wrong position and size. Every generated utility is scoped `:is(<canvas>, <portal root>) .class`, which only
+  ever matches a descendant of a root, never the root itself, so `qss-absolute qss-inset-0` written on the portal
+  root itself matched nothing; the canvas escapes this through its own unscoped "Root Anchor" rule, and the portal
+  had no equivalent. Measured in a real browser: the root landed in normal flow after the canvas (zero width and
+  height, `top` equal to the viewport height), and a `qss-w[640] qss-pos-r[16]` overlay inside it resolved against
+  that empty box (negative `left`, wrong size). The portal root now gets its own rule by id: `position: fixed;
+  inset: 0` (a viewport-sized layer; placed after the canvas it paints above it with no `z-index`),
+  `container-type: inline-size` with `--qnt` resolved on its children exactly as the canvas does (so qnt-sized
+  overlays measure against the viewport's width, equal to the canvas unit whenever the canvas spans the viewport),
+  `pointer-events: none` on the root and `auto` on its direct children (a viewport-sized transparent layer must not
+  swallow clicks meant for the page), and the same actor reset the canvas gives its actors. That reset moved into a
+  shared mixin (`qss-actor-reset`), so an actor portaled into an overlay is a full Steel Frame actor too.
+  Classes written on the portal root itself still do nothing; its geometry is built in. The engine's runtime rules
+  were already unscoped and needed no change.
+- New real-browser coverage in `rake render_check` (`qss-core-render-check`, now 35 checks): a portal root carrying
+  the documented `qss-absolute qss-inset-0` is asserted to compute a fixed, exactly viewport-sized box, and a
+  qnt-sized overlay inside it to have its real width, height and edge offsets. Run against the 0.3.0 stylesheet, 7 of
+  those checks fail, reproducing the report. The static auditor cannot catch this class of bug, since statically the
+  classes on the portal root look fine.
 
-## [0.1.2] - 2026-10-05
+### Changed
+- `config.portal_root` now defaults to `#qss-portal` in `config/grammar.yml` (it was empty), so the shipped stylesheet,
+  the auditors and the engine agree on one default portal id. The compiled core CSS therefore scopes its utilities to
+  `#qss-portal` alongside the canvas and carries the portal rule above. Set it to `""` to build without a portal root.
+
+## [0.4.0] - 2026-10-19
+
+### Added
+- Three-tier stylesheet audit. The auditor now resolves classes against up to three tiers, and tiers 1 and 2 are
+  integrity-checked and otherwise silent (they surface only as an integrity failure):
+  1. **Core**: the gem's own `qss_core.css`, always known, never configured. `rake compile` marks it DO NOT EDIT and
+     writes `config/integrity.json` (its SHA-256, line endings normalized, plus the gem version); the auditor
+     verifies it before use. A mismatch, a missing file or a manifest from another version raises
+     `QSS::CoreIntegrityError`.
+  2. **Tool**: `auditor.tool_stylesheets`, a dev tool's own compiled chrome (for example Parapet's
+     `qss_application.css`). The tool seals each file when it builds it with the new `qss-seal` executable (or
+     `QSS::Integrity.seal`), which writes `<file>.qss-seal`; `--header` also marks the file DO NOT EDIT. An unsealed or
+     changed file raises `QSS::ToolIntegrityError`.
+  3. **Host**: `auditor.host_stylesheets`, the end consumer's own compiled output, as paths or globs relative to the
+     project root, plus whatever `QSS.configure(host_stylesheets: -> { ... })` returns (evaluated each time the
+     settings are read, in the host's own process). With nothing configured, a Rails host gets
+     `app/assets/builds/*.css`.
+- `QSS::IntegrityError`, the base of both integrity errors, so a host's CI can rescue and report one class.
 
 ### Changed
-- Gem metadata only, no code changes: the summary and description now explain why QSS exists (agents and flex/grid
-  layout, addressable structure, static auditing and its limits, the origin in Parapet), and the gem links to
-  `docs/DESIGN_HISTORY.md` as its documentation. The rubygems.org page reads these from the latest release.
+- Core's classes are now always known to `unresolved_class`. Before, setting `stylesheet_path` replaced core's
+  stylesheet, so a consumer that listed only its own file lost every core class. `stylesheet_path` and
+  `drywall_stylesheet_path` keep working (`stylesheet_path` counts as a host stylesheet). The Tailwind/QSS boundary
+  check is unchanged and still reads `drywall_stylesheet_path` only.
 
-## [0.1.1] - 2026-10-05
+## [0.4.1] - 2026-10-20
 
-### Fixed
-- `contain-layout` and `qss-contain-layout` now have a rule (`contain: layout`) in `qss_core.css`. The README
-  documents the class for structural frames and the native auditor mandates it, but the stylesheet never defined it,
-  so a frame that satisfied the auditor received no containment. Anyone already using the class will now get layout
-  containment on those frames: check that absolutely and fixed-positioned descendants still position as expected.
-  Covered by a spec on the compiled stylesheet and by three checks in the browser render check (21 in total).
+### Added
+- `QSS::Error`, the base of every failure QSS raises on purpose: `ConfigurationError`, `IntegrityError` (and so
+  `CoreIntegrityError`, `ToolIntegrityError`). One `rescue QSS::Error` covers all of them; each means the audit cannot
+  run as configured, not that a view has a finding. `ConfigurationError` is not an `IntegrityError`.
 
-## [0.1.0] - 2026-09-25
+### Changed
+- A configured stylesheet that is not on disk (`drywall_stylesheet_path`, `stylesheet_path`, or a literal `host_stylesheets` entry)
+  now raises `QSS::ConfigurationError` naming the file. Before, it loaded as an empty stylesheet, so a Tailwind build that had
+  not run yet showed up as a large, misleading `unresolved_class` count. A glob that matches nothing is still just empty.
 
-First release, extracted from the Parapet project.
+## [0.4.2] - 2026-10-20
 
 ### Added
-- Core stylesheet (`qss/qss_core.scss`, compiled `qss/qss_core.css`): utilities on a 1000-unit canvas grid; the unit
-  (`--qnt`, canvas width / 1000) computed by CSS alone (`0.1cqw` of the canvas; the viewport width outside one).
-- Base reset for QSS actors at the canvas id's weight only, so every core utility applies without the JS engine.
-- Neutral `!default` SCSS settings (`qss/_qss_defaults.scss`); a project sets its own before importing core.
-- Optional runtime engine (`qss/qss-engine.js`): rules for uncovered bracket classes, measured element edges.
-- `QSS::QssNativeAuditor`: id grammar (`{qualifier}-{baseObject}`, `QSSObject` custom types) with a per-project
-  registry, `qss-function` / `qss-relation` attributes, explicit dimensions for every actor, unit rules (no raw CSS
-  lengths on QSS structure; rem or % only in foreign content), `!important`, z-index and inline-style checks.
-- `QSS::QssAuditor`: the older class-whitelist auditor.
-- `QSS.configure(root:, config:)`: a project's settings read at runtime; paths resolve against its root.
-- `QSS::Blueprints` (`QSS.grid`, `QSS.object`): layout arithmetic and object blueprints.
-- `QSS::Engine`: Rails engine for the asset pipeline, loaded only when Rails is present.
-- `qss-sync`: writes a project's SCSS settings (`--core` regenerates the gem's own generated sections).
-- `qss-core-render-check`: renders the compiled CSS alone in headless Chrome and checks core utilities.
+- A dimension can be declared by an `#id { ... }` rule in a configured tool or host stylesheet, not only by a size
+  class. The implicit-dimension check (red for a `qss` actor, orange for other structural elements) now also reads the
+  actor's own id from `tool_stylesheets`, `host_stylesheets` and `stylesheet_path`: `width`/`inline-size` declares the
+  width, `height`/`block-size` the height, `left`+`right` (or `inset`, `inset-inline`) pin the width, `top`+`bottom`
+  (or `inset`, `inset-block`) pin the height. This is how an actor anchors to another actor's resizable dimension with
+  plain custom properties (`right: var(--bar-w)`), which the bracket classes cannot express. Only unconditional rules
+  count: a rule inside `@media`/`@supports`, a nested rule, or a compound selector (`div#x`, `#x:hover`, `#x.on`)
+  declares the size only sometimes and is ignored, as is a value that sizes nothing (`auto`, `fit-content`, ...).
+
+## [0.5.0] - 2026-10-22
+
+A consumer (Parapet) set its header title and its sub-title to two different `qss-text-size[N]` values and measured
+both at exactly 9px in a real browser — not a coincidence. `text_scale.floor_px` was a flat 9, and the per-size
+floor is `N * 0.875`, so every N from 1 to 10 computed below 9 and the flat floor won across that entire range:
+`[5]`, `[7]` and `[10]` were indistinguishable from each other.
+
+### Changed
+- The `qss-text-size[N]` floor drops from a flat 9px to 5px (`text_scale.floor_px`). With 9px, every N from 1 to 10
+  computed `N * 0.875` below the floor, so `[5]`, `[7]` and `[10]` all rendered at exactly 9px. Now `[5]` floors at 5px
+  and `[7]` and up scale with the canvas (`N * 0.875` is the floor from N = 6), so small sizes are distinct. The cap and
+  `floor_multiplier` are unchanged. A small size on a narrow canvas can now render smaller than before; the auditor's
+  legibility check (below 11, `qss-legibility-override` to waive) is unchanged. The 5 is a judgment call, not a
+  derived number: a floor and cap are the right guard for text people actually read, but as the next entry found,
+  wrong for text that was never meant to be legibility-constrained in the first place.
+
+## [0.6.0] - 2026-10-22
+
+The same investigation that produced 0.5.0 raised a second question the floor-only fix couldn't answer: a legibility
+clamp is right for body copy, and wrong for a wordmark or display title that should resize like a photo, with no
+floor holding it artificially large on a narrow canvas and no cap holding it artificially small on a wide one.
+Rather than removing the clamp from `qss-text-size[N]` (which every reader of body copy depends on), a second,
+separate class was added for the different use case.
+
+### Added
+- `qss-text-size-linear[N]` (N 1 to 96): text that scales in pure proportion to the viewport, `N * 100vw / 1440`, with no
+  floor, no cap and no dampening, for cosmetic text (wordmarks, titles) that should resize like a picture. It uses the
+  same unit as `qss-icon-size[N]`, so it tracks the viewport width, not the canvas. Body copy should keep using
+  `qss-text-size[N]`. The Ruby auditor's below-11 legibility check only reads `qss-text-size[N]`, so it does not apply here.
+  The name was a deliberate choice over `qss-display-size` (names the use, not the behavior) and `qss-text-fluid`
+  (collides with the CSS community's existing "fluid type," which usually still clamps). Known limitation at this
+  point: the unit this class rides on (`--u`, `100vw / 1440`) tracks the real viewport rather than the canvas, which
+  is right for a full-width header and wrong for the same text inside a narrower sized container — `--qnt` already
+  solves exactly this shape of problem for everything else, defaulting to the viewport and re-resolving via
+  container-query units inside a sized container as one variable rather than two parallel systems. The plan at this
+  point is for `--u` to learn that same trick in a future release, not to add a second parallel canvas unit.
+
+## [0.7.0] - 2026-11-02
+
+Two real, independent consumers (Parapet and a second PWA app under development) hit the same root cause from two
+different angles within days of each other: `--qnt` is one scalar, derived from the canvas's *width* alone, used
+for both axes — deliberate, since it's what keeps two elements positioned on different axes holding their
+relative position to each other as the canvas reshapes (the gem's founding guarantee). But a design that uses the
+`y` axis the same way it uses `x` is implicitly assuming a **square** canvas, and nothing enforces that. The
+second app's landing page measured elements rendering 1,408px and 2,048px below the bottom edge of a real
+1,298px-tall browser window — not clipped, rendering entirely outside the visible, `overflow: hidden` canvas —
+and, separately, a logo clipping its own container on every ordinary 16:9/16:10 window because its height came
+from one canvas axis and its width (derived from that
+height via a fixed image aspect ratio) effectively depended on the other.
+
+Several plausible-looking fixes were tried and rejected before landing on the real one:
+
+- **Splitting `--qnt` into `--qnt-x`/`--qnt-y`.** Makes y-axis positioning finally proportional to the canvas's
+  actual height — but breaks the one guarantee the single scalar exists for, reintroducing "which property
+  actually moved it" ambiguity inside QSS's own unit system, the exact failure QSS exists to prevent. Proposed and
+  rejected twice, independently, by two different people, before either rejection's reasoning reached the other.
+- **A configured canvas aspect ratio with a letterboxed/pillarboxed canvas.** Actually built, as an app-level
+  stopgap, then reverted the same day after producing visible pillarboxing on a real ultra-wide window. QSS is
+  built primarily for full-bleed, PWA-style apps that must fill every real window at every resolution with zero
+  per-project configuration; a visible gutter, on principle, is not an acceptable trade to get there, regardless of
+  whether the lock is a fixed square or a configurable ratio.
+- **The mirror image: scale to cover the viewport and crop whatever overflows**, instead of letterboxing. Solves
+  the full-bleed requirement, but only for a design with a genuine decorative margin near its edges to sacrifice —
+  it's the wrong default for a design where the edges carry load-bearing UI (a nav bar, a file-tree explorer, a
+  toolbar) with nothing there to crop.
+- **A static auditor rule bounding position-plus-size against a configured worst-case ratio.** Zero CSS cost, but
+  advisory only, with a hard silent cliff at whatever ratio is configured — a window narrower than that stays
+  completely unchecked, which is exactly the original failure.
+
+What shipped instead: three separate tools, matched to three different kinds of content, rather than one
+canvas-wide policy. Content whose relative position *is* the point (a toolbar's own internal spacing, a tightly
+grouped cluster) keeps today's rigid, canvas-width-relative `--qnt` exactly as it works today — no change, and no
+canvas content should assume otherwise. Content that's allowed to flex gracefully within a bounded range (headroom
+above a cluster, a gap that's more margin than structural relationship) gets a new clamped percentage-of-parent
+mechanism. Content that's genuinely edge-docked and load-bearing (global nav, a sidebar, a toolbar that must never
+crop) gets documented as belonging in the overlay portal rather than on the canvas at all, sized by `--qnt` but
+positioned by real CSS edges.
+
+### Added
+- `qss-elastic-y-min[N]` / `qss-elastic-y-pct[N]` / `qss-elastic-y-max[N]` + the bare `qss-elastic-y` trigger class:
+  clamped percentage-of-parent spacing for gaps that should flex with their immediate containing block's actual
+  rendered size, bounded between a floor and a cap (`top: clamp(min, pct, max)`), rather than holding rigidly
+  proportional to the canvas (`qss-pos-y[N]`) or growing unbounded with the parent (`qss-pos-y-pct[N]` alone). Four
+  classes rather than one three-parameter bracket, because a bracket with three independent values can't be
+  precompiled the way a single-value one can (it would need every min×pct×max combination generated in advance);
+  composing single-value classes keeps this working with zero JavaScript, the same idiom the rest of the grammar
+  already uses. Stack all four classes on one element. See DESIGN_HISTORY.md #17.2.
+
+- The overlay portal is now documented (`docs/HOWTO.md`) as the home for persistent, viewport-anchored chrome
+  (global nav, a file-tree explorer, a toolbar pinned to an edge), not only transient overlays: placed by real CSS
+  edges, sized by `--qnt` like any other actor, with no second root needed alongside transient overlays, because a
+  native top-layer modal always paints above everything regardless of which root anything lives in, and chrome is
+  never meant to float above a modal that's taking over the user's attention. The one contract this depends on:
+  overlay-mounting code must always append to the portal, never insert at a fixed index, so later-added overlays
+  keep painting over earlier, static chrome. See DESIGN_HISTORY.md #17.3.
+
+### Fixed
+- The JS engine's `applyContainerNames` now also names actors inside `#qss-portal`, not just `#qss-canvas`. Named
+  container-query variants (Tailwind's `@sm/<frame-name>:`) silently never worked on any portal content before this
+  — existing overlays included, not just new chrome. Not a deliberate canvas-only design; found while documenting
+  the portal as the home for persistent, viewport-anchored chrome (nav bars, toolbars), which made the gap
+  impossible to miss. See DESIGN_HISTORY.md #17.3.