qss 0.6.0 → 0.7.0

data/docs/DESIGN_HISTORY.md

@@ -0,0 +1,882 @@
+# The Design History of QSS
+
+How QSS came to look the way it does: the problems that started it, the ideas that were tried and dropped, and the
+reasoning behind what stayed. It is a curated account, not a commit log. QSS was created by Kraig Fairhurst, who made
+the design decisions recorded here; much of the work was done with AI coding agents, which is also where most of
+the lessons came from.
+
+## 1. The problem: AI agents and CSS
+
+If you have asked an AI coding agent to change a layout, you have probably seen some of this:
+
+- You ask it to "move the sidebar 10px to the left." It edits a margin, then an `order`, then a `flex-basis`, and
+  something else on the page moves.
+- It reports the change as done and "verified", while the page is visibly broken in a browser.
+- Class names drift: two spellings of the same utility, classes that resolve to no CSS at all, `!important` and
+  `z-index` added until something shows up.
+- The only way to know what a layout does is to render it.
+
+QSS exists to make a layout something an agent (and a person) can read and change from its source, with one
+unambiguous place to make each edit, and to make "done" mean something a developer does not have to re-check by
+hand. The goal is confidence in the outcome, not a particular look.
+
+## 2. The founding example
+
+The case that shaped everything: an agent told "move X left by 10px" does it trivially when X is positioned
+explicitly, and breaks it under flex or grid layout. It took several rounds to explain why correctly.
+
+- It is **not** that agents are bad at arithmetic. "Read `--sidebar-x`, subtract 10, write it back" is reliable:
+  one explicit value, one target.
+- Complex derived math (multi-step quantization, midpoints between named elements) is a genuine weakness.
+- The flex/grid failure is a third thing: **ambiguous intent-to-mechanism mapping.** "Left" is not one property in
+  flex or grid; it emerges from margin, order, basis, gap and the siblings. The agent has to guess which to touch,
+  and the guess is where it goes wrong.
+
+The design rule that follows: **keep every structural value explicit, single-purpose and directly addressable**, so
+an edit always has exactly one target. This is what QSS calls **addressability**; being able to check what actually
+rendered is **observability**. Together they are what "agent-aware" means here.
+
+## 3. Origins: a bracket DSL and a runtime engine
+
+QSS began inside Parapet, a Rails development tool whose own interface was the first thing built with it. The early
+version had:
+
+- a bracket grammar (`pos-x[500]`, `w[240]`) on a 1000-unit canvas grid, where one unit (a **qnt**) is one
+  thousandth of the canvas width;
+- relational anchoring (`pos-y[^header]`: place this below the header, by measuring the header at runtime);
+- a JavaScript engine that transpiled classes at runtime and measured elements;
+- an auditor that checked every class against a whitelist.
+
+Its structural ideas held up: a flat hierarchy of frames directly on one canvas (deep nesting is what confuses
+agents, so remove it rather than tolerate it), frames that isolate their layout, overlays in a portal at the
+document root instead of `z-index` wars, and a ban on `!important` and ad-hoc inline styles.
+
+## 4. What broke, and what it taught
+
+- **The custom parser was the bug farm.** Every serious defect of that period lived in the hand-maintained
+  regex/whitelist layer, not in CSS: a regex that one comma could defeat, a whitelist that drifted between client and
+  server, a validation shortcut that let anything starting with a capital letter through.
+- **An invented syntax has a cost for agents.** A model has seen enormous amounts of real CSS and Tailwind, and
+  none of a project's private bracket language. The DSL was paying an unfamiliarity tax while trying to buy
+  certainty.
+- **Self-graded verification did not hold.** Repeatedly, a change was reported as fixed, with the auditor green and
+  the unit tests passing, while the page did not work: once the JavaScript engine did not load at all. Each time it
+  was a real browser that caught it. Lesson: "verified" has to come from running the real thing, checked by
+  something other than the tool that made the change.
+- **Framework CSS leaked.** A beta export of QSS broke the styling of a production application that used it,
+  because its rules could reach outside their own area.
+
+Two of these are different problems and were kept apart on purpose: a better grammar narrows one class of mistake;
+only real, independent verification makes an agent's "done" trustworthy.
+
+## 5. 2026-09-16: retire the DSL as the foundation
+
+The decision: structure moves to **native CSS**: plain custom properties with a naming convention (not a new
+syntax), fluid scaling instead of breakpoints, and a short **native-CSS auditor** (frames isolate their layout,
+declare their dimensions, stay out of `z-index`, keep structure off text tags) instead of a whitelist grammar. Reusable
+interface patterns become Rails ViewComponents rather than a bespoke object system. A visual canvas editor stays
+wanted but explicitly last: it is an editor for the other layers, so it cannot be designed before they are stable.
+
+## 6. 2026-09-17: the first real pilot
+
+Rebuilding one real feature (a file editor) on the new direction, and getting its browser tests to pass, found four
+separate problems rather than one: scripts that the asset pipeline had silently never loaded; a base rule that won on
+CSS specificity and made `hidden` panels visible (patched locally that day; its root cause was only fixed in core a
+week later, section 11); a stylesheet generator that simply had no rule for dozens of commonly used classes (786
+elements across 50 files depended on them); and a second, hyphenated class spelling that matched nothing. Browser
+tests went from 0 of 12 scenarios passing to 8.
+
+## 7. 2026-09-21: brackets kept for content, with guardrails
+
+A census of every class token in the interface (7,887 occurrences) found about 29 percent resolving to no CSS at all,
+while both auditors reported green. The bracket form was the one convention that actually worked (99 percent
+resolved). So the brackets were **kept for content** (spacing, sizes, radius, borders, type and icon size, colour
+alpha), on three conditions: one source of truth for the grammar, an auditor rule that every class must resolve, and
+real-browser checks at several widths before anything is called done. Structure stays native CSS.
+
+Also decided: a named palette with per-property alpha (`bg-alpha[50]`), because one shared alpha class was ambiguous
+two times in three; and **scoping instead of prefixes**: every generated rule applies only inside the canvas (and the
+overlay portal), so a host application's CSS and QSS's cannot collide, whatever anyone names their classes.
+
+## 8. 2026-09-22: four layers, full CSS coverage, essential and accidental
+
+- **Four layers**: (1) the core framework; (2) a library of interaction patterns; (3) the canvas, the authoring
+  tool for a project's own objects; (4) a project's own instances. Work the core first; data that belongs to one
+  project must never sit in the core.
+- **Full coverage, not usage-gated.** Whether to support a pseudo-class is decided by the CSS specification, not by
+  what one project happens to use. Position selectors such as `:nth-child()` are included: they are not ambiguous
+  (one precise meaning), and an agent edits the template that defines every row, never the rendered list.
+- **Essential and accidental properties.** Generating every colour for every state for every group had grown the
+  stylesheet past 485,000 lines and broken the test suite. Kraig traced it to Aristotle's distinction: what a thing
+  *is* (its type) is essential; what it happens to have (colour, spacing, which value a state takes) is accidental.
+  Core defines the essential and never pre-multiplies the accidental: `.group-hover:bg-accent` reads
+  `--accent-bg`, set by a separate colour class, so the rule count becomes additive instead of multiplicative.
+- **Identity in the id.** An id is `{qualifier}-{baseObject}`: a real HTML tag, or the anchor `QSSObject` for a
+  project's own type (`activity-card-QSSObject`). Hyphens, because they mean nothing in CSS selectors. Relation and
+  function are separate attributes (`qss-relation="form"`, `qss-function="delete"`), not packed into the id, because
+  a positional parse of one long id has no reliable boundaries.
+- **Drift prevention.** Open vocabularies (qualifiers, functions, custom types) go in a per-project registry. A new
+  name that is only a near-miss of a registered one ("frm" for "form", leetspeak, a vowel dropped) is flagged for a
+  person to confirm, never silently registered as a second name for the same thing.
+
+## 9. 2026-09-23: separating the core, and a real auditor
+
+Everything project-specific was moved out of the core into the consuming project (archived where unused). The native
+auditor gained the identity rules: a closed alphabet for names (lowercase words and hyphens), similarity checks,
+registry-driven types, and a severity scheme: RED means a rule is violated (fix the markup, or rethink the rule);
+ORANGE means a judgment call. It was then run against code QSS had never seen: hundreds of templates from widely used
+Rails gems (no crashes), and the class vocabularies of several production Tailwind sites, which is how the unit
+rules were calibrated.
+
+**The units and viewport rule.** QSS depends on the viewport through exactly one channel, the canvas grid. Raw
+viewport units (`vw`, `svh`, ...) on QSS structure would add a second, unaddressable coordinate system, and some
+change at runtime; so structure carries no raw CSS lengths at all, and foreign content may use `rem` or `%` only.
+
+## 10. 2026-09-24: the fixes that made the gem possible
+
+- **Every actor declares its size.** A panel's scroll area silently grew to the height of its content (3,013px
+  inside a 476px frame), because QSS's reset stops actors shrinking and nothing required it to declare a height. The
+  rule is now enforced by the auditor.
+- **Compiled CSS works without JavaScript.** The base reset turned out to outrank every compiled utility on CSS
+  specificity; utilities only worked because the runtime engine re-emitted them with a doubled id. Rendered with the
+  CSS alone, `hidden`, `flex` and `w-full` all failed. The reset now uses `:where()`, and a render check proves the
+  compiled CSS alone in a headless browser.
+- **The unit in pure CSS.** The qnt was set by JavaScript after measuring. It is now `0.1cqw` of the canvas (a CSS
+  container query unit), registered as a length so it resolves once at the canvas and inherits unchanged. A canvas
+  shown at half width, say a preview inside an editor, keeps its contents in proportion. The qnt stays the one unit
+  authors use; `cqw` appears only in its definition.
+- **Vocabulary.** An element's id is its **noun**, its classes are **adjectives**, and `qss-function` /
+  `qss-relation` are **attributes**. Essential/accidental remains the principle underneath; the two are not
+  synonyms (some essential facts live in attributes, and a declared size is an essential fact written as a class).
+- **The gem.** Every setting that belonged to the first consuming project (id prefix, palette, registry, portal)
+  moved out of the core into that project's own configuration, read at runtime. The core loads in plain Ruby, ships
+  neutral defaults, and became this gem, with a small Rails engine for the asset pipeline.
+
+## 11. Open questions (all resolved 2026-10-17 -- see CHANGELOG.md's Unreleased section for each fix)
+
+The last of this section's items was whether frames should clip their content: `contain: layout` isolates layout
+but not paint, so a frame's overflow could still cover its neighbours. Resolved by making `contain-layout`/
+`qss-contain-layout` clip paint too by default, with `qss-paint-override` as the opt-out for a frame that wants
+decorative overflow without going through the portal (anything that needs to visually escape a frame on
+purpose -- tooltips, dropdowns, modals -- already has to use the portal regardless, so this did not reopen that
+case). The section number is kept stable for the cross-references below and in CHANGELOG.md.
+
+## 12. 2026-10-16: the Tailwind/QSS boundary, restored
+
+Kraig's original intent for QSS, from before any of the pivots above, was never "QSS replaces CSS." It was: QSS
+handles positioning and custom element definitions; Tailwind handles standard form elements and other common HTML
+widgets. That division was written into the first consumer's own `CLAUDE.md` ("Tailwind utility classes use a `qss-` prefix")
+but never actually built — that consumer had no Tailwind dependency anywhere (no `package.json`, no `tailwindcss` entry),
+and its compile task is a plain, non-content-scanning `Sass.compile` over hand-authored SCSS. Over the course of the
+pivots in sections 5-10, the hand-authored bracket vocabulary quietly absorbed the content-styling job too (section
+7's "brackets kept for content" decision), without anyone deciding that on purpose. This section is the correction.
+
+### 12.1 What a direct coverage audit found
+
+Checking the compiled surface directly, not the stated intent, on 2026-10-16:
+
+- Zero `@keyframes`/`animation`, zero `gradient`, zero `appearance`, zero `input[type=...]`, zero `::-webkit-*`
+  (range thumbs, scrollbars, file-input buttons), zero `::placeholder`/`::selection`, zero
+  `clip-path`/`aspect-ratio`/`writing-mode`.
+- `filter`/`transform`/`grid-template-columns` exist only as a handful of fixed, non-parametric presets (`.blur`,
+  `.bright`, `.contrast`, `.grayscale`, `.hue`; `.grid-cols-1`/`-2`; a couple of `translate(-50%)` centering
+  helpers), not general coverage.
+- Section 10.2 formally committed QSS's core to full CSS pseudo-class/pseudo-element coverage regardless of current
+  usage. Section 10.3's own taxonomy lists the entire checkbox/input-state family (`checked`, `indeterminate`,
+  `valid`/`invalid`, `required`, `read-only`, `autofill`), `focus-visible`, link states, `target`/`scope`,
+  DOM-position selectors, and `open`/`popover-open`/`modal`/`fullscreen` as "committed, not yet built." The
+  2026-09-24 four-layer roadmap lists the same item as "not yet started." Nothing has moved on it since; the first consumer's
+  attention shifted to Authentication/Authorization/Activity-Tracking/Intentions, and it was never picked back up.
+- The "a class must resolve to real CSS" auditor guardrail, named as a requirement in section 8 after the
+  29-percent-dead-class census, was also never built. The native auditor checks structural governance (containment,
+  explicit dimensions, no `!important`/manual `z-index`/inline style) and identity grammar, not whether a class
+  resolves to emitted CSS.
+- Roughly 32,000 responsive (`md:w-pct[N]`-style) rules still silently emit invalid CSS at the Sass level, confirmed
+  still present, never fixed.
+
+### 12.2 The decision: restore the original split, don't build full native coverage
+
+Two different problems were being treated as one. The founding QSS problem — "move X left 10px" breaking under
+flex/grid — is ambiguous intent-to-mechanism mapping: margin, order, flex-basis, gap and siblings all plausibly do
+it, so an agent guesses. That is a structural/positioning problem, and QSS's `--qnt` grid, bracket utilities, and
+the Thin Pulse relational-anchoring engine actually solve it. That part keeps.
+
+Gradients, animations, native form-control restyling, and pseudo-class/pseudo-element coverage are not
+ambiguous-mechanism problems — each has exactly one correct CSS mechanism. They are a breadth problem, and
+hand-authoring breadth inside QSS's own grammar is the one move that has broken every time it has been tried here:
+the 2026-09-17 generator gap (786 elements), the 2026-09-21 dead-class census (29 percent), the still-open
+32,000-rule responsive bug, `contain-layout` shipping with no implementing rule at all in 0.1.1. Every one of those
+postmortems called for the same fix (class-must-resolve verification), and it has never been built. Scaling the
+hand-authored surface up to match the full CSS spec bets on the exact mechanism that keeps failing, without first
+closing the gap every prior failure said to close first. It would also reopen the stylesheet-bloat ceiling QSS
+already hit once (485,000 lines, forced the essential/accidental rewrite in section 8) and has no content-scanning
+to bound it a second time.
+
+**Decision**: QSS's core stays scoped to Steel Frame — structural addressability, relational anchoring, `--qnt`
+resolution scaling, and the native auditor's structural governance. A real Tailwind compiler (JIT, content-scanning,
+prefixed and scoped so it cannot collide with a host app's own styles) is adopted as a dependency for Drywall —
+content, decoration, native form-control styling, animation, gradients, and CSS pseudo-class/pseudo-element
+coverage. Section 10.2's "full CSS-spec coverage" commitment is retired as a QSS-core goal; that coverage comes from
+Tailwind instead, where it already exists, is battle-tested, and is something agents already have deep training
+exposure to — the same unfamiliarity-tax argument that killed the bracket DSL as a structural foundation in section
+5 applies in Tailwind's favor here, in reverse.
+
+### 12.3 Why Tailwind doesn't reopen the original wound
+
+Tailwind's content/decoration utilities (`animate-spin`, `bg-gradient-to-r`, `rotate-45`, pseudo-state variants) are
+each already single-purpose — there is no margin-vs-order-vs-basis ambiguity for "add a shadow" or "turn on
+italics." The ambiguity problem was specific to layout/positioning, which stays QSS's job. Tailwind's JIT,
+content-scanned build is also a stronger observability guarantee than QSS's current unscanned hand-generation,
+which is how the 29-percent dead-class rate happened in the first place: every class Tailwind compiles is
+guaranteed to be one actually referenced in scanned markup.
+
+The one piece that must be built, not assumed: a native-auditor rule that a `qss`-marked Steel Frame actor may never
+carry a plain Tailwind layout utility (flex/grid/positioning/sizing). That is what makes the boundary mechanically
+enforced rather than a convention someone can forget to follow — exactly the kind of rule QSS is already good at
+writing.
+
+### 12.4 Resolution scaling is unaffected
+
+`--qnt` is `clamp(0.39px, 0.1cqw, 3.2px)` (dampened at the extremes, settled 2026-10-17 — see the Unreleased entry
+in `CHANGELOG.md`), set via `container-type: inline-size` on `#qss-canvas` and inherited unchanged. It resolves
+once, at the canvas, and has no relationship to whatever styles content inside a frame. The units-and-viewport rule
+from section 9 already anticipated this exact situation — foreign content inside frames may use `rem`/`%` only,
+never raw viewport units — and Tailwind's utility scale is `rem`-based by default, so it satisfies that rule without
+any special-casing. The dampening fix is completely orthogonal to this decision either way.
+
+### 12.5 CSS Suite Preview Window: per-frame container queries
+
+Tailwind's native container-query variants (`@sm:`, `@md:`, etc., reacting to a `@container` box instead of the real
+browser viewport) let Drywall content inside a frame respond to that frame's own rendered width — exactly what a
+Preview Window needs, with zero JavaScript. For this to work per-frame rather than canvas-wide, each Steel Frame
+actor needs its own `container-type: inline-size` plus a `container-name` derived from its existing noun/id — one
+line, riding on the dimension declaration every Steel Frame actor already must carry per the native auditor.
+Tailwind content inside that frame then uses the named variant (`@sm/<frame-name>:`) to target that specific frame,
+independent of the real window size or any sibling frame's size. `theme.containers` breakpoint thresholds should be
+tuned to realistic frame widths, not inherited from Tailwind's viewport-shaped defaults (640/768/1024px...).
+
+### 12.6 Follow-through from the boundary decision: all resolved by 0.2.0
+
+The list this section carried when the boundary was decided (2026-10-16), with how each item ended:
+
+- **A real Tailwind pipeline.** Belongs to the consuming app, not this gem (a JIT compiler has to content-scan real
+  markup that doesn't exist here). Proved out in 12.8 with a disposable app outside both repos; the first consumer
+  has since wired it in and migrated to 0.2.0.
+- **The forbidden-layout-utility rule.** Done: `drywall_boundary`, framework-agnostic and property-based (12.7).
+- **Container queries on frames.** Done: every Steel Frame actor is a size container, named after its own id by the
+  engine (12.5). The `theme.containers` breakpoint values are Tailwind config and live with the consumer.
+- **Decorative utilities.** Decided in 12.9: deprecated in 0.2.0 (orange `deprecated_decorative`), removal planned,
+  with a `drywall_prefix_collision` guard against a Drywall framework compiled with the `qss` prefix. The concern
+  that originally raised it was that QSS-native names (`border-slate-800`, `font-black`, `uppercase`) read exactly
+  like Tailwind's: since 12.7's mandatory prefix, unprefixed means Drywall and `qss-` means QSS, so the vocabulary
+  itself says which layer owns a property.
+- **z-index provisioning.** Retired in 12.9: `qss-z-group[N]`, `qss-depth[key]` and the `depths` config are gone;
+  frames stay out of `z-index` entirely, and overlays use the native top layer or the portal (12.9).
+- **The earlier list.** The roughly-32,000-rule responsive-percent bug, the extreme-resolution `--qnt` dampening and
+  the "class must resolve" auditor rule were fixed before 0.1.3. `qss-dampen-scaling`, reserved for a per-actor
+  dampening opt-in that became a global default instead, was removed in 0.2.0 as vestigial.
+
+### 12.7 2026-10-17: every QSS class is now `qss`-prefixed, no exceptions
+
+Planning the boundary's enforcement surfaced a second, more mechanical problem alongside the forbidden-layout-utility
+rule: QSS's own vocabulary already used bare, unprefixed names deliberately close to a content framework's own
+(`flex`, `absolute`, `w-full`, `w[200]`) -- some utilities had carried a `qss-` twin alongside the bare spelling
+since Item A (2026-09-23), with one of that work's own comments flagging "prefix decision still open." Left bare,
+these can't be told apart, in source text, from a framework like Tailwind compiling its own unprefixed utilities
+onto the same canvas on purpose (12.2's whole point). Settled: every QSS class is `qss`-prefixed, full stop, with no
+bare synonym kept. This also settled the design for the still-open forbidden-layout-utility rule (12.6): a non-QSS
+rule (found by reading the Drywall framework's own compiled CSS, the same technique as the class-resolution check
+built in 0.1.3) setting a structural property (`display`, `position`, `top`/`right`/`bottom`/`left`,
+`width`/`height`, `flex*`, `grid*`, `gap`, `z-index`, `order`) on a `qss`-marked actor is the violation -- checked by
+CSS property, not by matching a maintained list of one framework's class names. That makes the rule framework
+agnostic for free: it needs no fork for Foundation, Bootstrap, or anything else that might fill Drywall instead of
+Tailwind, and it needs neither side's classes to carry any particular prefix to function (a bracket-syntax
+collision check separately confirmed the risk was already near zero there: QSS's `w[200]` and Tailwind's own
+arbitrary-value syntax `w-[200px]` are different strings on sight). Built as `drywall_boundary` the same day (see
+the Unreleased entry in `CHANGELOG.md`).
+
+Picking the canonical word where a bare/`qss-` pair already existed was its own small decision, made explicitly
+rather than by habit: wherever the existing `qss-` twin already matched the underlying CSS mechanism more directly
+than QSS's original invented synonym (`qss-absolute` over `detached`, `qss-flex-row` over `horizontal`,
+`qss-justify-between` over `spaced`, `qss-cursor-pointer` over `clickable`), that twin won. This is not "mirror
+Tailwind's convention" as a goal in itself -- doing that for its own sake would be real coupling to one framework,
+undercutting the agnostic rule above. These particular words (CSS position values, `flex-direction` values,
+`align-items`/`justify-content` shorthand) are close to self-describing CSS regardless of any framework; Tailwind
+happens to use the same shorthand because it's the obvious choice, not because QSS borrowed it. A bare-only
+utility with no existing twin just gained the prefix on its own word, no invention. Bracket-value classes
+(`w[N]`, `p[N]`, `pos-x[N]`, ...) are prefixed the same way, matching `QSS-MANIFESTO.md`'s own original example
+syntax (`.qss-pos-x[500]`) -- the mandatory prefix was the manifesto's stated grammar from the start (section 3),
+and this change restores it rather than introducing it. Identity/relational markers that were never adjectives in
+the manifesto's own sense (`qss` itself, `group`, `foreign`) are unchanged.
+
+Consumer migration is mechanical -- QSS's vocabulary is a closed, known list (`config/grammar.yml`) -- but real: a
+consumer's existing markup using the old bare spellings now resolves to no compiled CSS at all, surfaced
+immediately as `unresolved_class` red findings (0.1.3) rather than silently. `qss-engine.js`'s runtime parsing was
+already prefix-tolerant (an optional, not mandatory, `qss-` in its class-parsing regexes) and is now prefix-
+mandatory instead, so CSS-only and engine-assisted behavior stay consistent -- the engine no longer quietly keeps
+an old bare class working after its compiled rule is gone.
+
+### 12.8 2026-10-18: a real Tailwind integration spike, outside both repos
+
+The first consumer's own migration to 12.7's mandatory prefix surfaced a second, much larger problem: ~308 distinct classes
+across 68 files that read as Tailwind decoration (`qss-gap-2`, `qss-text-[9px]`, `qss-bg-emerald-400`, ...) but have
+never resolved to any compiled CSS at all, in any version of core. Root cause suspected but not yet proven: the first consumer's
+own architecture docs claim a Tailwind build exists (`CLAUDE.md`: "Tailwind CSS, custom prefix: qss-") but no such
+build has ever actually been wired in -- no `tailwind.config`, no `@tailwind`/`@import "tailwindcss"` anywhere in
+the repo.
+
+Deciding how to fix that live, in the consumer's session, was explicitly rejected (Kraig, same conversation) as the
+exact failure mode QSS's own gem extraction (2026-09-25) was supposed to end: the first consumer and QSS co-evolving reactively
+in circles, each dictating the other's next move. "QSS needs to become what it will become, independent of all
+other influences" -- so rather than wire Tailwind into the consumer's messy, debt-carrying codebase and read the signal
+through that noise, or wire it into this gem's own repo (which doesn't need Rails/Tailwind build tooling for
+anything **its own** design requires -- the `drywall_boundary` mechanism is already proven framework-agnostic via
+synthetic fixtures, `spec/qss/native_auditor_drywall_boundary_spec.rb`), a third, disposable option: a minimal Rails
+app outside both repos (`qss-tailwind-spike`, not checked into either repo, gem dependency on QSS via the same
+`path:` mechanism the first consumer uses, a real `tailwindcss-rails` build, a handful of fixture views, nothing else) to prove
+the integration pattern in isolation, then report findings back here -- not decide anything live.
+
+**Confirmed working, for real, not just in theory**: `drywall_boundary` correctly flagged three deliberate
+structural violations (`grid` sets `display`, `fixed` sets `position`, `inset-0` sets `inset`) on a `qss`-marked
+actor, reading Tailwind v4's actual compiled output (`auditor.drywall_stylesheet_path` pointed at
+`app/assets/builds/tailwind.css`) -- not the synthetic `.flex { display: flex; }`-style strings its own spec suite
+uses. The framework-agnostic, property-based design holds up outside a unit test.
+
+**Confirmed working**: a real `tailwindcss-rails` build and this gem's own engine-provided assets
+(`app/assets/stylesheets/qss/qss_core.css`, `app/assets/javascripts/qss/qss-engine.js`) coexist under Propshaft with
+zero friction -- correct digest fingerprinting on both compiled stylesheets, no load-order issue, no configuration
+needed beyond the two Gemfile dependencies. `QSS::Engine`'s asset paths get picked up automatically, as designed.
+
+**Confirmed broken -- and very likely the actual root cause of the first consumer's whole dead-class debt, not merely
+"the consumer never built Tailwind"**: `unresolved_class` (`Stylesheet.load`, called with `settings['stylesheet_path']`
+in `audit_file`) only ever checks a class against `auditor.stylesheet_path`, which defaults to core's own
+`qss_core.css`. It has no knowledge of `auditor.drywall_stylesheet_path` at all -- that setting is read only by the
+separate `drywall_boundary` check. Every one of the spike's genuinely real, genuinely compiled Tailwind decoration
+classes (`text-slate-500`, `text-sm`, `font-semibold`, `uppercase`, `tracking-wide`, `p-4`, `bg-slate-100`) came back
+as `unresolved_class` red, exactly as if no Tailwind build existed at all. This means even a consumer that had wired
+up a real Tailwind build from day one would show the identical false-red findings today, because the check never
+looks at the second stylesheet. Needs a real fix, not a consumer-side workaround: `unresolved_class` should check the
+union of `stylesheet_path` and `drywall_stylesheet_path` (when the latter is configured) before calling a class
+dead.
+
+**Side finding, reproduced cleanly outside any consumer, confirming it's a gem bug and not a consumer-only artifact**: the
+spike's first fixture draft happened to pick the exact three words used as prose examples in 12.7's own paragraph
+above (`flex`, `absolute`, `w-full`) and in the generated `qss_core.css`'s corresponding comment (around line
+70737: "a content framework compiling its own unprefixed `.flex`/`.absolute`/`.w-full` would..."). All three
+silently registered as "resolved" with no `unresolved_class` finding at all, despite no real rule existing for any
+of them (confirmed: `grep` for `\.flex\b` etc. in the compiled CSS matches only that comment line, never a selector).
+`Stylesheet.classes_in`'s selector-extraction regex (`css_text.scan(/([^{}]+)\{[^{}]*\}/m)`) sweeps up whatever text
+sits between two rules, including comment bodies, and reads it as if it were selector text for the rule that
+follows. Any class name mentioned in a comment, anywhere in core, silently and incorrectly resolves. Narrow fix:
+strip comments before extracting selectors, same as CSS tooling generally does.
+
+Nothing here was decided or built against this gem from the spike itself -- findings only, per the above. The spike
+app is disposable and not checked into either repo. Both bugs were fixed in the commit that followed and shipped in
+0.2.0 (the `unresolved_class` check now reads the union of both stylesheets, and comments are stripped before
+selector extraction).
+
+### 12.9 2026-10-18: closing out 0.2.0's two open design questions
+
+Both questions flagged in 12.6 were decided on QSS's own merits, with the 12.8 spike as the evidence base that
+12.6 said was missing.
+
+**z-index provisioning: retired.** `qss-z-group[0..10]` and `qss-depth[key]` contradicted the stated design (frames
+stay out of `z-index`; overlays portal to the document root) and sat outside the Portal Integrity rule, whose regex
+matches neither shape. Both are gone, along with everything that existed only to feed them (`depths` config,
+`$qss-depths`, the generated `DEPTHS` constants, the engine's runtime `z`/`z-index`/`depth` cases). Portal Integrity
+is kept as is: it now has nothing of QSS's own to be bypassed by, and still catches inline `z-index` and
+framework `z-N` classes outside a portal. Breaking for consumers (the first consumer used `depth[...]` widely); that is a
+0.x minor-version break, called out in the changelog.
+
+**Decorative utilities: deprecated now, removed later.** The 12.6 worry was two grammars producing identical-looking
+class names. Since 12.7 that is mostly answered by the prefix itself (unprefixed = Drywall, `qss-` = QSS), so the
+remaining hazards are (a) a Drywall framework compiled *with* the `qss` prefix, which makes the two indistinguishable
+again, and (b) QSS still shipping Tailwind-shaped appearance classes (colors, type styling, shadows, filters) that
+Drywall now owns. For (a), the auditor gained a red `drywall_prefix_collision` finding. For (b), the named
+decorative classes are flagged orange `deprecated_decorative` and stay functional for one release, rather than
+being deleted blind: a consumer needs a migration window, and the 12.8 spike proved wiring, not full coverage
+equivalence. QSS's quantized bracket scale (`qss-border[2]`, `qss-rounded[8]`, `qss-text-size[14]`) is kept: it
+scales with `--qnt`, which no Drywall framework can do. Still open for a later release: actually removing the
+deprecated set (and the palette-driven color/alpha/accent generation, which is most of the compiled stylesheet),
+once a consumer has migrated off it.
+
+**Overlays: native top layer first, z-index as the fallback.** Retiring QSS's own z-index utilities left the question
+of how overlays get stacked. The rule (Kraig, 2026-10-18): modals, dialogs and popovers use the browser's native top
+layer (`<dialog>` + `showModal()`, or the `popover` attribute) whenever possible, which needs no `z-index` and cannot
+lose a stacking fight with anything in the page. Where that is not possible (a custom overlay, an older browser), the
+element lives in the portal root, rooted at the document body above the QSS canvas, and may carry a `z-index` there.
+Enforced as an orange `top_layer_preferred` finding with an explicit `qss-overlay-fallback` escape hatch, rather
+than a red rule, because whether the fallback is justified is a judgment call. Portal Integrity was also widened to
+allow `z-index` anywhere inside the portal (not only on the portal root element itself), since otherwise the
+fallback path could not stack one overlay above another without being a violation. Portal detection itself was
+scoped at the same time: the old `id.include?('portal')` substring match would have flagged any `customer-portal`-style
+id, so a portal root is now the configured `portal_root` id, or `portal` behind the `qss-` or project id prefix.
+
+Also cleared: the vestigial `qss-dampen-scaling` marker (never did anything once dampening became a global
+default) and a stale `qss-bg` grammar entry; `QSS-MANIFESTO.md` (which ships in the gem) was brought in line with
+the current install flow and the boundary.
+
+### 12.10 2026-10-18, after 0.2.0 shipped: a locked-down portal root and a positioning diagnostic
+
+Two follow-ups to 12.9, built once 0.2.0 was out and the first consumer had migrated to it.
+
+**The portal root is matched by exact id.** 0.2.0 recognised the portal root three ways (the configured id,
+`qss-portal`, or `portal` behind the project's own id prefix). Every one of those was a convention an auditor had to
+guess at. Now there is exactly one: `config.portal_root`, a simple `#id` selector the project chooses (default
+`#qss-portal`), validated when the settings load and again in `qss-sync`, and compared exactly. A first version of this
+change also required the id to start with `qss-`; that was dropped because the id names a real element in the
+consumer's own markup, which the consumer owns, so mandating a prefix would only break working installs without making
+the match any more exact. What locks it down is exactness, not the name. It does not cover a second overlay root a
+project invents without registering it, or a portal created by script at runtime; the static auditor cannot know
+about either.
+
+**`QSSEngine.auditPositioning()`.** The static auditor catches a Drywall class that sets `position` only when the
+element is a frame (`drywall_boundary`), and only when the class resolves in the Drywall stylesheet. A `fixed` utility
+on any other element is invisible to it. The browser knows the computed position, so the engine gained an opt-in
+diagnostic that reports fixed/sticky elements QSS does not own (frames, anything in the portal, foreign content, and
+the native top layer are exempt). It is deliberately not part of the pulse: it scans the whole document, and it is a
+development aid, not a runtime behavior.
+
+### 12.11 2026-10-19: the portal root's own geometry (0.3.1)
+
+The first consumer's migration found that a portal root configured as `portal_root` had no base geometry in the
+compiled stylesheet. Every generated utility is scoped `:is(<canvas>, <portal root>) .class`, which can only match a
+descendant of a root, so `qss-absolute qss-inset-0` on the portal root itself matched nothing; the canvas never
+suffers from this because of its separate, unscoped Root Anchor rule, and the portal had no equivalent. The root fell
+into normal flow after the canvas with no size, and everything portaled into it measured against an empty box.
+Neither auditor can see this (the classes look fine statically), which is why the fix came with the first
+real-browser assertion of portal geometry (`qss-core-render-check`), confirmed to fail against the 0.3.0 stylesheet.
+
+Decisions: the portal root gets its geometry from a rule by id, not from utility classes (utility scope is a
+deliberate descendant-only design, and widening it would let a utility rewrite the root's own box); it is
+`position: fixed; inset: 0` because an overlay layer is viewport-relative by definition, unlike the canvas's
+parent-relative `position: relative`; it is a size container with `--qnt` resolved on its children so qnt-sized
+overlays work, which equals the canvas unit when the canvas spans the viewport and differs when it does not; and it
+is `pointer-events: none` with `auto` on its direct children so a viewport-sized layer never blocks the page. The
+base actor reset the canvas gives its actors now also applies inside the portal (a shared mixin), since an actor
+portaled into an overlay is still a Steel Frame actor. The default `portal_root` also became `#qss-portal` in the
+grammar, so the stylesheet, auditors and engine share one default.
+
+## 13. State of the gem after 0.3.1 (2026-10-19)
+
+Where sections 1-12 ended up, in one place.
+
+**The split.** QSS owns *structure*: position, size, flow, containment and stacking context. Whatever fills the
+content layer ("Drywall", normally Tailwind) owns *appearance*. Every QSS class is `qss-`-prefixed, so the vocabulary
+alone says which layer owns a property; the native auditor enforces the split from both directions
+(`drywall_boundary` for a Drywall class that sets a structural property on a frame, `drywall_prefix_collision` for a
+Drywall framework compiled with QSS's own prefix).
+
+**What QSS provides.**
+- The canvas and `--qnt` (canvas width / 1000, pure CSS, dampened at extreme widths), with bracket classes in qnt for
+  position and size (`qss-pos-x[500]`, `qss-w[200]`) and QSS's own quantized scale for borders, radii, text and icons.
+- Steel Frame actors (`qss`): each is a size container named after its own id, so Drywall content can respond to its
+  own frame (`@sm/<frame>:`).
+- Two auditors. `QssNativeAuditor` is the live one (identity and registry rules, dimensions, units, class
+  resolution against the compiled stylesheet and the Drywall stylesheet, the boundary rules, Portal Integrity and
+  top-layer preference); `QssAuditor` is the older class-whitelist auditor. The engine can also report fixed/sticky
+  elements QSS does not own (`QSSEngine.auditPositioning()`, opt-in, 12.10).
+- Two real-browser render checks (`rake render_check`, `rake engine_check`), because only a browser is real proof.
+
+**Overlays.** Frames never set `z-index`. Modals, dialogs and popovers use the browser's native top layer
+(`<dialog>` + `showModal()`, `popover`); anything else is the fallback path, rooted in the portal outside the
+canvas, where a `z-index` is allowed and a `qss-overlay-fallback` marker says it is deliberate. The portal root is
+identified by one exact configured id (12.10), and gets its own base geometry from core (12.11).
+
+**Deprecated, not yet removed.** The decorative named utilities (colors, type styling, shadows, filters). They still
+compile and still work; each use is an orange `deprecated_decorative` finding. Removing them, and the
+palette-driven color classes that make up most of the compiled stylesheet, is the main open item.
+
+**No iframe policy (decided 2026-10-18).** An iframe is a separate document the auditors cannot see, and QSS treats
+it like any other element: as a frame it still has to declare its size, and its contents are the embedded page's own
+business. Iframes are still common for third-party embeds (video, maps, payment and captcha widgets), so none is
+forbidden, and a rule would have nothing to check inside one.
+
+**State variants: built and held out (noted 2026-10-21).** Checked against `qss_core.scss`, prompted by a stale status
+line in a consumer's own spec that still called most of this "not yet built". State variants are written
+`{state}:{class}` (the state itself is never `qss-` prefixed) and compile to a real rule, scoped under the canvas.
+- *Built, essential* (`$qss-accent-states`, 31 states, additive: palette size adds no rules). `{state}:qss-bg-accent`,
+  `-text-accent` and `-border-accent`, plus their group-relational forms (`group-{state}:...`, and each registered
+  `group/{name}`), for: hover, focus, focus-within, focus-visible, active; enabled, disabled, checked, indeterminate,
+  default, placeholder-shown; valid, invalid, in-range, out-of-range, required, optional; read-only, read-write,
+  user-valid, user-invalid, autofill; link, any-link, target; open, popover-open, modal, fullscreen,
+  picture-in-picture, defined. The state list is the W3C convention, not consumer config.
+- *Built, palette-driven* (`$qss-state-prefixes-test`, 21 states: the list above up to and including autofill,
+  without focus-visible). The self-referential palette colors and alpha steps per state. This is the part of the
+  compiled stylesheet that grows with the palette, and it is among what the open item in section 13 would remove.
+- *Held out, with reasons that differ.* `:visited` is held out for privacy restrictions: browsers limit which
+  properties a `:visited` rule may set, so it needs its own test and is still a runtime-only carve-out.
+  The DOM-position selectors (`:nth-child()` and its family) use a different mechanism, not a state-prefix rule.
+  `:local-link` is held out because no browser implements it; that is "nothing to build yet", not a state that merely
+  has not been got to.
+
+## 14. 2026-10-22: the text scale learns two sizes of "small" (0.5.0, 0.6.0)
+
+**The finding.** A consumer (Parapet) set its header title and sub-title to `qss-text-size[7]` and measured both at exactly
+9px in a real browser. Not a coincidence: `text_scale.floor_px` was 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 for the whole range. `[5]`, `[7]` and `[10]` were indistinguishable.
+
+**Decision 1: lower the floor to 5px.** The 9px floor was a legibility guard from the 2026-09-21 text-scale decision (item 7).
+It was clamping harder than needed. At 5px, `[5]` still floors flat, and `[7]` and up scale with the canvas (`N * 0.875` is the
+floor from N = 6). The cost, accepted: a small size on a narrow canvas now renders smaller than before (`[9]` is under 8px
+at 390). The Ruby auditor's below-11 check is unchanged, so tiny body text still draws a finding unless waived with
+`qss-legibility-override`. The 5 is a judgment call, not a derived number.
+
+**Decision 2: legibility clamping is for body copy, not for branding.** A floor and cap are right for text people read, and wrong
+for a wordmark that should resize like a photo. So the clamp is not removed from `qss-text-size[N]`; a second class is added,
+`qss-text-size-linear[N]` (N 1 to 96): `N * 100vw / 1440`, no floor, no cap, no dampening. It deliberately reuses the existing
+`--u` unit of `qss-icon-size[N]` instead of a new one. The name was a judgment call (alternatives `qss-display-size`, which
+names the use but not the behavior, and `qss-text-fluid`, which clashes with CSS "fluid type" that usually clamps). The
+auditor's legibility check does not read it, on purpose.
+
+**Known limit, and the next move.** `--u` is `100vw / 1440`, so it tracks the viewport, not the canvas: fine for a
+full-width header, wrong for text inside a narrower sized container. `--qnt` already solves the same shape of problem: it
+defaults to the viewport and re-resolves with container-query units inside a sized container, as one variable, not two
+systems. The plan for the next minor is for `--u` to learn the same trick, not to add a parallel canvas unit. Not built yet.
+
+**Process note.** The floor change shipped as 0.5.0 (an unpublished 0.4.3 was renumbered before release), and the linear
+class followed the same day as 0.6.0. The `v0.4.3` tag is a leftover, not a release.
+
+## 15. 2026-11-01: `#qss-wrapper` and the canvas's own aspect ratio — proposal superseded, see section 17
+
+**The finding.** `QSS-MANIFESTO.md` names `#qss-wrapper` as the second piece of the four-piece "Deterministic
+Stack" ("Enforces viewport boundaries and provides a Safety Gutter"), but `qss_core.scss` has never had a rule for
+it -- only `#qss-canvas` is styled there. A consumer's `#qss-wrapper` is therefore an ordinary `div` with no size
+of its own, so `#qss-canvas`'s `height: 100%` resolves against nothing unless the consumer gives the wrapper a
+real height by hand, and most reach for `width: 100vw; height: 100vh` -- which stretches the canvas to fill
+whatever shape the real window happens to be, edge to edge, exactly.
+
+That stretch is a real problem specifically because of how `--qnt` is defined: one scalar, `canvas width / 1000`,
+used for every bracket class on **both** axes (`qss-pos-y[N]` compiles to `N * qnt`, the same unit as
+`qss-pos-x[N]` -- confirmed in `qss_core.scss`'s bracket loop, one `@for` driving `pos-x`, `pos-y`, `w` and `h`
+off the same `--qnt`). That's deliberate (section 10: a canvas shown at half width "keeps its contents in
+proportion"), and it's the mechanism behind the gemspec's own pitch -- "the same numbers hold at any screen
+size." But the guarantee is conditional: it only holds if the canvas's own *shape* stays fixed. A design has no
+way to declare "my content needs a canvas at least this tall relative to its width" -- the 1000-unit grid has one
+axis, width, with y riding along on the same unit -- so a design that uses y all the way up to 1000 (matching the
+canvas's own 1000-qnt width, the natural reading of "use the whole grid") is implicitly assuming a **square**
+canvas, and a consumer that stretches `#qss-wrapper` to an arbitrary window shape will see that content run past
+the real bottom edge on a wide/short window, with nothing above the auditor layer able to catch it (this is pure
+rendered geometry; the static auditor doesn't simulate layout).
+
+**Found twice now, independently**, per Kraig: this is the second real consumer to hit content running off the
+canvas's bottom edge from this exact gap. The most recent and best-documented case: a second PWA app's landing
+page (`qss-pos-y[550]`/`qss-pos-y[800]` elements) computed well past the bottom of a real 2560x1298 browser window --
+1408px and 2048px down against a 1298px-tall, edge-to-edge-stretched canvas -- so the elements weren't just
+clipped, they were rendering entirely outside the visible, `overflow: hidden` canvas. Pixel-measured against a
+screenshot, not just reasoned about: see that app's own dev notes, dated 2026-11-01, for the full measurement.
+
+**What that app did, as an app-level stopgap (2026-11-01).** In its own `application.scss`:
+```scss
+#qss-wrapper {
+  position: relative;
+  width: 100vw;
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: /* the app's own gutter fill */;
+}
+#qss-canvas {
+  width: min(100vw, 100vh);
+  height: min(100vw, 100vh);
+  flex-shrink: 0;
+}
+```
+This locks the canvas to the largest square that fits the real viewport and centers it, letting the wrapper's own
+background show through as a gutter on whichever axis is wider. It works, and it's a reasonable reference for the
+end behavior, but it's hand-rolled app CSS: hardcoded to a 1:1 ratio, rediscovered from scratch by a consumer who
+had no way to know this was supposed to be core's job. Exactly the kind of thing meant to be solved once, centrally
+(same reasoning as the `qss-` prefix boundary in section 12, or the native auditor existing at all): a second
+consumer hitting the identical bug independently is the signal.
+
+**Proposed for the next iteration.**
+1. A new config key -- working name `config.canvas_aspect_ratio` -- read the same way `portal_root` and `palette`
+   already are. A number (`1` = square) is enough to start; a `"w:h"` string (`"16:9"`) is the more general shape
+   if non-square consumers show up, but adds real width/height math (see the open question below) rather than the
+   `min(100vw, 100vh)` shortcut a square ratio allows.
+2. Thread it through `exe/qss-sync`'s `scss_variables` (same place `portal_root` flows today, `exe/qss-sync` lines
+   ~125-167) into both `_qss_defaults.scss` (core's own neutral default) and a consumer's generated
+   `_qss_variables.scss`.
+3. `qss_core.scss`: a real `#qss-wrapper`/`#qss-canvas` rule driven by that variable -- flex-centered wrapper,
+   canvas locked to the configured ratio, a gutter fill color (reuse an existing palette entry, or a second new
+   config key).
+4. `#qss-portal`: should need no change -- it's already sized to the full viewport independent of the canvas by
+   design (section 12.11/CHANGELOG 0.3.1), which is correct; overlays are meant to cover the real viewport, not
+   just the letterboxed canvas. Worth confirming explicitly when this is built, not assuming.
+5. `QSS::QssNativeAuditor`: no change anticipated. This is rendered geometry the static auditor has no mechanism
+   to see.
+
+**Open questions for whoever picks this up.**
+- **Default behavior.** Should an unconfigured consumer keep today's edge-to-edge stretch (fully backward
+  compatible, the new behavior opt-in only), or should core default `canvas_aspect_ratio` to `1` given both known
+  real consumers have now independently hit the same bug without it? The first is the conservative, semver-safe
+  choice; the second is arguably the more honest default, since the MANIFESTO already describes this as the
+  wrapper's job rather than an opt-in extra. Either way, the CHANGELOG entry needs to say plainly whether this is
+  a visually breaking change for existing consumers, even inside 0.x's "minor versions may break the API" rule.
+- **Non-square math, not yet written or tested.** That app's stopgap only had to handle 1:1, where
+  `min(100vw, 100vh)` on both axes is enough. A general ratio needs real width/height math (something like
+  `width: min(100vw, 100vh * $ratio); height: min(100vh, 100vw / $ratio);`, or the CSS `aspect-ratio` property
+  paired with `max-width`/`max-height` caps) -- sketched here, not built or checked in a real browser.
+- **The existing `qss-safety-gutter` utility.** Core already ships `.qss-safety-gutter { padding: 2px;
+  background-color: slate-900 }`, whose name matches the MANIFESTO's "Safety Gutter" wording closely enough that
+  it was plausibly meant for this, but it's a decorative padding/background utility class, not a layout rule, and
+  nothing applies it to `#qss-wrapper` today. Decide whether the new wrapper rule subsumes it, replaces it, or the
+  two stay separate (one for the actual letterbox layout, one for optional decoration on top of it).
+- **Migration for existing consumers.** Once core emits a real `#qss-wrapper`/`#qss-canvas` rule, a consumer that
+  already hand-rolled its own (as of 2026-11-01) will get a cascade collision on upgrade and needs to
+  delete its local version in favor of the config key. Needs a CHANGELOG migration note when this ships.
+
+Not built yet.
+
+**2026-11-02 update.** The `canvas_aspect_ratio` + letterbox/pillarbox design sketched above was actually built, as
+that app's own app-level stopgap, then reverted the same day (2026-11-01) after it produced visible pillarboxing
+on a real 2560x1298 window locked to 16:10. Independently ruled out in principle the next day (2026-11-02) as
+incompatible with full-bleed PWA use, where any visible gutter is unacceptable regardless of how it's produced. The
+canvas-ratio-lock approach described in this section is retired — see section 17 for the model that replaced it.
+
+**2026-11-02, second update, after a documentation audit.** The fix proposal above being retired is a different
+fact from whether `#qss-wrapper` should still be *claimed* as one of `QSS-MANIFESTO.md`'s required "Deterministic
+Stack" pieces, and the manifesto still listed it as required (item 2 of 4) after the first update above. That's
+now corrected too: `#qss-wrapper` is dropped from the stack entirely (three required pieces, not four), not
+merely marked unbuilt — the finding above already established it never had an implementing rule, and the "Safety
+Gutter" it was described as providing is the exact thing section 17 ruled out on principle, so no fix this project
+would actually ship was ever going to make the original claim true. Recorded here rather than silently deleted, in
+case a real need for a wrapper-level mechanism comes up later — an embed mode that isn't full-bleed, say. If so, it
+should be scoped and named fresh rather than reviving this description verbatim, since "enforces viewport
+boundaries and provides a Safety Gutter" is specifically the behavior section 17 rejected. This also resolves, by
+making moot, this section's own open question above about whether the existing decorative `qss-safety-gutter`
+utility should be subsumed by a future wrapper rule: there is no wrapper rule coming for it to be subsumed by.
+
+## 16. 2026-11-01 (same day): the single-axis qnt problem, found again at element scale
+
+**The finding.** Section 15 documented the single-axis `--qnt` problem at the scale of the whole canvas
+(`#qss-wrapper` stretching to an arbitrary window shape, so width-relative `qss-pos-y[N]` can run past the
+real bottom edge). The same root cause -- one scalar unit, derived from canvas **width**, used for everything,
+with no corresponding canvas-**height**-relative unit -- turns out to bite at the scale of a single element too,
+independent of whether `#qss-wrapper` itself is ever fixed to a ratio.
+
+A second PWA app's landing-page logo (`#landing-logo`) is a `.qss` actor with `qss-w[150]` (width = `150 * qnt`,
+canvas-width-relative) containing an `<img>` styled `width: auto; height: 200%` (height = 200% of the
+container's own height, and the container's height comes from `qss-h-pct[200]`, i.e. **canvas-height**-relative,
+a completely different, uncoupled axis). The image's rendered width is then derived from that
+canvas-height-relative height times the image's own fixed aspect ratio (a 410x520 two-frame hover-reveal
+sprite, 0.7885). Algebraically:
+
+```
+container_width = 0.15 * canvasWidth
+image_width      = 2 * 0.20 * canvasHeight * 0.7885 = 0.3154 * canvasHeight
+```
+
+These only come out equal when `canvasWidth / canvasHeight ≈ 2.10`. Below that ratio -- every ordinary 16:9 or
+16:10 window -- the image renders wider than its own container, and `overflow: hidden` clips the excess evenly
+off both left and right edges. At 16:10 the deficit is roughly 47 qnt (a serious, visible clip); at a window
+near the 2.10 coincidence point it can shrink to a couple of pixels, which is what actually prompted this
+finding -- it first looked like a rounding artifact, and only algebra (not a bigger/smaller test) revealed it
+was the same structural mismatch as section 15, just small by coincidence of one particular window's aspect
+ratio. See that app's own dev notes, dated 2026-11-01, for the pixel-measurement and the full calc.
+
+**First stopgap tried, and why it failed (same day).** The obvious fix looks like: drop the element's `qss-w[N]`
+class and let the actor reset's default `width: auto` shrink-wrap the `display: flex !important` container to
+its one child's rendered width, so `container_width` and `image_width` become the same value by construction
+instead of two independent calculations that only coincide near one ratio. **This does not work, and not by
+accident.** Every `.qss` actor is given `container-type: inline-size` (`qss_core.scss` line 76, for the
+container-query engine that resolves `--qnt` and lets consumers key off a container's own name/size). Per the
+CSS Containment spec, `container-type: inline-size` implies inline-size *containment*, which requires the
+browser to compute an `auto` inline size (width, in horizontal writing mode) as if the box has no content --
+sizing can't depend on descendants, because that's what would make container queries circular. The practical
+effect: `width: auto` on any `.qss` actor doesn't shrink-to-fit, it collapses straight to the actor reset's
+floor, `min-width: calc(1 * var(--qnt))` -- a 1px-ish sliver. Confirmed by trying it on that app's logo:
+exactly this collapse, reproducing the *original* "missing positioning quantity" sliver bug from earlier the
+same day (this gem's `min-width: 1 * qnt` reset is exactly what a width-less or auto-width actor collapses to).
+This is a hard architectural fact, not a workaround to refine: **no `.qss` actor can ever use shrink-to-fit/
+content-based auto sizing, in either axis, full stop** -- containment forbids it by spec, in every current and
+future browser that implements container queries correctly. Any fix has to keep every actor's box fully
+explicit.
+
+**What that app did instead, as a working app-level stopgap (2026-11-01).** Kept both dimensions explicit,
+but moved the height off the canvas-height-relative axis entirely: `qss-h-pct[200]` (percentage of canvas
+height) became `qss-h[95]` (plain `calc(95 * qnt)`, the *same* canvas-width-relative unit as `qss-w[150]`).
+Solved for 95 by requiring `image_width == container_width` with no canvas-height term anywhere in the
+equation: `containerWidth = 2 * containerHeight * 0.7885` (the sprite's aspect ratio) -->
+`containerHeight = containerWidth / 1.5769` --> `150 / 1.5769 ≈ 95.1`, rounded down to keep the image a hair
+narrower than its box rather than a hair wider (a sub-qnt gap, not a clip). Because both numbers now live
+entirely on the same qnt axis, their ratio is a fixed constant baked into the markup -- it holds at *every*
+`canvasWidth/canvasHeight`, not just one coincidental value. The cost: this element's on-screen size now scales
+with canvas width only (consistent with the rest of the qnt system), no longer with canvas height the way
+`qss-h-pct` intended -- an acceptable tradeoff here since nothing about this particular logo needed
+height-relative scaling in the first place.
+
+**Proposed for the next iteration.** This strengthens the case for section 15's fix (a real
+`canvas_aspect_ratio`, so canvas shape is never arbitrary and both qnt and `%`-of-canvas-height stay in a fixed,
+known relationship) but also suggests a second, smaller, independent gap worth considering alongside it: QSS
+currently has no first-class way to say "this element's width and height must stay in a fixed ratio to each
+other," only width-relative (`qss-w`/`qss-pos-x`) and height-relative (`qss-h-pct`/`qss-pos-y-pct`) units that
+are each relative to a *different* canvas dimension, and (per the containment finding above) no way to derive
+one axis from actual rendered content either. A bracket class built on the native CSS `aspect-ratio` property
+(something like `qss-aspect[77:100]`) would let an actor declare its own intrinsic ratio directly, independent
+of canvas shape, and -- importantly -- `aspect-ratio` is an intrinsic-sizing CSS property, not content-based
+auto-sizing, so it is **not** subject to the inline-size containment problem above; it would sidestep the whole
+issue rather than require consumers to hand-solve a qnt pair like this app just did. Worth scoping as a
+follow-on to section 15 rather than folded into it, since it solves a different case (an element's own internal
+ratio, vs. the canvas's own ratio).
+
+**Open questions for whoever picks this up.**
+- Should `qss-aspect[W:H]` interact with `qss-w[N]`/`qss-h[N]` (one given, the other derived) or be mutually
+  exclusive with explicit width/height classes? CSS `aspect-ratio` already defines this precedence natively
+  (an explicit `width` or `height` wins, `aspect-ratio` only fills in the missing one), so the bracket class
+  likely just needs to expose that existing behavior rather than invent new rules.
+- Whether this is worth a dedicated audit rule in `QSS::QssNativeAuditor` (flagging an actor that mixes a
+  width-relative class with a height-relative one on the same element, the exact pattern that caused this) --
+  static, so it could catch this class of bug before it ever reaches a browser, unlike section 15's.
+- Whether the containment finding belongs in `QSS-MANIFESTO.md` on its own, independent of the aspect-ratio
+  question -- "no actor may rely on shrink-to-fit/auto sizing from its content, in any axis" is a general rule
+  any consumer can trip over (not just this aspect-ratio case), and nothing currently documents it or warns
+  against it before a consumer tries it and gets a 1px sliver.
+
+Not built yet.
+
+**2026-11-02 update.** The `qss-aspect[W:H]` proposal above still stands — it addresses a genuinely separate
+concern (an element's own intrinsic ratio) from the canvas-shape questions resolved in section 17, and remains a
+good complement to that section's "rigid qnt" tool for any actor (sprite, icon, logo) that needs a fixed shape
+independent of its container. The single-axis diagnosis in this section is folded into section 17's broader model.
+The containment-constraint open question above is resolved: written into `QSS-MANIFESTO.md` section 2 on
+2026-11-02.
+
+## 17. 2026-11-02: three tools for proportionality (position vs. size vs. shape), retiring the canvas-ratio lock
+
+**The question this closes out.** Sections 15 and 16 diagnosed the single-axis `--qnt` problem at the canvas scale
+and the element scale, and section 15 proposed a canvas-shape-level fix: a configured `canvas_aspect_ratio` plus a
+letterboxed/pillarboxed `#qss-wrapper`/`#qss-canvas` rule. Kraig flagged two hard requirements that rule that fix
+out for how the gem is actually meant to be used: it's built primarily for PWA-style apps, where the canvas must
+fill every real window at every resolution with zero dev-side configuration, and a locked ratio's gutters —
+visible pillarboxing/letterboxing — are not an acceptable tradeoff to get there, full stop (2026-11-02). A
+same-day discussion, following a cross-session message from a second PWA app under development (which
+independently hit the same bugs against gem 0.6.0 — see that app's own dev notes), worked through several
+plausible-looking alternatives before landing on the actual fix.
+Recording the rejected paths here so none of them get re-proposed blind.
+
+**Rejected approaches, and why.**
+
+1. **Splitting `--qnt` into `--qnt-x`/`--qnt-y`** (canvas-width- vs. canvas-height-derived, via CSS's `cqw`/`cqh`
+   container query units). Makes `qss-pos-y[N]` finally proportional to the canvas's *actual* height instead of its
+   width — but breaks the one guarantee the single scalar exists for: two elements positioned on different axes
+   stop holding their relative position to each other as the canvas reshapes, reintroducing "ordinary responsive
+   CSS's guess-which-property-moved problem" inside QSS's own unit system. Proposed and rejected twice,
+   independently: once in that app's own session on 2026-11-01, once again (unknowingly, by this repo's own
+   session) on 2026-11-02, before the first rejection's reasoning surfaced. The gem's existing `qss-*-pct[N]`
+   classes (plain CSS percentage of the immediate containing block) are mathematically the identical split, just
+   expressed without a second custom property, and carry the same cross-axis drift cost whenever used as a blanket
+   replacement for qnt rather than deliberately, per element (see tool 2 below).
+2. **Section 15's `canvas_aspect_ratio` + `min()`-based letterbox/pillarbox.** Actually built, as that app's own
+   app-level stopgap (2026-11-01), then reverted the same day after producing visible pillarboxing on a real
+   2560x1298 window locked to 16:10. Ruled out in principle the next day for the reason above: any visible gutter
+   is unacceptable for full-bleed PWA use, independent of whether the lock is a fixed square or a configurable
+   ratio.
+3. **`max()`-based "cover" scaling** (the mirror image of 2: fill the viewport with no gutters, crop whatever
+   canvas content overflows instead). Satisfies "full-bleed, no black boxes," but conflates two different kinds of
+   content. It's an acceptable tradeoff for a design with a genuine center and only decorative margin near its
+   edges (a book-style, centered layout); it is not acceptable for a design where the edges carry load-bearing,
+   non-decorative UI (global nav, a file-tree explorer, a toolbar docked to the side) — there's no sacrificial
+   margin there to crop. Rejected as a canvas-wide default for that reason; QSS has consumers of both kinds.
+4. **A static `QssNativeAuditor` rule** bounding `pos-y + h` (or resolved `h-pct`) against a configured worst-case
+   aspect ratio. Zero CSS cost — pure build-time arithmetic, same category as the gem's existing structural
+   checks — and deliberately avoids the stylesheet-bloat risk an equivalent `@media`-breakpoint-based mechanism
+   would carry (`qss_core.css` is a real, confirmed 5.16MB today; section 12.1 already flags roughly 32,000
+   responsive-breakpoint rules from that same family of mechanism, though most of the compiled weight is the
+   palette-driven decorative generation per section 13). Rejected anyway, not for cost but for effectiveness: it's
+   advisory only, with a hard, silent cliff at whatever ratio is configured — a window narrower than that is
+   simply unchecked, right back to the original off-canvas-bottom failure. Superseded by tool 1 below, which
+   removes the overflow risk structurally instead of flagging it after the fact.
+
+**The actual fix: three tools, matched to three kinds of content — not one canvas-wide policy.**
+
+### 17.1 Rigid qnt — unchanged, for content that must move together as one image
+Exactly today's system, no change: `qss-pos-x[N]`/`qss-pos-y[N]`/`qss-w[N]`/`qss-h[N]`, all off the single
+canvas-width-derived `--qnt`. Use this for any composition where the relative position between elements *is* the
+point — a toolbar's own internal button spacing, a tightly-grouped cluster, a canvas-grid layout meant to tile
+against siblings. This is section 10's original guarantee ("a canvas shown at half width keeps its contents in
+proportion") and it still holds, exactly, for anything that stays entirely on this axis.
+
+### 17.2 Clamped percentage-of-parent spacing — for selectively elastic gaps, not a canvas-wide replacement
+For spacing that's allowed to flex gracefully rather than hold rigidly — headroom above/below a cluster, the gap
+between two groups, anything closer to a margin than to a structural relationship — express it as a percentage
+of the immediate containing block's actual rendered size (reusing the existing `qss-pos-y-pct[N]`/`qss-h-pct[N]`
+classes, or a new composite adjective wrapping the value in `clamp()` so the elastic range stays bounded, the same
+`clamp(floor, value, cap)` pattern already shipping for `--qnt`'s own extreme-viewport dampening, section 11). The
+analogy that settled this (Kraig, 2026-11-02): the rule of thirds in video framing — a subject's horizontal
+position stays fixed and deliberate, while the headroom above their head is allowed to vary with the frame's actual
+shape, within a visually sane range, without looking broken. The critical distinction from the rejected qnt-split
+(item 1 above): this is applied *selectively*, to values a designer deliberately marks as elastic, not
+*systemically* to every `pos-y`/`h` in the grammar — the rigid skeleton (17.1) stays exactly as proportional as
+it is today; only the chosen gaps breathe.
+
+**Built 2026-11-02.** Not the single 3-param bracket sketched above — that would need every min×pct×max
+combination precompiled, the same combinatorial problem the registry-based `.qss-Button[W|H]` blueprints sidestep
+by being JS-engine-only (confirmed while implementing: `.qss-Button[...]` has no compiled-CSS counterpart at all,
+only a `qss-engine.js` runtime path), which would make a feature this foundational silently do nothing without the
+optional engine loaded. Shipped instead as three composable single-value classes feeding one fixed trigger class,
+each an ordinary `@for`-loop atomic adjective exactly like `qss-pos-y[N]`: `qss-elastic-y-min[N]` and
+`qss-elastic-y-max[N]` set `--qss-ey-min`/`--qss-ey-max` to `calc(N * var(--qnt))`, `qss-elastic-y-pct[N]` sets
+`--qss-ey-pct` to a percentage (same 0.1%-per-unit scale as `*-pct[N]`), and the bare `qss-elastic-y` trigger class
+reads all three into `top: clamp(var(--qss-ey-min, 0px), var(--qss-ey-pct, 0%), var(--qss-ey-max, 0px))`. Fully
+CSS-only, zero JS dependency — the same stack-many-single-purpose-classes idiom the rest of the grammar already
+uses, just applied across four classes on one element instead of one. Verified in a real browser
+(`qss-core-render-check`): a parent resized to 100/300/1000px against `min[20]`/`pct[100]`/`max[80]` produces
+`top` of exactly 20/30/80px — the clamp floors, tracks, and caps against the parent's actual rendered height, not
+just that the math compiles.
+
+### 17.3 Viewport-anchored chrome — for edge-docked functional elements that must never crop
+For content that's genuinely edge-docked and load-bearing — global nav, a file-tree explorer, a toolbar pinned
+to the side (Parapet's layout is the motivating case; the second PWA app's current landing page has none) — don't treat
+it as canvas content at all. Root it in a portal-style layer: `#qss-portal` already is exactly this mechanism
+(`position: fixed; inset: 0`, its own `--qnt` resolved from the *viewport's* `cqw` rather than the canvas's, per the
+existing doc comment in `qss_core.scss`), used today for transient overlays; the same properties make it equally
+suited to persistent structural chrome. Whether persistent chrome shares the literal `#qss-portal` root or gets a
+second, parallel root using the identical pattern (cleaner separation of "ephemeral overlay" from "always-present
+dock," at the cost of one more root) is an open question below, not resolved here.
+
+Inside that layer, three further sub-rules, confirmed in session discussion:
+- **The chrome root's own placement** uses real CSS edges (`top: 0`, `left: 0`, `height: 100vh`, etc.), never qnt
+  position classes — its placement needs no proportional math at all, since it's always exactly at the true edge
+  by definition, at any shape.
+- **Each element's own size** (an icon, a button) stays qnt-based, scaling proportionally with the real viewport
+  — visually consistent with the rest of the UI's scale at any resolution, exactly as canvas content does.
+- **Position within the chrome root** (e.g., "this button cluster sits 70-80% down the nav bar, vertically
+  centered") uses percentage-of-immediate-parent (17.2's mechanism, nested one level deeper) for the band's
+  placement, plus ordinary flexbox (`justify-content: center`/`align-items: center`) for centering within it —
+  both auto-recalculate against the chrome root's actual current size, with no special-casing needed regardless of
+  how tall the real viewport is.
+
+**Open questions for whoever picks this up.**
+- ~~Exact syntax for 17.2's clamped elastic classes~~ — resolved and built 2026-11-02; see the "Built" note above.
+- ~~Whether persistent chrome shares `#qss-portal` with transient overlays or gets its own root~~ — resolved
+  2026-11-02: it shares `#qss-portal`. A second root would only buy anything for one narrow case — keeping chrome
+  visually above the z-index *fallback* overlay path (native top-layer `<dialog>`/`popover` always wins regardless
+  of which root anything lives in, so a second root can't outrank those either way) — and Kraig confirmed there's
+  no scenario where a toolbar should take visual precedence over a modal/popup, which are designed to take over
+  the user's entire attention. So: no second root, no new config key, no new SCSS. The only thing this decision
+  requires, not yet written down anywhere consumer-facing, is the DOM-order contract it depends on — overlay-
+  mounting code must always *append* to `#qss-portal`, never insert at a fixed index, so later-added overlays keep
+  painting over earlier, static chrome (stacking here is pure DOM paint order, no z-index, section 12.9).
+
+  While verifying this, found and fixed a real, pre-existing gap: `qss-engine.js`'s `applyContainerNames` only ever
+  scanned `#qss-canvas`, never `#qss-portal`, so no portal content — existing ephemeral overlays or new persistent
+  chrome — got its automatic container-name, silently breaking Tailwind's named container-query variants
+  (`@sm/<frame-name>:`) on anything rooted there. Not a deliberate canvas-only design: Kraig's framing (2026-11-02)
+  is that the portal is the base for an entire layout's viewport-anchored chrome, not a secondary concern bolted
+  onto the canvas — `#qss-canvas` is for internal elements that mimic a browser window of their own, not for the
+  whole layout. Fixed by widening `applyContainerNames` to scan both roots; covered by a new
+  `qss-engine-render-check` case (an actor inside `#qss-portal` gets its own container-name). The chrome-docking
+  convention and its append-only DOM-order contract are now written up in the README ("Persistent chrome: dock it
+  in the portal root too"), with a `qss-core-render-check` case proving a docked sidebar stays pinned full-height
+  with a qnt-tracking width as the viewport reshapes.
+- Whether `QssNativeAuditor` should gain a rule flagging an actor that mixes qnt position classes with the
+  viewport-anchored chrome pattern (i.e., catches someone reaching for `qss-pos-y[N]` on something that should have
+  been chrome) — a narrower, more clearly-scoped version of the rejected item 4 above, now checking for a
+  category mistake rather than trying to bound an inherently unbounded canvas shape.
+- `qss-aspect[W:H]` (section 16) is unaffected by any of this and remains open on its own merits — it's a
+  per-element intrinsic-ratio concern, orthogonal to which of the three tools above positions or sizes that
+  element.
+
+Not built yet.