qss 0.1.1 → 0.1.3

data/app/assets/stylesheets/qss/qss_core.scss

@@ -10,11 +10,20 @@
 /* The QSS unit (qnt): one thousandth of the canvas width, computed by CSS alone. The canvas is a size container
    and each of its children declares --qnt as 0.1cqw; registered as a <length>, it resolves there once and
    inherits unchanged, so every descendant measures against its canvas, never a nearer container. Outside a
-   canvas (e.g. an overlay portal at the document root) the unit approximates from the viewport width. */
+   canvas (e.g. an overlay portal at the document root) the unit approximates from the viewport width.
+
+   Ultra-wide/extreme-resolution dampening (SETTLED 2026-10-17): clamped between the qnt value at a real
+   narrow-mobile CSS viewport width (floor) and just past a maximized 1440p/27" monitor (cap), so ordinary
+   desktop widths scale freely and only genuine ultra-wide/high-res canvases -- or genuine phone-narrow ones --
+   get dampened. Beyond the cap, every structural dimension stays fixed regardless of how much wider the canvas
+   gets; extra width becomes more usable space, not bigger borders/gaps/padding. See docs/DESIGN_HISTORY.md #11. */
 @property --qnt { syntax: "<length>"; inherits: true; initial-value: 1px; }
 
+$qss-dampen-floor: map-get($qss-dampen-scale, "floor-width") * 0.001 * 1px;
+$qss-dampen-cap: map-get($qss-dampen-scale, "cap-width") * 0.001 * 1px;
+
 :root {
-  --qnt: 0.1vw;
+  --qnt: clamp(#{$qss-dampen-floor}, 0.1vw, #{$qss-dampen-cap});
   /* Item 3: pure-CSS linear content unit, no JS, no clamp. Only icon-size[N] uses
      this today -- see the content_scale note in _qss_variables.scss. */
   --u: calc(100vw / #{map-get($qss-content-scale, "calibration-width")});
@@ -63,7 +72,7 @@ html, body {
   background-color: transparent;
   box-sizing: border-box;
 
-  > * { --qnt: 0.1cqw; }
+  > * { --qnt: clamp(#{$qss-dampen-floor}, 0.1cqw, #{$qss-dampen-cap}); }
 
   /* The Base Nature of a Spatial Actor — ONLY inside the stage.
      :where() keeps this reset at the anchor's weight alone, (1,0,0): below every core utility, which is
@@ -413,9 +422,16 @@ $qss-scope: if($qss-portal-root == "", $qss-anchor, "#{$qss-anchor}, #{$qss-port
 @include qss-dsl-boost(".contain") { object-fit: contain; }
 
 /* Layout containment for structural frames: the class the README documents and the native auditor mandates on
-   frames whose id names a structural word (header, nav, sidebar, ...). Both spellings the auditor accepts. */
-@include qss-dsl-boost(".contain-layout")     { contain: layout; }
-@include qss-dsl-boost(".qss-contain-layout") { contain: layout; }
+   frames whose id names a structural word (header, nav, sidebar, ...). Both spellings the auditor accepts.
+   Clips paint by default too (SETTLED 2026-10-17): `contain: layout` alone isolates layout math but not paint, so
+   a frame's overflow could still cover its neighbours -- the exact gap DESIGN_HISTORY #11 named. Anything that
+   needs to visually escape a frame on purpose (tooltips, dropdowns, modals) already goes through the portal
+   (z-index outside it is its own red violation), so this does not reopen that case; qss-paint-override is the
+   escape hatch for the rare frame that wants decorative overflow (a shadow, a hover scale) without the portal. */
+@include qss-dsl-boost(".contain-layout")     { contain: layout paint; }
+@include qss-dsl-boost(".qss-contain-layout") { contain: layout paint; }
+@include qss-dsl-boost(".contain-layout.qss-paint-override")     { contain: layout; }
+@include qss-dsl-boost(".qss-contain-layout.qss-paint-override") { contain: layout; }
 @include qss-dsl-boost(".cover")   { object-fit: cover; }
 
 /* Visual Atmosphere */
@@ -598,10 +614,10 @@ $qss-accent-states: (
 @each $bp-name, $bp-width in $qss-breakpoints {
   @media (min-width: #{$bp-width}) {
     @for $i from 0 through map-get($qss-quantization, "units") {
-      .qss-#{$bp-name}\:w-pct\[#{$i}\] { width: #{$i * 0.1}%; }
-      .qss-#{$bp-name}\:h-pct\[#{$i}\] { height: #{$i * 0.1}%; }
-      .qss-#{$bp-name}\:pos-x-pct\[#{$i}\] { left: #{$i * 0.1}%; }
-      .qss-#{$bp-name}\:pos-y-pct\[#{$i}\] { top: #{$i * 0.1}%; }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:w-pct\\[#{$i}\\]") { width: percentage($i * 0.001); }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:h-pct\\[#{$i}\\]") { height: percentage($i * 0.001); }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:pos-x-pct\\[#{$i}\\]") { left: percentage($i * 0.001); }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:pos-y-pct\\[#{$i}\\]") { top: percentage($i * 0.001); }
     }
   }
 }
@@ -610,10 +626,10 @@ $qss-accent-states: (
 @each $bp-name, $bp-height in $qss-vertical-breakpoints {
   @media (min-height: #{$bp-height}) {
     @for $i from 0 through map-get($qss-quantization, "units") {
-      .qss-#{$bp-name}\:w-pct\[#{$i}\] { width: #{$i * 0.1}%; }
-      .qss-#{$bp-name}\:h-pct\[#{$i}\] { height: #{$i * 0.1}%; }
-      .qss-#{$bp-name}\:pos-x-pct\[#{$i}\] { left: #{$i * 0.1}%; }
-      .qss-#{$bp-name}\:pos-y-pct\[#{$i}\] { top: #{$i * 0.1}%; }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:w-pct\\[#{$i}\\]") { width: percentage($i * 0.001); }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:h-pct\\[#{$i}\\]") { height: percentage($i * 0.001); }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:pos-x-pct\\[#{$i}\\]") { left: percentage($i * 0.001); }
+      @include qss-dsl-boost(".qss-#{$bp-name}\\:pos-y-pct\\[#{$i}\\]") { top: percentage($i * 0.001); }
     }
   }
 }

data/config/grammar.yml

@@ -132,6 +132,7 @@ adjectives:
     - qss-legibility-override
     - qss-ergonomic-override
     - qss-payload-override
+    - qss-paint-override
     - qss-dampen-scaling
     - qss-content-driven
 
@@ -214,6 +215,18 @@ config:
   content_scale:
     calibration_width: 1440
 
+  # Structural unit dampening (SETTLED 2026-10-17). --qnt is 0.1cqw of the canvas with no
+  # bound of its own; clamped between the qnt value at floor_width (a real narrow-mobile
+  # CSS viewport width -- phones report this regardless of physical/FHD+/QHD+ panel
+  # resolution, since cqw/vw only ever see CSS pixels) and at cap_width (just past a
+  # maximized 1440p/27" monitor, so ordinary wide desktops scale freely and real ultra-wide
+  # monitors, 3440px and up, are the ones dampened). Beyond cap_width, every structural
+  # dimension stays fixed regardless of how much wider the canvas gets -- extra width
+  # becomes more usable space, not bigger borders/gaps/padding.
+  dampen_scale:
+    floor_width: 390
+    cap_width: 3200
+
   # Named-group registry for group-{state}/{name} relational classes. Consumer-supplied.
   group_names: []
 
@@ -253,6 +266,13 @@ auditor:
   # native auditor. Relative to the process working directory. Empty = no registry (an empty vocabulary).
   registry_path: ""
 
+  # The compiled stylesheet the native auditor checks every class against (SETTLED 2026-10-17): a class must
+  # literally appear in some selector here, not just match a known shape (the 2026-09-21 census found ~29% of
+  # real class tokens resolved to no CSS at all while both auditors reported green). Empty = core's own
+  # qss_core.css; a consumer normally points this at its own compiled output (core + its overrides), which is
+  # what its markup actually renders against.
+  stylesheet_path: ""
+
 # Files exe/qss-sync generates into. core_variables, engine, auditor and native_auditor are core's own files,
 # relative to core's root; variables is the consumer's, relative to the directory the sync is run from, and a consumer
 # normally sets it in its own config file. (Keeps file locations out of the script itself.)

data/exe/qss-core-render-check

@@ -32,6 +32,12 @@ HTML = <<~HTML
     <div id="padded" class="qss p[4]"></div>
     <div id="contained" class="qss contain-layout"></div>
     <div id="contained-prefixed" class="qss qss-contain-layout"></div>
+    <div id="clip-frame" class="qss w[100] h[50] contain-layout" style="position: relative;">
+      <div id="clip-overflow" class="qss" style="position: absolute; left: 150px; top: 0; width: 20px; height: 20px;"></div>
+    </div>
+    <div id="override-frame" class="qss w[100] h[50] contain-layout qss-paint-override" style="position: relative;">
+      <div id="override-overflow" class="qss" style="position: absolute; left: 150px; top: 0; width: 20px; height: 20px;"></div>
+    </div>
     <div id="host" class="qss host-static"></div>
     <div class="foreign"><div id="in-foreign" class="qss"></div></div>
     <div id="nearer-container" class="qss w[100] h[10]" style="container-type: inline-size"><div id="deep" class="qss"></div></div>
@@ -51,8 +57,9 @@ CHECKS = [
   [ "flex-1 beats the reset's flex-shrink",           "flex1",        "flex",           "1 1 0%" ],
   [ "p[N] beats the reset (4 units on a 1000px canvas)", "padded", "padding",           "4px" ],
   [ "a host app's plain class does not override structure", "host", "position",        "absolute" ],
-  [ "contain-layout gives layout containment",          "contained",          "contain",        "layout" ],
-  [ "qss-contain-layout gives layout containment",      "contained-prefixed", "contain",        "layout" ],
+  [ "contain-layout gives layout and paint containment", "contained",          "contain",        "layout paint" ],
+  [ "qss-contain-layout gives layout and paint containment", "contained-prefixed", "contain",   "layout paint" ],
+  [ "qss-paint-override restores layout-only containment", "override-frame",   "contain",        "layout" ],
   [ "a bare actor has no containment",                  "bare",               "contain",        "none" ],
   [ "foreign content is left alone",                  "in-foreign",   "position",       "static" ]
 ].freeze
@@ -80,10 +87,34 @@ Dir.mktmpdir do |dir|
       puts format("%-4s %-56s %s=%s%s", ok ? "ok" : "FAIL", label, prop, actual, ok ? "" : " (expected #{expected})")
     end
 
+    # Real visual proof that paint containment actually clips, not just that getComputedStyle says "paint": the
+    # overflow child sits past its frame's right edge (frame is 100px wide; the child is at left:150px), so
+    # elementFromPoint at that spot hits the clipped-away child only when painting isn't actually contained.
+    hit = lambda do |frame_id, overflow_id|
+      driver.execute_script(<<~JS, frame_id, overflow_id)
+        const rect = document.getElementById(arguments[0]).getBoundingClientRect();
+        const el = document.elementFromPoint(rect.left + 160, rect.top + 10);
+        return !!el && el.id === arguments[1];
+      JS
+    end
+    [
+      [ "contain-layout actually clips an overflowing child's paint", "clip-frame", "clip-overflow", false ],
+      [ "qss-paint-override actually lets an overflowing child paint through", "override-frame", "override-overflow", true ]
+    ].each do |label, frame_id, overflow_id, expected|
+      actual = hit.(frame_id, overflow_id)
+      ok = actual == expected
+      total += 1
+      failures += 1 unless ok
+      puts format("%-4s %-56s hit=%s%s", ok ? "ok" : "FAIL", label, actual, ok ? "" : " (expected #{expected})")
+    end
+
     # The unit: one thousandth of the canvas width, from CSS alone, measured against the canvas even inside a nearer
     # size container; outside a canvas it approximates from the viewport.
     qnt = ->(id) { driver.execute_script("return getComputedStyle(arguments[0] ? document.getElementById(arguments[0]) : document.documentElement).getPropertyValue('--qnt').trim()", id) }
-    [ [ 1000, "1px" ], [ 1500, "1.5px" ] ].each do |width, expected|
+    # 300px and 5000px fall outside the dampening clamp's 390px-3200px range (DESIGN_HISTORY #11): unclamped they'd
+    # be 0.3px and 5px, so seeing 0.39px/3.2px instead proves the floor/cap actually engage, not just that the
+    # unclamped math is right.
+    [ [ 1000, "1px" ], [ 1500, "1.5px" ], [ 300, "0.39px" ], [ 5000, "3.2px" ] ].each do |width, expected|
       driver.execute_script("document.getElementById('qss-canvas').style.width = arguments[0] + 'px'", width)
       [ [ "canvas child", "bare" ], [ "element inside a nearer container", "deep" ] ].each do |where, id|
         actual = qnt.(id)

data/exe/qss-sync

@@ -142,6 +142,11 @@ def scss_variables(config, header, default)
   #{scss_scale.(config['content_scale'])}
   )#{d};
 
+  /* Structural unit dampening (SETTLED 2026-10-17). */
+  $qss-dampen-scale: (
+  #{scss_scale.(config['dampen_scale'])}
+  )#{d};
+
   /* Named-group registry (consumer-supplied). */
   $qss-group-names: (#{(config['group_names'] || []).map { |n| "\"#{n}\"" }.join(", ")})#{d};
 

data/lib/qss/configuration.rb

@@ -53,6 +53,7 @@ module QSS
       portal = data.dig("config", "portal_root")
       settings["portal_root"] = portal.to_s unless portal.nil?
       settings["registry_path"] = resolve(settings["registry_path"])
+      settings["stylesheet_path"] = resolve(settings["stylesheet_path"])
       settings.freeze
     end
 

data/lib/qss/qss_auditor.rb

@@ -81,6 +81,7 @@ module QSS
       'qss-dampen-scaling',
       'qss-ergonomic-override',
       'qss-legibility-override',
+      'qss-paint-override',
       'qss-payload-override',
       'relative',
       'resize',
@@ -121,7 +122,7 @@ module QSS
 
     PAYLOAD_TAGS = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "span", "label", "blockquote", "li"].freeze
 
-    ADJECTIVE_CATEGORIES = {"positional"=>["detached", "floating", "stuck", "absolute", "pos-x", "pos-y", "pos-r", "pos-b", "pos"], "flow_relative"=>["anchored", "relative"], "layout"=>["vertical", "horizontal", "centered", "v-mid", "h-mid", "v-start", "v-end", "h-start", "h-end", "spaced", "around", "evenly", "flex", "flex-col", "flex-row", "flex-wrap", "flex-nowrap", "flex-1", "flex-auto", "flex-none", "items-center", "justify-center", "justify-between", "grid", "table-fixed", "contain-layout", "w-full", "h-full", "w-f", "h-f"], "typographic"=>["italic", "uppercase", "lowercase", "underline", "nowrap", "truncate", "font-mono", "font-sans", "font-medium", "font-bold", "font-black", "text-size", "leading", "tracking", "tracking-tighter", "tracking-wide", "tracking-wider", "tracking-widest", "icon-size"], "visual"=>["bg", "border", "border-t", "border-b", "border-l", "border-r", "rounded", "rounded-full", "shadow", "opacity", "blur", "bright", "contrast", "grayscale", "hue", "invert", "saturate", "sepia", "blend", "contain", "cover", "visible", "invisible", "bg-alpha", "border-alpha", "text-alpha"], "interactive"=>["clickable", "smooth", "busy", "ghost", "unselectable", "scroll-smooth", "scroll", "cursor-col-resize", "cursor-row-resize", "transition-all", "transition-colors", "transition-none", "ring", "resize", "outline-none"], "internal"=>["qss", "dev-border", "group", "foreign", "qss-legibility-override", "qss-ergonomic-override", "qss-payload-override", "qss-dampen-scaling", "qss-content-driven"]}.freeze
+    ADJECTIVE_CATEGORIES = {"positional"=>["detached", "floating", "stuck", "absolute", "pos-x", "pos-y", "pos-r", "pos-b", "pos"], "flow_relative"=>["anchored", "relative"], "layout"=>["vertical", "horizontal", "centered", "v-mid", "h-mid", "v-start", "v-end", "h-start", "h-end", "spaced", "around", "evenly", "flex", "flex-col", "flex-row", "flex-wrap", "flex-nowrap", "flex-1", "flex-auto", "flex-none", "items-center", "justify-center", "justify-between", "grid", "table-fixed", "contain-layout", "w-full", "h-full", "w-f", "h-f"], "typographic"=>["italic", "uppercase", "lowercase", "underline", "nowrap", "truncate", "font-mono", "font-sans", "font-medium", "font-bold", "font-black", "text-size", "leading", "tracking", "tracking-tighter", "tracking-wide", "tracking-wider", "tracking-widest", "icon-size"], "visual"=>["bg", "border", "border-t", "border-b", "border-l", "border-r", "rounded", "rounded-full", "shadow", "opacity", "blur", "bright", "contrast", "grayscale", "hue", "invert", "saturate", "sepia", "blend", "contain", "cover", "visible", "invisible", "bg-alpha", "border-alpha", "text-alpha"], "interactive"=>["clickable", "smooth", "busy", "ghost", "unselectable", "scroll-smooth", "scroll", "cursor-col-resize", "cursor-row-resize", "transition-all", "transition-colors", "transition-none", "ring", "resize", "outline-none"], "internal"=>["qss", "dev-border", "group", "foreign", "qss-legibility-override", "qss-ergonomic-override", "qss-payload-override", "qss-paint-override", "qss-dampen-scaling", "qss-content-driven"]}.freeze
 
     ILLEGAL_COMBOS = [{"tag_in"=>"payload_tags", "forbid_category"=>"positional", "severity"=>"red", "message"=>"Protocol Violation: Payload tags (<tag>) cannot carry flow-breaking positional adjectives. Use a wrapping <div> Frame.", "escape_hatch"=>"qss-payload-override"}].freeze
 
@@ -133,7 +134,7 @@ module QSS
 
     DEPTHS = {"canvas"=>0, "content"=>100, "ui"=>500, "overlay"=>900, "modal"=>1000}.freeze
 
-    AUDITOR_CONFIG = {"id_prefix"=>"", "structural_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "narrow_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "icon_prefixes"=>[], "registry_path"=>"", "portal_root"=>""}.freeze
+    AUDITOR_CONFIG = {"id_prefix"=>"", "structural_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "narrow_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "icon_prefixes"=>[], "registry_path"=>"", "stylesheet_path"=>"", "portal_root"=>""}.freeze
     # QSS-GENERATED-END
     # rubocop:enable all
 

data/lib/qss/qss_native_auditor.rb

@@ -1,5 +1,6 @@
 require 'nokogiri'
 require 'yaml'
+require 'set'
 
 module QSS
   class QssNativeAuditor
@@ -8,7 +9,7 @@ module QSS
     # GENERATED FROM grammar.yml - DO NOT EDIT
     PAYLOAD_TAGS = ["p", "h1", "h2", "h3", "h4", "h5", "h6", "span", "label", "blockquote", "li"].freeze
 
-    AUDITOR_CONFIG = {"id_prefix"=>"", "structural_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "narrow_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "icon_prefixes"=>[], "registry_path"=>"", "portal_root"=>""}.freeze
+    AUDITOR_CONFIG = {"id_prefix"=>"", "structural_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "narrow_words"=>["header", "footer", "sidebar", "workspace", "main", "panel", "frame", "wrapper", "nav", "aside"], "icon_prefixes"=>[], "registry_path"=>"", "stylesheet_path"=>"", "portal_root"=>""}.freeze
     # QSS-GENERATED-END
     # rubocop:enable all
 
@@ -273,10 +274,34 @@ module QSS
         found
       end
 
+      # Two opposite insets on a positioned element pin both its edges on that axis, fixing its size exactly even
+      # with no width/height class at all (SETTLED 2026-10-17, revisiting the 2026-09-24 deferral now that flex and
+      # Tailwind's boundary are settled -- DESIGN_HISTORY #12). pos-x[N]+pos-r[N] (left+right) fix width;
+      # pos-y[N]+pos-b[N] (top+bottom) fix height. Bare native and qss- forms both count, same normalization as
+      # from_classes above.
+      INSET_SIDES = { 'width' => %w[pos-x pos-r], 'height' => %w[pos-y pos-b] }.freeze
+
+      def self.inset_declared?(classes, axis)
+        bases = classes.map { |c| c.sub(/\Aqss-/, '')[/\A[a-z-]+(?=\[)/] }.compact
+        INSET_SIDES.fetch(axis).all? { |side| bases.include?(side) }
+      end
+
+      # flex-1/flex-auto (flex: 1 1 0%/1 1 auto) fixes a flex item's size exactly, but only on the flex
+      # container's MAIN axis -- the cross axis is untouched by it and still needs its own answer. Which axis is
+      # main depends on the PARENT's own classes: .vertical is flex-direction: column (main = height); .flex or
+      # .horizontal, with no .vertical, is row, CSS's own default (main = width). No flex parent at all means
+      # flex-1 fixes nothing here: never guess which axis it would have covered.
+      def self.main_axis(parent_classes)
+        return nil unless parent_classes.any? { |c| %w[flex horizontal vertical].include?(c) }
+        parent_classes.include?('vertical') ? 'height' : 'width'
+      end
+
       # The axes an element's classes leave undeclared, width before height (empty when both are declared).
-      def self.missing_axes(classes)
+      # parent_classes is the flex container's own classes, if any, used only to resolve flex-1/flex-auto.
+      def self.missing_axes(classes, parent_classes: [])
         found = from_classes(classes)
-        %w[width height].reject { |axis| found.key?(axis) }
+        flexed = (classes.include?('flex-1') || classes.include?('flex-auto')) ? main_axis(parent_classes) : nil
+        %w[width height].reject { |axis| found.key?(axis) || inset_declared?(classes, axis) || axis == flexed }
       end
 
       def self.describe(fact)
@@ -378,6 +403,54 @@ module QSS
       end
     end
 
+    # The class-must-resolve check (item 4, SETTLED 2026-10-17): the 2026-09-21 census found about 29 percent of
+    # real class tokens resolved to no CSS at all while both auditors reported green, because they only checked a
+    # class's SHAPE (does it look like a known pattern), never whether a rule for it actually exists. This checks
+    # the compiled stylesheet directly: a class must literally appear in some selector in it.
+    module Stylesheet
+      CACHE = {}
+      # Core's own compiled CSS, used when a consumer configures no stylesheet_path (auditor.stylesheet_path).
+      CORE_CSS_PATH = File.expand_path('../../app/assets/stylesheets/qss/qss_core.css', __dir__)
+
+      # Deliberately CSS-free: behavioral flags this auditor (or the older whitelist auditor) reads from the class
+      # list itself, never meant to carry a rule. qss and foreign happen to appear inside compound selectors in
+      # core's own reset (:where(.qss:not(.foreign *))), but that is an accident of how the reset is written, not
+      # a guarantee -- a consumer's own compiled stylesheet may not repeat it verbatim, so both are listed
+      # explicitly rather than left to resolve by coincidence. group and dev-border are not here: group is real
+      # selector vocabulary (the ancestor half of every group-variant rule, .group:hover ...), and dev-border has
+      # its own standalone rule -- both are supposed to be found in the stylesheet, not exempted from looking.
+      MARKER_CLASSES = %w[qss foreign qss-legibility-override qss-ergonomic-override qss-payload-override
+                           qss-dampen-scaling qss-content-driven].freeze
+
+      # One class token: a run of escaped-pair (\X, however Sass escaped it: \:, \[, \], \/, \.) or plain identifier
+      # characters. Stops at the first unescaped character outside that set -- a real pseudo-class like :hover
+      # that follows a QSS class in the same compound selector, never part of the class name itself.
+      CLASS_TOKEN = /\.((?:\\.|[A-Za-z0-9_-])+)/.freeze
+
+      # Every class token referenced by any selector anywhere in the stylesheet, unescaped back to the literal
+      # form an author writes in `class="..."`. Scoped to selector text only (everything before a "{"): a
+      # declaration's VALUES can contain "." too (decimals, calc()), which must never be mistaken for a class.
+      def self.classes_in(css_text)
+        selectors = css_text.scan(/([^{}]+)\{[^{}]*\}/m).flatten
+        tokens = selectors.flat_map { |s| s.scan(CLASS_TOKEN).flatten }
+        tokens.map { |t| t.gsub(/\\(.)/, '\1') }.to_set
+      end
+
+      def self.load(path)
+        path = path.to_s.empty? ? CORE_CSS_PATH : path
+        return Set.new unless File.exist?(path)
+        mtime = File.mtime(path)
+        cached = CACHE[path]
+        return cached.last if cached && cached.first == mtime
+        known = classes_in(File.read(path).force_encoding('UTF-8').scrub)
+        CACHE[path] = [ mtime, known ]
+        known
+      end
+
+      def self.resolves?(class_name, known)
+        MARKER_CLASSES.include?(class_name) || known.include?(class_name)
+      end
+    end
 
     # A consumer's vocabulary, read at runtime from a YAML file (decision 3):
     #
@@ -670,7 +743,10 @@ module QSS
       def self.register_or_similar(result, id, known, registry)
         near = NameRules.similar(id, known, allow_digits: registry.allow_digits)
         if near.empty?
-          kind = result.branch == :custom ? 'declare it as a type' : "register what #{result.qualifier.inspect} adds to #{result.base.inspect}, or drop the qualifier"
+          # Native-branch advice never offers "drop the qualifier": a bare native tag is itself a red
+          # missing_qualifier violation (see check_native above), so dropping it would just trade one red
+          # finding for another, not resolve anything.
+          kind = result.branch == :custom ? 'declare it as a type' : "register what #{result.qualifier.inspect} adds to #{result.base.inspect}"
           result.findings << finding(result.branch == :custom ? :undeclared_type : :unregistered_qualifier, 'red', "#{id.inspect} is not in the registry: #{kind}")
         else
           list = near.map { |name, why| "#{name.inspect} (#{why})" }.join(', ')
@@ -744,9 +820,11 @@ module QSS
       narrow_pattern = narrow_structural_pattern(settings)
       portal_label = portal_label(settings)
       registry = Registry.load(settings['registry_path'])
+      known_classes = Stylesheet.load(settings['stylesheet_path'])
       exempt_prefixes = [ prefix, IdRules::FRAMEWORK_PREFIX ]
       seen_ids = {}
       seen_attributes = {}
+      seen_unresolved = {}
       unless registry.errors.empty?
         issues << { type: 'identity', code: :registry_problem, message: "Registry problem (#{registry.errors.size}): #{registry.errors.first[:message]}", severity: 'red' }
       end
@@ -788,6 +866,18 @@ module QSS
 
         next if is_foreign && !is_structural # Skip internal payload of foreign components
 
+        # Class resolution (item 4): every class must literally appear in the compiled stylesheet, not just match
+        # a known shape (the 2026-09-21 census: ~29% didn't, with both auditors green). Foreign content is the
+        # host app's own classes, never QSS's to check; ERB-built class lists can't be known statically.
+        if !is_foreign && !node['class'].to_s.include?('<!--ERB-->')
+          classes.each do |cls|
+            next if Stylesheet.resolves?(cls, known_classes)
+            next if seen_unresolved[cls]
+            seen_unresolved[cls] = true
+            issues << { type: 'protocol', code: :unresolved_class, message: "Unresolved Class: #{cls.inspect} is not in the compiled stylesheet (#{settings['stylesheet_path'].to_s.empty? ? "core's qss_core.css" : settings['stylesheet_path']}); it will render as if the class were never written", severity: 'red' }
+          end
+        end
+
         # Identity findings (item B), each id reported once per file.
         if identity && !seen_ids[id]
           seen_ids[id] = true
@@ -835,7 +925,8 @@ module QSS
         # built in ERB are skipped: their classes cannot be known from the template.
         actor_dimensions_checked = qss_actor && !is_foreign && !is_content_driven && !node['class'].include?('<!--ERB-->')
         if actor_dimensions_checked
-          missing = Dimensions.missing_axes(classes)
+          parent_classes = node.parent&.element? ? (node.parent['class']&.split(/\s+/) || []) : []
+          missing = Dimensions.missing_axes(classes, parent_classes: parent_classes)
           unless missing.empty?
             label = id.empty? ? "<#{node.name}>" : "##{id}"
             issues << { type: 'protocol', code: :implicit_dimension, message: "Implicit Dimension Violation: QSS actor #{label} declares no #{missing.join(' and no ')}; declare it with a QSS size class (w[N]/h[N], w-pct[N]/h-pct[N], w-full/h-full) or opt out with qss-content-driven", severity: 'red' }

data/lib/qss/version.rb

@@ -3,7 +3,7 @@
 module QSS
   # The gem's version. QSS::VERSION is the usual spelling; QSS::Version::STRING the same value.
   module Version
-    STRING = "0.1.1"
+    STRING = "0.1.3"
   end
 
   VERSION = Version::STRING

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: qss
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Kraig Fairhurst
@@ -93,10 +93,16 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: QSS sizes and places layout on a 1000-unit canvas grid (1 qnt = canvas
-  width / 1000, pure CSS), ships compiled and SCSS sources, and audits views for rule
-  violations. Includes a Rails engine for the asset pipeline; the auditors also run
-  without Rails.
+description: |-
+  AI coding agents struggle with CSS. Asked to move a sidebar 10px, an agent edits a margin, then an order, then a flex-basis, and something else moves. It then reports the change as done while the page is broken. Flex and grid have no single "left" property, so the agent has to guess which one to touch.
+
+  QSS makes layout addressable. Every structural value is an explicit, single-purpose quantity on a 1000-unit canvas grid (1 qnt = canvas width / 1000, computed in pure CSS), so each edit has one target and the same numbers hold at any screen size. Frames sit flat on one canvas, isolate their layout, and overlays portal to the document root.
+
+  QSS also audits what can be checked statically. Two auditors flag violations such as !important, inline layout styles, undeclared sizes and raw viewport units. RED marks a rule violation and ORANGE a judgment call. Static checks can't prove a page renders, so QSS includes a render check for the compiled CSS alone, and its design history is explicit that only a real browser is real proof.
+
+  QSS was extracted from Parapet, a Rails development tool, which was its first consumer. Its early custom parser was a bug farm, and an invented syntax costs agents more than it buys. Structure moved to plain CSS custom properties; bracket values remain for content such as spacing and sizes. What was tried and dropped is in docs/DESIGN_HISTORY.md.
+
+  Status: 0.1.x. Expect names and APIs to change before 1.0.
 email:
 - kmfairhurst@gmail.com
 executables:
@@ -132,6 +138,7 @@ metadata:
   source_code_uri: https://bitbucket.org/kmf2/qss
   bug_tracker_uri: https://bitbucket.org/kmf2/qss/issues
   changelog_uri: https://bitbucket.org/kmf2/qss/src/main/CHANGELOG.md
+  documentation_uri: https://bitbucket.org/kmf2/qss/src/main/docs/DESIGN_HISTORY.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -150,5 +157,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.13
 specification_version: 4
-summary: 'Quantized Spatial Styling: an agent-aware CSS layout framework, with auditors'
+summary: 'Quantized Spatial Styling: CSS layout that AI agents can read, edit and
+  check from source'
 test_files: []