@excom/quark 0.1.0

package/support/demos/toggle-content.html

@@ -0,0 +1,14 @@
+<div>
+  <details>
+    <summary>Panel <span bind-status></span></summary>
+    <p>Panel body.</p>
+  </details>
+  <quark-sheet>
+    details[open] [bind-status] {
+      content: "Open";
+    }
+    details:not([open]) [bind-status] {
+      content: "Closed";
+    }
+  </quark-sheet>
+</div>

package/support/demos/unset.html

@@ -0,0 +1,12 @@
+<div>
+  <details>
+    <summary bind-foo></summary>
+    <p>Open me to shadow the host's binding.</p>
+  </details>
+  <quark-sheet>
+    :scope { $foo: 1; }
+    details[open] { $foo: 2; }
+    details:not([open]) { $foo: unset; }
+    [bind-foo] { content: "$foo resolves to #{$foo}"; }
+  </quark-sheet>
+</div>

package/support/demos/view-transition.html

@@ -0,0 +1,36 @@
+<div data-count="2">
+  <button type="button" data-add>Add planet</button>
+  <button type="button" data-remove>Remove planet</button>
+  <ul>
+    <template>
+      <li bind-name></li>
+    </template>
+  </ul>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    :scope {
+      $count: +attr("data-count");
+      @on click (target: "[data-add]") { data-count: $count + 1; }
+      @on click (target: "[data-remove]") { data-count: $count - 1; }
+    }
+    [data-add] { disabled: $count == 4; }
+    [data-remove] { disabled: $count == 0; }
+    ul {
+      @view-transition (types: "planets") {
+        content: iterate(getPlanets().slice(0, $count));
+      }
+    }
+    [bind-name] { content: item; }
+  </quark-sheet>
+  <style>
+    #demo-quark-view-transition > :first-child {
+      ul { view-transition-name: demo-planets; }
+      li {
+        view-transition-name: match-element;
+        view-transition-class: demo-planet;
+      }
+    }
+    ::view-transition-group(.demo-planet) { animation-duration: 250ms; }
+  </style>
+</div>

package/support/docs/ATTRIBUTES.md

@@ -0,0 +1,37 @@
+# Attributes
+
+Any property that is not `$…` / `content` / `class` / `dataset` / `ariaset` becomes an attribute of the matched element; `none` removes it.
+
+## Writing attributes
+
+```quark
+dialog[open] input {
+  autofocus: "";
+}
+dialog:not([open]) input {
+  autofocus: none;
+}
+```
+
+A string or number is written as text, a boolean writes `""` (present) or removes the attribute, and a wipe value (`none`, `null`, `undefined`) removes it. Custom attributes always contain a dash (`data-is-empty`, `is-open`) so they can never collide with a native one.
+
+## Reading attributes
+
+A literal `attr("x")` in an expression subscribes to `x` — the rule re-runs when that attribute changes, even if `x` is not in the selector. `attr($name)` does not subscribe.
+
+## Attribute helpers
+
+- `class:` sets the `class` attribute from a string (replaces), an array (joined) or an object (`{ name: boolean }` toggles each class).
+- `dataset:` writes one `data-*` attribute per key (camelCase → dash-case) and removes the `data-*` attributes this sheet set earlier; `ariaset:` does the same with the `aria-` prefix. Unpack a pre-defined object (`dataset: item`) rather than constructing a map for it.
+
+## Form controls
+
+On `<input>` and `<option>` the `value` / `checked` / `selected` attributes are only defaults; once the user has touched the control the browser stops mirroring them into the live property. Quark keeps the attribute authoritative: writing `value:` / `checked:` on an `<input>` or `selected:` on an `<option>` also sets the live property, so an edited control follows the rule whenever it writes (even to the value the attribute already holds). Custom elements are not touched, and `<select>` has no `value` attribute (write `selected:` on its options). The sync is one-way: typing never updates an attribute and is not observed.
+
+```quark
+[data-unit="f"] input {
+  value: ($celsius * 9 / 5 + 32).toFixed(1); /* shows even after the user typed */
+}
+```
+
+A text result painted into a `<textarea>` is mirrored the same way — see [Content](./CONTENT.md).

package/support/docs/AT_RULES.md

@@ -0,0 +1,45 @@
+# At-rules
+
+Seven at-rules run: `@use` imports modules, `@scope` anchors rules, `@on` wires listeners, `@dispatch` / `@command` send events and commands from an `@on` block, `@view-transition` animates a block's writes, `@delay` defers a block, and `@warn` / `@debug` / `@error` report from a rule.
+
+## Reference
+
+`@on` takes a comma list of event names, an optional options group (a map: `name: value` entries and bare flags) and a block applied once per event — or just the options. `@dispatch` / `@command` take a name list and options, inside `@on` blocks only. `@delay` takes a duration expression and a block; `@warn` / `@debug` / `@error` take an expression. *Generated.*
+
+<!-- generated:at-rules -->
+| At-rule | Effect |
+| --- | --- |
+| `@use "url" [as name \| as *];` | Imports a JS module anywhere in the sheet. The namespace defaults to the URL's last path segment without its extension; `as *` merges exports into the bare scope, last import winning. A `with (…)` clause is a parse error. |
+| `@scope { … }` | Rules inside stay anchored to the host in a global sheet (the implicit wrapper of a scoped sheet). It takes no prelude. |
+| `@on <event>[, <event>] [(options)] { … }` | Inside a rule: listens for the events (bare names such as `click` or `super-form-success`, or strings; a comma list shares one listener) on the matched element and applies the block once per event — a one-shot transaction. The block is an ordinary rule body: declarations write the matched element (attributes, `$variables`, `--props`, `content`), nested rules write its matching descendants, or its siblings when the nested selector starts with `+` / `~`, `@dispatch` / `@command` statements fire after those writes are queued. `event` names the DOM event and `target` the delegate (or `event.target`) inside the block and in its per-event options. `@on` inside a block is not supported. |
+| `@on <event> (option, option: value) …` | An options group after the events gates and configures the listener; with it the block is optional (`@on submit (prevent-default);`). A bare name is a flag. Filters: `target: "<selector>"` (delegation — fires only when the event target is inside a matching descendant; that element is `target` in the block), `self` (only when the event target is the matched element), `key: "Escape"` / `"Shift+K"` (keyboard chords; space-separated alternatives). Event flags: `prevent-default`, `stop-propagation`, `stop-immediate-propagation`. Timing: `debounce: <ms>`, `throttle: <ms>`. JS: `handle: fn` — a function (or a call returning one, or a list `(a, b)`) called with the event before the block, `this` being the element. Registration: `once` (removed after the first event that passes the filters), `passive`, `capture`, `host: window` / `host: document` (listen there while the element is connected; `target` then resolves against the whole document). `target`, `key`, `debounce`, `throttle` and `handle` are evaluated when the event fires, in the block's scope; the rest once per match. Two `@on`s for one event may coexist when their options differ. |
+| `@dispatch <event>[, <event>] [(options)];` | Inside an `@on` block (or a nested rule / `@delay` block within one): dispatches a `CustomEvent` of each name from the block's element after the block's writes are queued — synchronously, before they paint, so the event is an occurrence, not a delivery of State. Options, evaluated per event: `detail: <expression>`; `target: "<selector>"` (every match in the element's document; `:scope` = the block's element, not the sheet host — resolved as `<event-handler target-ref>` is) or `target: <element \| list>` (`closest("provider-fetch")`); `host: window` / `host: document`; `form: "<selector>"` or `form: <form>` (its field values become the detail, an explicit `detail` map merges over them); the flags `bubbles` (default true), `cancelable` (default true), `composed` (default false), each settable to `false`. Dispatching the enclosing `@on` event is refused; every dispatch is one loop-guard hop, so an event cycle is cut. Not allowed at rule level: a rule matching is not an occurrence. |
+| `@command <name>[, <name>] [(target: …)];` | Inside an `@on` block: invokes each command on the target elements (the block's element by default; `target` as for `@dispatch`) the way a `<button command commandfor>` would — native commands (`show-modal`, `close`, `request-close`, `show-popover`, `hide-popover`, `toggle-popover`) and custom `--names`, which reach the target as a `command` event. Where the browser lacks the Invoker Commands API, custom commands are dispatched as a synthetic `command` event and native ones call the element's method. Only `target` is an option. |
+| `@view-transition [(options)] { … }` | Inside a rule, around rules, or inside an `@on` block: every paint of the writes in the block — its declarations (on the rule's element) and its nested rules' — commits inside `document.startViewTransition()`, so CSS animates the change (`view-transition-name`, `::view-transition-*`). It scopes *how* writes land, never *when* rules run. The transition waits for Quark to settle before the new state is captured, so writes that react to these land in the same cut. Committed without a transition: writes that change nothing, the sheet's first render, `prefers-reduced-motion: reduce`, browsers without the API, and writes while another view transition is active. |
+| `@view-transition (option, option: value) { … }` | `types: "a b"` names the transition for `:active-view-transition-type()` (a string or a list). `timeout: <ms>` caps the settle wait (default 300). `delay: <ms>` holds these writes back first. `first-render` also animates the sheet's first render. `if-active: skip \| replace`: while another transition runs, commit unanimated (default) or start anyway, which skips the running one. `until: "<selector>"` keeps the transition open until the block's element matches the selector, `until: <promise>` until it settles (default timeout 1000; the page is frozen meanwhile, so for short waits only). Values are evaluated per write. |
+| `@delay <ms> { … }` | Inside a rule or an `@on` / `@delay` block: applies the block once, `<ms>` milliseconds (an expression) after the rule applied or the event fired — provided the element is still in the document and the rule still matches; otherwise the block is dropped. Applying the rule again restarts the timer (one per element). The block is an ordinary rule body (declarations write the matched element, nested rules its descendants; `event` / `target` are kept inside an `@on` block). Timers keep the loop guard's causal depth and are cleared when the sheet unregisters. |
+| `@warn <expression>; / @debug <expression>; / @error <expression>;` | Inside a rule or a block: evaluates the expression on the matched element and reports it — to the console at that level (`@debug` is silent below debug logging) and to DevTools as `quark/diagnostic`. The selector is the condition (`img:not([alt]) { @warn "img needs alt"; }`). `@warn` / `@error` speak once per element and rule; `@debug` speaks on every application, so it re-logs when a binding or `prop()` it reads changes. A comma list reports one value per item. |
+<!-- /generated -->
+
+```quark
+form {
+  @on submit (prevent-default, handle: saveDraft);
+  @on keydown (key: "Escape") { is-editing: none; }
+  @on reset { @dispatch draft-cleared (target: "#status"); }
+  &:not([is-locked]) { @on input (debounce: 200) { data-draft: event.target.value; } }
+  button[data-copy] { @on click { data-copied: ""; @delay 2000 { data-copied: none; } } }
+  img:not([alt]) { @warn "img needs alt"; }
+}
+```
+
+## Pages
+
+- [`@use`](./USE.md) — JS modules
+- [`@on`](./ON.md) — events, blocks, options
+- [`@dispatch` / `@command`](./DISPATCH.md) — outgoing events and commands
+- [`@view-transition`](./VIEW_TRANSITION.md) — animated writes
+- [`@delay`](./DELAY.md) — deferred writes
+- [`@warn` / `@debug` / `@error`](./DIAGNOSTICS.md) — diagnostics
+- `@scope` — see [Sheets & scoping](./SHEETS.md)
+
+That is the whole set. Any other name — CSS's `@media`, `@supports`, `@keyframes`, SCSS's `@if`, `@mixin`, … — is a parse error (`@media is not a Quark at-rule`).

package/support/docs/BUILTINS.md

@@ -0,0 +1,57 @@
+# Built-in functions
+
+Available in every expression, after `@use` exports: element reads, loop context, rendering, listeners, utilities.
+
+## Reference
+
+*Generated.*
+
+<!-- generated:builtin-functions -->
+**Element reads**
+
+| Name | Description |
+| --- | --- |
+| `attr("name")` | The matched element's attribute value (`null` when absent). `attr("content")` returns its `innerHTML`. A literal name is observed: the rule re-runs when that attribute changes, even if it is not in the selector. `attr($name)` reads but does not subscribe. |
+| `prop("name")` | The matched element's JS property (`prop("provision")` reads a Neutron provision). A literal name is observed: the rule re-runs when JS assigns `element.name` (coalesced per microtask). In-place mutation and browser-driven native state are not observed. `prop($name)` reads but does not subscribe. |
+| `closest("selector")` | `element.closest(selector)` from the matched element: the nearest ancestor-or-self matching the selector, else `null`. Not observed. |
+| `element` | The matched element itself — the node the rule is applied to (inside an `@on … { }` block the listening element; `target` is the delegate). Hand it to `@use` functions that need the node: `@on click fire(element)`, `$chart: mount(element)`. Reads through it are not observed — use `attr()` / `prop()` for reactive reads. |
+
+**Loop context**
+
+| Name | Description |
+| --- | --- |
+| `item` | Inside an `iterate()` row: the current collection item (the value for objects). `undefined` outside a row. |
+| `index` | Inside an `iterate()` row: the current position (the key for objects). `undefined` outside a row. |
+
+**Rendering (`content`)**
+
+| Name | Description |
+| --- | --- |
+| `iterate(collection, "template-ref"?, "key-property"?)` | For `content`: renders one clone of the element's `<template>` child (or the template at `template-ref`, a selector / URL) per array item or object entry, keyed by `key-property` (else a content hash) so existing rows are reused. `null` / `undefined` wipes the rows; an empty collection clears them; a non-collection no-ops. |
+| `template("template-ref"?)` | For `content`: renders one clone of the referenced `<template>` (selector or URL; defaults to the element's own `<template>` child). |
+| `dangerous-html(html)` | For `content`: sets `innerHTML` to the string. No sanitizing: never pass user-controlled markup. |
+
+**Event listeners**
+
+| Name | Description |
+| --- | --- |
+| `event` | Inside an `@on … { }` block, its per-event options and its `@dispatch` / `@command` statements: the DOM event being handled (`event.target`, `event.detail`, …). `undefined` elsewhere. |
+| `target` | Inside an `@on … { }` block and its per-event options: the element the `target:` option matched (the delegate), or `event.target` without that option. `undefined` elsewhere. |
+| `prevent-default` | A listener that calls `event.preventDefault()`, for `handle:`. The `(prevent-default)` flag is the shorter form. |
+| `stop-propagation` | A listener that calls `event.stopPropagation()`, for `handle:`. The `(stop-propagation)` flag is the shorter form. |
+
+**Utilities**
+
+| Name | Description |
+| --- | --- |
+| `ternary(condition, whenTrue, whenFalse?)` | `whenTrue` if `condition` is truthy, else `whenFalse` (`null` when omitted). Prefer `if()` for multi-arm conditionals. |
+
+**Debugging**
+
+| Name | Description |
+| --- | --- |
+| `log(...values)` | Logs the values to the console and returns them as an array. |
+| `debug(...values)` | Hits a `debugger` statement and returns the values as an array. |
+<!-- /generated -->
+
+Reading the matched element's JS properties and handing the node to module functions: [Element properties](./ELEMENT_PROPERTIES.md). Methods callable on values: [Allowed methods](./METHODS.md).

package/support/docs/CONTENT.md

@@ -0,0 +1,40 @@
+# Content
+
+`content:` replaces an element's rendered children — text, a template clone, one row per item, or raw HTML.
+
+## Text, templates, HTML
+
+```quark
+article {
+  content: template("#article-tmpl"); /* or template("/views/a.html") */
+}
+details:not([open]) p {
+  content: none;
+}
+header {
+  content: dangerous-html(getHeaderHtml());
+}
+```
+
+A JS callout may also return a `Node` / `NodeList` — same paint path as `template()` / `iterate()`. A source `<template>` child is kept; writing into a `<template>` targets its `.content`; a promise is awaited.
+
+A text result painted into a `<textarea>` is also mirrored to its live `.value` (the text is only the default value; see [Attributes](./ATTRIBUTES.md#md-form-controls)).
+
+## Iterations
+
+`iterate(array)` renders one copy of the element's `<template>` per item:
+
+<include-content data-demo="iterate"></include-content>
+
+`item` / `index` are available to matching rules for each row. Objects iterate as key → `index`, value → `item`. Pass a key property (`iterate($todos, none, "id")`) so existing rows are reused when the collection changes.
+
+## Pitfall
+
+Do not render a template that re-matches the same rule — the loop guard cuts it after 50 nested paints, but the fix is the selector:
+
+```quark
+/* BAD — each new span matches again */
+span {
+  content: template("#span-template");
+}
+```

package/support/docs/CSS_VARIABLES.md

@@ -0,0 +1,16 @@
+# CSS variables
+
+`--custom-prop:` declarations write CSS custom properties on matched elements (inline style), so stylesheets consume Quark state via `var()` — computed colors, progress percentages, live theming. Values that attribute selectors can't express.
+
+## Writing custom properties
+
+<include-content data-demo="css-variables"></include-content>
+
+- Values are Quark expressions — **CSS literals must be quoted**: `--accent: "#ccc"`, not `--accent: #ccc`. Same for keywords, lengths, and functions: `"red"`, `"10px"`, `"var(--x)"`, `"red !important"` (a trailing `!important` inside the string maps to the priority argument).
+- Numeric expression results work: `--progress: "#{($done / $total * 100)}%"`.
+- Wipe values (`none` / `undefined` / `null`) remove the property; `preserve` no-ops.
+- Write-only: Quark never reads CSS variables back. Own the value in a `$variable` if rules need to react to it.
+
+## No reversion
+
+Like every other write, a CSS variable persists after its rule stops matching — write the inverse rule (see [No reversion](./NO_REVERSION.md)).

package/support/docs/DECLARATIONS.md

@@ -0,0 +1,26 @@
+# Declaration kinds
+
+The property key selects what a declaration does: a `$variable`, a CSS variable, `content`, one of the attribute helpers, or an attribute of that name.
+
+## By key shape
+
+Checked top to bottom; the first match wins. Listeners are at-rules, not declarations. *Generated.*
+
+<!-- generated:declaration-kinds -->
+| Key | Effect | Accepts |
+| --- | --- | --- |
+| `$name` | Stores a binding on each matched element; consumers resolve it by walking up from their own element (CSS custom-property semantics, shared across sheets). | Any value. `unset` deletes the binding. |
+| `--name` | Writes the CSS custom property `--name` on the element's inline style. Write-only: Quark never reads CSS variables back. A trailing `!important` inside the string sets the priority. | A string or number. CSS literals must be quoted (`"#ccc"`, `"10px"`); bare `#hex` / unit numbers are rejected at build. |
+| `content` | Replaces the element's rendered children (a source `<template>` child is kept). Promises are awaited. Writing into a `<template>` targets its `.content`. On a `<textarea>` a text result is also mirrored to the live `.value` (the text is only the default value). | A string (text), a `Node` / `NodeList`, or the result of `template()` / `iterate()` / `dangerous-html()`. Wipe values clear. |
+| `class` | Sets the `class` attribute. | A string (replaces), an array (joined with spaces), or an object (`{ name: boolean }` toggles each class). Wipe values remove the attribute. |
+| `dataset` | Writes one `data-*` attribute per key (camelCase → dash-case) and removes `data-*` attributes this sheet set earlier. | An object. Strings / numbers write as-is, booleans as present / absent, string arrays space-joined, objects and other arrays as their length. |
+| `ariaset` | Same as `dataset`, with the `aria-` prefix. | An object (same conversions as `dataset`). |
+| `<anything else>` | Sets the attribute of that name on the matched element (`none` removes it). Always contains a dash in practice; `autofocus: ""` sets a boolean attribute. On native form controls the attribute is authoritative: `value` / `checked` on `<input>` and `selected` on `<option>` also set the live property, so a control the user has edited still follows the rule. | A string or number (written as text), a boolean (`true` → `""`, `false` → removed), or a wipe value. |
+<!-- /generated -->
+
+## Details per kind
+
+- [Attributes](./ATTRIBUTES.md) — the default kind, `class` / `dataset` / `ariaset`, form controls
+- [Content](./CONTENT.md) — `content` with `template()`, `iterate()`, `dangerous-html()`
+- [CSS variables](./CSS_VARIABLES.md) — `--name`
+- [Variables](./VARIABLES.md) — `$name`

package/support/docs/DELAY.md

@@ -0,0 +1,37 @@
+# @delay
+
+`@delay <ms> { … }` applies a block once, after a pause — a "Copied!" flash, a toast that hides itself, an undo window — with no timer in JS.
+
+## Writing a delay
+
+```quark
+button[data-copy] {
+  @on click {
+    data-copied: "";
+    @delay 2000 { data-copied: none; }   /* rapid clicks restart it */
+  }
+}
+output[is-visible] { @delay 4000 { is-visible: none; } }
+todo-item[is-pending-delete] {
+  @on click (target: "[data-undo]") { is-pending-delete: none; }
+  @delay 5000 { is-deleted: ""; }         /* dropped if undo clears the gate first */
+}
+[data-flash] { @delay +attr("data-flash-ms") or 1500 { data-flash: none; } }
+```
+
+The duration is any expression — a literal, a binding, an `attr()` read, arithmetic, a `quark:math` call — in milliseconds. The block is an ordinary rule body: declarations write the matched element, nested rules write its matching descendants, and it may hold another `@delay` or a `@view-transition`. `@on` inside the block is not supported.
+
+## When it fires
+
+- The timer starts when the rule applies to the element, or when the event fires inside an `@on` block, and **restarts on every application** — one timer per element. A rule re-applies when its selector's dependencies change, so a rule that fans out on unrelated attribute changes restarts its delays too.
+- When the timer fires, the block applies **only if the element is still in the document and the rule still matches**; otherwise it is dropped. That is what makes the undo idiom above safe: clearing the gate cancels the pending write.
+- Inside an `@on` block, `event` and `target` keep the values the block was scheduled with.
+- Pending timers are cleared when the sheet unregisters.
+
+## Safety
+
+The block keeps the [loop guard](./LOOP_GUARD.md)'s causal depth of the run that scheduled it, so two delays that keep re-triggering each other are cut like any other runaway chain instead of ticking forever.
+
+Time is otherwise an Adapter's protocol: `@delay` is for a wait that belongs to one State change, not for clocks, polling or animation — those are elements (`<timer-…>`) and CSS.
+
+DevTools sees every timer as a `["quark", "delay"]` publication: `scheduled` (with `ms`), `fired`, or `dropped` (with `reason`: `"disconnected"`, `"unregistered"`, `"unmatched"`) — see [JS API](./JS_API.md).

package/support/docs/DIAGNOSTICS.md

@@ -0,0 +1,32 @@
+# @warn / @debug / @error
+
+Diagnostics report from inside a rule; the selector is the condition. Nothing is written to the document.
+
+## Writing diagnostics
+
+```quark
+img:not([alt]) { @warn "img needs alt"; }
+form button:not([type]) { @warn "button defaults to type=submit"; }
+provider-fetch[is-error] { @error "fetch failed", prop("provision").error; }
+todo-list {
+  $todos: prop("provision").body;
+  @debug "todos", $todos.length;                    /* again when $todos changes */
+  @on todo-remove { @debug "remove", event.detail.id; }
+}
+```
+
+Each statement evaluates its expression on the matched element — bindings, `attr()`, `prop()`, `event` inside an `@on` block, module functions — and reports it. A comma list reports one value per item; a single expression is one value, even when it is a list.
+
+## When it speaks
+
+- `@warn` and `@error` speak **once per element and rule**. A warning repeated on every re-run is noise; a new offending element is its own warning.
+- `@debug` speaks **on every application**, so it re-logs when a binding or `prop()` it reads changes — a trace of the value over time.
+- A failing expression reports a `quark/error` (like any declaration) instead of a diagnostic.
+- Outside a rule there is no element to evaluate against: a top-level statement is rejected when the sheet is built.
+
+## Where it goes
+
+- The console, at the matching logger level: `Quark @warn (img:not([alt])): img needs alt`. `@debug` is silent unless Quark logs at debug level (`VITE_LOG_LEVEL` ≥ 3).
+- The DevTools hook, as `["quark", "diagnostic"]` — `level`, `values`, `message`, `expression`, the selector, rule and element — so the Nucleus DevTools extension and the agent tools can list them next to the rule. See [JS API](./JS_API.md).
+
+Use `@warn` for invariants a sheet can state better than a test (`img:not([alt])`, `button:not([type])`), `@error` for States that should never occur, and `@debug` while developing a rule — then remove it. The `log()` and `debug()` built-ins remain for tracing inside an expression.

package/support/docs/DISPATCH.md

@@ -0,0 +1,81 @@
+# @dispatch / @command
+
+`@dispatch` sends a custom event and `@command` invokes a command, from inside an `@on` block. They are the outgoing half of `@on`: the sheet heard an event, wrote State, and now tells another element.
+
+```quark
+todo-item {
+  @on click (target: "[data-remove]") {
+    @dispatch todo-remove (detail: (id: attr("data-id")));
+  }
+}
+provider-fetch {
+  @on super-form-success { @dispatch provider-fetch-trigger; }
+}
+button[data-help] {
+  @on click { @command toggle-popover (target: element.nextElementSibling); }
+}
+```
+
+<include-content data-demo="dispatch"></include-content>
+
+## Where they may appear
+
+Inside an `@on … { }` block, its nested rules (then the event goes out from each matching descendant) and a `@delay` block within it. Not at rule level and not at sheet level: a rule matching is not an occurrence, so a rule cannot announce one. The runtime logs an error and drops such a statement.
+
+## When they run
+
+At the end of the block, after every write in it has been queued and before those writes paint — synchronously, like a handler. An event is an occurrence, not a delivery of State: a listener that needs the block's writes should react to the State the block wrote (an attribute the recipient's own rule selects on), not to the event. Dispatching the enclosing `@on` event type is refused. Every dispatch is one [loop-guard](./LOOP_GUARD.md) hop, so an event cycle (`@on a { @dispatch b } … @on b { @dispatch a }`) is cut like a write cycle.
+
+## `@dispatch`
+
+`@dispatch <event>[, <event>] [(options)];` — a `CustomEvent` per name. Options are evaluated per event, in the block's scope (`event`, `target`, `element`, `$bindings`):
+
+| Option | Effect |
+| --- | --- |
+| `detail: <expression>` | The event's `detail` — a map `(id: $id, at: event.timeStamp)`, a `$binding`, anything. |
+| `target: "<selector>"` | Dispatch on every element matching the selector in the element's document (or shadow root). **`:scope` is the block's element — the one the `@on` matched — not the sheet's `:scope` host.** Resolved exactly as `<event-handler target-ref>` is (`selectAll` from kit-utils): `provider-fetch:has(+ :scope)` is the `provider-fetch` right before the element, `:scope + dialog` the dialog right after it. Default: the block's element. |
+| `target: <element>` / `<list>` | An element or list of elements from an expression: `closest("provider-fetch")`, `element.nextElementSibling`, `closest("section").children`. |
+| `host: window` / `host: document` | Dispatch on the window / document instead. |
+| `form: "<selector>"` / `form: <form>` | The form's field values (as `formToJson` reads them) become the detail; an explicit `detail` map merges over them. |
+| `bubbles` / `cancelable` / `composed` | Event flags. Bare means `true`; `bubbles: false` switches one off. Defaults: bubbles and cancelable on, composed off. |
+
+An unmatched `target` warns once per element and sends nothing. Events bubble by default, so an ancestor's sheet hears a dispatch from a descendant without any `target`.
+
+## `@command`
+
+`@command <name>[, <name>] [(target: …)];` — invokes each command on the target elements the way a `<button command="…" commandfor="…">` would. Native commands — `show-modal`, `close`, `request-close`, `show-popover`, `hide-popover`, `toggle-popover` — and custom ones, which start with `--` and reach the target as a `command` event (`event.command`; `event.source` is the invoker — under the Command API the hidden button Quark clicks, so a recipient should read State from itself or the sheet rather than from `source`; without the API, the block's element).
+
+```quark
+[data-open-help] { @on click { @command show-modal (target: "#help"); } }
+#help { @on keydown (key: "Escape") { @command close; } }
+[data-refresh] { @on click { @command --refresh (target: "#feed"); } }
+```
+
+Where the browser has the Invoker Commands API, a hidden invoker button carries the command so native behaviour and `event.source` are exactly the platform's. Elsewhere, custom commands are dispatched as a synthetic `command` event and native ones call the element's method (`showModal()`, `togglePopover()`, …); an unknown native command warns once. `target` is the only option and resolves like `@dispatch`'s: the whole document, `:scope` = the block's element (not the sheet host).
+
+```quark
+:scope {
+  button {
+    @on click {
+      /* the provider-fetch right before this button */
+      @command --fetch (target: "provider-fetch:has(+ :scope)");
+    }
+  }
+}
+```
+
+A nested rule starting with a sibling combinator is the other spelling: `+ provider-fetch { @command --fetch; }` inside the block runs against the `provider-fetch` right after the button, with no `target` to resolve.
+
+```quark
+:scope {
+  button {
+    @on click {
+      + provider-fetch { @command --fetch; }
+    }
+  }
+}
+```
+
+## Replacing `<event-handler>`
+
+`@on` with `@dispatch` / `@command` covers what `<event-handler>` wires: `listen-for` is the event list, `selector-filter` / `keycode-filter` / `is-debounced` / `host-ref` are options, `fire-event` + `detail-*` + `form-ref` are `@dispatch (detail: …, form: …)`, `target-ref` is `target:`, `command-name` is `@command`. Prefer the sheet when the page has one; keep the element for markup without a sheet.

package/support/docs/ELEMENT_PROPERTIES.md

@@ -0,0 +1,34 @@
+# Element properties
+
+`prop("<name>")` reads a JS property of the matched element and re-runs when JS assigns it — the way a sheet reads an Adapter's `provision`.
+
+## `prop()`
+
+`prop("<name>")` reads a JS property of the **matched element**; it mirrors `attr("<name>")`. `prop("provision")` reads a Neutron element's provision:
+
+```quark
+provider-fetch[is-success] {
+  $todo: prop("provision").body;
+  [bind-title] { content: $todo.title; }
+}
+```
+
+A literal `prop("x")` subscribes to `x`: the rule re-runs when JS assigns `element.x` (assignments coalesce per microtask). In-place mutation of an object is not observed — assign a new object. Changes the browser makes without a JS assignment (a user typing into an `<input>`'s `value`, a `<details>` toggling `open`) are not observed either: select on the reflected attribute / listen for the event. `prop($name)` reads but does not subscribe.
+
+## Reading an ancestor provider
+
+`prop()` reads the matched element only. To read an ancestor provider, publish it as a binding from a rule that matches the provider — in a parent sheet whose host contains it (preferred) or an `is-global` sheet — and read the `$binding` from descendants:
+
+```quark
+provider-fetch[is-success] { $todos: prop("provision").body; }
+[bind-count] { content: $todos.length; }
+```
+
+## `element`
+
+`element` is the matched element itself — the way to hand the node to a module function (a handler factory, a chart mount) without a selector walk. Reads through it are not observed; use `attr()` / `prop()` for those:
+
+```quark
+[data-chart] { $chart: mountChart(element, $series); }
+button[data-sku] { @on click (handle: addToCart(element, event)); } /* evaluated per click */
+```

package/support/docs/EXPRESSIONS.md

@@ -0,0 +1,31 @@
+# Expressions
+
+A value is an expression: names resolve through keywords, modules, built-ins and `$bindings`; operators follow JS; accessors never throw.
+
+## Evaluation
+
+- **Names** resolve in order: value keywords → `@use` exports (bare `as *` exports, then namespaces) → built-in functions → `$bindings`. A `$binding` is read by walking up from the matched element to the nearest ancestor-or-self that holds it; an unbound `$name` is `undefined` (a wipe), while an unknown bare identifier is an error (a no-op). A module export shadows a built-in of the same name.
+- **Literals**: unitless numbers are numbers; a number with a unit (`10px`, `50%`) and a color (`#ccc`) evaluate to strings. Strings unescape `\n`, `\t`, `\r`, and `\x` → `x`. Interpolated strings and `url(…)` join their parts, with `null` / `undefined` parts rendered empty.
+- **`&`** in an expression is the matched element's tag name.
+- **Accessors** never throw: `.field` and `[index]` on `null` / `undefined` yield `undefined`. `object.$name` reads the property literally named `$name` (namespaced variables: `math.$pi`).
+- **Calls**: a bare callee resolves through the name order above and must be a function. A method call on a value (`item.name.trim()`) is allowed for own-property functions (a `@use` namespace, a provided object) and for the [allowed prototype methods](./METHODS.md); anything else is an error. Calling a method on `null` / `undefined` yields `undefined`. Named arguments are passed positionally (the name is ignored); `$list...` spreads an array.
+- **Operators**: `and` / `or` short-circuit and return an operand (JS semantics, so `$title or preserve` works); `not` returns a boolean; `==` / `!=` are loose; `+` concatenates when either side is a string (prefer `#{$x}` interpolation for building strings); `-` `*` `/` `%` and comparisons follow JS.
+- **`if()`** returns the value of the first arm whose condition is truthy; with no match and no `else` it is `undefined` (a wipe). `ternary()` is the two-arm function form.
+- **Lists** (space or comma separated) evaluate to arrays; **maps** to objects, with bare identifier keys taken literally (`(name: "Ada")` → `{ name: "Ada" }`) and other keys stringified.
+- **Results**: listeners and `$variables` apply synchronously; attributes, CSS variables, and content are painted in a batch. A `content` result that is a promise is awaited.
+
+## Example
+
+```quark
+[data-user] {
+  $user: prop("provision");
+  label: $user.profile.name or "Anonymous";
+  title: if($user.role == "admin": "Administrator"; else: $user.role);
+  data-tags: $user.tags.join(", ");
+  --progress: "#{($user.done / $user.total * 100).toFixed(0)}%";
+}
+```
+
+## Facts over `if()`
+
+Several rules branching on the same condition with `if()` is a smell: derive the condition once as an attribute (`data-is-admin: $user.role == "admin";` — a boolean writes `""` or removes the attribute) and select on it from Quark and CSS.

package/support/docs/INTERNAL.md

@@ -0,0 +1,8 @@
+# Limitations:
+- Interaction / validity pseudo-classes (`:hover`, `:focus`, `:checked`, `:invalid`, …) and pseudo-elements are not observed — the rule matches on its first run only (warned at build; see README *Selectors*)
+- `:has(+ …)` / `:has(~ …)` and a `:has()` nested in a complex `:is()` / `:not()` argument re-run the whole rule from the host
+- `:empty` ignores text-only changes; `:nth-child(… of S)` observes only the attributes in `S`; `:open` covers `<details>` / `<dialog>` only
+- At-rules other than `@use` / `@scope` / `@on` / `@view-transition` / `@delay` / `@warn` (`@debug`, `@error`) are not supported yet
+- `@view-transition` relies on `document.startViewTransition()`: one transition per document, no scoped transitions yet; `until` freezes the page while it waits (short waits only)
+- Setting attributes is recommended over toggling / mutating classes and ids, since the latter has a heavier impact on Quark's performance (a sheet that names any class wakes on every class change under its host)
+- Runaway cycles (attribute ↔ attribute, `$binding` ↔ `$binding` across sheets, content re-matching its own paint, rule ↔ element effect, attribute ↔ event) are cut by the shared loop guard after `LoopGuard.limit` (50) dependent writes, not prevented; writers Quark / Neutron do not route (plain `setAttribute` in app JS) are invisible to it

package/support/docs/JS_API.md

@@ -0,0 +1,53 @@
+# JS API
+
+The `Quark` class hosts a sheet programmatically (tests, tooling), settles on demand and reports to the shared DevTools hook.
+
+## `Quark`
+
+```ts
+import { Quark } from "@excom/quark";
+
+const quark = new Quark({
+  src: `span { content: "four times two equals #{twice(4)}"; }`,
+  modules: { dfault: { twice: (n) => n * 2 } },
+});
+quark.register({ sheetElement }); // host = sheetElement.parentElement
+// …
+quark.unregister();
+```
+
+`isScoped` mirrors `<quark-sheet>`'s default (see [Sheets & scoping](./SHEETS.md)); `modules` pre-provides what `@use` would import; `Quark.moduleLoader` can be overridden in tests.
+
+`Quark.whenSettled({ timeout? })` resolves once no rule pass, paint, async `content` or `@use` load is pending (`"settled"`), or after `timeout` ms (`"timeout"`, default 1000) — for tests and tools; sheets have no after-render hook.
+
+Writing `$variables` from app code goes through `element.quark` — see [Writing from JS](./JS_WRITES.md).
+
+## DevTools
+
+Quark reports to the same global hook as Neutron. The Nucleus DevTools extension installs it at page load; for tests or late attachment call `Quark.attachDevtools()` (identical to `Neutron.attachDevtools()`).
+
+Publications, one per property resolution on a matched element:
+
+- `["quark", "sheet", "registered" | "unregistered"]` on the host — `sheetId`, `ruleCount`, `isScoped`
+- `["quark", "apply"]` — `selector`, `key`, `expression`, `result`, `runId`, `isNoop` / `isWipe`
+- `["quark", "error"]` — a failed expression (`errorMessage`), which never wipes; also a loop-guard trip (`errorName: "LoopGuardDepth"` / `"LoopGuardBatch"`, `key` = the dropped attribute / binding, see [Loop guard](./LOOP_GUARD.md))
+- `["quark", "diagnostic"]` — a `@warn` / `@debug` / `@error` statement that spoke: `level`, `values`, `message`, `expression`, the selector and element (see [Diagnostics](./DIAGNOSTICS.md))
+- `["quark", "delay"]` — a `@delay` block `scheduled` (with `ms`), `fired`, or `dropped` (with `reason`: `"disconnected"`, `"unregistered"`, `"unmatched"`; see [`@delay`](./DELAY.md))
+- `["quark", "transition"]` — a commit holding `@view-transition` writes: `phase: "start"`, `"settled"` (with `result`: `"settled"` / `"until"` / `"timeout"`) or `"skip"` (with `reason`: `"unsupported"`, `"reduced-motion"`, `"hidden"`, `"unchanged"`, `"active"`, `"error"`), plus `types` and the number of `paints`
+
+The extension can also paint a whole-document paint-count heatmap from the `apply` records (toolbar icon → "Paint heatmap"); nothing is written to the page's elements.
+
+The extension's Element › Orchestration tab lists them, plus the selected element's current `$variables`, Quark-written attributes and CSS custom properties, listeners (with the `@on` handlers that attached them) and `iterate()` row context.
+
+```ts
+Quark.attachDevtools({
+  version: 1,
+  publicize: (path, meta) => console.log(path.join("/"), meta),
+});
+```
+
+The renderer Quark injects into the hook (`hook.inject(renderer)`, `kind: "quark"`) also carries the on-demand queries behind the extension's agent tools: `inspect(el)` (the snapshot above), `sheets()` (every registered sheet with host, scope, source and rules), `matchingRules(el)` (rules whose selector matches `el` now, scope-aware, in definition order) and `evaluate(el, expression, sheetId?)` (an expression evaluated as a rule on `el` would see it, `@use` modules from `sheetId` or the first matching sheet). All three are read-only queries over already-built state.
+
+## Language metadata
+
+The documented language surface (keywords, declaration kinds, at-rules, built-ins, allowed methods, pseudo-class support) is data on `@excom/quark/language`, off the main entry so its prose stays out of app bundles. The reference tables on these pages are generated from it.

package/support/docs/JS_WRITES.md

@@ -0,0 +1,36 @@
+# Writing from JS
+
+Every element carries `element.quark`, shaped like `element.style`: the sanctioned way for app JS to write a `$variable` that rules read.
+
+## `element.quark`
+
+| Method | Effect |
+| --- | --- |
+| `setProperty(name, value)` | Stores the binding on that element (it becomes the owner) and re-runs readers below it, in every sheet. Returns `true` when the value changed. |
+| `setProperties({ … })` | Stores several bindings, then announces them, so a reader of two names runs once with both. |
+| `removeProperty(name)` | `unset`: deletes the binding so readers fall through to an ancestor. |
+| `getPropertyValue(name)` | What a rule on that element would read (nearest owner, self first). |
+
+`name` may be written with or without the `$`. Change detection is by value (a new object is a change, an in-place mutation is not), the same rule a declaration follows. It is State, not an event: a value written before a sheet registers is read on the sheet's first run.
+
+```quark
+:scope { $count: 0; }
+button { @on click (handle: incrementFromJs(closest("[data-demo-counter]"))); }
+output { content: "Clicked #{$count} times"; }
+```
+
+```js
+// JS module
+export const incrementFromJs = (owner) => () => {
+  const current = Number(owner.quark.getPropertyValue("$count") ?? 0);
+  owner.quark.setProperty("$count", current + 1);
+};
+```
+
+<include-content data-demo="js-api"></include-content>
+
+## Rules of thumb
+
+- One writer per name per element: a rule that declares `$name` on the same element rewrites the JS value when its declaration re-runs (last writer wins). Initialize in the sheet and update from JS, or write from JS only.
+- Primitives that CSS or a selector should see belong in attributes (`setAttribute` + `attr()`, serializable and selectable); `element.quark` earns its place for rich values and for `$name` reads across a subtree.
+- DevTools shows a JS write as a binding change without a sheet.