qss 0.1.2 → 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.2"
+    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.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Kraig Fairhurst