@excom/quark 0.1.0

package/support/docs/LIMITATIONS.md

@@ -0,0 +1,26 @@
+# Limitations
+
+What the current engine does not observe or support, and the pitfalls that follow from it.
+
+## Beta limits
+
+- Selector features backed by state the DOM does not reflect are not observed: interaction and validity pseudo-classes (`:hover`, `:focus`, `:checked`, `:invalid`, …) match on the first run only, and the rule logs a warning at build. Everything else the native engine matches is observed — see [Selectors](./SELECTORS.md) for the list and the partial cases (`:empty` ignores text-only changes, `:nth-child(… of S)` observes only the attributes in `S`, `:open` covers `<details>` / `<dialog>` only, sibling-relative `:has(+ …)` re-runs the whole rule)
+- At-rules are Quark's own — `@use`, `@scope`, `@on`, `@dispatch` / `@command`, `@view-transition`, `@delay`, `@warn` / `@debug` / `@error` — and any other name is a parse error, so CSS's `@media` / `@keyframes` and SCSS's control flow belong in a stylesheet, not a sheet
+- 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 (styling churn included)
+- Rules do not revert when they stop matching — see [No reversion](./NO_REVERSION.md)
+- `@view-transition` relies on `document.startViewTransition()`: one transition per document, no scoped transitions yet; `until` freezes the page while it waits (short waits only)
+
+See the related section under [Limitations](/nucleus/docs/limitations) in the guides.
+
+## Pitfalls
+
+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");
+}
+```
+
+A sheet that registers after an element's connect-time events will not hear them (no replay): react to state attributes, or load the sheet first in its host.

package/support/docs/LOOP_GUARD.md

@@ -0,0 +1,30 @@
+# Loop guard
+
+Runaway write chains are cut, not prevented: one shared guard bounds every chain Quark, Neutron and `dom-observer` take part in.
+
+## What it cuts
+
+Two rules that flip each other's attributes, a rule and an element effect feeding each other, an event whose listener re-writes the attribute that fired it, or content that re-matches its own paint would otherwise run forever. The Nucleus Stack bounds every such chain with one shared guard, `LoopGuard` from `@excom/kit-utils` (Nucleus Kit users: `Neutron.DOM.LoopGuard`). Each write an engine makes carries the depth of the chain that caused it — Quark attributes, `content`, `$bindings`; Neutron attribute reflection and observed property assignments; `dom-observer` events — and the hop past the limit is **dropped**:
+
+- default limit **50** dependent writes (a legitimate chain is under ten);
+- the dropped write is logged once (`Loop guard: a chain of 51 dependent writes reached "data-x" on <p> — …`) and published to DevTools as `quark/error`;
+- nothing else happens: no event fires, no attribute is wiped, the sheet is not disabled, and the document keeps the state it had before the drop — the cycle's participants stay wherever the chain left them, so treat a trip as a bug report, not a recovery;
+- a new external write in a later task (user input, a timer, a fetch, app JS) starts a fresh chain at zero, so streams of updates never trip, however long.
+
+## API
+
+```ts
+import { LoopGuard } from "@excom/kit-utils";
+
+LoopGuard.limit; // 50
+LoopGuard.configure({ limit: 100, log: (message) => myLogger.error(message) });
+const off = LoopGuard.onTrip(({ kind, target, name, depth, limit }) => {
+  // kind: "depth" (a write chain) | "batch" (one Neutron handler re-ran > limit times)
+});
+```
+
+`configure()` is global and takes effect immediately. `onTrip` fires on every trip (the console line is deduplicated per name per task). Rules that gate on attributes they write for each other are named in a warning when the sheet builds, before anything runs.
+
+## Not covered
+
+Writes Quark and Neutron do not route — plain `setAttribute` / `innerHTML` in app JS — neither count nor get cut, and a declaration is never re-run by the attribute it wrote (`class:` excepted), so a rule cannot loop on its own gate (see [Reactivity](./REACTIVITY.md#md-loops)).

package/support/docs/METHODS.md

@@ -0,0 +1,43 @@
+# Allowed methods
+
+Prototype methods an expression may call on a value through the dot accessor. Everything else is an error; wrap other logic in a `@use` module function.
+
+## Reference
+
+*Generated.*
+
+<!-- generated:allowed-methods -->
+| Method | On | Description |
+| --- | --- | --- |
+| `.toLowerCase()` | string | Lower-cased copy. |
+| `.toUpperCase()` | string | Upper-cased copy. |
+| `.trim()` | string | Copy without leading / trailing whitespace. |
+| `.split(separator, limit?)` | string | Array of substrings. |
+| `.charAt(index)` | string | The character at `index`. |
+| `.startsWith(search, position?)` | string | Boolean. |
+| `.endsWith(search, length?)` | string | Boolean. |
+| `.padStart(length, fill?)` | string | Left-padded copy. |
+| `.padEnd(length, fill?)` | string | Right-padded copy. |
+| `.replace(search, replacement)` | string | Copy with the first match replaced (string search only). |
+| `.replaceAll(search, replacement)` | string | Copy with every match replaced (string search only). |
+| `.toString()` | string, array, number, date | String form. |
+| `.includes(search)` | string, array | Boolean. |
+| `.slice(start?, end?)` | string, array | Sub-range copy. |
+| `.indexOf(search)` | string, array | First position, or `-1`. |
+| `.lastIndexOf(search)` | string, array | Last position, or `-1`. |
+| `.concat(...values)` | string, array | Joined copy. |
+| `.at(index)` | string, array | Element at `index`; negative counts from the end. |
+| `.join(separator?)` | array | String of the items. |
+| `.flat(depth?)` | array | Flattened copy. |
+| `.toFixed(digits?)` | number | Fixed-point string. |
+| `.toLocaleString(locale?, options?)` | number, date, array | Locale-formatted string. |
+| `.toLocaleDateString(locale?, options?)` | date | Locale-formatted date. |
+| `.toLocaleTimeString(locale?, options?)` | date | Locale-formatted time. |
+| `.toISOString()` | date | ISO 8601 string. |
+| `.getAttribute("name")` | element | Attribute value or `null`. Not observed. |
+| `.hasAttribute("name")` | element | Boolean. Not observed. |
+| `.matches("selector")` | element | Boolean. |
+| `.closest("selector")` | element | Nearest ancestor-or-self matching the selector, or `null`. |
+<!-- /generated -->
+
+Own-property functions on a value (a `@use` namespace, a provided object) are always callable; see [Expressions](./EXPRESSIONS.md).

package/support/docs/MODULES.md

@@ -0,0 +1,111 @@
+# Built-in modules
+
+Pure helpers for numbers, lists, maps, strings and dates, imported like JS modules — `@use "quark:math" as math;` — so nothing is global.
+
+## Using a module
+
+```quark
+@use "quark:math" as math;
+@use "quark:list" as *;
+
+[data-progress] { --progress: math.percentage($done / $total); }
+[bind-count] { content: count($todos, "done", true); }
+```
+
+`as name` namespaces the functions (`math.clamp(0, $x, 1)`, `math.$pi`); `as *` merges them into the bare scope. Every function is pure and null-tolerant: a missing collection reads as empty, a missing value passes through, and results are copies. Collection functions take a dot path (`"user.name"`) instead of a callback.
+
+## Reference
+
+*Generated.*
+
+<!-- generated:builtin-modules -->
+**`quark:math`** — Numbers. Arguments are coerced with `parseFloat`; the CSS argument order is kept.
+
+| Name | Description |
+| --- | --- |
+| `math.$pi` | π. |
+| `math.$e` | Euler's number. |
+| `min(...values)` | The smallest value (lists are flattened). |
+| `max(...values)` | The largest value (lists are flattened). |
+| `clamp(min, value, max)` | `value` limited to the range, in CSS argument order. |
+| `round(value, digits?)` | Rounded to `digits` decimals (default 0). |
+| `floor(value)` | Rounded down. |
+| `ceil(value)` | Rounded up. |
+| `abs(value)` | Absolute value. |
+| `mod(value, divisor)` | Wrapping modulo: `mod(-1, 3)` is `2` (the `%` operator keeps the sign). `NaN` for a zero divisor. |
+| `pow(base, exponent)` | `base` to the power `exponent`. |
+| `sqrt(value)` | Square root. |
+| `percentage(fraction)` | `"25%"` for `0.25` — a string, ready for an attribute or CSS variable. |
+
+**`quark:list`** — Arrays (an object counts as the list of its values). `"path"` arguments are dot paths into each item; comparisons are loose (`==`), like `find()`.
+
+| Name | Description |
+| --- | --- |
+| `count(list, "path"?, value?)` | The number of items; with a path, the items whose value at it is non-empty; with a value too, the items equal to it. `0` for a missing list. |
+| `find(list, "path", value)` | The first item whose value at the path equals `value`, else `undefined` (was a global built-in before 2026-09-13). |
+| `filter(list, "path", value?)` | The items whose value at the path equals `value` — or is non-empty when `value` is omitted. |
+| `reject(list, "path", value?)` | The complement of `filter`. |
+| `pluck(list, "path")` | The value at the path of every item. |
+| `sort-by(list, "path"?, "desc"?)` | A sorted copy: numbers numerically, everything else with a locale-aware, numeric-aware comparison; `null` last. `"desc"` reverses. |
+| `sum(list, "path"?)` | The total of the items (or of their value at the path); non-numbers count as 0. |
+| `range(end) / range(start, end, step?)` | `range(3)` → `[0, 1, 2]`; `range(1, 4)` → `[1, 2, 3]`; counts down when `start > end`. For skeleton rows and pagination. |
+| `unique(list, "path"?)` | A copy without duplicates (by the value at the path when given), first occurrence kept. |
+| `group-by(list, "path")` | A map from each distinct value at the path to the items carrying it. |
+| `first(list)` | The first item, or `undefined`. |
+| `last(list)` | The last item, or `undefined`. |
+| `reverse(list)` | A reversed copy (was a global built-in before 2026-09-13). |
+| `compact(list)` | A copy without `null`, `undefined`, `""`, empty lists and empty maps. |
+
+**`quark:map`** — Plain objects (`(key: value)` literals, provisions, `dataset`-shaped data). Never mutates; returns copies.
+
+| Name | Description |
+| --- | --- |
+| `get(map, "path", fallback?)` | The value at the dot path, or `fallback` when it is missing. |
+| `has-key(map, "path")` | Whether the dot path resolves to a value. |
+| `keys(map)` | The keys, in insertion order. |
+| `values(map)` | The values, in insertion order. |
+| `entries(map)` | `[(key: …, value: …), …]` — iterate a map with `item.key` / `item.value` in the rows. |
+| `merge(...maps)` | A shallow merge, later maps winning. |
+| `pick(map, ...keys)` | A copy holding only the named keys. |
+| `omit(map, ...keys)` | A copy without the named keys. |
+
+**`quark:string`** — Text. Values are stringified first; `null` / `undefined` read as `""`.
+
+| Name | Description |
+| --- | --- |
+| `plural(count, forms, locale?)` | The form for `count` from a map keyed by `Intl.PluralRules` category (`one`, `other`, `few`, …); `#` in the form is replaced by the count: `plural($n, (one: "# item", other: "# items"))`. |
+| `escape-html(value)` | `& < > " '` escaped, for text that goes through `dangerous-html()`. |
+| `truncate(value, max, suffix?)` | Cut to `max` characters including the suffix (default `…`). |
+| `capitalize(value)` | First character upper-cased. |
+| `slugify(value)` | Lower-case ASCII with dashes: `"Héllo World!"` → `"hello-world"`. |
+
+**`quark:date`** — Dates arrive as strings; these parse and format them. Every function accepts a `Date`, an ISO string or a timestamp and returns `null` / `""` for an unparseable value.
+
+| Name | Description |
+| --- | --- |
+| `parse(value)` | A `Date`, or `null` — for the allowed date methods (`toLocaleDateString()`, `toISOString()`). |
+| `is-valid(value)` | Whether the value parses as a date. |
+| `format(value, locale?, options?)` | `Intl.DateTimeFormat` output: `format($when, "en-GB", (dateStyle: "medium"))`. |
+| `add(value, amount, unit?)` | A new date `amount` units later (`"days"` by default; seconds … weeks, months, years — months and years step the calendar). |
+| `diff(later, earlier, unit?)` | Whole units between two dates (`"days"` by default), negative when `later` is earlier. |
+
+**`quark:url`** — Query strings, via `URLSearchParams`.
+
+| Name | Description |
+| --- | --- |
+| `query(map)` | `"q=a+b&page=2"` from a map; `null` / `""` values are dropped, lists repeat the key. |
+| `params(url)` | The query of a URL (or a bare query string) as a map; repeated keys become lists. |
+| `encode(value)` | `encodeURIComponent`. |
+
+**`quark:util`** — Small value helpers.
+
+| Name | Description |
+| --- | --- |
+| `coalesce(...values)` | The first value that is not `null` / `undefined` (`or` also skips `0`, `""` and `false`). |
+| `is-empty(value)` | `true` for `null`, `undefined`, `""`, an empty list or an empty map. |
+| `type-of(value)` | `"string"`, `"number"`, `"boolean"`, `"list"`, `"map"`, `"date"`, `"null"`, `"undefined"` or `"function"`. |
+| `to-json(value, indent?)` | `JSON.stringify`, for `content` or a `data-*` attribute. |
+| `from-json(text)` | `JSON.parse`, or `null` when the text is not JSON. |
+<!-- /generated -->
+
+Functions available without an import: [Built-in functions](./BUILTINS.md).

package/support/docs/NO_REVERSION.md

@@ -0,0 +1,18 @@
+# No reversion
+
+Quark rules do not undo their writes when they stop matching — the one deliberate divergence from CSS.
+
+## Write the inverse rule
+
+In CSS, a rule's declarations stop applying the moment its selector stops matching. **Quark rules do not revert** — this applies to every property kind: attributes, content, listeners, `$variables`, and CSS variables persist after the rule that set them stops matching. Write the counter-rule for every state you leave:
+
+```quark
+details[open] { --border-color: "red"; }
+details:not([open]) { --border-color: "transparent"; }
+```
+
+The same applies to `:has()` facts (`:scope:has(…)` + `:scope:not(:has(…))`, see [Selectors](./SELECTORS.md)) and to any attribute derived from a condition.
+
+## Why
+
+Quark does not own the document: anything can write an attribute outside a sheet's knowledge, so pretending a rule can be applied and unapplied like CSS would be dishonest. Unmatch reversion may be introduced in a future version.

package/support/docs/ON.md

@@ -0,0 +1,87 @@
+# @on
+
+`@on` wires listeners inside a rule: one or more event names, an options group that filters and configures the listener, and a block applied once per event.
+
+```quark
+form {
+  @on submit (prevent-default, handle: saveDraft($draft)) { is-submitted: ""; }
+  @on input, change (debounce: 300) { data-draft: event.target.value; }
+  @on keydown (key: "Escape", host: window) { is-open: none; }
+}
+```
+
+The prelude says *when*: which events, which filters. The block says *what*: writes, `@dispatch` / `@command`, `@delay`. JS callouts are the `handle:` option. There is no handler list after the event names any more (`@on click go;` is a parse error that points at `handle:`).
+
+## Events
+
+`@on click`, `@on super-form-success`, `@on "my:event"` — a bare name or a string. A comma list shares one listener and one block: `@on input, change { … }`. `event.type` tells them apart inside the block.
+
+## Blocks
+
+`@on <events> [(options)] { … }` turns the event into a **one-shot transaction**: the block is an ordinary rule body, evaluated when the event fires instead of when the rule matches. Declarations write the matched element; nested rules write its matching descendants; `event` is the DOM event; `@dispatch` / `@command` statements fire after the writes are queued. It is how typed input, clicks and element events become State without JS:
+
+```quark
+:scope {
+  $count: +attr("data-count");
+  [bind-count] { content: $count; }
+  @on counter-increment { data-count: $count + 1; }
+  @on input {
+    data-draft: event.target.value;
+    #preview { content: event.target.value or preserve; }
+  }
+  @on submit (prevent-default) { is-submitted: ""; }
+}
+```
+
+A nested rule whose selector starts with a sibling combinator writes the element's siblings instead of its descendants — `:scope { button { @on click { + provider-fetch { @command --fetch; } } } }` invokes `--fetch` on the `provider-fetch` right after the button.
+
+Writes are batched like any rule's; `$variables` set in a block persist on the element. `@on` inside a block is not supported.
+
+## Options
+
+The **options group** after the events is a map: `name: value` entries and bare flags, which mean `true`. With options the block is optional — `@on submit (prevent-default);` is a complete statement. These are the same filters `<event-handler>` offers, in the sheet:
+
+```quark
+ul {
+  @on click (target: "li[data-id]") { data-selected: target.getAttribute("data-id"); }
+  @on keydown (key: "Escape", host: window) { is-open: none; }
+  @on input (debounce: 300) { data-query: event.target.value; }
+  @on scroll (throttle: 100, passive, handle: trackScroll);
+  @on click (self, once, prevent-default);
+}
+```
+
+| Option | Effect |
+| --- | --- |
+| `target: "<selector>"` | Delegation: fires only when the event target is inside a descendant matching the selector; that element is `target` in the block and in the other options (`event.target` otherwise). With `host:` the selector is matched document-wide. |
+| `self` | Fires only when the event target is the matched element itself. |
+| `key: "Escape"` / `"Shift+K"` | Keyboard chord; space-separated tokens are alternatives (`"Escape Enter"`). Listed modifiers (`shift`, `alt`, `ctrl`, `meta` / `cmd`) must be held. |
+| `prevent-default` / `stop-propagation` / `stop-immediate-propagation` | Act on the event as soon as it passes the filters, before any timing. |
+| `debounce: <ms>` / `throttle: <ms>` | Wait for a pause / run at most once per window (leading edge). Exclusive. |
+| `handle: fn` | JS: a function, a call returning one, or a list `(a, b)` — each called with the event, `this` being the element, before the block. `prevent-default` and `stop-propagation` are also functions, for lists. |
+| `once` | Detach after the first event that passes the filters. |
+| `passive` / `capture` | Native `addEventListener` options. |
+| `host: window` / `host: document` | Register on the window / document while the element is in the document; the listener lets go on the first event after the element is removed. |
+
+### When values are evaluated
+
+`target`, `key`, `debounce`, `throttle` and `handle` are expressions evaluated **when the event fires**, in the block's scope: `event`, `target`, `element` and the element's current `$bindings` are all in reach.
+
+```quark
+#list {
+  $row: attr("data-row-selector");
+  @on click (target: $row, handle: pick(target.getAttribute("data-id"), event)) { … }
+}
+```
+
+So nothing about a listener is reactive — a changed `$row` is read by the next click, and no re-run ever re-registers the DOM listener. The flags, `once` and `host` configure the registration and are read once per match; they must be bare words.
+
+Two `@on`s for one event may coexist when their options differ (`(key: "Escape")` and `(key: "Enter")`).
+
+## Outgoing events
+
+`@dispatch` and `@command` inside the block send events and commands from it — see [`@dispatch` / `@command`](./DISPATCH.md).
+
+## No `@off`
+
+There is no `@off`: a listener you would remove is a listener that should not fire — gate it with options or with event data inside its block. Listeners persist like any other write (see [No reversion](./NO_REVERSION.md)).

package/support/docs/REACTIVITY.md

@@ -0,0 +1,24 @@
+# Reactivity
+
+A rule runs when an element matches it and re-runs when something its selector or its values depend on changes — nothing more, nothing less.
+
+## When a rule re-runs
+
+- an attribute, class (`.x`) or id (`#x`) named in its selector changing on the matched element, on an ancestor or earlier sibling on the selector's path, or on a descendant named in `:has()` (a class change counts only when it adds or removes a class the sheet names, unless a rule needs the whole value: `[class~="x"]`, `attr("class")`);
+- a literal `attr("x")` in one of its values, when `x` changes on the matched element;
+- a `$binding` one of its values reads, when that binding changes on an ancestor-or-self owner (the nearest owner wins, so a farther change is ignored);
+- a literal `prop("x")` in one of its values, when JS assigns `element.x`;
+- elements being inserted anywhere under the host, whether by Quark, an element, or app JS (a `childList` MutationObserver): rules matching the new elements run, `content` rules below the insertion point re-run, and `:has()` / `:empty` candidates above it are re-checked;
+- elements being removed, only while some rule's match depends on children or sibling position (`:has()`, `:empty`, `:nth-child()`, `a + b`): the same re-runs as an insertion at that parent. Text-only changes are never observed.
+
+## Not observed
+
+Interaction and validity pseudo-classes (`:hover`, `:focus`, `:checked`, `:invalid`, … — warned at build), pseudo-elements, `attr($dynamic)` / `prop($dynamic)`, `closest()` and DOM method reads (`getAttribute`, `matches`), in-place mutation of an object a `prop()` or `$binding` holds, and browser-driven native state that does not go through a JS setter (typing into an `<input>`, `<details>` toggling). Select on reflected attributes or listen to events for those. The reverse direction is covered: `value` / `checked` / `selected` / textarea `content` writes also set the live property on native form controls (see [Attributes](./ATTRIBUTES.md)).
+
+## Loops
+
+A declaration is never re-run by the attribute it wrote (the mutation that woke the rule is excluded from that pass), so a rule cannot loop on its own gate. `class:` is the exception: classes are separate facts, so `.is-done { class: (is-struck: true); }` applies when `is-done` arrives. Setting attributes is recommended over toggling / mutating classes and ids, since the latter has a heavier impact on Quark's performance. Cycles through two or more attributes or classes, `$bindings` across sheets, content that re-matches its own paint, element effects or events are cut by the shared [loop guard](./LOOP_GUARD.md): every write carries the depth of the chain that caused it — a deferred paint keeps the depth of the run that scheduled it; an observer record, an `attributeChangedCallback` or a property-change event inherits the depth stamped on the address it reacts to — and the hop past `LoopGuard.limit` (50) is dropped, logged once and published as `quark/error`. Chains restart at zero on every external write in a later task, so a stream of provider updates never trips. Rules that gate on attributes they write for each other are warned about when the sheet builds (`Quark: rules gate on attributes they write for each other — …`).
+
+## Timing
+
+Listeners and `$variables` apply synchronously; attributes, CSS variables and content are painted in a batch one task later, and the rules that depend on those writes run in the next cycle. Writes more than a tick apart are separate facts.

package/support/docs/README.md

@@ -0,0 +1,143 @@
+# quark
+
+CSS-like orchestration for your HTML — bind attributes, render lists, and wire events without a component tree.
+
+Quark is a derivative of CSS with CSS-compatible syntax (a CSS parser can tokenize Quark). The language is familiar. Rule properties are HTML attributes. The utilities (at-rules, util functions) are new.
+
+Prefer `<quark-sheet>` for apps; use the `Quark` class when you need a programmatic host (tests, tooling).
+
+## Features
+
+- **CSS-like sheets** Selectors + nested rules that mutate the live DOM
+- **`$variables`** Scoped values that nest and resolve in expressions
+- **JS writes** `element.quark.setProperty()` writes a `$variable` from JavaScript, on any element
+- **CSS variables** Write `--custom-props` from state; style via `var()`
+- **Content rendering** `content`, `template()`, `iterate()`, `dangerous-html()`
+- **Element properties** `prop("provision")` reads Neutron provisions / any JS property, re-running on assignment
+- **Events** `@on` at-rules with delegation, key, timing and host options, plus `prevent-default` / `stop-propagation`
+- **View transitions** `@view-transition` commits a block's writes inside `document.startViewTransition()`, so CSS animates list changes, removals included
+- **Delayed writes** `@delay 2000 { … }` applies a block after a pause — flashes, toasts, undo windows — dropped if the rule stopped matching
+- **Diagnostics** `@warn` / `@debug` / `@error` report from a rule; the selector is the condition
+- **Built-in modules** `@use "quark:math"`, `quark:list`, `quark:map`, `quark:string`, `quark:date`, `quark:url`, `quark:util` — pure helpers, imported like JS modules
+- **Attribute helpers** `dataset`, `ariaset`, `class`, `none` to clear
+- **JS modules** Call app helpers from expressions via `@use "/url"`
+- **Scoped host** Sheet + targets share a parent; updates follow DOM mutations
+- **DevTools** `Quark.attachDevtools()` reports rule applications and `$variables` to the Nucleus DevTools extension
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+App authors almost always load Quark through `<quark-sheet>`:
+
+```html
+<section>
+  <quark-sheet>
+    details[open] [bind-status] {
+      content: "Open";
+    }
+    details:not([open]) [bind-status] {
+      content: "Closed";
+    }
+  </quark-sheet>
+  <details>
+    <summary>Panel</summary>
+    <span bind-status></span>
+  </details>
+</section>
+```
+
+Programmatic API (tests / custom hosts):
+
+```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();
+```
+
+### Documentation
+
+Syntax
+
+- [Sheets & scoping](./SHEETS.md) — `<quark-sheet>`, `@scope`, `is-global`, what runs
+- [Syntax](./SYNTAX.md) — rules, declarations, literals, operators, `if()`
+
+Selectors
+
+- [Selectors](./SELECTORS.md) — combinators and pseudo-classes, what is observed
+- [Reactivity](./REACTIVITY.md) — when a rule re-runs, loops, timing
+- [No reversion](./NO_REVERSION.md) — write the inverse rule
+
+Declarations
+
+- [Declaration kinds](./DECLARATIONS.md) — what a key does
+- [Attributes](./ATTRIBUTES.md) — attributes, `class` / `dataset` / `ariaset`, form controls
+- [Content](./CONTENT.md) — `content`, `template()`, `iterate()`, `dangerous-html()`
+- [CSS variables](./CSS_VARIABLES.md) — `--custom-props`
+
+Values & expressions
+
+- [Variables](./VARIABLES.md) — `$variables`, cascade, `unset`, raising state
+- [Writing from JS](./JS_WRITES.md) — `element.quark.setProperty()`
+- [Values & keywords](./VALUES.md) — `none` / `preserve` / `unset`, wipes and no-ops
+- [Expressions](./EXPRESSIONS.md) — name resolution, operators, `if()`, lists and maps
+- [Built-in functions](./BUILTINS.md) — `attr()`, `prop()`, `iterate()`, `event`, …
+- [Allowed methods](./METHODS.md) — `.toFixed()`, `.join()`, …
+- [Built-in modules](./MODULES.md) — `@use "quark:math"`, `quark:list`, `quark:map`, `quark:string`, `quark:date`, `quark:url`, `quark:util`
+- [Element properties](./ELEMENT_PROPERTIES.md) — `prop("provision")`, `element`
+
+At-rules
+
+- [At-rules](./AT_RULES.md) — the ones that run
+- [`@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 from a rule
+
+Runtime
+
+- [JS API](./JS_API.md) — `Quark`, `whenSettled()`, DevTools
+- [Loop guard](./LOOP_GUARD.md) — runaway chains are cut
+- [Limitations](./LIMITATIONS.md) — beta limits and pitfalls
+
+The grammar (EBNF, precedence, AST) is the `quark-parser` package's *Language reference*.
+
+### Examples
+
+#### React to element state
+
+Native element state drives content — no JS, no listeners:
+
+<include-content data-demo="toggle-content"></include-content>
+
+#### List from a provider
+
+`prop("provision")` pulls the fetch payload; `iterate()` renders a row per item and re-renders on every provision:
+
+<include-content data-demo="provider-list"></include-content>
+
+#### Call a module helper
+
+```html
+<quark-sheet>
+  @use "/helpers.js" as *;
+
+  #out { content: formatPrice($amount); }
+</quark-sheet>
+```
+
+#### Count clicks from JS
+
+The sheet hands the owner element to a JS helper; each click calls `owner.quark.setProperty("$count", …)` and every rule reading `$count` below the owner re-runs. See [Writing from JS](./JS_WRITES.md).
+
+<include-content data-demo="js-api"></include-content>

package/support/docs/SELECTORS.md

@@ -0,0 +1,87 @@
+# Selectors
+
+Quark rides the native selector engine: whatever `querySelectorAll` matches, a rule matches. What Quark adds is observation — knowing which changes can flip a match and where the subjects are afterwards.
+
+## What is observed
+
+Attributes, classes and ids named anywhere in a selector are observed on the element they sit on: the matched element, an ancestor or earlier sibling on the selector's path, or a descendant named in `:has()`. Structure is observed too: elements inserted or removed under the host re-check the rules whose match depends on children or sibling position. *Generated.*
+
+<!-- generated:selectors -->
+**Combinators**
+
+| Combinator | Observed |
+| --- | --- |
+| `a b` | Descendant. An attribute change on `a` re-runs the rule for the matching `b`s below it. |
+| `a > b` | Child. Same observation as the descendant combinator. |
+| `a + b` | Next sibling. An attribute change on `a` re-runs the rule from the parent; elements inserted or removed under that parent re-run it too. |
+| `a ~ b` | Subsequent siblings. Same observation as `+`. |
+
+**Logical**
+
+| Pseudo-class | Observed |
+| --- | --- |
+| `:is(…)` | Attributes anywhere in the argument list are observed like the compound's own. A complex argument (`:is(section[x] li)`) re-runs the rule from the changed element down. |
+| `:where(…)` | Same as `:is()` (Quark has no specificity). |
+| `:not(…)` | Same observation as `:is()`. |
+
+**Relational**
+
+| Pseudo-class | Observed |
+| --- | --- |
+| `:has(…)` | Attributes named in the argument are observed on descendants, and elements inserted or removed below a candidate re-check it: the rule re-runs for every matching ancestor of the change. Sibling-relative arguments (`:has(+ …)`, `:has(~ …)`) and a `:has()` nested in a complex `:is()` / `:not()` argument re-run the whole rule from the host instead. Without rule reversion, pair it with the inverse `:not(:has(…))` rule. |
+
+**Structural (sibling position, children)**
+
+| Pseudo-class | Observed |
+| --- | --- |
+| `:first-child` | Sibling position: re-runs when elements are inserted or removed under the parent. |
+| `:last-child` | Same as `:first-child`. |
+| `:only-child` | Same as `:first-child`. |
+| `:nth-child(An+B [of S])` | Same as `:first-child`. With `of S`, attributes in `S` are observed on the siblings and each change re-runs the rule from the parent. |
+| `:nth-last-child(An+B [of S])` | Same as `:nth-child()`. |
+| `:first-of-type` | Same as `:first-child`. |
+| `:last-of-type` | Same as `:first-child`. |
+| `:only-of-type` | Same as `:first-child`. |
+| `:nth-of-type(An+B)` | Same as `:first-child`. |
+| `:nth-last-of-type(An+B)` | Same as `:first-child`. |
+| `:empty` | Re-checked when elements are inserted or removed below the element. Text-only changes are not observed. |
+
+**Attribute-backed**
+
+| Pseudo-class | Observed |
+| --- | --- |
+| `:disabled` | Observes `disabled` on the element and on ancestors (a disabled `<fieldset>`). |
+| `:enabled` | Same as `:disabled`. |
+| `:required` | Observes `required`. |
+| `:optional` | Same as `:required`. |
+| `:read-only` | Observes `readonly`, `disabled` and `contenteditable` on the element and its ancestors. |
+| `:read-write` | Same as `:read-only`. |
+| `:any-link` | Observes `href`. |
+| `:lang(…)` | Observes `lang` on the element and its ancestors. |
+| `:open` | Observes the `open` attribute (`<details>`, `<dialog>`). A `<select>` / `<input>` picker opening is not observed. |
+
+**Static**
+
+| Pseudo-class | Observed |
+| --- | --- |
+| `:scope` | The host; never changes. |
+| `:root` | The document element; never changes. |
+
+**Not observed** — `:hover`, `:focus`, `:focus-within`, `:focus-visible`, `:active`, `:visited`, `:link`, `:target`, `:checked`, `:indeterminate`, `:default`, `:valid`, `:invalid`, `:in-range`, `:out-of-range`, `:placeholder-shown`, `:popover-open`, `:modal`, `:fullscreen`, `:defined`, `:dir(…)`: Interaction or browser state with no attribute behind it: matches on the first run only (warned at build). Select on reflected attributes instead. Any pseudo-class not listed above is treated the same way.
+<!-- /generated -->
+
+## `:has()`
+
+`:has()` costs a native subtree scan per candidate on every fan-out that includes the rule, plus one ancestor walk per observed change — keep its arguments shallow and off rules that match many rows. Without rule reversion a `:has()` rule needs its inverse (`:not(:has(…))`) like any other state:
+
+```quark
+/* an aggregate over the rows becomes a fact on the host */
+:scope:has(li[data-is-selected]) { data-has-selection: ""; }
+:scope:not(:has(li[data-is-selected])) { data-has-selection: none; }
+```
+
+## Classes and ids
+
+Class (`.x`) and id (`#x`) selectors are observed like attributes (a class change counts only when it adds or removes a class the sheet names). Setting attributes is still 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 (styling churn included).
+
+When a rule re-runs, and what stays unobserved: [Reactivity](./REACTIVITY.md).

package/support/docs/SHEETS.md

@@ -0,0 +1,67 @@
+# Sheets & scoping
+
+A sheet lives next to the elements it orchestrates; its rules reach the host's subtree and nothing else, exactly like an inline `<style>` with `@scope`.
+
+## Loading a sheet
+
+App authors almost always load Quark through `<quark-sheet>`:
+
+```html
+<section>
+  <quark-sheet>
+    details[open] [bind-status] {
+      content: "Open";
+    }
+    details:not([open]) [bind-status] {
+      content: "Closed";
+    }
+  </quark-sheet>
+  <details>
+    <summary>Panel</summary>
+    <span bind-status></span>
+  </details>
+</section>
+```
+
+Sheets can also be fetched (`<quark-sheet src-url="/views/app.quark">`) or constructed programmatically — see [JS API](./JS_API.md).
+
+## Scoping
+
+By default (`<quark-sheet>` without `is-global`, or the `isScoped` constructor option), sheets are implicitly wrapped in `@scope { … }`, anchored at the host (the sheet's parent element) — the same model and semantics as CSS inline-`<style>` scoping. Global sheets (`<quark-sheet is-global>`) skip the wrap: top-level rules run in the root context — e.g. to read a provider that is an ancestor of the host — and rules the author nests in an explicit `@scope { }` block stay host-scoped. Every part of a selector matches strict descendants of the host: an ancestor compound (e.g. the `provider-fetch[is-success]` in `provider-fetch[is-success] h4`) is only satisfied by an element *inside* the host, never by the host itself or anything above it. The host is reachable only via the explicit `:scope` selector:
+
+```quark
+:scope { data-app: "ready"; }             /* mutate the host itself */
+:scope[data-mode="on"] [bind-x] { … }     /* react to host state */
+```
+
+Registered hosts carry a generated `q-scope="<id>"` attribute — Quark's scoping anchor. Treat it as internal: don't set, copy, or select on it.
+
+## What runs
+
+A sheet is minified (comments stripped, whitespace collapsed), optionally wrapped in `@scope { … }` (see above), and parsed. The runtime then executes:
+
+- **Rules**, nested to any depth. A nested selector is joined to its parent as a descendant, or spliced over each `&`.
+- **Declarations inside rules**, by key shape (see [Declaration kinds](./DECLARATIONS.md)).
+- **`@use "url" [as name | as *]`** anywhere in the sheet. The namespace defaults to the URL's last path segment without its extension (`/api-client.js` → `api-client`); `as *` merges exports into the bare scope, last import winning on clashes. A `with (…)` clause is a parse error.
+- **`@scope { … }`**, which takes no prelude: rules inside stay anchored to the host in a global sheet.
+- **`@on <event> [(options)] …;`** inside rules: listeners (see [`@on`](./ON.md)).
+- **`@view-transition [(options)] { … }`** inside rules, around rules or inside `@on` blocks: the writes inside it commit inside a view transition (see [`@view-transition`](./VIEW_TRANSITION.md)).
+- **`@delay <ms> { … }`** inside rules and blocks: the block applies once, after the pause, if the rule still matches (see [`@delay`](./DELAY.md)).
+- **`@warn` / `@debug` / `@error <expression>;`** inside rules and blocks: report on the matched element (see [Diagnostics](./DIAGNOSTICS.md)).
+
+That list is the language: any other at-rule, a nested property block, a `%placeholder` selector, `#{…}` outside a string, and `!important` / `!default` / `!global` are parse errors, and a sheet that fails to parse does not run (`<quark-sheet>` sets `is-error`). Top-level declarations parse but have no element to write.
+
+```quark
+@use "/helpers.js" as *;
+main {
+  $items: prop("provision").body;
+  ul {
+    content: iterate($items);
+    li { data-id: item.id; &[data-id="0"] { is-first: ""; } }
+  }
+}
+```
+
+## Load order
+
+Imports (`@use`) and `src-url` sheets resolve before the first rule run, so a sheet that registers late misses events fired meanwhile — react to state attributes (`is-*`) rather than one-shot events, and put the sheet first in its host when it must hear boot-time events.