qss 0.1.0

data/config/grammar.yml

@@ -0,0 +1,265 @@
+# QSS Grammar Registry
+# Single Source of Truth for the QSS DSL
+# -------------------------------------------------------------------
+
+adjectives:
+  # 1. Positional: Elements that define the "Steel Frame" (Coordinates/Flow-breaking)
+  # These are forbidden on "Payload" tags unless overridden.
+  positional:
+    - detached
+    - floating
+    - stuck
+    - absolute
+    - pos-x
+    - pos-y
+    - pos-r
+    - pos-b
+    - pos
+
+  # 1b. Flow-Relative: Positioning that doesn't break document flow
+  flow_relative:
+    - anchored
+    - relative
+
+  # 2. Layout: Deterministic container logic (Flex/Grid)
+  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
+    - w-full
+    - h-full
+    - w-f
+    - h-f
+
+  # 3. Typographic: Flow-safe styling for "Drywall" (Content)
+  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
+
+  # 4. Visual: Surface-level aesthetics
+  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
+
+  # 5. Interactive: State and behavior
+  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
+
+  # 6. Internal: Framework-specific markers
+  internal:
+    - qss
+    - dev-border
+    - group
+    - foreign
+    - qss-legibility-override
+    - qss-ergonomic-override
+    - qss-payload-override
+    - qss-dampen-scaling
+    - qss-content-driven
+
+# Tags that represent variable-length human content (Payload)
+payload_tags:
+  - p
+  - h1
+  - h2
+  - h3
+  - h4
+  - h5
+  - h6
+  - span
+  - label
+  - blockquote
+  - li
+
+# Enforcement Rules for the QssAuditor
+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
+
+# Configuration -- neutral QSS DEFAULTS. Feeds exe/qss-sync -> core's _qss_defaults.scss (every setting !default).
+# A consuming project overrides/extends these in its own config file; exe/qss-sync deep-merges that file over this
+# one (hashes merge by key, lists replace) into the consumer's SCSS settings, and the auditors read it at runtime
+# (lib/qss/configuration.rb). Nothing project-specific belongs here.
+config:
+  unit: "1px"
+  anchor: "#qss-canvas"
+
+  # Overlay portal root. Empty = the DSL rules are scoped to the anchor only. A consumer
+  # that portals overlays out of the anchor sets its portal element's selector here.
+  portal_root: ""
+
+  # Minimal default palette: only what qss_core.scss itself references (slate-800 border
+  # default, slate-900 safety gutter, rose-500 dev border) plus the neutral scale.
+  # Consumers add their own colors; the generated color/alpha/accent rules follow.
+  palette:
+    black: "#000000"
+    white: "#ffffff"
+    transparent: "transparent"
+    none: "none"
+    slate-50: "#f8fafc"
+    slate-100: "#f1f5f9"
+    slate-200: "#e2e8f0"
+    slate-300: "#cbd5e1"
+    slate-400: "#94a3b8"
+    slate-500: "#64748b"
+    slate-600: "#475569"
+    slate-700: "#334155"
+    slate-800: "#1e293b"
+    slate-900: "#0f172a"
+    slate-950: "#020617"
+    rose-500: "#f43f5e"
+
+  depths:
+    canvas: 0
+    content: 100
+    ui: 500
+    overlay: 900
+    modal: 1000
+
+  quantization:
+    units: 1000
+    borders: 50
+
+  # Text scale (SETTLED 2026-09-21). text-size[N] = N px at calibration_width, scaling
+  # with --qnt, bounded by a floor/cap that are themselves functions of N.
+  text_scale:
+    calibration_width: 1440
+    floor_px: 9
+    floor_multiplier: 0.875
+    cap_multiplier: 1.5
+
+  # Non-text content scale (SETTLED 2026-09-21, option C). Only new tokens (icon-size)
+  # use it until the Phase B converter activates it for w/h/px/gap/border/rounded.
+  content_scale:
+    calibration_width: 1440
+
+  # Named-group registry for group-{state}/{name} relational classes. Consumer-supplied.
+  group_names: []
+
+  breakpoints:
+    sm: "640px"
+    md: "768px"
+    lg: "1024px"
+    xl: "1280px"
+
+  vertical_breakpoints:
+    v-sm: "400px"
+    v-md: "600px"
+    v-lg: "800px"
+    v-xl: "1000px"
+
+  fonts:
+    sans: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif"
+    mono: "'JetBrains Mono', 'Fira Code', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace"
+
+# Auditor settings -- neutral defaults (QssAuditor / QssNativeAuditor). A consuming
+# project overrides these in its own config file. Portal root comes from config.portal_root.
+auditor:
+  # Elements whose id starts with this prefix count as first-party structural frames.
+  # Empty = no prefix convention: structural elements are recognised by the words below alone.
+  id_prefix: ""
+
+  # Words that mark an id as a structural frame (drives the inline-style and explicit-dimension checks).
+  structural_words: [header, footer, sidebar, workspace, main, panel, frame, wrapper, nav, aside]
+
+  # Subset of those words that MANDATE `contain: layout`.
+  narrow_words: [header, footer, sidebar, workspace, main, panel, frame, wrapper, nav, aside]
+
+  # Class prefixes of third-party icon sets that the whitelist check skips.
+  icon_prefixes: []
+
+  # The consumer's vocabulary registry (types, functions, allow_digits), a YAML file read at runtime by the
+  # native auditor. Relative to the process working directory. Empty = no registry (an empty vocabulary).
+  registry_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.)
+sync_targets:
+  # Core's own SCSS defaults (every setting !default), generated from this file alone; core imports it.
+  core_variables: app/assets/stylesheets/qss/_qss_defaults.scss
+  # The consumer's SCSS settings (this file merged with the consumer's); the consumer imports it before core.
+  variables: app/assets/stylesheets/_qss_variables.scss
+  engine: app/assets/javascripts/qss/qss-engine.js
+  auditor: lib/qss/qss_auditor.rb
+  native_auditor: lib/qss/qss_native_auditor.rb

data/config/qss-objects.json

@@ -0,0 +1,3 @@
+{
+  "blueprints": []
+}

data/exe/qss-core-render-check

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Renders QSS core's compiled CSS on its own -- no consumer stylesheet, no qss-engine.js -- in headless Chrome and
+# checks that core's utilities apply. Guards against the core reset outranking core utilities (found 2026-09-24:
+# `.qss:not(.foreign *)` weighed (1,2,0) against the utilities' (1,1,0), so compiled utilities only worked when the
+# JS engine re-emitted them). Exit 0 when every check passes, 1 otherwise.
+#
+#   qss-core-render-check [path/to/qss_core.css]
+#
+# The test canvas is 1000px wide, so one QSS unit is exactly 1px unless a check resizes it.
+
+require "selenium-webdriver"
+require "tmpdir"
+
+css_path = File.expand_path(ARGV[0] || File.join(__dir__, "..", "app", "assets", "stylesheets", "qss", "qss_core.css"))
+abort "qss-core-render-check: no stylesheet at #{css_path}" unless File.exist?(css_path)
+
+HTML = <<~HTML
+  <!doctype html><html><head>
+  <link rel="stylesheet" href="file:///#{css_path.tr('\\', '/')}">
+  <style>.host-static { position: static; display: inline; }</style>
+  </head><body><div id="qss-canvas" style="width: 1000px">
+    <div id="bare" class="qss"></div>
+    <div id="hidden" class="qss hidden"></div>
+    <div id="qss-relative" class="qss qss-relative"></div>
+    <div id="anchored" class="qss anchored"></div>
+    <div id="sized" class="qss w[200] h[100]"><div id="full" class="qss w-full h-full"></div></div>
+    <div id="flex" class="qss flex"></div>
+    <div id="vertical" class="qss vertical"></div>
+    <div id="flex1" class="qss flex-1"></div>
+    <div id="padded" class="qss p[4]"></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>
+  </div></body></html>
+HTML
+
+CHECKS = [
+  [ "bare actor gets the reset: position",            "bare",         "position",       "absolute" ],
+  [ "bare actor gets the reset: flex-shrink",         "bare",         "flexShrink",     "0" ],
+  [ "hidden beats the reset",                         "hidden",       "display",        "none" ],
+  [ "qss-relative beats the reset",                   "qss-relative", "position",       "relative" ],
+  [ "anchored beats the reset",                       "anchored",     "position",       "relative" ],
+  [ "w-full beats the reset",                         "full",         "width",          "200px" ],
+  [ "h-full beats the reset",                         "full",         "height",         "100px" ],
+  [ "flex beats the reset",                           "flex",         "display",        "flex" ],
+  [ "vertical beats the reset",                       "vertical",     "flexDirection",  "column" ],
+  [ "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" ],
+  [ "foreign content is left alone",                  "in-foreign",   "position",       "static" ]
+].freeze
+
+failures = 0
+total = CHECKS.size
+Dir.mktmpdir do |dir|
+  page = File.join(dir, "qss_core_render_check.html")
+  File.write(page, HTML)
+  options = Selenium::WebDriver::Chrome::Options.new
+  %w[--headless --disable-gpu --window-size=1400,1000 --allow-file-access-from-files].each { |a| options.add_argument(a) }
+  # CI containers run Chrome as root with a small /dev/shm; CHROME_BIN / CHROMEDRIVER_PATH point at a packaged Chromium.
+  %w[--no-sandbox --disable-dev-shm-usage].each { |a| options.add_argument(a) } if ENV["CI"]
+  options.binary = ENV["CHROME_BIN"] if ENV["CHROME_BIN"]
+  service = ENV["CHROMEDRIVER_PATH"] ? Selenium::WebDriver::Service.chrome(path: ENV["CHROMEDRIVER_PATH"]) : nil
+  driver = service ? Selenium::WebDriver.for(:chrome, options: options, service: service) : Selenium::WebDriver.for(:chrome, options: options)
+  begin
+    driver.navigate.to("file:///#{page.tr('\\', '/')}")
+    engine = driver.execute_script("return typeof window.QSSEngine !== 'undefined'")
+    abort "qss-core-render-check: the JS engine is present; this check must run on CSS alone" if engine
+    CHECKS.each do |label, id, prop, expected|
+      actual = driver.execute_script("return getComputedStyle(document.getElementById(arguments[0]))[arguments[1]]", id, prop)
+      ok = actual == expected
+      failures += 1 unless ok
+      puts format("%-4s %-56s %s=%s%s", ok ? "ok" : "FAIL", label, prop, 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|
+      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)
+        ok = actual == expected
+        total += 1
+        failures += 1 unless ok
+        puts format("%-4s %-56s --qnt=%s%s", ok ? "ok" : "FAIL", "canvas #{width}px: unit on the #{where}", actual, ok ? "" : " (expected #{expected})")
+      end
+    end
+    viewport = driver.execute_script("return window.innerWidth")
+    expected = "#{(viewport * 0.001).round(4).to_s.sub(/\.0\z/, '')}px"
+    actual = qnt.(nil)
+    ok = actual == expected
+    total += 1
+    failures += 1 unless ok
+    puts format("%-4s %-56s --qnt=%s%s", ok ? "ok" : "FAIL", "outside a canvas: viewport approximation (#{viewport}px)", actual, ok ? "" : " (expected #{expected})")
+  ensure
+    driver.quit
+  end
+end
+
+puts failures.zero? ? "qss-core-render-check: #{total} of #{total} passed" : "qss-core-render-check: #{failures} of #{total} FAILED"
+exit(failures.zero? ? 0 : 1)

data/exe/qss-sync

@@ -0,0 +1,205 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: false
+
+require 'json'
+require 'yaml'
+
+# Generates QSS's derived files from two inputs:
+#   config/grammar.yml      -- core grammar + neutral defaults (source of truth), found relative to this script
+#   config/qss_config.yml   -- the consuming project's settings (optional), relative to the directory the sync is
+#                              run from; another path via QSS_CONSUMER_CONFIG (e.g.
+#                              QSS_CONSUMER_CONFIG=config/myapp/qss_config.yml qss-sync)
+# Two modes. By default (a consuming project) it writes ONLY the consumer's SCSS settings file. With --core (QSS's
+# own maintainers: `rake sync` in the gem) it also regenerates core's generated files, which live in the gem and
+# must never be rewritten from an app. Core's outputs (engine, auditors, core SCSS defaults) resolve from core's
+# root; the consumer's SCSS settings file
+# resolves from the directory the sync is run from. Merge rule: hashes merge by key, lists and scalars replace.
+
+CORE_ROOT = File.expand_path('..', __dir__)
+grammar_path = File.join(CORE_ROOT, 'config/grammar.yml')
+unless File.exist?(grammar_path)
+  puts "Error: #{grammar_path} not found"
+  exit 1
+end
+
+def deep_merge(base, over)
+  return over unless base.is_a?(Hash) && over.is_a?(Hash)
+  base.merge(over) { |_k, a, b| deep_merge(a, b) }
+end
+
+grammar = YAML.load_file(grammar_path)
+consumer_path = ENV.fetch('QSS_CONSUMER_CONFIG', 'config/qss_config.yml')
+consumer = File.exist?(consumer_path) ? (YAML.load_file(consumer_path) || {}) : {}
+puts "Consumer config: #{File.exist?(consumer_path) ? consumer_path : 'none (core defaults only)'}"
+CORE_MODE = ARGV.include?('--core')
+unless CORE_MODE || File.exist?(consumer_path)
+  abort "Nothing to do: no consumer config at #{consumer_path} (set QSS_CONSUMER_CONFIG), and --core not given."
+end
+
+config = deep_merge(grammar['config'], consumer['config'] || {})
+
+# A consumer's grammar_extensions and auditor: settings are NOT written anywhere by this script: the auditors read
+# them at runtime (lib/qss/configuration.rb). Only the consumer's SCSS settings file is generated from them.
+
+# Output locations (grammar.yml `sync_targets:`, overridable by the consumer).
+targets = deep_merge(grammar['sync_targets'] || {}, consumer['sync_targets'] || {})
+%w[core_variables variables engine auditor native_auditor].each { |k| abort "sync_targets.#{k} is not configured" unless targets[k] }
+# Core's files live in core; only the consumer's SCSS settings file belongs to the consumer.
+%w[core_variables engine auditor native_auditor].each { |k| targets[k] = File.expand_path(targets[k], CORE_ROOT) }
+
+# --- Generated regions -------------------------------------------------------------------
+# Each generated target carries ONE marked region:
+#     <comment> QSS-GENERATED-BEGIN ...
+#     <comment> QSS-GENERATED-END
+# The sync rewrites everything between the markers and touches nothing else. A missing,
+# duplicated or misordered marker aborts the run BEFORE anything is written: there is no
+# fallback placement. (An earlier version anchored on the class name and, when nothing matched,
+# silently prepended the constants to the top of the file.)
+GENERATED_WARNING = 'GENERATED FROM grammar.yml - DO NOT EDIT'.freeze # qss_auditor.rb checks the engine for this exact text
+GEN_INDENT = '    '.freeze
+
+def region_markers(text)
+  begins = text.to_enum(:scan, /^[ \t]*(?:#|\/\/) QSS-GENERATED-BEGIN\b.*$/).map { Regexp.last_match }
+  ends = text.to_enum(:scan, /^[ \t]*(?:#|\/\/) QSS-GENERATED-END\b.*$/).map { Regexp.last_match }
+  [ begins, ends ]
+end
+
+def check_region!(path, text)
+  begins, ends = region_markers(text)
+  return [ begins[0], ends[0] ] if begins.size == 1 && ends.size == 1 && begins[0].end(0) <= ends[0].begin(0)
+  abort "#{path}: expected exactly one QSS-GENERATED-BEGIN line followed by one QSS-GENERATED-END line " \
+        "(found #{begins.size} BEGIN, #{ends.size} END#{begins.size == 1 && ends.size == 1 ? ', END before BEGIN' : ''}). " \
+        "Add the pair where the generated constants should live. Nothing was written."
+end
+
+def read_target(path)
+  raw = File.binread(path).force_encoding('UTF-8')
+  [ raw.include?("\r\n"), raw.gsub("\r\n", "\n") ]
+end
+
+def indent_block(text)
+  lines = text.lines
+  base = (lines.find { |l| !l.strip.empty? } || '')[/[ \t]*/]
+  lines.map { |l| l.strip.empty? ? '' : "#{GEN_INDENT}#{l.start_with?(base) ? l[base.length..] : l.lstrip}".chomp }.join("\n")
+end
+
+# Preflight: validate every target's markers before anything is generated or written.
+%w[engine auditor native_auditor].each do |k|
+  next unless CORE_MODE && File.exist?(targets[k])
+  check_region!(targets[k], read_target(targets[k]).last)
+end
+
+def write_region(path, blocks, comment)
+  unless File.exist?(path)
+    puts "Warning: #{path} not found, skipping."
+    return
+  end
+  crlf, text = read_target(path)
+  first, last = check_region!(path, text)
+  body = "\n#{GEN_INDENT}#{comment} #{GENERATED_WARNING}\n" + blocks.map { |b| indent_block(b) }.join("\n\n") + "\n"
+  text = text[0...first.end(0)] + body + text[last.begin(0)..]
+  File.binwrite(path, crlf ? text.gsub("\n", "\r\n") : text)
+  puts "Updated #{path}"
+end
+objects_path = File.join(CORE_ROOT, 'config/qss-objects.json')
+objects = File.exist?(objects_path) ? JSON.parse(File.read(objects_path)) : { "blueprints" => [] }
+
+# 1. SCSS settings, twice. Core's defaults file (grammar.yml alone, every setting !default) is imported by core;
+#    the consumer's file (grammar.yml + consumer config, plain assignments) is imported by the consumer BEFORE core,
+#    so its values win over the defaults. Core's compiled CSS therefore carries no consumer's settings.
+def scss_variables(config, header, default)
+  d = default ? ' !default' : ''
+  scss_map = ->(h) { h.map { |k, v| "  \"#{k}\": #{v}" }.join(",\n") }
+  scss_scale = ->(h) { h.map { |k, v| "  \"#{k.to_s.tr('_', '-')}\": #{v}" }.join(",\n") }
+  <<~SCSS
+  /* #{header} - DO NOT EDIT MANUALLY */
+
+  $qss-unit: #{config['unit']}#{d};
+  $qss-anchor: "#{config['anchor']}"#{d};
+
+  /* Overlay portal root; "" = rules scoped to the anchor only. */
+  $qss-portal-root: "#{config['portal_root']}"#{d};
+
+  $qss-palette: (
+  #{scss_map.(config['palette'])}
+  )#{d};
+
+  $qss-depths: (
+  #{scss_map.(config['depths'])}
+  )#{d};
+
+  $qss-quantization: (
+  #{scss_scale.(config['quantization'])}
+  )#{d};
+
+  /* Text scale (item 2, SETTLED 2026-09-21). */
+  $qss-text-scale: (
+  #{scss_scale.(config['text_scale'])}
+  )#{d};
+
+  /* Non-text content scale (item 3, SETTLED 2026-09-21). */
+  $qss-content-scale: (
+  #{scss_scale.(config['content_scale'])}
+  )#{d};
+
+  /* Named-group registry (consumer-supplied). */
+  $qss-group-names: (#{(config['group_names'] || []).map { |n| "\"#{n}\"" }.join(", ")})#{d};
+
+  $qss-breakpoints: (
+  #{scss_map.(config['breakpoints'])}
+  )#{d};
+
+  $qss-vertical-breakpoints: (
+  #{scss_map.(config['vertical_breakpoints'])}
+  )#{d};
+
+  $qss-fonts: (
+  #{scss_map.(config['fonts'].transform_values { |v| "\"#{v}\"" })}
+  )#{d};
+  SCSS
+end
+
+if CORE_MODE
+  File.write(targets['core_variables'], scss_variables(grammar['config'], 'QSS core defaults, generated from grammar.yml alone', true))
+  puts "Generated #{targets['core_variables']}"
+end
+
+if File.exist?(consumer_path)
+  File.write(targets['variables'], scss_variables(config, "Generated from grammar.yml + #{consumer_path}", false))
+  puts "Generated #{targets['variables']}"
+else
+  puts "No consumer config: #{targets['variables']} not written"
+end
+
+# Core-only inputs for everything that ships in the gem (engine, auditors).
+core_config = grammar['config']
+core_adjectives = grammar['adjectives']
+
+# 2. qss-engine.js -- CORE ONLY (grammar.yml alone; the engine ships in the gem).
+palette_js = "const BRAND_COLORS = {\n" + core_config['palette'].map { |k, v| "    '#{k}': '#{v}'" }.join(",\n") + "\n};"
+depths_js = "const DEPTHS = {\n" + core_config['depths'].map { |k, v| "    '#{k}': '#{v}'" }.join(",\n") + "\n};"
+blueprints_js = "let objectRegistry = " + JSON.pretty_generate(objects['blueprints'].each_with_object({}) { |b, h| h[b['name']] = b }) + ";"
+fonts_js = "const FONTS = {\n" + core_config['fonts'].map { |k, v| "    '#{k}': \"#{v}\"" }.join(",\n") + "\n};"
+whitelist_js = "const DSL_WHITELIST = new Set([\n" + core_adjectives.values.flatten.uniq.sort.map { |a| "    '#{a}'" }.join(",\n") + "\n]);"
+write_region(targets['engine'], [ palette_js, depths_js, blueprints_js, fonts_js, whitelist_js ], '//') if CORE_MODE
+
+# 3. QSS::QssAuditor -- CORE ONLY. The auditors ship in the gem, so their generated constants carry grammar.yml's
+# neutral defaults and nothing from a consumer; a consumer's settings reach them at runtime (lib/qss/configuration.rb).
+core_auditor_cfg = (grammar['auditor'] || {}).merge('portal_root' => core_config['portal_root'].to_s)
+whitelist_rb = "DSL_WHITELIST = [\n  " + core_adjectives.values.flatten.uniq.sort.map { |a| "'#{a}'" }.join(",\n  ") + "\n].freeze"
+payload_tags_rb = "PAYLOAD_TAGS = " + grammar['payload_tags'].inspect + ".freeze"
+categories_rb = "ADJECTIVE_CATEGORIES = " + core_adjectives.inspect + ".freeze"
+combos_rb = "ILLEGAL_COMBOS = " + grammar['illegal_combos'].inspect + ".freeze"
+blueprints_rb = "BLUEPRINT_NAMES = " + objects['blueprints'].map { |b| b['name'] }.inspect + ".freeze"
+blueprint_slots = objects['blueprints'].each_with_object({}) { |b, h| h[b['name']] = (b['slots'] || []).map { |s| s['name'] } }
+slots_rb = "BLUEPRINT_SLOTS = " + blueprint_slots.inspect + ".freeze"
+palette_rb = "BRAND_COLORS = " + core_config['palette'].inspect + ".freeze"
+depths_rb = "DEPTHS = " + core_config['depths'].inspect + ".freeze"
+auditor_config_rb = "AUDITOR_CONFIG = " + core_auditor_cfg.inspect + ".freeze"
+if CORE_MODE
+  write_region(targets['auditor'],
+               [ whitelist_rb, payload_tags_rb, categories_rb, combos_rb, blueprints_rb, slots_rb, palette_rb, depths_rb, auditor_config_rb ], '#')
+end
+
+# 4. QSS::QssNativeAuditor
+write_region(targets['native_auditor'], [ payload_tags_rb, auditor_config_rb ], '#') if CORE_MODE

data/lib/qss/blueprints.rb

@@ -0,0 +1,106 @@
+require "json"
+require "ostruct"
+
+module QSS
+  # Core helpers for layout arithmetic and object blueprints (config/qss-objects.json), available as QSS.grid,
+  # QSS.object, QSS.resolve_parametric and QSS.resolve_height.
+  module Blueprints
+    OBJECTS_PATH = File.expand_path("../../config/qss-objects.json", __dir__)
+
+    # Deterministic Grid Calculation
+    # Returns an array of OpenStructs with x, y, w, h, and index
+    def grid(count, cols:, w:, h:, gap_x: 0, gap_y: 0)
+      (0...count).map do |i|
+        row = (i / cols).to_i
+        col = i % cols
+
+        OpenStruct.new(
+          index: i + 1,
+          x: col * (w + gap_x),
+          y: row * (h + gap_y),
+          w: w,
+          h: h
+        )
+      end
+    end
+
+    # Object Blueprint Resolver
+    def object(name)
+      @objects ||= load_objects
+      @objects[name.to_s]
+    end
+
+    # Resolves parameters for an object based on its blueprint and optional overrides
+    # Returns a hash of resolved dimensions { w: num, h: num }
+    def resolve_parametric(blueprint, param_string = nil)
+      return blueprint['intrinsic'] unless param_string
+
+      params = param_string.split('|')
+      param_map = blueprint['params'] || []
+      dimensions = blueprint['intrinsic'].dup
+
+      params.each_with_index do |val, idx|
+        key = param_map[idx]
+        if key && val
+          num_val = val.to_f
+
+          # Clamping logic
+          if blueprint["min-#{key}"]
+            num_val = [ num_val, blueprint["min-#{key}"].to_f ].max
+          end
+          if blueprint["max-#{key}"]
+            num_val = [ num_val, blueprint["max-#{key}"].to_f ].min
+          end
+
+          dimensions[key] = num_val
+        end
+      end
+
+      dimensions
+    end
+
+    # Resolved Height for Variable Objects
+    def resolve_height(blueprint, slot_name = nil, vars = {})
+      return 0 unless blueprint
+
+      intrinsic = if slot_name
+        slots = blueprint['slots'] || []
+        slot = slots.find { |s| s['name'] == slot_name.to_s }
+        slot ? slot['intrinsic'] : nil
+      else
+        blueprint['intrinsic']
+      end
+
+      unless intrinsic
+        # Default to 100% of parent height (1000 units) if missing
+        return 1000
+      end
+
+      return intrinsic['h'] if intrinsic['h'].is_a?(Numeric)
+
+      if intrinsic['h'].to_s == 'computed' || intrinsic['h'].to_s == 'variable'
+        variables = blueprint['variables'] || {}
+        max_rows = (vars[:max_rows] || variables['max_rows'] || variables[:max_rows] || 100).to_i
+        rows = [ (vars[:rows] || 0).to_i, max_rows ].min
+        row_height = (vars[:row_height] || variables['row_height'] || variables[:row_height] || 32).to_i
+
+        return rows * row_height
+      end
+
+      # Default to 100% inheritance if 'inherit' or missing
+      1000
+    end
+
+    private
+
+    # Core's own blueprint file, found relative to this file (not Rails.root or the working directory).
+    def load_objects
+      return {} unless File.exist?(OBJECTS_PATH)
+
+      data = JSON.parse(File.read(OBJECTS_PATH))
+      data['blueprints'].each_with_object({}) { |b, h| h[b['name']] = b }
+    end
+  end
+
+  extend Blueprints
+end