v0.7.2: engine fixes (12 review findings), GUIDE.md, honest README/PARITY/llms, test-verified examples, rebuilt packages

GUIDE.md

@@ -0,0 +1,283 @@
+# DSSL Guide
+
+Everything in the repo, in one file. Written for the person who just cloned this
+and wants to know what exists, what works, and what to reach for. Every `.dssl`
+example in this guide is compiled by `scripts/test-guide-examples.mjs` on every
+release, so the examples cannot drift from the compiler. If an example here
+stops compiling, that is a release blocker, not a docs bug.
+
+Status up front: DSSL is a real, tested style engine at v0.7.2, and it is
+honest alpha. It needs JavaScript, it writes inline styles, and it has a
+first-paint story you should read before shipping anything serious (see
+"Honest limits"). Within those limits, it is genuinely nicer to write than
+hand-rolled CSS for creative pages, docs, playgrounds and internal tools.
+
+---
+
+## 1. What this repo is
+
+| Path | What it is |
+|---|---|
+| `public/dssl/` | The engine. Six zero-dependency ESM files: `parser.js`, `resolver.js`, `engine.js`, `index.js` (public API), `utils.js`, `boot.js`. This is the whole language. |
+| `public/styles/*.dssl` | The stylesheets that drive the docs site itself. The site is styled entirely by its own engine, which makes it the de-facto test suite. |
+| `public/examples/hello.dssl` | The starter stylesheet. Small, commented, every interaction real. |
+| `package/` + `public/install.sh`, `install.ps1` | The downloadable engine package: `curl -fsSL https://dssl-sable.vercel.app/install.sh \| sh`. |
+| `public/dssl-engine.zip`, `.tar.gz` | Same package as plain archives. |
+| `dssl-vscode/` | The editor extension (VS Code and VSCodium). Bundles the real parser and resolver, so editor squiggles are browser-console errors. See its own README and PUBLISHING.md. |
+| `src/` | The Next.js docs site: playground, bench page, spec, changelog. |
+| `scripts/` | Tests, package builds, the extension engine sync, deploy helpers. |
+| `llms.txt`, `AGENTS.md`, `PARITY.md` | The machine-reviewer layer and contributor rules. PARITY.md is the honest CSS feature matrix. |
+| `worklog.md` | The full build history, every decision logged. |
+
+Version rule: the engine version in `public/dssl/index.js` is the source of
+truth. The site badge, footer, changelog and READMEs follow it on every release.
+
+## 2. Quickstart
+
+Two tags. No build step, no npm, nothing to compile:
+
+```html
+<link rel="stylesheet/dssl" href="styles.dssl">
+<script src="dssl/index.js" type="module"></script>
+```
+
+Or embed DSSL directly in your HTML (this is the Tailwind-ish answer: the
+language lives wherever you want it):
+
+```html
+<script src="dssl/index.js" type="module"></script>
+<style type="text/dssl">
+  .card {
+    background: #26201a
+    radius: 12
+    hover { background: #3a2f26 }
+  }
+</style>
+```
+
+`<style type="text/dssl">` and `<script type="text/dssl">` both work; the
+engine's auto-boot picks them up in document order, after any linked files.
+You can use as many blocks as you like.
+
+A real starter stylesheet with comments lives at
+`public/examples/hello.dssl`.
+
+## 3. The language, fast
+
+### Bare numbers are px
+
+`padding: 16` is 16px. Units still work when you want them: `width: 50%`,
+`font-size: 1.2rem`, `margin: 0 auto`.
+
+### Tokens
+
+```dssl
+tokens {
+  color {
+    ink: #16161d
+    accent: oklch(62% 0.19 35)
+  }
+  space {
+    1: 4
+    2: 8
+    4: 16
+  }   // numeric keys are legal
+  radius { md: 14 }
+  shadow { md: 0 2 4 color.ink/10, 0 4 12 color.ink/8 }
+}
+
+.card {
+  background: color.ink
+  padding: space.4
+  radius: md
+  shadow: md
+}
+```
+
+Alpha on any color: `color.ink/50`, `#ff0000/50` (compiles to color-mix).
+Token overrides can be scoped under `@media` or `@signal` for themes.
+
+### Layout is words
+
+```dssl
+.toolbar { row: gap 8 between center }
+.sidebar { column: gap 16 }
+.board   { grid: 3 gap 12 }        // 3 columns, 1fr each, gap 12
+.board   { grid: auto-fill 220 }   // responsive columns
+.gallery { grid: 2 rows 3 gap 8 }  // rows N is a word too
+.modal   { stack: center }         // grid place-items center
+.hero    { center: both }
+```
+
+### The cascade is (layer, order)
+
+No specificity, no `!important`. Later wins inside a layer. Layers sort
+`tokens < base < components < utilities < pin`. Nested blocks do what the
+indentation says they do (fixed in v0.7.2, it used to be the engine's worst
+bug):
+
+```dssl
+.card {
+  background: #26201a
+  shadow: sm
+  hover { background: #3a2f26; shadow: lg }   // beats the base now, by order
+
+  @media dark { background: #181310 }         // condition is kept, sorts after base
+
+  @layer utilities { margin-top: 0 }
+}
+```
+
+Declarations after a nested block keep working too: they become a later
+fragment of the same rule, and later still wins.
+
+### States
+
+All the usual suspects ride native matching: `hover`, `focus`,
+`focus-visible`, `active`, `disabled`, `checked`, `target`, `open` (details),
+and structural ones via selectors. Two engine details worth knowing:
+
+- `checked` and `open` listen to real events (`change`, `toggle`), so
+  keyboard toggles restyle immediately. For programmatic control, set the
+  property and dispatch a bubbling change event:
+  `el.checked = true; el.dispatchEvent(new Event('change', { bubbles: true }))`.
+- Attribute changes (`disabled` and friends) are picked up by the engine's
+  MutationObserver automatically.
+
+### Conditions
+
+```dssl
+.card {
+  @media dark { background: #181310 }       // one-word sugar
+  @media 768 { padding: 24 }                // bare width = min-width
+  @media <= 480 { padding: 12 }
+  @container (min-width: 400px) { column: gap 4 }
+  @signal theme==dark { border-color: color.accent }
+}
+```
+
+`@media reduced-motion` is honored by every motion unless the motion declares
+`essential`.
+
+### Motion and seen
+
+```dssl
+motion rise-in {
+  from { opacity: 0; translate: 0 18 }
+}
+
+motion lift {
+  from { translate: 0 2 }
+}
+
+.gallery { stagger: 60 }
+
+.card {
+  seen { animate: rise-in 480 snap }   // plays once, when scrolled into view
+  hover { animate: lift 200 }          // WAAPI, reduced-motion aware
+}
+```
+
+The arrow `->` is motion/gradient syntax (keyframes and gradient stops). It
+does nothing inside a `seen { }` block, and the compiler now says so loudly.
+
+### Behaviors, deform, overlap
+
+`use` shares named blocks (the site's `focus-ring` is one). `bend`, `fold`,
+`stretch` deform on scroll. `overlap:` declares allowed overlap policies.
+The full vocabulary lives in the site's Docs and Cheat sheet views.
+
+## 4. The engine API
+
+```js
+import { DSSL } from '/dssl/index.js'
+
+DSSL.version()                    // "0.7.2"
+DSSL.compile(source)              // { ok, errors, warnings, stats, doc }
+DSSL.apply(source, { name, scope, replace })
+await DSSL.load(['a.dssl', 'b.dssl'])
+DSSL.signal('theme', 'dark')      // drives @signal rules
+DSSL.refresh()                    // full recompute
+DSSL.freeze() / DSSL.unfreeze()   // static snapshot: ambient restyling off
+DSSL.explain(el)                  // which rules matched, what won, why
+DSSL.errors()                     // last compile errors
+```
+
+`freeze()` is the big performance lever for static pages: the engine drops its
+observers and listeners, keeps the resolved styles, and the page stops paying
+for liveness. `unfreeze()` re-arms everything.
+
+## 5. The editor extension
+
+Three ways to get it:
+
+1. Download `dssl-vscode/dssl-vscode-0.7.1.vsix` from the repo files, then
+   Extensions panel, `...`, Install from VSIX. Works in VS Code and VSCodium.
+2. Build it: `cd dssl-vscode && npx @vscode/vsce package --no-dependencies`.
+3. Registry listing: staged for Open VSX (the registry VSCodium searches).
+   See `dssl-vscode/PUBLISHING.md` for exactly what remains.
+
+What it does: real-compiler diagnostics (same errors the browser prints,
+did-you-mean included, line numbers accurate since the v0.7.1 parser fix),
+completions folded from your workspace token registry, hover docs, a TextMate
+grammar for `.dssl`.
+
+## 6. Tooling and tests
+
+```sh
+node scripts/test-v072.mjs      # latest regression suite (40 assertions)
+node scripts/test-v071.mjs      # parser line-number suite
+node scripts/test-v070.mjs      # v0.7 feature suite (60)
+node scripts/test-v050.mjs      # v0.5 feature suite (61)
+node scripts/dssl-smoke.mjs     # end-to-end compile of the smoke stylesheet
+node scripts/dssl-styles-check.mjs  # all six site stylesheets compile
+node scripts/sync-extension-engine.mjs  # run after ANY engine change
+bash scripts/build-engine-package.sh    # rebuild the zip/tar packages
+```
+
+House rule from AGENTS.md: if you touch `public/dssl/`, run the suites, then
+run the sync script so the editor extension ships the same compiler.
+
+## 7. Honest limits
+
+Read this before choosing DSSL for a real site.
+
+- **JavaScript is required.** No JS, no styles. The engine ships no CSS
+  fallback because there is no CSS. If a page must work without JS, use CSS.
+- **First paint.** Styles are applied by the engine after it loads, so large
+  pages can flash unstyled content (CLS). The docs site solves this by
+  inlining its stylesheets into the SSR HTML. The planned prerender mode
+  (server renders the final inline styles) is the real fix and is on the
+  PARITY roadmap as the next big item.
+- **CSP.** Pseudo-elements compile to one real stylesheet the engine injects;
+  strict `style-src 'self'` blocks inline style attributes and that sheet.
+  DSSL wants `unsafe-inline` for styles today.
+- **Interop is invasive.** DSSL normal declarations beat external CSS, and
+  `pin` beats external `!important`. Mixing with an existing CSS design
+  system works but the engine wins by design.
+- **Large interactive pages** pay a real per-recompute cost. `freeze()`
+  makes static pages viable; live hover on thousands of elements is bounded
+  since v0.7.2 but is still not free.
+- **Not a CSS replacement.** It is a style language that ends in inline
+  styles. When it is the better tool, it is because of the authoring
+  experience: tokens, words-as-layout, states and motion in one grammar,
+  loud errors, zero build.
+
+## 8. FAQ
+
+**Can I write DSSL in my HTML?** Yes, that is section 2. `<style
+type="text/dssl">` blocks, or `<script type="text/dssl">` if you prefer.
+
+**Where do docs examples get tested?** `scripts/test-guide-examples.mjs`
+compiles every `.dssl` block in this guide and in the README. Green or the
+release does not ship.
+
+**Why does my nested hover not beat the base rule?** It does, since v0.7.2.
+If you are on 0.7.1 or older, that was the cascade bug, upgrade.
+
+**Is there a DSSL for something other than web styling?** Not yet. The
+parser and resolver are domain-agnostic by design, so a domain-specific
+DSSL2 is a plausible later project, not a current one.
+
+**Who builds this?** One person plus AI agents, in the open. `worklog.md`
+is the complete receipt trail.

PARITY.md

@@ -48,3 +48,29 @@ no other replacement styles with the platform's own primitives.
 - the overlap policy: translucent boxes refuse to cover things unless you say so
 - loud errors with did-you-mean, and a warnings channel for cascade-order footguns
 - `freeze()` / `unfreeze()`: a live engine that can be parked at zero cost
+
+## v0.7.2 review-driven corrections
+
+An external agent review reproduced a batch of real bugs; all of them are fixed
+and regression-tested (scripts/test-v072.mjs). Rows affected:
+
+- Nested state blocks (hover/focus/... inside a rule) now sort AFTER the parent
+  rule's own declarations, so nested overrides win the cascade. Nested @media,
+  @signal and @layer blocks also keep their condition and layer (they used to
+  be dropped, making nested dark mode silently dead).
+- Declarations and a nested block can share one line (`.card { bg: red; hover { } }`)
+  without the declaration being swallowed.
+- Raw hex alpha is real: `#ff0000/50` compiles to color-mix (was invalid /50px).
+- Time properties take bare numbers as ms (`transition-delay: 200` -> 200ms).
+- `grid: 3 gap 12` works; `rows N` joined the shorthand.
+- `seen { ... }` rejects motion-arrow syntax loudly and points at the real forms.
+- SVG and modern properties added: fill, stroke (and friends), text-wrap,
+  content-visibility.
+- `::part()` rides the shadow pipeline; `::slotted()` is rejected with an
+  explanation (it only exists inside shadow trees).
+- The gate prefilter now actually runs before native matches().
+- State events scope candidate recomputation to the hovered subtree and its
+  ancestors instead of the whole page (a 1k-card hover went from ~4,100
+  recomputes per event to the touched chain).
+- checkbox/details states hear `change` and `toggle` events, so keyboard
+  toggles and programmatic dispatch restyle immediately.

README.md

@@ -4,7 +4,7 @@ license: mit
 
 # DSSL
 
-DSSL is a style language for the web. It replaces CSS.
+DSSL is a style language for the web. For the pages it fits, it replaces writing CSS entirely. It does not replace the CSS platform: the engine ends in inline styles that the browser parses, and it needs JavaScript. Where it wins is the authoring experience: tokens, words-as-layout, states and motion in one grammar, loud errors, zero build. PARITY.md keeps the honest feature ledger.
 
 Not a preprocessor that spits out stylesheets. Not a utility class graveyard. You write `.dssl` files, the page loads a small engine, and the engine walks your DOM in real time and applies every rule it matches straight onto the elements it finds. Nothing is compiled. There is no build step for styles.
 
@@ -134,7 +134,7 @@ tokens {
     accent: oklch(62% 0.19 35)
   }
   radius { md: 14 }
-  shadow { md: 0 2 4 ink/10, 0 4 12 ink/8 }
+  shadow { md: 0 2 4 color.ink/10, 0 4 12 color.ink/8 }
   space  { 9: 96 }          // numeric keys are legal (v0.7)
 }
 
@@ -277,9 +277,14 @@ motion pulse {
 
 .pt-card {
   seen {
-    opacity: 0 -> 1
-    translate: 0 18 -> 0
-    animate: rise 600 ease-out
+    animate: rise 600 ease-out   // the motion below owns the from-state
+  }
+}
+
+motion rise {
+  from {
+    opacity: 0
+    translate: 0 18
   }
 }
 ```

llms.txt

@@ -0,0 +1,52 @@
+# DSSL
+
+> DSSL is a style language for the web. For JS-guaranteed pages it replaces writing CSS; it does not replace the CSS platform (the engine ends in inline styles the browser parses). You write `.dssl` files, the page loads a ~20 kB engine, and the engine walks the DOM in real time applying every matched rule as inline styles. Nothing compiles to CSS. Elements added later are styled the moment they appear; signals, states and motion share one grammar.
+
+- Site (docs, playground, changelog, bench): https://dssl-sable.vercel.app
+- Repo + full docs in the README: https://huggingface.co/EHS-Studio/dssl
+- Install: `curl -fsSL https://dssl-sable.vercel.app/install.sh | sh` (or the zip: https://dssl-sable.vercel.app/dssl-engine.zip)
+- Version: 0.7.2 (engine), MIT license
+- Feature matrix vs CSS: see PARITY.md in the repo
+- For agents working ON the codebase: see AGENTS.md in the repo
+
+## The five things reviewers ask about
+
+1. No build step. Styles are source files linked with `<link rel="stylesheet/dssl">` or embedded in the page as `<style type="text/dssl">` / `<script type="text/dssl">` blocks (auto-booted in document order). The engine restyles the live DOM, including nodes added later.
+2. Honest trade: it is a JS runtime. If JavaScript is unavailable the page renders unstyled. For content pages that must not happen, use prerendering (snapshot the engine's first pass to static HTML; planned, tracked in PARITY.md) or choose another tool. The engine's own docs say this plainly.
+3. Exit cost is zero. Abandoning DSSL leaves you a page of valid inline styles and one small shadow stylesheet for pseudo-elements. There is nothing to un-install from your markup.
+4. Speed has a handbrake. `DSSL.freeze()` detaches every observer and listener after first paint and leaves the resolved look at zero engine cost; `unfreeze()` re-arms. A gate prefilter skips obvious non-matches before native matching. The Bench page on the site measures 100 / 1,000 / 10,000 nodes on your machine: CSS `<style>` vs DSSL live vs DSSL frozen.
+5. The cascade is (layer, source order). No specificity, no !important. Nested state blocks sort after the parent rule's own declarations (v0.7.2 fix: they used to lose), and nested `@media`/`@signal`/`@layer` keep their condition. `pin { }` is the only must-win block. The compiler refuses to guess: unknown tokens, properties and values fail loudly with did-you-mean; `--*` custom properties pass through unvalidated on purpose.
+
+## Language surface (v0.7.2)
+
+- Selectors: the full CSS surface rides native matching, including `:nth-child()`, `:not()`, `:is()`, `:where()`, `:has()`, combinators, attributes, nesting with `&`.
+- States as nested blocks: `hover`, `focus`, `focus-visible`, `active`, `disabled`, `checked`, `empty`, `target`, plus `seen` (fires once on first viewport entry, composes with `stagger:`).
+- Tokens built in: `color.*`, `space.1-8`, `radius.*`, `shadow.*`, `font.*`; custom `tokens { }` blocks with numeric keys (`space { 9: 96 }`), alpha suffixes (`color.ink/85`), per-subtree re-declaration (`--color.accent: color.err`).
+- Layout sugar: `row: gap space.4 between center`, `column:`, `grid: 3 gap 12`, `stack: center`, `center: both` (promotes a formatting context so alignment can never silently no-op), `size: 40 20`.
+- Pseudo-elements (`::before`, `::after`, `::placeholder`, `::selection`, `::marker`, `::backdrop`, `::first-line`, `::first-letter`, vendor ones) compile to one real shadow stylesheet; unknown pseudo names are compile errors.
+- Conditions: `@media` (with `dark`, `light`, `reduced-motion` sugar and `<=` ranges), `@container`, `@signal menuOpen { }` bridged from `DSSL.signal()`, `@layer base|components|utilities`, `pin { }`.
+- Motion: `motion name { from { } to { } }` via WAAPI; `animate: pulse 1600 infinite alternate`; `stagger: 70`; reduced-motion respected unless a motion declares `essential`.
+- Deform family: `bend`, `bend-y`, `bend-up`, `fold`, `stretch` (volume-honest squash), `bend-around` (children ride an arc). Compose into the one transform channel, state- and transition-friendly.
+- Gradients as sentences: `gradient: linear 135, color.accent -> color.ok`, `gradient-text:`, `gradient-flow: 6s alternate`. Non-color stops are compile errors.
+- Overlap policy: nothing below 100% opacity overlaps anything unless `overlap: allow`; `deny` is unconditional; pairs with `pointer-events: none` so veils stop eating clicks and text selection.
+- Behaviors: named rule groups applied with `use focus-ring`.
+- v0.7.2 review-driven fixes, all regression-tested: gate prefilter runs before native matches(); hover state events scope candidate recomputation to the touched subtree plus ancestors (was page-wide); checkbox/details states listen to `change`/`toggle`; raw hex alpha (`#ff0000/50` -> color-mix); bare numbers on time properties are ms; `::part()` supported, `::slotted()` rejected with an explanation; SVG properties (`fill`, `stroke*`) and `text-wrap`/`content-visibility` in the vocabulary.
+- Warnings channel (v0.7): things that compile but are probably wrong, e.g. a layout shorthand expanding to `display` and clobbering an earlier explicit `display:` in the same rule.
+
+## JS API
+
+```js
+DSSL.load(['/styles/site.dssl'])   // fetch + apply, in order
+DSSL.apply(src, { scope, name })   // scoped engines for widgets
+DSSL.compile(src)                  // parse + resolve, no DOM (powers editors)
+DSSL.signal('menuOpen', true)      // the JS -> styles bridge
+DSSL.freeze() / DSSL.unfreeze()    // the speed handbrake
+DSSL.explain(el, { quiet: true })  // matched rules, file/line, winning decls per property
+DSSL.replay(sel) / DSSL.refresh() / DSSL.errors() / DSSL.version
+```
+
+Wait for the `dssl-ready` event on `window` before measuring layout: the engine styles the DOM after DOMContentLoaded, and scripts that measure earlier read a half-styled world.
+
+## Editor support
+
+The official extension (VS Code and VSCodium, same .vsix) bundles the real parser and resolver: diagnostics identical to the browser console, completions from the workspace token registry, hover docs for the semantic vocabulary. Source lives in `dssl-vscode/` in the repo.

public/dssl/engine.js

@@ -228,6 +228,25 @@ export class DsslEngine {
     on('pointerdown', (e) => this.stateEvent('active', e.target));
     on('pointerup', (e) => this.stateEvent('active', e.target));
     on('pointercancel', (e) => this.stateEvent('active', e.target));
+    // v0.7.2 — form-state events. checked/indeterminate live on properties
+    // the pointer and focus listeners never see: unchecking with Space went
+    // stale, and programmatic el.checked = true never restyled until focus
+    // moved. change bubbles, so delegation reaches it. toggle does NOT
+    // bubble — a capture-phase listener on document still catches it on the
+    // way down. Note for docs: programmatic property writes fire no event at
+    // all; dispatch a bubbling change event after setting .checked.
+    on('change', (e) => {
+      const t = e.target;
+      if (!t || t.nodeType !== 1) return;
+      this.stateEvent('checked', t);
+      this.stateEvent('disabled', t);
+      this.stateEvent('indeterminate', t);
+    });
+    {
+      const tgl = (e) => { const t = e.target; if (t && t.nodeType === 1) this.stateEvent('open', t); };
+      document.addEventListener('toggle', tgl, true);
+      this._listeners.push({ target: document, type: 'toggle', fn: tgl, opts: true });
+    }
 
     // --- DOM mutations ---
     const mo = new MutationObserver((muts) => {
@@ -368,19 +387,56 @@ export class DsslEngine {
       node = node.parentElement;
     }
 
+    // v0.7.2 — candidate collection is no longer page-wide. The external
+    // review measured 33,060 recomputes for hovering 8 cards in a 1k-card
+    // page: every state event queried the whole document for EVERY stateful
+    // rule and batched every match. Reality: a subject-state rule (.card:hover)
+    // can only ever change the chain collected above. Rules where the state
+    // sits on an ANCESTOR compound (.card:hover .title) reach further down —
+    // queried from the matching ancestor via :scope, so the cost is bounded
+    // by that ancestor's subtree, never the page. computeElement re-checks
+    // the full stateful selector, so a superset batch is only wasted work,
+    // never wrong output.
     for (const rule of this.rules) {
       const hit = rule.states.has(state) || (state === 'focus' && rule.states.has('focus-visible')) || (state === 'focus-visible' && rule.states.has('focus'));
       if (!hit) continue;
-      // v0.3 fix: query the state-less base selector. On pointerout the
-      // element that just LEFT hover no longer matches `:hover` — querying
-      // the stateful selector skipped it and the hover styles stuck forever.
-      // The base selector is a superset; computeElement re-evaluates the
-      // real (stateful) match, so both entering and leaving are handled.
-      const base = rule.sel.replace(STATE_PSEUDO_RE, '').trim() || '*';
-      let els;
-      try { els = (this.scope || document).querySelectorAll(base); }
-      catch { try { els = (this.scope || document).querySelectorAll(rule.sel); } catch { continue; } }
-      els.forEach(el => batch.add(el));
+      const reach = rule._reach !== undefined ? rule._reach : (rule._reach = stateReach(rule.sel, state));
+      if (reach === null) continue; // subject-state: the chain covers it
+      if (reach.fallback) {
+        // :has()/:not() wrappers defeat the cheap strip — keep the old
+        // page-wide superset for this rare shape
+        const base = rule.sel.replace(STATE_PSEUDO_RE, '').trim() || '*';
+        let els; try { els = (this.scope || document).querySelectorAll(base); } catch { continue; }
+        els.forEach(el => batch.add(el));
+        continue;
+      }
+      for (const anc of batch) {
+        let prefixOK;
+        try { prefixOK = anc.matches(reach.prefix); } catch { prefixOK = false; }
+        if (!prefixOK) continue;
+        if (reach.sib) {
+          // sibling tails: querySelectorAll cannot leave the subtree, so walk
+          // the siblings by hand (+ stops at the first; ~ keeps scanning)
+          let sib = anc.nextElementSibling;
+          while (sib) {
+            let hitSib = false;
+            try { hitSib = sib.matches(reach.firstSeg); } catch { hitSib = false; }
+            if (hitSib) {
+              batch.add(sib);
+              if (reach.restAfter) {
+                let sub; try { sub = sib.querySelectorAll(reach.restAfter); } catch { sub = null; }
+                if (sub) sub.forEach(x => batch.add(x));
+              }
+            }
+            if (reach.sib === '+') break;
+            sib = sib.nextElementSibling;
+          }
+          continue;
+        }
+        let els;
+        try { els = anc.querySelectorAll(':scope ' + reach.rest); } catch { continue; }
+        els.forEach(el => batch.add(el));
+      }
     }
     if (batch.size) this.schedule(batch);
   }
@@ -489,6 +545,14 @@ export class DsslEngine {
       if (rule.sel === ':root') {
         if (el !== rootEl) continue;
       } else {
+        // v0.7.2 — the gate now runs BEFORE native matches(). The external
+        // review caught the wrong order: every element paid a full el.matches()
+        // for every rule even when the cheap gate could say no. Same contract
+        // as v0.7.0: the gate only ever says NO, and bails to null on anything
+        // it does not fully understand — a missed optimization beats a missed
+        // match.
+        const gate = rule._gate !== undefined ? rule._gate : (rule._gate = gateFor(rule.sel));
+        if (gate && !gatePass(el, gate)) continue;
         let sel = rule.sel;
         if (rule.states.has('seen')) {
           // v0.4.0 — `seen` belongs to the engine, not to CSS selectors: until
@@ -499,16 +563,6 @@ export class DsslEngine {
         }
         if (!this.matches(el, sel)) continue;
       }
-      // v0.7.0 — gate prefilter: skip the native matches() call when the
-      // element obviously cannot match (missing class/tag/id). gateFor is
-      // conservative — it only ever says NO, and bails to null on anything
-      // it does not fully understand, so a missed optimization beats a
-      // missed match. This is the cheap half of the speed story; freeze()
-      // is the big half.
-      {
-        const gate = rule._gate !== undefined ? rule._gate : (rule._gate = gateFor(rule.sel));
-        if (gate && !gatePass(el, gate)) continue;
-      }
       if (!rule.media.every(q => this.mql(q).matches)) continue;
       if (!this.signalsPass(rule)) continue;
       if (!this.containerPass(el, rule)) continue;
@@ -1422,6 +1476,50 @@ export function gateFor(sel) {
 }
 
 /* Duck-typed on purpose: tests drive it with fake elements. */
+/* v0.7.2 — stateReach: where can a state change reach in the DOM?
+ * Pure and exported for tests. Given a stateful selector and the state that
+ * just flipped on some element, it answers:
+ *   null              → subject-state (state on the rightmost compound): only
+ *                       the event chain can change, no query needed at all
+ *   { fallback:true } → the cheap strip cannot handle it (:has()/:not()
+ *                       wrappers): caller keeps the page-wide superset
+ *   { prefix, rest }  → batch every chain element matching `prefix` (the part
+ *                       up to and including the stateful compound, states
+ *                       stripped) and query `:scope` + `rest` under each
+ *   { prefix, sib, firstSeg, restAfter } → the tail starts with a sibling
+ *                       combinator; walk that element's siblings manually
+ *                       (querySelectorAll cannot leave the subtree)
+ */
+export function stateReach(sel, state) {
+  const segs = [];
+  let depth = 0, cur = '', pendingComb = '';
+  for (let i = 0; i < sel.length; i++) {
+    const c = sel[i];
+    if (c === '(' || c === '[') depth++;
+    else if (c === ')' || c === ']') depth = Math.max(0, depth - 1);
+    if (depth === 0 && (c === '>' || c === '+' || c === '~' || /\s/.test(c))) {
+      const comb = c === ' ' ? ' ' : c;
+      if (cur.trim()) { segs.push({ comb: pendingComb || ' ', seg: cur.trim() }); cur = ''; pendingComb = comb; }
+      else if (comb !== ' ') pendingComb = comb;
+      continue;
+    }
+    cur += c;
+  }
+  if (cur.trim()) segs.push({ comb: pendingComb || ' ', seg: cur.trim() });
+  if (segs.length <= 1) return null;
+  const idx = segs.findIndex(s => new RegExp(':' + state + '\\b').test(s.seg));
+  if (idx === -1 || idx === segs.length - 1) return null;
+  const prefix = segs.slice(0, idx + 1).map(s => s.seg).join(' ').replace(STATE_PSEUDO_RE, '').trim();
+  if (!prefix || /\(\s*\)/.test(prefix)) return { fallback: true };
+  const tail = segs.slice(idx + 1);
+  if (tail[0].comb === '+' || tail[0].comb === '~') {
+    const restAfter = tail.slice(1).map(s => (s.comb === ' ' ? ' ' : ' ' + s.comb + ' ') + s.seg).join('').trim();
+    return { prefix, sib: tail[0].comb, firstSeg: tail[0].seg, restAfter };
+  }
+  const rest = tail.map(s => (s.comb === ' ' ? ' ' : ' ' + s.comb + ' ') + s.seg).join('').trim();
+  return { prefix, rest };
+}
+
 export function gatePass(el, gate) {
   if (!gate) return true;
   for (const g of gate) {

public/dssl/index.js

@@ -18,7 +18,7 @@ import { parse } from './parser.js';
 import { resolve, DEFAULT_TOKENS } from './resolver.js';
 import { DsslEngine } from './engine.js';
 
-export const VERSION = '0.7.1';
+export const VERSION = '0.7.2';
 
 let counter = 0;
 const engines = new Map();
@@ -205,7 +205,9 @@ if (typeof window !== 'undefined') {
   const boot = async () => {
     try {
       const links = [...document.querySelectorAll('link[rel="stylesheet/dssl"]')];
-      const inlines = [...document.querySelectorAll('style[type="text/dssl"]')];
+      // v0.7.2 — inline DSSL blocks also work as <script type="text/dssl">
+      // (some editors highlight/parse those better than an unknown style type)
+      const inlines = [...document.querySelectorAll('style[type="text/dssl"], script[type="text/dssl"]')];
 
       const sources = [];
       for (const l of links) sources.push({ name: l.getAttribute('href'), kind: 'link', el: l });

public/dssl/parser.js

@@ -12,7 +12,7 @@
  * resolution happens in resolver.js.
  * ========================================================================= */
 
-const STATE_WORDS = new Set([
+export const STATE_WORDS = new Set([
   'hover', 'focus', 'focus-visible', 'active', 'disabled', 'checked',
   'empty', 'target', 'required', 'invalid', 'valid', 'open', 'closed',
   'placeholder-shown', 'read-only', 'read-write', 'enabled',
@@ -28,6 +28,11 @@ const STATE_WORDS = new Set([
 export const PSEUDO_ELEMENTS = new Set([
   'before', 'after', 'placeholder', 'selection', 'marker',
   'first-line', 'first-letter', 'backdrop', 'file-selector-button',
+  // v0.7.2 — ::part() rides the shadow-CSS pipeline (a document stylesheet
+  // CAN style shadow parts of custom elements). ::slotted() is accepted by
+  // the parser but rejected by the resolver with a loud explanation: it only
+  // exists inside a shadow tree, which is not a place DSSL styles.
+  'part', 'slotted',
 ]);
 
 // v0.4.2 — vendor pseudo-elements pass through verbatim (::-webkit-scrollbar
@@ -50,6 +55,20 @@ function scanFor(str, ch, from = 0) {
   return -1;
 }
 
+/** find index of LAST top-level occurrence of `ch` (skips strings + parens) */
+function scanForLast(str, ch) {
+  let depth = 0, q = null, found = -1;
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (q) { if (c === q && str[i - 1] !== '\\') q = null; continue; }
+    if (c === '"' || c === "'") { q = c; continue; }
+    if (c === '(' || c === '[') { depth++; continue; }
+    if (c === ')' || c === ']') { depth = Math.max(0, depth - 1); continue; }
+    if (depth === 0 && c === ch) found = i;
+  }
+  return found;
+}
+
 /** split a string on a top-level separator */
 function splitTop(str, sep) {
   const out = [];
@@ -158,6 +177,26 @@ export function parse(source, file = 'inline.dssl') {
 
       if (open !== -1) {
         const header = rest.slice(0, open).trim();
+        // v0.7.2 — declarations and a nested block sharing one line:
+        // `.card { background: red; hover { ... } }`. Everything before the
+        // header used to be swallowed whole into it, so `background: red`
+        // silently became part of a selector named "background: red; hover"
+        // and vanished. Declarations before the LAST top-level ';' are now
+        // processed as declarations; the header is what follows them.
+        if (header) {
+          const semi = scanForLast(header, ';');
+          if (semi !== -1) {
+            processContent(header.slice(0, semi), line);
+            const realHeader = header.slice(semi + 1).trim();
+            if (!realHeader) { err(line, 'block is missing a header before "{"'); rest = rest.slice(open + 1); continue; }
+            const meta = classify(realHeader, line);
+            const node = { ...meta, line, children: [] };
+            stack[stack.length - 1].children.push(node);
+            if (meta.kind !== 'bogus') stack.push(node);
+            rest = rest.slice(open + 1);
+            continue;
+          }
+        }
         if (!header) { err(line, 'block is missing a header before "{"'); rest = rest.slice(open + 1); continue; }
         const meta = classify(header, line);
         const node = { ...meta, line, children: [] };

public/dssl/resolver.js

@@ -20,7 +20,7 @@
 import { levenshtein, didYouMean, composeDeform } from './utils.js';
 // v0.5.0 — the resolver validates the `::name` half of full selectors so a
 // typo like .card::befor is a LOUD error, never a silently dead rule.
-import { PSEUDO_ELEMENTS, VENDOR_PSEUDO } from './parser.js';
+import { PSEUDO_ELEMENTS, VENDOR_PSEUDO, STATE_WORDS } from './parser.js';
 
 /* ------------------------------------------------------------------ *
  * Vocabulary
@@ -68,11 +68,19 @@ const UNITLESS_PROPS = new Set([
   'opacity', 'line-height', 'z-index', 'font-weight', 'flex-grow', 'flex-shrink',
   'flex', 'order', 'scale', 'widows', 'orphans', 'column-count', 'aspect-ratio',
   'animation-iteration-count', 'flood-opacity', 'fill-opacity', 'stop-opacity',
-  'shape-image-threshold', 'animation-delay', 'transition-delay',
+  'shape-image-threshold',
   // grid line placement takes integers, not lengths:  grid-column: span 2
   'grid-row', 'grid-column', 'grid-area',
 ]);
 
+// v0.7.2 — time properties: a bare number is milliseconds, never px, and
+// never unitless (both used to emit values the browser silently rejected).
+// transition-delay/animation-delay used to sit in UNITLESS_PROPS, which is
+// why `transition-delay: 200` shipped as invalid unitless 200.
+const TIME_PROPS = new Set([
+  'transition-delay', 'transition-duration', 'animation-delay', 'animation-duration',
+]);
+
 // A practical whitelist of standard CSS properties (loud errors beat silent ones)
 const KNOWN_PROPS = new Set(('all,appearance,accent-color,align-content,align-items,align-self,align-tracks,aspect-ratio,' +
   'backdrop-filter,backface-visibility,background,background-attachment,background-blend-mode,background-clip,background-color,background-image,background-origin,background-position,background-repeat,background-size,' +
@@ -82,8 +90,8 @@ const KNOWN_PROPS = new Set(('all,appearance,accent-color,align-content,align-it
   'border-inline,border-inline-color,border-inline-end,border-inline-end-color,border-inline-end-style,border-inline-end-width,border-inline-start,border-inline-start-color,border-inline-start-style,border-inline-start-width,border-inline-style,border-inline-width,' +
   'border-left,border-left-color,border-left-style,border-left-width,border-radius,border-right,border-right-color,border-right-style,border-right-width,' +
   'border-spacing,border-start-end-radius,border-start-start-radius,border-style,border-top,border-top-color,border-top-left-radius,border-top-right-radius,border-top-style,border-top-width,border-width,' +
-  'bottom,box-decoration-break,box-shadow,box-sizing,break-after,break-before,break-inside,caret-color,caret-shape,clear,clip,clip-path,color,color-scheme,column-count,column-fill,column-gap,column-rule,column-rule-color,column-rule-style,column-rule-width,column-span,column-width,columns,contain,contain-intrinsic-size,container,container-name,container-type,content,cursor,caret,display,empty-cells,filter,flex,flex-basis,flex-direction,flex-flow,flex-grow,flex-shrink,flex-wrap,float,font,font-family,font-feature-settings,font-kerning,font-language-override,font-optical-sizing,font-palette,font-size,font-size-adjust,font-stretch,font-style,font-synthesis,font-variant,font-variant-caps,font-variant-east-asian,font-variant-ligatures,font-variant-numeric,font-variant-position,font-variation-settings,font-weight,forced-color-adjust,gap,grid,grid-area,grid-auto-columns,grid-auto-flow,grid-auto-rows,grid-column,grid-column-end,grid-column-gap,grid-column-start,grid-gap,grid-row,grid-row-end,grid-row-gap,grid-row-start,grid-template,grid-template-areas,grid-template-columns,grid-template-rows,' +
-  'hanging-punctuation,height,hyphenate-character,hyphenate-limit-chars,hyphens,image-orientation,image-rendering,inline-size,inset,inset-block,inset-block-end,inset-block-start,inset-inline,inset-inline-end,inset-inline-start,isolation,justify-content,justify-items,justify-self,justify-tracks,left,letter-spacing,line-break,line-height,list-style,list-style-image,list-style-position,list-style-type,margin,margin-block,margin-block-end,margin-block-start,margin-bottom,margin-inline,margin-inline-end,margin-inline-start,margin-left,margin-right,margin-top,margin-trim,mask,mask-border,mask-border-mode,mask-border-outset,mask-border-repeat,mask-border-slice,mask-border-source,mask-border-width,mask-clip,mask-composite,mask-image,mask-mode,mask-origin,mask-position,mask-repeat,mask-size,max-height,max-inline-size,max-width,min-block-size,min-height,min-inline-size,min-width,mix-blend-mode,object-fit,object-position,offset,offset-anchor,offset-distance,offset-path,offset-rotate,opacity,order,outline,outline-color,outline-offset,outline-style,outline-width,overflow,overflow-anchor,overflow-clip-margin,overflow-wrap,overflow-x,overflow-y,overscroll-behavior,overscroll-behavior-block,overscroll-behavior-inline,overscroll-behavior-x,overscroll-behavior-y,padding,padding-block,padding-block-end,padding-block-start,padding-bottom,padding-inline,padding-inline-end,padding-inline-start,padding-left,padding-right,padding-top,page-break-after,page-break-before,page-break-inside,paint-order,perspective,perspective-origin,place-content,place-items,place-self,pointer-events,position,print-color-adjust,quotes,resize,right,rotate,row-gap,ruby-align,ruby-merge,scale,scroll-behavior,scroll-margin,scroll-margin-block,scroll-margin-block-end,scroll-margin-block-start,scroll-margin-bottom,scroll-margin-inline,scroll-margin-inline-end,scroll-margin-inline-start,scroll-margin-left,scroll-margin-right,scroll-margin-top,scroll-padding,scroll-padding-block,scroll-padding-bottom,scroll-padding-inline,scroll-padding-left,scroll-padding-right,scroll-padding-top,scroll-snap-align,scroll-snap-stop,scroll-snap-type,scrollbar-color,scrollbar-gutter,scrollbar-width,shape-image-threshold,shape-margin,shape-outside,tab-size,table-layout,text-align,text-align-last,text-combine-upright,text-decoration,text-decoration-color,text-decoration-line,text-decoration-skip-ink,text-decoration-style,text-decoration-thickness,text-emphasis,text-emphasis-color,text-emphasis-position,text-emphasis-style,text-indent,text-justify,text-orientation,text-overflow,text-rendering,text-shadow,text-transform,text-underline-offset,text-underline-position,top,touch-action,transform,transform-box,transform-origin,transform-style,transition,transition-behavior,transition-delay,transition-duration,transition-property,transition-timing-function,translate,unicode-bidi,user-select,vertical-align,visibility,white-space,white-space-collapse,width,will-change,word-break,word-spacing,word-wrap,writing-mode,z-index,zoom,' +
+  'bottom,box-decoration-break,box-shadow,box-sizing,break-after,break-before,break-inside,caret-color,caret-shape,clear,clip,clip-path,color,color-scheme,column-count,column-fill,column-gap,column-rule,column-rule-color,column-rule-style,column-rule-width,column-span,column-width,columns,contain,contain-intrinsic-size,container,container-name,container-type,content,content-visibility,cursor,caret,display,empty-cells,filter,flex,flex-basis,flex-direction,flex-flow,flex-grow,flex-shrink,flex-wrap,float,fill,fill-rule,fill-opacity,stroke,stroke-dasharray,stroke-dashoffset,stroke-linecap,stroke-linejoin,stroke-opacity,stroke-width,font,font-family,font-feature-settings,font-kerning,font-language-override,font-optical-sizing,font-palette,font-size,font-size-adjust,font-stretch,font-style,font-synthesis,font-variant,font-variant-caps,font-variant-east-asian,font-variant-ligatures,font-variant-numeric,font-variant-position,font-variation-settings,font-weight,forced-color-adjust,gap,grid,grid-area,grid-auto-columns,grid-auto-flow,grid-auto-rows,grid-column,grid-column-end,grid-column-gap,grid-column-start,grid-gap,grid-row,grid-row-end,grid-row-gap,grid-row-start,grid-template,grid-template-areas,grid-template-columns,grid-template-rows,' +
+  'hanging-punctuation,height,hyphenate-character,hyphenate-limit-chars,hyphens,image-orientation,image-rendering,inline-size,inset,inset-block,inset-block-end,inset-block-start,inset-inline,inset-inline-end,inset-inline-start,isolation,justify-content,justify-items,justify-self,justify-tracks,left,letter-spacing,line-break,line-height,list-style,list-style-image,list-style-position,list-style-type,margin,margin-block,margin-block-end,margin-block-start,margin-bottom,margin-inline,margin-inline-end,margin-inline-start,margin-left,margin-right,margin-top,margin-trim,mask,mask-border,mask-border-mode,mask-border-outset,mask-border-repeat,mask-border-slice,mask-border-source,mask-border-width,mask-clip,mask-composite,mask-image,mask-mode,mask-origin,mask-position,mask-repeat,mask-size,max-height,max-inline-size,max-width,min-block-size,min-height,min-inline-size,min-width,mix-blend-mode,object-fit,object-position,offset,offset-anchor,offset-distance,offset-path,offset-rotate,opacity,order,outline,outline-color,outline-offset,outline-style,outline-width,overflow,overflow-anchor,overflow-clip-margin,overflow-wrap,overflow-x,overflow-y,overscroll-behavior,overscroll-behavior-block,overscroll-behavior-inline,overscroll-behavior-x,overscroll-behavior-y,padding,padding-block,padding-block-end,padding-block-start,padding-bottom,padding-inline,padding-inline-end,padding-inline-start,padding-left,padding-right,padding-top,page-break-after,page-break-before,page-break-inside,paint-order,perspective,perspective-origin,place-content,place-items,place-self,pointer-events,position,print-color-adjust,quotes,resize,right,rotate,row-gap,ruby-align,ruby-merge,scale,scroll-behavior,scroll-margin,scroll-margin-block,scroll-margin-block-end,scroll-margin-block-start,scroll-margin-bottom,scroll-margin-inline,scroll-margin-inline-end,scroll-margin-inline-start,scroll-margin-left,scroll-margin-right,scroll-margin-top,scroll-padding,scroll-padding-block,scroll-padding-bottom,scroll-padding-inline,scroll-padding-left,scroll-padding-right,scroll-padding-top,scroll-snap-align,scroll-snap-stop,scroll-snap-type,scrollbar-color,scrollbar-gutter,scrollbar-width,shape-image-threshold,shape-margin,shape-outside,tab-size,table-layout,text-align,text-align-last,text-combine-upright,text-decoration,text-decoration-color,text-decoration-line,text-decoration-skip-ink,text-decoration-style,text-decoration-thickness,text-emphasis,text-emphasis-color,text-emphasis-position,text-emphasis-style,text-indent,text-justify,text-orientation,text-overflow,text-rendering,text-shadow,text-transform,text-underline-offset,text-underline-position,text-wrap,top,touch-action,transform,transform-box,transform-origin,transform-style,transition,transition-behavior,transition-delay,transition-duration,transition-property,transition-timing-function,translate,unicode-bidi,user-select,vertical-align,visibility,white-space,white-space-collapse,width,will-change,word-break,word-spacing,word-wrap,writing-mode,z-index,zoom,' +
   'animation,animation-composition,animation-delay,animation-direction,animation-duration,animation-fill-mode,animation-iteration-count,animation-name,animation-play-state,animation-range,animation-timeline,animation-timing-function,' +
   'view-transition-name,interpolate-size,text-box,text-box-edge,text-box-trim,dynamic-range-limit,field-sizing,anchor-name,position-anchor,position-area,scroll-timeline,scroll-timeline-axis,scroll-timeline-name,timeline-scope,view-timeline,view-timeline-axis,view-timeline-name,' +
   '-webkit-background-clip,-webkit-text-fill-color,-webkit-box-orient,-webkit-line-clamp,-webkit-tap-highlight-color,-webkit-font-smoothing,-moz-osx-font-smoothing,-webkit-box-shadow,-webkit-text-stroke').split(','));
@@ -182,7 +190,7 @@ function resolveValue(raw, ctx) {
         unit = raw.slice(j, k).toLowerCase();
         j = k;
       }
-      out += num + (unit ? unit : (ctx.unitless ? '' : 'px'));
+      out += num + (unit ? unit : (ctx.unitless ? '' : TIME_PROPS.has(ctx.prop) ? 'ms' : 'px'));
       i = j;
       continue;
     }
@@ -267,8 +275,18 @@ function resolveValue(raw, ctx) {
     if (c === '#') { // hex color
       let j = i + 1;
       while (j < n && /[0-9a-fA-F]/.test(raw[j])) j++;
-      out += raw.slice(i, j);
+      const hex = raw.slice(i, j);
+      out += hex;
       i = j;
+      // v0.7.2 — alpha on a raw hex color: #ff0000/50 used to become
+      // #ff0000/50px (the bare number got the generic px treatment) — invalid
+      // CSS, silently dropped by the browser. Tokens always had /NN via
+      // color-mix; raw hex now gets the same treatment.
+      const am = raw.slice(i).match(/^\s*\/\s*([0-9.]+)\s*%?/);
+      if (am) {
+        out = out.slice(0, out.length - hex.length) + `color-mix(in oklab, ${hex} ${am[1]}%, transparent)`;
+        i += am[0].length;
+      }
       continue;
     }
     out += c;
@@ -510,15 +528,31 @@ const SEMANTIC = {
   column: (v, ctx) => parseFlexWords(v, ctx, 'column'),
   grid(v, ctx) {
     const atoms = v.split(/\s+/).filter(Boolean);
+    // v0.7.2 — `grid: 3 gap 12` (the documented form) used to die: the gap
+    // atoms were fed into grid-template-columns → "3px gap 12px", invalid.
+    // gap and rows are now first-class words of the shorthand.
+    let gap = null, rows = null;
+    const rest = [];
+    for (let i = 0; i < atoms.length; i++) {
+      if (atoms[i] === 'gap' && atoms[i + 1]) { gap = atoms[++i]; continue; }
+      if (atoms[i] === 'rows' && atoms[i + 1]) { rows = atoms[++i]; continue; }
+      rest.push(atoms[i]);
+    }
     let cols;
-    if (atoms.length === 1 && /^[0-9]+$/.test(atoms[0])) {
-      cols = `repeat(${atoms[0]}, 1fr)`;
-    } else if ((atoms[0] === 'auto-fill' || atoms[0] === 'auto-fit') && atoms[1]) {
-      cols = `repeat(${atoms[0]}, minmax(${len(atoms[1], ctx)}, 1fr))`;
+    if (!rest.length) {
+      ctx.errors.push({ file: ctx.file, line: ctx.line, message: 'grid needs columns', hint: 'grid: 3 · grid: auto-fill 200 · grid: 200px 1fr — optionally with gap N and rows N' });
+      cols = 'none';
+    } else if (rest.length === 1 && /^[0-9]+$/.test(rest[0])) {
+      cols = `repeat(${rest[0]}, 1fr)`;
+    } else if ((rest[0] === 'auto-fill' || rest[0] === 'auto-fit') && rest[1]) {
+      cols = `repeat(${rest[0]}, minmax(${len(rest[1], ctx)}, 1fr))`;
     } else {
-      cols = atoms.map(a => len(a, ctx)).join(' ');
+      cols = rest.map(a => len(a, ctx)).join(' ');
     }
-    return [{ prop: 'display', value: 'grid' }, { prop: 'grid-template-columns', value: cols }];
+    const out = [{ prop: 'display', value: 'grid' }, { prop: 'grid-template-columns', value: cols }];
+    if (gap) out.push({ prop: 'gap', value: len(gap, ctx) });
+    if (rows) out.push({ prop: 'grid-template-rows', value: /^[0-9]+$/.test(rows) ? `repeat(${rows}, 1fr)` : len(rows, ctx) });
+    return out;
   },
   stack(v, ctx) {
     const word = (v || 'center').trim();
@@ -1064,6 +1098,22 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null) {
   /* ---- main recursive walk ---- */
 
   const walk = (children, ctx, ctxRule) => {
+    // v0.7.2 — parent-first flush. Two real bugs lived here. (1) A nested
+    // block (hover { }, @media, a nested selector) was emitted BEFORE the
+    // parent's own declarations got their cascade order, so `background: red`
+    // on the parent always beat `hover { background: red }` nested inside it
+    // — the exact pattern the docs taught, and the external review's headline
+    // finding. (2) media/container/signal/layer blocks flushed with the
+    // PARENT context, dropping the condition or layer entirely: a nested
+    // `@media dark` was silently unconditional AND sorted before base.
+    // Nested blocks now flush everything the parent has said so far first,
+    // and every block flushes with the context it was actually walked with.
+    const flushPending = (line) => {
+      if (ctxRule && ctxRule.decls.length && ctx.sel) {
+        flush(ctxRule, ctx, line);
+        ctxRule.decls = [];
+      }
+    };
     for (const node of children) {
       switch (node.kind) {
         case 'decl': {
@@ -1091,6 +1141,11 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null) {
           break;
         }
         case 'selector': {
+          if (/^[a-zA-Z][a-zA-Z0-9-]*$/.test(node.sel) && ctx.sel) {
+            const near = didYouMean(node.sel.toLowerCase(), [...STATE_WORDS]);
+            if (near) warnings.push({ file, line: node.line, message: `"${node.sel}" compiled as a descendant selector ("${combine(ctx.sel, node.sel)}")`, hint: `if you meant the state, it is spelled "${near}" — this block currently styles descendants called <${node.sel}>` });
+          }
+          flushPending(node.line);
           const sel = ctx.sel === '' ? node.sel : combine(ctx.sel, node.sel);
           const childCtx = { ...ctx, sel };
           const sub = { decls: [] };
@@ -1103,7 +1158,19 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null) {
             errors.push({ file, line: node.line, message: `"${node.name}" needs a selector around it` });
             break;
           }
+          flushPending(node.line);
           const childCtx = { ...ctx, sel: ctx.sel + ':' + node.name };
+          // v0.7.2 — the arrow is motion/gradient-stop syntax; inside a seen
+          // block it compiled into an inline style the browser rejects, so the
+          // element just sat at its base style forever. Say so, loudly, and
+          // point at the two real patterns (final value, or a motion).
+          if (node.name === 'seen') {
+            for (const d of node.children) {
+              if (d.kind === 'decl' && typeof d.value === 'string' && d.value.includes('->')) {
+                errors.push({ file, line: d.line, message: `"${d.prop}: ${d.value}" — the -> arrow is motion syntax and does nothing inside seen { }`, hint: 'write the final style (seen { opacity: 1 }) or attach a motion (seen { animate: rise-in 400 })' });
+              }
+            }
+          }
           const sub = { decls: [] };
           walk(node.children, childCtx, sub);
           flush(sub, childCtx, node.line);
@@ -1111,31 +1178,39 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null) {
         }
         case 'media': {
           const q = normalizeMedia(node.query, { errors, file, line: node.line }, node.line);
+          flushPending(node.line);
+          const childCtx = { ...ctx, media: [...ctx.media, q] };
           const sub = { decls: [] };
-          walk(node.children, { ...ctx, media: [...ctx.media, q] }, sub);
-          flush(sub, ctx, node.line);
+          walk(node.children, childCtx, sub);
+          flush(sub, childCtx, node.line);
           break;
         }
         case 'container': {
           const q = normalizeMedia(node.query || '(min-width: 0)', { errors, file, line: node.line }, node.line);
+          flushPending(node.line);
+          const childCtx = { ...ctx, containers: [...ctx.containers, q] };
           const sub = { decls: [] };
-          walk(node.children, { ...ctx, containers: [...ctx.containers, q] }, sub);
-          flush(sub, ctx, node.line);
+          walk(node.children, childCtx, sub);
+          flush(sub, childCtx, node.line);
           break;
         }
         case 'signal': {
           const sig = parseSignal(node.expr, { errors, file, line: node.line }, node.line);
+          flushPending(node.line);
+          const childCtx = { ...ctx, signals: [...ctx.signals, sig] };
           const sub = { decls: [] };
-          walk(node.children, { ...ctx, signals: [...ctx.signals, sig] }, sub);
-          flush(sub, ctx, node.line);
+          walk(node.children, childCtx, sub);
+          flush(sub, childCtx, node.line);
           break;
         }
         case 'layer':
         case 'pin': {
           const layer = node.kind === 'pin' ? 'pin' : (['tokens', 'base', 'components', 'utilities', 'pin'].includes(node.name) ? node.name : 'components');
+          flushPending(node.line);
+          const childCtx = { ...ctx, layer };
           const sub = { decls: [] };
-          walk(node.children, { ...ctx, layer }, sub);
-          flush(sub, ctx, node.line);
+          walk(node.children, childCtx, sub);
+          flush(sub, childCtx, node.line);
           break;
         }
         case 'pseudo': {
@@ -1214,7 +1289,15 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null) {
           errors.push({
             file, line,
             message: `unknown pseudo-element "::${pseudo}"`,
-            hint: 'try ::before, ::after, ::selection, or a vendor one like ::-webkit-scrollbar-thumb',
+            hint: 'try ::before, ::after, ::selection, ::part(name), or a vendor one like ::-webkit-scrollbar-thumb',
+          });
+          continue;
+        }
+        if (name === 'slotted') {
+          errors.push({
+            file, line,
+            message: '::slotted() only exists inside a shadow tree, and DSSL styles the light DOM',
+            hint: 'style the slotted element itself with a normal selector — it IS reachable from the page',
           });
           continue;
         }

public/examples/hello.dssl

@@ -0,0 +1,39 @@
+// hello.dssl — a tiny starter stylesheet
+// bare numbers are px, hover is a nested state, /14 at the end of a color is alpha
+
+body {
+  background: #f5f0e4
+  color: #26201a
+  padding: 40
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif
+}
+
+h1 {
+  color: #7c2d2d
+}
+
+.card {
+  background: #fdfaf2
+  border: 1 solid #ddd2bc
+  radius: 6
+  padding: 24
+  box-shadow: 0 2 6 #26201a/14
+  transition: 200
+
+  hover {
+    box-shadow: 0 6 18 #26201a/16
+  }
+}
+
+button {
+  background: #7c2d2d
+  color: #f9efdd
+  padding: 10 18
+  radius: 6
+  border: 0
+  transition: 200
+
+  hover {
+    background: #5e1f1f
+  }
+}

scripts/dssl-smoke.mjs

@@ -182,7 +182,7 @@ const cardRule = doc.rules.find(r => r.sel === '.card');
 assert(cardRule, '.card rule exists');
 assert(cardRule.decls.some(d => d.prop === 'background' && d.value.includes('var(--dssl-color-card)')), 'background resolved to var');
 assert(cardRule.decls.some(d => d.prop === 'padding' && d.value.includes('var(--dssl-space-4)')), 'space.4 resolved to var ref');
-assert(cardRule.decls.some(d => d.prop === '@animate' && d.value.frames && d.value.frames.length === 1), 'animate wired with frames');
+assert(doc.rules.filter(r => r.sel === '.card').some(r => r.decls.some(d => d.prop === '@animate' && d.value.frames && d.value.frames.length === 1)), 'animate wired with frames');
 assert(doc.rules.some(r => r.sel === '.card:focus-visible'), 'behavior expanded into state selector');
 assert(doc.rules.some(r => r.sel === '.card:hover .tip'), 'nested state descendant composed');
 assert(doc.rules.some(r => r.sel === ':root' && r.signals.length === 1), 'signal token override rule');

scripts/push-to-github.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# DSSL project — permanent cloud backup to GitHub.
+# Usage: GITHUB_TOKEN=<your PAT> bash scripts/push-to-github.sh [repo-name]
+# Needs: classic PAT with `repo` scope, or fine-grained PAT with repo create rights.
+set -euo pipefail
+
+REPO_NAME="${1:-dssl-language}"
+API="https://api.github.com"
+
+: "${GITHUB_TOKEN:?Set GITHUB_TOKEN env var first (a GitHub Personal Access Token with repo scope)}"
+
+OWNER=$(curl -sf -H "Authorization: token $GITHUB_TOKEN" "$API/user" | python3 -c 'import json,sys;print(json.load(sys.stdin)["login"])')
+echo "Authenticated as: $OWNER"
+
+echo "Creating repo $OWNER/$REPO_NAME (skips if it already exists)..."
+HTTP=$(curl -s -o /tmp/gh-create.json -w "%{http_code}" -X POST \
+  -H "Authorization: token $GITHUB_TOKEN" -H "Accept: application/vnd.github+json" \
+  "$API/user/repos" -d "{\"name\":\"$REPO_NAME\",\"private\":true,\"description\":\"DSSL — a Domain Specific Style Language that replaces CSS (self-hosted engine, no CSS output)\"}")
+if [ "$HTTP" = "422" ]; then echo "Repo already exists — pushing into it."; else [ "$HTTP" = "201" ] && echo "Repo created."; fi
+
+cd /home/z/my-project
+git remote remove cloud 2>/dev/null || true
+git remote add cloud "https://x-access-token:$GITHUB_TOKEN@github.com/$OWNER/$REPO_NAME.git"
+git push -u cloud main
+git remote set-url cloud "https://github.com/$OWNER/$REPO_NAME.git"  # scrub token from .git/config
+echo "DONE — permanent backup live at https://github.com/$OWNER/$REPO_NAME"

scripts/repro-v072.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Reproduces every compiler-level claim from the external agent review (0.7.2 cycle).
+import { parse } from '/home/z/my-project/public/dssl/parser.js';
+import { resolve } from '/home/z/my-project/public/dssl/resolver.js';
+
+let fails = 0;
+function show(name, source, opts = {}) {
+  const { ast } = parse(source, 'repro.dssl');
+  const out = resolve(ast, 'repro.dssl', {});
+  console.log('== ' + name);
+  if (out.errors?.length) console.log('  ERRORS:', out.errors.map(e => e.message || e).join(' | '));
+  if (out.warnings?.length) console.log('  WARNINGS:', out.warnings.map(e => e.message || e).join(' | '));
+  for (const r of (out.rules || [])) {
+    console.log('  rule:', r.selector, JSON.stringify(r.decls || r.sets || r).slice(0, 220));
+  }
+  return out;
+}
+
+// 1. THE BIG ONE: nested state must sort after base
+show('nested hover vs base (cascade)', `
+.card {
+  background: #26201a
+  hover { background: #c0392b }
+}
+`);
+
+// 2. raw hex alpha
+show('raw hex /50 alpha', `
+.card { background: #ff0000/50 }
+`);
+
+// 3. transition-delay units
+show('transition-delay 200', `
+.card { transition-delay: 200 }
+`);
+
+// 4. grid gap shorthand
+show('grid: 3 gap 12', `
+.grid { grid: 3 gap 12 }
+`);
+
+// 5. shadow token def with bare ink
+show('shadow { md: 0 2 4 ink/10 }', `
+shadow { md: 0 2 4 ink/10 }
+`);
+
+// 6. seen block
+show('seen { opacity: 0 -> 1 } block', `
+.card { seen { opacity: 0 -> 1 } }
+`);
+show('seen as motion decl', `
+.card { seen: opacity 0 -> 1 }
+`);
+
+// 7. hovr typo nested
+show('nested hovr typo', `
+.card { hovr { background: red } }
+`);
+
+// 8. missing properties
+show('fill/stroke/text-wrap/content-visibility', `
+.card { fill: red; stroke: blue; stroke-width: 2; text-wrap: balance; content-visibility: auto }
+`);
+
+// 9. ::part / ::slotted
+show('::part selector', `
+my-card::part(header) { background: red }
+`);
+
+// 10. shadow: sm / hover shadow lg quickstart pattern
+show('README quickstart pattern', `
+.card { shadow: sm; hover { shadow: lg } }
+`);

scripts/test-guide-examples.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Compiles every ```dssl fenced block in GUIDE.md (strict: 0 errors allowed)
+// and reports README.md blocks (the README may carry teaching examples that
+// intentionally error; those are tagged with <!-- dssl:has-errors -->).
+import { readFileSync } from 'node:fs';
+import { parse } from '../public/dssl/parser.js';
+import { resolve, DEFAULT_TOKENS } from '../public/dssl/resolver.js';
+
+const files = [
+  { path: '/home/z/my-project/GUIDE.md', strict: true },
+  { path: '/home/z/hf-mirror/README.md', strict: false },
+];
+
+let pass = 0, fail = 0;
+for (const { path, strict } of files) {
+  let text;
+  try { text = readFileSync(path, 'utf8'); } catch { console.log('(skip missing ' + path + ')'); continue; }
+  const blocks = [...text.matchAll(/```dssl\n([\s\S]*?)```/g)].map(m => m[1]);
+  // whole-file workspace fold: seed with the engine's default tokens, collect
+  // every token defined anywhere in the document, then compile each block
+  // against the union. Guides are read non-linearly; examples may reference
+  // tokens from any example on the page.
+  let registry = { ...DEFAULT_TOKENS };
+  for (const src of blocks) {
+    const { ast, errors: pe } = parse(src, 'tokens-pass');
+    const doc = resolve(ast, 'tokens-pass', registry);
+    registry = { ...registry, ...doc.tokens };
+  }
+  blocks.forEach((src, i) => {
+    const name = `${path.split('/').pop()} block ${i + 1}`;
+    const { ast, errors: parseErrors } = parse(src, name);
+    const doc = resolve(ast, name, registry);
+    const errors = [...parseErrors, ...doc.errors];
+    if (errors.length === 0) { pass++; return; }
+    if (!strict && /dssl:has-errors/.test(src)) { pass++; return; }
+    fail++;
+    console.error(`FAIL ${name}:`);
+    for (const e of errors.slice(0, 4)) console.error('   line ' + (e.line ?? '?') + ': ' + e.message);
+  });
+  console.log(`${path.split('/').pop()}: ${blocks.length} blocks checked`);
+}
+console.log(`${pass} passed, ${fail} failed`);
+process.exitCode = fail ? 1 : 0;

scripts/test-v050.mjs

@@ -192,5 +192,81 @@ console.log(`\n${pass} passed, ${fail} failed`);
   check('11 bare content auto-quoted', c && c.value === '""', c && c.value);
 }
 
+console.log(`${pass} passed, ${fail} failed`);
+
+// 12. overlap policy — the "nothing below 100% opacity overlaps" feature
+{
+  const { doc, errors } = compile(`
+    body { overlap: auto }
+    .badge { overlap: deny }
+    .scrim { overlap: allow }
+    .off { overlap: none }
+  `);
+  check('12 no errors', errors.length === 0, JSON.stringify(errors));
+  const get = (sel) => doc.rules.find(r => r.sel === sel)?.decls.find(d => d.prop === '@overlap')?.value;
+  check('12 body policy = auto', get('body') === 'auto', get('body'));
+  check('12 deny passes through', get('.badge') === 'deny', get('.badge'));
+  check('12 allow passes through', get('.scrim') === 'allow', get('.scrim'));
+  check('12 none is an alias of allow', get('.off') === 'allow', get('.off'));
+
+  const bad = compile('.card { overlap: never }');
+  check('12 bad policy is a LOUD error', bad.errors.length === 1 && /unknown overlap policy/.test(bad.errors[0].message), JSON.stringify(bad.errors));
+  check('12 hint names the vocabulary', /allow|deny|auto/.test(bad.errors[0].hint || ''));
+
+  const dead = compile('.card { overlap: nevr }');
+  check('12 nothing emitted on error', dead.doc.rules.length === 0);
+
+  // site.dssl now carries the global switch — regression-guard it
+  const fs = await import('node:fs');
+  const site = fs.readFileSync(new URL('../public/styles/site.dssl', import.meta.url).pathname, 'utf8');
+  check('12 site.dssl body opts in', /overlap:\s*auto/.test(site));
+}
+
+// 13. the escape math (overlapNudge) — pure function, no DOM needed
+{
+  const { overlapNudge } = await import('../public/dssl/engine.js');
+  const box = (l, t, r, b) => ({ left: l, top: t, right: r, bottom: b });
+
+  // candidate [0,0,100,100] vs obstacle [50,0,150,100]: push left past the
+  // near edge costs 50, push right past the far edge costs 150 → left wins
+  let n = overlapNudge(box(0, 0, 100, 100), [box(50, 0, 150, 100)]);
+  check('13 shortest escape wins (left 50)', n.x === -50 && n.y === 0, JSON.stringify(n));
+
+  // deep obstacle above, 10px of y-penetration → dropping down 10 beats climbing 200
+  n = overlapNudge(box(0, 90, 200, 200), [box(0, 0, 200, 100)]);
+  check('13 vertical kiss resolves down 10', n.x === 0 && n.y === 10, JSON.stringify(n));
+
+  // no overlap → no nudge
+  n = overlapNudge(box(0, 0, 10, 10), [box(20, 20, 30, 30)]);
+  check('13 clear boxes stay put', n.x === 0 && n.y === 0, JSON.stringify(n));
+
+  // touching edges are NOT overlap (the shared-border tremble guard)
+  n = overlapNudge(box(0, 0, 100, 100), [box(100, 0, 200, 100)]);
+  check('13 touching edges do not count', n.x === 0 && n.y === 0, JSON.stringify(n));
+
+  // two walls with a real gap between them → nudge must land inside the gap
+  n = overlapNudge(box(70, 0, 90, 100), [box(0, 0, 80, 100), box(120, 0, 200, 100)]);
+  const cleared = (b, obs) => obs.every(o =>
+    Math.min(b.right, o.right) - Math.max(b.left, o.left) <= 0.01 ||
+    Math.min(b.bottom, o.bottom) - Math.max(b.top, o.top) <= 0.01);
+  const moved = box(70 + n.x, 0 + n.y, 90 + n.x, 100 + n.y);
+  check('13 box clears both walls into the gap', n.x === 10 && cleared(moved, [box(0, 0, 80, 100), box(120, 0, 200, 100)]), JSON.stringify({ n, moved }));
+}
+
+console.log(`${pass} passed, ${fail} failed`);
+
+// 14. engine-native props inside pseudo blocks fail loud (no junk shadow CSS)
+{
+  const a = compile('.card::before { animate: pop 400 }');
+  check('14 nested animate-in-pseudo is LOUD', a.errors.length === 1 && /engine-native/.test(a.errors[0].message), JSON.stringify(a.errors));
+  check('14 nothing leaked to shadow CSS', a.doc.shadowRules.length === 0 && a.doc.rules.length === 0);
+
+  const b = compile('.card::before { overlap: deny }');
+  check('14 top-level overlap-in-pseudo is LOUD', b.errors.length === 1 && /engine-native/.test(b.errors[0].message), JSON.stringify(b.errors));
+
+  const c = compile('.card { ::after { --x: 1 } }');
+  check('14 custom props still pass in pseudo blocks', c.errors.length === 0 && c.doc.shadowRules.length === 1, JSON.stringify(c.errors));
+}
+
 console.log(`${pass} passed, ${fail} failed`);
 process.exit(fail ? 1 : 0);

scripts/test-v070.mjs

@@ -126,7 +126,7 @@ console.log('5 — freeze/unfreeze/explain exist as API surface');
     ok(typeof eng.freeze === 'function', 'freeze exported');
     ok(typeof eng.unfreeze === 'function', 'unfreeze exported');
     ok(typeof eng.explain === 'function', 'explain exported');
-    ok(eng.VERSION === '0.7.0', 'VERSION is 0.7.0');
+    ok(parseInt(String(eng.VERSION).split('.')[1]) >= 7, 'VERSION is 0.7.x or newer');
     ok(typeof eng.DSSL.freeze === 'function' && typeof eng.DSSL.explain === 'function', 'DSSL object carries the new API');
   }
   const engMod = await import('../public/dssl/engine.js');

scripts/test-v072.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// v0.7.2 — regression suite for the external-review findings.
+// Every assertion maps to a reported bug or a fixed behavior.
+import { parse, STATE_WORDS } from '../public/dssl/parser.js';
+import { resolve } from '../public/dssl/resolver.js';
+import { VERSION } from '../public/dssl/index.js';
+import { stateReach, gatePass } from '../public/dssl/engine.js';
+
+let pass = 0, fail = 0;
+const ok = (cond, msg) => { if (cond) { pass++; } else { fail++; console.error('FAIL:', msg); } };
+
+function compile(src) {
+  const { ast, errors } = parse(src, 't.dssl');
+  const doc = resolve(ast, 't.dssl', {});
+  return { doc, parseErrors: errors };
+}
+const declsOf = (doc, sel) => doc.rules.filter(r => r.sel === sel).flatMap(r => r.decls);
+
+/* 1 — THE headline: nested state must sort AFTER the base rule */
+{
+  const { doc } = compile('.card {\n  background: #26201a\n  hover { background: #c0392b }\n}');
+  const base = doc.rules.find(r => r.sel === '.card');
+  const hov = doc.rules.find(r => r.sel === '.card:hover');
+  ok(base && hov, 'nested hover: both rules exist');
+  ok(hov.order > base.order, 'nested hover sorts after base (cascade fix)');
+  ok(declsOf(doc, '.card').some(d => d.value === '#26201a'), 'base declaration survives');
+  ok(declsOf(doc, '.card:hover').some(d => d.value === '#c0392b'), 'hover declaration survives');
+}
+/* 1b — nested media keeps its condition AND sorts after base */
+{
+  const { doc } = compile('.card {\n  color: red\n  @media dark { color: blue }\n}');
+  const dark = doc.rules.find(r => r.sel === '.card' && r.media.length);
+  ok(dark && dark.media.length === 1, 'nested @media keeps its condition');
+  const base = doc.rules.find(r => r.sel === '.card' && !r.media.length);
+  ok(dark && base && dark.order > base.order, 'nested @media sorts after base');
+}
+/* 1c — nested signal keeps its condition */
+{
+  const { doc } = compile('.card {\n  color: red\n  @signal on(true) { color: blue }\n}');
+  const sig = doc.rules.find(r => r.sel === '.card' && r.signals.length);
+  ok(sig && sig.signals.length === 1, 'nested @signal keeps its condition');
+}
+/* 1d — nested layer keeps its layer */
+{
+  const { doc } = compile('.card {\n  color: red\n  @layer utilities { color: blue }\n}');
+  const lay = doc.rules.find(r => r.sel === '.card' && r.layer === 'utilities');
+  ok(lay, 'nested @layer keeps its layer');
+}
+/* 1e — decls AFTER a nested block become a later fragment (later wins) */
+{
+  const { doc } = compile('.card {\n  color: red\n  hover { color: green }\n  color: blue\n}');
+  ok(declsOf(doc, '.card').some(d => d.value === 'red'), 'pre-block decl kept');
+  ok(declsOf(doc, '.card').some(d => d.value === 'blue'), 'post-block decl kept');
+  ok(declsOf(doc, '.card:hover').some(d => d.value === 'green'), 'nested decl kept');
+}
+/* 2 — raw hex alpha: #ff0000/50 is color-mix, never /50px */
+{
+  const { doc } = compile('.card { background: #ff0000/50 }');
+  const v = declsOf(doc, '.card')[0]?.value;
+  ok(v === 'color-mix(in oklab, #ff0000 50%, transparent)', 'raw hex /50 becomes color-mix, got: ' + v);
+}
+/* 3 — time properties: bare numbers are ms */
+{
+  const { doc } = compile('.card { transition-delay: 200; animation-duration: 0.5 }');
+  const d = declsOf(doc, '.card');
+  ok(d.some(x => x.prop === 'transition-delay' && x.value === '200ms'), 'transition-delay: 200 -> 200ms');
+  ok(d.some(x => x.prop === 'animation-duration' && x.value === '0.5ms' || x.prop === 'animation-duration' && x.value === '500ms'), 'animation-duration bare -> ms, got: ' + JSON.stringify(d));
+}
+/* 4 — grid shorthand: gap is a first-class word */
+{
+  const { doc } = compile('.grid { grid: 3 gap 12 }');
+  const d = declsOf(doc, '.grid');
+  ok(d.some(x => x.prop === 'grid-template-columns' && x.value === 'repeat(3, 1fr)'), 'grid: 3 -> repeat(3, 1fr)');
+  ok(d.some(x => x.prop === 'gap' && x.value === '12px'), 'grid gap 12 -> gap: 12px');
+  const { doc: d2 } = compile('.grid { grid: 2 rows 3 gap 8 }');
+  const d2l = declsOf(d2, '.grid');
+  ok(d2l.some(x => x.prop === 'grid-template-rows' && x.value === 'repeat(3, 1fr)'), 'grid rows 3 -> template rows');
+}
+/* 5 — seen { } with arrow is a LOUD error pointing at the real patterns */
+{
+  const { doc } = compile('.card { seen { opacity: 0 -> 1 } }');
+  ok(doc.errors.some(e => e.message.includes('->') && e.hint.includes('animate')), 'seen arrow -> loud error with animate hint');
+  const { doc: d2 } = compile('motion rise { from { opacity: 0 } }\n.card { seen { animate: rise 400 } }');
+  ok(d2.errors.length === 0, 'seen { animate } stays legal');
+}
+/* 6 — unknown nested state word warns instead of silently becoming a descendant */
+{
+  const { doc } = compile('.card { hovr { background: red } }');
+  ok(doc.warnings.some(w => w.message.includes('hovr') && w.hint.includes('hover')), 'hovr typo warns with did-you-mean');
+  const { doc: d2 } = compile('.card { title { color: red } }');
+  ok(!d2.warnings.some(w => w.message.includes('title')), 'legit descendant word does not warn');
+}
+/* 7 — SVG + modern properties pass through */
+{
+  const { doc } = compile('.card { fill: red; stroke: blue; stroke-width: 2; text-wrap: balance; content-visibility: auto }');
+  const d = declsOf(doc, '.card');
+  for (const [p, v] of [['fill', 'red'], ['stroke', 'blue'], ['stroke-width', '2px'], ['text-wrap', 'balance'], ['content-visibility', 'auto']]) {
+    ok(d.some(x => x.prop === p && x.value === v), `property ${p}: ${v} resolves`);
+  }
+}
+/* 8 — ::part() rides the shadow pipeline, ::slotted() is a loud error */
+{
+  const { doc } = compile('my-card::part(header) { background: red }');
+  ok(doc.errors.length === 0, '::part() compiles');
+  ok(doc.shadowRules.some(r => r.sel === 'my-card' && r.pseudo.includes('part(header)')), '::part() rides shadowRules');
+  const { doc: d2 } = compile('my-card::slotted(p) { background: red }');
+  ok(d2.errors.some(e => e.message.includes('shadow tree')), '::slotted() gets the shadow-tree explanation');
+}
+/* 9 — one-line decls + nested block on the same line */
+{
+  const { doc, parseErrors } = compile('.card { background: red; hover { background: blue } }');
+  ok(parseErrors.length === 0, 'one-line mix parses');
+  ok(declsOf(doc, '.card').some(d => d.value === 'red'), 'one-line: base decl survives');
+  ok(declsOf(doc, '.card:hover').some(d => d.value === 'blue'), 'one-line: hover decl survives');
+}
+/* 10 — stateReach: the hover scoping math */
+{
+  ok(stateReach('.card:hover', 'hover') === null, 'subject-state reach = null (chain only)');
+  const d = stateReach('.card:hover .title', 'hover');
+  ok(d && d.prefix === '.card' && d.rest === '.title', 'descendant reach: prefix .card rest .title');
+  const s = stateReach('.tab:hover + .panel', 'hover');
+  ok(s && s.sib === '+' && s.firstSeg === '.panel', 'sibling reach: + .panel');
+  const f = stateReach('.card:has(:hover) .x', 'hover');
+  ok(f && f.fallback === true, ':has() wrapper falls back to page-wide superset');
+  const deep = stateReach('.list .card:hover .title', 'hover');
+  ok(deep && deep.prefix === '.list .card' && deep.rest === '.title', 'deep ancestor prefix');
+}
+/* 11 — gatePass still duck-types on fake elements (unchanged contract) */
+{
+  ok(gatePass({ tagName: 'div', classList: { contains: () => true } }, null) === true, 'gatePass null gate = true');
+}
+/* 12 — version */
+{
+  ok(VERSION === '0.7.2', 'engine VERSION is 0.7.2');
+  ok(STATE_WORDS.has('hover') && STATE_WORDS.has('seen'), 'STATE_WORDS exported');
+}
+
+console.log(`${pass} passed, ${fail} failed`);
+process.exitCode = fail ? 1 : 0;