qss 0.6.0 → 0.7.0

data/QSS-MANIFESTO.md

@@ -9,12 +9,24 @@ Traditional CSS treats the web as a "Document Stream" where elements flow like i
 **QSS rejects flow.** It treats the screen as a 1000-unit 2D CAD canvas. Every element has a mathematical origin and a predictable footprint.
 
 ### 2. The Deterministic Stack
-To ensure isolation and predictable rendering, QSS requires four things:
+To ensure isolation and predictable rendering, QSS requires three things:
 
 1.  **Stage (`#qss-canvas`)**: The relative-positioned root. All spatial math is relative to this origin. Its id is fixed, so a document has exactly one top-level canvas; nested independent instances belong in separate documents (an iframe), and QSS does not build support for them.
-2.  **Wrapper (`#qss-wrapper`)**: Enforces viewport boundaries and provides a "Safety Gutter."
-3.  **Noun (`id="..."`)**: The unique Identity. Every "Object" on the canvas is a Noun defined by its ID.
-4.  **Actor (`.qss`)**: The mandatory base class (The DNA). It enforces `position: absolute` and a "Nuclear Reset."
+2.  **Noun (`id="..."`)**: The unique Identity. Every "Object" on the canvas is a Noun defined by its ID.
+3.  **Actor (`.qss`)**: The mandatory base class (The DNA). It enforces `position: absolute` and a "Nuclear Reset."
+
+A fourth piece, a `#qss-wrapper` enforcing viewport boundaries with a "Safety Gutter," was dropped from this list
+2026-11-02: it never had an implementing rule, and the gutter it described is incompatible with QSS's full-bleed,
+no-visible-gutter design. See `docs/DESIGN_HISTORY.md` section 15.
+
+**Containment constraint.** Every Actor is also `container-type: inline-size`, for the container-query engine that
+resolves `--qnt`. Per the CSS Containment spec, that implies inline-size containment, which requires the browser to
+compute the Actor's own size as if it had no content -- sizing cannot depend on descendants, because that is exactly
+what would make container queries circular. In practice: **no Actor may ever rely on shrink-to-fit/content-based
+`auto` sizing, in either axis**, in any current or future browser that implements container queries correctly. An
+Actor's width and height must always come from an explicit class; a width- or height-less Actor collapses to the
+Nuclear Reset's `min-width`/`min-height` floor instead of sizing to its content. See `docs/DESIGN_HISTORY.md`
+section 16.
 
 ### 3. Grammar: The "Adjective" System
 Adjectives define the traits, positioning, and state of a Noun.

data/README.md

@@ -1,183 +1,79 @@
 # QSS: Quantized Spatial Styling
 
-QSS is a CSS layout framework built so that both people and AI agents can read a layout from its source, without
-rendering it. Layout is placed and sized on a 1000-unit grid across a **canvas** element: one **qnt** is one
-thousandth of the canvas width, computed by CSS alone. QSS ships compiled CSS, its SCSS sources, an optional
-JavaScript engine, and two **auditors** that check views against QSS's rules. It includes a Rails engine for the
-asset pipeline; the auditors and configuration also work in plain Ruby.
-
-> **Status: 0.x, early.** QSS was extracted from a Rails development tool,
-> which was its first consumer. Expect names and APIs to change before 1.0. See [CHANGELOG.md](CHANGELOG.md).
-> Why QSS is designed this way: [docs/DESIGN_HISTORY.md](docs/DESIGN_HISTORY.md).
-
-## Vocabulary
-
-- **Canvas**: the element QSS measures against, `<div id="qss-canvas">` by default.
-- **Actor**: an element with class `qss` inside the canvas. Actors declare their size; QSS's reset keeps them from
-  shrinking or growing implicitly.
-- **qnt**: the QSS unit, `canvas width / 1000`. `qss-w[240]` means 240 qnt wide: 24% of the canvas, at any screen size.
-- **Noun, adjective, attribute**: an element's `id` is its noun (its identity), its classes are adjectives (its
-  traits), and `qss-function` / `qss-relation` are QSS attributes. See [QSS-MANIFESTO.md](QSS-MANIFESTO.md).
-- **Foreign content**: anything inside class `foreign` (or `qss-payload-override`) is left to ordinary CSS.
-
-## Installation (Rails)
+**A CSS layout system built so AI agents — and the humans reviewing their work — never have to guess.**
+
+## The problem
+
+Ask an AI coding agent to move a button 10 pixels left. Watch it struggle. CSS gives it five or six different ways
+to control position — margin, padding, a flex order, a grid column, a transform — and nothing says which one is
+actually in charge on this particular page. It guesses, edits the wrong one, and something else quietly shifts. It
+reports the change as done. The page is now broken.
+
+## The fix
+
+QSS removes the guessing by removing the agent's choice. Every element's position and size is **one explicit number**, not
+a tug-of-war between competing properties. Those numbers share a single unit — a **qnt**, 1/1000th of the layout's
+own width, computed in pure CSS — so the same edit holds its exact proportion at any screen size: a phone, a
+laptop, a 4K display. No breakpoints. No media queries. No separate rules to keep in sync. Move something once,
+and it stays put, everywhere.
+
+## Why teams adopt it
+
+- **One number, not a tug-of-war.** Position and size are each a single explicit value; nothing else can quietly
+  override them.
+- **Scales without breakpoints.** The same markup looks right on a phone and a monitor, because the unit is a
+  fraction of the layout's own width, not a fixed pixel count.
+- **Proof, not vibes.** Two built-in auditors flag violations automatically (RED is broken, ORANGE is a judgment
+  call), and a real-headless-browser render check confirms the compiled CSS actually renders as intended — a
+  passing lint rule isn't the same as watching it work.
+- **Works with zero JavaScript.** The compiled CSS alone is fully functional. An optional JS engine adds a few
+  runtime conveniences on top; it's never required.
+- **Plays nice with your design system.** QSS only ever owns position, size and structure. Tailwind or anything
+  else still owns color, type and visual polish — and the auditor flags it if a content framework strays into
+  QSS's territory.
+- **Built full-bleed by default.** Apps that must fill any real window shape, at any size, with zero per-project
+  configuration — no letterboxed gutters, no guessing which breakpoint you're in.
+- **Battle-tested, not theoretical.** Extracted from a real production Rails tool that still runs on it today.
+- **Transparent by design.** Every major decision — including the ones that didn't work — is recorded in
+  [docs/DESIGN_HISTORY.md](docs/DESIGN_HISTORY.md), so you can see exactly *why* QSS looks the way it does, not
+  just that it does.
+
+> **Status: 0.x, early.** Expect names and APIs to change before 1.0. See [CHANGELOG.md](CHANGELOG.md).
+
+## Quick reference
+
+| Term | Meaning |
+|---|---|
+| **Canvas** | The element QSS measures against: `<div id="qss-canvas">`, fixed and singular per document. |
+| **Actor** | Any element with class `qss` inside the canvas (or the overlay portal). Declares its own size; QSS's reset stops it shrinking or growing implicitly. |
+| **qnt** | The QSS unit: `canvas width / 1000`. `qss-w[240]` is 240 qnt wide — 24% of the canvas, at any screen size. |
+| **Noun / Adjective / Attribute** | An element's `id` is its noun (identity); its classes are adjectives (traits); `qss-function`/`qss-relation` are attributes. See [QSS-MANIFESTO.md](QSS-MANIFESTO.md). |
+| **Portal** | `#qss-portal` by default: a fixed, viewport-sized layer outside the canvas, for overlays and viewport-anchored chrome (nav bars, toolbars). |
+| **Foreign content** | Anything inside class `foreign` (or `qss-payload-override`) — left to ordinary CSS entirely. |
+
+## 60-second start
 
 ```ruby
 # Gemfile
 gem "qss"
 ```
 
-The gem's Rails engine puts QSS's assets on your asset pipeline (`qss/qss_core.css`, `qss/qss_core.scss`,
-`qss/qss-engine.js`).
-
-### Markup
-
-The canvas id is fixed: `#qss-canvas` is not configurable, so a document has exactly one top-level QSS canvas.
-Two independent QSS instances nested in the same page would collide on it; isolate them in separate documents (for
-example an `<iframe>`) instead. This is a known constraint, not something QSS will build support for.
-
-An id is `{qualifier}-{baseObject}`: the base object is an HTML tag, the qualifier says which one. A qualifier is
-declared once in your registry, recording what it adds to its base. Structural frames (`nav`, `main`, ...) carry
-`qss-contain-layout`.
-
-```erb
-<div id="qss-canvas">
-  <nav id="main-nav" class="qss qss-relative qss-contain-layout qss-w[200] qss-h-full"> ... </nav>
-  <section id="content-section" class="qss qss-relative qss-contain-layout qss-w[800] qss-h-full"> ... </section>
-</div>
-```
-
-```yaml
-# config/qss_registry.yml (auditor.registry_path in your config, below)
-types:
-  main-nav:
-    extends: nav
-  content-section:
-    extends: section
-```
-
-This example audits green with `QSS::QssNativeAuditor` (below).
-
-### Stylesheet: neutral defaults
-
 ```erb
+<%# app/views/layouts/application.html.erb %>
 <%= stylesheet_link_tag "qss/qss_core" %>
-```
 
-### Stylesheet: with your own settings
-
-Set your values first, then import core; core's settings are `!default`, so yours win. Put
-`QSS.stylesheets_path` on your Sass load path so `qss/qss_core` resolves:
-
-```scss
-// app/assets/stylesheets/application.scss
-@import "qss_variables";   // generated from your config by qss-sync (below)
-@import "qss/qss_core";
-```
-
-```ruby
-Sass.compile("app/assets/stylesheets/application.scss",
-             load_paths: ["app/assets/stylesheets", QSS.stylesheets_path])
-```
-
-### The JavaScript engine (optional)
-
-The compiled CSS works on its own. The engine adds rules at runtime for bracket classes the compiled CSS does not
-cover, exports measured element edges as CSS variables, and names each actor's CSS container after its own id
-(`container-name`, so Drywall content inside a frame can use a named container-query variant, such as Tailwind's
-`@sm/<frame-name>:`, to react to that specific frame's own width -- DESIGN_HISTORY #12.5). Every actor is already a
-size container without the engine (`container-type: inline-size`, a static default); only the name needs an id,
-which CSS can't read into an arbitrary property on its own.
-
-```erb
-<%= javascript_include_tag "qss/qss-engine", defer: true %>
-<script>
-  document.addEventListener("DOMContentLoaded", () => { QSSEngine.startPulse(); QSSEngine.startObserver(); });
-</script>
-```
-
-While developing, `QSSEngine.auditPositioning()` lists every element that is `position: fixed` or `sticky` without QSS
-owning it, which no static check can see (a Drywall `fixed` utility only becomes a position once a stylesheet resolves
-it). Frames, the overlay portal, `foreign` content and the browser's native top layer are exempt. It runs only when
-you call it, and `QSSEngine.setPortal("#qss-overlays")` tells it where your portal root is if it isn't `#qss-portal`.
-
-## Configuration
-
-QSS starts neutral. A project declares its own settings in one YAML file and tells QSS where it is:
-
-```ruby
-# config/initializers/qss.rb
-QSS.configure(root: Rails.root, config: "config/qss_config.yml")
-```
-
-```yaml
-# config/qss_config.yml -- every key is optional; see the gem's config/grammar.yml for the defaults
-config:
-  portal_root: "#qss-portal"        # overlays render here (any one #id; default #qss-portal); "" = rules scoped to the canvas only
-  palette:
-    brand-main: "#0f1115"
-  group_names: [menu]               # named groups for group-*:hover style classes
-auditor:
-  id_prefix: "app-"                  # optional project id prefix
-  registry_path: "config/qss_registry.yml"
-sync_targets:
-  variables: app/assets/stylesheets/_qss_variables.scss
-```
-
-Relative paths resolve against the declared `root`, never the working directory.
-
-### Generating your SCSS settings
-
-```sh
-QSS_CONSUMER_CONFIG=config/qss_config.yml bundle exec qss-sync
+<div id="qss-canvas">
+  <nav id="main-nav" class="qss qss-contain-layout qss-pos-x[0] qss-w[200] qss-h-full"> ... </nav>
+  <section id="content-section" class="qss qss-contain-layout qss-pos-x[200] qss-w[800] qss-h-full"> ... </section>
+</div>
 ```
 
-This writes your `_qss_variables.scss` (the `sync_targets.variables` path). Without `QSS_CONSUMER_CONFIG` it reads
-`config/qss_config.yml` from the current directory.
-
-## Auditing views
-
-```ruby
-result = QSS::QssNativeAuditor.audit_file("app/views/layouts/application.html.erb")
-result[:status] # => "green", "orange" or "red"
-result[:issues] # => [{ type:, message:, severity: }, ...] (plus code: on most identity and unit findings)
-```
+That's a complete, working QSS layout: no JavaScript, no media queries, no breakpoints. `main-nav` sits flush
+against the canvas's left edge and is exactly 20% of its width; `content-section` starts exactly where `main-nav`
+ends and fills the remaining 80% — at any screen size, from a phone to a 4K display.
 
-RED means a rule is violated: fix the markup, or reconsider the rule. ORANGE is a judgment call. Examples of rules:
-every actor declares its width and height (or opts out with `qss-content-driven`); structure carries no raw CSS
-lengths (sizes are in qnt or canvas percentages); no `!important`; ids follow the `{qualifier}-{baseObject}`
-grammar; every class literally resolves to a rule in the compiled stylesheet, not just a known shape; a `qss`-marked
-actor carries no class (from a content framework such as Tailwind) that resolves, in `auditor.drywall_stylesheet_path`,
-to a rule setting a structural property (`display`, `position`, sizing, `flex*`/`grid*`, `gap`, `z-index`, `order`)
--- checked by CSS property, so it works for any content framework with no fork.
-`QSS::QssAuditor` is the older class-whitelist auditor: it predates the bracket vocabulary (it reports `qss-w[200]`
-as unknown) and is kept for projects that still use its whitelist.
-
-**Three tiers of stylesheet.** Class resolution reads core's own `qss_core.css` (always, verified against the manifest
-shipped with the gem, `QSS::CoreIntegrityError` on a mismatch), any sealed tool stylesheets
-(`auditor.tool_stylesheets`, sealed by the tool's build with `qss-seal`, `QSS::ToolIntegrityError`), and the host's
-own output (`auditor.host_stylesheets`, `stylesheet_path`, `QSS.configure(host_stylesheets: -> { ... })`; a Rails host
-defaults to `app/assets/builds/*.css`).
-
-Appearance classes (colors, type styling, shadows, filters) are **deprecated** as of 0.2.0: the auditor reports each as
-orange `deprecated_decorative`, since appearance belongs to whatever fills Drywall; QSS's quantized bracket scale
-(`qss-border[2]`, `qss-text-size[14]`) is unaffected. A Drywall stylesheet compiled with the `qss` prefix is a red
-`drywall_prefix_collision`. Frames stay out of `z-index` entirely.
-
-**Overlays: use the native top layer.** The portal root is the element whose id is your configured `portal_root`
-(any one `#id` selector; `#qss-portal` when none is set), matched exactly: no prefix or substring guessing.
-Core gives it its own geometry (a fixed, viewport-sized layer, `pointer-events: none` on the root and `auto` on its
-direct children, `--qnt` resolved on its children as on the canvas), so write no QSS classes on the root itself, which
-match nothing there, and place it after the canvas in the document so it paints above it without a `z-index`. A modal, dialog, menu or popover belongs outside the canvas, in the overlay
-portal root, and should be a `<dialog>` opened with `showModal()` or carry the `popover` attribute: the browser then
-renders it above everything with no `z-index` at all. A plain element placed directly in the portal root is the
-fallback path. It is allowed, but the auditor reports it as orange `top_layer_preferred` until you mark it
-`qss-overlay-fallback`. A `z-index` is permitted only on the portal root and inside it (to order one fallback overlay
-above another, or by DOM order alone); anywhere else Portal Integrity makes it red.
-
-Every QSS class is prefixed `qss-` (SETTLED 2026-10-17, DESIGN_HISTORY #12): QSS owns structure/positioning
-exclusively, and any content framework sharing the same canvas (Tailwind or otherwise) must not be able to mistake
-its own unprefixed utility classes for QSS's.
+For configuration, the optional JS engine, the two auditors, and the overlay/persistent-chrome conventions, see
+**[docs/HOWTO.md](docs/HOWTO.md)** — the full step-by-step guide.
 
 ## Requirements
 

data/app/assets/javascripts/qss/qss-engine.js

@@ -60,6 +60,10 @@ const QSSEngine = (function() {
         'qss-cursor-pointer',
         'qss-cursor-row-resize',
         'qss-dev-border',
+        'qss-elastic-y',
+        'qss-elastic-y-max',
+        'qss-elastic-y-min',
+        'qss-elastic-y-pct',
         'qss-ergonomic-override',
         'qss-evenly',
         'qss-fixed',
@@ -333,14 +337,20 @@ const QSSEngine = (function() {
      * needs an id, which CSS can't read into an arbitrary property on its own. Skips an actor whose container-name
      * is already set by anything (a future static/declarative path), checked by computed value so an inline style
      * or any stylesheet rule both count, not just a prior run of this same function.
+     *
+     * Covers both the canvas and the overlay portal root (DESIGN_HISTORY #17.3): the portal is not a secondary
+     * concern bolted onto the canvas, it is where an entire layout's viewport-anchored chrome lives, so its actors
+     * need the same named container-query support canvas frames get. Found missing 2026-11-02 while verifying the
+     * chrome-docking pattern -- it had simply never been extended there, not a deliberate canvas-only scope.
      */
     function applyContainerNames() {
-        const anchor = document.querySelector(anchorSelector);
-        if (!anchor) return;
-        anchor.querySelectorAll('.qss[id]').forEach(actor => {
-            if (getComputedStyle(actor).containerName === 'none') {
-                actor.style.containerName = actor.id;
-            }
+        [ document.querySelector(anchorSelector), document.querySelector(portalSelector) ].forEach(root => {
+            if (!root) return;
+            root.querySelectorAll('.qss[id]').forEach(actor => {
+                if (getComputedStyle(actor).containerName === 'none') {
+                    actor.style.containerName = actor.id;
+                }
+            });
         });
     }