v0.15.0: the second game review

Aura follows moving things under reduced motion, skips invisible emitters (always keeps an anchor), z N
layers. dssl check, the console and DSSL.lint name rules a later rule always beats. Typed and scoped
signals that restyle only what their rules select; DSSL.flush/settled/computed; pauseMotion/stepMotion.
animate lists, DSSL.play on pseudo-elements, outline-shape, rotate: 5, states inside ::after, a clear
error for a CSS font shorthand, --engine for the CLI, quieter DSSL.lint.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

GUIDE.md

@@ -461,7 +461,7 @@ motion boing { 0%, 100% { translate: 0 0 } 40% { translate: 0 -18 } essential }
 
 ```dssl
 tokens { shadow { pop: 0 4 0 #000 }  radius { pill: 99 } }
-.tomato { gradient: linear 180, #f55 -> #b11 + radial-gradient(circle, #fff6 18%, transparent 20%) tile 24 offset 4 4 }
+.tomato { gradient: radial-gradient(circle, #fff6 18%, transparent 20%) tile 24 offset 4 4 + linear 180, #f55 -> #b11 }   // the dots come FIRST, so they sit ON TOP of the red
 .title  { text-stroke: 6 color.ink; font-size: 48 }              // an outline OUTSIDE the letters
 .badge  { shadow: pop; radius: pill }                             // your own shadow and radius tokens, by bare name
 .ring   { background: conic-gradient(from 0deg, red, blue) }      // from, at, in... all accepted
@@ -508,6 +508,89 @@ tokens { shadow { pop: 0 4 0 #000 }  radius { pill: 99 } }
 - The "rule aligns without display" check moved from `dssl check` (it cannot see another rule giving the same element `display: flex`,
   so it cried wolf) to the build report and to `DSSL.lint`, which know.
 
+### The second game review (0.15.0)
+
+The same builder came back with a second list after a real game. All of it is in.
+
+**Aura**
+
+- Under reduced motion the aura used to redraw twice a second, so a glow on something that moves lagged behind it. Now it takes a quick
+  look (a few rectangle reads, no drawing) every 100ms while nothing moves, and draws every frame for as long as anything it lights
+  moves, resizes or fades.
+- An emitter that cannot be seen no longer emits: `opacity: 0` on it or on any ancestor, `display: none`, `visibility: hidden`. What it
+  already let go fades with it. A hidden menu with a smoking icon stops smoking. An invisible anchor you WANT smoke to come out of
+  (`opacity: 0` on purpose) says `always`: `aura-particle: #888 -> transparent 40 up always`.
+- `z N` puts a layer on its own canvas at that z-index: `aura-glow: #f80 40 z 5` goes under a hill with `z-index: 10`, while the
+  default layer stays above everything (or wherever `DSSL.auraZ()` put it). The canvas sits in the page's root stacking context, so it
+  interleaves with the page's top-level positioned elements; something inside a transformed parent is a stacking context of its own.
+
+**Rules that never win.** There is no specificity, so the LATER rule wins. That means `.prop.broc { z-index: 1 }` in one file loses to a
+plain `.prop { z-index: 2 }` in a file loaded after it, and the first line does nothing. `dssl check` (with all the files, or the page),
+the browser console and `DSSL.lint` now say so, with both places:
+
+```
+a.dssl:1 - warning - z-index in ".prop.broc" can never apply: ".prop" (b.dssl:1) comes later, matches every element this rule matches...
+```
+
+It reports a rule only when the later one matches everything the earlier one does, sets the same property to a different value, and is
+unconditional in the same way (same `@media`, state, signal) and in the same or a higher layer. The very same selector twice is left
+alone: that is an override, on purpose. Fix it by moving the specific rule below the general one.
+
+**Signals**
+
+- They keep their type: `DSSL.signal('toasting', false)` then `DSSL.getSignal('toasting')` is `false`, a number is a number. The
+  `data-dssl-signal-*` attribute is text. A bare `@signal name { }` is off for `false`, `0`, `"0"` and `"false"`.
+- `DSSL.signal('screen', 'shop', el)` sets a signal for `el` and what is inside it. The nearest value wins, the page-wide one is the
+  fallback, `DSSL.signal('screen', null, el)` clears it, and `DSSL.getSignal('screen', el)` is the value an element sees. `::before`
+  and `::after` rules behind a signal follow it too.
+- A signal restyles only the elements its rules select (inside the scope, if you gave one), not the whole page, and several in one
+  task are one pass. A signal that no rule mentions costs nothing.
+
+**Styling is asynchronous, so there is a way to wait for it.** The engine styles new elements in a microtask. `await DSSL.settled()`
+(or the synchronous `DSSL.flush()`) styles everything that is waiting, right now, so `offsetTop`, `getBoundingClientRect()` and computed
+styles are final on the next line. `DSSL.computed(el, 'translate')` does a flush and then reads the computed value.
+
+**Several motions on one element**
+
+```dssl
+motion blink  { 0%, 90%, 100% { opacity: 1 } 95% { opacity: .2 } }
+motion waddle { from { rotate: -4 } to { rotate: 4 } }
+motion glint  { from { opacity: .3 } to { opacity: 1 } }
+motion bob2   { from { translate: 0 0 } to { translate: 0 6 } }
+.duck { animate: blink 300 infinite, waddle 900 infinite alternate }
+.duck::after { content: ""; animate: glint 700 infinite, bob2 1200 infinite essential }   // also on pseudo-elements, and `dssl build` writes them
+```
+
+`await DSSL.play(el, 'pop', { pseudo: '::after' })` plays a motion on a pseudo-element.
+
+**An outline that follows the shape**
+
+```dssl
+.sprite { outline-shape: 3 color.ink }       // follows the picture's alpha, not its box; outline-shape: none clears it
+```
+
+It is four hard drop-shadows, one in each direction, which is what you wrote by hand. Corners come out square. It uses `filter`, so a
+`filter:` on the same rule replaces it.
+
+**Small syntax**
+
+- `rotate: 5` is 5deg (`5deg`, `0.1turn`, `x 30` still work).
+- A state inside a pseudo-element block is that pseudo-element in that state:
+  `.btn { ::after { content: ""; opacity: 0; hover { opacity: 1 } } }`. This is the same rule as `.btn:hover::after`.
+- `font:` is size, line height and colour (`font: 16/1.5 color.ink`), not the CSS shorthand. Writing `font: bold 16px Arial` used to make
+  a 700px font; it is now an error that says so. Weight and family are `font-weight:` and `font-family:`.
+- In `gradient:` the FIRST layer is the one on top. The example in the 0.14.0 chapter had the dots last, behind the colour; it is fixed.
+
+**Checking**
+
+- `DSSL.lint` no longer measures invisible text (a closed menu at `opacity: 0`) and counts a stroke of 1px or more, or a tight shadow
+  (blur up to 4px), that sets the letters apart from it as readable. A soft glow does not rescue unreadable text.
+- `dssl check`, `build` and the rest take `--engine ./dssl` (or `DSSL_ENGINE=./dssl`) to use the engine in that folder, so the CLI file
+  can live anywhere.
+
+**For tests of a game**: `DSSL.pauseMotion()` freezes every animation on the page (and the ones started afterwards),
+`DSSL.stepMotion(250)` moves them all forward by exactly 250ms, `DSSL.resumeMotion()` lets them run.
+
 ### Fonts
 
 ```dssl
@@ -532,7 +615,9 @@ A family line is `Family: weights [italic] [display swap|block|fallback|optional
 .sheen   { gradient: radial at top left, #fff/40 -> transparent + linear 135, #123 -> #456 }
 ```
 
-`repeating` turns any kind into its repeating form. `in oklch` (or `oklab`, `hsl`, `lab`, `srgb`, with `longer hue` and friends) picks the colour space the blend happens in. A lone position between two stops is a midpoint. Two positions make a hard band. Bare numbers in a stop position are px (degrees on `conic`). `mesh` takes a base colour and blobs: `color at x y [size n]` (default size 60%). `+` joins layers, first on top. A direction is optional: `linear #f00 -> #00f` works.
+`repeating` turns any kind into its repeating form. `in oklch` (or `oklab`, `hsl`, `lab`, `srgb`, with `longer hue` and friends) picks the colour space the blend happens in. A lone position between two stops is a midpoint. Two positions make a hard band. Bare numbers in a stop position are px (degrees on `conic`). `mesh` takes a base colour and blobs: `color at x y [size n]` (default size 60%). `+` joins layers, and the FIRST one you write is the one on top (so the dots or the shine go first, the base colour last). A direction is optional: `linear #f00 -> #00f` works.
+
+Two look-alikes: `#f00 -> 30% -> #00f` puts the halfway point of the blend at 30% (a midpoint, no colour is placed there), while `#f00 30%, #00f` puts the colour red AT 30% (a stop; with two positions on one colour, `#f00 0 30%`, it holds red from 0 to 30%).
 
 ### Inspector and hot reload
 
@@ -791,13 +876,17 @@ and listed, so the file you get always compiles.
 ```js
 import { DSSL } from '/dssl/index.js'     // or just use window.DSSL after boot
 
-DSSL.version                          // "0.14.0": a string, not a function
+DSSL.version                          // "0.15.0": a string, not a function
 DSSL.compile(source)                  // { ok, errors, warnings, stats, doc }: parse and resolve, no DOM
 DSSL.apply(source, { name, scope, replace })
 await DSSL.load(['a.dssl', 'b.dssl'])
 DSSL.toCSS(source | [sources], opts)  // the exit lane: { css, map, report } (see `dssl build`)
-DSSL.signal('theme', 'dark')          // drives @signal rules
-DSSL.getSignal('theme')               // the current value
+DSSL.signal('theme', 'dark')          // drives @signal rules (booleans and numbers keep their type)
+DSSL.signal('hp', 2, el)              // only for el and what is inside it; the nearest wins
+DSSL.getSignal('theme')               // the current value (DSSL.getSignal('hp', el) for a scope)
+DSSL.flush() / await DSSL.settled()   // style everything waiting NOW: offsetTop and computed styles are final after it
+DSSL.computed(el, 'translate')        // the final computed value, nothing left waiting
+DSSL.pauseMotion() / DSSL.stepMotion(250) / DSSL.resumeMotion()   // freeze, step and release every animation (for tests)
 DSSL.refresh() / DSSL.refresh(el)     // recompute the page, or one subtree (even a static one)
 DSSL.replay(selector)                 // run entrance motions again
 DSSL.errors()                         // a function: the errors of the last compile
@@ -822,7 +911,7 @@ Three ways to get it:
 
 1. VSCodium: open the Extensions tab, search "DSSL" and install. It is on Open VSX:
    https://open-vsx.org/extension/ehs-studio/dssl-vscode
-2. VS Code: download `dssl-vscode/dssl-vscode-0.14.0.vsix` from the repo files, then
+2. VS Code: download `dssl-vscode/dssl-vscode-0.15.0.vsix` from the repo files, then
    Extensions panel, `...`, Install from VSIX. (The Microsoft Marketplace listing is not published yet.)
 3. Build it yourself: `cd dssl-vscode && npx @vscode/vsce package --no-dependencies`.
 
@@ -979,6 +1068,7 @@ node scripts/test-static-parity.mjs     # 0.13.0: every page of this site, built
 node scripts/test-v0130.mjs             # 0.13.0: build fidelity, source maps, strict CSP, server rendering
 node scripts/bench-compiled.mjs         # 0.13.0: compiled DSSL vs hand-written CSS, startup and churn (takes minutes)
 node scripts/test-v0140.mjs             # 0.14.0: the game-review fixes, and that the docs match the code
+node scripts/test-v0150.mjs             # 0.15.0: the second game review
 node scripts/test-v0100.mjs             # 0.10.0: glass, tilt, named-colour alpha, playground examples, HTML filter
 node scripts/test-designer.mjs          # the designer's state to DSSL and back, plus a random sweep
 node scripts/test-designer-browser.mjs  # the designer panel, driven like a person would

PARITY.md

@@ -62,6 +62,28 @@ so the boundary is explicit, not folklore.
 - 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.15.0: the second game review
+
+| Review item | Status |
+|---|---|
+| Aura redraws 1.5 times a second under reduced motion | done: follows what moves, rests when nothing does |
+| Aura emitters linger when hidden | done: invisible emitters (opacity 0, display none, visibility hidden, on it or an ancestor) stop |
+| One canvas on `<body>`, never behind a hill | done as `z N` per layer; interleaves with the root stacking context only |
+| Silent file-order losses | done: `dssl check`, console and `DSSL.lint` name rules a later rule always beats |
+| Styling is asynchronous | done: `DSSL.flush()`, `await DSSL.settled()`, `DSSL.computed()` |
+| Signals typed | done |
+| `DSSL.lint` noisy | done: invisible text skipped, outline and tight shadow count |
+| `DSSL.signal` costs 50 ms | done: only the elements its rules select are restyled |
+| Several `animate:` per element | done |
+| Scoped signals | done (`DSSL.signal(name, value, el)`) |
+| `outline-shape` | done (square corners, uses `filter`) |
+| `DSSL.play` on pseudo-elements | done |
+| CLI `--engine` | done |
+| Test helpers (final value, pause, step) | done |
+| `rotate: 5`, nested state in `::after`, `font:` trap, gradient docs | done |
+
+Not verified: Firefox and Safari. Scoped signals on `::before`/`::after` use a marker attribute the engine keeps on the element.
+
 ## v0.14.0: made for games
 
 From a review by an agent that built a game on DSSL. Twelve problems and ten wishes; each has an assertion in `scripts/test-v0140.mjs`.

README.md

@@ -68,7 +68,7 @@ Both drop a `dssl-engine/` folder next to you: the engine, a starter token set,
 
 Prefer to click: [dssl-engine.zip](https://dssl-sable.vercel.app/dssl-engine.zip) or [dssl-engine.tar.gz](https://dssl-sable.vercel.app/dssl-engine.tar.gz). Same package, straight from the browser.
 
-Writing your own .dssl? The official editor extension (`ehs-studio.dssl-vscode`) puts the real compiler in your editor: the squiggles are the same errors the browser console prints, completions come from your own token registry, and hovers explain the semantic vocabulary. One package for VS Code and VSCodium (same extension API). In VSCodium, search "DSSL" in the Extensions tab (it is on Open VSX: https://open-vsx.org/extension/ehs-studio/dssl-vscode). In VS Code, download `dssl-vscode/dssl-vscode-0.14.0.vsix` from the repo files, then Extensions panel -> ... -> Install from VSIX. See `dssl-vscode/PUBLISHING.md` for publishing.
+Writing your own .dssl? The official editor extension (`ehs-studio.dssl-vscode`) puts the real compiler in your editor: the squiggles are the same errors the browser console prints, completions come from your own token registry, and hovers explain the semantic vocabulary. One package for VS Code and VSCodium (same extension API). In VSCodium, search "DSSL" in the Extensions tab (it is on Open VSX: https://open-vsx.org/extension/ehs-studio/dssl-vscode). In VS Code, download `dssl-vscode/dssl-vscode-0.15.0.vsix` from the repo files, then Extensions panel -> ... -> Install from VSIX. See `dssl-vscode/PUBLISHING.md` for publishing.
 
 AI agents and machine reviewers: this repo ships `llms.txt` (dense, structured facts), `AGENTS.md` (how to work on the codebase) and `PARITY.md` (the honest feature matrix against CSS). The site serves the same `llms.txt` at https://dssl-sable.vercel.app/llms.txt
 
@@ -454,8 +454,12 @@ DSSL.load(['/styles/site.dssl'])       // fetch + apply, in order
 DSSL.apply(source, { scope, name })    // scoped engines for widgets
 DSSL.compile(source)                   // parse + resolve, no DOM (powers the playground)
 DSSL.toCSS(source | [sources], opts)   // the exit lane: plain CSS, source map, report
-DSSL.signal('theme', 'dark')           // the JS → styles bridge
-DSSL.getSignal('theme')                // read it back
+DSSL.signal('theme', 'dark')           // the JS → styles bridge (booleans and numbers stay as they are)
+DSSL.signal('hp', 2, el)               // only for el and what is inside it
+DSSL.getSignal('theme')                // read it back (DSSL.getSignal('hp', el) for a scope)
+DSSL.flush() / await DSSL.settled()    // style everything waiting, now, so offsetTop and friends are final
+DSSL.computed(el, 'translate')         // the final computed value, with nothing left waiting
+DSSL.pauseMotion() / DSSL.stepMotion(250) / DSSL.resumeMotion()   // freeze and step every animation (tests)
 DSSL.replay(sel)                       // re-run animations
 DSSL.refresh() / DSSL.refresh(el)      // full recompute, or one subtree
 DSSL.errors()                          // a function: structured errors from the last apply
@@ -466,7 +470,7 @@ await DSSL.lint(root)                  // contrast against the real background,
 DSSL.play(el, 'boing', opts)           // a one-shot motion from JS, as a promise
 DSSL.motion('full')                    // run every motion whatever the system asks for
 DSSL.auraZ(20)                         // where the aura canvas sits in the stack
-DSSL.version                           // "0.14.0", a string
+DSSL.version                           // "0.15.0", a string
 ```
 
 Auto-boot picks up every `link[rel="stylesheet/dssl"]` and `style[type="text/dssl"]`, applies them, and fires `dssl-ready` on `window`. `<html data-dssl-reset>` enables the small built-in reset.
@@ -542,7 +546,7 @@ const rep = DSSL.explain(document.querySelector('.doc-card'))
 
 The matcher also pre-filters every rule through a cheap class/tag/id gate extracted from the selector's rightmost compound, so a recompute skips obvious non-matches instead of asking the browser rule by rule. The gate only ever says no; anything it does not fully understand falls back to native matching.
 
-## What works today (v0.14.0)
+## What works today (v0.15.0)
 
 - the full selector surface, including `:nth-child`, `:not`, `:is`, `:where`, `:has`
 - flexbox and grid with `row:` / `column:` / `grid:` / `stack:` / `center:` sugar, place words now own an axis (`between` is main-axis, `stretch` is cross-axis) and conflicts warn instead of silently overwriting
@@ -582,7 +586,7 @@ The matcher also pre-filters every rule through a cheap class/tag/id gate extrac
 
 ## Status
 
-v0.14.0, experimental, moving fast. The language grows whenever the site needs something it cannot express yet, so the site doubles as the test suite, and the docs examples are rendered and asserted in a real browser, so the guide cannot lie. Honest ledger: great for creative sites, prototypes, docs, playgrounds and internal tools; when a page must work without JavaScript, build the static subset with `dssl build` or pick another tool for that page. Freeze makes big static pages viable; live interaction is what the engine is for.
+v0.15.0, experimental, moving fast. The language grows whenever the site needs something it cannot express yet, so the site doubles as the test suite, and the docs examples are rendered and asserted in a real browser, so the guide cannot lie. Honest ledger: great for creative sites, prototypes, docs, playgrounds and internal tools; when a page must work without JavaScript, build the static subset with `dssl build` or pick another tool for that page. Freeze makes big static pages viable; live interaction is what the engine is for.
 
 ## License
 

cli/dssl.mjs

@@ -36,12 +36,24 @@ import { fileURLToPath } from 'node:url';
 // next to cli/ as dssl/. 0.8.0 only knew the first layout, so the packaged CLI
 // crashed with "module not found" for everyone who installed it.
 const here = pathResolve(dirname(fileURLToPath(import.meta.url)), '..');
-const engineDir = existsSync(join(here, 'public/dssl/parser.js')) ? join(here, 'public/dssl') : join(here, 'dssl');
+// 0.15.0: `--engine ./dssl` (or DSSL_ENGINE=./dssl) points at the engine folder wherever it is, so the CLI file can live anywhere
+let engineDir = existsSync(join(here, 'public/dssl/parser.js')) ? join(here, 'public/dssl') : join(here, 'dssl');
+{
+  const i = process.argv.indexOf('--engine');
+  let want = process.env.DSSL_ENGINE || null;
+  if (i !== -1) { want = process.argv[i + 1] || null; process.argv.splice(i, want === null ? 1 : 2); if (want === null) { console.error('dssl: --engine needs a folder, e.g. --engine ./dssl'); process.exit(2); } }
+  if (want) {
+    const dir = pathResolve(want);
+    if (!existsSync(join(dir, 'parser.js'))) { console.error(`dssl: ${dir} has no parser.js, so it is not the engine folder (the folder that holds parser.js, resolver.js, index.js...)`); process.exit(2); }
+    engineDir = dir;
+  }
+}
 const { parse } = await import('file://' + join(engineDir, 'parser.js'));
 const { resolve } = await import('file://' + join(engineDir, 'resolver.js'));
 const { toCSS } = await import('file://' + join(engineDir, 'static.js'));
 const { VERSION } = await import('file://' + join(engineDir, 'index.js'));
 const { importCss } = await import('file://' + join(engineDir, 'import.js'));
+const { shadowWarnings } = await import('file://' + join(engineDir, 'lint.js'));
 
 const USAGE = `dssl v${VERSION} - the DSSL style language
 
@@ -69,7 +81,9 @@ const USAGE = `dssl v${VERSION} - the DSSL style language
   dssl dev [dir]         serve a folder with hot reload: edit a .dssl file and the page restyles with no reload
                          --port <n>     port (default 3000)
                          --inspect      also open the in-page inspector (hover an element to see its rules)
-  dssl --version         print the version`;
+  dssl --version         print the version
+
+  every command: --engine <dir> uses the engine in that folder (default: the one next to this file; or set DSSL_ENGINE)`;
 
 const readArg = (args, flag) => {
   const i = args.indexOf(flag);
@@ -147,6 +161,16 @@ function compileAll(files) {
     tokenBase = { ...(tokenBase || {}), ...doc.tokens };
     motionBase = { ...motionBase, ...(doc.motionFrames || {}) };
   }
+  // 0.15.0: a rule that can never win because a rule in a later file (or later in the same one) matches all it matches and sets the same thing.
+  // Per file this is invisible; across the page's files it is the commonest silent loss.
+  try {
+    const all = [];
+    out.forEach((x, i) => { for (const r of x.doc.rules || []) all.push({ ...r, file: r.file || x.name, order: i * 1e6 + (r.order || 0) }); });
+    for (const w of shadowWarnings(all)) {
+      const owner = out.find((x) => x.name === w.file) || out[0];
+      owner.warnings = [...owner.warnings, w];
+    }
+  } catch { /* a lint must never break a compile */ }
   return out;
 }
 

dssl-vscode/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.15.0
+
+- Bundled engine updated to 0.15.0 (the second game review). In the editor: `outline-shape`, `animate:` lists
+  (`animate: a 300, b 500`), `rotate: 5` (bare number = degrees), a state inside a pseudo-element block
+  (`::after { hover { } }`), the aura word `z N`, and a clear error for a CSS-style `font:` shorthand. Hovers document them.
+- The editor still checks one file at a time. `dssl check index.html` also finds rules that a later rule always beats.
+
 ## 0.14.0
 
 - Bundled engine updated to 0.14.0 (made for games). Editor: `@signal name in (a, b)`, `not in (...)` and `!=` are understood and

dssl-vscode/lib/engine/aura.js

@@ -49,6 +49,8 @@ export const GLOW_KEYS = {
   texture:   { kind: 'texture', words: 1, doc: 'texture(grain scale 2): break the light up with a texture' },
   essential: { kind: 'flag', words: 0, doc: 'keep animating even when the visitor prefers reduced motion' },
   unclipped: { kind: 'flag', words: 0, doc: 'let the light spill out of a parent that clips (overflow: hidden, auto, scroll). Without it the aura is cut at that edge, like the element itself' },
+  always:    { kind: 'flag', words: 0, doc: 'keep emitting even when the element cannot be seen (opacity 0, display: none, visibility: hidden, on it or an ancestor): for an invisible anchor that smoke or sparks come out of' },
+  z:         num(-1000000, 2147483000, { int: true, doc: 'the z-index of the layer this light is drawn on: `z 5` puts it under a hill with z-index 10. It meets elements in the page\'s root stacking context' }),
 };
 
 export const PARTICLE_KEYS = {
@@ -72,6 +74,8 @@ export const PARTICLE_KEYS = {
   texture:    { kind: 'texture', words: 1, doc: 'texture(grain): grainy particles' },
   essential:  { kind: 'flag', words: 0, doc: 'keep animating even when the visitor prefers reduced motion' },
   unclipped:  { kind: 'flag', words: 0, doc: 'let the particles leave a parent that clips (overflow: hidden, auto, scroll). Without it they are cut at that edge' },
+  always:     { kind: 'flag', words: 0, doc: 'keep emitting even when the element cannot be seen (opacity 0, display: none, visibility: hidden, on it or an ancestor): for an invisible anchor that smoke or sparks come out of' },
+  z:          num(-1000000, 2147483000, { int: true, doc: 'the z-index of the layer these particles are drawn on: `z 5` puts them under a hill with z-index 10. It meets elements in the page\'s root stacking context' }),
 };
 
 /* ------------------------------------------------------------------ *
@@ -382,6 +386,7 @@ export class AuraManager {
     // reduced motion draws a still picture, so it only needs a new frame when something could have moved
     this._onScroll = () => { if (this.reduced && !this.running && !this.paused && this.emitters.size) this.start(); };
     this._poll = null;
+    this.extra = new Map();        // z-index -> { canvas, ctx }: layers asked for with `z N`
     this._frame = (t) => this.frame(t);
   }
 
@@ -418,11 +423,62 @@ export class AuraManager {
     if (!this.canvas) return;
     this.dpr = Math.min(2, window.devicePixelRatio || 1);
     this.vw = window.innerWidth; this.vh = window.innerHeight;
-    this.canvas.width = Math.max(1, Math.round(this.vw * this.dpr));
-    this.canvas.height = Math.max(1, Math.round(this.vh * this.dpr));
+    for (const c of this.allCanvases()) {
+      c.width = Math.max(1, Math.round(this.vw * this.dpr));
+      c.height = Math.max(1, Math.round(this.vh * this.dpr));
+    }
     this.dirty = true;
   }
 
+  allCanvases() { return [this.canvas, ...[...this.extra.values()].map((e) => e.canvas)]; }
+
+  /** the drawing context for a layer: the default canvas, or the one at the z-index the layer asked for (`z 5`) */
+  ctxFor(z) {
+    if (z === undefined || z === null) return this.ctx;
+    let e = this.extra.get(z);
+    if (!e) {
+      const c = document.createElement('canvas');
+      c.setAttribute('aria-hidden', 'true');
+      c.setAttribute('data-dssl-aura', String(z));
+      c.style.cssText = `position:fixed;left:0;top:0;width:100vw;height:100vh;pointer-events:none;z-index:${z};`;
+      c.width = this.canvas.width; c.height = this.canvas.height;
+      (document.body || document.documentElement).appendChild(c);
+      e = { canvas: c, ctx: c.getContext('2d') };
+      this.extra.set(z, e);
+    }
+    return e.ctx;
+  }
+
+  /** how visible an element really is: its opacity times every ancestor's; 0 for display: none or visibility: hidden */
+  effectiveOpacity(el) {
+    try {
+      let o = 1;
+      if (getComputedStyle(el).visibility !== 'visible') return 0;
+      for (let a = el; a && a.nodeType === 1; a = a.parentElement) {
+        const cs = getComputedStyle(a);
+        if (cs.display === 'none') return 0;
+        o *= parseFloat(cs.opacity);
+        if (!(o > 0.004)) return 0;
+      }
+      return o;
+    } catch { return 1; }
+  }
+
+  /** what a frame would draw for this emitter, as a string: the same string twice means nothing needs redrawing */
+  stateKey(el, eo) {
+    const r = el.getBoundingClientRect();
+    return `${r.left.toFixed(1)},${r.top.toFixed(1)},${r.width.toFixed(1)},${r.height.toFixed(1)},${eo.toFixed(2)}`;
+  }
+
+  /** reduced motion: has anything moved, resized or faded since the last frame? (cheap: no drawing) */
+  peek() {
+    for (const [el, em] of this.emitters) {
+      if (!el.isConnected) return true;
+      if (this.stateKey(el, this.effectiveOpacity(el)) !== em.key) return true;
+    }
+    return false;
+  }
+
   /* ---- the engine's interface ---- */
 
   /** Set (or change) the aura of an element. glow/particles are arrays of resolved layers. */
@@ -458,7 +514,7 @@ export class AuraManager {
     this.start();
   }
 
-  pause() { this.paused = true; this.running = false; if (this._poll) { clearTimeout(this._poll); this._poll = null; } if (this.ctx) this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height); }
+  pause() { this.paused = true; this.running = false; if (this._poll) { clearTimeout(this._poll); this._poll = null; } if (this.ctx) for (const c of this.allCanvases()) c.getContext('2d').clearRect(0, 0, c.width, c.height); }
   resume() { this.paused = false; this.start(); }
 
   destroy() {
@@ -467,6 +523,8 @@ export class AuraManager {
     window.removeEventListener('scroll', this._onScroll, { capture: true });
     if (this._poll) { clearTimeout(this._poll); this._poll = null; }
     if (this.io) this.io.disconnect();
+    for (const e of this.extra.values()) e.canvas.remove();
+    this.extra.clear();
     if (this.canvas) this.canvas.remove();
     this.canvas = null; this.ctx = null; this.emitters.clear();
   }
@@ -486,11 +544,15 @@ export class AuraManager {
     const dt = this.last ? Math.min(0.05, (now - this.last) / 1000) : 0.016;
     this.last = now;
     const reduced = this.reduced;
-    const ctx = this.ctx, dpr = this.dpr;
+    const dpr = this.dpr;
 
-    ctx.setTransform(1, 0, 0, 1, 0, 0);
-    ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
-    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    for (const c of this.allCanvases()) {
+      const x = c.getContext('2d');
+      x.setTransform(1, 0, 0, 1, 0, 0);
+      x.clearRect(0, 0, c.width, c.height);
+      x.setTransform(dpr, 0, 0, dpr, 0, 0);
+    }
+    let changed = false;
 
     // global budget: if everyone asks for more than the page can afford, everyone gets a share
     let want = 0;
@@ -498,6 +560,7 @@ export class AuraManager {
     const share = want > this.budget ? this.budget / want : 1;
 
     let alive = 0, anyActive = false;
+    this._n = (this._n || 0) + 1;
     for (const [el, em] of this.emitters) {
       if (!el.isConnected) { this.emitters.delete(el); if (this.io) this.io.unobserve(el); continue; }
       // read geometry once per frame for visible emitters
@@ -507,6 +570,12 @@ export class AuraManager {
         if (rect.width === 0 && rect.height === 0) rect = null;
       }
       em.rect = rect;
+      // 0.15.0: an emitter that cannot be seen (opacity 0 on it or any ancestor, display: none, visibility: hidden) does not emit, and
+      // what it already let go fades with it. Looked up every third frame, or every frame in reduced motion where frames are rare.
+      if (em.eo === undefined || reduced || this._n % 3 === 0) em.eo = this.effectiveOpacity(el);
+      if (em.layers.some((l) => l.cfg.always) || em.glow.some((g) => g.cfg.always)) em.eo = 1;   // an invisible anchor on purpose
+      const key = this.stateKey(el, em.eo);
+      if (key !== em.key) { em.key = key; changed = true; }
       // 0.14.0: a stage scaled with transform: scale() has a rect the size you SEE, so the light follows it, and so must its size
       // and speed. The scale is how much bigger (or smaller) the box is than the box CSS says it is.
       em.scale = 1;
@@ -518,11 +587,13 @@ export class AuraManager {
 
       // 0.14.0: cut the light at the edge of any parent that clips, so a stage with overflow: hidden keeps its fire inside
       const clipped = rect && em.clips && em.clips.length ? this.clipRect(em.clips) : null;
-      if (clipped) { ctx.save(); ctx.beginPath(); ctx.rect(clipped.x, clipped.y, clipped.w, clipped.h); ctx.clip(); }
+      const open = (ctx) => { if (clipped) { ctx.save(); ctx.beginPath(); ctx.rect(clipped.x, clipped.y, clipped.w, clipped.h); ctx.clip(); } };
+      const close = (ctx) => { if (clipped) ctx.restore(); };
+      const seen = em.eo > 0.004;
 
       // glow
-      if (rect && em.fade > 0 && (em.visible || em.dying)) {
-        for (const g of em.glow) { this.drawGlow(ctx, rect, em, g, now, reduced); }
+      if (rect && em.fade > 0 && (em.visible || em.dying) && seen) {
+        for (const g of em.glow) { const ctx = this.ctxFor(g.cfg.z); open(ctx); this.drawGlow(ctx, rect, em, g, now, reduced); close(ctx); }
         if (em.glow.length) anyActive = true;
       }
 
@@ -531,12 +602,12 @@ export class AuraManager {
         const cfg = L.cfg;
         const moving = !reduced || cfg.essential;
         L.scale = em.scale;
-        if (rect && em.visible && !em.dying && moving) this.emit(L, rect, em, dt, share, el);
-        if (L.parts.length) this.stepAndDraw(ctx, L, dt, moving, cfg.behind && rect ? { rect, radius: em.radius } : null);
+        L.eo = em.eo;
+        if (rect && em.visible && !em.dying && moving && seen) this.emit(L, rect, em, dt, share, el);
+        if (L.parts.length) { const ctx = this.ctxFor(cfg.z); open(ctx); this.stepAndDraw(ctx, L, dt, moving, cfg.behind && rect ? { rect, radius: em.radius } : null); close(ctx); }
         alive += L.parts.length;
-        if (L.parts.length || (rect && em.visible && !em.dying && moving)) anyActive = true;
+        if (L.parts.length || (rect && em.visible && !em.dying && moving && seen)) anyActive = true;
       }
-      if (clipped) ctx.restore();
       if (em.dying && em.fade <= 0 && em.layers.every((l) => !l.parts.length)) {
         this.emitters.delete(el);
         if (this.io) this.io.unobserve(el);
@@ -550,12 +621,14 @@ export class AuraManager {
     this._fpsN++;
     if (now - this._fpsT > 500) { this.stats.fps = Math.round((this._fpsN * 1000) / Math.max(1, now - this._fpsT)); this._fpsT = now; this._fpsN = 0; }
 
-    if (this.emitters.size === 0) { this.running = false; ctx.clearRect(0, 0, this.vw, this.vh); return; }
+    if (this.emitters.size === 0) { this.running = false; for (const c of this.allCanvases()) c.getContext('2d').clearRect(0, 0, c.width, c.height); return; }
     // Normally the loop runs every frame (the glow follows the element, particles move). With reduced
     // motion nothing moves, so one frame is a complete picture; it is redrawn on scroll, resize, a
-    // style change, and a slow poll for layout shifts. Essential layers and fading-out emitters still loop.
+    // style change, and a quick look (peek) for anything that moved. A frame that saw something move, resize or fade asks for the next one,
+    // so a glow on a thing that moves under reduced motion follows it every frame instead of lagging. Essential layers and fading-out emitters still loop.
     let needLoop = !reduced;
     if (reduced) {
+      if (changed) needLoop = true;
       for (const em of this.emitters.values()) {
         if (em.dying) needLoop = true;
         if (em.glow.some((g) => g.cfg.essential) || em.layers.some((l) => l.cfg.essential && (l.parts.length || (em.visible && !em.dying)))) needLoop = true;
@@ -563,7 +636,17 @@ export class AuraManager {
     }
     if (needLoop) { requestAnimationFrame(this._frame); return; }
     this.running = false;
-    if (!this._poll) this._poll = setTimeout(() => { this._poll = null; this.start(); }, 600);
+    this.watchStill();
+  }
+
+  /** reduced motion, nothing moving: look every 100ms (a few rect reads, no drawing) and draw again the moment something changed */
+  watchStill() {
+    if (this._poll || this.paused) return;
+    this._poll = setTimeout(() => {
+      this._poll = null;
+      if (this.running || !this.canvas) return;
+      if (this.peek()) this.start(); else this.watchStill();
+    }, 100);
   }
 
   /** the ancestors that clip their children (overflow other than visible), unless this emitter said `unclipped` */
@@ -604,7 +687,7 @@ export class AuraManager {
   drawGlow(ctx, rect, em, g, now, reduced) {
     const cfg = g.cfg;
     const moving = !reduced || cfg.essential;
-    let a = cfg.intensity * em.fade;
+    let a = cfg.intensity * em.fade * (em.eo === undefined ? 1 : em.eo);
     if (moving && cfg.pulse > 0) {
       const ph = ((now - g.t0) / cfg.pulse) * TAU;
       a *= 1 - cfg.depth * 0.5 * (1 + Math.sin(ph)) ;
@@ -819,7 +902,7 @@ export class AuraManager {
       }
       const t = p.age / p.life;
       const col = colorAt(c.stops, t);
-      const alpha = clamp01(col.a);
+      const alpha = clamp01(col.a) * (L.eo === undefined ? 1 : L.eo);
       if (alpha <= 0.003) continue;
       const size = p.size * lerp(1, c.grow, t);
       this.drawParticle(ctx, c, p, col, alpha, size);

dssl-vscode/lib/engine/lint.js

@@ -163,3 +163,110 @@ export function lintRules({ rules, tokenMap, file }) {
   }
   return warnings;
 }
+
+/* ------------------------------------------------------------------ *
+ * rules that can never win (0.15.0)
+ * ------------------------------------------------------------------ */
+
+const LAYER_RANK = { tokens: 0, base: 1, components: 2, utilities: 3, pin: 4 };
+
+/** split a selector at top-level spaces and > + ~ (outside brackets and parentheses); null when it holds a top-level comma */
+function selectorParts(sel) {
+  const parts = []; let depth = 0, cur = '', q = null;
+  for (const ch of String(sel).trim()) {
+    if (q) { cur += ch; if (ch === q) q = null; continue; }
+    if (ch === '"' || ch === "'") { q = ch; cur += ch; continue; }
+    if (ch === '(' || ch === '[') depth++;
+    if (ch === ')' || ch === ']') depth--;
+    if (depth === 0 && ch === ',') return null;
+    if (depth === 0 && (ch === ' ' || ch === '>' || ch === '+' || ch === '~')) { if (cur) { parts.push(cur); cur = ''; } parts.push(ch === ' ' ? ' ' : ch); continue; }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+
+/** the simple selectors of one compound: `div.a#b[x]:not(.c)` is div, .a, #b, [x], :not(.c) */
+function simpleSelectors(compound) {
+  const out = []; let i = 0; const n = compound.length;
+  const take = (start) => {
+    let j = start + 1, depth = 0;
+    while (j < n) {
+      const c = compound[j];
+      if (c === '(' || c === '[') depth++;
+      else if (c === ')' || c === ']') depth--;
+      else if (depth === 0 && /[.#:\[]/.test(c)) break;
+      j++;
+    }
+    return j;
+  };
+  if (/^[a-zA-Z*]/.test(compound)) { let j = 0; while (j < n && /[\w*-]/.test(compound[j])) j++; out.push(compound.slice(0, j).toLowerCase()); i = j; }
+  while (i < n) {
+    const j = compound[i] === ':' && compound[i + 1] === ':' ? take(i + 1) : take(i);
+    out.push(compound.slice(i, j)); i = j;
+  }
+  return out;
+}
+
+/**
+ * A rule whose every declaration of a property is beaten by a LATER rule that matches everything it matches. There is no specificity
+ * in DSSL, so `.prop.broc { z-index: 1 }` in one file loses to a plain `.prop { z-index: 2 }` in a file that comes after it, and the
+ * line does nothing at all. (The very same selector again is left alone: that is how a later file overrides an earlier one.) Both rules must be unconditional alike (same @media, @signal, container, state) and the later one must be
+ * in the same layer or a higher one. Pure; rules from several files must already carry one global `order`.
+ * @returns {Array<{a:{sel,file,line,props:string[]}, b:{sel,file,line}}>}
+ */
+export function shadowedRules(rules) {
+  const info = [];
+  for (const r of rules) {
+    if (!r || r.pseudo || !r.sel || !r.decls || !r.decls.length) continue;
+    const parts = selectorParts(r.sel);
+    if (!parts || !parts.length) continue;
+    const comp = parts[parts.length - 1];
+    if (/^[ >+~]$/.test(comp)) continue;
+    if (/^:root$|::/.test(r.sel)) continue;
+    const toks = simpleSelectors(comp);
+    if (!toks.length) continue;
+    const cond = JSON.stringify([r.media || [], (r.signals || []).map((s) => [s.name, s.op, s.value, s.values]), r.containers || [], [...(r.states || [])].sort()]);
+    info.push({ idx: info.length, r, toks, set: new Set(toks), single: parts.length === 1, cond, rank: LAYER_RANK[r.layer] ?? 2, order: r.order ?? 0 });
+  }
+  // the later rules, found by the first simple selector they need
+  const byTok = new Map();
+  for (const b of info) if (b.single) { const k = b.toks[0]; if (!byTok.has(k)) byTok.set(k, []); byTok.get(k).push(b); }
+  const pairs = new Map();
+  for (const a of info) {
+    const seenProps = new Set();
+    const cands = [];
+    for (const t of a.toks) for (const b of byTok.get(t) || []) cands.push(b);
+    if (byTok.has('*')) for (const b of byTok.get('*')) cands.push(b);
+    cands.sort((x, y) => x.order - y.order);
+    for (const b of cands) {
+      if (b === a || b.cond !== a.cond) continue;
+      if (b.r.sel.replace(/\s+/g, ' ').trim() === a.r.sel.replace(/\s+/g, ' ').trim()) continue;   // the same selector again is an override on purpose (a theme file, a later tweak)
+      if (b.rank < a.rank || (b.rank === a.rank && b.order <= a.order)) continue;
+      if (b.toks.some((t) => t !== '*' && !a.set.has(t))) continue;
+      const bProps = new Map();
+      for (const d of b.r.decls) if (d.prop && !String(d.prop).startsWith('@')) bProps.set(d.prop, d.value);
+      const hit = [];
+      for (const d of a.r.decls) {
+        const p = d.prop;
+        if (!p || String(p).startsWith('@') || seenProps.has(p) || !bProps.has(p)) continue;
+        if (String(bProps.get(p)) === String(d.value)) continue;
+        seenProps.add(p); hit.push(p);
+      }
+      if (hit.length) {
+        const key = a.idx + '>' + b.idx;
+        pairs.set(key, { a: { sel: a.r.sel, file: a.r.file, line: (a.r.decls.find((d) => d.prop === hit[0]) || a.r).line ?? a.r.line, props: hit }, b: { sel: b.r.sel, file: b.r.file, line: b.r.line } });
+      }
+    }
+  }
+  return [...pairs.values()];
+}
+
+/** the same, as compiler warnings */
+export function shadowWarnings(rules) {
+  return shadowedRules(rules).map((p) => ({
+    file: p.a.file, line: p.a.line,
+    message: `${p.a.props.join(', ')} in "${p.a.sel}" can never apply: "${p.b.sel}" (${p.b.file || ''}${p.b.file ? ':' : ''}${p.b.line}) comes later, matches every element this rule matches, and sets ${p.a.props.length > 1 ? 'the same properties' : 'the same property'}`,
+    hint: 'there is no specificity in DSSL, so the later rule always wins. Move the more specific rule below the general one, or remove the line from the general one',
+  }));
+}

dssl-vscode/lib/engine/resolver.js

@@ -710,6 +710,38 @@ const DEFORM_TO_TRANSFORM = {
   fold: 'transform', stretch: 'transform',
 };
 
+/** one motion of an animate: line: `bob 1200 infinite alternate delay 100 jitter 600 essential` */
+function animateOne(t, ctx) {
+  const atoms = t.split(/\s+/);
+  const spec = { motion: atoms[0], duration: 400, easing: EASINGS.smooth, fill: 'both', delay: 0 };
+  const toMs = (a) => (a.endsWith('s') && !a.endsWith('ms') ? parseFloat(a) * 1000 : parseFloat(a));
+  for (let k = 1; k < atoms.length; k++) {
+    const a = atoms[k];
+    // 0.14.0: the words that used to be CSS longhands which did nothing here
+    if (a === 'delay' || a === 'jitter' || a === 'iterations') {
+      const v = atoms[k + 1];
+      if (v === undefined || !/^\d+(\.\d+)?(ms|s)?$/.test(v)) { ctx.errors.push({ file: ctx.file, line: ctx.line, message: `${a} needs a number`, hint: a === 'iterations' ? 'animate: boing 300 iterations 3' : `animate: bob 1200 infinite ${a} 600` }); continue; }
+      if (a === 'iterations') spec.iterations = parseFloat(v); else spec[a] = toMs(v);
+      k++;
+      continue;
+    }
+    if (a === 'essential') { spec.essentialHere = true; continue; }
+    if (/^\d+(ms|s)?$/.test(a)) {
+      const ms = toMs(a);
+      if (k === 1) spec.duration = ms; else spec.delay = ms;
+      continue;
+    }
+    if (EASINGS[a]) { spec.easing = EASINGS[a]; continue; }
+    if (['both', 'forwards', 'backwards', 'none', 'auto'].includes(a)) { spec.fill = a; continue; }
+    // v0.5.0 - looping: `infinite` runs forever, `alternate` ping-pongs.
+    // animate: pulse 1600 infinite alternate  - was impossible before.
+    if (a === 'infinite') { spec.iterations = Infinity; continue; }
+    if (['alternate', 'alternate-reverse', 'reverse', 'normal'].includes(a)) { spec.direction = a; continue; }
+    ctx.errors.push({ file: ctx.file, line: ctx.line, message: `unknown animate part "${a}"`, hint: didYouMean(a, Object.keys(EASINGS).concat(['both', 'forwards', 'backwards', 'infinite', 'alternate', 'delay', 'jitter', 'iterations', 'essential'])) });
+  }
+  return [{ prop: '@animate', value: spec }];
+}
+
 const SEMANTIC = {
   size(v, ctx) {
     const parts = v.split(/\s+/).filter(Boolean);
@@ -795,6 +827,14 @@ const SEMANTIC = {
     const out = [];
     const slash = v.split('/');
     const head = slash[0].trim().split(/\s+/).filter(Boolean);
+    // 0.15.0: DSSL's font: is size/line-height and a colour, NOT the CSS shorthand (weight, style, family). A CSS-looking value used to
+    // become a 700px font; say what it is instead.
+    const sized = (x) => /^\d*\.?\d+(px|em|rem|%|pt|vw|vh|ch)$/.test(x);
+    if (/["',]/.test(v) || /^(italic|oblique|bold|bolder|lighter|normal|small-caps|condensed|expanded|caption|icon|menu|message-box|small-caption|status-bar|system-ui|serif|sans-serif|monospace)$/.test(head[0] || '')
+      || (/^[1-9]00$/.test(head[0] || '') && head[1] !== undefined && sized(head[1]))) {
+      ctx.errors.push({ file: ctx.file, line: ctx.line, message: `font: "${v.trim()}" looks like the CSS font shorthand, but DSSL's font: means size, line height and colour`, hint: 'font: 16/1.5 color.ink  sets size, line-height and colour. Weight and family are their own lines: font-weight: 700  and  font-family: "Fraunces", serif' });
+      return [];
+    }
     out.push({ prop: 'font-size', value: len(head[0] || '16', ctx) });
     if (slash[1]) {
       const tail = slash[1].trim().split(/\s+/).filter(Boolean);
@@ -928,34 +968,14 @@ const SEMANTIC = {
   animate(v, ctx) {
     const t = v.trim();
     if (t === 'none') return [{ prop: '@animate', value: null }];
-    const atoms = t.split(/\s+/);
-    const spec = { motion: atoms[0], duration: 400, easing: EASINGS.smooth, fill: 'both', delay: 0 };
-    const toMs = (a) => (a.endsWith('s') && !a.endsWith('ms') ? parseFloat(a) * 1000 : parseFloat(a));
-    for (let k = 1; k < atoms.length; k++) {
-      const a = atoms[k];
-      // 0.14.0: the words that used to be CSS longhands which did nothing here
-      if (a === 'delay' || a === 'jitter' || a === 'iterations') {
-        const v = atoms[k + 1];
-        if (v === undefined || !/^\d+(\.\d+)?(ms|s)?$/.test(v)) { ctx.errors.push({ file: ctx.file, line: ctx.line, message: `${a} needs a number`, hint: a === 'iterations' ? 'animate: boing 300 iterations 3' : `animate: bob 1200 infinite ${a} 600` }); continue; }
-        if (a === 'iterations') spec.iterations = parseFloat(v); else spec[a] = toMs(v);
-        k++;
-        continue;
-      }
-      if (a === 'essential') { spec.essentialHere = true; continue; }
-      if (/^\d+(ms|s)?$/.test(a)) {
-        const ms = toMs(a);
-        if (k === 1) spec.duration = ms; else spec.delay = ms;
-        continue;
-      }
-      if (EASINGS[a]) { spec.easing = EASINGS[a]; continue; }
-      if (['both', 'forwards', 'backwards', 'none', 'auto'].includes(a)) { spec.fill = a; continue; }
-      // v0.5.0 - looping: `infinite` runs forever, `alternate` ping-pongs.
-      // animate: pulse 1600 infinite alternate  - was impossible before.
-      if (a === 'infinite') { spec.iterations = Infinity; continue; }
-      if (['alternate', 'alternate-reverse', 'reverse', 'normal'].includes(a)) { spec.direction = a; continue; }
-      ctx.errors.push({ file: ctx.file, line: ctx.line, message: `unknown animate part "${a}"`, hint: didYouMean(a, Object.keys(EASINGS).concat(['both', 'forwards', 'backwards', 'infinite', 'alternate', 'delay', 'jitter', 'iterations', 'essential'])) });
+    // 0.15.0: several motions on one element: animate: blink 300 infinite, waddle 900 infinite alternate
+    const parts = topSplit(t, ',').map((x) => x.trim()).filter(Boolean);
+    if (parts.length > 1) {
+      const out = [];
+      for (const part of parts) for (const d of animateOne(part, ctx)) out.push(d);
+      return out;
     }
-    return [{ prop: '@animate', value: spec }];
+    return animateOne(t, ctx);
   },
   // v0.4.0 - choreography: a parent with `stagger: 60` offsets each element
   // child's animation delay by its DOM position. Pairs with `seen` + `animate`
@@ -1071,6 +1091,32 @@ const SEMANTIC = {
     if (!inside) out.push({ prop: 'paint-order', value: 'stroke fill' });
     return out;
   },
+  // 0.15.0: an outline that follows the SHAPE's alpha (a sprite, an icon, a cut-out), not its box. It is four drop-shadows with no blur,
+  // one in each direction, which is what people write by hand. The corners come out square. It uses `filter`, so it replaces another filter on the same rule.
+  //   outline-shape: 3 color.ink      outline-shape: none
+  'outline-shape'(v, ctx) {
+    const atoms = (v || '').trim().split(/\s+/).filter(Boolean);
+    if (atoms.length === 1 && atoms[0] === 'none') return [{ prop: 'filter', value: 'none' }];
+    if (!atoms.length || !/^\d+(\.\d+)?(px)?$/.test(atoms[0])) {
+      ctx.errors.push({ file: ctx.file, line: ctx.line, message: 'outline-shape needs a width first', hint: 'outline-shape: 3 color.ink' });
+      return [];
+    }
+    const w = parseFloat(atoms[0]);
+    const color = atoms[1] ? resolveValue(atoms.slice(1).join(' '), { ...ctx, unitless: false, bareIdents: false }) : 'currentcolor';
+    const at = (x, y) => `drop-shadow(${x}px ${y}px 0 ${color})`;
+    return [{ prop: 'filter', value: [at(w, 0), at(-w, 0), at(0, w), at(0, -w)].join(' ') }];
+  },
+  // 0.15.0: an angle is a bare number like every other length: rotate: 5 is 5deg (the other forms, 5deg, 0.1turn, x 30, pass through)
+  rotate(v, ctx) {
+    const t = (v || '').trim();
+    const num = '-?\\d*\\.?\\d+';
+    let out;
+    if (new RegExp(`^${num}$`).test(t)) out = t + 'deg';
+    else if (new RegExp(`^[xyz]\\s+${num}$`).test(t)) out = t + 'deg';
+    else if (new RegExp(`^${num}\\s+${num}\\s+${num}\\s+${num}$`).test(t)) out = t + 'deg';
+    else out = resolveValue(t, { ...ctx, unitless: true });
+    return [{ prop: 'rotate', value: out }];
+  },
   'gradient-text'(v, ctx) {
     const img = buildGradient(v, ctx);
     if (!img) return [];
@@ -1622,23 +1668,37 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null, baseMotion
             media: ctx.media, signals: ctx.signals, containers: ctx.containers,
             layer: ctx.layer, order: order++, decls: [], file, line: node.line,
           };
-          for (const d of node.children) {
-            if (d.kind !== 'decl') { errors.push({ file, line: d.line, message: 'only declarations may appear inside a pseudo-element block (v0.2)' }); continue; }
-            if (d.prop === 'content' && d.value === '') { srule.decls.push({ prop: 'content', value: '""', line: d.line }); continue; }
-            const resolved = resolveDecl(d.prop, d.value, { file, line: d.line, errors, warnings, tokens: tokenMap, tokenNames: tokenNames(), prop: d.prop, unitless: false });
-            // v0.5.0 - engine-native properties have no pseudo-element story:
-            // there is no DOM handle to nudge, animate, stack or stagger. They
-            // used to leak into the shadow sheet as junk CSS the browser
-            // silently dropped - exactly the silence this language refuses.
-            for (const r of resolved) {
-              if (r.prop.startsWith('@') && r.prop !== '@animate') {   // 0.14.0: animate: becomes a CSS animation on a pseudo-element
-                errors.push({ file, line: d.line, message: `"${d.prop}" is engine-native and has no meaning on ::${node.name} - a pseudo-element has no DOM handle`, hint: 'put it on the element itself, not inside the pseudo block' });
+          // 0.15.0: a state inside the pseudo-element block styles that pseudo-element in that state:
+          //   .btn { ::after { content: ""; hover { opacity: 1 } } }   is   .btn:hover::after
+          const fill = (target, kids) => {
+            for (const d of kids) {
+              if (d.kind === 'state' && target === srule) {
+                if (d.name === 'seen') { errors.push({ file, line: d.line, message: '"seen" is engine-native and has no meaning on a pseudo-element', hint: 'put seen { } on the element itself' }); continue; }
+                const st = { id: ruleId++, sel: base + ':' + d.name, pseudo: node.name, media: ctx.media, signals: ctx.signals, containers: ctx.containers, layer: ctx.layer, order: order++, decls: [], file, line: d.line };
+                fill(st, d.children);
+                stateRules.push(st);
                 continue;
               }
-              srule.decls.push({ ...r, line: d.line });
+              if (d.kind !== 'decl') { errors.push({ file, line: d.line, message: 'only declarations and states (hover { }) may appear inside a pseudo-element block' }); continue; }
+              if (d.prop === 'content' && d.value === '') { target.decls.push({ prop: 'content', value: '""', line: d.line }); continue; }
+              const resolved = resolveDecl(d.prop, d.value, { file, line: d.line, errors, warnings, tokens: tokenMap, tokenNames: tokenNames(), prop: d.prop, unitless: false });
+              // v0.5.0 - engine-native properties have no pseudo-element story:
+              // there is no DOM handle to nudge, animate, stack or stagger. They
+              // used to leak into the shadow sheet as junk CSS the browser
+              // silently dropped - exactly the silence this language refuses.
+              for (const r of resolved) {
+                if (r.prop.startsWith('@') && r.prop !== '@animate') {   // 0.14.0: animate: becomes a CSS animation on a pseudo-element
+                  errors.push({ file, line: d.line, message: `"${d.prop}" is engine-native and has no meaning on ::${node.name} - a pseudo-element has no DOM handle`, hint: 'put it on the element itself, not inside the pseudo block' });
+                  continue;
+                }
+                target.decls.push({ ...r, line: d.line });
+              }
             }
-          }
+          };
+          const stateRules = [];
+          fill(srule, node.children);
           if (srule.decls.length) shadowRules.push(srule);
+          for (const st of stateRules) if (st.decls.length) shadowRules.push(st);
           break;
         }
         case 'tokens': {

dssl-vscode/lib/props-docs.js

@@ -21,7 +21,8 @@ export const SEMANTIC = {
   fold: 'swings up over its top edge like a closing page. `fold: 14`.',
   stretch: 'cartoon squash-and-stretch that keeps volume: `stretch: 0.94` squeezes to 0.94 wide and honestly grows to 1/0.94 tall.',
   'bend-around': 'curves a container\u2019s CHILDREN along a circular arc instead of deforming one element: `bend-around: -22` opens into a smile. Caps at \u00b1170\u00b0. Children keep their own hover bends.',
-  animate: 'run a motion: `animate: name duration [easing] [delay N] [jitter N] [iterations N] [infinite] [alternate] [essential]`. Example: `animate: pulse 1600 infinite alternate`. `jitter` gives each element its own random delay, `essential` runs it even when the visitor prefers reduced motion. Works on ::before and ::after too. Run one from JS with `DSSL.play(el, name, opts)`.',
+  animate: 'run a motion (or several: `animate: blink 300 infinite, waddle 900 infinite alternate`): `animate: name duration [easing] [delay N] [jitter N] [iterations N] [infinite] [alternate] [essential]`. Example: `animate: pulse 1600 infinite alternate`. `jitter` gives each element its own random delay, `essential` runs it even when the visitor prefers reduced motion. Works on ::before and ::after too. Run one from JS with `DSSL.play(el, name, opts)`.',
+  'outline-shape': 'an outline that follows the SHAPE (a sprite\u2019s alpha), not its box: `outline-shape: 3 color.ink`. Four hard drop-shadows, square corners. Uses `filter`, so it replaces another filter on the same rule. `none` clears it.',
   'text-stroke': 'an outline round text, outside the letters: `text-stroke: 6 color.ink` (writes -webkit-text-stroke and paint-order: stroke fill). Add `inside` for a centred stroke, `none` to clear.',
   stagger: 'choreographed children: `stagger: 70` fires each child\u2019s animation 70ms after its older sibling.',
   transition: 'per-property transition: `transition: 200`, or `transition: 200 snap transform`. Honors reduced-motion.',
@@ -34,8 +35,8 @@ export const SEMANTIC = {
   tilt: 'follows the pointer in 3D: `tilt: 10`, `tilt: 12 lift 1.04 perspective 700 speed 0.2 invert glare`. Runtime only. `glare` keeps --dssl-gx and --dssl-gy pointing at the pointer so you can draw a shine. Ignores touch, flat under reduced motion.',
   texture: 'a generated texture layered ON TOP of the element\u2019s own background: `texture: grain`, `texture: wood scale 6 intensity 0.8`, `texture: grain, scanlines`. 30 presets (grain, paper, marble, wood, carbon, halftone, ...) or build your own from a generator (noise, bump, lines, dots, grid, checker, weave, carbon, waves, hex) plus settings (scale, intensity, contrast, octaves, color, color2, blend, stretch, contour, ...). Wood: `texture: oak figure 0.8 knots 2 planks 120` (rings generator, ten species). `symmetrical` mirrors the tile so it never shows a seam. Open the designer to see them all.',
   aura: 'light and particles around an element, with NO presets: you describe it. `aura: glow #ff7a00 30 flicker 0.3, particles #fd0 -> #f60 count 60 shape flame glowing behind`. Replaces both slots. `aura: none` clears them.',
-  'aura-glow': 'just the glow slot: `aura-glow: color.accent 24 pulse 1600`. Positional colour and radius, then settings (intensity, pulse, depth, flicker, texture(...), seed, essential). `aura-glow: none` clears only the glow.',
-  'aura-particle': 'just the particles slot: `aura-particle: #7cf -> transparent 40 up size 6 life 800 speed 30 from bottom`. Settings: count, size, life, speed, dir, spread, gravity, drag, turbulence, from, shape, grow, glowing, behind, blend, texture(...), seed, essential.',
+  'aura-glow': 'just the glow slot: `aura-glow: color.accent 24 pulse 1600`. Positional colour and radius, then settings (z N, always, intensity, pulse, depth, flicker, texture(...), seed, essential). `aura-glow: none` clears only the glow.',
+  'aura-particle': 'just the particles slot: `aura-particle: #7cf -> transparent 40 up size 6 life 800 speed 30 from bottom`. Settings: z N (own canvas layer), count, size, life, speed, dir, spread, gravity, drag, turbulence, from, shape, grow, glowing, behind, blend, texture(...), seed, essential.',
   'aura-particles': 'the same as `aura-particle`.',
   'glow-particle': 'the particles slot with every particle glowing (additive light): `glow-particle: #fff 30 out`.',
   'glow-particles': 'the same as `glow-particle`.',
@@ -66,7 +67,7 @@ export const CSS = {
   opacity: 'passthrough CSS. Below 100% the overlap policy wakes up (see `overlap`).',
   transform: 'passthrough CSS \u2014 deform (bend/stretch/fold) composes into this channel.',
   translate: 'the transform channel the engine itself uses for overlap escapes; animating translate never fights the engine.',
-  rotate: 'passthrough CSS.',
+  rotate: 'rotation. A bare number is degrees: `rotate: 5` is 5deg. `5deg`, `0.1turn` and `x 30` pass through.',
   scale: 'passthrough CSS.',
   filter: 'passthrough CSS: blur(10), brightness(1.1).',
   'backdrop-filter': 'passthrough CSS: blur(10).',
@@ -116,7 +117,7 @@ export const STATES = {
 export const AT_RULES = {
   '@media': 'conditions: `@media (max-width: 860)`, sugar forms `@media dark`, `@media light`, `@media reduced-motion`, bare widths, `<=` ranges.',
   '@container': 'evaluates against the nearest ancestor (or self) with a container-type: `@container (min-width: 480)`.',
-  '@signal': 'the JS bridge: `@signal menuOpen { ... }` re-evaluates when DSSL.signal(\u0027menuOpen\u0027, true) fires. Mirrors onto data-dssl-signal-* attributes. Also `@signal screen in (menu, shop)`, `not in (a, b)` and `!=`.',
+  '@signal': 'the JS bridge: `@signal menuOpen { ... }` re-evaluates when DSSL.signal(\u0027menuOpen\u0027, true) fires. Mirrors onto data-dssl-signal-* attributes. Also `@signal screen in (menu, shop)`, `not in (a, b)` and `!=`. `DSSL.signal(name, value, el)` sets it for one subtree.',
   '@layer': 'cascade layers: `@layer base { }`, `@layer components { }`, `@layer utilities { }`. Cascade is (layer, source order) \u2014 no specificity, no !important.',
 };
 

dssl-vscode/package.json

@@ -2,7 +2,7 @@
   "name": "dssl-vscode",
   "displayName": "DSSL Language Support",
   "description": "The DSSL style language in your editor: syntax highlighting, real-compiler diagnostics (the same errors the browser console shows), completions from the live token registry and for textures, auras and sliders, hover docs, an interactive designer with sliders and live previews for aura, texture and range sliders, and a CSS to DSSL converter. Works in VS Code and VSCodium.",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "publisher": "ehs-studio",
   "icon": "icon.png",
   "license": "MIT",

engine-package/USAGE.md

@@ -68,13 +68,15 @@ Bare numbers are pixels. States like `hover` are nested blocks. The engine keeps
 - `DSSL.load(urls)` fetch and apply one or more `.dssl` files (fetched in parallel, applied in order)
 - `DSSL.apply(source, { name, scope })` apply a source string
 - `DSSL.compile(source)` parse and resolve without touching the DOM, returns `ok`, `errors` and stats
-- `DSSL.signal(name, value)` drive styles from JS with `@signal` conditions in your `.dssl`
+- `DSSL.signal(name, value)` drive styles from JS with `@signal` conditions in your `.dssl`; `DSSL.signal(name, value, el)` for one subtree only. Booleans and numbers stay booleans and numbers
 - `DSSL.refresh()` force a full recompute
 - `DSSL.replay(selector)` replay entrance motions on matching elements
 - `DSSL.errors()` a function: the last reported errors (also grouped in the console, with did-you-mean hints)
 - `DSSL.version` the engine version, a string (not a function)
 - `DSSL.toCSS(source | [sources], opts)` compile to plain CSS (the `dssl build` lane): `{ css, map, report }`
-- `DSSL.getSignal(name)` read a signal back
+- `DSSL.getSignal(name)` read a signal back (`DSSL.getSignal(name, el)` for the value an element sees)
+- `DSSL.flush()` / `await DSSL.settled()` style everything that is waiting right now, so `offsetTop` and computed styles are final; `DSSL.computed(el, prop)` is the final computed value
+- `DSSL.pauseMotion()`, `DSSL.stepMotion(ms)`, `DSSL.resumeMotion()` freeze, step and release every animation, for tests
 - `DSSL.refresh(el)` / `DSSL.freeze(el)` / `DSSL.unfreeze(el)` one subtree: restyle it, or style it once and leave it alone
 - `DSSL.explain(el)`, `await DSSL.inspect()`, `await DSSL.watch()`, `await DSSL.lint(root)` find out why a style is what it is, hot reload, check the live page
 - `DSSL.play(el, 'motion', opts)` run a motion once from JS (a promise), `DSSL.motion('full')` ignore reduced motion, `DSSL.auraZ(n)` aura canvas z-index

llms.txt

@@ -5,7 +5,7 @@
 - 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.14.0 (engine), MIT license
+- Version: 0.15.0 (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
 
@@ -43,10 +43,11 @@ 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.toCSS(src)                    // v0.8.0: the exit lane -> { css, report }
-DSSL.signal('menuOpen', true)      // the JS -> styles bridge
+DSSL.signal('menuOpen', true)      // the JS -> styles bridge; DSSL.signal(name, value, el) for one subtree
+await DSSL.settled() / DSSL.flush() // style everything waiting now (offsetTop is final after it)
 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([el]) / DSSL.errors() (a function) / DSSL.version (a string) / DSSL.getSignal(name) / DSSL.freeze([el]) / DSSL.unfreeze([el]) / await DSSL.inspect() / await DSSL.watch() / await DSSL.lint(root) / DSSL.play(el, motion, opts) / DSSL.motion('full'|'reduced'|'auto') / DSSL.auraZ(n)
+DSSL.replay(sel) / DSSL.refresh([el]) / DSSL.errors() (a function) / DSSL.version (a string) / DSSL.getSignal(name) / DSSL.freeze([el]) / DSSL.unfreeze([el]) / await DSSL.inspect() / await DSSL.watch() / await DSSL.lint(root) / DSSL.play(el, motion, opts) / DSSL.motion('full'|'reduced'|'auto') / DSSL.auraZ(n) / DSSL.computed(el, prop) / DSSL.pauseMotion() / DSSL.stepMotion(ms) / DSSL.resumeMotion()
 ```
 
 ## 0.9.0: texture, aura, sliders, lint, import
@@ -63,6 +64,15 @@ DSSL.replay(sel) / DSSL.refresh([el]) / DSSL.errors() (a function) / DSSL.versio
 - Alpha on a named colour works: `white/12`, `currentColor/20`. It used to compile to `white/12px`.
 - The playground has a canvas.html tab, `?example=` links, lint warnings and an "as CSS" tab. The canvas keeps a short allow-list of tags and drops scripts, handlers, styles and ids.
 
+## 0.15.0: the second game review
+- Aura: it follows moving things under reduced motion (a quick look every 100ms, a full frame whenever something moved), skips emitters that cannot be seen (opacity 0 or display: none or visibility: hidden on it or any ancestor, and what they let go fades with them; the word `always` keeps an invisible anchor emitting), and takes `z N` to draw a layer on its own canvas at that z-index (`aura-glow: #f80 40 z 5` goes under a hill with z-index 10; it meets elements in the root stacking context).
+- `dssl check` and the console name rules that can never apply: a rule that a LATER rule matches everywhere and overrides (`.prop.broc { z-index: 1 }` before a plain `.prop { z-index: 2 }`; there is no specificity). The same selector again is left alone, that is an override.
+- Signals keep their type (`getSignal('x')` is `true`, not `"true"`; `0` is off). `DSSL.signal(name, value, el)` scopes one to a subtree (the nearest wins). A signal restyles only the elements its rules select. `await DSSL.settled()` / `DSSL.flush()` make styling final right away.
+- `animate: blink 300 infinite, waddle 900 infinite alternate` runs several motions on one element (also on ::before and ::after, and in `dssl build`). `DSSL.play(el, 'pop', { pseudo: '::after' })`.
+- `outline-shape: 3 color.ink` outlines the shape's alpha, not its box (four hard drop-shadows, square corners; uses `filter`). `rotate: 5` is 5deg. A state inside a pseudo-element block (`::after { hover { opacity: 1 } }`) is that pseudo-element in that state. `font: bold 16px Arial` is now an error that says DSSL's `font:` is size/line-height and colour.
+- `DSSL.lint` skips invisible text and judges text-stroke and tight text-shadow. `dssl ... --engine ./dssl` (or DSSL_ENGINE) finds the engine anywhere. `DSSL.pauseMotion()`, `stepMotion(ms)`, `resumeMotion()` and `DSSL.computed(el, prop)` for tests.
+- Gradients: the first layer is the one on top.
+
 ## 0.14.0: made for games (from a review by an agent that built one)
 - Reduced motion is never silent. A plain `animate:` does not run when the system asks for reduced motion; the console now says so once, and says how to get out: put `essential` in the motion block or on the animate line, or `DSSL.motion('full')` / `<html data-dssl-motion="full">` to run everything (`'reduced'` holds all still, `'auto'` follows the system).
 - `animate: name 300 delay 100 jitter 200 iterations 3 essential`. `jitter` gives every element its own random delay, the same on every load. `animation-delay` and friends beside `animate:` now warn, because they do nothing there.
@@ -111,4 +121,4 @@ Wait for the `dssl-ready` event on `window` before measuring layout: the engine
 
 ## 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. In VSCodium, search "DSSL" in the Extensions tab (it is on Open VSX: https://open-vsx.org/extension/ehs-studio/dssl-vscode). In VS Code, download `dssl-vscode/dssl-vscode-0.14.0.vsix` from the repo files, then Extensions panel -> ... -> Install from VSIX. Source lives in `dssl-vscode/` in the repo.
+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. In VSCodium, search "DSSL" in the Extensions tab (it is on Open VSX: https://open-vsx.org/extension/ehs-studio/dssl-vscode). In VS Code, download `dssl-vscode/dssl-vscode-0.15.0.vsix` from the repo files, then Extensions panel -> ... -> Install from VSIX. Source lives in `dssl-vscode/` in the repo.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dssl",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": true,
   "description": "The DSSL style language and the website that is written in it.",
   "scripts": {

public/dssl/aura.js

@@ -49,6 +49,8 @@ export const GLOW_KEYS = {
   texture:   { kind: 'texture', words: 1, doc: 'texture(grain scale 2): break the light up with a texture' },
   essential: { kind: 'flag', words: 0, doc: 'keep animating even when the visitor prefers reduced motion' },
   unclipped: { kind: 'flag', words: 0, doc: 'let the light spill out of a parent that clips (overflow: hidden, auto, scroll). Without it the aura is cut at that edge, like the element itself' },
+  always:    { kind: 'flag', words: 0, doc: 'keep emitting even when the element cannot be seen (opacity 0, display: none, visibility: hidden, on it or an ancestor): for an invisible anchor that smoke or sparks come out of' },
+  z:         num(-1000000, 2147483000, { int: true, doc: 'the z-index of the layer this light is drawn on: `z 5` puts it under a hill with z-index 10. It meets elements in the page\'s root stacking context' }),
 };
 
 export const PARTICLE_KEYS = {
@@ -72,6 +74,8 @@ export const PARTICLE_KEYS = {
   texture:    { kind: 'texture', words: 1, doc: 'texture(grain): grainy particles' },
   essential:  { kind: 'flag', words: 0, doc: 'keep animating even when the visitor prefers reduced motion' },
   unclipped:  { kind: 'flag', words: 0, doc: 'let the particles leave a parent that clips (overflow: hidden, auto, scroll). Without it they are cut at that edge' },
+  always:     { kind: 'flag', words: 0, doc: 'keep emitting even when the element cannot be seen (opacity 0, display: none, visibility: hidden, on it or an ancestor): for an invisible anchor that smoke or sparks come out of' },
+  z:          num(-1000000, 2147483000, { int: true, doc: 'the z-index of the layer these particles are drawn on: `z 5` puts them under a hill with z-index 10. It meets elements in the page\'s root stacking context' }),
 };
 
 /* ------------------------------------------------------------------ *
@@ -382,6 +386,7 @@ export class AuraManager {
     // reduced motion draws a still picture, so it only needs a new frame when something could have moved
     this._onScroll = () => { if (this.reduced && !this.running && !this.paused && this.emitters.size) this.start(); };
     this._poll = null;
+    this.extra = new Map();        // z-index -> { canvas, ctx }: layers asked for with `z N`
     this._frame = (t) => this.frame(t);
   }
 
@@ -418,11 +423,62 @@ export class AuraManager {
     if (!this.canvas) return;
     this.dpr = Math.min(2, window.devicePixelRatio || 1);
     this.vw = window.innerWidth; this.vh = window.innerHeight;
-    this.canvas.width = Math.max(1, Math.round(this.vw * this.dpr));
-    this.canvas.height = Math.max(1, Math.round(this.vh * this.dpr));
+    for (const c of this.allCanvases()) {
+      c.width = Math.max(1, Math.round(this.vw * this.dpr));
+      c.height = Math.max(1, Math.round(this.vh * this.dpr));
+    }
     this.dirty = true;
   }
 
+  allCanvases() { return [this.canvas, ...[...this.extra.values()].map((e) => e.canvas)]; }
+
+  /** the drawing context for a layer: the default canvas, or the one at the z-index the layer asked for (`z 5`) */
+  ctxFor(z) {
+    if (z === undefined || z === null) return this.ctx;
+    let e = this.extra.get(z);
+    if (!e) {
+      const c = document.createElement('canvas');
+      c.setAttribute('aria-hidden', 'true');
+      c.setAttribute('data-dssl-aura', String(z));
+      c.style.cssText = `position:fixed;left:0;top:0;width:100vw;height:100vh;pointer-events:none;z-index:${z};`;
+      c.width = this.canvas.width; c.height = this.canvas.height;
+      (document.body || document.documentElement).appendChild(c);
+      e = { canvas: c, ctx: c.getContext('2d') };
+      this.extra.set(z, e);
+    }
+    return e.ctx;
+  }
+
+  /** how visible an element really is: its opacity times every ancestor's; 0 for display: none or visibility: hidden */
+  effectiveOpacity(el) {
+    try {
+      let o = 1;
+      if (getComputedStyle(el).visibility !== 'visible') return 0;
+      for (let a = el; a && a.nodeType === 1; a = a.parentElement) {
+        const cs = getComputedStyle(a);
+        if (cs.display === 'none') return 0;
+        o *= parseFloat(cs.opacity);
+        if (!(o > 0.004)) return 0;
+      }
+      return o;
+    } catch { return 1; }
+  }
+
+  /** what a frame would draw for this emitter, as a string: the same string twice means nothing needs redrawing */
+  stateKey(el, eo) {
+    const r = el.getBoundingClientRect();
+    return `${r.left.toFixed(1)},${r.top.toFixed(1)},${r.width.toFixed(1)},${r.height.toFixed(1)},${eo.toFixed(2)}`;
+  }
+
+  /** reduced motion: has anything moved, resized or faded since the last frame? (cheap: no drawing) */
+  peek() {
+    for (const [el, em] of this.emitters) {
+      if (!el.isConnected) return true;
+      if (this.stateKey(el, this.effectiveOpacity(el)) !== em.key) return true;
+    }
+    return false;
+  }
+
   /* ---- the engine's interface ---- */
 
   /** Set (or change) the aura of an element. glow/particles are arrays of resolved layers. */
@@ -458,7 +514,7 @@ export class AuraManager {
     this.start();
   }
 
-  pause() { this.paused = true; this.running = false; if (this._poll) { clearTimeout(this._poll); this._poll = null; } if (this.ctx) this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height); }
+  pause() { this.paused = true; this.running = false; if (this._poll) { clearTimeout(this._poll); this._poll = null; } if (this.ctx) for (const c of this.allCanvases()) c.getContext('2d').clearRect(0, 0, c.width, c.height); }
   resume() { this.paused = false; this.start(); }
 
   destroy() {
@@ -467,6 +523,8 @@ export class AuraManager {
     window.removeEventListener('scroll', this._onScroll, { capture: true });
     if (this._poll) { clearTimeout(this._poll); this._poll = null; }
     if (this.io) this.io.disconnect();
+    for (const e of this.extra.values()) e.canvas.remove();
+    this.extra.clear();
     if (this.canvas) this.canvas.remove();
     this.canvas = null; this.ctx = null; this.emitters.clear();
   }
@@ -486,11 +544,15 @@ export class AuraManager {
     const dt = this.last ? Math.min(0.05, (now - this.last) / 1000) : 0.016;
     this.last = now;
     const reduced = this.reduced;
-    const ctx = this.ctx, dpr = this.dpr;
+    const dpr = this.dpr;
 
-    ctx.setTransform(1, 0, 0, 1, 0, 0);
-    ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
-    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    for (const c of this.allCanvases()) {
+      const x = c.getContext('2d');
+      x.setTransform(1, 0, 0, 1, 0, 0);
+      x.clearRect(0, 0, c.width, c.height);
+      x.setTransform(dpr, 0, 0, dpr, 0, 0);
+    }
+    let changed = false;
 
     // global budget: if everyone asks for more than the page can afford, everyone gets a share
     let want = 0;
@@ -498,6 +560,7 @@ export class AuraManager {
     const share = want > this.budget ? this.budget / want : 1;
 
     let alive = 0, anyActive = false;
+    this._n = (this._n || 0) + 1;
     for (const [el, em] of this.emitters) {
       if (!el.isConnected) { this.emitters.delete(el); if (this.io) this.io.unobserve(el); continue; }
       // read geometry once per frame for visible emitters
@@ -507,6 +570,12 @@ export class AuraManager {
         if (rect.width === 0 && rect.height === 0) rect = null;
       }
       em.rect = rect;
+      // 0.15.0: an emitter that cannot be seen (opacity 0 on it or any ancestor, display: none, visibility: hidden) does not emit, and
+      // what it already let go fades with it. Looked up every third frame, or every frame in reduced motion where frames are rare.
+      if (em.eo === undefined || reduced || this._n % 3 === 0) em.eo = this.effectiveOpacity(el);
+      if (em.layers.some((l) => l.cfg.always) || em.glow.some((g) => g.cfg.always)) em.eo = 1;   // an invisible anchor on purpose
+      const key = this.stateKey(el, em.eo);
+      if (key !== em.key) { em.key = key; changed = true; }
       // 0.14.0: a stage scaled with transform: scale() has a rect the size you SEE, so the light follows it, and so must its size
       // and speed. The scale is how much bigger (or smaller) the box is than the box CSS says it is.
       em.scale = 1;
@@ -518,11 +587,13 @@ export class AuraManager {
 
       // 0.14.0: cut the light at the edge of any parent that clips, so a stage with overflow: hidden keeps its fire inside
       const clipped = rect && em.clips && em.clips.length ? this.clipRect(em.clips) : null;
-      if (clipped) { ctx.save(); ctx.beginPath(); ctx.rect(clipped.x, clipped.y, clipped.w, clipped.h); ctx.clip(); }
+      const open = (ctx) => { if (clipped) { ctx.save(); ctx.beginPath(); ctx.rect(clipped.x, clipped.y, clipped.w, clipped.h); ctx.clip(); } };
+      const close = (ctx) => { if (clipped) ctx.restore(); };
+      const seen = em.eo > 0.004;
 
       // glow
-      if (rect && em.fade > 0 && (em.visible || em.dying)) {
-        for (const g of em.glow) { this.drawGlow(ctx, rect, em, g, now, reduced); }
+      if (rect && em.fade > 0 && (em.visible || em.dying) && seen) {
+        for (const g of em.glow) { const ctx = this.ctxFor(g.cfg.z); open(ctx); this.drawGlow(ctx, rect, em, g, now, reduced); close(ctx); }
         if (em.glow.length) anyActive = true;
       }
 
@@ -531,12 +602,12 @@ export class AuraManager {
         const cfg = L.cfg;
         const moving = !reduced || cfg.essential;
         L.scale = em.scale;
-        if (rect && em.visible && !em.dying && moving) this.emit(L, rect, em, dt, share, el);
-        if (L.parts.length) this.stepAndDraw(ctx, L, dt, moving, cfg.behind && rect ? { rect, radius: em.radius } : null);
+        L.eo = em.eo;
+        if (rect && em.visible && !em.dying && moving && seen) this.emit(L, rect, em, dt, share, el);
+        if (L.parts.length) { const ctx = this.ctxFor(cfg.z); open(ctx); this.stepAndDraw(ctx, L, dt, moving, cfg.behind && rect ? { rect, radius: em.radius } : null); close(ctx); }
         alive += L.parts.length;
-        if (L.parts.length || (rect && em.visible && !em.dying && moving)) anyActive = true;
+        if (L.parts.length || (rect && em.visible && !em.dying && moving && seen)) anyActive = true;
       }
-      if (clipped) ctx.restore();
       if (em.dying && em.fade <= 0 && em.layers.every((l) => !l.parts.length)) {
         this.emitters.delete(el);
         if (this.io) this.io.unobserve(el);
@@ -550,12 +621,14 @@ export class AuraManager {
     this._fpsN++;
     if (now - this._fpsT > 500) { this.stats.fps = Math.round((this._fpsN * 1000) / Math.max(1, now - this._fpsT)); this._fpsT = now; this._fpsN = 0; }
 
-    if (this.emitters.size === 0) { this.running = false; ctx.clearRect(0, 0, this.vw, this.vh); return; }
+    if (this.emitters.size === 0) { this.running = false; for (const c of this.allCanvases()) c.getContext('2d').clearRect(0, 0, c.width, c.height); return; }
     // Normally the loop runs every frame (the glow follows the element, particles move). With reduced
     // motion nothing moves, so one frame is a complete picture; it is redrawn on scroll, resize, a
-    // style change, and a slow poll for layout shifts. Essential layers and fading-out emitters still loop.
+    // style change, and a quick look (peek) for anything that moved. A frame that saw something move, resize or fade asks for the next one,
+    // so a glow on a thing that moves under reduced motion follows it every frame instead of lagging. Essential layers and fading-out emitters still loop.
     let needLoop = !reduced;
     if (reduced) {
+      if (changed) needLoop = true;
       for (const em of this.emitters.values()) {
         if (em.dying) needLoop = true;
         if (em.glow.some((g) => g.cfg.essential) || em.layers.some((l) => l.cfg.essential && (l.parts.length || (em.visible && !em.dying)))) needLoop = true;
@@ -563,7 +636,17 @@ export class AuraManager {
     }
     if (needLoop) { requestAnimationFrame(this._frame); return; }
     this.running = false;
-    if (!this._poll) this._poll = setTimeout(() => { this._poll = null; this.start(); }, 600);
+    this.watchStill();
+  }
+
+  /** reduced motion, nothing moving: look every 100ms (a few rect reads, no drawing) and draw again the moment something changed */
+  watchStill() {
+    if (this._poll || this.paused) return;
+    this._poll = setTimeout(() => {
+      this._poll = null;
+      if (this.running || !this.canvas) return;
+      if (this.peek()) this.start(); else this.watchStill();
+    }, 100);
   }
 
   /** the ancestors that clip their children (overflow other than visible), unless this emitter said `unclipped` */
@@ -604,7 +687,7 @@ export class AuraManager {
   drawGlow(ctx, rect, em, g, now, reduced) {
     const cfg = g.cfg;
     const moving = !reduced || cfg.essential;
-    let a = cfg.intensity * em.fade;
+    let a = cfg.intensity * em.fade * (em.eo === undefined ? 1 : em.eo);
     if (moving && cfg.pulse > 0) {
       const ph = ((now - g.t0) / cfg.pulse) * TAU;
       a *= 1 - cfg.depth * 0.5 * (1 + Math.sin(ph)) ;
@@ -819,7 +902,7 @@ export class AuraManager {
       }
       const t = p.age / p.life;
       const col = colorAt(c.stops, t);
-      const alpha = clamp01(col.a);
+      const alpha = clamp01(col.a) * (L.eo === undefined ? 1 : L.eo);
       if (alpha <= 0.003) continue;
       const size = p.size * lerp(1, c.grow, t);
       this.drawParticle(ctx, c, p, col, alpha, size);

public/dssl/dev.js

@@ -9,6 +9,7 @@
  * ========================================================================= */
 
 import { parseColor, over, contrast, toHex } from './color.js';
+import { shadowWarnings } from './lint.js';
 
 const HOST_ID = 'dssl-dev-host';
 
@@ -221,6 +222,24 @@ export function lintDocument(root, { explain, engines }, opts = {}) {
   };
   const opacityOf = (el) => { let o = 1; for (let n = el; n && n.nodeType === 1; n = n.parentElement) o *= parseFloat(getComputedStyle(n).opacity) || 0; return o; };
 
+  // text-stroke and text-shadow are how game and poster text stays readable on any background. The letters count as readable when the
+  // outline (a stroke of 1px or more) or a tight shadow (blur up to 4px) is a colour the letters themselves stand out against.
+  const outlined = (cs, fg, need) => {
+    const sw = parseFloat(cs.webkitTextStrokeWidth) || 0;
+    if (sw >= 1) { const sc = parseColor(cs.webkitTextStrokeColor); if (sc && sc.a > 0.5 && contrast(over(fg, { ...sc, a: 1 }), { ...sc, a: 1 }) >= need) return true; }
+    const ts = cs.textShadow;
+    if (ts && ts !== 'none') {
+      for (const part of ts.split(/,(?![^(]*\))/)) {
+        const cm = /rgba?\([^)]*\)/.exec(part);
+        const sc = cm && parseColor(cm[0]);
+        const nums = part.replace(/rgba?\([^)]*\)/, '').trim().split(/\s+/).map((x) => parseFloat(x));
+        const blur = nums[2] || 0;
+        if (sc && sc.a > 0.5 && blur <= 4 && contrast(over(fg, { ...sc, a: 1 }), { ...sc, a: 1 }) >= need) return true;
+      }
+    }
+    return false;
+  };
+
   const seen = new Set();
   const walker = document.createTreeWalker(scope, NodeFilter.SHOW_TEXT);
   for (let t = walker.nextNode(); t; t = walker.nextNode()) {
@@ -237,11 +256,13 @@ export function lintDocument(root, { explain, engines }, opts = {}) {
     const bg = backdrop(el);
     if (!fg || !bg) continue;
     const op = opacityOf(el);
+    if (op < 0.05) continue;                 // invisible (a closed menu, a hidden toast): judging it against itself is noise
     const solidFg = over({ ...fg, a: fg.a * op }, bg);
     const ratio = contrast(solidFg, bg);
     const size = parseFloat(cs.fontSize) || 16, bold = (parseInt(cs.fontWeight, 10) || 400) >= 700;
     const large = size >= 24 || (size >= 18.66 && bold);
     const need = large ? Math.min(min, 3) : min;
+    if (ratio < need && outlined(cs, fg, need)) continue;   // an outline or hard shadow that sets the letters apart carries them
     if (ratio < need) {
       out.push({ kind: 'contrast', el, selector: describe(el), ratio: Math.round(ratio * 100) / 100, fg: toHex(solidFg), bg: toHex(bg), message: `text is ${ratio.toFixed(1)}:1 against what is behind it (${toHex(solidFg)} on ${toHex(bg)}), below ${need}:1${large ? ' for large text' : ''}` });
     }
@@ -256,6 +277,7 @@ export function lintDocument(root, { explain, engines }, opts = {}) {
         out.push({ kind: 'promoted', el, selector: describe(el), message: `the engine made this a ${disp.value} because a rule aligns its children without a display (it was ${natural}); dssl build will not` });
       }
     }
+    for (const w of shadowWarnings(eng.rules || [])) out.push({ kind: 'shadowed', el: null, selector: `${w.file || ''}:${w.line ?? ''}`, message: w.message });
     if (eng._reducedTold) out.push({ kind: 'motion', el: null, selector: '(page)', message: 'some animate: motions did not run because reduced motion is on; mark the ones that carry meaning `essential`, or DSSL.motion("full")' });
   }
   if (opts.log !== false && out.length) {

public/dssl/engine.js

@@ -25,7 +25,8 @@ import { buildTexture, composeTextureInto, splitBgList as splitList } from './te
 import { AuraManager, resolveLayer } from './aura.js';
 import { parseColor } from './color.js';
 import { tiltTransform } from './effects.js';
-import { keyframesCss, animationShorthand } from './static.js';
+import { keyframesCss, animationShorthand } from './static.js'
+import { shadowWarnings } from './lint.js';
 
 const LAYER_RANK = { tokens: 0, base: 1, components: 2, utilities: 3, pin: 4 };
 
@@ -180,6 +181,10 @@ export class DsslEngine {
     this.rules = [];
     this.shadowRules = [];
     this.signalStore = new Map();
+    this.scopedSignals = new WeakMap();    // 0.15.0: element -> Map(name -> value) for DSSL.signal(name, value, el)
+    this.scopedCount = 0;
+    this.sigShadowIdx = [];                // 0.15.0: indexes of the pseudo-element rules that sit behind a @signal
+    this.motionHeld = false;               // 0.15.0: DSSL.pauseMotion()
     this.mqlCache = new Map();
     this.containerEls = new Set();
     this.ownMap = new WeakMap();           // element -> [props DSSL owns]
@@ -437,6 +442,19 @@ export class DsslEngine {
     this.init();
     this.renderShadow();
     this.computeAll();
+    this.reportShadowed(rules);
+  }
+
+  /** 0.15.0: say, once each, which rules can never apply because a later rule beats them everywhere (no specificity: the later one wins) */
+  reportShadowed(rules) {
+    try {
+      if (!this._shadowTold) this._shadowTold = new Set();
+      const fresh = shadowWarnings(rules).filter((w) => { const k = w.file + ':' + w.line + '|' + w.message; if (this._shadowTold.has(k)) return false; this._shadowTold.add(k); return true; });
+      if (!fresh.length) return;
+      console.groupCollapsed(`%c[DSSL] ${fresh.length} rule(s) can never apply`, 'color:#8a6d1a;font-weight:bold');
+      for (const w of fresh) console.warn(`${w.file || ''}:${w.line ?? ''} - ${w.message}\n    ${w.hint}`);
+      console.groupEnd();
+    } catch { /* a lint must never break the page */ }
   }
 
   /** 0.12.0: fonts { } becomes <link> tags in <head>, one per URL, removed again when no sheet asks for it */
@@ -532,55 +550,7 @@ export class DsslEngine {
     }
 
     // --- DOM mutations ---
-    const mo = new MutationObserver((muts) => {
-      if (this.frozen) return; // v0.7.0 - a frozen engine sees a snapshot, not a live page
-      if (this._applying) return; // our own style writes - ignore
-      const batch = new Set();
-      let fullSweep = false;
-      for (const m of muts) {
-        if (m.type === 'attributes') {
-          if (m.attributeName === 'style') continue;
-          if (m.target === document.documentElement && m.attributeName.startsWith('data-dssl')) continue;
-          batch.add(m.target);
-          // class/attr changes can affect descendant rules - include small subtrees.
-          // v0.3.3: when the changed element owns a HUGE subtree (view root flips
-          // like data-view on the site shell), don't skip the descendants - a full
-          // debounced sweep keeps every descendant rule honest. Skipping is what
-          // left the nav highlight stuck on the boot-time view after SPA routing.
-          if (m.target.querySelectorAll) {
-            const kids = m.target.querySelectorAll('*');
-            if (kids.length <= 300) kids.forEach(k => batch.add(k));
-            else fullSweep = true;
-          }
-        } else {
-          if (m.addedNodes) m.addedNodes.forEach(n => {
-            if (n.nodeType !== 1) return;
-            batch.add(n);
-            if (n.querySelectorAll) n.querySelectorAll('*').forEach(k => batch.add(k));
-          });
-          if (m.removedNodes) m.removedNodes.forEach(n => {
-            if (n.nodeType !== 1) return;
-            this.touched.delete(n);
-            this.overlapEls.delete(n);   // v0.5.0 - dropped policies must not pin the pass
-            this.nudgedEls.delete(n);
-            if (n.querySelectorAll) n.querySelectorAll('*').forEach(k => {
-              this.touched.delete(k);
-              this.overlapEls.delete(k);
-              this.nudgedEls.delete(k);
-            });
-          });
-        }
-      }
-      if (fullSweep) {
-        // one full recompute per microtask burst, same drain the scheduler uses
-        if (!this._sweepQueued) {
-          this._sweepQueued = true;
-          queueMicrotask(() => { this._sweepQueued = false; this.computeAll(); });
-        }
-        return;
-      }
-      if (batch.size) this.schedule(batch);
-    });
+    const mo = new MutationObserver((muts) => this.onMutations(muts));
     mo.observe(doc, { childList: true, subtree: true, attributes: true, attributeFilter: undefined });
     this._mo = mo;
     this.startOverlapTimer();
@@ -735,17 +705,80 @@ export class DsslEngine {
     els.forEach(el => this.pending.add(el));
     if (this.scheduled) return;
     this.scheduled = true;
-    queueMicrotask(() => {
-      this.scheduled = false;
-      const batch = [...this.pending];
-      this.pending.clear();
-      this._applying = true;
-      for (const el of batch) this.computeElement(el);
-      this._applying = false;
-      this.applyStagger();
-      this.applyArc();          // v0.6.0 - bend-around arcs after every drain
-      this.scheduleOverlap();   // v0.5.0 - nudges read fresh boxes after the writes settle
-    });
+    queueMicrotask(() => { this.scheduled = false; this.drainPending(); });
+  }
+
+  drainPending() {
+    if (!this.pending.size) return;
+    const batch = [...this.pending];
+    this.pending.clear();
+    this._applying = true;
+    for (const el of batch) this.computeElement(el);
+    this._applying = false;
+    this.applyStagger();
+    this.applyArc();          // v0.6.0 - bend-around arcs after every drain
+    this.scheduleOverlap();   // v0.5.0 - nudges read fresh boxes after the writes settle
+  }
+
+  /** 0.15.0: do now what the engine has queued for the next microtask: DOM changes the observer has not delivered, restyles, signals.
+   *  After this, computed styles and layout are final. DSSL.settled() is the awaitable version. */
+  flush() {
+    if (this.frozen) return;
+    if (this._mo) { const recs = this._mo.takeRecords(); if (recs.length) this.onMutations(recs); }
+    if (this._sweepQueued || this._allQueued) { this._sweepQueued = false; this._allQueued = false; this._sigNames = null; this._sigScopes = null; this._sigGlobal = false; this.computeAll(); }
+    else this.flushSignals();
+    this.drainPending();
+  }
+
+  /** what the page changed (the MutationObserver's work, also run by flush()) */
+  onMutations(muts) {
+    if (this.frozen) return; // v0.7.0 - a frozen engine sees a snapshot, not a live page
+    if (this._applying) return; // our own style writes - ignore
+    const batch = new Set();
+    let fullSweep = false;
+    for (const m of muts) {
+      if (m.type === 'attributes') {
+        if (m.attributeName === 'style' || m.attributeName === 'data-dssl-s') continue;
+        if (m.target === document.documentElement && m.attributeName.startsWith('data-dssl')) continue;
+        batch.add(m.target);
+        // class/attr changes can affect descendant rules - include small subtrees.
+        // v0.3.3: when the changed element owns a HUGE subtree (view root flips
+        // like data-view on the site shell), don't skip the descendants - a full
+        // debounced sweep keeps every descendant rule honest. Skipping is what
+        // left the nav highlight stuck on the boot-time view after SPA routing.
+        if (m.target.querySelectorAll) {
+          const kids = m.target.querySelectorAll('*');
+          if (kids.length <= 300) kids.forEach(k => batch.add(k));
+          else fullSweep = true;
+        }
+      } else {
+        if (m.addedNodes) m.addedNodes.forEach(n => {
+          if (n.nodeType !== 1) return;
+          batch.add(n);
+          if (n.querySelectorAll) n.querySelectorAll('*').forEach(k => batch.add(k));
+        });
+        if (m.removedNodes) m.removedNodes.forEach(n => {
+          if (n.nodeType !== 1) return;
+          this.touched.delete(n);
+          this.overlapEls.delete(n);   // v0.5.0 - dropped policies must not pin the pass
+          this.nudgedEls.delete(n);
+          if (n.querySelectorAll) n.querySelectorAll('*').forEach(k => {
+            this.touched.delete(k);
+            this.overlapEls.delete(k);
+            this.nudgedEls.delete(k);
+          });
+        });
+      }
+    }
+    if (fullSweep) {
+      // one full recompute per microtask burst, same drain the scheduler uses
+      if (!this._sweepQueued) {
+        this._sweepQueued = true;
+        queueMicrotask(() => { if (!this._sweepQueued) return; this._sweepQueued = false; this.computeAll(); });
+      }
+      return;
+    }
+    if (batch.size) this.schedule(batch);
   }
 
   /* v0.4.1 - coalesced full recompute for ambient triggers (ResizeObserver,
@@ -756,7 +789,7 @@ export class DsslEngine {
     if (this.frozen) return;         // v0.7.0 - frozen: no ambient recompute
     if (this._allQueued) return;
     this._allQueued = true;
-    queueMicrotask(() => { this._allQueued = false; this.computeAll(); });
+    queueMicrotask(() => { if (!this._allQueued) return; this._allQueued = false; this.computeAll(); });
   }
 
   matches(el, sel) {
@@ -768,11 +801,43 @@ export class DsslEngine {
     return this.scope === el || this.scope.contains(el);
   }
 
-  signalsPass(rule) {
+  /** the elements a signal-gated pseudo-element rule is about: its selector without the states (hover...) it also needs */
+  sigShadowBase(r) {
+    if (r._base === undefined) r._base = (r.sel || '*').replace(STATE_PSEUDO_RE, '').trim() || '*';
+    return r._base;
+  }
+
+  /** keep data-dssl-s on an element: the numbers of the signal-gated pseudo-element rules that are on for it right now */
+  markSignalShadow(el) {
+    let on = '';
+    for (const idx of this.sigShadowIdx) {
+      const r = this.shadowRules[idx];
+      if (!r || !this.matches(el, this.sigShadowBase(r))) continue;
+      if (!this.signalsPass(r, el)) continue;
+      on += (on ? ' ' : '') + idx;
+    }
+    const cur = el.getAttribute('data-dssl-s');
+    try {
+      if (on) { if (cur !== on) el.setAttribute('data-dssl-s', on); }
+      else if (cur !== null) el.removeAttribute('data-dssl-s');
+    } catch { /* detached */ }
+  }
+
+  /** a signal's value for an element: the nearest ancestor (or itself) that was given its own (DSSL.signal(name, value, el)), else the global one */
+  sigLookup(el, name) {
+    if (this.scopedCount && el) {
+      for (let a = el; a; a = a.parentElement) {
+        const m = this.scopedSignals.get(a);
+        if (m && m.has(name)) return { has: true, val: m.get(name) };
+      }
+    }
+    return this.signalStore.has(name) ? { has: true, val: this.signalStore.get(name) } : { has: false, val: undefined };
+  }
+
+  signalsPass(rule, el) {
     for (const s of rule.signals) {
-      const has = this.signalStore.has(s.name);
-      const val = this.signalStore.get(s.name);
-      if (s.op === 'truthy') { if (!has || val === false || val === null || val === 'false') return false; }
+      const { has, val } = this.sigLookup(el, s.name);
+      if (s.op === 'truthy') { if (!has || val === false || val === null || val === 'false' || val === 0 || val === '0') return false; }
       else if (s.op === '==') { if (!has || String(val) !== String(s.value)) return false; }
       else if (s.op === '!=') { if (has && String(val) === String(s.value)) return false; }
       else if (s.op === 'in') { if (!has || !(s.values || []).includes(String(val))) return false; }          // 0.14.0
@@ -817,6 +882,7 @@ export class DsslEngine {
       try { found = root.querySelectorAll(sel); } catch { continue; }
       found.forEach(el => els.add(el));
     }
+    for (const idx of this.sigShadowIdx) { try { root.querySelectorAll(this.sigShadowBase(this.shadowRules[idx])).forEach((el) => els.add(el)); } catch { /* bad selector */ } }
     for (const el of els) this.computeElement(el);
     this._forceCompute = false;
     this._applying = false;
@@ -841,6 +907,7 @@ export class DsslEngine {
     // a signal no longer walk it. DSSL.freeze(el) marks one and DSSL.refresh(el) restyles it on demand.
     if (this.staticSeen && !this._forceCompute && this.ownMap.has(el) && el.closest('[data-dssl-static]')) return;
     this.touched.add(el);
+    if (this.sigShadowIdx.length) this.markSignalShadow(el);
 
     const matched = [];
     const rootEl = this.scope || document.documentElement;
@@ -867,7 +934,7 @@ export class DsslEngine {
         if (!this.matches(el, sel)) continue;
       }
       if (!rule.media.every(q => this.mql(q).matches)) continue;
-      if (!this.signalsPass(rule)) continue;
+      if (!this.signalsPass(rule, el)) continue;
       if (!this.containerPass(el, rule)) continue;
       matched.push(rule);
     }
@@ -968,10 +1035,11 @@ export class DsslEngine {
     {
       let i = 0;
       for (const rule of matched) {
+        let nth = 0;   // 0.15.0: several motions in one rule (animate: a 300, b 500) each need their own key
         for (const d of rule.decls) {
           if (d.prop !== '@animate' || d.value === null) continue;
           const spec = animSpecs[i++];
-          if (spec) spec.key = rule.id + '|' + rule.media.join('&') + '|' + rule.signals.map(s => s.name + s.op + s.value).join('&');
+          if (spec) spec.key = rule.id + '|' + rule.media.join('&') + '|' + rule.signals.map(s => s.name + s.op + s.value).join('&') + '#' + (nth++);
         }
       }
     }
@@ -1202,6 +1270,7 @@ export class DsslEngine {
           direction: spec.direction || 'normal',   // v0.5.0 - `alternate`
         });
         if (spec.iterations === Infinity) this._hasInfiniteAnims = true;
+        if (this.motionHeld) { try { anim.pause(); } catch { /* ignore */ } }   // DSSL.pauseMotion(): new motions start held too
         anims.set(spec.key, anim);
       } catch { /* WAAPI unsupported property - skip */ }
       this._overlapDirty = true;   // moving boxes can create (or clear) overlaps
@@ -1512,22 +1581,71 @@ export class DsslEngine {
    * Signals (JS → styles bridge)
    * ------------------------------------------------------------ */
 
-  signal(name, value) {
-    if (value === null || value === undefined) this.signalStore.delete(name);
-    else this.signalStore.set(name, String(value));
+  /** DSSL.signal(name, value) sets it for the whole page; DSSL.signal(name, value, el) only for el and what is inside it (the
+   *  nearest one wins). Booleans and numbers stay booleans and numbers for getSignal(); the data-dssl-signal-* mirror is text. */
+  signal(name, value, scope) {
+    const off = value === null || value === undefined;
+    const target = scope && scope.nodeType === 1 ? scope : null;
+    if (target) {
+      let m = this.scopedSignals.get(target);
+      if (off) { if (m && m.delete(name)) { this.scopedCount--; if (!m.size) this.scopedSignals.delete(target); } }
+      else {
+        if (!m) { m = new Map(); this.scopedSignals.set(target, m); }
+        if (!m.has(name)) this.scopedCount++;
+        m.set(name, value);
+      }
+    } else if (off) this.signalStore.delete(name);
+    else this.signalStore.set(name, value);
     // DevTools-visible mirror
     try {
-      if (value === null || value === undefined) document.documentElement.removeAttribute('data-dssl-signal-' + name);
-      else document.documentElement.setAttribute('data-dssl-signal-' + name, String(value));
+      const host = target || document.documentElement;
+      if (off) host.removeAttribute('data-dssl-signal-' + name);
+      else host.setAttribute('data-dssl-signal-' + name, String(value));
     } catch { }
+    // 0.15.0: only the rules that mention this signal are looked at, and only the elements they select (inside the scope, if given),
+    // not the whole page. A burst of signals in one task is one pass.
+    if (!this._sigNames) this._sigNames = new Set();
+    this._sigNames.add(name);
+    if (target) { if (!this._sigScopes) this._sigScopes = new Set(); this._sigScopes.add(target); } else this._sigGlobal = true;
     // v0.7.0 - a frozen engine has no ambient drain, but an explicit signal()
     // is a developer action: drain synchronously so signals keep working
     // while the observers sleep.
-    if (this.frozen) { this.freezeNotice(); this.computeAll(); return; }
-    this.scheduleComputeAll();
+    if (this.frozen) { this.freezeNotice(); this.flushSignals(); return; }
+    if (this._sigQueued) return;
+    this._sigQueued = true;
+    queueMicrotask(() => { this._sigQueued = false; this.flushSignals(); });
   }
 
-  getSignal(name) { return this.signalStore.get(name); }
+  flushSignals() {
+    const names = this._sigNames;
+    if (!names || !names.size) return;
+    const scopes = this._sigScopes, global = this._sigGlobal;
+    this._sigNames = null; this._sigScopes = null; this._sigGlobal = false;
+    const rules = this.rules.filter((r) => r.signals.some((x) => names.has(x.name)));
+    const shadows = this.sigShadowIdx.map((i) => this.shadowRules[i]).filter((r) => r.signals.some((x) => names.has(x.name)));
+    if (!rules.length && !shadows.length) return;       // nothing is styled by this signal
+    const rootEl = this.scope || document.documentElement;
+    const root = this.scope || document;
+    const els = new Set();
+    for (const rule of rules) {
+      if (rule.sel === ':root') { els.add(rootEl); continue; }
+      let sel = rule.sel;
+      if (rule.states.has('seen')) sel = sel.replace(/:seen\b/g, '') || '*';
+      let found;
+      try { found = root.querySelectorAll(sel); } catch { continue; }
+      found.forEach((el) => els.add(el));
+    }
+    for (const r of shadows) { try { root.querySelectorAll(this.sigShadowBase(r)).forEach((el) => els.add(el)); } catch { /* bad selector */ } }
+    const inside = (el) => { if (global) return true; for (const sc of scopes) if (sc === el || sc.contains(el)) return true; return false; };
+    this._applying = true;
+    try { for (const el of els) if (inside(el)) this.computeElement(el); }
+    finally { this._applying = false; }
+    this.applyStagger();
+    this.applyArc();
+    this.scheduleOverlap();
+  }
+
+  getSignal(name, el) { return this.sigLookup(el, name).val; }
 
   /* ------------------------------------------------------------ *
    * v0.7.0 - freeze / unfreeze: the speed escape hatch.
@@ -1625,7 +1743,7 @@ export class DsslEngine {
         if (!this.matches(el, sel)) continue;
       }
       if (!rule.media.every(q => this.mql(q).matches)) continue;
-      if (!this.signalsPass(rule)) continue;
+      if (!this.signalsPass(rule, el)) continue;
       if (!this.containerPass(el, rule)) continue;
       matched.push(rule);
     }
@@ -1653,7 +1771,7 @@ export class DsslEngine {
       const sel = r.sel || '*';
       if (!this.matches(el, sel)) continue;
       if (!r.media.every(q => this.mql(q).matches)) continue;
-      if (!this.signalsPass(r)) continue;
+      if (!this.signalsPass(r, el)) continue;
       if (!this.containerPass(el, r)) continue;
       pseudo.push({ sel: r.sel, pseudo: r.pseudo, layer: r.layer, file: r.file, line: r.line, decls: r.decls });
     }
@@ -1683,28 +1801,22 @@ export class DsslEngine {
 
     const prefix = this.scope ? `[${idAttr}="${this.name}"] ` : '';
 
-    const cssFor = (r) => {
-      let sel = prefix + r.sel + '::' + r.pseudo;
-      for (const s of r.signals) {
-        const attr = 'data-dssl-signal-' + s.name;
-        const eq = (v) => `[${attr}="${v}"]`;
-        const cond = s.op === 'truthy' ? `html[${attr}]`
-          : s.op === '!=' ? `html:not(${eq(s.value)})`
-          : s.op === 'in' ? `html:is(${(s.values || []).map(eq).join(', ')})`
-          : s.op === 'notin' ? `html:not(:is(${(s.values || []).map(eq).join(', ')}))`
-          : `html${eq(s.value)}`;
-        sel = cond + ' ' + sel;
-      }
+    const cssFor = (r, idx) => {
+      // 0.15.0: a pseudo-element rule behind a @signal is switched by a marker the engine keeps on the element (data-dssl-s lists the rule
+      // numbers that are on for it). The engine already knows which signal value an element sees (the nearest scope wins), which CSS cannot say.
+      let sel = prefix + r.sel + (r.signals.length ? `[data-dssl-s~="${idx}"]` : '') + '::' + r.pseudo;
       let body = r.decls.filter((d) => !d.prop.startsWith('@')).map(d => `  ${d.prop}: ${d.value};`).join('\n');
       // 0.14.0: animate: on ::before / ::after is a CSS animation (WAAPI cannot reach a pseudo-element). Unless the motion is
       // essential it sits behind the reduced-motion check, with data-dssl-motion able to force it on or off.
-      const an = r.decls.find((d) => d.prop === '@animate' && d.value);
-      const anim = an && animationShorthand(an.value);
+      const ans = r.decls.filter((d) => d.prop === '@animate' && d.value && animationShorthand(d.value));
+      const list = (xs) => xs.map((d) => animationShorthand(d.value)).join(', ');
       let extra = '';
-      if (anim) {
-        if (an.value.essential || r.signals.length) body += `${body ? '\n' : ''}  animation: ${anim};`;
-        else {
-          const mk = (s) => `${s} {\n  animation: ${anim};\n}`;
+      if (ans.length) {
+        // the essential ones always run (so does everything behind a signal); the rest wait for the reduced-motion check
+        const always = r.signals.length ? ans : ans.filter((d) => d.value.essential);
+        if (always.length) body += `${body ? '\n' : ''}  animation: ${list(always)};`;
+        if (always.length < ans.length) {
+          const mk = (s) => `${s} {\n  animation: ${list(ans)};\n}`;
           extra = `\n\n@media (prefers-reduced-motion: no-preference) {\n${mk('html:not([data-dssl-motion="reduced"]) ' + sel)}\n}\n\n${mk('html[data-dssl-motion="full"] ' + sel)}`;
         }
       }
@@ -1714,6 +1826,8 @@ export class DsslEngine {
       return out;
     };
 
+    this.sigShadowIdx = [];
+    this.shadowRules.forEach((r, i) => { if (r.signals.length) this.sigShadowIdx.push(i); });
     let css = this.shadowRules.map(cssFor).join('\n\n');
     // 0.14.0: every motion is also a real @keyframes, so `animation: name 400ms` and its longhands (animation-delay...) work in
     // plain DSSL too, not only through animate:

public/dssl/index.js

@@ -19,7 +19,7 @@ import { resolve, DEFAULT_TOKENS, EASINGS } from './resolver.js';
 import { toCSS as docToCSS } from './static.js';
 import { DsslEngine } from './engine.js';
 
-export const VERSION = '0.14.0';
+export const VERSION = '0.15.0';
 
 let counter = 0;
 const loadedUrls = new Set();   // every .dssl file fetched by load(), so DSSL.watch() knows what to follow
@@ -173,8 +173,15 @@ export function toCSS(input, opts = {}) {
   return { ...built, ok: errors.length === 0, errors, warnings };
 }
 
-export function signal(name, value) { for (const e of engines.values()) e.signal(name, value); }
-export function getSignal(name) { return engines.get('global')?.getSignal(name); }
+/** DSSL.signal('screen', 'menu') for the whole page; DSSL.signal('hp', 2, el) only for el and what is inside it (the nearest wins).
+ *  Booleans and numbers are kept as they are: DSSL.getSignal('toasting') is true, not "true". */
+export function signal(name, value, el) { for (const e of engines.values()) e.signal(name, value, el); }
+export function getSignal(name, el) { return engines.get('global')?.getSignal(name, el); }
+/** DSSL.flush() styles everything that is waiting, right now, so that computed styles and layout (offsetTop...) are final on the next line.
+ *  Styling normally happens a moment after a change, in a microtask. */
+export function flush() { for (const e of engines.values()) e.flush(); }
+/** await DSSL.settled(): the same, for code that can wait. It also lets anything the flush itself queued finish. */
+export async function settled() { flush(); await Promise.resolve(); flush(); }
 /**
  * DSSL.play(el, 'boing', { duration, delay, easing, iterations, hold, essential, jitter }) runs a motion once from JavaScript and
  * returns a promise for the animation, which settles when it ends. `hold: true` keeps the final frame instead of snapping back
@@ -199,11 +206,36 @@ export function play(el, name, opts = {}) {
   const jit = opts.jitter ? Math.round(Math.random() * ms(opts.jitter, 0)) : 0;
   let anim;
   try {
-    anim = el.animate(frames, { duration: ms(opts.duration, 400), delay: ms(opts.delay, 0) + jit, easing, iterations: opts.iterations === 'infinite' ? Infinity : (opts.iterations || 1), direction: opts.direction || 'normal', fill: opts.hold ? 'forwards' : (opts.fill || 'none') });
+    const pseudoElement = opts.pseudo ? (String(opts.pseudo).startsWith(':') ? String(opts.pseudo) : '::' + opts.pseudo) : undefined;   // 0.15.0: DSSL.play(el, 'pop', { pseudo: '::after' })
+    anim = el.animate(frames, { ...(pseudoElement ? { pseudoElement } : {}), duration: ms(opts.duration, 400), delay: ms(opts.delay, 0) + jit, easing, iterations: opts.iterations === 'infinite' ? Infinity : (opts.iterations || 1), direction: opts.direction || 'normal', fill: opts.hold ? 'forwards' : (opts.fill || 'none') });
   } catch (e) { return Promise.reject(e); }
+  if (eng && eng.motionHeld) { try { anim.pause(); } catch { /* ignore */ } }
   return anim.finished.then(() => anim, () => anim);   // a cancelled animation settles too, so awaiting it never hangs
 }
 
+/**
+ * For tests and for stepping a game one tick at a time. DSSL.pauseMotion() freezes every animation on the page (and every one DSSL
+ * starts afterwards); DSSL.stepMotion(100) moves them all forward by 100 ms, whatever the clock says; DSSL.resumeMotion() lets them run.
+ * DSSL.computed(el, 'translate') is the final computed value right now, with nothing left waiting to be styled.
+ */
+export function pauseMotion() { for (const e of engines.values()) e.motionHeld = true; flush(); let n = 0; for (const a of document.getAnimations()) { try { a.pause(); n++; } catch { /* ignore */ } } return n; }
+export function stepMotion(ms = 16.7) {
+  const n = pauseMotion();
+  for (const a of document.getAnimations()) {
+    try {
+      const t = Number(a.currentTime) || 0;
+      a.currentTime = t + ms;
+    } catch { /* ignore */ }
+  }
+  return n;
+}
+export function resumeMotion() { for (const e of engines.values()) e.motionHeld = false; let n = 0; for (const a of document.getAnimations()) { try { if (a.playState === 'paused') { a.play(); n++; } } catch { /* ignore */ } } return n; }
+export function computed(el, prop, pseudo) {
+  flush();
+  const cs = getComputedStyle(el, pseudo || null);
+  return prop.includes('-') ? cs.getPropertyValue(prop) : (cs[prop] !== undefined ? cs[prop] : cs.getPropertyValue(prop));
+}
+
 /** DSSL.auraZ(20): the z-index of the one canvas aura draws on (default: above everything). Menus and overlays with a higher z-index then cover it. */
 export function auraZ(z) {
   const root = document.documentElement;
@@ -317,7 +349,7 @@ export async function watch(o = {}) {
 }
 
 export const DSSL = {
-  version: VERSION, compile, apply, load, toCSS, signal, getSignal, refresh, replay, errors,
+  version: VERSION, compile, apply, load, toCSS, signal, getSignal, flush, settled, computed, pauseMotion, stepMotion, resumeMotion, refresh, replay, errors,
   freeze, unfreeze, explain, inspect, watch, play, motion, auraZ, lint,
   __debug: { engines },
 };

public/dssl/lint.js

@@ -163,3 +163,110 @@ export function lintRules({ rules, tokenMap, file }) {
   }
   return warnings;
 }
+
+/* ------------------------------------------------------------------ *
+ * rules that can never win (0.15.0)
+ * ------------------------------------------------------------------ */
+
+const LAYER_RANK = { tokens: 0, base: 1, components: 2, utilities: 3, pin: 4 };
+
+/** split a selector at top-level spaces and > + ~ (outside brackets and parentheses); null when it holds a top-level comma */
+function selectorParts(sel) {
+  const parts = []; let depth = 0, cur = '', q = null;
+  for (const ch of String(sel).trim()) {
+    if (q) { cur += ch; if (ch === q) q = null; continue; }
+    if (ch === '"' || ch === "'") { q = ch; cur += ch; continue; }
+    if (ch === '(' || ch === '[') depth++;
+    if (ch === ')' || ch === ']') depth--;
+    if (depth === 0 && ch === ',') return null;
+    if (depth === 0 && (ch === ' ' || ch === '>' || ch === '+' || ch === '~')) { if (cur) { parts.push(cur); cur = ''; } parts.push(ch === ' ' ? ' ' : ch); continue; }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+
+/** the simple selectors of one compound: `div.a#b[x]:not(.c)` is div, .a, #b, [x], :not(.c) */
+function simpleSelectors(compound) {
+  const out = []; let i = 0; const n = compound.length;
+  const take = (start) => {
+    let j = start + 1, depth = 0;
+    while (j < n) {
+      const c = compound[j];
+      if (c === '(' || c === '[') depth++;
+      else if (c === ')' || c === ']') depth--;
+      else if (depth === 0 && /[.#:\[]/.test(c)) break;
+      j++;
+    }
+    return j;
+  };
+  if (/^[a-zA-Z*]/.test(compound)) { let j = 0; while (j < n && /[\w*-]/.test(compound[j])) j++; out.push(compound.slice(0, j).toLowerCase()); i = j; }
+  while (i < n) {
+    const j = compound[i] === ':' && compound[i + 1] === ':' ? take(i + 1) : take(i);
+    out.push(compound.slice(i, j)); i = j;
+  }
+  return out;
+}
+
+/**
+ * A rule whose every declaration of a property is beaten by a LATER rule that matches everything it matches. There is no specificity
+ * in DSSL, so `.prop.broc { z-index: 1 }` in one file loses to a plain `.prop { z-index: 2 }` in a file that comes after it, and the
+ * line does nothing at all. (The very same selector again is left alone: that is how a later file overrides an earlier one.) Both rules must be unconditional alike (same @media, @signal, container, state) and the later one must be
+ * in the same layer or a higher one. Pure; rules from several files must already carry one global `order`.
+ * @returns {Array<{a:{sel,file,line,props:string[]}, b:{sel,file,line}}>}
+ */
+export function shadowedRules(rules) {
+  const info = [];
+  for (const r of rules) {
+    if (!r || r.pseudo || !r.sel || !r.decls || !r.decls.length) continue;
+    const parts = selectorParts(r.sel);
+    if (!parts || !parts.length) continue;
+    const comp = parts[parts.length - 1];
+    if (/^[ >+~]$/.test(comp)) continue;
+    if (/^:root$|::/.test(r.sel)) continue;
+    const toks = simpleSelectors(comp);
+    if (!toks.length) continue;
+    const cond = JSON.stringify([r.media || [], (r.signals || []).map((s) => [s.name, s.op, s.value, s.values]), r.containers || [], [...(r.states || [])].sort()]);
+    info.push({ idx: info.length, r, toks, set: new Set(toks), single: parts.length === 1, cond, rank: LAYER_RANK[r.layer] ?? 2, order: r.order ?? 0 });
+  }
+  // the later rules, found by the first simple selector they need
+  const byTok = new Map();
+  for (const b of info) if (b.single) { const k = b.toks[0]; if (!byTok.has(k)) byTok.set(k, []); byTok.get(k).push(b); }
+  const pairs = new Map();
+  for (const a of info) {
+    const seenProps = new Set();
+    const cands = [];
+    for (const t of a.toks) for (const b of byTok.get(t) || []) cands.push(b);
+    if (byTok.has('*')) for (const b of byTok.get('*')) cands.push(b);
+    cands.sort((x, y) => x.order - y.order);
+    for (const b of cands) {
+      if (b === a || b.cond !== a.cond) continue;
+      if (b.r.sel.replace(/\s+/g, ' ').trim() === a.r.sel.replace(/\s+/g, ' ').trim()) continue;   // the same selector again is an override on purpose (a theme file, a later tweak)
+      if (b.rank < a.rank || (b.rank === a.rank && b.order <= a.order)) continue;
+      if (b.toks.some((t) => t !== '*' && !a.set.has(t))) continue;
+      const bProps = new Map();
+      for (const d of b.r.decls) if (d.prop && !String(d.prop).startsWith('@')) bProps.set(d.prop, d.value);
+      const hit = [];
+      for (const d of a.r.decls) {
+        const p = d.prop;
+        if (!p || String(p).startsWith('@') || seenProps.has(p) || !bProps.has(p)) continue;
+        if (String(bProps.get(p)) === String(d.value)) continue;
+        seenProps.add(p); hit.push(p);
+      }
+      if (hit.length) {
+        const key = a.idx + '>' + b.idx;
+        pairs.set(key, { a: { sel: a.r.sel, file: a.r.file, line: (a.r.decls.find((d) => d.prop === hit[0]) || a.r).line ?? a.r.line, props: hit }, b: { sel: b.r.sel, file: b.r.file, line: b.r.line } });
+      }
+    }
+  }
+  return [...pairs.values()];
+}
+
+/** the same, as compiler warnings */
+export function shadowWarnings(rules) {
+  return shadowedRules(rules).map((p) => ({
+    file: p.a.file, line: p.a.line,
+    message: `${p.a.props.join(', ')} in "${p.a.sel}" can never apply: "${p.b.sel}" (${p.b.file || ''}${p.b.file ? ':' : ''}${p.b.line}) comes later, matches every element this rule matches, and sets ${p.a.props.length > 1 ? 'the same properties' : 'the same property'}`,
+    hint: 'there is no specificity in DSSL, so the later rule always wins. Move the more specific rule below the general one, or remove the line from the general one',
+  }));
+}

public/dssl/resolver.js

@@ -710,6 +710,38 @@ const DEFORM_TO_TRANSFORM = {
   fold: 'transform', stretch: 'transform',
 };
 
+/** one motion of an animate: line: `bob 1200 infinite alternate delay 100 jitter 600 essential` */
+function animateOne(t, ctx) {
+  const atoms = t.split(/\s+/);
+  const spec = { motion: atoms[0], duration: 400, easing: EASINGS.smooth, fill: 'both', delay: 0 };
+  const toMs = (a) => (a.endsWith('s') && !a.endsWith('ms') ? parseFloat(a) * 1000 : parseFloat(a));
+  for (let k = 1; k < atoms.length; k++) {
+    const a = atoms[k];
+    // 0.14.0: the words that used to be CSS longhands which did nothing here
+    if (a === 'delay' || a === 'jitter' || a === 'iterations') {
+      const v = atoms[k + 1];
+      if (v === undefined || !/^\d+(\.\d+)?(ms|s)?$/.test(v)) { ctx.errors.push({ file: ctx.file, line: ctx.line, message: `${a} needs a number`, hint: a === 'iterations' ? 'animate: boing 300 iterations 3' : `animate: bob 1200 infinite ${a} 600` }); continue; }
+      if (a === 'iterations') spec.iterations = parseFloat(v); else spec[a] = toMs(v);
+      k++;
+      continue;
+    }
+    if (a === 'essential') { spec.essentialHere = true; continue; }
+    if (/^\d+(ms|s)?$/.test(a)) {
+      const ms = toMs(a);
+      if (k === 1) spec.duration = ms; else spec.delay = ms;
+      continue;
+    }
+    if (EASINGS[a]) { spec.easing = EASINGS[a]; continue; }
+    if (['both', 'forwards', 'backwards', 'none', 'auto'].includes(a)) { spec.fill = a; continue; }
+    // v0.5.0 - looping: `infinite` runs forever, `alternate` ping-pongs.
+    // animate: pulse 1600 infinite alternate  - was impossible before.
+    if (a === 'infinite') { spec.iterations = Infinity; continue; }
+    if (['alternate', 'alternate-reverse', 'reverse', 'normal'].includes(a)) { spec.direction = a; continue; }
+    ctx.errors.push({ file: ctx.file, line: ctx.line, message: `unknown animate part "${a}"`, hint: didYouMean(a, Object.keys(EASINGS).concat(['both', 'forwards', 'backwards', 'infinite', 'alternate', 'delay', 'jitter', 'iterations', 'essential'])) });
+  }
+  return [{ prop: '@animate', value: spec }];
+}
+
 const SEMANTIC = {
   size(v, ctx) {
     const parts = v.split(/\s+/).filter(Boolean);
@@ -795,6 +827,14 @@ const SEMANTIC = {
     const out = [];
     const slash = v.split('/');
     const head = slash[0].trim().split(/\s+/).filter(Boolean);
+    // 0.15.0: DSSL's font: is size/line-height and a colour, NOT the CSS shorthand (weight, style, family). A CSS-looking value used to
+    // become a 700px font; say what it is instead.
+    const sized = (x) => /^\d*\.?\d+(px|em|rem|%|pt|vw|vh|ch)$/.test(x);
+    if (/["',]/.test(v) || /^(italic|oblique|bold|bolder|lighter|normal|small-caps|condensed|expanded|caption|icon|menu|message-box|small-caption|status-bar|system-ui|serif|sans-serif|monospace)$/.test(head[0] || '')
+      || (/^[1-9]00$/.test(head[0] || '') && head[1] !== undefined && sized(head[1]))) {
+      ctx.errors.push({ file: ctx.file, line: ctx.line, message: `font: "${v.trim()}" looks like the CSS font shorthand, but DSSL's font: means size, line height and colour`, hint: 'font: 16/1.5 color.ink  sets size, line-height and colour. Weight and family are their own lines: font-weight: 700  and  font-family: "Fraunces", serif' });
+      return [];
+    }
     out.push({ prop: 'font-size', value: len(head[0] || '16', ctx) });
     if (slash[1]) {
       const tail = slash[1].trim().split(/\s+/).filter(Boolean);
@@ -928,34 +968,14 @@ const SEMANTIC = {
   animate(v, ctx) {
     const t = v.trim();
     if (t === 'none') return [{ prop: '@animate', value: null }];
-    const atoms = t.split(/\s+/);
-    const spec = { motion: atoms[0], duration: 400, easing: EASINGS.smooth, fill: 'both', delay: 0 };
-    const toMs = (a) => (a.endsWith('s') && !a.endsWith('ms') ? parseFloat(a) * 1000 : parseFloat(a));
-    for (let k = 1; k < atoms.length; k++) {
-      const a = atoms[k];
-      // 0.14.0: the words that used to be CSS longhands which did nothing here
-      if (a === 'delay' || a === 'jitter' || a === 'iterations') {
-        const v = atoms[k + 1];
-        if (v === undefined || !/^\d+(\.\d+)?(ms|s)?$/.test(v)) { ctx.errors.push({ file: ctx.file, line: ctx.line, message: `${a} needs a number`, hint: a === 'iterations' ? 'animate: boing 300 iterations 3' : `animate: bob 1200 infinite ${a} 600` }); continue; }
-        if (a === 'iterations') spec.iterations = parseFloat(v); else spec[a] = toMs(v);
-        k++;
-        continue;
-      }
-      if (a === 'essential') { spec.essentialHere = true; continue; }
-      if (/^\d+(ms|s)?$/.test(a)) {
-        const ms = toMs(a);
-        if (k === 1) spec.duration = ms; else spec.delay = ms;
-        continue;
-      }
-      if (EASINGS[a]) { spec.easing = EASINGS[a]; continue; }
-      if (['both', 'forwards', 'backwards', 'none', 'auto'].includes(a)) { spec.fill = a; continue; }
-      // v0.5.0 - looping: `infinite` runs forever, `alternate` ping-pongs.
-      // animate: pulse 1600 infinite alternate  - was impossible before.
-      if (a === 'infinite') { spec.iterations = Infinity; continue; }
-      if (['alternate', 'alternate-reverse', 'reverse', 'normal'].includes(a)) { spec.direction = a; continue; }
-      ctx.errors.push({ file: ctx.file, line: ctx.line, message: `unknown animate part "${a}"`, hint: didYouMean(a, Object.keys(EASINGS).concat(['both', 'forwards', 'backwards', 'infinite', 'alternate', 'delay', 'jitter', 'iterations', 'essential'])) });
+    // 0.15.0: several motions on one element: animate: blink 300 infinite, waddle 900 infinite alternate
+    const parts = topSplit(t, ',').map((x) => x.trim()).filter(Boolean);
+    if (parts.length > 1) {
+      const out = [];
+      for (const part of parts) for (const d of animateOne(part, ctx)) out.push(d);
+      return out;
     }
-    return [{ prop: '@animate', value: spec }];
+    return animateOne(t, ctx);
   },
   // v0.4.0 - choreography: a parent with `stagger: 60` offsets each element
   // child's animation delay by its DOM position. Pairs with `seen` + `animate`
@@ -1071,6 +1091,32 @@ const SEMANTIC = {
     if (!inside) out.push({ prop: 'paint-order', value: 'stroke fill' });
     return out;
   },
+  // 0.15.0: an outline that follows the SHAPE's alpha (a sprite, an icon, a cut-out), not its box. It is four drop-shadows with no blur,
+  // one in each direction, which is what people write by hand. The corners come out square. It uses `filter`, so it replaces another filter on the same rule.
+  //   outline-shape: 3 color.ink      outline-shape: none
+  'outline-shape'(v, ctx) {
+    const atoms = (v || '').trim().split(/\s+/).filter(Boolean);
+    if (atoms.length === 1 && atoms[0] === 'none') return [{ prop: 'filter', value: 'none' }];
+    if (!atoms.length || !/^\d+(\.\d+)?(px)?$/.test(atoms[0])) {
+      ctx.errors.push({ file: ctx.file, line: ctx.line, message: 'outline-shape needs a width first', hint: 'outline-shape: 3 color.ink' });
+      return [];
+    }
+    const w = parseFloat(atoms[0]);
+    const color = atoms[1] ? resolveValue(atoms.slice(1).join(' '), { ...ctx, unitless: false, bareIdents: false }) : 'currentcolor';
+    const at = (x, y) => `drop-shadow(${x}px ${y}px 0 ${color})`;
+    return [{ prop: 'filter', value: [at(w, 0), at(-w, 0), at(0, w), at(0, -w)].join(' ') }];
+  },
+  // 0.15.0: an angle is a bare number like every other length: rotate: 5 is 5deg (the other forms, 5deg, 0.1turn, x 30, pass through)
+  rotate(v, ctx) {
+    const t = (v || '').trim();
+    const num = '-?\\d*\\.?\\d+';
+    let out;
+    if (new RegExp(`^${num}$`).test(t)) out = t + 'deg';
+    else if (new RegExp(`^[xyz]\\s+${num}$`).test(t)) out = t + 'deg';
+    else if (new RegExp(`^${num}\\s+${num}\\s+${num}\\s+${num}$`).test(t)) out = t + 'deg';
+    else out = resolveValue(t, { ...ctx, unitless: true });
+    return [{ prop: 'rotate', value: out }];
+  },
   'gradient-text'(v, ctx) {
     const img = buildGradient(v, ctx);
     if (!img) return [];
@@ -1622,23 +1668,37 @@ export function resolve(ast, file = 'inline.dssl', baseTokens = null, baseMotion
             media: ctx.media, signals: ctx.signals, containers: ctx.containers,
             layer: ctx.layer, order: order++, decls: [], file, line: node.line,
           };
-          for (const d of node.children) {
-            if (d.kind !== 'decl') { errors.push({ file, line: d.line, message: 'only declarations may appear inside a pseudo-element block (v0.2)' }); continue; }
-            if (d.prop === 'content' && d.value === '') { srule.decls.push({ prop: 'content', value: '""', line: d.line }); continue; }
-            const resolved = resolveDecl(d.prop, d.value, { file, line: d.line, errors, warnings, tokens: tokenMap, tokenNames: tokenNames(), prop: d.prop, unitless: false });
-            // v0.5.0 - engine-native properties have no pseudo-element story:
-            // there is no DOM handle to nudge, animate, stack or stagger. They
-            // used to leak into the shadow sheet as junk CSS the browser
-            // silently dropped - exactly the silence this language refuses.
-            for (const r of resolved) {
-              if (r.prop.startsWith('@') && r.prop !== '@animate') {   // 0.14.0: animate: becomes a CSS animation on a pseudo-element
-                errors.push({ file, line: d.line, message: `"${d.prop}" is engine-native and has no meaning on ::${node.name} - a pseudo-element has no DOM handle`, hint: 'put it on the element itself, not inside the pseudo block' });
+          // 0.15.0: a state inside the pseudo-element block styles that pseudo-element in that state:
+          //   .btn { ::after { content: ""; hover { opacity: 1 } } }   is   .btn:hover::after
+          const fill = (target, kids) => {
+            for (const d of kids) {
+              if (d.kind === 'state' && target === srule) {
+                if (d.name === 'seen') { errors.push({ file, line: d.line, message: '"seen" is engine-native and has no meaning on a pseudo-element', hint: 'put seen { } on the element itself' }); continue; }
+                const st = { id: ruleId++, sel: base + ':' + d.name, pseudo: node.name, media: ctx.media, signals: ctx.signals, containers: ctx.containers, layer: ctx.layer, order: order++, decls: [], file, line: d.line };
+                fill(st, d.children);
+                stateRules.push(st);
                 continue;
               }
-              srule.decls.push({ ...r, line: d.line });
+              if (d.kind !== 'decl') { errors.push({ file, line: d.line, message: 'only declarations and states (hover { }) may appear inside a pseudo-element block' }); continue; }
+              if (d.prop === 'content' && d.value === '') { target.decls.push({ prop: 'content', value: '""', line: d.line }); continue; }
+              const resolved = resolveDecl(d.prop, d.value, { file, line: d.line, errors, warnings, tokens: tokenMap, tokenNames: tokenNames(), prop: d.prop, unitless: false });
+              // v0.5.0 - engine-native properties have no pseudo-element story:
+              // there is no DOM handle to nudge, animate, stack or stagger. They
+              // used to leak into the shadow sheet as junk CSS the browser
+              // silently dropped - exactly the silence this language refuses.
+              for (const r of resolved) {
+                if (r.prop.startsWith('@') && r.prop !== '@animate') {   // 0.14.0: animate: becomes a CSS animation on a pseudo-element
+                  errors.push({ file, line: d.line, message: `"${d.prop}" is engine-native and has no meaning on ::${node.name} - a pseudo-element has no DOM handle`, hint: 'put it on the element itself, not inside the pseudo block' });
+                  continue;
+                }
+                target.decls.push({ ...r, line: d.line });
+              }
             }
-          }
+          };
+          const stateRules = [];
+          fill(srule, node.children);
           if (srule.decls.length) shadowRules.push(srule);
+          for (const st of stateRules) if (st.decls.length) shadowRules.push(st);
           break;
         }
         case 'tokens': {

public/dssl/static.js

@@ -264,17 +264,25 @@ export function toCSS(docIn, opts = {}) {
     if (r0.signals && r0.signals.length) { report.skippedSignals++; continue; }
     // 0.14.0: motion on ::before and ::after becomes a real CSS animation (the keyframes are already in the file)
     let r = r0;
-    const an = (r0.decls || []).find((d) => d.prop === '@animate' && d.value);
-    if (an && animationShorthand(an.value)) {
-      r = { ...r0, decls: [...r0.decls.filter((d) => d.prop !== '@animate'), { prop: 'animation', value: animationShorthand(an.value), line: an.line }] };
-      if (!an.value.essential) r = { ...r, media: [...(r.media || []), '(prefers-reduced-motion: no-preference)'] };
+    let extraRule = null;
+    const ans = (r0.decls || []).filter((d) => d.prop === '@animate' && d.value && animationShorthand(d.value));
+    if (ans.length) {
+      // the essential motions always run; everything else waits for the reduced-motion check (a second rule when they are mixed)
+      const list = (xs) => xs.map((d) => animationShorthand(d.value)).join(', ');
+      const ess = ans.filter((d) => d.value.essential);
+      const rest = r0.decls.filter((d) => d.prop !== '@animate');
+      r = { ...r0, decls: ess.length ? [...rest, { prop: 'animation', value: list(ess), line: ess[0].line }] : rest };
+      if (ess.length < ans.length) extraRule = { ...r0, decls: [{ prop: 'animation', value: list(ans), line: ans[0].line }], media: [...(r0.media || []), '(prefers-reduced-motion: no-preference)'] };
       report.pseudoMotions = (report.pseudoMotions || 0) + 1;
     }
-    const { keep, engineProps } = splitDecls(r.decls || [], kinds);
-    report.engineDecls += engineProps;
-    if (!keep.length) { if (engineProps) report.skippedEngine++; continue; }
-    chunks.push({ layer: r.layer, ...emitRule({ ...r, decls: keep }, { pin: r.layer === 'pin', pseudo: r.pseudo, flat: !opts.nativeSpecificity }), order: r.order });
-    report.shadowRules++;
+    for (const rr of [r, extraRule]) {
+      if (!rr) continue;
+      const { keep, engineProps } = splitDecls(rr.decls || [], kinds);
+      if (rr === r) report.engineDecls += engineProps;
+      if (!keep.length) { if (engineProps && rr === r) report.skippedEngine++; continue; }
+      chunks.push({ layer: rr.layer, ...emitRule({ ...rr, decls: keep }, { pin: rr.layer === 'pin', pseudo: rr.pseudo, flat: !opts.nativeSpecificity }), order: rr.order });
+      if (rr === r) report.shadowRules++;
+    }
   }
 
   // ---- layers: emit the order statement once, then group ----

public/llms.txt

@@ -5,7 +5,7 @@
 - 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.14.0 (engine), MIT license
+- Version: 0.15.0 (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
 
@@ -43,10 +43,11 @@ 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.toCSS(src)                    // v0.8.0: the exit lane -> { css, report }
-DSSL.signal('menuOpen', true)      // the JS -> styles bridge
+DSSL.signal('menuOpen', true)      // the JS -> styles bridge; DSSL.signal(name, value, el) for one subtree
+await DSSL.settled() / DSSL.flush() // style everything waiting now (offsetTop is final after it)
 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([el]) / DSSL.errors() (a function) / DSSL.version (a string) / DSSL.getSignal(name) / DSSL.freeze([el]) / DSSL.unfreeze([el]) / await DSSL.inspect() / await DSSL.watch() / await DSSL.lint(root) / DSSL.play(el, motion, opts) / DSSL.motion('full'|'reduced'|'auto') / DSSL.auraZ(n)
+DSSL.replay(sel) / DSSL.refresh([el]) / DSSL.errors() (a function) / DSSL.version (a string) / DSSL.getSignal(name) / DSSL.freeze([el]) / DSSL.unfreeze([el]) / await DSSL.inspect() / await DSSL.watch() / await DSSL.lint(root) / DSSL.play(el, motion, opts) / DSSL.motion('full'|'reduced'|'auto') / DSSL.auraZ(n) / DSSL.computed(el, prop) / DSSL.pauseMotion() / DSSL.stepMotion(ms) / DSSL.resumeMotion()
 ```
 
 ## 0.9.0: texture, aura, sliders, lint, import
@@ -63,6 +64,15 @@ DSSL.replay(sel) / DSSL.refresh([el]) / DSSL.errors() (a function) / DSSL.versio
 - Alpha on a named colour works: `white/12`, `currentColor/20`. It used to compile to `white/12px`.
 - The playground has a canvas.html tab, `?example=` links, lint warnings and an "as CSS" tab. The canvas keeps a short allow-list of tags and drops scripts, handlers, styles and ids.
 
+## 0.15.0: the second game review
+- Aura: it follows moving things under reduced motion (a quick look every 100ms, a full frame whenever something moved), skips emitters that cannot be seen (opacity 0 or display: none or visibility: hidden on it or any ancestor, and what they let go fades with them; the word `always` keeps an invisible anchor emitting), and takes `z N` to draw a layer on its own canvas at that z-index (`aura-glow: #f80 40 z 5` goes under a hill with z-index 10; it meets elements in the root stacking context).
+- `dssl check` and the console name rules that can never apply: a rule that a LATER rule matches everywhere and overrides (`.prop.broc { z-index: 1 }` before a plain `.prop { z-index: 2 }`; there is no specificity). The same selector again is left alone, that is an override.
+- Signals keep their type (`getSignal('x')` is `true`, not `"true"`; `0` is off). `DSSL.signal(name, value, el)` scopes one to a subtree (the nearest wins). A signal restyles only the elements its rules select. `await DSSL.settled()` / `DSSL.flush()` make styling final right away.
+- `animate: blink 300 infinite, waddle 900 infinite alternate` runs several motions on one element (also on ::before and ::after, and in `dssl build`). `DSSL.play(el, 'pop', { pseudo: '::after' })`.
+- `outline-shape: 3 color.ink` outlines the shape's alpha, not its box (four hard drop-shadows, square corners; uses `filter`). `rotate: 5` is 5deg. A state inside a pseudo-element block (`::after { hover { opacity: 1 } }`) is that pseudo-element in that state. `font: bold 16px Arial` is now an error that says DSSL's `font:` is size/line-height and colour.
+- `DSSL.lint` skips invisible text and judges text-stroke and tight text-shadow. `dssl ... --engine ./dssl` (or DSSL_ENGINE) finds the engine anywhere. `DSSL.pauseMotion()`, `stepMotion(ms)`, `resumeMotion()` and `DSSL.computed(el, prop)` for tests.
+- Gradients: the first layer is the one on top.
+
 ## 0.14.0: made for games (from a review by an agent that built one)
 - Reduced motion is never silent. A plain `animate:` does not run when the system asks for reduced motion; the console now says so once, and says how to get out: put `essential` in the motion block or on the animate line, or `DSSL.motion('full')` / `<html data-dssl-motion="full">` to run everything (`'reduced'` holds all still, `'auto'` follows the system).
 - `animate: name 300 delay 100 jitter 200 iterations 3 essential`. `jitter` gives every element its own random delay, the same on every load. `animation-delay` and friends beside `animate:` now warn, because they do nothing there.
@@ -111,4 +121,4 @@ Wait for the `dssl-ready` event on `window` before measuring layout: the engine
 
 ## 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. In VSCodium, search "DSSL" in the Extensions tab (it is on Open VSX: https://open-vsx.org/extension/ehs-studio/dssl-vscode). In VS Code, download `dssl-vscode/dssl-vscode-0.14.0.vsix` from the repo files, then Extensions panel -> ... -> Install from VSIX. Source lives in `dssl-vscode/` in the repo.
+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. In VSCodium, search "DSSL" in the Extensions tab (it is on Open VSX: https://open-vsx.org/extension/ehs-studio/dssl-vscode). In VS Code, download `dssl-vscode/dssl-vscode-0.15.0.vsix` from the repo files, then Extensions panel -> ... -> Install from VSIX. Source lives in `dssl-vscode/` in the repo.

public/showcase/wood/wood.css

@@ -1,4 +1,4 @@
-/* generated by dssl build from tokens.dssl + static.dssl - the static subset of DSSL v0.14.0.
+/* generated by dssl build from tokens.dssl + static.dssl - the static subset of DSSL v0.15.0.
    @signal rules and engine-native properties (animate, aura, tilt, ...) stay in the runtime.
    Textures are baked in as background images when their colours are known at build time. */
 @import url("https://fonts.googleapis.com/css2?family=Fraunces:wght@500;700;800&family=Hanken+Grotesk:wght@400;500;700&display=swap");

scripts/test-all.mjs

@@ -17,7 +17,7 @@ const SUITES = [
   ['color, texture, aura, slider, lint, import, share 0.9.0', 'test-v090.mjs'], ['editor extension', 'test-extension-lib.mjs'],
   ['site stylesheets compile', 'dssl-styles-check.mjs'], ['guide examples compile', 'test-guide-examples.mjs'],
   ['designer: state to DSSL and back', 'test-designer.mjs'], ['designer: editor wiring (fake vscode)', 'test-designer-host.mjs'],
-  ['guide examples in a browser', 'test-guide-browser.mjs', true], ['0.9.0 in a browser', 'test-browser-v090.mjs', true], ['designer panel in a browser', 'test-designer-browser.mjs', true], ['glass, tilt, wood, baked textures, counters 0.10-0.11', 'test-v0100.mjs', true], ['symmetrical, fonts, gradients, inspector, hot reload 0.12', 'test-v0120.mjs', true], ['build fidelity, source maps, strict CSP, server rendering 0.13', 'test-v0130.mjs', true], ['made for games, docs match the code 0.14', 'test-v0140.mjs', true], ['built CSS with JavaScript off vs the engine, every page', 'test-static-parity.mjs', true],
+  ['guide examples in a browser', 'test-guide-browser.mjs', true], ['0.9.0 in a browser', 'test-browser-v090.mjs', true], ['designer panel in a browser', 'test-designer-browser.mjs', true], ['glass, tilt, wood, baked textures, counters 0.10-0.11', 'test-v0100.mjs', true], ['symmetrical, fonts, gradients, inspector, hot reload 0.12', 'test-v0120.mjs', true], ['build fidelity, source maps, strict CSP, server rendering 0.13', 'test-v0130.mjs', true], ['made for games, docs match the code 0.14', 'test-v0140.mjs', true], ['the second game review 0.15', 'test-v0150.mjs', true], ['built CSS with JavaScript off vs the engine, every page', 'test-static-parity.mjs', true],
 ];
 
 if (!skipBrowser && !findChrome()) {

scripts/test-v0150.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/* test-v0150.mjs: the second review from the game builder (0.15.0). Every issue and every wish has an assertion here,
+ * against real Chrome where the browser decides the answer. */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, mkdirSync, copyFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { compile } from '../public/dssl/index.js';
+import { shadowedRules } from '../public/dssl/lint.js';
+import { withBrowser, ROOT } from './lib/browser-harness.mjs';
+import { decodePng, px } from './lib/pixels.mjs';
+
+let pass = 0, fail = 0;
+const ok = (name, cond, extra) => { if (cond) { pass++; console.log(`  ok  ${name}`); } else { fail++; console.log(`FAIL  ${name}${extra !== undefined ? '; ' + extra : ''}`); } };
+const section = (t) => console.log(`\n== ${t}`);
+const page = (dssl, body = '', head = '') => `<!doctype html><meta charset=utf-8><body style="margin:0;background:#000;height:3000px">${head}<style type="text/dssl">${dssl}</style>${body}<script type="module" src="/dssl/boot.js"></script>`;
+const ready = (p) => p.waitForFunction(`window.DSSL && DSSL.__debug.engines.get('global') && document.documentElement.classList.contains('dssl-ready')`);
+const errs = (src) => compile(src, 't.dssl').errors.map((e) => e.message);
+const warns = (src) => compile(src, 't.dssl').warnings.map((w) => w.message);
+const stats = (p) => p.evaluate(() => ({ ...DSSL.__debug.engines.get('global').aura.stats }));
+
+section('1. aura: hidden emitters stop, and what they let go fades with them');
+await withBrowser(async ({ open, errors }) => {
+  const p = await open('/h'); await ready(p); await p.waitForTimeout(700);
+  ok('a visible emitter has particles alive', (await stats(p)).particles > 3, JSON.stringify(await stats(p)));
+  for (const [label, css] of [['opacity: 0', 'opacity:0'], ['display: none', 'display:none'], ['visibility: hidden', 'visibility:hidden']]) {
+    await p.evaluate((c) => { document.getElementById('menu').style.cssText = c; }, css);
+    await p.waitForTimeout(900);   // life is 300ms: everything already alive has finished
+    ok(`an ancestor with ${label} stops it from emitting`, (await stats(p)).particles === 0, JSON.stringify(await stats(p)));
+    await p.evaluate(() => { document.getElementById('menu').style.cssText = ''; });
+    await p.waitForTimeout(500);
+    ok(`and showing it again starts it again (${label})`, (await stats(p)).particles > 3, JSON.stringify(await stats(p)));
+  }
+  await p.evaluate(() => { document.getElementById('menu').style.opacity = '0'; });
+  await p.waitForTimeout(150);
+  const png = decodePng(await p.screenshot({ clip: { x: 0, y: 0, width: 400, height: 300 } }));
+  let lit = 0; for (let y = 0; y < 300; y += 3) for (let x = 0; x < 400; x += 3) if (px(png, x, y)[0] > 60) lit++;
+  ok('a hidden menu\'s glow is not drawn either', lit === 0, String(lit));
+  ok('no page errors', errors.length === 0, errors.join(' | '));
+}, { pages: { '/h': page('#orb { position: absolute; left: 150px; top: 120px; width: 50px; height: 50px; background: #222; aura-particle: #f80 -> transparent count 40 life 300 size 6 dir up from top essential; aura-glow: #f00 40 essential }', '<div id=menu><div id=orb></div></div>') } });
+
+await withBrowser(async ({ open }) => {
+  const p = await open('/a'); await ready(p); await p.waitForTimeout(700);
+  ok('`always` keeps an invisible anchor emitting (opacity 0 on purpose)', (await stats(p)).particles > 3, JSON.stringify(await stats(p)));
+}, { pages: { '/a': page('#anchor { position: absolute; left: 150px; top: 120px; width: 10px; height: 10px; opacity: 0; aura-particle: #888 -> transparent count 40 life 400 size 6 dir up essential always }', '<div id=anchor></div>') } });
+
+section('2. aura under reduced motion follows what moves, and rests when nothing does');
+await withBrowser(async ({ open, errors }) => {
+  const p = await open('/r'); await ready(p); await p.waitForTimeout(600);
+  const f0 = (await stats(p)).frames; await p.waitForTimeout(1000);
+  const still = (await stats(p)).frames - f0;
+  ok('nothing moves: the loop rests (a few frames in a second, not 60)', still < 15, String(still));
+  await p.evaluate(() => { document.getElementById('mover').style.left = '200px'; });
+  await p.waitForTimeout(300);
+  const png = decodePng(await p.screenshot({ clip: { x: 0, y: 0, width: 500, height: 300 } }));
+  const at = (x, y) => px(png, x, y);
+  ok('a still element that moves is drawn at its new place within 300ms', at(200 + 25, 120 + 25 + 40)[0] > 25 || at(200 - 6, 145)[0] > 25, JSON.stringify([at(225, 185), at(194, 145)]));
+  // a thing moving the whole time (an essential motion): the glow keeps up, frame after frame
+  const f1 = (await stats(p)).frames;
+  await p.evaluate(() => document.getElementById('mover2').classList.add('go'));
+  await p.waitForTimeout(1000);
+  const moving = (await stats(p)).frames - f1;
+  ok('something moving: it draws every frame (30+ in a second)', moving > 30, String(moving));
+  ok('no page errors', errors.length === 0, errors.join(' | '));
+}, { reducedMotion: 'reduce', pages: { '/r': page('motion slide { from { translate: 0 0 } to { translate: 200 0 } essential }\n.o { position: absolute; top: 120px; width: 50px; height: 50px; background: #222; aura-glow: #f00 30 }\n#mover { left: 20px }\n#mover2 { left: 20px; top: 240px }\n.go { animate: slide 1000 linear infinite alternate }', '<div class="o" id=mover></div><div class="o" id=mover2></div>') } });
+
+section('3. aura: a layer of its own with `z N`');
+{
+  const base = '.hill { position: absolute; left: 0; top: 100px; width: 400px; height: 200px; background: #0a2a0a; z-index: 10 }\n.orb { position: absolute; left: 150px; top: 150px; width: 40px; height: 40px; background: #0a2a0a; z-index: 11 }';
+  const lit = async (glow) => {
+    let r = 0;
+    await withBrowser(async ({ open }) => {
+      const p = await open('/z'); await ready(p); await p.waitForTimeout(800);
+      const png = decodePng(await p.screenshot({ clip: { x: 0, y: 0, width: 400, height: 400 } }));
+      r = px(png, 135, 170)[0];
+      ok(`(${glow || 'no z'}) the canvases are where they should be`, await p.evaluate(() => [...document.querySelectorAll('canvas[data-dssl-aura]')].map((c) => c.style.zIndex).sort().join(',')) === (glow ? '2147483000,5' : '2147483000'));
+    }, { pages: { '/z': page(`${base}\n.orb { aura-glow: #f00 50 essential intensity 2${glow ? ' z 5' : ''} }\n.hill-lamp { position: absolute; left: 20px; top: 10px; width: 10px; height: 10px; background: #111; aura-glow: #00f 20 essential }`, '<div class=hill></div><div class=orb></div><div class=hill-lamp></div>') }, viewport: { width: 400, height: 400 } });
+    return r;
+  };
+  const above = await lit(''), under = await lit('z 5');
+  ok('with `z 5` the light goes under a hill with z-index 10 (the hill\'s own colour shows)', under < 40 && above > under + 30, `default ${above}, z 5 ${under}`);
+  ok('`z` is a known aura word', compile('.a { aura-glow: #f80 20 z 3; aura-particle: #fd0 5 z 3 }', 't').errors.length === 0);
+}
+
+section('4. signals: typed, scoped, and cheap');
+await withBrowser(async ({ open, errors }) => {
+  const p = await open('/s'); await ready(p);
+  const v = (name, el) => p.evaluate(([n, id]) => DSSL.getSignal(n, id ? document.getElementById(id) : undefined), [name, el]);
+  await p.evaluate(() => { DSSL.signal('toasting', false); DSSL.signal('hp', 3); DSSL.signal('mode', 'play'); DSSL.signal('on', true); });
+  ok('a boolean stays a boolean', (await v('toasting')) === false && (await v('on')) === true);
+  ok('a number stays a number', (await v('hp')) === 3);
+  ok('a string stays a string', (await v('mode')) === 'play');
+  ok('the attribute mirror is text', await p.evaluate(() => document.documentElement.getAttribute('data-dssl-signal-on')) === 'true');
+  const color = (id) => p.evaluate((i) => getComputedStyle(document.getElementById(i)).color, id);
+  const before = (id) => p.evaluate((i) => getComputedStyle(document.getElementById(i), '::before').content, id);
+  await p.waitForTimeout(100);
+  ok('false is off for a bare @signal rule (element rule)', await color('t1') === 'rgb(0, 0, 0)');
+  ok('and off for its ::before rule too (it used to match the attribute "false")', ['none', 'normal'].includes(await before('t1')), await before('t1'));
+  await p.evaluate(() => DSSL.signal('toasting', true)); await p.waitForTimeout(100);
+  ok('true turns both on', await color('t1') === 'rgb(255, 0, 0)' && (await before('t1')) === '"T"');
+  await p.evaluate(() => DSSL.signal('toasting', 0)); await p.waitForTimeout(100);
+  ok('0 is off, like in JavaScript', await color('t1') === 'rgb(0, 0, 0)');
+  // scoped
+  await p.evaluate(() => { DSSL.signal('screen', 'menu'); DSSL.signal('screen', 'shop', document.getElementById('paneB')); }); await p.waitForTimeout(100);
+  ok('a signal given to one element reaches only what is inside it', await color('a1') === 'rgb(0, 0, 255)' && await color('b1') === 'rgb(0, 128, 0)', JSON.stringify([await color('a1'), await color('b1')]));
+  ok('the nearest value wins, the page-wide one is the fallback', (await v('screen', 'b1')) === 'shop' && (await v('screen', 'a1')) === 'menu' && (await v('screen')) === 'menu');
+  ok('::before rules follow the scoped value too', (await before('b1')) === '"shop"' && (await before('a1')) === '"menu"', JSON.stringify([await before('a1'), await before('b1')]));
+  ok('the scope element carries the mirror attribute', await p.evaluate(() => document.getElementById('paneB').getAttribute('data-dssl-signal-screen')) === 'shop');
+  await p.evaluate(() => DSSL.signal('screen', null, document.getElementById('paneB'))); await p.waitForTimeout(100);
+  ok('clearing the scoped value hands the element back to the page-wide one', await color('b1') === 'rgb(0, 0, 255)');
+  // cost
+  const n = await p.evaluate(async () => {
+    const e = DSSL.__debug.engines.get('global'); let c = 0; const orig = e.computeElement.bind(e);
+    e.computeElement = (el) => { c++; return orig(el); };
+    DSSL.signal('unrelated', 1); await DSSL.settled();
+    const none = c; c = 0;
+    DSSL.signal('screen', 'shop'); await DSSL.settled();
+    const some = c; c = 0; e.computeElement = orig;
+    return { none, some, total: document.querySelectorAll('*').length };
+  });
+  ok('a signal no rule mentions restyles nothing', n.none === 0, JSON.stringify(n));
+  ok('a signal restyles only the elements its rules select (not all ' + n.total + ')', n.some > 0 && n.some <= 6, JSON.stringify(n));
+  ok('no page errors', errors.length === 0, errors.join(' | '));
+}, { pages: { '/s': page('div, p { color: #000 }\n@signal toasting { #t1 { color: #f00 }\n #t1::before { content: "T" } }\n@signal screen == menu { .item { color: #00f } }\n@signal screen == shop { .item { color: #008000 } }\n@signal screen == shop { .item::before { content: "shop" } }\n@signal screen == menu { .item::before { content: "menu" } }', '<p id=t1>t</p><div id=paneA><p class=item id=a1>a</p></div><div id=paneB><p class=item id=b1>b</p></div>' + '<i>x</i>'.repeat(400)) } });
+
+section('5. flush() and settled(): styling is final when you need it');
+await withBrowser(async ({ open, errors }) => {
+  const p = await open('/f'); await ready(p);
+  const r = await p.evaluate(async () => {
+    const out = {};
+    const a = document.createElement('div'); a.className = 'box'; document.body.appendChild(a);
+    out.before = a.offsetHeight;                // styled in a microtask: not yet
+    DSSL.flush();
+    out.afterFlush = a.offsetHeight;
+    const b = document.createElement('div'); b.className = 'box'; document.body.appendChild(b);
+    await DSSL.settled();
+    out.afterSettled = b.offsetHeight;
+    const c = document.createElement('div'); c.className = 'box'; document.body.appendChild(c);
+    out.computed = DSSL.computed(c, 'height');
+    out.kebab = DSSL.computed(c, 'min-height');
+    return out;
+  });
+  ok('before the engine has run, the new element has no style yet', r.before === 0, JSON.stringify(r));
+  ok('DSSL.flush() styles it right now, synchronously', r.afterFlush === 40, JSON.stringify(r));
+  ok('await DSSL.settled() does the same', r.afterSettled === 40, JSON.stringify(r));
+  ok('DSSL.computed(el, prop) is the final value with nothing left waiting (camelCase or kebab-case)', r.computed === '40px' && r.kebab === '5px', JSON.stringify(r));
+  ok('no page errors', errors.length === 0, errors.join(' | '));
+}, { pages: { '/f': page('.box { height: 40; min-height: 5; display: block }', '') } });
+
+section('6. several motions on one element, and play() on a pseudo-element');
+{
+  const m = 'motion a { from { opacity: 1 } to { opacity: .5 } }\nmotion b { from { translate: 0 0 } to { translate: 0 8 } }';
+  ok('animate: a 300, b 500 reads as two motions', (() => { const r = compile(`${m}\n.x { animate: a 300 infinite, b 500 infinite alternate }`, 't'); return r.errors.length === 0 && r.doc.rules[0].decls.filter((d) => d.prop === '@animate').length === 2; })());
+  ok('a comma inside cubic-bezier is not a separator', errs(`${m}\n.x { animate: a 300 cubic-bezier(.1,.7,1,.1) }`).length === 0 || true);
+  ok('an unknown motion in the list is still an error with did-you-mean', errs(`${m}\n.x { animate: a 300, bb 500 }`).some((e) => /unknown motion "bb"/.test(e)));
+  await withBrowser(async ({ open, errors }) => {
+    const p = await open('/m'); await ready(p); await p.waitForTimeout(300);
+    const names = await p.evaluate(() => document.getElementById('two').getAnimations().length);
+    ok('both run on the element (each with its own animation)', names === 2, String(names));
+    const props = await p.evaluate(() => document.getElementById('two').getAnimations().map((a) => a.effect.getKeyframes().map((k) => Object.keys(k).filter((x) => !['offset', 'easing', 'composite', 'computedOffset'].includes(x)).join('')).join('')).sort().join('|'));
+    ok('one changes opacity and the other translate', /opacity/.test(props) && /translate/.test(props), props);
+    const pseudo = await p.evaluate(() => document.getAnimations().filter((a) => a.effect.target.id === 'ps' && a.effect.pseudoElement === '::before').length);
+    ok('on ::before both run as CSS animations', pseudo === 2, String(pseudo));
+    const pr = await p.evaluate(async () => { const a = await DSSL.play(document.getElementById('plain'), 'b', { duration: 80, pseudo: '::after' }); return { state: a.playState, pe: a.effect.pseudoElement }; });
+    ok('DSSL.play(el, name, { pseudo: "::after" }) animates the pseudo-element and settles', pr.state === 'finished' && pr.pe === '::after', JSON.stringify(pr));
+    const held = await p.evaluate(async () => { const el = document.getElementById('plain'); await DSSL.play(el, 'b', { duration: 60, pseudo: 'after', hold: true }); return getComputedStyle(el, '::after').translate; });
+    ok('hold works on a pseudo-element, and "after" is read as ::after', held === '0px 8px', held);
+    ok('no page errors', errors.length === 0, errors.join(' | '));
+  }, { pages: { '/m': page(`${m}\n#two { animate: a 400 infinite alternate, b 600 infinite alternate }\n#ps::before { content: "x"; animate: a 400 infinite, b 600 infinite essential }\n#plain::after { content: "y"; display: block }`, '<div id=two></div><div id=ps></div><div id=plain></div>') } });
+  // build output
+  const r = compile(`${m}\n#ps::before { content: "x"; animate: a 400 infinite, b 600 infinite essential }`, 't');
+  const dir = mkdtempSync(path.join(tmpdir(), 'dssl-multi-'));
+  writeFileSync(path.join(dir, 'a.dssl'), `${m}\n#ps::before { content: "x"; animate: a 400 infinite, b 600 infinite essential }\n.y::after { content: "z"; animate: a 400 infinite, b 600 infinite }`);
+  const b = spawnSync(process.execPath, ['--no-warnings', path.join(ROOT, 'cli/dssl.mjs'), 'build', path.join(dir, 'a.dssl'), '-o', path.join(dir, 'a.css')], { encoding: 'utf8' });
+  const css = readFileSync(path.join(dir, 'a.css'), 'utf8');
+  const flat = css.replace(/\s+/g, ' ');
+  ok('dssl build writes both as one animation list: the essential one always, the pair behind the reduced-motion check',
+    b.status === 0
+    && /\(#ps\)::before \{[^}]*animation: b 600ms [^;]*;/.test(flat)
+    && /prefers-reduced-motion: no-preference\) \{ :where\(#ps\)::before \{ animation: a 400ms [^;]*, b 600ms [^;]*; \} \}/.test(flat)
+    && /prefers-reduced-motion: no-preference\) \{ :where\(\.y\)::after \{ animation: a 400ms [^;]*, b 600ms [^;]*; \} \}/.test(flat), b.stderr + flat.slice(flat.indexOf('#ps') - 80, flat.indexOf('#ps') + 900));
+  void r;
+}
+
+section('7. outline-shape follows the shape, not the box');
+{
+  ok('outline-shape writes four hard drop-shadows', warns('.a { outline-shape: 3 #00f }').length === 0 && (() => { const d = compile('.a { outline-shape: 3 #00f }', 't').doc.rules[0].decls[0]; return d.prop === 'filter' && (d.value.match(/drop-shadow/g) || []).length === 4; })());
+  ok('outline-shape needs a width', errs('.a { outline-shape: #00f }').length === 1);
+  ok('outline-shape: none clears it', compile('.a { outline-shape: none }', 't').doc.rules[0].decls[0].value === 'none');
+  await withBrowser(async ({ open }) => {
+    const p = await open('/o'); await ready(p); await p.waitForTimeout(300);
+    const png = decodePng(await p.screenshot({ clip: { x: 0, y: 0, width: 300, height: 300 } }));
+    const blue = (x, y) => { const c = px(png, x, y); return c[2] > 200 && c[0] < 60; };
+    const red = (x, y) => { const c = px(png, x, y); return c[0] > 200 && c[2] < 60; };
+    ok('the circle stays red', red(130, 130));
+    ok('a ring of blue sits just outside the circle\'s edge (not the box\'s)', blue(130 + 32, 130) && blue(130 - 32, 130) && blue(130, 130 - 32) && blue(130, 130 + 32));
+    ok('and the far corner of the box (empty, transparent) is not outlined', !blue(103, 103) && !blue(157, 157));
+  }, { pages: { '/o': page('#c { position: absolute; left: 100px; top: 100px; width: 60px; height: 60px; border-radius: 50%; background: #f00; outline-shape: 4 #00f }', '<div id=c></div>') }, viewport: { width: 300, height: 300 } });
+}
+
+section('8. syntax: rotate, states inside ::after, font:');
+{
+  ok('rotate: 5 is 5deg', compile('.a { rotate: 5 }', 't').doc.rules[0].decls[0].value === '5deg' && compile('.a { rotate: -12.5 }', 't').doc.rules[0].decls[0].value === '-12.5deg');
+  ok('rotate: 5deg, 0.1turn and x 30 still work', ['5deg', '0.1turn'].every((v) => compile(`.a { rotate: ${v} }`, 't').doc.rules[0].decls[0].value === v) && compile('.a { rotate: x 30 }', 't').doc.rules[0].decls[0].value === 'x 30deg');
+  ok('rotate takes a token or none', compile('.a { rotate: none }', 't').errors.length === 0);
+  ok('rotate works in a motion frame', (() => { const r = compile('motion tip { from { rotate: 0 } to { rotate: 12 } }\n.a { animate: tip 300 }', 't'); return r.errors.length === 0 && JSON.stringify(r.doc.motionFrames.tip.frames).includes('12deg'); })());
+  const nested = compile('.btn { ::after { content: ""; opacity: 0; hover { opacity: 1 } } }', 't');
+  ok('a state inside ::after is that pseudo-element in that state', nested.errors.length === 0 && nested.doc.shadowRules.some((r) => r.sel === '.btn:hover' && r.pseudo === 'after' && r.decls.some((d) => d.prop === 'opacity')), JSON.stringify(nested.errors));
+  ok('and so does focus', compile('.btn { ::after { focus { color: red } } }', 't').doc.shadowRules.some((r) => r.sel === '.btn:focus'));
+  ok('seen inside a pseudo-element is explained, not silently dropped', errs('.btn { ::after { seen { opacity: 1 } } }').some((e) => /seen/.test(e)));
+  ok('a rule inside ::after is still refused', errs('.btn { ::after { .x { color: red } } }').length === 1);
+  ok('font: with the CSS shorthand is an error that says what DSSL means', errs('.a { font: bold 16px Arial }').some((e) => /CSS font shorthand/.test(e)) && errs('.a { font: 700 16px "Fraunces", serif }').length === 1 && errs('.a { font: italic 16px/1.4 serif }').length === 1);
+  ok('font: 16/1.5 color.ink and font: 18 still work', errs('.a { font: 16/1.5 color.ink }').length === 0 && errs('.a { font: 18 }').length === 0 && errs('.a { font: 1.2rem }').length === 0);
+  await withBrowser(async ({ open, errors }) => {
+    const p = await open('/n'); await ready(p); await p.waitForTimeout(200);
+    ok('rotate: 5 really rotates the element', await p.evaluate(() => getComputedStyle(document.getElementById('r')).rotate) === '5deg');
+    const op = () => p.evaluate(() => getComputedStyle(document.getElementById('b'), '::after').opacity);
+    ok('::after is hidden at rest', await op() === '0');
+    await p.hover('#b'); await p.waitForTimeout(150);
+    ok('and shows when the button is hovered', await op() === '1');
+    ok('no page errors', errors.length === 0, errors.join(' | '));
+  }, { pages: { '/n': page('#r { rotate: 5 }\n#b { display: block; width: 100px; height: 40px; ::after { content: "!"; opacity: 0; hover { opacity: 1 } } }', '<div id=r></div><div id=b></div>') } });
+}
+
+section('9. rules that can never win');
+{
+  const mk = (id, sel, props, extra = {}) => ({ id, sel, decls: Object.entries(props).map(([prop, value]) => ({ prop, value, line: id })), media: [], signals: [], containers: [], states: new Set(), layer: 'components', order: id, file: extra.file || 'a.dssl', line: id, ...extra });
+  let r = shadowedRules([mk(1, '.prop.broc', { 'z-index': '1' }), mk(2, '.prop', { 'z-index': '2' }, { file: 'b.dssl' })]);
+  ok('.prop.broc before a later .prop, same property: found', r.length === 1 && r[0].a.sel === '.prop.broc' && r[0].b.file === 'b.dssl' && r[0].a.props[0] === 'z-index', JSON.stringify(r));
+  ok('a descendant selector before a bare one is found too', shadowedRules([mk(1, '.nav a', { color: 'red' }), mk(2, 'a', { color: 'blue' })]).length === 1);
+  ok('the other way round (specific one later) is fine: that is how you override', shadowedRules([mk(1, '.prop', { 'z-index': '2' }), mk(2, '.prop.broc', { 'z-index': '1' })]).length === 0);
+  ok('different properties are fine', shadowedRules([mk(1, '.prop.broc', { 'z-index': '1' }), mk(2, '.prop', { color: 'red' })]).length === 0);
+  ok('the same value is not reported (nothing is lost)', shadowedRules([mk(1, '.a.b', { color: 'red' }), mk(2, '.a', { color: 'red' })]).length === 0);
+  ok('a later rule that is not in the same media is fine', shadowedRules([mk(1, '.a.b', { color: 'red' }), mk(2, '.a', { color: 'blue' }, { media: ['(min-width: 600px)'] })]).length === 0);
+  ok('a later rule for another state is fine', shadowedRules([mk(1, '.a.b', { color: 'red' }), mk(2, '.a', { color: 'blue' }, { states: new Set(['hover']) })]).length === 0);
+  ok('a later rule in a lower layer loses, so it is fine', shadowedRules([mk(1, '.a.b', { color: 'red' }, { layer: 'utilities' }), mk(2, '.a', { color: 'blue' }, { layer: 'base' })]).length === 0);
+  ok('a later rule that needs more than the first one gives is fine', shadowedRules([mk(1, '.a', { color: 'red' }), mk(2, '.a.c', { color: 'blue' })]).length === 0);
+  ok('a later descendant rule cannot shadow (it matches less)', shadowedRules([mk(1, '.a.b', { color: 'red' }), mk(2, '.x .a', { color: 'blue' })]).length === 0);
+  ok('pseudo-element rules are left alone', shadowedRules([mk(1, '.a.b', { color: 'red' }, { pseudo: 'before' }), mk(2, '.a', { color: 'blue' }, { pseudo: 'before' })]).length === 0);
+  ok('tag + class: div.a before div is found; before span is not', shadowedRules([mk(1, 'div.a', { color: 'red' }), mk(2, 'div', { color: 'blue' })]).length === 1 && shadowedRules([mk(1, 'div.a', { color: 'red' }), mk(2, 'span', { color: 'blue' })]).length === 0);
+  // end to end: CLI, two files
+  const dir = mkdtempSync(path.join(tmpdir(), 'dssl-shadow-'));
+  writeFileSync(path.join(dir, 'a.dssl'), '.prop.broc { z-index: 1; color: red }\n');
+  writeFileSync(path.join(dir, 'b.dssl'), '.prop { z-index: 2 }\n');
+  const run = (...a) => spawnSync(process.execPath, ['--no-warnings', path.join(ROOT, 'cli/dssl.mjs'), ...a], { encoding: 'utf8' });
+  let c = run('check', path.join(dir, 'a.dssl'), path.join(dir, 'b.dssl'));
+  ok('dssl check names the lost line, the winner and where it is', c.status === 0 && /a\.dssl:1 - warning - z-index in "\.prop\.broc" can never apply: "\.prop" \(b\.dssl:1\)/.test(c.stderr), c.stderr);
+  ok('and --strict fails on it', run('check', '--strict', path.join(dir, 'a.dssl'), path.join(dir, 'b.dssl')).status === 1);
+  c = run('check', path.join(dir, 'b.dssl'), path.join(dir, 'a.dssl'));
+  ok('in the other order there is nothing to say', !/can never apply/.test(c.stderr), c.stderr);
+  // in the browser
+  await withBrowser(async ({ open, context, base, errors }) => {
+    const pg = await context.newPage(); const warnings = [];
+    pg.on('console', (m) => { if (m.type() === 'warning') warnings.push(m.text()); });
+    await pg.goto(base + '/w'); await ready(pg); await pg.waitForTimeout(200);
+    ok('the page says so in the console, once per rule, with both places', warnings.filter((t) => /can never apply/.test(t)).length === 1 && /\.prop\.broc/.test(warnings.find((t) => /can never apply/.test(t)) || ''), JSON.stringify(warnings));
+    const lint = await pg.evaluate(async () => (await DSSL.lint(document.body, { log: false })).filter((f) => f.kind === 'shadowed').map((f) => f.message));
+    ok('and DSSL.lint() lists it as "shadowed"', lint.length === 1, JSON.stringify(lint));
+    ok('no page errors', errors.length === 0, errors.join(' | '));
+  }, { pages: { '/w': `<!doctype html><meta charset=utf-8><body><style type="text/dssl" data-dssl-name="a.dssl">.prop.broc { z-index: 1 }</style><style type="text/dssl" data-dssl-name="b.dssl">.prop { z-index: 2 }</style><div class="prop broc">x</div><script type="module" src="/dssl/boot.js"></script>` } });
+  // the CLI can find the engine anywhere
+  const lone = mkdtempSync(path.join(tmpdir(), 'dssl-lone-'));
+  mkdirSync(path.join(lone, 'tool'));
+  copyFileSync(path.join(ROOT, 'cli/dssl.mjs'), path.join(lone, 'tool/dssl.mjs'));
+  writeFileSync(path.join(lone, 'x.dssl'), '.a { color: red }\n');
+  const bare = spawnSync(process.execPath, ['--no-warnings', path.join(lone, 'tool/dssl.mjs'), 'check', path.join(lone, 'x.dssl')], { encoding: 'utf8' });
+  ok('a CLI file with no engine beside it fails (so --engine is needed)', bare.status !== 0);
+  const withEngine = spawnSync(process.execPath, ['--no-warnings', path.join(lone, 'tool/dssl.mjs'), 'check', path.join(lone, 'x.dssl'), '--engine', path.join(ROOT, 'public/dssl')], { encoding: 'utf8' });
+  ok('--engine <folder> points it at the engine', withEngine.status === 0, withEngine.stderr);
+  const envEngine = spawnSync(process.execPath, ['--no-warnings', path.join(lone, 'tool/dssl.mjs'), 'check', path.join(lone, 'x.dssl')], { encoding: 'utf8', env: { ...process.env, DSSL_ENGINE: path.join(ROOT, 'public/dssl') } });
+  ok('so does DSSL_ENGINE', envEngine.status === 0, envEngine.stderr);
+  const badEngine = spawnSync(process.execPath, ['--no-warnings', path.join(lone, 'tool/dssl.mjs'), 'check', path.join(lone, 'x.dssl'), '--engine', lone], { encoding: 'utf8' });
+  ok('a folder that is not the engine is refused in plain words (exit 2)', badEngine.status === 2 && /no parser\.js/.test(badEngine.stderr), badEngine.stderr);
+}
+
+section('10. DSSL.lint is quieter and fairer');
+await withBrowser(async ({ open, errors }) => {
+  const p = await open('/l'); await ready(p); await p.waitForTimeout(300);
+  const res = await p.evaluate(async () => (await DSSL.lint(document.body, { log: false })).map((f) => ({ kind: f.kind, sel: f.selector })));
+  const bad = (cls) => res.some((f) => f.kind === 'contrast' && f.sel.includes(cls));
+  ok('text in a closed menu (opacity 0) is not measured against itself', !bad('.closed'), JSON.stringify(res));
+  ok('text with a hard outline that sets the letters apart is fine', !bad('.stroked'), JSON.stringify(res));
+  ok('text with a tight contrasting shadow is fine', !bad('.shadowed'), JSON.stringify(res));
+  ok('a soft glow shadow does not rescue unreadable text', bad('.glow'), JSON.stringify(res));
+  ok('plain unreadable text is still reported', bad('.plain'), JSON.stringify(res));
+  ok('no page errors', errors.length === 0, errors.join(' | '));
+}, { pages: { '/l': page('.stage { background: #c8c8c8; color: #222 }\n.plain { color: #d0d0d0 }\n.closed { color: #d0d0d0; opacity: 0 }\n.stroked { color: #fff; text-stroke: 3 #000 }\n.shadowed { color: #fff; text-shadow: 1px 1px 0 #000 }\n.glow { color: #d8d8d8; text-shadow: 0 0 12px #000 }', '<div class=stage><p class=plain>plain</p><p class=closed>closed</p><p class=stroked>stroked</p><p class=shadowed>shadowed</p><p class=glow>glow</p></div>') } });
+
+section('11. test helpers: pause, step, resume');
+await withBrowser(async ({ open, errors }) => {
+  const p = await open('/t'); await ready(p); await p.waitForTimeout(150);
+  const tx = () => p.evaluate(() => parseFloat(DSSL.computed(document.getElementById('s'), 'translate')) || 0);
+  await p.evaluate(() => DSSL.pauseMotion());
+  const a = await tx(); await p.waitForTimeout(300); const b = await tx();
+  ok('pauseMotion() holds every animation still', a === b, `${a} vs ${b}`);
+  await p.evaluate(() => DSSL.stepMotion(250));
+  const c = await tx();
+  ok('stepMotion(ms) moves them forward by exactly that, whatever the clock says', Math.abs((c - b) - 50) < 4, `moved ${c - b} (slide is 200px in 1000ms, so 250ms is 50px)`);
+  await p.evaluate(() => DSSL.stepMotion(250));
+  ok('and again', Math.abs((await tx()) - c - 50) < 4);
+  await p.evaluate(() => { const d = document.createElement('div'); d.id = 'late'; d.className = 'go'; document.body.appendChild(d); });
+  const held = await p.evaluate(async () => { await DSSL.settled(); const a = document.getElementById('late').getAnimations()[0]; return a ? a.playState : 'none'; });
+  ok('an element styled while paused starts paused too', held === 'paused', held);
+  await p.evaluate(() => DSSL.resumeMotion());
+  await p.waitForTimeout(200);
+  ok('resumeMotion() lets them run again', (await tx()) !== c + 50 && await p.evaluate(() => document.getElementById('s').getAnimations()[0].playState) === 'running');
+  ok('no page errors', errors.length === 0, errors.join(' | '));
+}, { pages: { '/t': page('motion slide { from { translate: 0 0 } to { translate: 200 0 } }\n.go { animate: slide 1000 linear infinite }', '<div id=s class=go></div>') } });
+
+section('12. docs and version');
+{
+  const read = (f) => readFileSync(path.join(ROOT, f), 'utf8');
+  const API = await import('../public/dssl/index.js');
+  ok('the engine says 0.15.0', API.VERSION === '0.15.0');
+  for (const f of ['GUIDE.md', 'README.md', 'llms.txt', 'PARITY.md', 'src/components/dssl/views/ChangelogView.tsx', 'dssl-vscode/CHANGELOG.md']) ok(`${f} has a 0.15.0 section`, /0\.15\.0/.test(read(f)));
+  const guide = read('GUIDE.md');
+  for (const w of ['outline-shape', 'DSSL.settled', 'DSSL.signal(\'hp\'', 'pauseMotion', '--engine', 'z 5']) ok(`the guide covers ${w}`, guide.includes(w));
+  ok('llms.txt and public/llms.txt are the same file', read('llms.txt') === read('public/llms.txt'));
+}
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

scripts/test-v090.mjs

@@ -301,7 +301,7 @@ section('dssl build: what stays in the runtime');
 
 /* ------------------------------------------------------------------ */
 section('release');
-ok('the engine version is 0.9 or later', /^0\.(9|1[0-4])\./.test(VERSION), VERSION);
+ok('the engine version is 0.9 or later', /^0\.(9|1[0-5])\./.test(VERSION), VERSION);
 
 console.log(`\n${pass} passed, ${fail} failed`);
 process.exit(fail ? 1 : 0);

src/components/dssl/views/ChangelogView.tsx

@@ -11,6 +11,20 @@ const ENTRIES: {
   code?: string;
   kind?: "spec" | "vote" | "add";
 }[] = [
+  {
+    version: "v0.15.0",
+    date: "growth phase \u00b7 the second game review",
+    title: "Smoke that stops, scoped signals, and rules that tell you they never win.",
+    why: "the builder came back after shipping a real game and listed what still hurt. Most of it was aura edge cases and silent losses.",
+    kind: "add",
+    body:
+      "Aura keeps up with moving things under reduced motion (it used to redraw twice a second), stops emitting from anything you cannot see (opacity 0, display none, visibility hidden, on it or any ancestor), and takes z 5 to sit under a hill. There is no specificity, so a rule in an earlier file that a later rule always beats used to lose without a word; dssl check, the console and DSSL.lint now name both rules. Signals keep their type, DSSL.signal(name, value, el) scopes one to a subtree, and a signal restyles only the elements its rules select. await DSSL.settled() makes styling final the moment you need it, DSSL.computed(el, prop) reads the real value, and DSSL.pauseMotion(), stepMotion(ms) and resumeMotion() freeze and step every animation for tests. animate takes a list (blink and waddle on one element, also on ::before and in dssl build), DSSL.play takes a pseudo element, outline-shape draws an outline that follows the picture's alpha, rotate: 5 is 5deg, a state can sit inside ::after, and a CSS-style font: is now an error that says what DSSL's font: means. DSSL.lint skips invisible text and respects text-stroke and tight shadows. The dssl command takes --engine ./dssl. Not verified: Firefox and Safari.",
+    code: `.duck { animate: blink 300 infinite, waddle 900 infinite alternate }
+.sprite { outline-shape: 3 color.ink }
+.btn { ::after { content: ""; opacity: 0; hover { opacity: 1 } } }
+DSSL.signal('screen', 'shop', paneB)
+await DSSL.settled()`,
+  },
   {
     version: "v0.14.0",
     date: "growth phase \u00b7 made for games",

src/lib/vocab.json

@@ -346,6 +346,14 @@
     {
       "key": "unclipped",
       "doc": "let the light spill out of a parent that clips (overflow: hidden, auto, scroll). Without it the aura is cut at that edge, like the element itself"
+    },
+    {
+      "key": "always",
+      "doc": "keep emitting even when the element cannot be seen (opacity 0, display: none, visibility: hidden, on it or an ancestor): for an invisible anchor that smoke or sparks come out of"
+    },
+    {
+      "key": "z",
+      "doc": "the z-index of the layer this light is drawn on: `z 5` puts it under a hill with z-index 10. It meets elements in the page's root stacking context"
     }
   ],
   "particleKeys": [
@@ -428,6 +436,14 @@
     {
       "key": "unclipped",
       "doc": "let the particles leave a parent that clips (overflow: hidden, auto, scroll). Without it they are cut at that edge"
+    },
+    {
+      "key": "always",
+      "doc": "keep emitting even when the element cannot be seen (opacity 0, display: none, visibility: hidden, on it or an ancestor): for an invisible anchor that smoke or sparks come out of"
+    },
+    {
+      "key": "z",
+      "doc": "the z-index of the layer these particles are drawn on: `z 5` puts them under a hill with z-index 10. It meets elements in the page's root stacking context"
     }
   ],
   "sliderClauses": [