# The Nucleus Stack

Rich HTML apps - implementing the novel [ASO architectural pattern](./adapter_state_orchestrator.md).

Live demo: fully RESTful Todo app - under 50 lines of code, zero app JS, no build process.

[Open the Todo App example app](./examples/todo-app/todo-app.html) — source: [HTML](./examples/todo-app/todo-app.html) · [Quark](./examples/todo-app/todo-app.quark) · [CSS](./examples/todo-app/todo-app.css)

Your HTML __*is*__ the app! Drop-in custom elements that each have a single responsibility, then author CSS-derived rules that observe the page and react accordingly. The source of truth - your HTML - is what the browser paints.

<p class="red-u">No components, no virtual DOM, no second copy of application state tucked away in JS memory, and no build process.</p>

## How it's different from existing UI solutions

- **Back to the future 🚗⚡️** Welcome back to building static HTML5 apps. A break from complex JavaScript apps that compile to HTML.
- **Little to no JavaScript** You no longer need to write JS for the vast majority of UI cases. You may still call-out to your own pure functions for complex cases.
- **Native++** It's real HTML. With a separate, synergistic guest: Quark.
- **No magic** No special frameworks, build processes, rendering wizardry, or "HTML-in-my-JS" / "JS-in-my-HTML" DSLs.
- **Progressively enhanced** Drop into existing static/server-side-rendered sites. Nucleus elements and Quark can also be used independently.
- **Fully composable** Templates, templating, behavior, and custom logic are all decoupled & robust.
- **Reactive State Machine** A simple, reliable, declarative syntax for your business logic - Quark.
- **No reconciliation tax** No large memory copies of state/DOM to be rebuilt, diffed against the DOM, recompiled with every state change.
- **Lightweight** All Nucleus elements + Quark + Neutron have a smaller footprint (just over ~50kb compressed) than some UI framework cores alone.

To see it running in a production-grade app, see [Wrenfield](https://wrenfield.excom.dev) - a fictional, full-featured ecommerce site with SSG, SPA, web AR/3d models, WebAuthn, View Transitions, touch gestures, and more. Try it on mobile to get a native-like experience. Wrenfield was built with no app JS and no UI build process.

## What's in the stack

- **NucleusKit elements** A growing catalog of drop-in custom elements, including: drawers, tabs, tables, lazy views, forms, routing, passkeys, data fetching, and more.
- **Quark** Like CSS, for document mutation. Select elements, bind data, stamp lists, wire events, and drive state transitions with simple rules instead of imperative code.
- **Valence.css** Semantic, classless CSS that caters to both native and custom elements, with themes, light/dark schemes, and design tokens. Designed for easy drop-in. Optional.
- **Neutron** The small JS factory used to author the elements above. Reach for it only when the NucleusKit catalog lacks what you need. Optional.

Every piece stands alone. Use one element on an existing site, or compose the whole stack into a full single-page app. `nucleus-kit` bundles it all behind one import; if you find you only use a handful of elements, install those packages à la carte instead (`@excom/content-drawer`, `@excom/quark-sheet`, …) and skip the rest.

## Why teams pick it

- **Significantly less app code** This is possible for two primary reasons. First, because NucleusKit elements are fully composable, configurable, and controllable, they will likely be compatible with the desired experience of most applications that use them; there is a low likelihood you will need to build your own. Secondly, Quark enables the majority of customization without needing to invite JavaScript.
- **No components** There is no "component" concept in this architecture. This allows application pieces to be maximally reusable and composable, as there is no home to entrap logic with a tightly coupled view.
- **One source of truth** Live markup _is_ the primary application state, so an entire family of bugs ("the UI disagrees with the model") cannot exist.
- **Fully inspectable** Open devtools and the entire application is in front of you: every value, every binding, and every transition. The state is the document/DOM, so all is plainly transparent to see, alter, and debug in your inspector.
- **Accessible by default** Declarative & ARIA state is the state... not a mirror someone forgot to update.
- **Human and machine friendly** Inspect this site to see its declarativeness. No more `<div>` soups bound to untraceable JavaScript. Custom elements make for a beautifully declarative document. A page that is legible, addressable, and serializable is an ideal target for code generation, AI-assisted editing, and confident human auditing. Tools reason about the screen's exact state instead of inferring a component tree. Likewise, writing and debugging UI code by hand has never felt simpler.
- **Declarative business behavior** The vast majority of your proprietary behaviors exist as a simple configurations, rather than buried inside imperative spaghetti code.

## Where it shines

Content-rich sites, complex data-driven business rules, progressive enhancement of static/server-rendered pages, embedded user experiences. See [Limitations](./limitations.md) for the edges.

The Nucleus Stack also opens up new possibilities that were not easily served by any UI technology before:
- zero-build-tool UIs (e.g. on-the-fly generation)
- declarative & auditable target for LLM UI building
- programmatic assembly of rich UX (like a CMS)
- incremental upgrading of static/legacy SSR sites
- resource-constrained, secure, or sandboxed web UIs (especially where scripting needs to be validated or limited, like an ATM)
- embedded UX (such as upgrading markdown with embedded functionality)

## Dogfood is nutritious

This entire site - including the complex bits, like the text editors - was built entirely using this UI stack alone. Due to the declarative design of these technologies, inspecting the document will give you a very strong understanding of the application's composition and features. Open your inspector! Installing [Nucleus DevTools](../nucleus-devtools.md) will also provide even stronger insight.

The Nucleus Stack is currently being used in production by partnering companies.

## Free & open source

The Nucleus Stack is MIT licensed and will remain free and open source, with long-term support. This is made possible by its contributors and sponsors.

<section class="sponsors">
  <a role="button" href="https://github.com/sponsors/excom-dev">Become a sponsor</a>
  <ul>
    <li>
      <small>Your logo here - <a href="https://github.com/sponsors/excom-dev">be the first sponsor</a></small>
    </li>
  </ul>
</section>

[Code contribution is welcome](./contributing.md).

## Start here

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Quick Start

One HTML file is enough. No install, no build, no framework.

What follows is our [Todo App example](./examples/todo-app/todo-app.html), verbatim, with one deliberate change — it reads from the public [JSONPlaceholder](https://jsonplaceholder.typicode.com) API and sorts the list with a built-in module. Open the example to edit any of it live.

## 1. Load NucleusKit

`nucleus-kit` packages the elements, Quark, and Valence.css behind a single import.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My first Nucleus app</title>
    <link rel="stylesheet" href="https://unpkg.com/@excom/nucleus-kit/dist/basic.min.css">
    <script src="https://unpkg.com/@excom/nucleus-kit/dist/index.umd.min.js"></script>
  </head>
  <body>
    <main></main>
  </body>
</html>
```

Want a package manager instead? `npm install @excom/nucleus-kit`, then `import "@excom/nucleus-kit"` and `@import "@excom/nucleus-kit/basic.css"`. Every element is also published independently — any package page covers the slim install.

## 2. The markup

Drop this `<article>` into the `<main>`, and save the two files beside it. It is the whole app: a provider that fetches, a `<template>` describing one row, and a form per action. No ids, no classes, nothing dynamic — every fact arrives later, as an attribute.

```html
<article>
  <link rel="stylesheet" href="/todo-app.css">
  <quark-sheet src-url="/todo-app.quark"></quark-sheet>
  <provider-fetch api-url="https://jsonplaceholder.typicode.com/todos?_limit=5">
    <ul>
      <template>
        <li>
          <super-form>
            <form method="patch">
              <input type="checkbox" name="completed">
              <input name="title" required autocomplete="off">
            </form>
          </super-form>
          <super-form>
            <form method="delete">
              <button type="submit"></button>
            </form>
          </super-form>
        </li>
      </template>
    </ul>
    <super-form>
      <form action="https://jsonplaceholder.typicode.com/todos" method="post">
        <input name="title" required autocomplete="off" placeholder="New Reminder">
        <button type="submit"></button>
      </form>
    </super-form>
  </provider-fetch>
</article>
```

[`provider-fetch`](../provider-fetch.md) does the reading and publishes the response for the sheet to pick up. [`super-form`](../super-form.md) wraps a `<form>` you write yourself and submits it over `fetch`, so `method="patch"` and `method="delete"` work where the browser only offers GET and POST.

JSONPlaceholder returns `{ userId, id, title, completed }` — the same field names the example already binds, so `title` and `completed` are untouched. Only the URLs changed: `/api/todos` became the JSONPlaceholder URL, and `?_limit=5` keeps the list to five rows.

## 3. The rules

A `<quark-sheet>` observes its parent and applies rules to everything inside it. Read it like CSS: *when the provider succeeds, take its body, stamp one `<li>` per todo, and fill each row from the item.*

```quark
@use "quark:list" as list;

provider-fetch[is-success] {
  $todos: prop("provision").body;
  ul {
    content: iterate(list.sort-by($todos, "title"), none, "id");
    form {
      action: "https://jsonplaceholder.typicode.com/todos/#{item.id}";
    }
  }
  input[name="completed"] {
    checked: item.completed;
  }
  input[name="title"] {
    value: item.title or "";
  }
  super-form:has([name="completed"]) {
    /* Submits form when inputs change. Uses native Command. */
    @on change { @command --submit; }
  }
  /* Re-fetches todos after successful form submission. */
  @on super-form-success { @command --fetch; }
}
```

Nine declarations carry the entire app. `iterate()` is keyed on `"id"`, so a re-read reuses the rows it already has. Every row's `action` is written from its own item, which is why one `<template>` serves every todo. The two `@on` blocks close the loop: a changed field submits its form, and any form that succeeds tells the provider to read the list again.

### Calling a module

The one deviation from the example app is `list.sort-by($todos, "title")`. `@use "quark:list" as list;` imports one of Quark's [built-in modules](/packages/quark/modules), with no file and no fetch, and namespaces its functions under `list`; `sort-by` returns a sorted copy for Quark to render.

Your own module loads the same way (`@use "./utils.js" as utils;`) and should hold the same kind of function: one that receives values as arguments, returns a value for Quark to write, and has no idea a document exists. Querying the DOM and writing to it is the Orchestrator's job, and Quark is already doing it. Reach for a module of your own only when the built-in modules fall short. [Business Logic](./business_logic.md) covers where that line sits and why calculations belong on this side of it.

## 4. The styling

Trimmed to what you need to see it work — the [example](./examples/todo-app/todo-app.html) carries the full file. The first two rules are the interesting ones: CSS selects on the same facts Quark writes, so an error message and a struck-through title need no extra state.

```css
@scope {
  /* data-driven css */
  provider-fetch[is-error] ul::before {
    display: block;
    padding: 0.6rem 1rem;
    color: var(--v-del-color);
    font-size: 0.875rem;
    content: "Could not load todos.";
  }
  li:has(:checked) input[name="title"] {
    color: var(--v-muted-color);
    text-decoration: line-through;
  }

  /* add cosmetic styling here */
}
```

## 5. What you will see

JSONPlaceholder **fakes every write**. A POST, PATCH or DELETE answers as if it worked — POST returns the new todo with `id: 201`, PATCH echoes the merged object, DELETE returns `{}` — but nothing is stored. Since this app re-reads the list after every successful write, the server's unchanged answer wins:

- **Check-off a todo** and it PATCHes, re-reads, and snaps back to whatever JSONPlaceholder still says.
- **Add a todo** and it POSTs, re-reads, and the new row disappears.
- **Delete a todo** and it DELETEs, re-reads, and the row returns.

That is the API being honest about being a fixture, not the app being broken. Point `api-url` and the two `action` URLs at a real endpoint and every one of those actions sticks, with no other change.

## What to try

- Tick a todo, then watch the network panel: one PATCH, one GET, and the row restored.
- Add "Write tests" and watch it vanish on the re-read.
- Reverse the order with `list.sort-by($todos, "title", "desc")`.
- Drop `?_limit=5` to render all 200 rows, and note that nothing else has to change.

## What just happened

- **Elements** owned their own behavior and reported state through attributes such as `is-success`.
- **The document** held every fact the app knows.
- **Quark** observed that state and cascadingly updated it in response.

That loop is the entire architecture. [Core Concepts](./core_concepts.md) walks through it in one sitting.

## Next steps

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Core Concepts

The Nucleus Stack implements an application architecture named **ASO: Adapter, State, Orchestrator**. Three roles.

## The driving idea

**The live HTML document is the application's state.** Not a rendering of that state, and not a projection of it. Facts live in the document, and the document is also what the user sees. There is no separate memory model to keep aligned, because a second copy does not exist.

Everything else follows from that.

## The three roles

### Adapters

An Adapter is an element that bridges the State and one protocol outside it — a server, a sensor, a store, or the person using the page. It carries that protocol's state as attributes on itself, announces what happens through events, and leaves all coordination to the Orchestrator.

```html
<provider-fetch api-url="/api/user"></provider-fetch>
```

`provider-fetch` bridges the network. Lifecycle shows up as attributes (`is-loading`, `is-success`, `is-error`); the response is published as data; events fire. It does not decide what happens next. It knows about nothing else.

Some native elements are Adapters as well. `<input>` bridges the keyboard: it owns its pseudoclasses like `:valid` and fires events like `change`. `<form>` bridges submission: it validates and fires `submit`. Nucleus Stack Adapters, through the Custom Element API, simply extend that same contract to protocols the platform does not cover yet.

### State

The State is the document: every element, attribute, and text node, plus the rich data some Adapters publish on themselves. Three properties let it function as state:

- **Structured** — nesting carries meaning. Rules scope themselves by ancestry.
- **Addressable** — any part can be named with a selector.
- **Serializable** — the whole thing can be written out, inspected, and shipped fully formed.

Anything you would put in a store belongs on an element instead: `<main data-mode="edit">`, `<li data-done>`, `<dialog open>`.

### Orchestrator

The Orchestrator watches the State and writes the State. In this stack that role is **Quark**, a CSS-derived language of rules:

```quark
main[data-mode="edit"] [bind-toolbar] { content: template("#edit-tools"); }
main:not([data-mode="edit"]) [bind-toolbar] { content: none; }
```

A rule names a condition (a selector) and the writes to perform while that condition holds (attributes, content, listeners, variables). The Orchestrator stores no state of its own. Whatever it knows, it reads from the DOM; whatever it decides, it writes back.

## The loop

1. An Adapter does its job — something happens on its protocol — and reflects the result on itself as an attribute or event.
2. The Orchestrator notices the change and applies matching rules, writing into other parts of the document.
3. Those writes drive other Adapters, which act on their protocols and reflect results. Those writes can also notify other relevant Orchestrator rules.
4. Repeat until the document settles.

Nothing directly calls anything else. Adapters hold no references to one another. The Orchestrator holds no references to Adapters. Coordination happens entirely through what is visible in the document.

## No components

This stack has no component concept. Like the native platform, elements are generic Lego pieces, not custom bricks: they have no intrinsic knowledge of any other elements outside of their own family, so you compose them the way you compose native HTML.

When you need a reusable chunk of UI with its own behavior, you write a **view**: an HTML fragment that optionally carries its own CSS and Quark sheet, loaded where you need it by `include-content` or `spa-route`. Views belong to you. Elements stay generic.

## Where the JavaScript goes

Most pages need none. When a calculation outgrows Quark expressions, the sheet imports a module and calls its functions:

```quark
@use "/pricing.js" as pricing;
[bind-total] { content: pricing.total($items, $tax-rate); }
```

A module should be pure business logic: it takes values and returns a value. It is also the exit for anything Quark cannot yet declare. Bridging a protocol, such as the network, storage, the clock or a person, belongs to an Adapter. Quark leans that way on purpose: it calls module functions synchronously and does not await what they return, so a fetch inside a module is deliberately awkward. A function may build and return a node it owns, such as a chart; it should still leave the document around it alone.

## Quick reference

| You want to… | Reach for |
| --- | --- |
| Bridge a protocol — a browser API, a store, a person's interaction (tabs, drawers) — configurably | A **NucleusKit element** |
| React to state, bind data, render lists, wire an event | A **Quark rule** |
| Compute or format a value | A **pure function** via `@use` |
| Style something | **CSS / Valence.css**, keyed to state attributes |
| Package a chunk of UI | A **view** (HTML + CSS + Quark) |

## Next steps

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Using NucleusKit Elements

Every NucleusKit element obeys the same contract: it is an [Adapter](./adapter_state_orchestrator.md), bridging one protocol and the document. Learn that contract once and any package page becomes readable in a minute.

## The contract

**Attributes in.** Options are attributes. Booleans are presence attributes. Names always contain a dash, so they never collide with native attributes.

```html
<include-content lazy-load template-ref="/views/profile.html"></include-content>
```

**Attributes out.** Primitive lifecycle and status appear as *state* attributes: `is-loading`, `is-success`, `is-error`, `is-active`, `has-rendered`, `did-fail`. Those are the attributes CSS and Quark select on.

```css
provider-fetch[is-loading] { opacity: 0.5; }
```

**Events out.** Custom events carry the tag name as a prefix (`super-form-success`, `spa-route-render`) so they never shadow native ones. Most bubble, which means a single listener higher in the tree can hear an entire subtree.

**Data out.** Providers — and a few others — publish a rich payload as a *provision*: the parsed response, route params, a geolocation reading. Quark reads it with `prop("provision")`:

```quark
provider-fetch[is-success] { $user: prop("provision").body; }
```

**Default actions.** Some events are cancelable. Call `preventDefault()` from a handler and the element skips whatever it would have done next. That is the escape hatch for the uncommon "almost, but not quite" case.

**Recognized elements.** Elements never invent opinionated children; they may recognize the children *you* write. `super-form` expects your `<form>`. `content-tabs` expects your `content-tabs-header` and `content-tabs-body`. Package pages list exactly what each element looks for.

## Reading a package page

| Section | What it tells you |
| --- | --- |
| Subtitle + demo | The one job, shown in the fewest possible lines |
| Features | The use cases it covers, in plain terms |
| Attributes | `option` (you set it) vs `state` (the element sets it), types, defaults, allowed values |
| Fires / Listens for | Every event, when it fires, and the shape of `event.detail` |
| Default actions | What `preventDefault()` will skip |
| Recognized elements | The descendants it wires up automatically |
| CSS | Classes, variables, and aliases you can hook into or opt-out of |

## Naming tells you the shape

NucleusKit elements follow the recommended naming conventions.

| Prefix | Meaning | Examples |
| --- | --- | --- |
| `super-*` | Wraps and upgrades a native element you still write yourself | `super-form`, `super-input` |
| `content-*` | Expects children and manages their presentation | `content-tabs`, `content-drawer`, `content-carousel` |
| `provider-*` | Publishes data for the page to consume | `provider-fetch`, `provider-geolocation`, `provider-orientation` |
| `spa-*` | Routing and navigation | `spa-manager`, `spa-route`, `spa-a` |
| `detect-*` | Reflects the environment as selectable attributes | `detect-browser`, `detect-features`, `detect-media` |

**Families.** Some jobs need a small group of tags that only make sense together (`content-tabs` + `content-tabs-header` + `content-tabs-body`, `spa-manager` + `spa-route`). The parent coordinates its own family — that is expected, and it is the one place an element manages something other than itself. Families share a name prefix so the relationship is visible in markup.

## The catalog

**Layout** — `content-carousel`, `content-drawer`, `content-tabs`, `dialog-anchor`, `dismiss-watcher`, `data-table`

**Content / routing** — `include-content`, `spa-route` (with `spa-manager`, `spa-a`), `scroll-into-view`

**Forms / auth** — `super-form`, `super-input`, `web-authn`

**Providers** — `provider-fetch`, `provider-geolocation`, `provider-orientation`, `provider-storage`

**Platform** — `detect-browser`, `detect-features`, `detect-media`, `dom-observer`, `event-handler`, `network-status`, `service-worker`

**Orchestration** — `quark-sheet`

The sidebar lists every package with its current API. `nucleus-kit` installs the whole catalog at once; each package also installs alone — if you end up using only a few elements, install those packages à la carte and skip the bundle.

## Three you'll use constantly

**`include-content`** renders a view when and where you need it — lazily on scroll, on idle, on an event, or immediately — from a `<template>` or a URL. It is the unit of composition for views. See [Building Views](./building_views.md).

**`provider-fetch`** turns a URL into a provision. Set `api-url`, read `prop("provision")` in Quark, react to `is-loading` / `is-success` / `is-error`. Pair it with `is-paused` to hold a request until the page is ready.

**`event-handler`** stitches behavior together: turn any event into a custom event or a command aimed at any element (`target-ref`), listen globally for keyboard shortcuts, or debounce input. Most "glue" that would otherwise be a click handler becomes one of these tags — or, where a sheet is already present, an `@on` block with `@dispatch` / `@command` (see [Orchestrating](./orchestrating.md)). Often no tag is needed at all: elements accept their imperatives as native commands, so a plain `<button command="--toggle" commandfor="menu">` drives a drawer with nothing in between.

```html
<button type="button" command="--toggle" commandfor="menu">Menu</button>
<content-drawer id="menu" class="absolute">
  <nav>…</nav>
</content-drawer>
<event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
```

Every command an element accepts (`--fetch`, `--submit`, `--reload`, `--open`) is listed on its package page under *Commands*. A `<button>` reaches its target by id; `<event-handler command-name>` reaches it by selector and can relay any event (`listen-for="super-form-success"`).

## Native elements are Adapters too

`<details>`, `<dialog>`, `<form>`, `<input>`, and `<select>` already bridge a protocol — disclosure, the top layer, submission, the keyboard — carrying its state as attributes and firing events. Prefer their native state before inventing your own:

```quark
details[open] #status { content: "Open"; }
details:not([open]) #status { content: "Closed"; }
```

The NucleusKit catalog exists to give the *same* contract to protocols the platform does not cover yet — not to replace what it already does.

## Two habits worth forming

- **Select on state, not on classes.** Setting attributes is recommended over toggling / mutating classes and ids, since the latter has a heavier impact on Quark's performance. Keep classes for static styling.
- **Prefer attributes before upgrade.** If script runs before an element's definition has loaded, `setAttribute()` is in the document at once, for CSS and Quark to select on; an assignment to a declared property is applied when the element upgrades.

## Next steps

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Orchestrating

Quark is the Orchestrator: it observes the document and writes back into it. It is a derivative of CSS, written in CSS syntax. Selectors, nesting, declarations and comments are CSS's own. The few additions Quark makes — variables, expressions, and at-rules of its own (`@use`, `@scope`, `@on`, `@dispatch`, `@command`, `@view-transition`, `@delay`, `@warn`, `@debug`, `@error`) — stay compatible with that syntax, so anyone who can read a stylesheet can read a sheet. What differs is the runtime: a stylesheet paints, a Quark sheet writes State. Features of the browser's style engine, such as media queries and keyframes, stay in your stylesheet.

## A sheet and its host

Put a `<quark-sheet>` next to the markup it should govern. The parent of that sheet is the **host**; every rule matches only inside it.

```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>
```

Scoping is identical to CSS `@scope`: selectors match strict descendants of the host. Reaching the host itself requires `:scope`.

```quark
:scope { data-ready: ""; }                  /* write to the host */
:scope[data-mode="edit"] [bind-x] { … }     /* react to host state */
```

- `src-url="/views/app.quark"` pulls the sheet from a file rather than inline text.
- `is-global` drops scoping so top-level rules run against the entire document. Use it sparingly, and nest rules inside an explicit `@scope { }` block wherever a region should stay host-scoped.
- Like many other elements, the sheet reflects its state: `is-loading` / `is-success` / `is-error`.

## Selectors

Quark rides the native selector engine, so whatever CSS can match, Quark can match — `:is()` / `:where()` / `:not()`, `:has()`, sibling combinators (`+`, `~`), structural pseudo-classes (`:nth-child()`, `:first-child`, `:empty`) and attribute-backed ones (`:disabled`, `:required`, `:lang()`) included. What Quark adds is observation: a rule re-runs when an attribute, class or id it names changes anywhere on its path — an ancestor, an earlier sibling, a `:has()` descendant — and when elements are inserted or removed where its match depends on them. The gaps are selector features backed by state the DOM does not reflect: interaction and validity pseudo-classes (`:hover`, `:focus`, `:checked`, `:invalid`) match on the first run only, and the sheet warns at build. Nesting works like CSS, and `&` means the current selector. See the related section under [Limitations](./limitations.md).

```quark
/* an aggregate over the rows becomes a fact on the host — no JS, no observer element */
:scope:has(li[data-is-selected]) { data-has-selection: ""; }
:scope:not(:has(li[data-is-selected])) { data-has-selection: none; }
```

```quark
provider-fetch[is-success] {
  $user: prop("provision").body;
  h3 { content: $user.name; }
  &[data-admin] h4 { content: "Admin"; }
}
```

Select on state, not on classes: attribute changes re-run Quark (attributes in the selector, and names read via literal `attr("x")`), as do JS property assignments read via literal `prop("x")`. Classes and ids named in a selector re-run it too, but setting attributes is recommended over toggling / mutating classes and ids, since the latter has a heavier impact on Quark's performance. `attr($name)` / `prop($name)` do not subscribe.

## Writing attributes

A property that is not a keyword becomes an attribute. `none` removes it. Booleans are `""`.

```quark
dialog[open] input { autofocus: ""; }
dialog:not([open]) input { autofocus: none; }
li[data-done] { aria-checked: "true"; }
```

Grouped-attribute helpers: `dataset` and `ariaset` accept a map and write `data-*` / `aria-*` attributes; `class` accepts a string, a list, or a map of `name: boolean`.

### Form controls

On `<input>`, `<option>` and `<textarea>` the markup only describes the *default*: the `value` / `checked` / `selected` attributes and a textarea's text. Once a user has interacted with a control, the browser stops mirroring those attributes into the live `.value` / `.checked` / `.selected` (the spec's "dirty" flags), so an attribute write alone would not show.

Quark papers over this. The attribute stays the authoritative, serializable State, and whenever a rule writes `value:` / `checked:` on an `<input>`, `selected:` on an `<option>`, or `content:` on a `<textarea>`, the live property is set to match. There is no property-write syntax and nothing new to learn: an edited control simply follows the rule again.

```quark
:scope[data-source="fahrenheit"] [bind-celsius] input {
  value: (($fahrenheit - 32) * 5 / 9).toFixed(1); /* wins over what the user typed */
}
form[data-reset] input[type="checkbox"] { checked: none; } /* attribute removed, box unchecked */
```

- The sync happens only when the rule writes. An edited control stays edited until a rule matching it re-runs; a re-run that resolves to the value the attribute already holds still restores the control.
- It is one-way. Typing never touches an attribute, so nothing re-runs on keystrokes. Reflect what you need as state through events (an `@on input { data-draft: event.target.value; }` block writing a `data-*` attribute is the idiom, see [Events](#md-events)) and select on that.
- Custom elements are not touched; they own their own reflection. `<select>` has no `value` attribute: write `selected:` on its options.

## Content

```quark
[bind-title] { content: $article.title; }                         /* text */
article { content: template("#article-tmpl"); }                   /* clone a <template> */
aside { content: template("/views/aside.html"); }                 /* fetch a fragment */
[bind-body] { content: dangerous-html(markdown($article.body)); } /* trusted HTML string */
details:not([open]) p { content: none; }                          /* clear */
```

A module function may also return a `Node` or `NodeList` it built. That is how a chart or another third-party widget reaches the page: the function creates its own element, renders into it and returns it. It needs no matched element: it creates its own.

```quark
[bind-chart] { content: createChart($series); }
```

## Variables

`$variables` work like CSS custom properties. A declaration stores the value on each matched element; a consumer walks upward from its own element to the nearest ancestor that holds it. They cascade across sheets, and the nearest binding wins.

```quark
main {
  $theme: "dark";
  [bind-theme] { content: $theme; }
}
[bind-theme-anywhere] { content: $theme; }   /* resolves if inside <main> */
```

Storage is per element, so writers that share a name collide (last writer wins). Namespace application variables: `$app-theme`, `$cart-total`.

A declaration on a descendant shadows the ancestor's binding rather than updating it. To raise state, write it on the owner: an `@on` block on the owner rule with `target:` delegation (see [Events](#md-events)), or, from JavaScript, `element.quark.setProperty(name, value)` on the owner element — every element has `element.quark`, shaped like `element.style` (`setProperty`, `setProperties`, `removeProperty`, `getPropertyValue`). The element written to becomes the owner; readers below it re-run in every sheet. It is State, not an event: a value written before a sheet registers is read on its first run. Keep one writer per name per element, and reflect primitives that CSS or a selector should see into attributes instead.

Keywords:

- `none` → removes the target attribute / clears content.
- `preserve` → explicit no-op; leaves whatever is already there. Useful while data is still loading: `content: $todo.title or preserve;`
- `unset` → variables only; deletes the binding so consumers fall through to an ancestor.
- An expression that resolves to `null` / `undefined` wipes its target. A failed expression **never** wipes; it logs and does nothing.

## Expressions

Values are Quark expressions, not JavaScript. They are derived from CSS expressions. Quote strings; a number with a unit (`10px`) is a string; `+ - * / %` and comparisons behave as you would expect; `and` / `or` short-circuit; member access on a missing value yields `undefined` instead of throwing. Prefer `#{$x}` interpolation over `+` when building strings.

```quark
[bind-count] { content: "Items: #{$items.length}"; }
#my-price { content: "#{($price * 1.2).toFixed(2)} EUR"; }
[bind-field="status"] { content: if($n == 0: "none"; $n > 3: "many"; else: "few"); }
```

Use `if()` for a one-off value. When several rules would branch on the same condition, write the condition to the document once (`data-is-empty: $n == 0;` — a boolean writes `""` or removes the attribute) and select on `[data-is-empty]` instead; see [Best Practices](./best_practices.md).

Method calls on values are limited to a read-only allowlist (`toUpperCase`, `slice`, `join`, `toFixed`, `getAttribute`, `closest`, …). Expressions may compute and read; they may not cause side effects. Logic they cannot express belongs in a module function (see [Modules](#md-modules)); anything that reaches the network, storage or the clock belongs in an Adapter.

## Element properties

`prop("<name>")` reads a JS property of the element the rule matches against; it mirrors `attr("<name>")`. `prop("provision")` reads the provision an element publishes.

```quark
provider-fetch[is-success] {
  $todo: prop("provision").body;
  h1#title { content: $todo.title; }
}
```

A rule that reads a literal `prop("x")` re-runs when JS assigns `element.x` (assignments coalesce per microtask). In-place mutation of an object is not observed — assign a new one. Changes the browser makes without a JS assignment (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.

`element` is the matched element itself, for the rare expression that needs the node: `@command toggle-popover (target: element.nextElementSibling)` in an `@on` block toggles the popover that follows it. Reads through it are not observed.

`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
/* shell sheet: its host contains <spa-manager> */
spa-route { $route-data: prop("provision"); }

/* any descendant view */
provider-fetch { api-url: "/api/users/#{$route-data.params.id}"; }
```

## Iterations

`iterate(array or object)` stamps one copy of the element's `<template>` per item, as siblings of that template. Inside each row, `item` and `index` are available to any rule — not only nested ones.

```html
<ul>
  <template>
    <li><span bind-title></span></li>
  </template>
</ul>
```

```quark
provider-fetch[is-success] {
  $todos: prop("provision").body;
  ul { content: iterate($todos); }
  li [bind-title] { content: "#{index}. #{item.title}"; }
}
```

## Events

`@on <events> [(options)] { … }` inside a rule listens on the matched elements — one event name, or a comma list — and applies the block once per event. With options the block is optional; the flags `prevent-default` and `stop-propagation` are options, and JS handlers are the `handle:` option.

```quark
form { @on submit (prevent-default) { is-submitted: ""; } }   /* the flag, then the writes */
a[data-external] { @on click (stop-propagation); }            /* options alone */
```

The block makes the event a one-shot transaction: a normal rule body, applied when the event fires instead of when the rule matches. Declarations write the matched element, nested rules write its matching descendants, and `event` is the DOM event. This is how user input becomes State without JavaScript:

```quark
:scope {
  $count: +attr("data-count");
  @on counter-increment { data-count: $count + 1; }            /* event → attribute */
  @on input, change { data-draft: event.target.value; }          /* typing → attribute */
  @on change { #panel { is-active: if(event.target.checked: ""; else: none); } }
}
```

Writes batch like any rule's, `$variables` set in a block persist on the element, and `preserve` skips a field you do not want to touch. `@on` inside a block is not supported.

### Listener options

The options group after the events is a map — `name: value` entries and bare flags — that filters and configures the listener: the same gates `<event-handler>` offers (`selector-filter`, `keycode-filter`, `is-debounced`, `host-ref`), written in the sheet:

```quark
ul { @on click (target: "li[data-id]") { data-selected: target.getAttribute("data-id"); } }  /* delegation */
dialog[is-open] { @on keydown (key: "Escape", host: window) { is-open: none; } }             /* global key */
form { @on input (debounce: 300) { data-query: event.target.value; } }                        /* typing settles */
main { @on scroll (throttle: 100, passive) { data-is-scrolled: event.target.scrollTop > 0; } }
a[data-external] { @on click (self, once, prevent-default); }
```

| Option | Effect |
| --- | --- |
| `target: "<selector>"` | Fire only when the event target is inside a matching descendant; that element is `target` in the block (`event.target` otherwise). |
| `self` | Fire only when the event target is the matched element itself. |
| `key: "Escape"` / `"Shift+K"` | Keyboard chord; space-separated tokens are alternatives. |
| `prevent-default` / `stop-propagation` / `stop-immediate-propagation` | Act on the event once it passes the filters. |
| `debounce: <ms>` / `throttle: <ms>` | Wait for a pause / at most once per window. |
| `handle: fn` | A JS listener: a function, a list `(a, b)`, or a call that returns one. Called with the event before the block, `this` being the element. |
| `once` | Detach after the first event that passes the filters. |
| `passive` / `capture` | Native listener options. |
| `host: window` / `host: document` | Listen there while the element is in the document. |

`target`, `key`, `debounce` and `throttle` are evaluated when the event fires, in the block's scope: `event`, `target`, `element` and the element's current `$bindings`. `handle:` is evaluated on every event too, so it reads current `$bindings`, but its value is the listener itself: `event` and `target` are not in its scope, because the listener receives the event. A call in `handle:` is a factory that must return the listener, and it runs on every event. Keep `handle:` for imperative DOM work Quark has no declaration for, such as moving focus once content renders:

```quark
include-content { @on include-content-did-render (handle: focusInput); }
```

Two `@on`s for one event may coexist when their options differ. There is no `@off`: rather than removing a listener, gate it — with options, or with `event` data and `preserve` inside its block.

### Dispatching events and commands

`@dispatch` and `@command` inside an `@on` block send an event or a command from it — the outgoing half of `@on`, and what `<event-handler>`'s `fire-event` / `command-name` do:

```quark
provider-fetch { @on super-form-success { @command --fetch; } }
todo-item { @on click (target: "[data-remove]") { @dispatch todo-remove (detail: (id: attr("data-id"))); } }
[data-help] { @on click { @command toggle-popover (target: element.nextElementSibling); } }
```

`detail:`, `target:` (a selector resolved like `<event-handler target-ref>` — `:scope` is the block's element, not the sheet's host — or an element from an expression), `host: window | document`, `form:` and the flags `bubbles` / `cancelable` / `composed` are the `@dispatch` options; `@command` takes `target:` and invokes native (`show-modal`, `close`, `toggle-popover`, …) or custom `--commands`. Both run at the end of the block, after its writes are queued — the event is an occurrence, not a delivery of State, so a recipient that needs the new State should select on it. Not allowed at rule level: a rule matching is not an occurrence.

## Modules

Functions come from modules imported with `@use`, for expressions and for `handle:`. Imports begin as soon as the sheet parses, load in parallel, and the first rule run waits for them.

```quark
@use "/helpers.js" as *;    /* bare exports */
@use "/utils.js" as utils;  /* namespaced */

[bind-total] { content: formatPrice(utils.total($items)); }
```

A module should be pure business logic: values in, a value out. It is also the exit for anything Quark cannot yet declare. Bridging a protocol, such as the network, storage, the clock or a person, belongs to an Adapter, which carries the result as attributes and a provision. Quark leans that way on purpose: it calls module functions synchronously and does not await what they return, so a fetch inside a module is deliberately awkward. A function may build and return a node it owns, like the chart under [Content](#md-content), and fill it once its work finishes (see [Asynchronous work](/packages/quark/use#md-asynchronous-work)); it should still leave the document around it alone.

Before writing a helper, check the built-in modules: `@use "quark:math"`, `quark:list`, `quark:map`, `quark:string`, `quark:date`, `quark:url` and `quark:util` ship pure functions for the derivations views need most — clamping, sorting and grouping a list by a dot path, counting, plurals, dates, query strings — imported like any module and never global:

```quark
@use "quark:list" as list;
@use "quark:string" as *;

ul { content: iterate(list.sort-by(list.filter($todos, "completed", false), "title"), none, "id"); }
[bind-left] { content: plural(list.count($todos, "completed", false), (one: "# item left", other: "# items left")); }
```

## Delayed writes

`@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. The timer restarts on every application of the rule (one per element), and the block is dropped if the element left the document or the rule stopped matching by the time it fires:

```quark
button[data-copy] {
  @on click {
    data-copied: "";
    @delay 2000 { data-copied: none; }     /* rapid clicks restart it */
  }
}
todo-item[is-pending-delete] {
  @on click (target: "[data-undo]") { is-pending-delete: none; }
  @delay 5000 { is-deleted: ""; }           /* undo clears the gate, the delete never lands */
}
```

The block is an ordinary rule body (`event` / `target` are kept inside an `@on` block), keeps the loop guard's causal depth, and its timers are cleared when the sheet unregisters. Time is otherwise an Adapter's protocol: `@delay` is for a wait that belongs to one State change, not for clocks or polling.

## Diagnostics

`@warn`, `@debug` and `@error` report from inside a rule; the selector is the condition, and nothing is written to the document:

```quark
img:not([alt]) { @warn "img needs alt"; }
provider-fetch[is-error] { @error "fetch failed", prop("provision").error; }
todo-list { $todos: prop("provision").body; @debug "todos", $todos.length; }   /* again when $todos changes */
```

`@warn` / `@error` speak once per element and rule; `@debug` speaks on every application. All three reach the console and the DevTools hook (`["quark", "diagnostic"]`), so the inspector and the agent tools list them next to the rule.

## Animating writes

Wrap writes in `@view-transition [(options)] { … }` and they commit inside `document.startViewTransition()`, so CSS animates the change — rows that leave included, which CSS transitions cannot reach. The block decides *how* its declarations and its nested rules' writes land, never *when* rules run:

```quark
provider-fetch[is-success] {
  $todos: prop("provision").body;
  @view-transition (types: "todo-change") {
    ul { content: iterate($todos, none, "id"); }
    [bind-count] { content: $todos.length; }
  }
}
```

```css
ul { view-transition-name: todos; }
li { view-transition-name: match-element; view-transition-class: todo; }
::view-transition-old(.todo):only-child { animation: todo-out 200ms; }
```

Every write of the same tick lands in the same cut, and the transition waits for Quark to settle before the new state is captured, so rows rendered by later rule passes are complete. Writes that change nothing, the sheet's first render, reduced motion and browsers without the API commit without a transition; so do writes while another transition runs (a route change), unless the block says `if-active: replace`. Options: `types`, `timeout`, `delay`, `first-render`, `if-active`, and `until: "<selector>"` to keep the transition open until the block's element matches — for short waits only, the page is frozen meanwhile. Styling recipes are in [Styling](./styling.md) (*Animation*); the full option table is on the [quark `@view-transition`](/packages/quark/view_transition) page.

## CSS variables

`--custom-prop:` declarations write CSS custom properties onto the matched element's inline style, so stylesheets consume Quark state through `var()`. Values are expressions — quote CSS literals.

```quark
#loadingbar { --progress: "#{($done / $total * 100)}%"; }
main[data-theme="warm"] { --accent: "#c96"; }
```

Write-only: Quark cannot read CSS variables back. If rules need the value, own it in a `$variable`.

## No rule reversion

In CSS, a declaration stops applying the moment its selector stops matching. For the time being, **Quark rules do not revert.** Attributes, content, listeners, variables, and CSS variables all remain after the rule that set them stops matching. Write the counter-rule for every state you leave:

```quark
details[open] {
  aria-expanded: "true";
  --border: "red";
}
details:not([open]) {
  aria-expanded: "false";
  --border: "transparent";
}
```

This was by design. Quark does not own the document; anything can write an attribute outside its knowledge, so claiming to "unapply" a rule would not be guaranteed. Reversion may appear in a later version, with no guarantee.

## Load order

Load a sheet before the elements it listens to begin their lifecycles: put `<quark-sheet>` first inside its host, and prefer inline sheets for anything that must catch connect-time events — `src-url` and `@use` delay the first run until they resolve. Attribute-driven rules are safe either way — the first run reads the settled document — so when in doubt, react to a state attribute rather than a one-shot event.

## Pitfalls

- A rule that renders a template containing elements its own selector matches will recurse forever. Match the template's host with a dedicated attribute or a nesting-guarded selector like `section:not(section section)`.
- Assigning an unused `$variable` purely to invoke a side-effecting function is an anti-pattern. Give the behavior a real element and a real event.
- Changes more than a tick apart are separate runs; encode a transition as a single write when coherence matters, or wrap the writes in `@view-transition` when the change should animate.
- A `@view-transition` block holding only `$variable` writes never animates: variables do not paint. Put the declarations that write attributes and content inside the block.
- A Quark sheet is not a place to park CSS. A sheet that holds an at-rule Quark does not have (`@media`, `@supports`, `@keyframes`, …) or an `!important` fails to load and is left `is-error`. Keep those in the stylesheet and have both sides select on the same attributes.

More in [Troubleshooting](./troubleshooting.md). The complete language reference lives on the [quark](../quark.md) package page.

## Next steps

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Styling

Style the state, not the script. CSS in the Nucleus Stack can read the same attributes Quark does, so visuals and behavior stay aligned without a line of glue.

## Valence.css

**Valence.css** is the stack's semantic, classless CSS: Pico's elegance, remixed so custom elements receive the same treatment as native tags, with other minor additions.

```css
@import "@excom/valence/basic.css";
```

`nucleus-kit/basic.css` already includes Valence.css plus every element's own styles, so loading NucleusKit means you are already styled.

- **Semantic tag aliases** — `article`, `button`, `dialog`, `table`, forms, and typography look right with no classes at all.
- **Role and class forms** — every tag alias is also matched by an ARIA role and a `.tag-*` class, so a custom element can borrow a native look: `<event-handler role="button">` or `<my-card class="tag-article">`. Prefer the role; semantics come along for free.
- **Molecules** — cards, dropdowns, modals, nav, progress, popovers, and tooltips assembled on top of the tag aliases.
- **Schemes** — light by default, dark via `prefers-color-scheme`, or force either with `<html data-scheme="dark">`.
- **Themes** — `basic` stays Pico-faithful; further themes share the same tokens so they can be swapped without touching markup.
- **Opt-outs** — `.unstyled` strips Valence.css from an element, `.unstyled-all` from its subtree, `.unanimated*` drops motion. Reach for these wherever framework styles would fight you.

## Tokens

Design tokens are CSS custom properties under the `--v-*` namespace: `--v-primary`, `--v-spacing`, `--v-border-radius`, `--v-font-family`, and the rest. Override them at `:root`, on a scheme, or on any subtree.

```css
:root { --v-primary: #2a6; --v-border-radius: 0.75rem; }
[data-scheme="dark"] { --v-primary: #5c8; }
aside { --v-spacing: 0.5rem; }
```

Use tokens in your own CSS so themes and schemes apply to your views automatically.

## Style the state

**Classes are for static flavor only.** `details.accordion` versus `details.dropdown` is a class. `.is-open` is not — that is state, and state belongs in an attribute the whole stack can see.

Hook native state first, then ARIA, then `data-*`:

```css
details[open] > summary { font-weight: 600; }
input:not(:valid) { border-color: crimson; }
[aria-current] { text-decoration: underline; }
li[data-done] { opacity: 0.6; text-decoration: line-through; }
```

Element state attributes are the same hooks:

```css
provider-fetch[is-loading] { opacity: 0.5; pointer-events: none; }
provider-fetch[is-error]::before { content: "Something went wrong."; }
spa-a[is-active] { color: var(--v-primary); }
```

The payoff: one attribute drives CSS, Quark, and assistive technology together, and it is visible in the inspector.

## Element CSS

Every element ships its styles next to its script and documents its CSS hooks on its package page: exposed variables, style classes (`content-tabs.underline`, `content-tabs.file-tabs`), and aliases. Override with your own selectors; nothing is locked behind a shadow root.

Write modern CSS in your stylesheets. Nesting, `@scope`, `:has()`, `color-mix()`, container queries, and view transitions are all fair game there. A Quark sheet is a derivative of CSS with a different runtime, so media queries, keyframes and the rest of the style engine stay in the stylesheet. Quark observes `:has()` too; interaction pseudo-classes (`:hover`, `:focus`) stay CSS-only (first run in a sheet).

## Quark and CSS together

Quark can write CSS custom properties from state, and CSS consumes them with `var()`. Use this for values a selector cannot express: computed colors, percentages, live theming.

```quark
[bind-progress] { --progress: "#{($done / $total * 100)}%"; }
```

```css
[bind-progress]::after { width: var(--progress); }
```

Quote CSS literals in Quark (`"#ccc"`, `"10px"`) — the value is an expression, not CSS grammar.

## Animation

State describes only the present, so an animation — a description of change over time — has no place in the document. Declare the destination state and let CSS own the motion:

- **Transitions** on state attributes: `[data-open] { translate: 0; transition: translate 200ms; }`
- **View transitions** between routes: `spa-manager` batches route changes into one `document.startViewTransition()`, and `spa-route` / `spa-a` reflect `is-active` / `was-active` so you can style enter and exit. `last-move` on the manager (`push` / `back` / `forward`) picks direction-aware transitions.
- **Card expansion and shared-element effects** come from CSS `view-transition-name` keyed to those same attributes.
- **List and content changes** from Quark: wrap the writes in `@view-transition (types: "…") { … }` and style the result. `view-transition-name: match-element` plus a `view-transition-class` on rows gives each row its own group, so `::view-transition-new(.row):only-child` animates rows that enter and `::view-transition-old(.row):only-child` rows that leave, and `:root:active-view-transition-type(…)` scopes the rules to that change. Keyed `iterate()` keeps rows alive, so moved rows slide instead of fading. Where `match-element` is not available, let the sheet name the rows (`--vt-name: "row-#{item.id}"`) and read it in CSS (`view-transition-name: var(--vt-name)`). The [View Transitions](./examples/view-transitions-app/view-transitions-app.html) example shows a card expansion, a page slide, a list reflow and a text crossfade built this way.

Quark writes are batched and not frame-aligned, so it is the wrong tool for per-frame values. Reach for CSS or the Web Animations API instead.

## Views

Each view owns its stylesheet, loaded by a `<link>` at the top of the fragment. Scope view CSS to the view's root element and keep shared layout in one site-wide stylesheet. See [Building Views](./building_views.md).

## Next steps

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Building Views

The Nucleus Stack has no components. When you need a reusable piece of UI with its own behavior, you write a **view**: an HTML fragment that owns its scoped CSS and Quark sheets. A JS Module is optional. Views are composed by the elements that load them.

## Anatomy of a view

```
views/
  profile/
    profile.html    # markup: one root element, bind-* targets, <template>s
    profile.css     # styles scoped to the root
    profile.quark   # orchestration scoped to the root
    profile.js      # custom logic functions, called from Quark.
```

```html
<section id="profile">
  <link rel="stylesheet" href="/views/profile/profile.css">
  <quark-sheet src-url="/views/profile/profile.quark"></quark-sheet>

  <provider-fetch api-url="/api/me">
    <h2 bind-name></h2>
    <ul bind-roles>
      <template><li></li></template>
    </ul>
  </provider-fetch>
</section>
```

```quark
@use "/views/profile/profile.js" as profile-module;

/* profile.quark — host is #profile */
provider-fetch[is-success] {
  $me: prop("provision").body;
  [bind-name] { content: profile-module.formatName($me.name); }
  [bind-roles] { content: iterate($me.roles); }
  [bind-roles] li { content: item; }
}
```

Two rules keep views portable:

1. **One root element.** That root is the sheet's host, so rules cannot leak and the view can be dropped anywhere.
2. **Re-derive your own context, if necessary.** Like CSS variables, Quark variables also cascade. If the parent view defines the desired variable, use it. If not, define it on the ancestor. You will need to use `<quark-sheet is-global>`.

## Loading views

A `<script>` inside a view fetched from a URL does not run; its `<link rel="stylesheet">`, `<style>` and `<quark-sheet>` do. A `<template>` parsed with the page does run its scripts once rendered. Load element definitions from the page.

### `include-content`

The workhorse. It renders a `<template>` or a remote fragment when and where you want it.

```html
<include-content lazy-load template-ref="/views/comments/comments.html"></include-content>
<include-content is-active template-ref="#empty-state"></include-content>
<include-content idle-load pre-fetch="idle" template-ref="/views/settings/settings.html"></include-content>
<include-content is-active><template>Recognized by default.</template></include-content>
```

- **Lazy (un)load** — render once scrolled into view, and optionally unrender once it leaves. `observer-root-margin` lets you start early.
- **Eager / idle** — render immediately (`is-active`), or when the browser is idle (`idle-load`).
- **Conditional** — toggle `is-active` from Quark to show or hide.
- **Prefetch** — `pre-fetch="idle"` warms a remote template so activation is instant.
- **Keep state** — `persist-content` reuses the same tree across toggles instead of rebuilding.

Because `is-active` is just an attribute, conditional rendering is a Quark rule:

```quark
main[data-mode="edit"] include-content[bind-editor] { is-active: ""; }
main:not([data-mode="edit"]) include-content[bind-editor] { is-active: none; }
```

### `spa-route`

Routing is a set of tags. Each `spa-route` matches a URL pattern and renders a view; `spa-manager` (which is optional) batches changes into view transitions; `spa-a` navigates.

```html
<spa-manager>
  <spa-route route-href="/" template-ref="/views/home/home.html"></spa-route>
  <spa-route route-href="/users/:id" template-ref="/views/user/user.html"></spa-route>
  <spa-route route-regex=".*" template-ref="/views/not-found/not-found.html" is-fallback></spa-route>
</spa-manager>

<nav>
  <spa-a route-href="/">Home</spa-a>
  <spa-a route-href="/users/42">Me</spa-a>
</nav>
```

Route params are a provision.

```quark
spa-route[is-active] {
  $params: prop("provision").params;

  &[template-ref$="user.html"] provider-fetch {
    api-url: "/api/users/#{$params.id}";
  }
}
```

Nested layouts (`match-nested`), scroll restoration, history actions, and per-direction transition styling are all attributes on these tags. See the [spa-route](../spa-route.md) package for the full set.

## An app skeleton

```html
<body>
  <quark-sheet src-url="/shell.quark"></quark-sheet>

  <include-content is-active template-ref="/views/header/header.html"></include-content>

  <spa-manager>
    <spa-route route-href="/" template-ref="/views/home/home.html"></spa-route>
    <spa-route route-href="/settings" template-ref="/views/settings/settings.html"></spa-route>
  </spa-manager>
</body>
```

```
/index.html
/shell.quark          # site-wide rules (theme, auth state, global shortcuts)
/shell.js             # optional pure functions any sheet may @use. Simple applications may prefer to keep all functions in this single file.
/shell.css            # shared layout
/views/<name>/<name>.{html,css,quark}
```

No build process is required. Files are served as-is, views load on demand, and editing any file is a refresh away.

## Data between views

Nested view communication and shared data is done the same way everything else is:

- **Down** through the document: a parent sets an attribute or publishes a provision; a descendant view reads it.
- **Up** through events: a view's element fires (or a sheet's `@on` block `@dispatch`es); an ancestor's sheet or `event-handler` listens. Events bubble, so a single rule at the root can hear the whole app.
- **Across** through shared state / Quark variable on a common ancestor.

When two views need the same value, put it on their nearest common ancestor and let both read it. Do not reach for JavaScript to pass it around.

Name every custom attribute with a dash (`data-duration`, `is-open`), never a bare word (`duration`): a bare name can shadow, or later collide with, a native attribute. Form field names follow the same rule when an `@on input` block copies them onto the host (`data-trip: event.target.form.elements["data-trip"].value`).

## Long lists

`iterate()` keeps the DOM proportional to your data. For heavy rows, stamp a lightweight `<include-content lazy-load>` per item and put the expensive markup in a commonly referenced template; only rows on screen materialize, and they can unrender as they scroll away (via the `lazy-unload` attr). This will ensure linear performance: only a single node per iteration. That covers most lists comfortably. At six figures of rows, node count itself becomes the limit — see [Limitations](./limitations.md).

## Enhancing existing static pages

Everything above works on a server-rendered or CMS page. Start with one element and one sheet inside one section. The rest of the page is unaffected, and there is no rewrite waiting at the end.

## Load order

Put `<quark-sheet>` first inside its host so it registers before sibling elements connect. Prefer reacting to state attributes (`is-success`, `is-active`) over one-shot events for anything that can happen during boot. See [Orchestrating](./orchestrating.md).

## Next steps

- [Quick Start - A working page, in five minutes.](./quick_start.md)
- [Core Concepts - The mental model, in one sitting.](./core_concepts.md)
- [Using Elements - The NucleusKit catalog and how elements behave.](./using_elements.md)
- [Orchestrating - Get familiar with Quark.](./orchestrating.md)
- [Styling - Valence.css themes, tokens, and state-driven CSS.](./styling.md)
- [Building Views - Structure a real app: routes, views, lazy loading.](./building_views.md)
- Other Guides - [Business Logic](./business_logic.md), [Creating Elements](./creating_elements.md), [Best Practices](./best_practices.md), [Troubleshooting](./troubleshooting.md), [Debugging with Agents](./debugging_with_agents.md)
- [Diving Deeper - The architecture behind it all, for the curious and the skeptical.](./diving_deeper.md)


---

# Business Logic

Pricing, eligibility, entitlements, approvals — the proprietary behaviour nobody can ship for you. In this stack it is not a layer of code. It is facts written into the document, and rules that select on them.

The shape never changes:

1. **Facts.** Everything the app knows lands in the document as an attribute, on an element named after the record it belongs to. Derived values are computed once and written next to the values they came from.
2. **Rules.** A business rule is a Quark selector over those facts, plus what follows from it.
3. **Consequences.** CSS selects on the same facts to render them: what shows, what it says, what it totals.

The payoff is not brevity. It is that a rule and its evidence sit in the document together. Open devtools on a disabled button and the attributes that disabled it are on its ancestors, spelled out. Nothing to step through, nothing to reproduce.

## Facts first

Stamp the server's answer onto the document *before* deciding anything with it. A record gets an element named after it — custom `data-` attributes and/or a custom tag starting with `data-` — and every field lands on its own line as a dashed attribute:

```html
<li></li>
```

```quark
li { dataset: prop("provision").body; }
```

Or:

```html
<!-- the session's facts live here; rules and CSS select on them -->
<data-session></data-session>
```

```quark
provider-fetch[api-url="/api/session"] {
  $session: prop("provision").body;
  data-session {
    account-id: $session.accountId;
    plan-name: $session.plan;
    region-code: $session.region;
    seat-count: $session.seatCount;
    seats-included: $session.seatsIncluded;
  }
}
```

Writing the fields out one at a time is the point, not a chore. The list *is* the schema: open the file and you know exactly what the API sends, and open devtools and you see the same names on the element. (`dataset: $session` would unpack the object in one declaration, but only onto `data-*` attributes, and it hides which fields exist — keep it for the case where a genuinely open-ended bag of `data-*` is what you want.)

Give the element the display it needs in CSS — an undefined custom element is `display: inline` until you say otherwise. Where the record is also *presented*, hand it the ARIA role the native tag would have carried (`<data-item role="listitem">`, `<data-return role="article">`): assistive technology reads it as before, and the Valence.css role aliases style it as before.

Then derive. A boolean declaration writes `""` when truthy and removes the attribute when falsy, so a derived fact ends up indistinguishable from a fact the API sent:

```quark
data-session {
  is-guest: $session.role == "guest";
  is-over-seats: $session.seatCount > $session.seatsIncluded;
}
```

Three rules keep this honest.

- **Derive once, select many times.** The same condition repeated across several `if()` calls means a fact is missing from the document. Write it as an attribute and every later rule — and every stylesheet — can see it.
- **Write the inverse.** Quark rules do not revert. Every state you leave needs its counter-rule, or a stale fact outlives the thing it described.
- **Dash every custom attribute.** `is-guest` or `seat-count`, never `guest` or `seats`. A bare word can shadow, or later collide with, a native attribute. Dropping the `data-` prefix does not buy you a dash-less name; it just moves the prefix to the tag, where it says something.

## Rules as selectors

A rule is a condition and its consequence. The condition is a selector over facts; the consequence is more facts.

### One fact per decision, its value the reason

When a decision has more than two outcomes, do not reach for a second boolean. Give the fact a value, and let that value *be* the reason it took:

```quark
:scope {
  /* the free plan carries one active project; a read-only seat carries none */
  &[is-read-only] {
    new-project-block: "read-only";
  }
  &[plan-name="free"]:not([is-read-only]):has([is-active]) {
    new-project-block: "plan-limit";
  }
  &:not([is-read-only]):not([plan-name="free"]),
  &[plan-name="free"]:not([is-read-only]):not(:has([is-active])) {
    new-project-block: none;
  }

  &[new-project-block] [bind-new-project] { disabled: ""; }
  &:not([new-project-block]) [bind-new-project] { disabled: none; }
}
```

Read the middle rule aloud and it is the requirement: *on the free plan, not read-only, already holding an active project*. The last selector is the inverse — every combination that leaves the blocked state. `:has()` turns a question about descendants into a fact on the ancestor, which is how an aggregate becomes selectable.

The same predicate almost certainly exists on your server, guarding the endpoint. That is fine and correct: it is stated once on each side of the wire, in the vocabulary of that side, and neither is hidden inside a call stack.

### Default-deny

Where the safe answer is "no", render every option, tag each with its identity, and let one rule open the ones that qualify. An option you forgot to account for stays closed:

```quark
provider-fetch[api-url="/api/carriers"][is-success] {
  $carriers: prop("provision").body;
  [bind-carriers] {
    content: iterate($carriers);
    > data-carrier { carrier-name: item; }
  }
}
```

```css
/* nothing ships anywhere until a region says so */
data-carrier { display: none; }
[region-code="uk"] :is([carrier-name="northwind"], [carrier-name="fenwick"]),
[region-code="de"] [carrier-name="brandt"] { display: block; }
```

In the business case above, opening a new market is just a selector, rather than a code change.
It should be noted that you still must have backend validation for all business logic, as with all UI frameworks.

### Facts derived from two places at once

A rule may compare a route against a session, a row against its parent, a line against the method chosen for the whole order. The comparison happens once; the result is a fact on the row:

```quark
spa-route[is-active] { $route: prop("provision"); }

data-project {
  is-active: attr("project-id") == $session.activeProjectId;
  is-locked: $route.params.mode == "audit" and attr("owner-id") != $session.accountId;
}
```

Now `data-project[is-active]` and `data-project:not([is-locked])` are available to every other rule and to the stylesheet, and neither has to know where the answer came from.

### Aggregates

`:scope:has()` sums a list up to its host without a counter, an observer, or a line of script:

```quark
:scope:has(data-line[is-selected])       { has-selection: ""; }
:scope:not(:has(data-line[is-selected])) { has-selection: none; }
:scope:has(data-line[is-selected][is-expedited])       { needs-approval: ""; }
:scope:not(:has(data-line[is-selected][is-expedited])) { needs-approval: none; }
```

Keep `:has()` arguments shallow. Each one costs a subtree scan per candidate element.

### Gating the submit

The last rule in most flows is the one that decides whether the user may proceed, and why not:

```quark
:scope {
  &:not([has-selection]) [bind-summary] {
    disabled-reason: "Pick at least one line";
    button { disabled: ""; }
  }
  &[has-selection][needs-approval]:not([approver-id]) [bind-summary] {
    disabled-reason: "Expedited lines need an approver";
    button { disabled: ""; }
  }
  &[has-selection]:not([needs-approval]) [bind-summary],
  &[has-selection][approver-id] [bind-summary] {
    disabled-reason: none;
    button { disabled: none; }
  }
}
```

The button's state and the sentence explaining it are written by the same rule, so they cannot disagree.

## The same rules, in CSS

Quark decides; CSS renders. Both select on the identical facts, which is what stops the two from drifting.

Quark owns anything that is *state*: attributes, content, listeners. `disabled` is state, so `disabled: ""` is a Quark declaration. CSS owns anything that is *appearance* — visibility, emphasis, the wording of a reason, a running total:

```css
[new-project-block] [bind-new-project] { cursor: not-allowed; opacity: 0.5; }
[new-project-block="plan-limit"] [bind-new-project-note]::before {
  content: "One project on the free plan — upgrade for more";
}
[new-project-block="read-only"] [bind-new-project-note]::before {
  content: "Your seat is read only";
}

/* a tooltip straight out of the fact that caused it */
[disabled-reason]:is(:hover, :focus-within)::after {
  content: attr(disabled-reason);
}
```

Counters handle totals, so the sum lives where the rows are rather than in a variable somewhere:

```css
[bind-lines] { counter-reset: picked subtotal; }
data-line[is-selected] {
  counter-increment: picked 1 subtotal attr(line-amount type(<integer>), 0);
}
[bind-summary] .totals::before {
  content: counter(picked) " selected · $" counter(subtotal);
}
```

Emptiness is a fact too. A value below a threshold that resolves to `""` disappears on its own:

```quark
[bind-margin] { content: if($line.marginPct > 1: "#{$line.marginPct}% margin"; else: ""); }
```

```css
[bind-margin]:empty { display: none; }
```

## When a calculation outgrows selectors

Selectors compare and combine; they do not iterate and accumulate. A weighted total, a tax table, an amortisation schedule — those are arithmetic, and arithmetic belongs in a function.

Check the [built-in modules](/packages/quark/modules) first: `quark:list` counts, filters, groups and sums, `quark:math` clamps and rounds, `quark:string` pluralises, `quark:date` does calendar arithmetic. Only write your own when they fall short.

When you do, `@use` it and let it return a value for Quark to write:

```quark
@use "/views/quote/pricing.js" as pricing;

provider-fetch[is-success] {
  $quote: prop("provision").body;
  :scope {
    contract-total: pricing.contractTotal($quote.lines, $quote.termMonths);
    is-above-approval-limit: pricing.contractTotal($quote.lines, $quote.termMonths) > 50000;
  }
}
```

```js
/* values in, value out. no DOM, no state, no attributes. */
export const contractTotal = (lines = [], termMonths = 12) =>
  lines
    .filter(({ isWaived }) => !isWaived)
    .reduce(
      (total, { unitPrice, seats, discountPct = 0 }) =>
        total + unitPrice * seats * termMonths * (1 - discountPct / 100),
      0,
    )
    .toFixed(2);
```

The function is a calculator. It takes values, returns a value, and has no idea a document exists. Quark writes the result into the DOM, where it becomes another fact that rules and CSS can select on — `[is-above-approval-limit]` now gates the submit exactly like any other fact.

### The counter-example

Here is the same feature written the way many stacks would write it:

```js
/* anti-pattern: goes shopping in the DOM, then writes to it */
export const updateTotal = () => {
  const rows = document.querySelectorAll("#quote data-line[is-selected]");
  const total = [...rows].reduce(
    (sum, row) => sum + Number(row.getAttribute("line-amount")),
    0,
  );
  document.querySelector("#quote-total").textContent = `$${total}`;
  document.querySelector("#submit").disabled = total === 0;
};
```

It works, and it costs you four things.

- **It is a second copy of a rule you already wrote.** `data-line[is-selected]` is now a requirement stated in two languages. One of them will be updated and the other will not.
- **It has to be called.** Every future path that changes a selection must remember to call it. That obligation is invisible until something forgets.
- **Its conclusion never reaches the document.** `total === 0` is the decisive fact, and it dies as a local variable. No CSS rule and no other Quark rule can see it, so the next feature that needs it computes it again.
- **It is untestable without a DOM,** and uninspectable with one — the selection is on screen, the reasoning is not.

The test is simple: **if a function reads the DOM or writes the DOM, it is doing the Orchestrator's job.** Give it arguments and let it return a value. A narrow allowance is a node the function builds itself: a chart is `[bind-chart] { content: createChart($series); }`, where `createChart` creates its own element, renders into it and returns it, and still never reads or writes the document around it ([Asynchronous work](/packages/quark/use#md-asynchronous-work) covers a render that finishes later). Talking to a server, a store or a payment provider is not a module's job: that is an Adapter's protocol, and its outcome reaches the document as attributes and a provision.

## Checklist

- [ ] Every value a rule needs is an attribute on an element, not a variable in a closure
- [ ] Every record is an element named after it (`data-<noun>`), with every field written out on its own line; it also can a generic element with `data-` attributes.
- [ ] Every derived boolean is written once, and has an inverse rule
- [ ] Every custom attribute contains a dash
- [ ] Decisions with several outcomes carry a value that names the reason, not a stack of booleans
- [ ] Aggregates come from `:scope:has()`, not from a counting loop
- [ ] The default is the denying case; qualifying opens it
- [ ] Quark writes state (`disabled`, `content`, the record's attributes); CSS renders appearance from the same facts
- [ ] Built-in modules checked before writing a helper
- [ ] Every module function takes values and returns a value — no state, no attributes, no DOM beyond a node it builds and returns
- [ ] The reason a control is disabled is a fact, and the message the user reads comes from it

Related: [Orchestrating](./orchestrating.md) for the language itself, [Best Practices](./best_practices.md) for the short rules, [Building Views](./building_views.md) for where these files live.


---

# Creating Elements

Most apps won't need to define any of their own custom elements. This will continue to get even less necessary as time goes on, as more elements will increasingly be added to the NucleusKit catalog.
Reach for your own only when neither the catalog nor Quark can cover the job — and when you do, build it as an **Adapter**: one protocol, its own state, events out.

## Element or rule?

| Write an element when… | Write a Quark rule when… |
| --- | --- |
| The behavior is generic | The behavior is custom |
| It speaks a protocol Quark cannot: an effect, time, focus, a key grammar, the accessibility tree | It reacts to State that is already visible |
| It needs configuration through several attributes | It's a one-off for this view |
| It integrates a browser API (fetch, geolocation, observers, passkeys) | It orchestrates a state transition between existing elements |
| It *catalyzes* change: it originates events or state | It *responds* to a catalyst |
| It wraps and upgrades a native element | It binds data or renders a list |

A useful test: if you find yourself assigning a `$variable` in Quark solely to call a side-effecting function, the behavior wants to be an element with a real event.

## The Adapter contract

> An Adapter is a located element — or a family of elements — that bridges the State and a foreign protocol: a system (network, storage, sensors, the clock, history, the viewport) or a person (pointer, keyboard, focus, the accessibility tree). It carries the protocol's state as attributes and provisions on itself, its occurrences as events, and its non-State machinery privately.

In practice:

- **Bridge one protocol, generically.** The protocol names the job: `content-drawer`, `provider-fetch`. Never the application: `add-to-cart`. Two elements for one protocol is duplication.
- **Manage only your own family.** Write your own attributes freely, and those of your recognized sub-adapters. Never write anything outside the family: invoke foreign elements (an event, a command) or read them (a `*-ref`), never mutate them.
- **Be drivable.** Writing your attributes must reproduce what your protocol would have done. A rule setting `is-open` and a click must be indistinguishable.
- **Attributes in, events out.** Options arrive as attributes. Results leave as state attributes, tag-prefixed events, and a `provision` for rich data. No public method is required to use you.
- **Stateless outside your node.** Everything lives on the instance, or on a sub-adapter. No module-level singletons, nothing on `window`. In-flight machinery — controllers, watchers, timers — stays private.
- **Clean up.** Cancel in-flight work on disconnect. Compose the `abortable-element` base and the cleanup is structural.
- **Never render your own children.** Recognize the children the author writes. Logic-free rendering of author-controlled content (a `<template>` clone, a fetched fragment, a third-party widget) is the narrow caveat, and it must be documented as the element's stated purpose.
- **Expose every opinion as an attribute.** Any default behavior someone might reasonably want to change gets a configurable attribute.
- **Prefer commands and events to methods.** Methods are private by convention and `_`-prefixed. If a consumer needs to tell you to do something, accept it as a command — a `command` event with a short `--verb` (`--submit`, `--reload`, `--open`), handled with Neutron `onCommand` — so a plain `<button command commandfor>` can invoke it. Commands never bubble and carry no payload: read what you need from your own attributes, or from the invoker's `data-*` through `event.source`. Never invent a bubbling `my-element-trigger` event for an imperative.
- **Speak the person's protocols fully.** If a person is on the far side, handle the keyboard grammar, focus, and ARIA state. An interaction element that does not is incomplete, not a different kind of element.
- **Mutable event detail is fine.** Letting listeners write into `event.detail` before a default action has native precedent (`formdata`, `beforeunload`, `respondWith`).

## Sub-adapters

Some jobs need a small family of tags that cannot stand alone: `content-tabs-header` only means something inside `content-tabs`. A **sub-adapter** is a dependent part of its root Adapter: it adapts input at its own node and announces upward, while the root keeps the family's state coherent and may write it. Two rules keep families honest:

1. Share a name prefix so the relationship is visible in markup.
2. The parent should prefer firing non-bubbling events *at* its children and letting them mutate themselves over mutating them directly.

## Building with Neutron

Neutron is a declarative factory over the Custom Elements API. Props reflect to attributes, lifecycles return **effects** instead of mutating, and events come with default actions built in.

```ts
import { Neutron } from "@excom/neutron";

export const CopyButton = Neutron({
  tag: "copy-button",
  props: {
    targetRef: String,          // ↔ `target-ref`
    didCopy: Boolean,           // ↔ `did-copy` (state)
  },
  events: {
    copy: { prefixWithTag: true },   // fires as `copy-button-copy`
  },
})
  .onEvent("click", () => ({
    emit: ["copy-button-copy"],
  }))
  .onEventDefault("copy-button-copy", (el) => {
    const text = document.querySelector(el.targetRef)?.textContent ?? "";
    navigator.clipboard.writeText(text);
    return { didCopy: true };
  });

CopyButton.define();
```

```html
<copy-button target-ref="#snippet">Copy</copy-button>
```

Consumers now have a state attribute to style (`copy-button[did-copy]`), an event to orchestrate against (`copy-button-copy`), and a default action they can cancel with `preventDefault()`. Resetting `did-copy` after a moment is the consumer's job — a Quark rule or a CSS animation — not the element's.

**Props.** Shorthand constructors (`String`, `Number`, `Boolean`, `TokenList`) reflect to kebab-case attributes. `TokenList` (exported by `@excom/neutron`) is a space-separated token attribute read as a `string[]`. `Object`, `Array`, elements, and promises stay on the instance. Rich config adds `defaultValue`, `isValid`, and custom `serialize` / `deserialize`. All custom attributes should contain dashes, to future-proof the element against later-defined native attributes.

**Events.** Events listened-to and fired by the element. By default, they bubble and are composed. Strongly recommended to prefix them with the tag name (`submit` - bad, `super-form-submit` - good) to prevent name conflicts with native events.

**Methods.** Neutron lets you define instance methods, called via effect-syntax like so: `myMethod: [myFirstArg, mySecondArg]`. However - if your method is potentially useful/necessary for the consuming application to call or prevent, it is better to define an event default action instead of a method. Example: `.onEventDefault('my-tag-foo-action', (el, { detail }) => ...)` and call like so: `emit: ['my-tag-foo-action', { detail: { myFirstArg, mySecondArg } }]`.

**Effects.** Every lifecycle and method returns a plain "effect" object/array of instructions: prop values, `emit`, `broadcast`, `style`, `addListener`, and nested effects for element-typed props. Return `{ didLoad: true }`; don't write `el.didLoad = true`. A handler must not set the prop it reacts to.

**Reactions.** `onPropSet` / `onPropUnset` / `onPropChanged` for one prop; `onEffect([...])` for a batch; `onPromiseResolved` / `Rejected` for promise props. `onConstructed` / `onConnected` / `onAdopted` / `onDisconnected` / `onError` for lifecycles. `onEvent` / `onEventDefault` / `onBroadcast` for events.

**Compose.** `Neutron.compose([Base, Neutron({...})])` stacks builders. The NucleusKit bases encode shared contracts you can opt into: `abortable-element` (cancelable async work), `fetchable-element` (a request lifecycle with `is-loading` / `is-success` / `is-error`), `renderable-element` (template rendering), `listenable-element` (declarative `listen-for`), `routable-element` (URL matching). Most elements are standalone; compose only when you need the contract.

**Provisions.** To publish rich data, set the `provision` prop (tag it `@provision` in JSDoc). Quark reads it with `prop("provision")` and re-runs when it is assigned; Neutron also fires `neutron-provision` for app JS. Provisions must be plain objects or arrays — assign a new one, in-place mutation is not observed.

**Prerendering.** An element composed from `fetchable-element` / `renderable-element` hydrates on a [prerendered page](./prerendering.md) with nothing to add. One that calls `fetch()` and replaces its own content still works there, fetching and rendering again; to keep the prerendered result it uses `fetchRecord()`, the `{ identity }` option of `replaceNonTemplateChildren()` and `holdHydration()` from `@excom/kit-utils`: see [Your own elements](/docs/prerendering#md-your-own-elements).

See the [neutron](../neutron.md) package for the complete API.

## Naming Recommendations

| Thing | Rule | Example |
| --- | --- | --- |
| Tag | Prefix by shape: `super-` wraps a native, `content-` expects children, `provider-` publishes data | `super-form`, `content-drawer`, `provider-fetch` |
| Attribute | Always contains a dash; booleans read as assertions | `target-ref`, `is-loading`, `did-fail`, `should-fetch` |
| `*-ref` attribute | Holds a CSS selector or a URL | `template-ref`, `form-ref` |
| Event | Prefixed with the tag name | `super-form-success` |
| Private state / method | Leading underscore | `_queue`, `_flush()` |
| Element base | `*Base` | `FetchableBase` |

Property and method names must not collide with anything on `HTMLElement`, now or plausibly in the future.

## Don't

- **Don't use shadow DOM** unless isolation is absolutely necessary, as around a region a rendering framework owns ([Handing rendering to a framework](/packages/quark/use#md-handing-rendering-to-a-framework)). It blocks the state-driven CSS and Quark rules the whole stack depends on and severely hampers composability even with slots.
- **Don't hold hard references to other elements.** Use `WeakRef` / `WeakSet`, and clear any parent reference in `onDisconnected`.
- **Don't render or mutate children** beyond the caveat above. If a parent must coordinate, fire events at children.
- **Don't add cross-cutting features.** `super-form` should not grow a `success-scroll-to` attribute; it should fire `super-form-success` and let `scroll-into-view` do the scrolling.
- **Don't observe more than you need.** Every state attribute is something Quark may watch. Keep the surface minimally comprehensive.

## Documenting

Elements are documented from JSDoc: `@option` and `@state` on props, `@provision` on the provision prop, `@fires` / `@listens` with `@type` naming the event type. Events deserve the most care: say exactly when they fire, the shape of `detail`, and whether `preventDefault()` skips a default action. Package READMEs open with a one-sentence pitch and the simplest possible demo, then a Features list in the consumer's own words. The [docs site](./introduction.md) generates the rest.


---

# Prerendering

Render every route to static HTML when the site is built. The browser takes each page over as it stands: nothing renders twice, nothing is fetched twice.

## Setup

[nucleus-ssr](../nucleus-ssr.md) renders the built site in Node: a config module names the routes and the app, which for an app built on NucleusKit is the kit's server entry: `entry: () => import("@excom/nucleus-kit/server")`. Build the site with [vite-plugin-nucleus](../vite-plugin-nucleus.md), then run `npx nucleus-ssr prerender.config.js`: it prerenders every route, reports each page and fails on a broken internal link. The nucleus-ssr page has the working example, the options and what fails a page. The app itself stays as it is: the same HTML, sheets, views and kit `<script>`. Prerender after every fresh build: a shell an earlier prerender wrote is refused.

## How it fits

The stack needs no second rendering model for this. Three things it already is are enough:

- **The HTML is the State.** State is attributes, text and children, so a serialized document is the State, fully formed. Provisions are State too: the page carries them, and each Adapter has its own again before it mounts.
- **Adapters are drivable.** Writing an Adapter's attributes reproduces what its protocol would have done, so a page that arrives with `is-active` or `is-success` set is an ordinary State to start from.
- **Hydration is a cold mount.** No element is told it hydrates. Each mounts as on any page load; its requests are answered at once, from the page, and its writes find their result already there. The Orchestrator derives the same State again and skips every equal write.

## In the browser

A prerendered page is static HTML plus the data it was built from, in a JSON `<script>` at the end of `<body>`. Once the kit loads:

- **Views** (`include-content`, `spa-route`) keep their prerendered content: no re-render, no refetch, no flash. `did-render` fires once, and content with `ready-on` is ready at once, never hidden. A view that changed since the build renders as on a cold load.
- **Providers** announce as on a cold load, `provider-fetch-loading` then `provider-fetch-success`, with the response the page carries and no request.
- **Loaded state** (`is-success` / `did-load`) is dropped and set again within one task as an element loads: content gated on it never flashes, and a MutationObserver sees one removal and one re-add.
- **Sheets** find what they would paint already there; `iterate()` adopts the prerendered rows.
- **`spa-manager`** runs its first update without a View Transition or `transition-delay` and leaves scroll to the browser; a reload gets its saved position back.
- **What the prerender left out** happens now, as on any page load: elements that read the device or the person, [`no-ssr` regions](#md-keeping-elements-out), `shadow` / `iframe` render hosts, `pre-fetch="idle"` fetches, anything behind a long timer (`@delay 3000`). An element whose data was kept out of the page arrives not loaded, its rendered content in place, and fetches as on a cold load.

Hydration ends once nothing holds it: kit requests, sheets and `@use` modules still loading, the first `spa-manager` update. From then on the page is an ordinary one. It lasts 10 s at most, and a console warning says when that limit ended it.

## Sheets

A sheet needs no change: the same sheet runs in the prerender and in the browser.

One contract to keep: **an `@on` write is a one-shot, on both sides.** `@on` blocks run during the prerender and their writes are in the HTML. In the browser the elements' events fire again (`provider-fetch-success`, `spa-route-did-render`), so a block applies again if its sheet is listening by then, the [load order](/docs/orchestrating#md-load-order) rule of any cold load. The first pass, though, paints again whatever a declarative rule also paints, and a `$binding` only an `@on` block wrote is unbound in the browser until that block runs again. Content that must survive prerendering derives from state attributes and provisions:

```quark
/* derived from State: the browser's first pass paints the same */
provider-fetch:not([is-success]) [bind-status] { content: "Loading…"; }
provider-fetch[is-success] [bind-status] { content: "Loaded"; }

/* a one-shot over a declarative paint: "Loading…" again, until the event is heard */
provider-fetch {
  [bind-status] { content: "Loading…"; }
  @on provider-fetch-success { [bind-status] { content: "Loaded"; } }
}
```

Four smaller things:

- Of two rules that set the same attribute, or text `content:`, on one element in one pass, only the later writes: a prerendered text node that already shows it is kept. `iterate()`, `template()`, `dangerous-html()` and `none` content is still written rule by rule, so one matching rule per element keeps the prerendered nodes.
- `iterate()` adopts prerendered rows by key: the key property's value, else a hash of the item, compared as text. A row whose key the browser does not find renders again.
- `template()` and `dangerous-html()` content is kept when its source is unchanged, replaced otherwise.
- A `$binding` not written yet, its sheet still loading a `@use` module, keeps what is painted until it is bound; once hydration ends, an unbound name is `undefined` again.

## Keeping elements out

What should not render at build time mounts in the browser instead, as on a cold load.

**`no-ssr` keeps a region out.** No Neutron element on or inside an element with the attribute mounts in the prerender, NucleusKit elements included. Use it for one place in a page, such as a live demo or a `lazy-load` view that should stay lazy:

```html
<include-content no-ssr lazy-load template-ref="/views/map/map.html"></include-content>
```

A sheet may write it too, on the element itself and first in the rule that activates it. An element that had already loaded or rendered when `no-ssr` reached it fails the page.

**`ssr: false` keeps a tag out.** `Neutron({ tag, props, ssr: false })` keeps every instance of your own element out, wherever it is written and without an attribute: for an element whose code reads the device or the person. Only the tag's own instances stay out; what they hold prerenders as usual.

## Your own elements

Compose `fetchable-element` / `renderable-element` and an element hydrates like the kit's own, with nothing to add. An element that calls `fetch()` and replaces its own content still works on a prerendered page: it fetches and renders again. To keep the prerendered result instead, use these from `@excom/kit-utils`:

- `fetchRecord(url, init)` in place of `fetch()`. It resolves the response as plain data (`ok`, `status`, `headers`, `body` as text). The prerender records a successful one, and in the browser the page answers, while it hydrates, as many identical GET / HEAD requests as the prerender made. A request that must be fresh or private always reaches the network: any other method, another origin, a `Request` object, `cache: "no-store"` / `"no-cache"` / `"reload"`, an `Authorization`, `Range` or `Cache-Control` header.
- `replaceNonTemplateChildren(host, nodes, { identity })` to render. `identity` names the source: `templateIdentity(ref, { scope })` or `htmlIdentity(html)`. Where `host` still holds what the prerender rendered from that source, its nodes stay (yours are not inserted) and the call returns `"adopted"`.
- `holdHydration(promise)` keeps the page hydrating until other start-up work settles, `whenHydrated()` resolves once hydration is over, and `isServerRender()` is `true` during a prerender.

A `provision` of plain data (what JSON carries) is restored from the page before the element mounts; any other is derived again in the browser. When the response it came from stayed out of the page, the element is written not loaded (no `is-success` / `did-load`) and fetches again. An element that reads the device or the person is defined with `ssr: false`, or stays undefined in the prerender: the entry does not load it, and `excludedTags` has the renderer check. A `<script>` an element inserts as HTML never runs in the browser, but does once it sits in a prerendered file: insert none. The attributes the prerender writes for itself (`n-ssr`, `n-tpl`, `n-tpl-id`, `n-inert`, `q-key`) are never written or selected on by hand.

## Static hosting

- **Slashless files.** `/docs/intro` is written to `docs/intro.html` and `/` to `index.html`. The host must serve `/docs/intro` from that file: many static hosts do, some need a rewrite rule.
- **A real 404.** Prerender the not-found route to `404.html`. Once `/` is prerendered, `index.html` is the home page: a host that falls back to it would answer every unknown URL with the home page and a 200. With a `404.html`, every route needs its file: a route that depends on the person (a bag, an account) is written as the untouched shell, through [`shellRoutes`](/packages/nucleus-ssr#md-options), and renders in the browser. The kit's server entry fails a soft 404, a page only the fallback route matches, so a link to a page that is gone cannot be written as one.
- **A file served for another URL** still works: the content of a route the URL does not match is removed, and the matching route renders.
- **Script loading.** Load the kit as a module or deferred script, so the page paints before the kit runs. A classic script works too: elements mount once the document is parsed.
- **Public files.** Nothing a per-person response returned may be in a prerendered page. nucleus-ssr fails a page built from a response marked private.

## Limits

- **Build time only.** No per-request rendering: what only a request knows (the person, a cookie) renders in the browser.
- **One renderer per process.** Pages render one at a time, or in a pool of worker processes; a cache writes a page again without rendering it while its shell and requests answer as in the last build. Both are [nucleus-ssr options](/packages/nucleus-ssr#md-workers-cache).
- **happy-dom, not a browser.** The prerender has no layout: every observed element counts as in view, so `lazy-load` views are in the page unless `no-ssr` keeps them out, and `matchMedia()` answers for one viewport. Where the browser derives something else, it writes it. Markup a browser would parse into other elements [fails the prerender](/packages/nucleus-ssr#md-failures): most often block content rendered into an element that sits in a `<p>`, or rows rendered straight into a `<table>` (write the `<tbody>`). The [hydration test](/packages/nucleus-ssr#md-test-hydration) runs on happy-dom too, so it cannot show what only a real browser does.
- **Time and randomness.** A page that depends on them differs between builds, and from what the browser derives.


---

# Best Practices

Short rules with rationale. They exist because the document *is* the state — keep that document honest and the rest stays simple.

## HTML

- **Semantic first.** `article`, `header`, `nav`, `figure`, `details`, etc. Avoid `div` soup. This will make it easier to hook into with Quark and CSS.
- **Classes carry static flavor only.** `details.accordion` is fine; `.is-open` is not. Dynamic state belongs in attributes: use an ARIA or `data-` attribute if the element does not provide the proper attribute.
- **Ids only where uniqueness is guaranteed.** Anything that might be iterated.
- **Use native state before inventing state.** `[open]`, `:valid`, `[aria-current]`, `[disabled]`.
- **Put state on elements, as attributes.** If you wish to store data somewhere, put `data-*` on the nearest sensible ancestor instead.

## Quark

- **Match on attributes rather than classes or ids that change.** Setting attributes is recommended over toggling / mutating classes and ids, since the latter has a heavier impact on Quark's performance.
- **Write the inverse rule.** Rules do not revert when they stop matching. Every state you leave needs a counter-rule (current limitation).
- **One sheet per view, first child of its root.** Registers before siblings connect; scope stays tight.
- **Binding identifiers.** You may need to target many parts of the document with your Quark rules in order to render content/attributes. If you choose to reserve classes for styling only, use logical, unused attribute patterns for data binding, such as `[bind-title]` or `[bind-field="title"]`.
- **Prefer nesting and facts over long combinator chains.** `>`, `+`, `~` and `:has()` are observed, but a deep chain couples a rule to markup structure; nest rules and select on attributes instead. Avoid over-nesting, since this is also brittle.
- **Namespace variables.** `$app-theme`, `$cart-total`. Like CSS, bindings are shared per element across Quark sheets.
- **Raise state on the owner.** A `$variable` written on a descendant shadows the owner's; put the `@on` block on the owner rule (`target:` for delegation) or call `element.quark.setProperty()` on the owner from JS. One writer per name per element.
- **`preserve` while loading.** `content: $todo.title or preserve;` keeps the last good value instead of flashing empty.
- **Never render what you match.** A rule that renders children (via `content:`) that match its own selector re-triggers itself until the loop guard cuts it (50 nested paints, logged as `Loop guard: …`).
- **Don't let rules gate on each other's writes.** `[data-a="1"] { data-b: "1"; }` next to `[data-b="1"] { data-a: "2"; }` is a cycle: Quark warns when the sheet builds (*rules gate on attributes they write for each other*) and the loop guard cuts it at run time if it never settles. Give the transition one attribute with a value, derive the second fact from the first in one direction only, or gate one side on a guard attribute. A rule cannot loop on the attribute it writes itself — that write never re-runs the same declaration.
- **Gate a one-shot on the fact it writes.** Rules re-run, and every run restarts a [`@delay`](/packages/quark/delay), so an unconditional `@delay 3000 { is-open: ""; }` reopens a dismissed banner. Write the fact with the effect and gate on it: `&:not([data-did-open]) { @delay 3000 { is-open: ""; data-did-open: ""; } }`.
- **Do not use variables to smuggle side effects.** An unused `$x: doThing();` is an element and an event in disguise.
- **Put the fact in the document before branching on it.** `if()` is fine, but many rules testing the same condition (`if($user.role == "admin": …)`) mean a fact is missing from the State. Write it once as an attribute (`data-is-admin: $user.role == "admin";`), then select on it: `[data-is-admin] button { … }`. The condition becomes declarative, addressable by CSS as well as Quark, visible in devtools, and evaluated in one place.
- **Prefer interpolation over concatenation.** `"Items: #{$n}"` and `"/api/users/#{$id}"`, not `"Items: " + $n` or `"/api/users/" + $id`. `+` stays for arithmetic.

## Custom JS (Quark Modules)

- **Little to none for simple apps.** Elements and Quark rules cover most needs; when they don't, that is usually a missing element or rule, not missing script.
- **Built-in modules first.** `@use "quark:list"`, `quark:math`, `quark:string`, `quark:map`, `quark:date`, `quark:url`, `quark:util` cover the derivations views need (sorting, counting, plurals, clamping, dates, query strings); write a module function only for what they lack.
- **Keep functions pure.** Values in, a value out. A module holds business logic; bridging the network, storage or the clock is an Adapter's job, and Quark does not await what a function returns. A function may build and return a node it owns without touching the document around it; imperative DOM work Quark cannot yet declare, such as moving focus, is a `handle:` listener.
- **No build step required.** Serve files as-is. Add a bundler only when you have a reason.
- **TypeScript is optional.** For a few dozen or hundred lines of pure functions, it usually isn't worth the build process.

## Events

- **Use the proper listeners.** Use Quark `@on` or custom elements like `<event-handler>` to listen to events, since they have a safe teardown procedure. Avoid using raw JS, which does not.
- **Invoke elements with commands.** A plain `<button type="button" command="--open" commandfor="id">` drives an element with nothing in between; `<event-handler command-name target-ref>` or a `@command` in an `@on` block does the same from any event or relative selector. Put `type="button"` on command buttons inside forms so they never submit.
- **Wire glue in the Quark sheet.** Retargeting, keyboard shortcuts, debouncing and custom payloads are `@on` options, and `@dispatch` / `@command` inside an `@on` block relay the event onward — `<event-handler>` offers the same as attributes for markup without a sheet.
- **Delegate.** Events bubble; one rule on a common ancestor beats a listener per element — `@on click (target: "li[data-id]")` names the row and exposes it as `target`.
- **Cancel default actions with `preventDefault()`,** don't fork the element.
- **Don't expect changing attributes to fire events.** State describes; events announce. Keep them distinct.

## Building Elements

- **Avoid Shadow DOM** ASO applications are heavily data-driven. Shadow DOMs are a hard boundary and severely blunt the power of Quark and CSS. Instead, consider using `@scope`. The exception is a region handed to a rendering framework that must own its DOM alone ([Handing rendering to a framework](/packages/quark/use#md-handing-rendering-to-a-framework)).
- **Single responsibility.** One job, configurable, observable. See [Creating Elements](./creating_elements.md).
- **Generic** `<content-drawer>` is good, `<add-to-cart>` is bad. Business logic belongs to Quark and its modules.
- **Never render children.** Composition is the design. The only caveat: an element may render fully author-controlled chilren, such as `<include-content>` does because this does not hinder composition.
- **Own your region.** An element writes only its own attributes and is permitted to write its [sub-adapters'](./adapter_state_orchestrator.md) attributes. Coordination across elements belongs to Quark sheets. Nothing else writes state.
- **Phrase booleans as assertions.** `is-loading`, `did-succeed`, `has-rendered`, `should-fetch`.
- **Dashed attributes, tag-prefixed events (`my-element-change`, never `change`).** This is to prevent collisions with native attributes and events - now and in the future.
- **Imperatives are commands, not events.** Accept "do this" as a `command` event with a short `--verb` (`onCommand("--submit")`), never as a bubbling `my-element-trigger` custom event. Commands are addressed to one element and never bubble, so the verb needs no tag prefix.
- **Underscore private members.** Minimize unnecessary imperative API surface.
- **Destructure the element in lifecycles.** `({ isOpen }) => ({ … })`, not `(el) => …` — a handler that only names the values it reads visibly cannot mutate the element imperatively. Destructured values are snapshots, so an async callback that needs current state should be a `defineMethods` method (it destructures fresh arguments when it runs).
- **Loosely couple** Avoid retaining hard references to other elements. When necessary, use `WeakRef` or ensure reliable cleanup during the proper lifecycles. Detached nodes make for significant memory leaks.

## CSS

- **Heavily utilize state attributes in selectors.** `provider-fetch[is-loading]`, `li[data-done]`, `[aria-expanded="true"]`.
- **Modern CSS is encouraged.** Nesting, `@scope`, `:has()`, container queries, view transitions.
- **Animate with CSS.** Declare the target state; let transitions and view transitions do the motion. Reach for Quark's `@view-transition` only where CSS transitions cannot go — rows that leave, list reflow — and keep `until` waits short.
- **Valence.css: Prefer roles to classes when borrowing a look.** `role="button"` over `class="tag-button"`.
- **Valence.css: Use tokens** (`--v-*`) so themes and schemes reach your views.

## Anti-patterns at a glance

| Smell | Fix |
| --- | --- |
| Toggling `.active` classes from a handler | Set an attribute; let CSS and Quark select on it |
| A Quark sheet variable that's never read | Move the effect to the event that causes it: an `@on` block with `handle:` or `@dispatch`. Consider `<event-handler listen-for-lifecycle="connected">` for a connect-time effect. |
| Two attributes flipped one after another to mean one thing | Prefer single attribute with a meaningful value |
| A custom element that reaches into a sibling or parent | Fire an event; let a rule coordinate |
| A bubbling `my-element-trigger` event that means "do this" | Accept a `--verb` command (`onCommand`); invoke it with `<button command commandfor>` |
| A `*-scroll-to` / `*-then-do-x` attribute on an element | Fire the event; compose with `<scroll-into-view>` or a rule |
| Shadow DOM "for encapsulation" | Light DOM plus scoped Quark / CSS |
| The same `if()` condition repeated across rules | Derive one attribute (`data-is-admin`, `data-is-eligible`) with a rule; select on it from Quark and CSS |
| `"Hello " + $name` / `"/api/" + $id` | `"Hello #{$name}"` / `"/api/#{$id}"` |


---

# Troubleshooting

Symptom first, then cause, then fix. Nearly every problem comes from one of three places: a rule that does not match what you think it does, a change Quark cannot see, or timing at startup.

## A rule doesn't run

**The Quark sheet did not load.** A sheet that holds an at-rule Quark does not have (`@media`, `@keyframes`, `@supports`, …) or an `!important` fails to load: the console names the offender (`@media is not a Quark at-rule`), the sheet gets an `is-error` attribute, and none of its rules run. Keep those in the stylesheet. An inline sheet that fails to parse though it reads right may hold text the browser took for markup: see [quark-sheet](/packages/quark-sheet#md-usage).

**It's outside the host.** A sheet matches only strict descendants of its parent element. Move the sheet, target the host with `:scope`, or use `is-global` if the rule truly must reach the whole document.

**It targets the host without `:scope`.** `section { … }` inside a sheet whose host is that section will not match it. Write `:scope { … }`.

**It uses an unobserved selector.** Interaction and validity pseudo-classes (`:hover`, `:focus`, `:checked`, `:invalid`) and pseudo-elements are not observed — the rule matches on its first run only, and the console shows a Quark warning at build. Hook element state instead: `dialog:not([open])`, `[aria-expanded="true"]`. `:has()`, sibling combinators and `:nth-child()` are observed and need no workaround.

**The referenced variable doesn't exist on an ancestor.** `$name` resolves upward from the consuming element. Confirm the declaring rule matches an ancestor (or the element itself), and that the name is spelled identically, including namespace.

**A nearer binding is shadowing.** When two rules write `$theme` at different depths, the nearest ancestor wins. Use `unset` on the inner one to fall through, or namespace them.

## A rule ran once and never again

**You read a class or id through `element` or `closest()`.** Those reads are not observed. Name the class or id in the selector (`li.is-done`, `#main`) or read it with a literal `attr("class")`. Setting attributes is still recommended over toggling / mutating classes and ids, since the latter has a heavier impact on Quark's performance.

**You changed a JS property, not an attribute.** In selectors, only attributes are observed. Reflect the value with `setAttribute()`, or read it in an expression with a literal `prop("x")` — that subscribes to JS assignments of `x`.

**The rule is reading a provision that hasn't re-published.** `prop("provision")` re-runs when the provider assigns a new provision. Confirm the provider actually refetched (the `--fetch` command, a changed `api-url`, or `is-paused` removed).

## Something stays set after its rule stopped matching

That's by design: **rules do not revert.** Write the counter-rule for every state you leave.

```quark
details[open] { --border: "red"; }
details:not([open]) { --border: "transparent"; }
```

## Content flashes empty while loading

The expression resolved to `null` / `undefined`, which wipes the target. Keep the last good value with `preserve`:

```quark
#title { content: $todo.title or preserve; }
```

## Content from a module function never appears

The target keeps what it had, and the console says `Quark: content does not await a promise from a module function — return a value or a node`. The function returned a promise: it is `async`, or it hands back the result of `fetch()` or another asynchronous API. Quark calls module functions synchronously on purpose.

- **Data from a server or a store** belongs to an Adapter: `provider-fetch` publishes the response, and a rule reads it with `prop("provision")`.
- **A library that has to load first:** `await` it at the top level of the module. The first rule run waits for `@use` imports.
- **Work that depends on the arguments:** create the element, return it at once, and fill it when the work finishes. See [Asynchronous work](/packages/quark/use#md-asynchronous-work).

## "Loop guard: …" in the console

Two participants keep re-triggering each other and the stack cut the chain. Causes, in order of likelihood:

- two rules that flip each other's attributes or classes (`a` sets `x` when `y`; `b` sets `y` when `x`). Give the transition one attribute with a value.
- an element effect that writes an attribute a rule reacts to, and the rule writes the attribute the effect reacts to.
- an attribute change fires an event (`dom-observer`, an element's `-change` event) and the listener — an `@on` block, an effect — changes that attribute again.
- a rule rendering elements its own selector matches, which re-triggers the rule (see below).

Every write an engine makes carries the depth of the chain that caused it; the write that would be hop 51 (`LoopGuard.limit`) is dropped, logged once with the element and attribute, and published to DevTools as an orchestration error. That is all that happens: no event fires, no attribute is wiped, no sheet or element is disabled, and the app is not told beyond the console line (subscribe with `LoopGuard.onTrip()` if it needs to know). The document keeps the state it had before the dropped write — but the participants are wherever the cycle left them, so treat the message as a bug report, not a fix. Start from the named attribute: what writes it, what reacts to it. Then let the reaction converge (a write of the value already there is skipped), give the transition one attribute, or gate one side on a guard attribute. Rules that gate on attributes they write for each other are also warned about when the sheet builds.

A rule cannot loop on its own attribute: a declaration is never re-run by the attribute it wrote. `class:` is the exception — its classes are separate facts, so `.is-done { class: (is-struck: true); }` applies when `is-done` arrives — and a class cycle is cut by the guard. Effects that keep re-queuing themselves inside one element are cut the same way, after `LoopGuard.limit` runs in one batch. `LoopGuard` (`@excom/kit-utils`, also `Neutron.DOM.LoopGuard`) exposes `limit`, `configure({ limit, log })` and `onTrip()`.

## The page freezes / "Maximum call stack"

A rule is rendering elements its own selector matches, which re-triggers the rule.

```quark
/* BAD */ span { content: template("#span-tmpl"); }
```

The loop guard stops this after 50 nested paints, but the fix is the selector: match the container or a `bind-*` attribute instead, and keep template children out of the selector's reach with a dedicated attribute or a nesting-guarded selector (`section:not(section section)`). A freeze the guard does not catch comes from writers it cannot see — plain `setAttribute` / `innerHTML` in app JS feeding each other — or from a loop with no DOM write in it at all.

## An event fired but nothing listened

**It fired before the sheet ran.** Sheets loaded via `src-url` or with `@use` imports don't run until those resolve. Place the sheet first in its host, prefer inline text for boot-time listeners, or react to a state attribute (`is-success`) instead of the one-shot event.

**It doesn't bubble that far.** Check the element's package page for the event's flags. Native events like `submit` are not composed, so they never cross a shadow root. Some events do not bubble at all.

## A `handle:` function never runs

`handle:` takes the listener itself, and Quark calls it with the event, `this` being the element. When the value is something else, the console shows the listener's key followed by `handle: needs a function or a list of functions, got <typeof>`, naming the type it received. An empty value (`null`, `undefined`, `preserve`) is skipped without a message.

**A quoted name.** `handle: "focusInput"` is a string, and the console says so in its own words. Write the bare name: `handle: focusInput`.

**A call.** `handle: focusInput()` runs `focusInput` on every event, without the event, and hands Quark its return value as the listener. A function that returns nothing leaves no listener to call, and nothing is logged. Drop the parentheses, unless the call is a factory that returns the listener. `event` and `target` are not in scope there: the listener receives the event.

**The name is wrong.** `handle:` refers to an export of a module imported with `@use`. Check the export name and the `as *` / `as name` namespace.

## An element ignores its attributes

**Wrong attribute name.** Attributes are kebab-case (`targetRef` → `target-ref`). Booleans are presence attributes (`is-paused`, not `is-paused="false"`).

## A form control shows a stale value

`value:` / `checked:` on `<input>`, `selected:` on `<option>` and `content:` on `<textarea>` also set the live property, so a control the user edited follows the rule whenever the rule writes. If it still looks stale:

- The rule did not re-run. Nothing re-runs on typing; check the state attribute the rule is gated on.
- It is a custom element. Quark writes only the attribute there; the element owns its own reflection.
- It is a `<select>`. There is no `value` attribute; write `selected:` on the matching `<option>`.

## `prop("provision")` returns nothing

- The provider hasn't assigned the `.provision` DOM node property yet.
- The selector doesn't match the provider's current state. `provider-fetch[is-success] { $foo: prop("provision") }` isn't matched while loading — that's a feature, not a bug.
- The provision isn't a plain object or array. Providers must publish POJOs.
- `prop()` reads the matched element only. To read an ancestor provider, publish it as a `$binding` from a rule matching the provider in a parent / `is-global` sheet.

## `prop("x")` never re-runs

- The object was mutated in place. Assign a new object — Quark observes assignments to `element.x`, not mutations inside it.
- The browser changed the property without a JS assignment (an `<input>`'s `value`, `open` on `<details>`). Select on the reflected attribute / listen for the event.
- The name isn't a literal. `prop($name)` reads but does not subscribe.

## A remote template never renders

- Wrong path in `template-ref`, or the fragment has more than one root element.
- The `include-content` never became active: `lazy-load` waits for viewport entry, `pre-fetch` only warms, and conditional includes need `is-active`.
- Check `is-error` on the element and the console for the fetch failure.

## Debugging tools

- **The inspector is the debugger.** Application state *is* the DOM. Watch attributes change in the Elements panel; that is your state timeline.
- **Nucleus DevTools** First-party devtools that will upgrade your Chromium dev tools to assist in inspectablility of both Neutron elements and Quark rules. Install it from the [Chrome Web Store](https://chromewebstore.google.com/detail/nucleus-devtools/mgfckaipagbdcacfgefodccipkpojlan).
- **Coding agents** The extension's probe exposes selector-addressed JSON tools (`diagnostics`, `state_snapshot`, `explain_attribute`, …) that chrome-devtools-mcp discovers as a "Nucleus Stack" tool group, or any browser automation calls as `__NUCLEUS_DEVTOOLS__.tools.*`; the pane's **Copy for AI** button copies a one-file bug report. Works on production sites with no app changes. See [Debugging with Agents](./debugging_with_agents.md).
- **Custom debugging** `Neutron.attachDevtools()` is available.
- **`QuarkRegistry`** is exposed on `window` in development. `QuarkRegistry.findRules("bind-title")` returns the rules that touch a selector; each rule tracks `numberOfRuns`.
- **`is-error` attributes** on sheets, providers, forms, and includes reflect failures, and matching `*-error` events carry the detail.
- **Log level** NucleusKit elements log only errors by default. `import { KitLogger } from "@excom/nucleus-kit"; KitLogger.level = 2;` adds warnings, such as a request that failed with an error status (`0` silent, `1` errors, `2` warnings, `3` debug, `4` info). Quark logs through its own `QuarkLogger`, exported next to it, with the same levels set independently. The progressive entry exports `KitLogger` only.
- **Serialize the state.** `document.documentElement.outerHTML` is a complete, shareable snapshot of the app at the moment of a bug. It will not include data provisions or Quark `$variables`.


---

# Debugging with Agents

An LLM agent can troubleshoot a Nucleus Stack app the way you would in DevTools: read the State, ask why an attribute has its value, test an expression, then edit the sheet. The [Nucleus DevTools](../nucleus-devtools.md) extension exposes that as tools, on development and production pages alike, with no change to the app and no runtime cost.

## What the agent gets

Eleven read-only tools. Each takes plain JSON, returns plain JSON, and addresses elements by CSS selector; every element in a result carries a unique `selector` the agent can pass straight back.

| Tool | Use it when |
| --- | --- |
| `diagnostics` | Anything is wrong. Failed expressions, effect errors, loop-guard trips, definition audits. |
| `state_snapshot` | You need the State: an element tree with attributes, `provision` data and Quark `$variables`. |
| `inspect_element` | One element: props, `$variables`, listeners, the rules matching it now, its recent history. |
| `explain_attribute` | "Why is `is-open` still set?" Every recorded write (rule + expression + result, or Neutron effect), the rules that could write it. |
| `list_sheets` / `matching_rules` | Which sheets exist, which rules apply to an element and in what order. |
| `evaluate_expression` | Test a Quark expression in an element's context before editing the sheet. |
| `trace` | What happened after an action: page-wide publications, filterable by element, path, or `sinceSeq`. |
| `list_definitions` | Which Neutron elements are defined, their attributes, audit findings. |
| `heatmap_top` | Which elements paint most (fan-out / cycle triage). |
| `dump` | One JSON bug report of all of the above. |

Tool descriptions carry the facts an agent tends to get wrong about this stack: rules never revert when they stop matching, the later matching rule wins, attributes (not classes) drive rules, rich data lives in `prop("provision")`.

## Setup

### chrome-devtools-mcp (recommended)

Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/nucleus-devtools/mgfckaipagbdcacfgefodccipkpojlan) in the Chrome you debug with, then point [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) at that profile with the third-party tools category enabled:

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect", "--categoryExperimentalThirdParty"]
    }
  }
}
```

`--autoConnect` drives your real browser (Chrome 144+, one-time toggle in `chrome://inspect/#remote-debugging`). The agent then finds a **Nucleus Stack** group through `list_3p_developer_tools` and calls tools with `execute_3p_developer_tool`, alongside chrome-devtools-mcp's own navigation, DOM, console and network tools.

### Any other browser automation

The same functions live on the page, so Playwright MCP, Cursor's browser, Puppeteer or a console work without flags:

```js
__NUCLEUS_DEVTOOLS__.listTools();
__NUCLEUS_DEVTOOLS__.tools.diagnostics({});
__NUCLEUS_DEVTOOLS__.tools.explain_attribute({ selector: "#cart", name: "is-open" });
await __NUCLEUS_DEVTOOLS__.tools.evaluate_expression({ selector: "#cart", expression: 'prop("provision").items.length' });
```

### No extension available

Evaluate `agent-tools.js` from the extension's release zip in the page (`evaluate_script`, `addScriptTag`, or a `<script>` when CSP allows). It installs the same tools; history starts at injection, so boot-time records are missed. With chrome-devtools-mcp, call `list_3p_developer_tools` after injecting.

## A workflow that works

1. `diagnostics` — an error usually names the attribute and the expression.
2. `state_snapshot` on the failing region — confirm what the State actually is.
3. `explain_attribute` on the attribute that looks wrong — the last write stands; find the rule that should have written its inverse.
4. `matching_rules` / `evaluate_expression` — test the fix against the live element.
5. Edit the sheet, reload, `trace({ sinceSeq })` to confirm the new run.

Add this to your `AGENTS.md` so the agent starts there:

```md
When debugging a Nucleus Stack page, use the "Nucleus Stack" DevTools tools (chrome-devtools-mcp `list_3p_developer_tools`, or `__NUCLEUS_DEVTOOLS__.tools.*` via evaluate). Order: `diagnostics` → `state_snapshot` → `explain_attribute` for the attribute that looks wrong → `matching_rules` / `evaluate_expression` to test the fix before editing the sheet. State lives in attributes and `provision`; rules never revert and the later matching rule wins.
```

## Sharing a bug

The extension's **Element** pane has a **Copy for AI** button. It copies `dump()` as JSON: the State tree, every sheet with source and rules, definitions, diagnostics, the last 200 publications and the paint heatmap. Paste it into a chat with the failing selector and the question.

## Limits

- Tools are read-only. `evaluate_expression` runs Quark's evaluator, which cannot assign; a `@use` function it calls can still side-effect.
- Output is capped: 500 trace records, 200 diagnostics, 200 history records per element and producer, 500 snapshot nodes by default; long strings are clipped with `… [+n]`.
- chrome-devtools-mcp's third-party tools are experimental and need the flag above; the page-global API is the stable fallback.
- Boot-time history needs the extension installed before the page loads (reload once after installing).


---

# Glossary

One definition per term. Capitalization marks a term that names one of the three ASO roles.

**Adapter** — A located element (or family of elements) that bridges the State and one foreign protocol — a system or a person — carrying the protocol's state as attributes and provisions, its occurrences as events, and its other machinery privately. On the web: a custom or native element.

**ASO** — Adapter, State, Orchestrator. The application architecture implemented by the Nucleus Stack.

**Addressability** — Any part of the State can be named. On the web, by a CSS selector. A precondition for orchestration.

**Binding** — A `$variable` value a Quark rule stores on an element, readable by that element and its descendants, across sheets.

**Catalyst** — Whatever originates change: a user action, a network response, a timer. Adapters originate change; rules respond.

**Closed under derivation** — Every fact in the State traces back to somewhere else in the State, with computation allowed in between. Nothing originates outside it.

**Command** — An imperative aimed at one element, carried by the platform's `command` event (`CommandEvent`): non-bubbling, cancelable, with a `--verb` name (`--submit`, `--reload`) and a `source`. Invoked by `<button command commandfor>`, `<event-handler command-name>`, or script; handled with Neutron `onCommand`. Not State (it describes no fact) and not an announcement.

**Content** — In Quark, the `content:` property: text, a cloned `<template>`, a fetched fragment, an iteration, trusted HTML, or a node a module function built.

**Default action** — What an element does after firing a cancelable event unless a listener synchronously calls `preventDefault()`. The escape hatch for customizing an Adapter without forking it.

**Effect** — In Neutron, the plain object (or array of objects) a lifecycle or method returns, describing what should happen (prop values, `emit`, `style`, listeners) instead of mutating the element directly.

**Element base** — A composable Neutron builder that encodes a shared contract (`abortable-element`, `fetchable-element`, `renderable-element`, `listenable-element`, `routable-element`). Opt-in.

**Family** — A root Adapter plus its sub-adapters, sharing a name prefix: `content-tabs` / `content-tabs-header` / `content-tabs-body`.

**Host** — The parent element of a `<quark-sheet>`. The sheet's rules match only inside it, unless `is-global` attr is set. The host itself is reachable via `:scope`.

**Iteration** — `iterate(array or object)`: stamps one copy of an element's `<template>` per item, exposing `item` and `index` to rules.

**Neutron** — The declarative factory for building custom elements as Adapters. Optional; an ASO app can use only native elements or other Custom Element constructors, so long as the elements themselves adhere to the Adapter definition.

**Neutron element** — Any custom element built with the Neutron factory, whether it ships in NucleusKit or the app author wrote it.

**NucleusKit** — The package that bundles the whole stack behind one import: `nucleus-kit`.

**NucleusKit element** — One of the drop-in custom elements in the NucleusKit catalog (`content-drawer`, `super-form`, `spa-route`, …). Each is also published on its own.

**Nucleus Stack** — The whole combination: NucleusKit elements + Neutron + Quark + Valence.css + Nucleus DevTools, published as `@excom/*`.

**Option attribute** — An attribute the author sets to configure an element (`api-url`, `lazy-load`).

**Orchestrator** — A declarative, selector-driven observer that watches the State for changes and writes coordinated changes back into it, holding no state of its own. On the web: Quark.

**Protocol** — What an Adapter bridges to the State: a system (network, storage, sensor, clock, history, viewport) or a person (pointer, keyboard, focus, the accessibility tree). One protocol per Adapter.

**Provision** — Rich data an Adapter publishes on itself (a parsed response, route params). Adapter-owned, published rather than authored. Read in Quark with `prop("provision")`.

**Pure function** — A JavaScript function that takes values and returns values without side effects. The preferred shape for everything imported via `@use`.

**Quark** — The CSS-derived orchestration language and runtime. Sheets of rules that select elements and write attributes, content, listeners, and variables.

**Recognized elements** — The descendants an element wires up automatically (`super-form` recognizes your `<form>`). Listed on each package page.

**Rule** — A selector plus declarations. Runs whenever a matched element's referenced attributes or bindings change. Does not revert on unmatch.

**Rule reversion** — CSS behavior in which a declaration stops applying when its selector stops matching. Quark does not do this; write the inverse rule.

**Scope** — The subtree a sheet may affect. Sheets are implicitly wrapped in `@scope { }` anchored at the host; `is-global` opts out.

**Serializability** — The whole State can be written out and shipped fully formed. A requirement, not a convenience.

**Quark Sheet** — A `<quark-sheet>` (inline or `src-url`) or a programmatic `Quark` instance: one unit of orchestration.

**`element.quark`** — The JS side of `$variables`: `setProperty` / `setProperties` / `removeProperty` / `getPropertyValue` on any element, shaped like `element.style`. The element written to becomes the binding's owner.

**State** — An application's living, structured, declarative body of data — the single source of truth - that is simultaneously what the application reads and presents. On the web: the document.

**State attribute** — An attribute an element writes about itself (`is-loading`, `did-fail`, `has-rendered`). What CSS and Quark select on.

**Sub-adapter** — A dependent part of an Adapter family that cannot operate alone. It adapts input at its own node and announces upward; the root keeps the family's state coherent and may write it.

**Super element** — A `super-*` element that wraps and upgrades a native element the author still writes (`super-form`, `super-input`).

**Tag alias** — A `.tag-*` class in Valence.css that lends a native tag's look to any element (`<my-card class="tag-article">`). Every alias has a matching ARIA role; prefer the role.

**Template method** — The architectural pattern behind an Adapter's customization surfaces: the Adapter owns the algorithm; attributes, events, and default actions are the hooks.

**Unified surface** — The State is simultaneously the source of truth and the presented artifact. ASO's headline property.

**Valence.css** — The stack's semantic, classless CSS with `--v-*` tokens, `[data-scheme]` light/dark, role and tag aliases, and opt-outs. Proud fork of the brilliant Pico.css.

**View** — An HTML fragment that owns its CSS and its Quark sheet, loaded by `include-content` or `spa-route`. The stack's replacement for components; always the app author's, never shipped with the stack.

**`@use`** — Quark's module import statement: `@use "/utils.js" as *;` exposes a module's exports to sheet expressions and event handlers.


---

# Diving Deeper

This section is for technically curious deep-divers. It explains *why* the Nucleus Stack/ASO is shaped as it is, names the ideas it stands on, and is candid about what it forgoes.

## Reading order

1. [Origin Story](./origin_story.md) — why Quark exists, and the platform gap it fills.
2. [Adapter, State, Orchestrator](./adapter_state_orchestrator.md) — the pattern, defined precisely.
3. [Prior Art](./prior_art.md) — where the ideas overlap and descend from existing ones, and what ASO is not.
4. [Limitations](./limitations.md) — the edges, the divergences, and the unresolved bits of this implementation
5. [Glossary](./glossary.md) — every term - one definition each.

## Design principles

**HTML is primary; JavaScript is a guest.** A conventional stack puts a JavaScript memory model in charge and targets the document as its compiled output. ASO upends that. The document *is* the program's state, elements embed into it, and optional scripting is invited in as pure functions once rules run out of expressiveness.

**The unified surface.** What the application reads and what it presents are the same artifact. Other frameworks' pipelines — memory model, logic, render, DOM — is exactly the severing of that unity, and everything required afterward (hydration, effects, reconciliation) exists to repair it. ASO never severs it.

**Distinctions are drawn by ownership, not by data.** Whether a value is a primitive attribute or a rich object is a storage detail of the host platform. Architecturally, what matters is who may write it: the author, the element that owns it, or the Orchestrator.

**Single responsibility is a constraint, not a preference.** An element with two jobs must be two elements. That is what makes composition work w/o a component model.

**There are no components.** Elements have no intrinsic knowledge of any other elements outside of their own family. Reusable UI is a *view* — markup plus its own CSS and Orchestrator sheet — loaded where needed. Nothing that ships with the stack decides what your page looks like.

**Coordination is anonymous and addressed by location.** Rules name places in the document with selectors. No participant holds a reference to another; none calls another. That is what lets two sheets cooperate without knowing the other exists. This follows CSS and the Blackboard pattern.

**State describes only the present.** No logic, no history, no futures. Animation belongs to CSS.

**Failure is inert.** A broken expression logs and does nothing. Malfunction in the Orchestrator degrades the experience; it cannot corrupt the state.

**The platform is the framework.** Selectors, mutation observers, custom elements, events, custom properties, view transitions. The stack adds a language - which is simply a derivative of CSS - and an optional factory over those primitives.

## One paragraph per role

An **Adapter** is a located element — or a family of elements — that bridges the State and a foreign protocol: a system (network, storage, sensors, the clock, history, the viewport) or a person (pointer, keyboard, focus, the accessibility tree). It carries the protocol's state as attributes and provisions on itself, its occurrences as events, and its non-State machinery privately.

**State** is an application's living, structured, declarative body of data — the single source of truth - that is simultaneously what the application reads and presents.

The **Orchestrator** is a declarative, selector-driven observer that watches State changes and writes coordinated changes back to it, holding no separate state of its own.

Continue to [Adapter, State, Orchestrator](./adapter_state_orchestrator.md).


---

# Quark's origin story

The web platform has always lacked a critical native feature: a way to declaratively map data to the document... a "templating language".
This fundamental gap is the primary reason for the creation and endless churn of frameworks and libraries that fill that gap, such as Angular, React, Vue, etc.

And yet, templating **actually has existed** for a long time via CSS:
```css
span::before {
  content: "I will be painted.";

  /* It can even be dynamic: */
  content: attr(data-my-text);

  /* from a variable: */
  content: var(--my-text);
}
```

Quark was conceived as exactly this: a derivative of CSS which mutates the document instead of styling it.
It also augments CSS expressions, so the same patterns can be applied for rich data:

```quark
span {
    content: "I will be painted.";
    
    /* attr */
    content: attr("data-my-text");
    
    /* variable */
    content: $my-text;

    /* DOM Node property */
    content: prop("myData").myText;

    /* custom logic */
    content: myModule.formatPrice($amount);
}
```

It can also be used for setting attributes, rendering `<template>` content, loops, conditions, event listeners, and more.

## Long term goal

The web still contains this fundamental gap. Framework churn will not cease until it is filled.
Compared to other frameworks and libraries filling this gap, Quark arguably stands apart as the most native-compatible solution.
If Quark sees widespread adoption, a WHATWG proposal will be drafted for the web platform to adopt a native feature/language bearing Quark's capabilities.


---

# Adapter, State, Orchestrator

**ASO** is an application architecture where the live document *is* the program's state — not a depiction of it. Autonomous **Adapters**, embedded in a shared, observable **State**, bridge that State and the world outside it. A declarative **Orchestrator** observes the State and writes coordinated updates back into it. Participants never hold references to one another; coordination travels only through the shared surface.

The pattern is abstract. It applies anywhere a structured, addressable, mutable, and observable body of state exists — not only on the web, and not only in user interfaces. The Nucleus Stack is the web realization: Adapters are elements (custom OR native), the State is the DOM, the Orchestrator is Quark.

## Adapter

> An Adapter is a located element — or a family of elements — that bridges the State and a foreign protocol: a system (network, storage, sensors, the clock, history, the viewport) or a person (pointer, keyboard, focus, the accessibility tree). It carries the protocol's state as attributes and provisions on itself, its occurrences as events, and its non-State machinery privately.

Updates cross the bridge in one direction or both. **Driving**: the protocol changes and the Adapter writes State — `provider-fetch` publishes a response, `content-tabs` records the chosen tab. **Driven**: State changes and the Adapter acts on the protocol — `api-url` starts a request, `is-open` moves focus and updates the accessibility tree. The Orchestrator only ever sees the State side of the bridge.

**Requirements** — an Adapter must:

- bridge one protocol. The protocol names the job, and two Adapters for one protocol is duplication
- stay generic: `<content-drawer>` is good, `<add-to-cart>` is bad.
- be drivable: writing its attributes reproduces what its protocol would have done. A rule setting `is-open` and a click must be indistinguishable
- write only itself. "Itself" includes its recognized sub-adapters; nothing outside the family is ever written. Foreign elements are invoked (an event, a command) or read (a `*-ref`), never mutated
- reflect state relevant to consumers (like the Orchestrator) as attributes, and publish rich data as a `provision`
- announce occurrences as tag-prefixed events, so that no consumer needs a reference to it
- hold nothing global, keep in-flight machinery (controllers, watchers, timers) private, and release it when it leaves the State

**Recommendations** — an Adapter should:

- expose each opinionated behavior as a configurable attribute
- prefer event listening over public methods. Methods are private by convention and `_`-prefixed
- keep its observable surface concise, since every state attribute is something the Orchestrator may observe
- never render opinionated children; recognize the children the author writes. Logic-free rendering of author-controlled content (a `<template>` clone, a fetched fragment, a third-party widget) is the narrow exception and must be the Adapter's stated purpose
- speak the person's protocols fully when it is an interaction Adapter: keyboard grammar, focus, ARIA state. An interaction Adapter that does not is incomplete, not a different kind of element

**Sub-adapters.** A family of tags is one Adapter whose protocol spans several nodes: `content-tabs` with `content-tabs-header` and `content-tabs-body`, `spa-manager` with `spa-route`. The root keeps the protocol's state coherent across the parts and may write them; parts adapt input at their own node and announce upward; they never manage the root. Families share a prefix so the relationship is visible in markup. Native precedent: `<details>` and `<summary>`.

**Two shapes, one role.** System Adapters are single nodes with a platform API on the far side (`provider-*`, `detect-*`, `service-worker`, `super-form`). Interaction Adapters are usually families with a person on the far side (`content-tabs`, `content-carousel`, `content-drawer`). Some bridge both — `spa-manager` bridges history and its routes, a native `<form>` bridges submission and its controls. The rules are the same; only the protocol differs. A rule reacts to State; an Adapter speaks a protocol the Orchestrator cannot.

**Native elements are Adapters.** `<input>` bridges the keyboard, `<img>` the network, `<a>` navigation, `<details>` / `<summary>` the disclosure protocol, `<dialog>` the top layer. Custom elements extend the same contract to protocols the platform does not cover yet, and should never replace what it does. Neutron is optional: an ASO application needs an Orchestrator, but its Adapters can be entirely native.

**Three customization surfaces.** Configuration attributes inform behavior before it instantiates; events report what happened or will happen; a cancelable default action lets a listener prevent what happens next. Taken together they follow the *template method* pattern expressed in markup: the Adapter owns the algorithm, the author controls the hooks.

**Capability bases.** A minority of NucleusKit elements are composed from shared contracts — `abortable`, `renderable`, `fetchable`, `listenable`, `routable`. Composition is opt-in. Most Adapters are standalone.

## State

> State is an application's living, structured, declarative body of data — the single source of truth - that is simultaneously what the application reads and presents.

State describes only the present. It holds no logic — it declares what is, never how anything happens. Structure, rather than flatness, is required - containment carries meaning, allowing the Orchestrator to scope and match its rules against this ancestry. This is what makes selector-based coordination possible.

Every part of it is addressable and serializable. Those are not conveniences of the web platform; they are requirements. Addressability is required for orchestration, and serializability is what enables inspection and lets a fully-formed State be shipped before any Adapter or Orchestrator exists.

It is observable and mutable by embedded Adapters (which write only their own regions) and by the Orchestrator (which coordinates across them). It is upgradeable in place: Adapters embed and hook into it rather than being rendered by it.

It has no exogenous derivation. Descendent parts of it may be computed from ancestor parts... that cascading is intentional. Nothing is derived from outside of it. Nothing more authoritative lives elsewhere.

It is singular per orchestration domain; encapsulation boundaries like shadow roots or iframes start a new State root with its own optional Orchestrator. They never reach across these boundaries.

Provisioned data — adapter-owned, published rather than authored — sits embedded as a region of State, rather than an exception to it.

### The unified surface

The State is both the source of truth & the presented artifact. This union is one of ASO's headline features, and the rest follows from it. A conventional pipeline (memory model -> logic -> render -> DOM) severs that unity and then spends its complexity budget repairing the seams: hydration, reconciliation, stale closures, effects. ASO never opens the seam. What the user sees can't disagree with what the application knows; they are the same object.

### Regions and ownership

Architectural distinctions are drawn by **write authority**, not data shape. Primitives vs rich data is a storage detail of the platform.

| Region | Owner | Web form | Readable by the Orchestrator |
| --- | --- | --- | --- |
| Initial state | The author | Elements, attributes, text | Yes — by selector |
| Provisioned data | The publishing Adapter | Rich `provision` on an element | Yes — by `prop("provision")` |

Provisions are published, not authored. A fetch response or a set of route params is owned by the element that produced it. `$variables` — declared by rules or written from JS through `element.quark.setProperty()` — are Orchestrator-owned working values anchored to elements; they are not selector-addressable, so a fact that CSS or a selector should see is reflected into an attribute instead.

### Consistency

Orchestrator writes are batched as a dedicated thread task; a given rule always reads synchronously-settled elements rather than a half-applied ones. Events are intentionally not batched: bubbling is synchronous, so listener (mid-bubble) must see the world as it is. Rules are idempotent - re-running one is harmless. Mutations of state via Adapters or the Orchestrator should be done as synchronous writes where coherence is important; async mutations are separate facts, and treating them as one is not the Orchestrator's job. Orchestrator rules and rule properties are matched/executed in the sequence they are defined.

### Origination

Initial State is usually authored statically, but need not be. The pattern does not prescribe where a State comes from, but once present, it's the sole authority.

## Orchestrator

> The Orchestrator is a declarative, selector-driven observer that watches State changes and writes coordinated changes back to it, holding no separate state of its own.

**Stateless.** Bindings live in State (on elements), shared across Orchestrator instances/sheets, the same way custom properties are, resolved by walking up ancestors. A sheet is pure behavior. Two sheets cooperate through the document without knowing the other exists; this follows CSS and the Blackboard pattern.

**Addressed, not invoked.** Rules name State locations by selector, never participants by real identity. The Orchestrator holds no reference to any Adapter... and no Adapter calls the Orchestrator. Coordination is anonymous in both directions.

**A deliberately narrow language.** Expressions may compute and read, they may not cause effects. Method calls, mapped to native JS, are limited to a read-only allowlist. The Orchestrator declares relationships between facts... anything imperative must leave through a custom, named module function, defined by the author. The architectural rule — "the Orchestrator does not execute procedures" — is enforced at the language level.

**Not a bridge.** A module function is the exit for logic the language cannot yet express. Bridging a protocol (the network, storage, a sensor, a person) is not that kind of work: it belongs to an Adapter.

**Failure-inert.** A broken expression logs and no-ops, like CSS. Malfunction in the Orchestrator degrades the experience... it cannot corrupt the State.

**Reactive and bounded.** It observes only what its own rules reference (the underlying MutationObserver is filtered to the attributes its rules name, plus element insertions — and removals only while a rule's match depends on children or sibling position), and its authority stops at an encapsulation boundary.

**Classification.** The Orchestrator is not a finite state machine - it has no enumerable state set. Its configuration is the document. It has features of a **conceptual Statechart**, but is more precisely a **reactive extended state machine**: hierarchical (rules nest and can scope to ancestors), with guards (selectors), actions (writes), and extended state (the document and its bindings).

**Quark's divergence from CSS.**
Rules are applied as ephemeral transactions, not persisted. This is because, unlike CSS, the Orchestrator does not own its domain (the State). Anything can write an attribute outside its knowledge. This may change in a future version of Quark.
This means:
- Rules do not revert when their selector stops matching. Authors must write the inverse rule if they wish to un-apply the rule in question.
- Specificity is not taken into account. If Rule A matches before Rule B, but has a higher CSS selector specificity, it will not matter. Rule B will be applied regardless.

Quark is also a derivative of CSS, written in CSS syntax: rules, selectors, nesting and declarations carry over, and what Quark adds (variables, expressions, at-rules of its own) stays compatible with that syntax. What differs is the runtime: a stylesheet paints, a sheet writes State. Features of the browser's style engine, such as media queries and keyframes, stay in the stylesheet.

## How it differs

**Component frameworks** (React and similar frameworks) put a memory model in charge, run it through custom app logic, and target the document as output. The component conflates view, orchestration, and adapter (and sometimes even styling) in one imperative unit, which is why composition and reuse are difficult. A parent cannot reshape a child's logic without forking it. ASO separates these three roles into three languages — HTML, Quark, plain functions — and deletes the memory model. Where an ASO app hands a region to such a framework, a shadow root is the boundary between them ([Handing rendering to a framework](/packages/quark/use#md-handing-rendering-to-a-framework)).

**MVC / MVVM** keeps a model separate from a view and spends its lifecycles synchronizing the two. ASO has one surface. There is nothing to bind.

**Nearest relatives** are the Blackboard pattern and CSS itself: see [Prior Art](./prior_art.md).


---

# Prior Art

ASO was worked out in practice, not derived from theory — but most ideas it contains already have a name. Those names let you reason about the architecture and borrow decades of thinking about its properties.

## Lineage

### Blackboard pattern

The closest ancestor. Knowledge sources in a blackboard system never talk to each other. They watch a shared, structured store (the blackboard), contribute when they recognize something they can act on, and a *control component* chooses what runs next. ASO maps onto that picture directly: the State is the blackboard, Adapters and rules are knowledge sources, and the Orchestrator is the control. Loose coupling, opportunistic problem solving, incremental solution-building — the blackboard literature's claims all apply here.

### Stigmergy

Biology's version of the same idea. Ants and termites coordinate by leaving traces in a shared environment; other individuals respond to those traces, with no direct communication. That is a useful lens for Adapters and sheets that cooperate without knowing the other exists — the document is the environment, attributes are the traces.

### Ports and adapters (hexagonal architecture)

Cockburn puts the application core at the center and reaches the outside world through adapters that translate both ways. ASO's first role takes its name from here. In ASO the document is that core and the Adapters are, literally, its adapters: `provider-fetch` adapts the network, `super-form` adapts user input, `content-tabs` adapts a person's tab-navigation protocol and the accessibility tree. Driving versus driven maps onto the two directions an Adapter carries updates. The capability bases (fetchable, listenable, routable, …) are adapter contracts.

### Statecharts

Harel's statecharts add hierarchy, guards, and extended state to finite state machines. The Orchestrator can be seen like a conceptual (non-visual) statechart, not an FSM: rules nest and scope by ancestry, selectors act as guards, writes are actions, and the document is the extended state. Calling it an FSM would imply an enumerable state set that does not exist.

### CSS

Quark derives from CSS in more than syntax. It inherits CSS semantics for scoping (`@scope`), cascade and inheritance (variables resolve up the ancestor chain, nearest wins, across sheets), and coordination by selector rather than by reference. Two deliberate departures: rules do not revert on unmatch — see [Limitations](./limitations.md) — and a sheet writes State instead of painting, so features of the browser's style engine, such as media queries and keyframes, stay in the stylesheet. Quark's JS-side variable API, `element.quark.setProperty()`, is modeled on `element.style.setProperty`.

### Smalltalk images

The unified-surface principle — the live system *is* the artifact, inspectable and serializable while it runs — has a lineage in Smalltalk's image-based environments, where no separate build product stands apart from the running state. ASO takes the same stance toward a web document.

### Template method

An Adapter's three customization surfaces — configuration attributes, events, and cancelable default actions — are the template method pattern expressed in markup: the Adapter owns the algorithm and exposes the hooks the author fills in.

### Native precedent

Letting listeners write into `event.detail` before a default action runs follows the platform's own `formdata`, `beforeunload`, and `respondWith` events. Booleans-as-attributes, `is-*` state, and tag-prefixed events extend conventions already present in HTML.

## A note on the name

"Adapter" is taken from ports and adapters and means the same thing here: the element that translates between the core — the document — and a protocol outside it, in either direction. The coordination literature to consult remains the blackboard literature; the participant literature is hexagonal architecture.

## Design patterns

ASO is not a re-cut of the Gang of Four taxonomy, but it is composed from its patterns the way the book's own introduction composes MVC from Observer, Composite, and Strategy. The State is a Composite — the document tree — whose serializability is a Memento. The Orchestrator is an Interpreter over that tree, coordinating as a Mediator and reacting as an Observer. Adapters are adapters in the structural sense, often Decorators of native elements (`super-*`) or Facades over a platform API, exposing their hooks through Template Method; `event-handler` is a Command invoker, and bubbling with cancelable default actions is Chain of Responsibility. Note what is absent: ASO assigns no creational pattern to the application — the platform parses and upgrades, the author writes the initial State — which is the no-components rule stated another way. One caution for GoF readers: ASO's *State* is the shared structure, not the behavioral State pattern; the closest thing to that pattern here is a Quark rule keyed on an attribute.

## Neighbors

Ideas ASO shares something with, and where the paths diverge:

- **Attribute-driven libraries** (HTMX, Alpine.js) also put behavior on HTML. HTMX's brain is the server: it swaps server-rendered fragments. Alpine embeds JavaScript expressions and component-like scopes in attributes. ASO keeps orchestration on the client, in a separate declarative language, with the document as the only state. It does not embed any foreign syntaxes into HTML.
- **Web component frameworks** (Lit and similar) use the same custom-element primitive but keep the component model: an element renders and manages its children from a template. ASO elements never do.
- **Flux / Redux / stores** centralize state outside the view and derive the view from it. ASO centralizes state *in* the view and nothing outside of it is treated as a source.
- **Elm / MVU** get predictability from a pure update function over an in-memory model. ASO gets it from declarative rules over a visible one.
- **MVC / MVVM** separate model from view and synchronize them. ASO has one surface and nothing to synchronize.

## What it is not

Not a virtual DOM. Not a component model. Not a store. Not a finite state machine. Not a build tool. It is a way of arranging responsibilities so the platform's own primitives — selectors, observers, custom elements, events, custom properties — can carry an application without a second copy of its state.


---

# Limitations

Below are the costs the Nucleus Stack currently accepts, stated directly, with the rationale for each and the practical response. Some limitations are temporary, some permanent, some by-design.

## May or may not play well with others

Works very well with all Custom Elements that follow the [Adapter](./adapter_state_orchestrator.md) pattern. They do not need to be constructed by Neutron. You can even import Quark by itself into your own Custom Element project, if that suits your fancy.

Nucleus Stack apps can always render other UI frameworks, not always the other way around:

Nucleus is not out-of-the-box compatible with certain other UI frameworks/libraries that lock the DOM to their own internal state, such as React. Many of these frameworks treat the DOM as a compilation target, not the source of truth as Nucleus does. Therefore, any changes Nucleus elements or Quark make to the DOM will be seen as "unreconciled" by the other framework and will be obliterated. If you seek to integrate the Nucleus Stack into an app of another UI framework, that framework MUST either allow untracked DOM changes, or you must use a Shadow DOM as a boundary between it and the Nucleus stack. The same boundary serves the other direction: when a sheet hands a region to a framework that needs sole authority over its DOM, a shadow root around that region keeps the two apart ([Handing rendering to a framework](/packages/quark/use#md-handing-rendering-to-a-framework)).

## Quark rules don't revert

The instant a CSS selector stops matching, the rule unapplies. Quark never does this. Attributes, content, listeners, variables, and CSS variables remain until some later rule overwrites them.

*Why.* The Orchestrator is not the owner of the document. An element, a script, or the user can write an attribute Quark doesn't own. Claiming a rule can be cleanly "unapplied" would overstate what Quark can promise. There is a real technical cost as well, but architectural honesty is what decided it.

*What to do.* For every state you leave, write the inverse rule. A future version may add reversion; do not build on that possibility.

## A Quark sheet is not a stylesheet

A Quark sheet that holds an at-rule Quark does not have (`@media`, `@keyframes`, `@supports`, …) fails to load.

*Why.* Quark is a derivative of CSS with a different runtime: a stylesheet paints, a Quark sheet writes State. Media queries, keyframes and the rest are features of the browser's style engine, and a Quark sheet paints nothing.

*What to do.* Keep them in your stylesheet, selecting on the same attributes the sheet writes.

## Writes are batched; events are not

Writes from the Orchestrator are gathered and flushed as a batch, so rules always read a settled element — and, as a result, writes are not aligned to frames. Events fire immediately and are never batched, because bubbling is inviolable: a listener still mid-bubble must be able to call `preventDefault()` or `stopPropagation()` against the actual world.

*Consequence.* Per-frame values are not a Quark job. Name the destination state and let CSS transitions, view transitions, or the Web Animations API own the motion. An animation describes change over time; State describes only the present, so animation has no place there.

`@view-transition` is the one place a write waits for the renderer: its writes land a rendering opportunity later, inside `document.startViewTransition()`. A document runs one view transition at a time — a route transition and a Quark one in the same moment cannot both animate, and Quark commits unanimated by default while another is active. `until` keeps the old state frozen on screen and delays the new capture, so use it for short waits, never for a fetch. Two elements sharing a `view-transition-name` abort the animation (the writes still land). Scoped, per-element transitions are not available yet in browsers, but this feature will likely utilize it in the future.

Element insertions under a Quark sheet's host are observed whoever makes them, so a widget that rebuilds its DOM every frame inside a host costs a rule pass per frame. Give such a widget a shadow root or an iframe, which Quark never enters.

## The DOM is proportional to your data

Any item that takes part in orchestration has to exist as an addressable node. Pairing `iterate()` with `include-content lazy-load` keeps each row's *cost* near zero until it enters the viewport, which is comfortable into the thousands. True virtualization — a recycled pool of rows windowed over a dataset — keeps node count proportional to the *viewport*; the out-of-the-box implementation does not do that. At six figures of rows, node count itself is the wall.

*What to do.* Page or filter within Quark before the iteration hits the document.

## No replay of past events

If a Quark sheet registers after an Adapter has already fired its connect-time events, those events are gone. Quark does not record or replay past events or past states on purpose: a replayed event cannot honor `preventDefault()` or `stopPropagation()`, so the replay would be a weaker, different event wearing the original's clothes.

*What to do.* Load sheets before the Adapters they listen to. Put `<quark-sheet>` first in its host. Prefer state attributes (`is-success`) over one-shot events for anything that can fire during boot. Attribute-driven rules are always safe, because the first run reads the settled document.

## Native form state is only half in the document

The platform keeps a form control's *default* in markup (`value`, `checked`, `selected`, a textarea's text) and its *live* state in JS properties that stop following the markup once the user touches the control. Quark hides the write half: an attribute a rule writes on `<input>` / `<option>` / `<textarea>` is pushed into the live property too, so the attribute stays authoritative and serializable. The read half stays with the platform: typing never updates an attribute, and the Orchestrator does not observe it. Reflect what you need through events (an `@on input { … }` block, `super-input reflect-value`) and select on that. A serialized document therefore holds what rules wrote, not what the user has typed since.

## Quark selector coverage & performance (in Beta)

Quark selectors do not observe state the DOM does not reflect: interaction and validity pseudo-classes (`:hover`, `:focus`, `:checked`, `:invalid`).

`:is()` / `:not()`, `:has()`, sibling combinators and structural pseudo-classes (`:nth-child()`, `:empty`) *are* observed, with two partial cases: `:empty` ignores text-only changes, and sibling-relative `:has(+ …)` / `:has(~ …)` re-runs the whole rule from the host.

`:has()` also costs a native subtree scan per candidate on every fan-out that includes the rule, so keep its arguments shallow and devoid of selectors that match many elements.

Classes and ids are observed, but 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 and compares class lists to find the ones it uses (`[class~="x"]` and `attr("class")` skip that filter and re-run on every change).

## Boundaries are absolute

A shadow root or iframe opens a new State root, with its own Orchestrator. Quark never crosses that line, and neither does CSS. That is what makes isolation trustworthy for embedded widgets, and it is also why the stack avoids shadow DOM by default: a boundary is a wall in both directions. Build one on purpose where a rendering framework must own a region alone ([Handing rendering to a framework](/packages/quark/use#md-handing-rendering-to-a-framework)).

## Nobody truly owns the document

Ownership in this ASO implementation is a discipline, not an enforcement. An element that writes a sibling's attribute will not be stopped. Rules are idempotent so that re-runs from unexpected writers stay harmless, but correctness still depends on participants honoring their regions.

*What to do.* Follow the Adapter contract. Keep script out of the state-writing business except through rules and elements. The inspector will show you if something is misbehaving.

## Runaway loops are cut, not prevented

Nothing stops you from writing two rules, two effects, or a rule and an element that keep re-triggering each other. What the stack does is bound the damage: every write an engine makes carries the depth of the chain that caused it, and the hop that would exceed `LoopGuard.limit` (50, from `@excom/kit-utils`) is dropped and reported once — in the console and, with DevTools attached, as an orchestration error naming the element and attribute. The document keeps the state it had before the dropped write. A chain restarts at zero on every external write (user input, a timer, a fetch, app JS in a later task), so a stream of updates never trips, however long it runs.

*Consequence.* A loop costs up to 50 passes before it dies, and the state it leaves behind is wherever the cycle happened to be. Writers the engines do not route — plain `setAttribute` or `innerHTML` in app JS — neither count nor get cut; a cycle made only of those is invisible. Rules that gate on attributes they write for each other are named in a build-time warning. Treat that and a "Loop guard" message as bugs to fix, not behavior to rely on.

## Prerendering happens at build time

[Prerendering](./prerendering.md) writes one static file per route when the site is built. There is no per-request rendering, so a page holds nothing that only a request knows: the person, a cookie, the hour. The renderer is happy-dom rather than a browser, one page at a time in one process, and it leaves `shadow` / `iframe` render hosts, `pre-fetch="idle"` fetches and the elements that read the device or the person to the browser.

*What to do.* Keep per-person content in elements that render in the browser, and look at a new page in a real browser: nucleus-ssr's [hydration test](/packages/nucleus-ssr#md-test-hydration) runs on happy-dom too.

## Commands need the Command API

Elements accept their imperatives as native `command` events (`<button command="--fetch" commandfor="…">`). That API is Baseline 2025 (Chrome 135, Firefox 144, Safari 26.2); older browsers ignore a `commandfor` button. `<event-handler command-name>`, `<dismiss-watcher command-name>` and script-built commands work everywhere, because the stack dispatches custom commands itself; only the built-in verbs (`show-modal`, `toggle-popover`) need the platform. Ship a Command API polyfill for older browsers, or use `<event-handler>` where it matters.

## Beta maturity

Quark is in beta. One item above (reversion) may change. Element APIs are stable in shape — attributes & commands in, events out — but individual packages evolve. Pin versions.

Some features will be broken for certain browsers whose versions are older than a year (mainly Firefox & Safari, mid-2025). This will be remedied in the first stable release.

## When not to use it

- Per-frame animation, canvas or WebGL-heavy scenes, and anything whose state is not naturally documentary.


---

# Roadmap

What is being worked on, what is queued behind it, and what is only an idea. No dates.

## Where it stands today

The Nucleus Stack is in **beta**. Breaking changes still land, and they land as removals rather than deprecations.

What is already settled:

- **The architecture.** [Adapter, State, Orchestrator](./adapter_state_orchestrator.md) is not up for major revision. The document is the state, elements bridge protocols, rules coordinate.
- **Element API shape.** Attributes in, events out, commands to invoke. Individual attributes come and go; the contract does not.
- **The zero-build path.** Serving files as-is is the default way to use the stack, not a degraded mode.

What "stable" will mean, when the beta ends: a **public API freeze** on the Quark language and on element attributes, events and commands, with semantic versioning honoured from that point on.

Until then: **pin your versions**, and read the change notes before you upgrade.

## Sooner

Work that is done or nearly done, landing in the next releases.

- **More elements in the catalog.** May include some of the following elements. Interaction: `content-sortable`, `content-splitter`, `content-popover`, `super-file-input`. Actions: `clipboard-copy`, `web-share`, `file-download`. Sensors: `detect-visibility`, `detect-size`, `detect-scroll`, `detect-document`, `detect-permission`. Providers: `provider-url-params`, `provider-sse`, `provider-websocket`, `provider-worker`.
- **Polyfills** Some features will be broken for certain browsers whose versions are older than a year (mainly Firefox & Safari, mid-2025). This will be remedied in the first stable release.
- **The small-bug backlog.** A coverage sweep across every package surfaced a list of minor defects. They are being triaged and fixed ahead of a stable release.
- **Sophisticated mobile features** These features - implemented via CSS and custom elements - will make a Nucleus app behave like a polished native app.
- **More themes for Valence.css.** Broader theme and scheme coverage, so a view's `--v-*` tokens carry further without custom CSS.
- **HTML/Quark "type checking"** Editor integration and optional build tool to raise warnings about unknown elements/attributes/provisions.

## Later

Wanted, thought about, not scheduled. Nothing here is a commitment.

- **Quark rule reversion & specificity.** There are open architectural and performance questions, not just an implementation cost. It is wanted. It is not scheduled. Do not build on it.
- **More of SSR.** Rendering per request, a worker pool for large sites (one renderer per process today), prerendered `shadow` / `iframe` render hosts, and a hydration check that runs in a real browser.
- **Optional build-time wins.** For teams who already run a bundler, shipping pre-parsed sheets would let the parser drop out of the runtime. Noted, not scheduled — and the zero-build path stays the default either way.
- **Scoped view transitions** When/if this lands in browsers, it is a very easy change to scope Quark's `@view-transition` rule.
- **A standards track.** If Quark finds real adoption, the intention is to draft a proposal for a native platform capability along these lines. See [Origin Story](./origin_story.md).

## How priorities get decided

When two good ideas compete, these break the tie.

- **Composability first.** If a change would make two pieces harder to combine, it does not land — even when it would be convenient. This is the reason there is no component concept and why elements never render or mutate children.
- **No cooperation required.** A mechanism that works on any element, including ones we did not write, beats a contract that only holds when everyone opts in.
- **If it is not in the document, it does not exist.** Features that route state or behaviour around the page are invisible to devtools, to serialisation and to every other sheet — which are the things the stack is for. Would rather not ship such a feature than ship one that hides state.

## How to influence it

Priorities here are set by what people actually hit, so the most useful thing you can send is a concrete case.

- **Report what broke.** [Open an issue](https://github.com/excom-dev/nucleus/issues) with the smallest HTML, CSS and Quark that reproduces it. A reduced case moves faster than anything else. Check [Troubleshooting](./troubleshooting.md) and [Limitations](./limitations.md) first — some surprises are documented trade-offs with a stated workaround.
- **Propose an element** by describing the protocol it bridges and why existing elements plus a Quark rule cannot already do it. [Contributing](./contributing.md) has the questions a proposal should answer.
- **Tell us what you had to write JavaScript for.** That is the single most valuable signal on this page. Every gap between "I could express this as a rule" and "I had to write a function" is a candidate for the language or the catalog, and the examples come from real applications, not from guessing.
- **Send a pull request.** Setup, conventions and what a reviewable change looks like are in [Contributing](./contributing.md).


---

# Contributing - help wanted!

How to get the monorepo running, what the conventions are, and what a reviewable pull request looks like.

The stack lives in one repository: [excom-dev/nucleus](https://github.com/excom-dev/nucleus). Every published package — the NucleusKit elements, Neutron, Quark, Valence.css — is a folder under `packages/`, managed by [Rush](https://rushjs.io) on top of pnpm.

## Getting set up

Node 24.13 or newer. Rush is invoked through the checked-in bootstrap script, so there is nothing to install globally.

```bash
git clone https://github.com/excom-dev/nucleus.git
cd nucleus
node common/scripts/install-run-rush.js install
node common/scripts/install-run-rush.js build
```

If you have Rush on your `PATH`, `rush install` and `rush build` are the same thing. `rush build` is incremental and cached: after the first run it only rebuilds what changed.

## Working in one package

Rush's per-package selection is the fast path. From inside `packages/<name>`, the package's own scripts do everything:

| Command | What it does |
| --- | --- |
| `pnpm run build` | Build that package's entry points |
| `pnpm run test` | Vitest, in happy-dom |
| `pnpm run coverage` | Tests plus a coverage report — fails below 90% on any metric. Only the package's own files count; a file no test loads counts as 0% |
| `pnpm run format` | Prettier over the package |
| `pnpm run dev` | Dev server, where the package has one |

Repo-wide equivalents exist as Rush commands (`rush test`, `rush coverage`, `rush format`), and `--to` / `--from` scope them to a dependency graph. Prefer the package-level script while you are iterating — it is the tightest loop.

Tests run in **happy-dom**, never a real browser. Everything in the stack is DOM work, so a test is usually "build a fragment, register a sheet or an element, assert on attributes".

## Package layout

```
packages/my-element/
  index.ts              # entry: defines and globally types every element here
  index.css             # entry: imports each element's CSS
  my-element.ts         # one source file per element
  my-element.css
  src/                  # helpers; not built as entry points
  support/
    docs/               # README.md and any further pages
    demos/              # one .html per demo, no JS
    tests/              # one <name>.test.ts per source file, one <demo>.view.test.ts per demo
  package.json          # needs to contain config common to other packages, such as `excom` object
```

Files in the package root become build entry points; files under `src/` do not. `dist/`, `coverage/`, `CHANGELOG.md` and the generated docs metadata are all produced by the tooling and are not committed. `CHANGELOG.json` is written by Rush on publish; never edit it by hand.

The checked-in `.vscode/settings.json` hides the per-package boilerplate (`config/`, `tsconfig.json`, `CHANGELOG.json`, generated metas) from the VS Code explorer and search.

## Conventions

These are the rules reviewers apply. [Best Practices](./best_practices.md) covers the reasoning; this is the short version for contributors.

**Elements**

- **Single responsibility.** One job, configurable, observable, generic. `content-drawer` is good; `add-to-cart` is not — business behaviour belongs to app authors' Quark sheets, not to the element catalog.
- **Never render or mutate children.** Composition is the design. The exception is an element whose *entire* purpose is logicless rendering of author-supplied markup, like `include-content`, and that has to be stated in its docs.
- **Dashed attributes.** Every custom attribute contains a dash (`listen-for`, `data-duration`, `is-open`), so it can never collide with a native attribute now or later. That applies to reflected state props too.
- **Tag-prefixed events.** `my-element-change`, never `change`.
- **Imperatives are commands.** Accept "do this" as a native `command` event with a short `--verb`, so a plain `<button command="--open" commandfor="id">` can drive it. Never a bubbling `my-element-trigger` event.
- **Underscore private members**, and keep the imperative surface small.
- **No Shadow DOM** unless isolation is genuinely the point. It walls off the very rules that make the stack composable.
- **Own your region.** An element writes its own attributes and those of the other elements in its family. Nothing else.

**Neutron lifecycles**

Keep them functional. Destructure the element argument, and return an effect rather than mutating:

```ts
onConnected: ({ isOpen }) => ({ ariaExpanded: String(isOpen) });
```

Not `(el) => { el.ariaExpanded = …; }`. Async work that needs current state belongs in a `defineMethods` method, which receives the live element. Never hold a hard reference to another element; use `WeakRef` and clear it in `onDisconnected`.

**CSS**

Modern CSS — nesting, `@scope`, `:has()`, container queries. Classes carry static flavour only (`details.accordion`); dynamic state is an attribute. Expose `--v-*` tokens so themes reach the element.

## Docs and demos

Every published package documents itself under `support/docs/`. The API reference is generated from code comments, so the prose you write is the intro, the features list and the usage:

- **README.md** — title, a one-sentence pitch, a demo, `Features`, `Usage`. Keep it terse; the features list is what a prospective app author reads first, so use the words they would search for.
- **Further pages** when the reference outgrows one screen. A `support/docs-sections.json` groups them into sidebar sections.
- **Links between pages** are plain relative markdown (`[Props](./PROPS.md)`, `[Styling](./styling.md)`). They work on GitHub, and the pipeline rewrites them for the site. Never hand-write `<spa-a>` in markdown.
- **`INTERNAL.md`** is a contributor file. It is never rendered or published.

How these pages become package metas, the custom elements manifest, `dist-docs/` and `llms.txt`: [the docs pipeline](https://github.com/excom-dev/nucleus/blob/main/support/docs/DOCS_PIPELINE.md). All of it is generated and none of it is committed.

Demos live in `support/demos/<name>.html`: one root element, no embedded JavaScript, the smallest markup that shows the point. Anything a demo needs but a reader does not (layout padding, colours) goes in the docs site's `demo-utils.css`. Four demos is plenty for a small package, eight for a large one.

## Proposing an element

Open a discussion before writing code. A proposal is easier to accept when it answers:

1. **What one protocol does it bridge?** A network, a store, a sensor, the clock, or a person's interaction. If the answer has an "and" in it, it may be two elements. See [Adapter, State, Orchestrator](./adapter_state_orchestrator.md).
2. **What is its state, as attributes?** Writing those attributes by hand should reproduce what the protocol would have done.
3. **What does it announce, as events?** And which imperatives does it accept, as commands?
4. **Why can existing elements plus a Quark rule not already do this?** Composition of what exists always beats a new tag.

Elements stay generic. If the idea only makes sense for one application, it is a [view](./building_views.md), and views belong to their authors.

## Change files

Every publishable package touched by a pull request needs a Rush change file. From the repo root, after committing:

```bash
node common/scripts/install-run-rush.js change
```

Rush compares your branch against `main`, prompts once per affected package, and writes JSON into `common/changes/@excom/<package>/`. Commit those files too — CI runs `rush change --verify` and only counts what is committed.

Pick the bump honestly:

| Type | When |
| --- | --- |
| `major` | A public attribute, event or export was removed or renamed; existing markup or listeners break |
| `minor` | New public capability — an attribute, an event field, an export |
| `patch` | A fix or internal improvement with the same public contract |
| `none` | Docs, demos or tests only |

The comment is published documentation — every type but `none` appears in the package's release notes, on the site and in the LLM docs — so write it for an app author who has never seen the implementation. Ask what it means to them: does it break them, fix something that annoyed them, give them something new to try?

- Imperative mood, starting with a verb — Add, Remove, Fix an issue where, Improve, Update, Upgrade, Initial release of.
- The outcome ("Searching now supports wildcards"), not the diff ("Add regex support to `SearchHelper`").
- Backticks around public names; `name()` for functions.
- Upgrades name both versions: Upgrade `happy-dom` from 15 to 20.
- "Issue", never "bug"; link the GitHub issue in parentheses when there is one.
- No acronyms or shorthand beyond the widely known (HTTP, CSS), and nothing private.
- No trailing period on a single sentence.

Removals are removals. The stack does not currently ship deprecation windows or compatibility shims; a dropped feature has its code, grammar, tests and docs deleted, and the API rejects it with a clear error. Record it as `major` and that is the migration story.

## Pull requests

Target `main`. CI installs the workspace and then, for every package your branch touches, runs the build and the coverage suite, verifies change files, and comments bundle sizes and coverage on the pull request.

Before you open one:

- [ ] Tests for the behaviour you added, next to the source file they cover
- [ ] Coverage still at or above 90% for the package
- [ ] `pnpm run format` run in each package you touched
- [ ] Docs updated — attribute and event comments, the features list if the pitch changed, a demo if it is a headline capability
- [ ] A committed change file per publishable package
- [ ] Custom attributes dashed, events tag-prefixed, imperatives as commands

Keep the pull request to one story. A rename and a new option are two change-file entries and, usually, two pull requests.

## Reporting issues

Bugs and feature requests go to [the issue tracker](https://github.com/excom-dev/nucleus/issues). A reduced case beats a description: the smallest HTML, CSS and Quark that reproduces it, plus what you expected. Check [Troubleshooting](./troubleshooting.md) and [Limitations](./limitations.md) first — several surprising behaviours are documented trade-offs with a stated workaround.

## Code of conduct

Be decent to each other. Assume good faith, critique the code rather than the person, and accept that a maintainer may say no to a feature that would cost composability. Conduct concerns can be raised privately with the maintainers through the issue tracker.


---

# abortable-element

AbortController ownership for Neutron elements — cancel in-flight
work cleanly when a newer request supersedes it.

## Features

- **Owned controller** Fresh `AbortController` per in-flight cycle
- **doAbort()** Abort current work and rotate a new controller
- **Fetch-ready** Pass `abortController.signal` into `fetch` /
  template loads

## Installation


`@excom/abortable-element` v0.1.4

```bash
pnpm add @excom/abortable-element
```

```bash
npm install @excom/abortable-element
```

```bash
yarn add @excom/abortable-element
```

### Import

```ts
import { /* … */ } from "@excom/abortable-element";
```



## Usage

Compose `AbortableElement` and pass `abortController.signal` into
async work. Call `doAbort()` when that work should be cancelled (e.g.
`template-ref` changed). `RenderableElement` already does this for
template fetches.

```ts
import { Neutron } from "@excom/neutron";
import { AbortableElement } from "@excom/abortable-element";

export const FetchOnce = Neutron.compose([
  AbortableElement,
  Neutron({
    tag: "fetch-once",
    props: { src: String },
  }),
])
  .onPropChanged("src", async (el) => {
    el.doAbort();
    if (!el.src) return;
    const res = await fetch(el.src, {
      signal: el.abortController.signal,
    });
    // …
  });

FetchOnce.define();
```

There are no public attributes — the controller is internal. See
[renderable-element](/packages/renderable-element) for the primary
consumer.

### API Reference

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# content-carousel

Rotate slides on autopilot or on click — galleries, hero banners, walkthroughs.


```html
<section>
  <content-carousel auto-play="1.5">
    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
  </content-carousel>
</section>
```


## Features

- **Auto-play** Rotate on a timer via `auto-play`
- **Manual nav** `--back` / `--next` commands from plain buttons; `rel="prev"` / `rel="next"` positions them
- **Slide or fade** Choose the transition with `slide-animation`: `slide` / `fade` / `track`
- **Swipeable** `slide-animation="track"` wrapped in [`gesture-handler`](/packages/gesture-handler): drag and flick between slides
- **Pauses itself** Manual navigation stops auto-play automatically
- **Bindable position** `.provision` is `{ index, count, lastMove }` — a
  progress readout is one Quark rule on `prop("provision")`

## Installation


`@excom/content-carousel` v0.1.4

```bash
pnpm add @excom/content-carousel
```

```bash
npm install @excom/content-carousel
```

```bash
yarn add @excom/content-carousel
```

### Import

```ts
import "@excom/content-carousel";
```



## Usage

Wrap `<content-carousel-slide>` elements in a `<content-carousel>`. Mark one
`is-active`, or leave it unset to default to the first.

```html
<content-carousel auto-play="5">
  <content-carousel-slide is-active>One</content-carousel-slide>
  <content-carousel-slide>Two</content-carousel-slide>
  <content-carousel-slide>Three</content-carousel-slide>
</content-carousel>
```

`.provision` is `{ index, count, lastMove }` — set on connect and after every slide change (a command, auto-play, a slide added / removed, `is-active` written on a slide), counting only this carousel's own slides. A "2 / 3" readout:

```quark
content-carousel {
  $slide: prop("provision").index + 1;
  $count: prop("provision").count;
  [bind-progress] { content: "#{$slide} / #{$count}"; }
}
```

Nothing animates until the first move: `last-move` is unset until then, so an initial `is-active`, in markup or written by the app, appears in place. `slide-animation="track"` renders only the active slide and its two DOM neighbours, so slides must be siblings (a `display: contents` wrapper around them is fine) and, with three or more slides, a wrap — `--next` from the last, `--back` from the first — cuts to the new slide instead of sliding; put it inside [`gesture-handler`](/packages/gesture-handler) to drag it.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `auto-play` | option | `number` |  |  | Seconds between automatic slide advances. Unset disables auto-play. |
| `is-scrubbing` | option | `boolean` |  |  | Set when the element is being dragged. Used by CSS only to disable `transition`. |
| `slide-animation` | option | `string` | `"slide"` | `"slide"` \| `"fade"` \| `"track"` | Transition used when the active slide changes. |
| `last-move` | state | `string` |  | `"forward"` \| `"back"` | Direction of the most recent slide change — drives the CSS animation direction. `is-active` moved from one slide to another counts as `forward` / `back` by position. Unset until the first move, so the initial slide appears without animating in. |
| `auto-play-stopped` | hybrid | `boolean` |  |  | Set automatically after manual navigation, or when the element leaves the document (a DOM move keeps auto-play running), to pause auto-play. Set it directly to pause / resume auto-play programmatically. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `ContentCarouselProvision` (`{ index: number; count: number; lastMove: "forward" \| "back" \| null; }`) | Position: `{ index, count, lastMove }` — the active slide's index among this carousel's own slides, how many there are, and the direction of the last move. Set on connect and after every change, including slides added / removed and `is-active` written on a slide. Not reflected as an attribute. |

#### Recognized Elements

| Relationship | Selector | Required | Description |
| --- | --- | --- | --- |
| `content-carousel-slide` | descendant | yes | Slides to rotate through. The first, or whichever has `is-active`, is shown initially. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `content-carousel-slide-changed` | `ContentCarouselSlideChangedEvent` (`CustomEvent & { type: "content-carousel-slide-changed"; detail: { activeSlide: HTMLElement \| null; previousSlide: HTMLElement \| null; }; bubbles: true; cancelable: true; composed: true }`) | After any slide change: a command, auto-play, or `is-active` moved from one slide to another (a swipe). |

#### Commands

| Command | Action |
| --- | --- |
| `--back` | Shows the previous slide (wraps to last). Stops auto-play. |
| `--next` | Shows the next slide (wraps to first). Stops auto-play. |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--content-carousel-slide-animation-duration` | `<time>` | `0.25s` | Length of the slide / fade transition. |
| `--content-carousel-transition-ease` | `<easing-function>` | `ease-out` | Easing used for the fade transition. |
| `--content-carousel-button-size` | `<length>` | `25px` | Min-width of the nav buttons. |
| `--content-carousel-progress` | `<number>` | `0` | `slide-animation="track"` only: how far the track is dragged, in slide widths — `1` shows the next slide, `-1` the previous. While `is-scrubbing` it follows a wrapping `<gesture-handler>`'s inherited `--gesture-progress` unless set explicitly — swipeable carousels. |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.tag-content-carousel-prev` | Positions a direct child with `rel="prev"` (or `.tag-content-carousel-prev`) as the "previous slide" nav control. |
| `.tag-content-carousel-next` | Positions a direct child with `rel="next"` (or `.tag-content-carousel-next`) as the "next slide" nav control. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--content-carousel` | element | `content-carousel`, `.tag-content-carousel` |  |
| `:--content-carousel--last-move` | state | `[last-move]`, `[data-last-move]` |  |
| `:--content-carousel--last-move-forward` | state | `[last-move="forward"]`, `[data-last-move="forward"]` |  |
| `:--content-carousel--last-move-back` | state | `[last-move="back"]`, `[data-last-move="back"]` |  |
| `:--content-carousel--slide-animation` | state | `[slide-animation]`, `[data-slide-animation]` |  |
| `:--content-carousel--slide-animation-slide` | state | `[slide-animation="slide"]`, `[data-slide-animation="slide"]` |  |
| `:--content-carousel--slide-animation-fade` | state | `[slide-animation="fade"]`, `[data-slide-animation="fade"]` |  |
| `:--content-carousel--slide-animation-track` | state | `[slide-animation="track"]`, `[data-slide-animation="track"]` |  |
| `:--content-carousel--is-scrubbing` | state | `[is-scrubbing]`, `[data-scrubbing]` |  |



### Examples

#### Manual navigation

Invoke `--back` / `--next` from a `<button command commandfor>`. A direct
child with `rel="prev"` / `rel="next"` (or
`.tag-content-carousel-prev` / `.tag-content-carousel-next`) is
positioned as the nav control for you. If you want swipeable slides, you
must use the carousel in conjunction with the [<gesture-handler>](/packages/gesture-handler).
A demo exists on that page.


```html
<section>
  <content-carousel id="demo-carousel-manual">
    <button type="button" rel="prev" command="--back" commandfor="demo-carousel-manual">‹</button>
    <button type="button" rel="next" command="--next" commandfor="demo-carousel-manual">›</button>
    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
  </content-carousel>
</section>
```


#### Fade transition

`slide-animation="fade"` crossfades instead of sliding.


```html
<section>
  <content-carousel auto-play="1.5" slide-animation="fade">
    <content-carousel-slide is-active><h2>One</h2></content-carousel-slide>
    <content-carousel-slide><h2>Two</h2></content-carousel-slide>
    <content-carousel-slide><h2>Three</h2></content-carousel-slide>
  </content-carousel>
</section>
```

## Release notes

### 0.1.3 (2026-10-01)

- Track mode hides every slide beyond the active slide's neighbours and no longer animates the first slide into place

### 0.1.2 (2026-09-30)

- Auto-play tests poll for the advanced slide instead of sleeping a fixed 80 ms (flaked on loaded CI runners); no runtime change
- Fix an issue where `provision` did not follow slides added or removed, and `last-move` and `content-carousel-slide-changed` did not follow `is-active` moving from one slide to another (a swipe): each change sets one provision, and a carousel moved in the DOM no longer sets it again
- Update the internal `autoPlayIntervalId` property to `_autoPlayIntervalId`, as its other private properties are named; it was never an attribute, so markup is unaffected

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<content-carousel-slide>`

> One rotating slide of a content-carousel.

**Tag:** `<content-carousel-slide>`

## API

### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-active` | hybrid | `boolean` |  |  | Marks this as the currently shown slide. The parent `<content-carousel>` keeps exactly one slide active. Write it directly (a swipe) and the carousel's `provision`, `last-move` and slide-changed event follow. |

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--content-carousel-slide` | element | `content-carousel-slide`, `.tag-content-carousel-slide` |  |
| `:--content-carousel-slide--is-active` | state | `[is-active]`, `[aria-current]` |  |


---

# content-drawer

Slide-in drawers and sheets for nav menus, filters, confirmations, and side panels — any edge, with peek stages.


```html
<section>
  <button type="button" command="--toggle" commandfor="demo-drawer-simple">
    Toggle sheet
  </button>
  <content-drawer id="demo-drawer-simple" class="absolute">
    <header>
      <button type="button" rel="prev" command="--close" commandfor="demo-drawer-simple" aria-label="Close"></button>
      <h2>Sheet open</h2>
    </header>
  </content-drawer>
  <event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
</section>
```


## Features

- **Any edge** Bottom (default), top, left, or right via `from-side`
- **Peek stages** Full, half, or peek via `open-stage`
- **Command-driven** `--open` / `--close` / `--toggle` from any `<button command commandfor>`
- **Dismissal** Outside click + Escape via `<dismiss-watcher>`
- **Backdrop** Valence.css dimmer — sibling `[role="presentation"]` / `.tag-backdrop`
- **Auto-dismiss** `disappear-after` for toast-style confirmations
- **Singleton groups** One open drawer per `singleton-name`
- **Layout modes** Viewport sheet (default, `position: fixed`), `.absolute` (inside its parent), `.relative`, or `.sticky`
- **Scrubbable** Wrap in [`gesture-handler`](/packages/gesture-handler): the sheet follows the finger via `is-scrubbing` + `--content-drawer-open-progress`

## Installation


`@excom/content-drawer` v0.2.2

```bash
pnpm add @excom/content-drawer
```

```bash
npm install @excom/content-drawer
```

```bash
yarn add @excom/content-drawer
```

### Import

```ts
import "@excom/content-drawer";
```



## Usage

Put content inside `<content-drawer>` and invoke `--open`, `--close`, or `--toggle` on it — a native `<button command commandfor>`, or `<event-handler command-name target-ref>` when the invoker is not a button. The parent of an `.absolute` drawer becomes `position: relative; overflow: clip`, so give that parent a real size along the drawer's axis.

```html
<button type="button" command="--toggle" commandfor="sheet">Toggle sheet</button>
<content-drawer id="sheet" class="absolute">
  <h2>Saved!</h2>
</content-drawer>
<event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
```

The backdrop never reads the drawer's own variables: set `--content-drawer-transition-duration`, `--content-drawer-transition-ease` and `--content-drawer-overlay-z-index` on the parent, the backdrop or `:root`. After its slide-out a closed drawer is `visibility: hidden`, so a custom `transition` on it must keep `visibility 0s <duration>`.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `from-side` | option | `string` | `"bottom"` | `"bottom"` \| `"top"` \| `"left"` \| `"right"` | Edge the drawer slides from. |
| `disappear-after` | option | `number` |  |  | Auto-close after this many seconds once opened — toast-style / transient confirmations. |
| `singleton-name` | option | `string` |  |  | Shared group name. Opening one drawer closes others with the same name (singleton coordination). |
| `open-stage` | hybrid | `number` |  | `"0"` \| `"1"` \| `"2"` | How far the drawer opens: `0` full, `1` half, `2` peek. Unset = full. Set statically, or per open through `data-open-stage` on the `--open` / `--toggle` invoker. |
| `is-open` | hybrid | `boolean` |  |  | Open state. Toggle directly, or through the `--open` / `--close` / `--toggle` commands. For Escape / outside-click dismissal pair with `<dismiss-watcher command-name="--close">`. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `content-drawer-opened` | `ContentDrawerOpenedEvent` (`CustomEvent & { type: "content-drawer-opened"; detail: HTMLElement; bubbles: true; cancelable: true; composed: true }`) | After open (`is-open` set), `detail` is the drawer. When `singleton-name` is set it is also broadcast so drawers sharing that name close. |
| `content-drawer-closed` | `ContentDrawerClosedEvent` (`CustomEvent & { type: "content-drawer-closed"; detail: HTMLElement; bubbles: true; cancelable: true; composed: true }`) | After close (`is-open` unset), `detail` is the drawer. |

#### Commands

| Command | Action |
| --- | --- |
| `--open` | Opens the drawer (`is-open` set). `data-*` attributes on the invoker that name a declared prop (`data-open-stage`, `data-from-side`, …) are applied first; unknown, private and `isOpen` keys are ignored. |
| `--close` | Closes the drawer (`is-open` unset). |
| `--toggle` | Toggles open / closed. Reads the invoker's `data-*` like `--open`. |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--content-drawer-transition-duration` | `<time>` | `0.25s` | Slide and backdrop fade duration. Set on the parent, the backdrop or `:root`: the backdrop never reads the drawer's own value. |
| `--content-drawer-transition-ease` | `<easing-function>` | `ease-out` | Slide and backdrop fade easing. Set on the parent, the backdrop or `:root`: the backdrop never reads the drawer's own value. |
| `--content-drawer-closed` | `<percentage>` | `101%` | Off-screen translate amount (closed). |
| `--content-drawer-open-full` | `<percentage>` | `0%` | Full-open translate (`open-stage` unset or `0`). |
| `--content-drawer-open-half` | `<percentage>` | `50%` | Half-open translate (`open-stage="1"`). |
| `--content-drawer-open-peek` | `<percentage>` | `75%` | Peek translate (`open-stage="2"`). |
| `--content-drawer-relative-max-width` | `<length>` | `200px` | Max width when open in `.relative` mode, used unless `--content-drawer-max-width` is set. |
| `--content-drawer-z-index` | `<integer>` | `3` | Stack order for the drawer panel. |
| `--content-drawer-overlay-z-index` | `<integer>` | `2` | Stack order for the sibling backdrop (`:--dialog-backdrop-aliases`). Set on the parent, the backdrop or `:root`, not on the drawer. |
| `--content-drawer-open-progress` | `<number>` | `var(--gesture-progress, 0)` | How far open the drawer is while `is-scrubbing`: `0` closed, `1` full. Declared on the drawer (not `:root`) so it follows a wrapping `<gesture-handler>`'s inherited `--gesture-progress` unless set explicitly — a swipe-to-open / drag-to-close bottom sheet. |
| `--content-drawer-max-width` | `<length>` |  | Overrides `--content-drawer-relative-max-width` for this drawer only. |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.close` | Close control — empty `.close` / `[rel="prev"]` button or link (theme close icon). |
| `.sticky` | `position: sticky` instead of the default `fixed` placement. |
| `.absolute` | `position: absolute` instead of the default `fixed` placement — a sheet inside its parent, which becomes `position: relative; overflow: clip`. |
| `.relative` | In-flow mode: the drawer participates in layout and animates `max-width` instead of overlaying via `position`, pushing sibling content aside as it opens. Currently only affects `from-side="left"`. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--content-drawer` | element | `content-drawer`, `.tag-content-drawer` |  |
| `:--content-drawer--is-open` | state | `[is-open]`, `[aria-expanded="true"]` |  |
| `:--content-drawer--is-scrubbing` | state | `[is-scrubbing][is-scrubbing]`, `[data-scrubbing][data-scrubbing]` |  |
| `:--content-drawer--open-stage-1` | state | `[open-stage="1"]`, `[data-open="1"]` |  |
| `:--content-drawer--open-stage-2` | state | `[open-stage="2"]`, `[data-open="2"]` |  |
| `:--content-drawer--from-side` | state | `[from-side]`, `[data-placement]` |  |
| `:--content-drawer--from-side-bottom` | state | `[from-side="bottom"]`, `[data-placement="bottom"]` |  |
| `:--content-drawer--from-side-top` | state | `[from-side="top"]`, `[data-placement="top"]` |  |
| `:--content-drawer--from-side-left` | state | `[from-side="left"]`, `[data-placement="left"]` |  |
| `:--content-drawer--from-side-right` | state | `[from-side="right"]`, `[data-placement="right"]` |  |



### Examples

#### Peek stages

`--open` with `data-open-stage` on the button sets the stage — `0` full, `1` half, `2` peek. The exact heights of each stage are configurable through CSS variables.


```html
<section>
  <button type="button" command="--open" commandfor="demo-drawer-stages" data-open-stage="0">
    Full (100%)
  </button>
  <button type="button" command="--open" commandfor="demo-drawer-stages" data-open-stage="1">
    Half (50%)
  </button>
  <button type="button" command="--open" commandfor="demo-drawer-stages" data-open-stage="2">
    Peek (25%)
  </button>
  <content-drawer id="demo-drawer-stages" class="absolute">
    <header>
      <button type="button" rel="prev" command="--close" commandfor="demo-drawer-stages" aria-label="Close"></button>
      <h2>Open stages</h2>
    </header>
    <p>Full / half / peek via <code>data-open-stage</code> on the button.</p>
  </content-drawer>
</section>
```


#### Dismissal

`<dismiss-watcher command-name="--close">` as the drawer's first child closes it on outside click or Escape / back gesture; the sheet gates its `is-active` on `content-drawer[is-open]` (with the inverse rule). Open with `--open`, not `--toggle` — an outside `mouseup` on the button closes first, the `click` then re-opens. Immediate next sibling `[role="presentation"]` / `.tag-backdrop` is the Valence.css modal dimmer; `<event-handler command-name="--close">` on that node closes on click.


```html
<section>
  <quark-sheet>
    :scope {
      content-drawer[is-open] dismiss-watcher { is-active: ""; }
      content-drawer:not([is-open]) dismiss-watcher { is-active: none; }
    }
  </quark-sheet>
  <button type="button" command="--open" commandfor="demo-drawer-dismiss">
    Open drawer
  </button>
  <content-drawer id="demo-drawer-dismiss" class="absolute">
    <dismiss-watcher watch-escape watch-outside-click command-name="--close"></dismiss-watcher>
    <nav>Menu</nav>
  </content-drawer>
  <event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
</section>
```


#### Side drawer

`from-side` slides from left / right / top instead of the default bottom.


```html
<section>
  <button type="button" command="--toggle" commandfor="demo-drawer-side">
    Toggle drawer
  </button>
  <content-drawer id="demo-drawer-side" class="absolute" from-side="left">
    <nav>Menu</nav>
  </content-drawer>
  <event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
</section>
```


#### Auto-dismiss

`disappear-after` closes the drawer after N seconds — useful for success toasts.


```html
<section>
  <button type="button" command="--open" commandfor="demo-drawer-disappear">
    Show success
  </button>
  <content-drawer id="demo-drawer-disappear" class="absolute" disappear-after="2">
    <h2>Saved!</h2>
  </content-drawer>
</section>
```


#### Singleton group

Drawers sharing `singleton-name` — opening one closes the other.


```html
<section>
  <button type="button" command="--open" commandfor="drawer-a">Open A</button>
  <button type="button" command="--open" commandfor="drawer-b">Open B</button>
  <content-drawer id="drawer-a" class="absolute" singleton-name="demo">
    <header>
      <button type="button" rel="prev" command="--close" commandfor="drawer-a" aria-label="Close"></button>
      <h2>Drawer A</h2>
    </header>
  </content-drawer>
  <content-drawer id="drawer-b" class="absolute" singleton-name="demo">
    <header>
      <button type="button" rel="prev" command="--close" commandfor="drawer-b" aria-label="Close"></button>
      <h2>Drawer B</h2>
    </header>
  </content-drawer>
</section>
```

## Release notes

### 0.2.0 (2026-09-30)

- Update `content-drawer` so only an `.absolute` drawer styles its parent, as `position: relative; overflow: clip` (was every drawer, with `overflow: hidden`): a fixed or sticky drawer no longer clips its parent, and sticky descendants keep working
- Update a closed `content-drawer` to be `visibility: hidden` once its slide-out ends, taking it out of the tab order and the accessibility tree: a custom `transition` on a closed drawer must keep `visibility 0s <duration>`, and a closed drawer shown in the layout needs `visibility: visible`

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# content-tabs

Tabs and accordions — single, multi, or toggle selection, paired by name
or position.


```html
<content-tabs class="underline">
  <content-tabs-header is-open>Overview</content-tabs-header>
  <content-tabs-header>Details</content-tabs-header>
  <content-tabs-header>Settings</content-tabs-header>
  <content-tabs-body is-open><p>Overview copy goes here.</p></content-tabs-body>
  <content-tabs-body><p>Details copy goes here.</p></content-tabs-body>
  <content-tabs-body><p>Settings copy goes here.</p></content-tabs-body>
</content-tabs>
```


## Features

- **Single / multi / toggle** Radio-like tabs, an accordion, or re-click
  to close
- **Pair by name or position** Match headers to bodies with `tab-name`,
  or by index when unnamed
- **Isolated nesting** Nested `<content-tabs>` groups never cross-wire
- **Bindable state** `.provision` is `{ tabType, openTabs, activeTab }` —
  read the active tab from Quark with `prop("provision")`
- **Included looks** `.underline` and `.file-tabs` styles ship built in

## Installation


`@excom/content-tabs` v0.1.4

```bash
pnpm add @excom/content-tabs
```

```bash
npm install @excom/content-tabs
```

```bash
yarn add @excom/content-tabs
```

### Import

```ts
import "@excom/content-tabs";
```



## Usage

Put `<content-tabs-header>` and `<content-tabs-body>` elements inside
`<content-tabs>`. A header pairs with the body sharing its `tab-name`,
or by position when both are unnamed.

```html
<content-tabs class="underline">
  <content-tabs-header is-open>Overview</content-tabs-header>
  <content-tabs-header>Details</content-tabs-header>
  <content-tabs-body is-open><p>Overview copy.</p></content-tabs-body>
  <content-tabs-body><p>Details copy.</p></content-tabs-body>
</content-tabs>
```

The open state is a fact, not just an event: `.provision` holds
`{ tabType, openTabs, activeTab }`, where a tab is its header's `tab-name`
(or its index when unnamed) and `activeTab` is the first open one. Quark
reads it on the group and binds it anywhere below:

```quark
content-tabs {
  $tab: prop("provision").activeTab;
  h2 { content: $tab; }
}
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `tab-type` | option | `string` | `"single"` | `"single"` \| `"multi"` \| `"toggle"` | Selection mode. `single` opens one header at a time (radio-like); `multi` allows any number open at once (accordion); `toggle` is like `single`, but re-clicking the open header closes it. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `ContentTabsProvision` (`{ tabType: string \| null; openTabs: Array<string \| number>; activeTab: string \| number \| null; }`) | Open state: `{ tabType, openTabs, activeTab }`. A tab is its header's `tab-name`, or its index among this group's own headers when unnamed; `activeTab` is the first open one (`null` when none). Set after mount and after every header change (batched with the body sync). Not reflected as an attribute. |

#### Recognized Elements

| Relationship | Selector | Required | Description |
| --- | --- | --- | --- |
| `content-tabs-header` | child | yes | Clickable tab headers. |
| `content-tabs-body` | child | yes | Panels shown / hidden to match their header. |

#### Listens for

| Name | Type | Description |
| --- | --- | --- |
| `content-tabs-header-opened` | `ContentTabsHeaderOpenedEvent` (`CustomEvent & { type: "content-tabs-header-opened"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Closes sibling headers when `tab-type` is `single` (default) or `toggle`. |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--content-tabs-border-color` | `<color>` | `var(--v-muted-border-color, currentColor)` | Border color for `.file-tabs` headers / bodies. |
| `--content-tabs-border-width` | `<length>` | `var(--v-border-width, 2px)` | Border width for `.file-tabs` headers / bodies. |
| `--content-tabs-color-active` | `<color>` | `var(--v-color-primary, inherit)` | Text color for the active header in `.underline`. |
| `--content-tabs-header-padding` | `<length>{1,4}` | `10px 15px` | Padding for each header. |
| `--content-tabs-body-padding` | `<length>{1,4}` | `var(--v-spacing, 15px)` | Padding for each body in `.file-tabs`. |
| `--content-tabs-active-indicator-height` | `<length>` | `2px` | Height of the `.file-tabs` active-tab accent bar. |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.file-tabs` | File-explorer look — headers render as bordered folder tabs joined to the active body. |
| `.underline` | Paper / underline look — the active header gets a bottom accent border instead of a bordered card. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--content-tabs` | element | `content-tabs`, `.tag-content-tabs` |  |
| `:--content-tab--is-open` | state | `[is-open]`, `[aria-selected="true"]` |  |



### Examples

#### File tabs

`.file-tabs` renders each header like a folder tab, joined to its body.


```html
<content-tabs class="file-tabs">
  <content-tabs-header is-open>index.ts</content-tabs-header>
  <content-tabs-header>utils.ts</content-tabs-header>
  <content-tabs-body is-open><pre>export const value = 1;</pre></content-tabs-body>
  <content-tabs-body><pre>export const double = (n) => n * 2;</pre></content-tabs-body>
</content-tabs>
```


#### Multi-select accordion

`tab-type="multi"` lets any number of headers stay open — clicking one does not close the others. Also displayed are the tab headers as buttons, if using Valence.css.

Useful for building your own UI toggle systems.


```html
<content-tabs tab-type="multi">
  <content-tabs-header is-open role="button">Shipping</content-tabs-header>
  <content-tabs-header role="button">Billing</content-tabs-header>
  <content-tabs-body is-open><p>Ships in 3-5 business days.</p></content-tabs-body>
  <content-tabs-body><p>Charged on shipment, not on order.</p></content-tabs-body>
</content-tabs>
```


#### Pair by tab-name

Give a header and body matching `tab-name` values to pair them regardless of their order in the DOM.


```html
<content-tabs class="underline">
  <content-tabs-body tab-name="b"><p>Body B — paired by name, not position.</p></content-tabs-body>
  <content-tabs-body tab-name="a" is-open><p>Body A — paired by name, not position.</p></content-tabs-body>
  <content-tabs-header tab-name="a" is-open>A</content-tabs-header>
  <content-tabs-header tab-name="b">B</content-tabs-header>
</content-tabs>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<content-tabs-body>`

> Tab panel — visible when its paired header is open.

**Tag:** `<content-tabs-body>`

## API

### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-open` | hybrid | `boolean` |  |  | Visibility, kept in sync with the paired header's `is-open`. Set directly only if this body is not paired with a header. |
| `tab-name` | option | `string` |  |  | Pairs this body with the `<content-tabs-header>` sharing the same `tab-name`. Unset headers / bodies pair by position instead. |

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--content-tabs-body` | element | `content-tabs-body`, `.tag-content-tabs-body` |  |


---

# `<content-tabs-header>`

> Tab header — opens its paired body on click.

**Tag:** `<content-tabs-header>`

## API

### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `tab-name` | option | `string` |  |  | Pairs this header with the `<content-tabs-body>` sharing the same `tab-name`. Unset headers / bodies pair by position instead. |
| `is-open` | hybrid | `boolean` |  |  | Open state. Click sets or toggles this depending on the parent's `tab-type`; set it directly to drive the tab programmatically. |

### Fires

| Name | Type | Description |
| --- | --- | --- |
| `content-tabs-header-opened` | `ContentTabsHeaderOpenedEvent` (`CustomEvent & { type: "content-tabs-header-opened"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Whenever `is-open` is set. The parent `<content-tabs>` listens for this to close sibling headers. |

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--content-tabs-header` | element | `content-tabs-header`, `.tag-content-tabs-header` |  |


---

# data-table

Sortable, filterable tables from plain custom tags — one behavior owner
(`<data-table>` + `<data-th>`), everything else is CSS.


```html
<data-table>
  <data-thead>
    <data-tr>
      <data-th column-type="string" sort-direction="asc">Name</data-th>
      <data-th column-type="number">Age</data-th>
    </data-tr>
  </data-thead>
  <data-tbody>
    <data-tr><data-td>Beatrice</data-td><data-td>44</data-td></data-tr>
    <data-tr><data-td>Cynthia</data-td><data-td>41</data-td></data-tr>
    <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
    <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
  </data-tbody>
</data-table>
```


## Features

- **Sort** Click a `<data-th>` to visually sort by string, number, or date
- **Filter** `filter-value` hides non-matching rows
- **Export** The `--export` command downloads visible / all rows as CSV / JSON
- **DOM-stable** Sort / filter via CSS only. Does not conflict with DOM owners, such as Quark.
- **Bindable counts** `.provision` is `{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }` — a "12 of 40 rows" readout is one Quark rule
- **Plain structural tags** `<data-thead>` / `<data-tbody>` / `<data-tr>` /
  `<data-td>` are CSS-only — no registration cost

## Installation


`@excom/data-table` v0.1.4

```bash
pnpm add @excom/data-table
```

```bash
npm install @excom/data-table
```

```bash
yarn add @excom/data-table
```

### Import

```ts
import "@excom/data-table";
```



## Usage

Only `<data-table>` and `<data-th>` are registered custom elements.
`<data-thead>`, `<data-tbody>`, `<data-tr>`, `<data-td>`, `<data-tfoot>`, and `<data-tf>` are plain tags — this package's CSS styles them as a table (or apply the equivalent `.tag-data-*` classes).

Sort and filter are visual only (CSS `order` / `display`).
Row nodes never move or leave the DOM, so Quark bindings and `iterate()` tables keep working.

```html
<data-table>
  <data-thead>
    <data-tr>
      <data-th column-type="string" sort-direction="asc">Name</data-th>
      <data-th column-type="number">Age</data-th>
    </data-tr>
  </data-thead>
  <data-tbody>
    <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
    <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
  </data-tbody>
</data-table>
```

`<data-tbody>` is required — sorting and filtering both operate on its
`<data-tr>` children.

`.provision` reports the row counts and the active sort / filter, recomputed after connect, after a sort, and after every filter change.
Read it from a rule matching the table:

```quark
data-table {
  $visible: prop("provision").visibleRows;
  $total: prop("provision").totalRows;
  [bind-count] { content: "#{$visible} of #{$total} rows"; }
}
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `filter-value` | option | `string` |  |  | Hides `data-tr` rows (via `--data-tr-display: none`) whose text content doesn't include this value. Case-insensitive unless `filter-casing` is set. Unset / empty clears the filter. Rows stay in the DOM so Quark bindings survive. |
| `filter-casing` | option | `boolean` |  |  | Match `filter-value` case-sensitively instead of the default case-insensitive comparison. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `DataTableProvision` (`{ totalRows: number; visibleRows: number; sortColumnIndex: number \| null; sortDirection: "asc" \| "desc" \| null; filterValue: string \| null; }`) | `{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }` — recomputed after connect, after the `data-table-sort` default action, and after every filter change. Not reflected as an attribute. |

#### Recognized Elements

| Relationship | Selector | Required | Description |
| --- | --- | --- | --- |
| `data-th` | descendant | yes | Sortable column header. Clicking toggles its `sort-direction` and fires `data-th-sort`, which becomes the active column. |
| `data-tbody` | descendant | yes | Required row container. Sorting and filtering both operate on its `data-tr` children. |
| `data-tr` | descendant | yes | Row, direct child of `data-tbody`. Gets `--data-tr-order` on sort and `--data-tr-display` on filter. DOM order is unchanged. |
| `data-td` | descendant | yes | Cell within a `data-tr`, read as sortable / export cell content. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `data-table-sort` | `DataTableSortEvent` (`CustomEvent & { type: "data-table-sort"; detail: { sortDirection: "asc" \| "desc"; columnType: "string" \| "number" \| "date"; columnIndex: number; sortFn: (a: string, b: string) => number; rows: HTMLElement[]; }; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the active sort column / direction changes: on connect (if a `data-th` already has `sort-direction`) and after every `data-th-sort`. Call `preventDefault()` to take over sorting yourself. |

#### Listens for

| Name | Type | Description |
| --- | --- | --- |
| `data-th-sort` | `DataThSortEvent` (`CustomEvent & { type: "data-th-sort"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Bubbled up from a descendant `data-th` when its `sort-direction` changes. Sets that header as the active sort column (clearing `sort-direction` from the previously active one) and emits `data-table-sort`. |

#### Commands

| Command | Action |
| --- | --- |
| `--export` | Builds a file from the table's `data-tr` / `data-td` / `data-th` text content and downloads it. Options are `data-*` on the invoker: `data-file-type` (`csv`, the default, or `json`), `data-file-name` (default `export_table_<locale-date>`), and `data-full` to download every row in DOM order instead of only the visible rows in visual sort order. Filtering needs no command: write `filter-value` / `filter-casing`. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `data-table-sort` | Sorts `event.detail.rows` by `columnIndex` with `sortFn` and sets `--data-tr-order` on each row (visual CSS `order` — DOM order is unchanged). |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--data-table-cols` | `<integer>` | `1` | Column count for shared subgrid tracks. Auto-detected from the widest row; set on the host to override. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--data-table` | element | `data-table`, `.tag-data-table` |  |
| `:--data-thead` | element | `data-thead`, `.tag-data-thead` |  |
| `:--data-tbody` | element | `data-tbody`, `.tag-data-tbody` |  |
| `:--data-tfoot` | element | `data-tfoot`, `.tag-data-tfoot` |  |
| `:--data-tr` | element | `data-tr`, `.tag-data-tr` |  |
| `:--data-td` | element | `data-td`, `.tag-data-td` |  |
| `:--data-tf` | element | `data-tf`, `.tag-data-tf` |  |



### Examples

#### Filter rows + export as CSV

Filtering is State: write `filter-value` / `filter-casing` on the table — here a Quark `@on input` block copies the search field into them. Matching is case-insensitive unless `filter-casing` is set.

Invoke `--export` on the table (`<button command="--export" commandfor="…">`) to download its visible rows (visual sort order). The button's `data-file-type` is `csv` (default) or `json`; `data-file-name` sets the download name; `data-full` downloads every row in DOM order, regardless of filtering / sorting.

The first export button is the happy path (the table as you see it, including active filter / sort). The form below it writes `data-file-type` / `data-file-name` / `data-full` onto its button.


```html
<div>
  <quark-sheet>
    :scope {
      @on input (target: "form[data-filter]") {
        data-table { filter-value: target.elements.filterValue.value; }
      }
      @on change (target: "form[data-filter]") {
        data-table { filter-casing: target.elements.filterCasing.checked; }
      }
      @on change (target: "form[data-export]") {
        form[data-export] [command="--export"] {
          data-file-type: target.elements.fileType.value;
          data-file-name: target.elements.fileName.value;
          data-full: target.elements.full.checked;
        }
      }
    }
  </quark-sheet>
  <form data-filter>
    <fieldset role="group">
      <input name="filterValue" placeholder="Filter table…" />
      <label>
        Case-sensitive
        <input name="filterCasing" role="switch" type="checkbox" />
      </label>
    </fieldset>
  </form>
  <data-table id="demo-data-table-filter">
    <data-thead>
      <data-tr>
        <data-th column-type="string">Name</data-th>
        <data-th column-type="number">Age</data-th>
      </data-tr>
    </data-thead>
    <data-tbody>
      <data-tr><data-td>Beatrice</data-td><data-td>44</data-td></data-tr>
      <data-tr><data-td>Cynthia</data-td><data-td>41</data-td></data-tr>
      <data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
      <data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
    </data-tbody>
  </data-table>
  <hr />
  <button type="button" command="--export" commandfor="demo-data-table-filter">
    Export as-is
  </button>
  <hr />
  <form data-export class="tag-article">
    <header>
      <h4>Export with options</h4>
    </header>
    <label>
      <select name="fileType">
        <option value="csv" selected>CSV</option>
        <option value="json">JSON</option>
      </select>
    </label>
    <label>
      File name
      <input name="fileName" placeholder="File name" />
    </label>
    <label>
      <input name="full" type="checkbox" role="switch" />
      Full table (ignores active filter/sort)
    </label>
    <button type="button" command="--export" commandfor="demo-data-table-filter">Export</button>
  </form>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<data-th>`

> Sortable column header — click toggles sort direction.

**Tag:** `<data-th>`

## API

### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `column-type` | option | `string` |  | `"string"` \| `"number"` \| `"date"` | Sort comparator to use for this column's cell values. `data-table` treats `null` as "string". |
| `sort-direction` | hybrid | `string` |  | `"asc"` \| `"desc"` | Current sort direction. A click toggles between `asc` / `desc`; setting it (by any means) fires `data-th-sort`. Only one `data-th` per table should carry this at a time — the parent `<data-table>` clears the previously active header when a new one is set. |

### Fires

| Name | Type | Description |
| --- | --- | --- |
| `data-th-sort` | `DataThSortEvent` (`CustomEvent & { type: "data-th-sort"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched whenever `sort-direction` is set, whether by a click or programmatically. Bubbles to the parent `<data-table>`. |

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--data-th` | element | `data-th`, `.tag-data-th` |  |
| `:--data-th--sort` | state | `:is(:--data-th)` |  |
| `:--data-th--sort-asc` | state | `[sort-direction="asc"]`, `[aria-sort="ascending"]` |  |
| `:--data-th--sort-desc` | state | `[sort-direction="desc"]`, `[aria-sort="descending"]` |  |


---

# detect-browser

Drop-in tag provides browser, OS, device, and language metadata — target Safari, standalone mode, mobile devices, etc. Helpful in creating device-specific UX.


```html
<div>
  <detect-browser></detect-browser>
  <style>
    #demo-detect-browser-simple> :first-child {
      detect-browser::before { content: "Rendered with CSS: "; }
      detect-browser::after {
        content:
        "browser: " attr(browser-name) " " attr(browser-version)
        " · engine: " attr(browser-engine)
        " · os: " attr(operating-system)
        " · device: " attr(device-type);
      }
    }
  </style>
</div>
```


## Features

- **Attribute metadata** Set once on connect for CSS / Quark targeting
- **Standalone / PWA detection** `is-standalone` reflects installed mode
- **Language detection** `language-id` reflects system-selected language
- **Device class** `device-type` (`mobile` / `desktop`) for coarse targeting
- **Full metadata** `.provision` exposes user agent, languages, hardware hints

## Installation


`@excom/detect-browser` v0.1.4

```bash
pnpm add @excom/detect-browser
```

```bash
npm install @excom/detect-browser
```

```bash
yarn add @excom/detect-browser
```

### Import

```ts
import "@excom/detect-browser";
```



## Usage

Drop it anywhere and select on its attributes with plain CSS.

```html
<detect-browser></detect-browser>
```

```css
html:has(detect-browser[browser-name="safari"]) .safari-only {
  display: block;
}
```

Live touch / pointer detection is `detect-media media-query="(pointer: coarse)"` — this element reports what the user agent says once, not what the input is now.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `browser-name` | state | `string` |  | `"chrome"` \| `"firefox"` \| `"safari"` \| `"edge"` \| `"opera"` \| `internet explorer` | Detected browser family. |
| `browser-version` | state | `string` |  |  | Browser version, as reported by the user agent string. |
| `browser-engine` | state | `string` |  | `"blink"` \| `"gecko"` \| `"webkit"` \| `"trident"` | Rendering engine. |
| `browser-vendor` | state | `string` |  |  | `navigator.vendor`, lowercased. |
| `operating-system` | state | `string` |  | `windows 10+` \| `windows 8.1` \| `windows 8` \| `windows 7` \| `macos <version>` \| `"android"` \| `"ios"` \| `"linux"` | Detected OS and, where available, version. |
| `operating-platform` | state | `string` |  |  | `navigator.userAgentData.platform` (falls back to `navigator.platform`), lowercased. |
| `device-type` | state | `string` |  | `"mobile"` \| `"desktop"` | Coarse device class inferred from the user agent string. |
| `is-standalone` | state | `boolean` |  |  | Present when running in standalone / installed PWA mode. |
| `language-id` | state | `string` |  |  | `navigator.language`, lowercased. |
| `cookies-enabled` | state | `boolean` |  |  | Present when `navigator.cookieEnabled` is `true`. |
| `do-not-track` | state | `string` |  |  | `navigator.doNotTrack`, as reported by the browser. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `BrowserInfo` (`{ browserName: string \| null; browserVersion: string \| null; browserEngine: string \| null; browserVendor: string \| null; operatingSystem: string \| null; operatingPlatform: string \| null; deviceType: string \| null; isStandalone: boolean \| null; languageId: string \| null; cookiesEnabled: boolean \| null; doNotTrack: string \| null; userAgent: string \| null; languageIds: string[] \| null; hardwareConcurrency: number \| null; deviceMemory: number \| null; }`) | Every field above, plus values with no CSS-friendly attribute form: full user agent string, `navigator.languages`, hardware concurrency, and device memory (GB, where supported). Not reflected as an attribute. |



### Examples

#### Language

Showing a greeting in your system language (Only Spanish or English for this example). `language-id` mirrors `navigator.language` (lowercased). Spanish prefixes show `Hola`; everything else shows `Hello`. Change the browser language (or override it in DevTools) and reload to flip it.


```html
<div>
  <detect-browser>
    <span lang="en">Hello</span>
    <span lang="es">Hola</span>
  </detect-browser>
  <style>
    #demo-detect-browser-language > :first-child {
      detect-browser {
        [lang="en"],
        [lang="es"] { display: none; }
        &[language-id^="es"] [lang="es"],
        &:not([language-id^="es"]) [lang="en"] { display: inline; }
      }
    }
  </style>
</div>
```


#### Safari-only install hint

iOS Safari has no install prompt, so the sheet renders "Add to Home Screen" steps there, and not once the app is installed. Spoof an iOS Safari user agent in DevTools and reload to trigger it.


```html
<div>
  <small role="note">Spoof an iOS Safari user agent in DevTools and reload.</small>
  <detect-browser></detect-browser>
  <include-content>
    <template>
      <p>Install this app: tap <strong>Share</strong>, then
        <strong>Add to Home Screen</strong>.</p>
    </template>
  </include-content>
  <quark-sheet>
    detect-browser[browser-name="safari"][operating-system="ios"]:not([is-standalone]) + include-content {
      is-active: "";
    }
  </quark-sheet>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# detect-features

Feature detection — gate content on real browser support with
plain CSS.


```html
<div>
  <detect-features></detect-features>
  <p>Geolocation supported in this browser.</p>
  <p role="alert">Geolocation is not supported in this browser.</p>
  <small role="note">See "Live document" tab below to see the <code>full-support</code> and <code>no-support</code> attributes populated with all of your browser's features.</small>
  <style>
    #demo-detect-features-simple {
      &:has(detect-features[full-support~="geolocation"]) p[role="alert"] {
        display: none;
      }
      &:has(detect-features:not([full-support~="geolocation"])) p:not([role="alert"]) {
        display: none;
      }
    }
  </style>
</div>
```


## Features

- **Support tokens** Set once on connect for CSS / Quark targeting
- **CSS-selectable** Gate content with attribute selectors, no polyfills
- **JS / Quark data** `.provision` exposes `fullSupport` / `noSupport` arrays
- **Common Web APIs** Geolocation, share, bluetooth, clipboard,
  media-devices, service-worker, payment-request, and many more

## Installation


`@excom/detect-features` v0.1.4

```bash
pnpm add @excom/detect-features
```

```bash
npm install @excom/detect-features
```

```bash
yarn add @excom/detect-features
```

### Import

```ts
import "@excom/detect-features";
```



## Usage

Check `full-support` / `no-support` for a space-separated feature name.

```html
<detect-features></detect-features>
```

Use CSS or Quark to react to the feature detection:

```css
detect-features:not([full-support~="geolocation"]) ~ .needs-location {
  display: none;
}
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `full-support` | state | `tokenlist` |  | `"geolocation"` \| `"vibrate"` \| `"bluetooth"` \| `"usb"` \| `"serial"` \| `"hid"` \| `"share"` \| `"clipboard"` \| `"credentials"` \| `"media-devices"` \| `"service-worker"` \| `"storage"` \| `"wake-lock"` \| `"gpu"` \| `"locks"` \| `"permissions"` \| `"connection"` \| `"user-agent-data"` \| `"battery"` \| `"midi"` \| `"webxr"` \| `"virtual-keyboard"` \| `"window-controls-overlay"` \| `"contacts"` \| `"local-storage"` \| `"session-storage"` \| `"indexed-db"` \| `"notification"` \| `"payment-request"` \| `"web-socket"` \| `"worker"` \| `"shared-worker"` \| `"broadcast-channel"` \| `"intersection-observer"` \| `"resize-observer"` \| `"speech-synthesis"` \| `"eye-dropper"` \| `"barcode-detector"` \| `"file-system-access"` \| `"webrtc"` \| `"dialog"` \| `"view-transitions"` \| `"cookie-store"` \| `"offscreen-canvas"` | Space-separated feature names fully supported by this browser. |
| `partial-support` | state | `tokenlist` |  |  | Reserved for features with partial / conditional support. Not populated yet — see `INTERNAL.md`. |
| `no-support` | state | `tokenlist` |  | `"geolocation"` \| `"vibrate"` \| `"bluetooth"` \| `"usb"` \| `"serial"` \| `"hid"` \| `"share"` \| `"clipboard"` \| `"credentials"` \| `"media-devices"` \| `"service-worker"` \| `"storage"` \| `"wake-lock"` \| `"gpu"` \| `"locks"` \| `"permissions"` \| `"connection"` \| `"user-agent-data"` \| `"battery"` \| `"midi"` \| `"webxr"` \| `"virtual-keyboard"` \| `"window-controls-overlay"` \| `"contacts"` \| `"local-storage"` \| `"session-storage"` \| `"indexed-db"` \| `"notification"` \| `"payment-request"` \| `"web-socket"` \| `"worker"` \| `"shared-worker"` \| `"broadcast-channel"` \| `"intersection-observer"` \| `"resize-observer"` \| `"speech-synthesis"` \| `"eye-dropper"` \| `"barcode-detector"` \| `"file-system-access"` \| `"webrtc"` \| `"dialog"` \| `"view-transitions"` \| `"cookie-store"` \| `"offscreen-canvas"` | Space-separated feature names with no support in this browser. |
| `granted-permissions` | state | `tokenlist` |  |  | Reserved for features that require an explicit permission grant. Not populated yet — see `INTERNAL.md`. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `FeatureInfo` (`{ fullSupport: keyof typeof FEATURE_CHECKS[]; noSupport: keyof typeof FEATURE_CHECKS[]; }`) | Same partitions as the token attributes, as string arrays for JS / Quark (`fullSupport`, `noSupport`). Not reflected as an attribute. |



### Examples

#### Gate a whole section

`full-support` lists every feature this browser supports; `no-support`
lists the rest. Wrap a whole section instead of one element by pairing
`:has()` with the same attribute selector:

```css
body:has(detect-features:not([full-support~="geolocation"])) #store-locator {
  display: none;
}
```

#### Web Share progressive UI

Show a share affordance only when `share` is listed in `full-support`.
Browsers without Web Share keep the fallback copy instead.


```html
<div>
  <detect-features></detect-features>
  <p>Web Share is available in this browser.</p>
  <p role="status">
    Web Share is not available — offer a copy-link fallback instead.
  </p>
  <small role="note">See "Live document" tab below to see the <code>full-support</code> and <code>no-support</code> attributes populated with all of your browser's features.</small>
  <style>
    #demo-detect-features-share {
      &:has(detect-features[full-support~="share"]) p[role="status"] {
        display: none;
      }
      &:has(detect-features:not([full-support~="share"])) p:not([role="status"]) {
        display: none;
      }
    }
  </style>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# detect-media

Live media-query facts as attributes — what CSS knows, Quark can now select on. One `<detect-media>` per query; `is-matched` follows `window.matchMedia` and flips as the query does.


```html
<div>
  <detect-media media-query="(prefers-color-scheme: dark)"></detect-media>
  <p>Dark color scheme — <code>is-matched</code> is set.</p>
  <p role="status">Light color scheme — <code>is-matched</code> is absent.</p>
  <small role="note">Live — switch your OS / browser color scheme (or emulate <code>prefers-color-scheme</code> in DevTools) to flip it.</small>
  <style>
    #demo-detect-media-simple {
      &:has(detect-media[is-matched]) p[role="status"] {
        display: none;
      }
      &:has(detect-media:not([is-matched])) p:not([role="status"]) {
        display: none;
      }
    }
  </style>
</div>
```


## Features

- **Live `is-matched`** Follows `MediaQueryList.matches` and its `change` event
- **Any media query** Color scheme, pointer type, motion, width — whatever `matchMedia` accepts
- **CSS / Quark selectable** Gate content on `detect-media[is-matched]`, no listeners
- **Provision + event** `.provision` is `{ mediaQuery, isMatched }`; `detect-media-change` fires on every flip

## Installation


`@excom/detect-media` v0.1.7

```bash
pnpm add @excom/detect-media
```

```bash
npm install @excom/detect-media
```

```bash
yarn add @excom/detect-media
```

### Import

```ts
import "@excom/detect-media";
```



## Usage

One element per query. `media-query` takes anything `window.matchMedia` does.

```html
<detect-media media-query="(pointer: coarse)"></detect-media>
```

Select on `is-matched` from CSS:

```css
body:has(detect-media[media-query="(pointer: coarse)"][is-matched]) .hover-hint {
  display: none;
}
```

Or from Quark — the attribute, or the provision:

```quark
detect-media[media-query="(pointer: coarse)"][is-matched] ~ nav {
  data-is-touch: "";
}
detect-media[media-query="(pointer: coarse)"]:not([is-matched]) ~ nav {
  data-is-touch: none;
}
detect-media[media-query="(prefers-color-scheme: dark)"] {
  $app-is-dark: prop("provision").isMatched;
}
```

Missing / empty `media-query` leaves `is-matched` unset and `provision` `null`; changing it re-subscribes. `detect-media-change` fires on every flip after mount, never on mount — react to the attribute for the initial state.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `media-query` | option | `string` |  |  | Media query to evaluate, in `window.matchMedia` syntax: `(prefers-color-scheme: dark)`, `(pointer: coarse)`, `(width < 600px)`. Required — missing / empty leaves `is-matched` unset and `provision` `null`. Changing it re-subscribes. |
| `is-matched` | state | `boolean` |  |  | Present while `media-query` matches. Live — follows the query's `change` event. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `DetectMediaProvision` (`{ mediaQuery: string; isMatched: boolean; }`) | `{ mediaQuery, isMatched }` — a new object on first evaluation and on every change; `null` without a query. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `detect-media-change` | `DetectMediaChangeEvent` (`CustomEvent & { type: "detect-media-change"; detail: { mediaQuery: string; isMatched: boolean; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched every time the query flips (not on mount). `event.detail` is the `.provision` payload. |



### Examples

#### Touch vs pointer views

Quark flips `is-active` on two `<include-content>` hosts from `(pointer: coarse)` — a true render, so the inactive view is not in the document. Toggle device emulation in DevTools to switch live.


```html
<div>
  <detect-media media-query="(pointer: coarse)">
    <include-content bind-touch>
      <template>
        <p>Touch layout</p>
      </template>
    </include-content>
    <include-content bind-pointer>
      <template>
        <p>Pointer layout</p>
      </template>
    </include-content>
  </detect-media>
  <quark-sheet>
    detect-media[is-matched] include-content[bind-touch] {
      is-active: "";
    }
    detect-media[is-matched] include-content[bind-pointer] {
      is-active: none;
    }
    detect-media:not([is-matched]) include-content[bind-pointer] {
      is-active: "";
    }
    detect-media:not([is-matched]) include-content[bind-touch] {
      is-active: none;
    }
  </quark-sheet>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# dialog-anchor

Open and close a native `<dialog>` — no JavaScript required.


```html
<div>
  <dialog-anchor role="button" target-ref="#da-simple" is-modal>Open dialog</dialog-anchor>
  <dialog id="da-simple">
    <p>A native, modal dialog.</p>
    <dialog-anchor role="button">Close</dialog-anchor>
  </dialog>
</div>
```


## Features

- **Click to toggle** Opens / closes a `<dialog>` on click
- **Target or fallback** Point at any `<dialog>` via `target-ref`, or let
  it find the nearest ancestor automatically (great for close buttons)
- **Modal or non-modal** `is-modal` blocks the rest of the page; omit it
  for a lightweight, dismissible popover
- **Any trigger event** Inherits `listen-for` to open/close on custom
  events instead of `click`

## Installation


`@excom/dialog-anchor` v0.1.4

```bash
pnpm add @excom/dialog-anchor
```

```bash
npm install @excom/dialog-anchor
```

```bash
yarn add @excom/dialog-anchor
```

### Import

```ts
import "@excom/dialog-anchor";
```

```css
@import "@excom/dialog-anchor/dialog-anchor.css";
```



## Usage

Wrap a trigger in `<dialog-anchor>` and point it at a `<dialog>`. A
`<dialog-anchor>` with no `target-ref`, placed inside the `<dialog>` it
should close, needs no configuration at all.

```html
<dialog-anchor target-ref="#confirm" role="button">Delete</dialog-anchor>
<dialog id="confirm">
  <p>Are you sure?</p>
  <dialog-anchor role="button">Cancel</dialog-anchor>
</dialog>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `target-ref` | option | `string` |  | `<CSS Selector>` | CSS selector for the `<dialog>` to toggle. If omitted, the element toggles the nearest ancestor `<dialog>`. |  |
| `is-modal` | option | `boolean` |  |  | Open the dialog as a modal (blocks the rest of the page) instead of a non-modal popover. |  |
| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`/`cmd`. Name the space bar `space` / `spacebar` and the plus key `plus` (`shift+space`). Case-insensitive. | `@excom/listenable-element` |
| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.unstyled` | Skip the pointer cursor from the listenable mixin. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--dialog-anchor` | element | `dialog-anchor`, `.tag-dialog-anchor` |  |



### Examples

#### Modal dialog

`is-modal` opens the dialog as a modal, blocking interaction with the rest
of the page until it's closed (using native `::backdrop`). Without that attribute,
the dialog is opened without a backdrop.

If using Valence.css, setting `.absolute` on the `dialog` element will display it `absolute`
in the surrounding content (as opposed to fixed).


```html
<div>
  <dialog-anchor role="button" target-ref="#da-modal" is-modal>
    Open as modal
  </dialog-anchor>
  <dialog-anchor role="button" target-ref="#da-modal">
    Open as non-modal
  </dialog-anchor>
  <dialog id="da-modal">
    <article>
      <header>
        <dialog-anchor role="button" rel="prev"></dialog-anchor>
        <h4>Modal dialogs block interaction with the rest of the page.</h4>
        <p>This dialog is shown with Valence.css styling</p>
      </header>
      <p>Dialog content</p>
      <footer>
        Footer content
      </footer>
    </article>
  </dialog>
</div>
```


#### Close on a custom event

`listen-for` swaps the default `click` for any event. Pair it with a real
`<super-form>`'s `super-form-success` event to auto-close a dialog
once a form inside it succeeds — simulated here with `<event-handler>`.


```html
<div>
  <dialog-anchor role="button" target-ref="#da-auto" is-modal>Open form</dialog-anchor>
  <dialog id="da-auto">
    <dialog-anchor listen-for="super-form-success">
      <p>Simulating a form submit…</p>
      <event-handler role="button" fire-event="super-form-success">
        Submit
      </event-handler>
    </dialog-anchor>
  </dialog>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# dismiss-watcher

One dismissal Adapter for drawers, menus, dialogs and popovers — Escape / back gesture and outside click, without each panel element owning the logic.


```html
<div>
  <quark-sheet>
    :scope {
      @on menu-open { data-is-open: ""; }
      @on dismiss-watcher-dismiss { data-is-open: none; }
      &[data-is-open] dismiss-watcher { is-active: ""; }
      &:not([data-is-open]) dismiss-watcher { is-active: none; }
    }
  </quark-sheet>
  <style>
    [data-demo-menu] { display: none; }
    [data-is-open] > [data-demo-menu] { display: block; }
  </style>
  <event-handler role="button" fire-event="menu-open">Open menu</event-handler>
  <nav data-demo-menu>
    <dismiss-watcher></dismiss-watcher>
    <ul>
      <li><a href="#">Profile</a></li>
      <li><a href="#">Settings</a></li>
      <li><a href="#">Sign out</a></li>
    </ul>
    <p>Press Escape or click outside to close.</p>
  </nav>
</div>
```


## Features

- **Escape / back gesture** Through a `CloseWatcher` (Android back, Escape) via `watch-escape`
- **Outside click** A `mouseup` outside the target via `watch-outside-click`
- **One event** `dismiss-watcher-dismiss` with `detail.reason`; cancel it with `preventDefault()`
- **Default action** `command-name` commands invoked on the target (`--close`), or `fire-event` names dispatched at it
- **Any target** The parent by default, or `target-ref` (`:scope`-relative)
- **Gated by State** Live only while `is-active` — set it from Quark on the panel's open state

## Installation


`@excom/dismiss-watcher` v0.1.7

```bash
pnpm add @excom/dismiss-watcher
```

```bash
npm install @excom/dismiss-watcher
```

```bash
yarn add @excom/dismiss-watcher
```

### Import

```ts
import "@excom/dismiss-watcher";
```



## Usage

Drop it inside the element being dismissed, gate `is-active` on that element's open state, and either react to `dismiss-watcher-dismiss` or let `command-name` / `fire-event` close the panel for you. When neither `watch-escape` nor `watch-outside-click` is present, both watchers are on.

```html
<nav>
  <dismiss-watcher fire-event="menu-close"></dismiss-watcher>
  …
</nav>
```

```quark
:scope {
  @on menu-open { data-is-open: ""; }
  @on menu-close { data-is-open: none; }
  &[data-is-open] dismiss-watcher { is-active: ""; }
  &:not([data-is-open]) dismiss-watcher { is-active: none; }
}
```

Why a separate element: dismissal is the same request whether the panel is a drawer, a menu, a dialog or a popover. Panel elements keep their own state (`is-open`); this Adapter only asks them to close. It renders nothing, listens only while `is-active`, and tears down when unset or removed. Write the inverse rule for `is-active` — Quark rules do not revert.

`dismiss-watcher-dismiss` bubbles and is cancelable. `detail.reason` is `"escape"` / `"outside-click"`. The default action invokes each `command-name` on the target (a `command` event, as a `<button command commandfor>` would) and dispatches each `fire-event` name at it as a bubbling `CustomEvent`; `preventDefault()` keeps the panel open (an unsaved-changes guard, for instance).

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-active` | hybrid | `boolean` |  |  | Watchers are live while set. Gate it from Quark on the panel's open state, and write the inverse rule. |
| `watch-escape` | option | `boolean` |  |  | Watch Escape / the back gesture through a `CloseWatcher`. When neither `watch-*` attribute is present both watchers are on. |
| `watch-outside-click` | option | `boolean` |  |  | Watch for a `mouseup` on the document outside the target. When neither `watch-*` attribute is present both watchers are on. |
| `target-ref` | option | `string` |  |  | Selector for the element being dismissed, `:scope`-relative (`:scope ~ nav`). Unset = the parent element. |
| `command-name` | option | `tokenlist` |  | `<command>…` | Commands invoked on the target as the default action of `dismiss-watcher-dismiss` — `--close` for a `<content-drawer>`, or any `--verb` the panel handles. |
| `fire-event` | option | `tokenlist` |  |  | Event names dispatched at the target (bubbling `CustomEvent`s) as the default action of `dismiss-watcher-dismiss`, for panels driven by events rather than commands (`menu-close`). |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `dismiss-watcher-dismiss` | `DismissWatcherDismissEvent` (`CustomEvent & { type: "dismiss-watcher-dismiss"; detail: { reason: "escape" \| "outside-click" }; bubbles: true; cancelable: true; composed: true }`) | A dismissal was requested; `detail.reason` is `"escape"` or `"outside-click"`. Default action: invoke each `command-name` on the target and dispatch each `fire-event` name at it as a bubbling `CustomEvent`. `preventDefault()` skips both. |



### Examples

#### Menu panel

Both watchers on (neither `watch-*` set), target = the parent `<nav>`. The sheet opens on `menu-open`, closes on `dismiss-watcher-dismiss`, and gates `is-active` on `data-is-open` with its inverse rule.


```html
<div>
  <quark-sheet>
    :scope {
      @on menu-open { data-is-open: ""; }
      @on dismiss-watcher-dismiss { data-is-open: none; }
      &[data-is-open] dismiss-watcher { is-active: ""; }
      &:not([data-is-open]) dismiss-watcher { is-active: none; }
    }
  </quark-sheet>
  <style>
    [data-demo-menu] { display: none; }
    [data-is-open] > [data-demo-menu] { display: block; }
  </style>
  <event-handler role="button" fire-event="menu-open">Open menu</event-handler>
  <nav data-demo-menu>
    <dismiss-watcher></dismiss-watcher>
    <ul>
      <li><a href="#">Profile</a></li>
      <li><a href="#">Settings</a></li>
      <li><a href="#">Sign out</a></li>
    </ul>
    <p>Press Escape or click outside to close.</p>
  </nav>
</div>
```


#### Content drawer

First child of `<content-drawer>`, `command-name="--close"` — the drawer needs no dismissal logic of its own. `is-active` follows `content-drawer[is-open]`.

Open with `--open`, not `--toggle`: an outside `mouseup` on the button closes the drawer first, then the button's `click` re-opens it. With `--toggle` the same click would close it again.


```html
<section>
  <quark-sheet>
    :scope {
      content-drawer[is-open] dismiss-watcher { is-active: ""; }
      content-drawer:not([is-open]) dismiss-watcher { is-active: none; }
    }
  </quark-sheet>
  <button type="button" command="--open" commandfor="demo-dismiss-drawer">
    Open drawer
  </button>
  <content-drawer id="demo-dismiss-drawer" class="absolute">
    <dismiss-watcher watch-escape watch-outside-click command-name="--close"></dismiss-watcher>
    <header>
      <h2>Drawer</h2>
    </header>
    <p>Press Escape or click outside to close.</p>
  </content-drawer>
  <event-handler class="tag-backdrop" role="presentation" target-ref="content-drawer:has(+ :scope)" command-name="--close"></event-handler>
</section>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# dom-observer

Fire an event whenever a configured element mutates.


```html
<div>
  <section>
    <dom-observer target-ref=":scope + details"></dom-observer>
    <details id="do-watched">
      <summary>Toggle me — mutates the "open" attribute</summary>
      <p>Toggling this
        fired <code>dom-observer-change</code>.</p>
    </details>
    <output></output>
  </section>
  <quark-sheet>
    section {
      @on dom-observer-change {
        output { content: "#{event.detail.mutations.length} mutation(s), open: #{event.detail.target.open}"; }
      }
    }
  </quark-sheet>
</div>
```


## Features

- **Mutation events** Fires `dom-observer-change` on target changes
- **Selector-based** `target-ref` resolves any element, anywhere
- **Waits for its target** No matching element yet? It watches for one
- **Fires once immediately** An empty-`mutations` fire on resolve lets
  listeners seed from current state
- **`<template>`-aware** Also observes a template's `.content` fragment

## Installation


`@excom/dom-observer` v0.1.4

```bash
pnpm add @excom/dom-observer
```

```bash
npm install @excom/dom-observer
```

```bash
yarn add @excom/dom-observer
```

### Import

```ts
import "@excom/dom-observer";
```



## Usage

Point `target-ref` at any selector, then react to `dom-observer-change`
with `<event-handler>` (or Quark).

```html
<dom-observer target-ref="#watched"></dom-observer>
<event-handler listen-for="dom-observer-change" target-ref="#log">
  <!-- runs on every #watched mutation, and once on attach -->
</event-handler>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `target-ref` | option | `string` |  |  | CSS selector used to resolve the element to observe. Resolved against `document`. If no element matches at connect time, the element waits for one to appear. |
| `target-element` | state | `HTMLElement` |  |  | The currently observed target element (if any). |
| `target-finding-observer` | state | `MutationObserver` |  |  | Document-level observer used to wait for a target matching `target-ref` to appear. Disconnected as soon as the target is found. |
| `target-change-observer` | state | `MutationObserver` |  |  | Observer attached to the resolved `targetElement` (and to its `.content` fragment when the target is a `<template>`). |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `dom-observer-change` | `DomObserverChangeEvent` (`CustomEvent & { type: "dom-observer-change"; detail: { target: Element; mutations: MutationRecord[]; }; bubbles: true; cancelable: true; composed: true }`) | Fires whenever the resolved target mutates, and once immediately (with `mutations: []`) as soon as the target is resolved so listeners can seed from current state. `mutations` is the `MutationRecord[]` from the underlying `MutationObserver` callback (empty on that first fire). |



### Examples

#### Waiting for the target to exist

If nothing matches `target-ref` at connect time, `<dom-observer>` watches
the document for a match and switches over automatically — no glue code:

```html
<dom-observer target-ref="article#late"></dom-observer>
```

#### Observing a `<template>`

A `<template>`'s authored content lives on its `.content`
`DocumentFragment`, not as DOM descendants of the `<template>` itself.
`<dom-observer>` observes both, so mutations to either surface through the
same event stream:

```html
<template id="rows">
  <li>seed</li>
</template>
<dom-observer target-ref="#rows"></dom-observer>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# event-handler

Stitch behaviors of your app together, primarily through events.


```html
<section>
    <event-handler target-ref=":scope + content-drawer" command-name="--toggle">
        Toggle drawer
    </event-handler>
    <content-drawer class="absolute">
        <h2>Open!</h2>
    </content-drawer>
</section>
```


## Features

- **Fire custom events** Map any input event, such as clicks, or lifecycles to custom output events
- **Commands** `command-name` invokes the HTML Command API — built-in verbs (`show-modal`) and the `--verb` commands elements accept (`--submit`, `--close`)
- **Retarget** Aim events/commands at any selector (`target-ref`) — where a `<button commandfor>` needs an id
- **Global / host listening** Listen to events globally or on any element. Helpful for: escape to dismiss, global shortcuts, etc.
- **Keycode filter** Escape to dismiss, Shift+K shortcuts — keys / modifier chords
- **Listen filters** Debounce, selector, and pathname gates
- **Custom Event Payloads** `detail-*` attributes and forms convert to `event.detail` JSON

> In a view that already has a `<quark-sheet>`, the same wiring is a rule: `@on click (target: "[data-add]") { @dispatch cart-add (detail: (sku: attr("data-sku"))); }` — `@on` options cover `selector-filter` / `keycode-filter` / `is-debounced` / `host-ref`, and `@dispatch` / `@command` cover `fire-event` / `target-ref` / `form-ref` / `command-name`. Keep `<event-handler>` for markup without a sheet.

## Installation


`@excom/event-handler` v0.1.4

```bash
pnpm add @excom/event-handler
```

```bash
npm install @excom/event-handler
```

```bash
yarn add @excom/event-handler
```

### Import

```ts
import "@excom/event-handler";
```



## Usage

Listen (default `click`), then either `fire-event` or `command-name`.

```html
<event-handler fire-event="cart-add">
  Add to cart
</event-handler>
```

Or, for example: a successful form submit re-fetches the related data by invoking the provider's `--fetch` command.
```html
<event-handler listen-for="super-form-success" target-ref="#fetch-todos" command-name="--fetch">
  <super-form>
    <form>
      <!-- form to create a new todo -->
    </form>
  </super-form>
</event-handler>
```

In a Nucleus Stack application, this will be one of the most heavily used elements. It is the primary method of linking a functional cause and effect.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `target-ref` | option | `string` |  | `<CSS Selector>` | Where outgoing events / mutations / commands apply. Unset = this element. Supports `:scope` for relative targeting (e.g. `:scope ~ dialog`). |  |
| `fire-event` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to dispatch on the target. Each name gets the same merged `detail`. Ignored when `mutate-target` is set. Pair with `detail-*` attributes for static detail fields. |  |
| `command-name` | option | `tokenlist` |  | `<command>…` | Space-separated commands to invoke on the target: custom `--verb` commands (`--submit`, `--close`) dispatch a `command` event, as a `<button command commandfor>` would; built-in verbs (`show-modal`, `close`, `toggle-popover`) run through the platform. |  |
| `not-bubbles` | option | `boolean` |  |  | Outgoing events use `bubbles: false` (default: bubble). |  |
| `not-cancelable` | option | `boolean` |  |  | Outgoing events use `cancelable: false` (default: cancelable). |  |
| `not-composed` | option | `boolean` |  |  | Outgoing events use `composed: false` (default: composed / cross shadow roots). |  |
| `form-ref` | option | `string` |  | `<CSS Selector>` | `<form>` whose fields merge into event `detail`, or become attributes when `mutate-target` is set. |  |
| `mutate-target` | option | `boolean` |  |  | @deprecated Write attributes on the target instead of firing events (sources: `attr-*` on this element plus `form-ref` fields). Use a Quark `@on <event> { … }` block instead — it writes State from the event without one element mutating another. Kept for compatibility; will be removed in a future major. |  |
| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`/`cmd`. Name the space bar `space` / `spacebar` and the plus key `plus` (`shift+space`). Case-insensitive. | `@excom/listenable-element` |
| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.unstyled` | Skip the pointer cursor from the listenable mixin. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--event-handler` | element | `event-handler`, `.tag-event-handler` |  |



### Examples

#### Fire a custom event

Click dispatches `cart-add` event with `{ sku: "sku-1" }` in `event.detail`.


```html
<div>
  <event-handler fire-event="cart-add" detail-sku="sku-1">
    Add to cart
  </event-handler>
  <output>Waiting…</output>
  <quark-sheet>
    @use "quark:util" as *;

    :scope {
      @on cart-add { output { content: to-json(event.detail); } }
    }
  </quark-sheet>
</div>
```


#### Open a dialog

`command-name` invokes the HTML Command API — here the built-in `show-modal` opens the sibling `<dialog>`. Custom commands (`command-name="--close"`) reach any element that handles them, such as `<content-drawer>`, through a relative `target-ref`.


```html
<section>
  <event-handler target-ref=":scope + dialog" command-name="show-modal">
    Open dialog
  </event-handler>
  <dialog>
    Hello!
    <form method="dialog"><button>Close</button></form>
  </dialog>
</section>
```


#### Close on Enter

`keycode-filter` gates keyboard handling — here Enter, focused in the
`input`, invokes the drawer's `--close` command (local / bubbling events only).


```html
<section>
  <event-handler target-ref=":scope + content-drawer" command-name="--toggle">
    Toggle drawer
  </event-handler>
  <content-drawer id="demo-enter-close-drawer" is-open class="absolute">
    <event-handler listen-for="keydown" keycode-filter="enter" target-ref="#demo-enter-close-drawer" command-name="--close">
      <label>
        Favorite color
        <input type="text" placeholder="Type something, then press Enter to close drawer" autofocus />
      </label>
    </event-handler>
  </content-drawer>
</section>
```


#### Escape to dismiss (global)

`host-ref="window"` listens for `keydown` on the window — Escape closes
the dialog even when focus is outside it.


```html
<section>
  <event-handler target-ref=":scope ~ dialog" command-name="show-modal">
    Open dialog
  </event-handler>
  <event-handler
    host-ref="window"
    listen-for="keydown"
    keycode-filter="escape"
    target-ref=":scope ~ dialog"
    command-name="close"
  ></event-handler>
  <dialog>
    Press Escape anywhere to close.
    <form method="dialog"><button>Close</button></form>
  </dialog>
</section>
```


#### Cancel a link click

`prevent-default` cancels the native action — here the wrapped `<a>` never navigates.
Use `stop-propagation` / `stop-immediate-propagation` the same way when you need to stop bubbling.


```html
<event-handler prevent-default>
  <a href="https://example.com">This native link does nothing</a>
</event-handler>
```


#### Retarget

`target-ref` aims the outgoing event at another element — useful when the target sits outside of the bubble path.


```html
<div>
  <output>Waiting…</output>
  <event-handler target-ref="output:has(+ :scope)" fire-event="demo-ping"
    detail-label="pong">
    Ping previous output
  </event-handler>
  <quark-sheet>
    output {
      @on demo-ping { content: event.detail.label; }
    }
  </quark-sheet>
</div>
```


#### Debounced input / form data

Inherited `delay-ms` + `is-debounced` coalesce noisy `input` into one `search-query` event. Demo below is debounced every 200ms.

Also demonstrated is form conversion into JSON: `text` -> `string`, `checkbox` -> `boolean`, etc. Including the data structure: `detail.strict` -> `{detail: {strict}}`.


```html
<div>
  <event-handler listen-for="input" delay-ms="200" is-debounced fire-event="search-query" form-ref=":scope form">
    <form>
      <label>
        <input name="detail.q" type="search" placeholder="Type to search…" />
      </label>
      <label>
        Strict search
        <input name="detail.strict" type="checkbox" role="switch" />
      </label>
    </form>
  </event-handler>
  <output>Waiting…</output>
  <quark-sheet>
    @use "quark:util" as *;

    :scope {
      @on search-query { output { content: to-json(event.detail); } }
    }
  </quark-sheet>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# fetchable-element

Composition base that owns the `fetch()` lifecycle for Neutron elements —
build the request from attributes, a `<form>`, or a custom override, then
track loading / success / error state automatically.

## Features

- **Shared lifecycle** States, `provision` and events come from [loadable-element](/packages/loadable-element)

- **Attribute-driven requests** URL, method, headers, redirect, and
  credentials all configurable declaratively
- **Form-aware** Point `form-ref` at a `<form>` to source action, method,
  enctype, and field values
- **Merged payloads** Attributes, form, and custom args deep-merge
  (lowest → highest priority)
- **Lifecycle state** `is-loading` / `is-success` / `is-error` managed
  for you
- **Provision** `provision` is the parsed response (or error payload) for
  Quark `prop("provision")` — not a reflected attribute
- **Cancel-safe** Superseded or disconnected requests are aborted via
  `AbortableElement`

## Installation


`@excom/fetchable-element` v0.3.0

```bash
pnpm add @excom/fetchable-element
```

```bash
npm install @excom/fetchable-element
```

```bash
yarn add @excom/fetchable-element
```

### Import

```ts
import { /* … */ } from "@excom/fetchable-element";
```



## Usage

Compose `FetchableElement`, then call `doFetch(url, requestInit)` —
usually built via `getFetchArgs(customFetchArgs?)` — whenever the
subclass decides a request should run. Concrete consumers include
`<provider-fetch>` (fetch on attribute change), `<super-form>` (fetch on
submit), and `<web-authn>` (WebAuthn ceremonies that still round-trip to
a server).

```ts
import { Neutron } from "@excom/neutron";
import { FetchableElement } from "@excom/fetchable-element";

export const RefreshOnClick = Neutron.compose([
  FetchableElement,
  Neutron({ tag: "refresh-on-click" }),
])
  .onEvent("click", ({ getFetchArgs }) => ({
    doFetch: getFetchArgs(),
  }));

RefreshOnClick.define();
```

```html
<refresh-on-click api-url="/api/status"></refresh-on-click>
```

Every prop, state field, and event documented below is inherited
verbatim by any element that composes `FetchableElement` — it flattens
directly into that element's own generated docs, so `<provider-fetch>`
and friends don't redeclare it.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `form-ref` | option | `string` |  | `<CSS Selector>` | CSS selector for a `<form>` to source the request from — its `action` (URL), `method`, `enctype` (Content-Type), and field values (as the JSON payload) all take priority over the matching attributes below. Omit to build the request entirely from attributes / custom `doFetch()` args. |  |
| `has-body` | option | `boolean` |  |  | Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`. |  |
| `api-url` | option | `string` | `""` |  | Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead. |  |
| `api-method` | option | `string` | `"GET"` |  | HTTP method. Always uppercased before the request is sent. |  |
| `header-accept` | option | `string` | `"application/json"` |  | `Accept` request header. |  |
| `header-content-type` | option | `string` | `"application/json"` |  | `Content-Type` request header. Dropped entirely when the request has no body. |  |
| `header-cache-control` | option | `string` |  |  | `Cache-Control` request header. Unset by default (browser default caching applies). |  |
| `fetch-redirect` | option | `string` |  | `"follow"` \| `"error"` \| `"manual"` | `RequestInit.redirect` mode. Unset defers to the browser default (`follow`). |  |
| `fetch-credentials` | option | `string` | `"include"` | `"omit"` \| `"same-origin"` \| `"include"` | `RequestInit.credentials` mode. |  |
| `is-loading` | state | `boolean` |  |  | A request is currently in flight. |  |
| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. Mutually exclusive with `is-loading` and `is-error`. |  |
| `is-error` | state | `boolean` |  |  | The most recent request failed (status 400 or above, network error, or a thrown error other than `AbortError`). Fires with the `error` event. |  |
| `did-load` | state | `boolean` |  |  | Work has succeeded and no failure followed. Stays set while a refresh loads, so content can stay on screen (stale-while-revalidate): gate it on `[did-load]` rather than `[is-success]`. Cleared on error. | `@excom/loadable-element` |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `FetchResponse` (`{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }`) | Response payload on success, or error payload on failure. Success shape: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `{tag}-loading` | `FetchableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched immediately before the request is sent. |
| `{tag}-success` | `FetchableSuccessEvent` (`CustomEvent & { type: "{tag}-success"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request resolves successfully. `event.detail` is the parsed response (see `provision`). |
| `{tag}-error` | `FetchableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; } \| { message: string; stack?: string }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails — status 400 or above, network error, or a thrown error. `event.detail` is the error payload (see `provision`). Not dispatched for aborted requests. |



There are no demos for this package — see
[provider-fetch](/packages/provider-fetch) for `FetchableElement` in
action against a real endpoint.

## Release notes

### 0.3.0 (2026-10-07)

- Add hydration of prerendered pages: an identical GET or HEAD request is answered from the page's hydration island, as often as the prerender made it, so the element announces `loading` then `success` without a network request

### 0.2.0 (2026-09-30)

- Add `did-load` from `loadable-element`: set on the first success, kept while a refresh runs, cleared on an error
- Update failed-request logging to one line: an error status (400 or above) logs a warning, `<tag>: request failed` with the response, which the default `KitLogger` level hides; a network or parse failure logs an error; an abort logs nothing

### 0.1.2 (2026-09-23)

- Fix typo in error message.

Older releases: https://nucleus.excom.dev/packages/fetchable-element


---

# gesture-handler

Let users drag, swipe, pinch and flick your UI — sheets, carousels, cards and images follow the finger, in CSS, with no per-frame script.


```html
<gesture-handler gesture-types="pan-y swipe" pointer-types="touch pen mouse" from-ref=":scope > content-drawer > header"
  handoff-ref=":scope > content-drawer" progress-axis="up" range-ref=":scope > content-drawer" snap-points="0 1">
  <quark-sheet>
    :scope {
      /* dragging an open sheet starts from fully open */
      &:has(> content-drawer[is-open]) {
        progress-offset: 1;
      }
      &:not(:has(> content-drawer[is-open])) {
        progress-offset: 0;
      }
      @on gesture-handler-start {
        content-drawer { is-scrubbing: ""; }
      }
      @on gesture-handler-end {
        content-drawer { is-open: event.detail.snap == 1; is-scrubbing: none; }
      }
    }
  </quark-sheet>
  <button type="button" command="--open" commandfor="demo-gesture-sheet">Open sheet</button>
  <content-drawer id="demo-gesture-sheet" class="absolute">
    <header><h2>Drag me</h2></header>
    <p>Two ways to dismiss it. Drag the header down and let go, or flick it —
      that is the <code>from-ref</code> grab handle.</p>
    <p>Or pull the text itself down: <code>handoff-ref</code> lets the sheet's
      own content scroll first, and only once it is back at the top does the
      next pull down become the same drag. Pulling up, or pulling down while
      the text is scrolled, keeps scrolling as usual.</p>
    <p>Scroll on. The sheet only takes the drag over at the very top, which is
      how a native sheet behaves.</p>
    <p>Keep going.</p>
    <p>Nearly there.</p>
    <p>Now scroll back up and pull once more — the sheet follows your finger
      and snaps to <code>0</code> or <code>1</code> on release.</p>
  </content-drawer>
  <style>
    #demo-gesture-handler-sheet > :first-child {
      /* short enough that the text scrolls: the handoff needs a scroller */
      content-drawer { max-block-size: 11rem; }
      /* the drag handle owns its touches; the content keeps scrolling */
      content-drawer > header {
        position: sticky;
        top: 0;
        touch-action: none;
        cursor: grab;
        background-color: inherit;
      }
    }
  </style>
</gesture-handler>
```


## Features

- **Swipe / pan / pinch / rotate / tap / long-press** Each recognized gesture is a tag-prefixed event
- **Follow the finger in CSS** Every frame lands in `--gesture-*` custom properties: scrubbable bottom sheets, swipe-to-dismiss, pinch-to-zoom, pull-to-refresh, parallax
- **Snap & fling** `snap-points` with velocity projection, a CSS transition on release (`--gesture-snap-duration` / `--gesture-snap-ease`), `gesture-handler-snap` when it lands
- **Drivable** Bounds, `progress-offset` and `is-disabled` are attributes a Quark rule sets from the driven element's state
- **Scoped starts** `from-ref` for drag handles, `from-edge` for edge swipes
- **Scroll handoff** `handoff-ref` lets a sheet's own scrolling content take the drag over when it runs out of scroll — a native-feeling pull-to-close
- **Native scrolling kept** `touch-action` follows `gesture-types`, so the page still scrolls where you don't pan

## Installation


`@excom/gesture-handler` v0.2.3

```bash
pnpm add @excom/gesture-handler
```

```bash
npm install @excom/gesture-handler
```

```bash
yarn add @excom/gesture-handler
```

### Import

```ts
import "@excom/gesture-handler";
```



## Usage

Wrap the surface the user touches. Pick the gestures with `gesture-types`; read the finger from `--gesture-*` in CSS (custom properties inherit, so any descendant can `var()` them); commit State on `gesture-handler-end` or `-snap` from a Quark `@on` block.

```html
<gesture-handler gesture-types="pan-y swipe" progress-axis="up" range-ref=":scope > content-drawer" snap-points="0 1">
  <quark-sheet>
    :scope {
      @on gesture-handler-start { content-drawer { is-scrubbing: ""; } }
      @on gesture-handler-end { content-drawer { is-open: event.detail.snap == 1; is-scrubbing: none; } }
    }
  </quark-sheet>
  <content-drawer>…</content-drawer>
</gesture-handler>
```

`--gesture-progress` is the travel along `progress-axis` as a fraction of the range (`range-ref` measures the driven element; `range-px` is a literal), clamped to `progress-min`..`progress-max` with optional `overshoot-resistance`. Written alongside it every frame: `--gesture-dx` / `-dy`, `--gesture-x` / `-y`, `--gesture-scale`, `--gesture-rotate`, `--gesture-vx` / `-vy`, `--gesture-pointers`; once per gesture: `--gesture-range-px`, `--gesture-width` / `-height`. Everything else is derived from those in the element's own CSS — `--gesture-distance`, `--gesture-angle`, `--gesture-progress-px`, `--gesture-x-ratio` / `-y-ratio` — so `var()` them the same way.

Values persist after release until the next gesture starts. On release the default action writes `--gesture-progress` straight to `detail.snap` and the element's own `transition` settles it there over `--gesture-snap-duration` (`200ms`) with `--gesture-snap-ease` (`ease-out`), firing `gesture-handler-snap` when it lands; the transition is off while `is-active`, so the finger itself is never eased, and a new gesture that interrupts the settle simply cancels it (no `-snap`).

### Driving NucleusKit elements

Elements that can be scrubbed expose a `--<tag>-…-progress` input and an `is-scrubbing` attribute; both default to the wrapping gesture-handler's `--gesture-progress`, so no mapping is needed:

| Element | Set up | While `is-scrubbing` |
| --- | --- | --- |
| `content-drawer` | `progress-axis` towards its open side, `range-ref` the drawer, `handoff-ref` the drawer too (it scrolls its own content) | Position follows `--content-drawer-open-progress` (`0` closed, `1` open), no transition |
| `content-carousel` | `slide-animation="track"`, `progress-min="-1" progress-max="1" snap-points="-1 0 1"` | The track follows `--content-carousel-progress` in slide widths |

The handoff is one Quark commit: the block that writes the final state (`is-open`, the active slide) also removes `is-scrubbing`, so the element switches from finger to State in the same paint. Commit on `-end` when a CSS transition should finish the motion (the drawer), on `-snap` when the element must be exactly at the snap point first (the carousel).

Anything else follows the same recipe: read `--gesture-*` in your own CSS, gate the mapping on a fact your sheet writes on start and clears on end.

Give a drag handle `touch-action: none` when using `from-ref`, so the browser does not scroll it away; without `from-ref` the element sets `touch-action` itself from `gesture-types`. For `pan-x` / `pan-y`, a touch whose first 3 px run along the handler's axis holds the page still for the rest of that touch (a non-passive `touchmove` listener does this; `touch-action` is unchanged), while a touch that starts across the axis scrolls the page as before. Add `mouse` to `pointer-types` for desktop dragging.

### Scroll handoff

`handoff-ref` names the scroll container(s) inside the surface whose *overscroll* starts a gesture (a `:scope`-relative selector; a comma list matches several). A pointer that goes down in one of them scrolls natively as usual. Only when its **first** move runs along `progress-axis`, nothing between the pointer and the element can still scroll that way (the named containers and any scroll container nested in or around them, so a scrolled editor inside a sheet scrolls back first), and `progress-offset` still has room to travel in that direction does the element cancel the native scroll for the rest of the touch and take the drag over — the same gesture, the same `--gesture-*` values and the same `-start` / `-end` / `-snap` events as a drag from a handle:

```html
<gesture-handler gesture-types="pan-y swipe" progress-axis="up" snap-points="0 1"
  from-ref=":scope > content-drawer > header" handoff-ref=":scope > content-drawer"
  range-ref=":scope > content-drawer">
```

An open sheet (`progress-offset: 1`) closes either from its header or by pulling its text down once the text is back at the top; pulling up, or pulling down mid-scroll, keeps scrolling. `handoff-ref` is additive — `from-ref` and `from-edge` starts are unchanged, and a `from-ref` handle inside a handoff container still starts on pointerdown. The element keeps `touch-action` out of the way while `handoff-ref` is set (the containers must be able to scroll), so give handles their own `touch-action: none`.

Mouse drags (`pointer-types="… mouse"`) take the same route with no native scroll to cancel: the first `pointermove` inside the container starts the gesture when nothing below the pointer can still scroll that way.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `gesture-types` | option | `tokenlist` | `"pan"` | `"pan"` \| `"pan-x"` \| `"pan-y"` \| `"pinch"` \| `"rotate"` \| `"swipe"` \| `"tap"` \| `"double-tap"` \| `"long-press"` | Gestures to recognize. `pan-x` / `pan-y` one axis (a touch starting along it holds the page still, one across it scrolls); `pan` both; `pinch` / `rotate` need two fingers; `swipe` velocity on release; `tap` / `double-tap` / `long-press` fire events. |
| `from-ref` | option | `string` |  | `<CSS Selector>` | Only start when pointerdown is inside this descendant (`:scope`-relative selector) — a drag handle, the sheet itself. Combined with `from-edge`, either qualifies. |
| `from-edge` | option | `tokenlist` |  | `"left"` \| `"right"` \| `"top"` \| `"bottom"` | Only start within `edge-px` of these edges — edge swipes (back nav, pulling a closed sheet up). |
| `edge-px` | option | `number` | `40` |  | Width of `from-edge` start zone (px). |
| `handoff-ref` | option | `string` |  | `<CSS Selector>` | Scroll containers that hand overscroll to the gesture (`:scope`-relative selector, comma list matches several) — e.g. a sheet closed by pulling its own content down. Pointerdown inside one scrolls natively; the gesture takes over only when the first move runs along `progress-axis`, every scroller between pointer and this element is at its limit that way, and `progress-offset` has room. Additive to `from-ref` / `from-edge`. |
| `pointer-types` | option | `tokenlist` | `"touch pen"` | `"touch"` \| `"pen"` \| `"mouse"` | Pointer types that can start a gesture. Add `mouse` for desktop drag. |
| `max-pointers` | option | `number` |  |  | Extra pointers beyond this many are ignored. Unset = `2` when `pinch` / `rotate` listed, else `1`. |
| `threshold-px` | option | `number` | `8` |  | Movement (px) before a pan is recognized. Taps / native scroll stay untouched below it. |
| `lock-axis` | option | `boolean` |  |  | A free `pan` locks to its dominant axis once recognized (`gesture-type` becomes `pan-x` / `pan-y`). |
| `arm-after` | option | `string` |  | `"long-press"` | Pans only arm after this gesture — `long-press` for hold-then-drag. |
| `long-press-ms` | option | `number` | `500` |  | Hold time (ms) for `long-press`; also tap time limit. |
| `double-tap-ms` | option | `number` | `300` |  | Max gap (ms) between taps for `double-tap`. |
| `swipe-min-velocity` | option | `number` | `0.5` |  | Release velocity (px/ms) that counts as a swipe. |
| `swipe-directions` | option | `tokenlist` |  | `"left"` \| `"right"` \| `"up"` \| `"down"` | Swipe directions to report. Unset = all four. |
| `progress-axis` | option | `string` |  | `"up"` \| `"down"` \| `"left"` \| `"right"` | Direction `--gesture-progress` grows. Unset = `down` for a `pan-y`-only element, else `right`. |
| `range-ref` | option | `string` |  | `<CSS Selector>` | Element whose size along `progress-axis` is the range of `progress` `0`..`1` (`:scope`-relative, read once per gesture) — sheet being dragged, slide being swiped. |
| `range-px` | option | `number` |  |  | Literal range (px) instead of `range-ref`. |
| `progress-min` | option | `number` | `0` |  | Lower bound of `progress`. |
| `progress-max` | option | `number` | `1` |  | Upper bound of `progress`. |
| `progress-offset` | option | `number` | `0` |  | Progress the gesture starts from. Set from a rule that reads the driven element's state (`1` while a sheet is open) so dragging it closed starts full. |
| `overshoot-resistance` | option | `number` | `0` |  | Rubber-band past `progress-min` / `progress-max`: `0` clamps, `0.3` overshoots at a third of travel. |
| `snap-points` | option | `tokenlist` |  | `<number>…` | Progress values to settle on after release (`0 0.5 1`). Target picked from position, fling velocity and swipe direction, reported as `detail.snap` on `-end`, settled on by the default action (a CSS transition, `--gesture-snap-duration` / `--gesture-snap-ease`). |
| `should-emit-move` | option | `boolean` |  |  | Fire `gesture-handler-move` every frame. Off by default; `--gesture-*` is enough for CSS. |
| `is-disabled` | hybrid | `boolean` |  |  | Ignore new pointers; a gesture in progress is cancelled. State-driven veto. |
| `is-active` | state | `boolean` |  |  | A pointer is down on the surface. Set from first pointer until release, so it also covers taps and pre-threshold phase. |
| `gesture-type` | state | `string` |  | `"pan"` \| `"pan-x"` \| `"pan-y"` \| `"pinch"` \| `"rotate"` | Recognized gesture in progress, unset before recognition and after release. |
| `pointer-count` | state | `number` |  |  | Pointers currently down. |
| `gesture-direction` | state | `string` |  | `"left"` \| `"right"` \| `"up"` \| `"down"` | Dominant travel direction of gesture in progress. |
| `last-gesture` | state | `string` |  | `"pan"` \| `"pan-x"` \| `"pan-y"` \| `"pinch"` \| `"rotate"` \| `"swipe-left"` \| `"swipe-right"` \| `"swipe-up"` \| `"swipe-down"` \| `"tap"` \| `"double-tap"` \| `"long-press"` | What last gesture turned out to be — style a "just swiped" state from it. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `GestureHandlerProvision` (`{ x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: \| "pan" \| "pan-x" \| "pan-y" \| "pinch" \| "rotate" \| "swipe" \| "tap" \| "double-tap" \| "long-press" \| null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number \| null; swipe: "left" \| "right" \| "up" \| "down" \| null; }`) | Last `-start` / `-end` / `-cancel` snapshot (`type`, travel, velocity, progress, `snap`, `swipe`, …). Not an attribute; per-frame values live in `--gesture-*`. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `gesture-handler-start` | `GestureHandlerStartEvent` (`CustomEvent & { type: "gesture-handler-start"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: \| "pan" \| "pan-x" \| "pan-y" \| "pinch" \| "rotate" \| "swipe" \| "tap" \| "double-tap" \| "long-press" \| null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number \| null; swipe: "left" \| "right" \| "up" \| "down" \| null; }; bubbles: true; cancelable: true; composed: true }`) | Gesture recognized: pan passed `threshold-px` (after `arm-after` if set), or a second finger for `pinch` / `rotate`. After `gesture-type` + `provision` set. `detail` = provision. Not cancelable — gate with `is-disabled`. |
| `gesture-handler-move` | `GestureHandlerMoveEvent` (`CustomEvent & { type: "gesture-handler-move"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: \| "pan" \| "pan-x" \| "pan-y" \| "pinch" \| "rotate" \| "swipe" \| "tap" \| "double-tap" \| "long-press" \| null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number \| null; swipe: "left" \| "right" \| "up" \| "down" \| null; }; bubbles: true; cancelable: true; composed: true }`) | Once per frame while a recognized gesture moves, only with `should-emit-move`. `detail` = provision. `--gesture-*` always updates, event or not. |
| `gesture-handler-end` | `GestureHandlerEndEvent` (`CustomEvent & { type: "gesture-handler-end"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: \| "pan" \| "pan-x" \| "pan-y" \| "pinch" \| "rotate" \| "swipe" \| "tap" \| "double-tap" \| "long-press" \| null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number \| null; swipe: "left" \| "right" \| "up" \| "down" \| null; }; bubbles: true; cancelable: true; composed: true }`) | Last pointer up after a recognized gesture. After `is-active` unset, `last-gesture` + `provision` set, and after `gesture-handler-swipe` if one was recognized. `detail.snap` = `snap-points` target from position / velocity / swipe (`null` without `snap-points`); `detail.swipe` = swipe direction. Default action: write `--gesture-progress` = `detail.snap`, which settles with a CSS transition (`--gesture-snap-duration` / `--gesture-snap-ease`), then `gesture-handler-snap`. `preventDefault()` leaves values where the finger left them. Persist until next gesture. |
| `gesture-handler-snap` | `GestureHandlerSnapEvent` (`CustomEvent & { type: "gesture-handler-snap"; detail: { value: number; index: number }; bubbles: true; cancelable: true; composed: true }`) | The settle transition reached the snap point (at once when there is nothing to animate; never when a new gesture interrupts it). `detail` = `{ value, index }` into `snap-points`. Commit here when consumer CSS follows `--gesture-progress` until the end. |
| `gesture-handler-cancel` | `GestureHandlerCancelEvent` (`CustomEvent & { type: "gesture-handler-cancel"; detail: { x: number; y: number; dx: number; dy: number; vx: number; vy: number; progress: number; scale: number; rotate: number; pointers: number; } & { type: \| "pan" \| "pan-x" \| "pan-y" \| "pinch" \| "rotate" \| "swipe" \| "tap" \| "double-tap" \| "long-press" \| null; pointerType: string; distance: number; rangePx: number; durationMs: number; snap: number \| null; swipe: "left" \| "right" \| "up" \| "down" \| null; }; bubbles: true; cancelable: true; composed: true }`) | Recognized gesture cut short: browser took pointer (`pointercancel`, usually native scroll), `is-disabled` set, or element left the document. `detail` = provision. No `-end`, no glide. |
| `gesture-handler-swipe` | `GestureHandlerSwipeEvent` (`CustomEvent & { type: "gesture-handler-swipe" \| `gesture-handler-swipe-${"left" \| "right" \| "up" \| "down"}`; detail: { direction: "left" \| "right" \| "up" \| "down"; velocity: number }; bubbles: true; cancelable: true; composed: true }`) | On release, velocity along dominant axis ≥ `swipe-min-velocity` and direction allowed by `swipe-directions`. `detail` = `{ direction, velocity }` (px/ms). Direction twin fires next (`gesture-handler-swipe-left` / `-right` / `-up` / `-down`). |
| `gesture-handler-tap` | `GestureHandlerPointEvent` (`CustomEvent & { type: \| "gesture-handler-tap" \| "gesture-handler-double-tap" \| "gesture-handler-long-press"; detail: { x: number; y: number }; bubbles: true; cancelable: true; composed: true }`) | Down and up without moving past `threshold-px`, within `long-press-ms`. `detail` = `{ x, y }` relative to the element. |
| `gesture-handler-double-tap` | `GestureHandlerPointEvent` (`CustomEvent & { type: \| "gesture-handler-tap" \| "gesture-handler-double-tap" \| "gesture-handler-long-press"; detail: { x: number; y: number }; bubbles: true; cancelable: true; composed: true }`) | Second tap within `double-tap-ms` of the previous (after its `gesture-handler-tap`). `detail` = `{ x, y }`. Pair consumed; a third tap starts over. |
| `gesture-handler-long-press` | `GestureHandlerPointEvent` (`CustomEvent & { type: \| "gesture-handler-tap" \| "gesture-handler-double-tap" \| "gesture-handler-long-press"; detail: { x: number; y: number }; bubbles: true; cancelable: true; composed: true }`) | Pointer stayed down without moving for `long-press-ms`. `detail` = `{ x, y }`. |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--gesture-x` | `<length>` | `0px` | Pointer centroid inside the element (px), horizontal — spotlight / parallax effects. Written every frame of a gesture; this is the resting value. |
| `--gesture-y` | `<length>` | `0px` | Pointer centroid inside the element (px), vertical. |
| `--gesture-dx` | `<length>` | `0px` | Horizontal travel since the gesture started (px) — drag-to-move, swipe-to-dismiss. |
| `--gesture-dy` | `<length>` | `0px` | Vertical travel since the gesture started (px). |
| `--gesture-vx` | `<number>` | `0` | Horizontal velocity over the last ~100 ms (px/ms). |
| `--gesture-vy` | `<number>` | `0` | Vertical velocity over the last ~100 ms (px/ms). |
| `--gesture-progress` | `<number>` | `0` | Travel along `progress-axis` as a fraction of the range, clamped to `progress-min`..`progress-max` — the value a scrubbable sheet, carousel or slider follows. Persists after release until the next gesture. |
| `--gesture-range-px` | `<length>` | `0px` | The measured range (`range-ref` size along the axis, or `range-px`). Written once, when the gesture starts. |
| `--gesture-width` | `<length>` | `0px` | The element's own width, measured when the gesture starts. |
| `--gesture-height` | `<length>` | `0px` | The element's own height, measured when the gesture starts. |
| `--gesture-scale` | `<number>` | `1` | Two-finger pinch ratio (`1` = unchanged) — pinch-to-zoom. |
| `--gesture-rotate` | `<angle>` | `0deg` | Two-finger rotation — rotate-to-adjust. |
| `--gesture-pointers` | `<integer>` | `0` | Pointers currently down. |
| `--gesture-distance` | `<length>` | `hypot(var(--gesture-dx), var(--gesture-dy))` | Length of the travel (px). Computed from `--gesture-dx` / `--gesture-dy`. |
| `--gesture-angle` | `<angle>` | `atan2(var(--gesture-dy), var(--gesture-dx))` | Direction of the travel: `0deg` right, `90deg` down. Computed from `--gesture-dx` / `--gesture-dy`. |
| `--gesture-progress-px` | `<length>` | `calc(var(--gesture-progress) * var(--gesture-range-px))` | `--gesture-progress` in px. Computed from `--gesture-progress` and `--gesture-range-px`. |
| `--gesture-x-ratio` | `<number>` | `tan(atan2(var(--gesture-x), var(--gesture-width)))` | `--gesture-x` as a 0..1 fraction of the element's width. Computed from `--gesture-x` and `--gesture-width`. |
| `--gesture-y-ratio` | `<number>` | `tan(atan2(var(--gesture-y), var(--gesture-height)))` | `--gesture-y` as a 0..1 fraction of the element's height. Computed from `--gesture-y` and `--gesture-height`. |
| `--gesture-snap-duration` | `<time>` | `200ms` | How long `--gesture-progress` takes to settle on its snap point after release. |
| `--gesture-snap-ease` | `<easing-function>` | `ease-out` | Easing of that settle. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--gesture-handler` | element | `gesture-handler`, `.tag-gesture-handler` |  |
| `:--gesture-handler--is-active` | state | `[is-active]`, `[data-active]` |  |



### Examples

#### Swipeable carousel

`slide-animation="track"` turns `content-carousel` into a draggable track. `progress-axis="left"` makes a leftward drag pull the next slide in; the `:has()` rules narrow the bounds at the first and last slide so nothing wraps mid-drag; the `gesture-handler-snap` block swaps `is-active` and un-scrubs in one commit.


```html
<gesture-handler gesture-types="pan-x swipe" pointer-types="touch pen mouse" progress-axis="left"
  range-ref=":scope > content-carousel" progress-min="-1" progress-max="1" snap-points="-1 0 1"
  overshoot-resistance="0.2">
  <quark-sheet>
    :scope {
      /* no wrap-around while dragging: clamp the ends */
      &:has(content-carousel-slide[is-active]:first-of-type) { progress-min: 0; }
      &:not(:has(content-carousel-slide[is-active]:first-of-type)) { progress-min: -1; }
      &:has(content-carousel-slide[is-active]:last-of-type) { progress-max: 0; }
      &:not(:has(content-carousel-slide[is-active]:last-of-type)) { progress-max: 1; }
      @on gesture-handler-start {
        content-carousel { is-scrubbing: ""; }
      }
      /* commit once the glide lands: the slide swap and the un-scrub paint together */
      @on gesture-handler-snap {
        /* snap-points "-1 0 1" → index 0 = previous, 1 = stay, 2 = next */
        $snap: event.detail.index;
        content-carousel {
          is-scrubbing: none;
          content-carousel-slide[is-active] + content-carousel-slide {
            is-active: $snap == 2 or preserve;
          }
          content-carousel-slide:has(+ content-carousel-slide[is-active]) {
            is-active: $snap == 0 or preserve;
          }
          content-carousel-slide[is-active] {
            is-active: $snap == 1 or none;
          }
        }
      }
    }
  </quark-sheet>
  <content-carousel slide-animation="track">
    <content-carousel-slide is-active>
      <h2>One</h2>
    </content-carousel-slide>
    <content-carousel-slide>
      <h2>Two</h2>
    </content-carousel-slide>
    <content-carousel-slide>
      <h2>Three</h2>
    </content-carousel-slide>
  </content-carousel>
</gesture-handler>
```


#### Pinch, rotate, drag

Two fingers (a trackpad or touch screen) for `--gesture-scale` and `--gesture-rotate`; one for `--gesture-dx` / `--gesture-dy`. Pure CSS mapping, no sheet. Each gesture starts from the resting values.


```html
<gesture-handler gesture-types="pan pinch rotate" pointer-types="touch pen mouse">
  <figure>Drag, pinch, twist</figure>
  <style>
    #demo-gesture-handler-pinch > :first-child figure {
      translate: var(--gesture-dx, 0px) var(--gesture-dy, 0px);
      scale: var(--gesture-scale, 1);
      rotate: var(--gesture-rotate, 0deg);
    }
  </style>
</gesture-handler>
```


#### Swipe to dismiss

`snap-points="-1 0 1"` with a literal `range-px`: a flick past `swipe-min-velocity` snaps the card off to the side, and the `gesture-handler-snap` block records the fact. A tap starts a new gesture (values reset) and clears it.


```html
<gesture-handler gesture-types="pan-x swipe tap" pointer-types="touch pen mouse" range-px="240" progress-min="-1" progress-max="1"
  snap-points="-1 0 1" overshoot-resistance="0.4">
  <quark-sheet>
    :scope {
      @on gesture-handler-snap {
        article { data-is-dismissed: event.detail.value != 0; }
      }
      @on gesture-handler-tap {
        article { data-is-dismissed: none; }
      }
    }
  </quark-sheet>
  <article>
    <h2>Swipe me away</h2>
    <p>Flick left or right. Tap to bring it back.</p>
  </article>
  <style>
    #demo-gesture-handler-swipe > :first-child article {
      translate: calc(var(--gesture-progress, 0) * 240px);
      rotate: calc(var(--gesture-progress, 0) * 8deg);
      &[data-is-dismissed] { opacity: 0.25; }
    }
  </style>
</gesture-handler>
```

## Release notes

### 0.2.2 (2026-10-07)

- Fix a type error in projects that load Node's timer types: the element's animation frame handle is typed as a number

### 0.2.1 (2026-10-01)

- Pan handlers cancel the page's cross-axis scroll on the first touch move

### 0.2.0 (2026-09-30)

- Hand a `handoff-ref` overscroll to the gesture only when every scroller between the pointer and the element is at its limit, so content scrolled inside a nested scroller scrolls back before the sheet moves

Older releases: https://nucleus.excom.dev/packages/gesture-handler


---

# include-content

One-stop shop for rendering a view when & where you need it — lazy-loading/unloading, conditional rendering, portalling… no app JS required.


```html
<div>
  <a>Hover me</a>
  <include-content lazy-load>
    <template>
      <p>HTML inserted</p>
    </template>
  </include-content>
  <small role="note">See Live document tab for DOM changes.</small>
  <style>
    #demo-include-content-simple > :first-child {
      a:not(:hover) + include-content:not([is-active]) {
        display: none;
      }
    }
  </style>
</div>
```


## Features

- **Zero JS** Sophisticated UX from a simple HTML-only API, as with all NucleusKit elements.
- **Lazy (un)load** Lazy load and lazy unload your views
- **Eager / idle** Prioritize critical content; defer the rest
- **Prefetch** Warm templates so they're ready on activate
- **Shared / remote templates** Point at a DOM `<template>` or URL
- **Choose the host** Portal into light DOM, shadow, author iframe, or any selector
- **Keep state** Reuse the same tree across toggles
- **Animatable** Built-in fade, or bring your own with `.instant`

## Installation


`@excom/include-content` v0.1.4

```bash
pnpm add @excom/include-content
```

```bash
npm install @excom/include-content
```

```bash
yarn add @excom/include-content
```

### Import

```ts
import "@excom/include-content";
```



## Usage

Put a `<template>` inside (or set `template-ref`) and pick when it should appear. For conditional rendering, use Quark or JS to toggle `is-active`.

```html
<include-content lazy-load template-ref="/path/to/view.html"></include-content>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `idle-load` | option | `boolean` |  |  | Activate after first paint, when the browser is idle. Useful for below-the-fold / secondary views that should not compete with critical content. |  |
| `lazy-load` | option | `boolean` |  |  | Activate when this element is on screen. Pair with `lazy-unload` for lazy load and lazy unload of views. |  |
| `lazy-unload` | option | `boolean` |  |  | Deactivate (unrender) when no longer on screen. Use with `lazy-load` to free DOM for off-screen views. |  |
| `observer-root` | option | `string` |  | `<CSS Selector>` | Scroll container for lazy load / unload. Defaults to the viewport. |  |
| `observer-root-margin` | option | `string` | `"-1px -1px -1px -1px"` | `<length>` \| `<percentage>` | How far outside the root counts as "visible". Expand (e.g. `500px`) to lazy-load a view *before* it enters the viewport so users never see an empty slot; shrink (default `-1px`) so edge-flush elements wait until they truly enter. |  |
| `observer-threshold` | option | `number` |  |  | Fraction of the element that must be visible (`0`–`1`) before activating. |  |
| `observer-delay` | option | `number` | `0` |  | Minimum time visible before activating (ms). Ignored where unsupported. Useful for ensuring lazy load is not triggered when a programmatic smooth scroll zips the user right past the element. |  |
| `template-ref` | option | `string` | `":scope > template"` | `<CSS Selector>` \| `<URL>` | Source `<template>` — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use `:scope` to relatively select elements: e.g. `main:has(:scope) > template` | `@excom/renderable-element` |
| `bypass-cache` | option | `boolean` |  |  | Skip the in-memory response cache (URL `template-ref` only). | `@excom/renderable-element` |
| `pre-fetch` | option | `string` | `"lazy"` | `""` \| `"eager"` \| `"idle"` \| `"lazy"` | When to fetch the template, independent of when it renders. `""` aliases `eager`. `idle` never runs in a prerender. | `@excom/renderable-element` |
| `persist-content` | option | `boolean` |  |  | Reuse the same live nodes across unrender / render (held on `_persistedTree`) so form values, scroll position, and subtree state survive toggles. | `@excom/renderable-element` |
| `host-ref` | option | `string` |  | `"shadow"` \| `"iframe"` \| `<CSS Selector>` | Where rendered children land. Unset = this element's light DOM. `shadow` attaches an open shadow root. `iframe` paints into a child `<iframe data-render-host>` body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector. | `@excom/renderable-element` |
| `ready-on` | option | `string` |  | `<Event Name>` | Event name that marks rendered children "ready". Until it fires, `delaying-ready` is set so CSS can hide the host for a coordinated paint / view transition. Prerendered content kept at hydration is ready at once, never hidden. | `@excom/renderable-element` |
| `is-active` | hybrid | `boolean` |  |  | Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc. | `@excom/renderable-element` |
| `is-loading` | state | `boolean` |  |  | Template fetch in flight. | `@excom/renderable-element` |
| `did-load` | state | `boolean` |  |  | Template resolved at least once. Stays set across `is-active` toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when `template-ref` changes or `--reload` forces a fresh resolve. | `@excom/renderable-element` |
| `is-error` | state | `boolean` |  |  | Latest template fetch rejected (excluding abort). Fires with the `error` event. | `@excom/renderable-element` |
| `delaying-ready` | state | `boolean` |  |  | Between `render` and the matching `ready-on` event (or a failed load). Hook with CSS for coordinated paints / view transitions. | `@excom/renderable-element` |

#### Recognized Elements

| Relationship | Selector | Required | Description | Inherited from |
| --- | --- | --- | --- | --- |
| `template` | child | no | Optional immediate `<template>` child used when `template-ref` is the default `":scope > template"`. Not required when `template-ref` points at a selector or URL elsewhere. | `@excom/renderable-element` |
| `iframe[data-render-host]` | child | no | Required when `host-ref="iframe"`. Content paints into `iframe.contentDocument.body`. Provide your own iframe (e.g. with `srcdoc`); the element will not create one. | `@excom/renderable-element` |

#### Fires

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `include-content-render` | `RenderableRenderEvent` (`CustomEvent & { type: "{tag}-render"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes active and is about to place template content into the host. `event.detail` is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding `ready-on` event fires (or immediately if `ready-on` is unset). The promise rejects if the template fails to load, `host-ref` resolves to no host (nor an author iframe still loading), or the element is torn down mid-flight (`startTeardown` while loading / `delaying-ready`). Call `preventDefault()` to defer rendering and invoke `event.detail()` later. | `@excom/renderable-element` |
| `include-content-unrender` | `RenderableUnrenderEvent` (`CustomEvent & { type: "{tag}-unrender"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes inactive and content is already painted. `event.detail` is a thunk that removes the rendered children. Call `preventDefault()` to defer the removal. Not fired when teardown cancels an in-flight load — that path emits `aborted` instead. | `@excom/renderable-element` |
| `include-content-did-render` | `RenderableDidRenderEvent` (`CustomEvent & { type: "{tag}-did-render"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after the template content has actually been placed into the host. | `@excom/renderable-element` |
| `include-content-did-unrender` | `RenderableDidUnrenderEvent` (`CustomEvent & { type: "{tag}-did-unrender"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after rendered children have been removed from the host. | `@excom/renderable-element` |
| `include-content-error` | `RenderableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the template promise rejects with anything other than an `AbortError`. | `@excom/renderable-element` |
| `include-content-aborted` | `RenderableAbortedEvent` (`CustomEvent & { type: "{tag}-aborted"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when an in-flight load / ready wait is canceled because `is-active` was unset (via `startTeardown`). | `@excom/renderable-element` |

#### Commands

| Command | Action | Inherited from |
| --- | --- | --- |
| `--reload` | Stops waiting for any in-flight load and re-resolves the template, bypassing the cache for URL refs (useful after remote content changes). A URL request is shared by the page, so the one in flight is not cancelled. | `@excom/renderable-element` |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) | Inherited from |
| --- | --- | --- |
| `include-content-render` | Invokes `event.detail()` to load (if needed) and render the template into the host. | `@excom/renderable-element` |
| `include-content-unrender` | Invokes `event.detail()` to remove rendered children from the host. | `@excom/renderable-element` |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--include-content-transition-duration` | `<time>` | `0.15s` | Fade-in duration. |
| `--include-content-transition-ease` | `*` | `ease-in` | Fade-in easing. |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.instant` | Skip the built-in fade — bring your own animation / view transition. Also opts-out if the element is portalling content elsewhere ([host-ref]) |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--include-content` | element | `include-content`, `.tag-include-content` |  |
| `:--include-content--lazy-load` | state | `[lazy-load]`, `[data-lazy-load]` |  |
| `:--include-content--lazy-unload` | state | `[lazy-unload]`, `[data-lazy-unload]` |  |
| `:--include-content--did-load` | state | `[did-load]`, `[data-did-load]` |  |
| `:--include-content--is-active` | state | `[is-active]`, `[aria-current]` |  |
| `:--include-content--host-shadow` | state | `[host-ref="shadow"]`, `[data-host-ref="shadow"]` |  |



### Examples

#### Template include

Break your app into smaller views. Point `template-ref` at a `<template>` or a URL with `is-active` to render it immediately. This demo does both. A `<script>` inside a URL template does not run; stylesheets, `<style>` and `<quark-sheet>` do.


```html
<div>
  <template id="ic-include-piece">
    <p>A reusable view piece.</p>
  </template>
  <include-content is-active template-ref="#ic-include-piece"></include-content>
  <include-content is-active template-ref="/fragments/remote-include.html"></include-content>
</div>
```


#### Lazy Load & Unload

`lazy-load` waits until on screen; `lazy-unload` removes it when it leaves. Give the host a real `min-height` so the trigger isn't ambiguous. Tune with `observer-root`, `observer-root-margin`, `observer-threshold`, and `observer-delay` — e.g. expand the margin to pre-render before the user scrolls to it. If remote template, pair with `pre-fetch="idle"` to warm the cache early.


```html
<section>
  <p>Scroll down…</p>
  <include-content lazy-load lazy-unload observer-root="section:has(> :scope)"
    observer-root-margin="0px" observer-threshold="0.5">
    <template>
      <p>Rendered at 50% visibility. Scroll away to remove
        (<code>lazy-unload</code>).</p>
    </template>
  </include-content>
  <p>Keep scrolling…</p>
  <style>
    #demo-include-content-lazy > :first-child {
      include-content {
        /* Prevent size collapse → render/unrender loop */
        min-height: 108px;
      }
    }
  </style>
</section>
```


#### Portal elsewhere

By default content lands in the element's light DOM. Set `host-ref` to
`shadow`, `iframe` (with a child `<iframe data-render-host>`), or any CSS
selector to render somewhere else. The iframe host only moves nodes: custom
elements inside it upgrade only if that document loads their definitions.


```html
<div>
  <include-content is-active host-ref="#ic-portal-mount">
    <template>
      <p>Portaled into the aside.</p>
    </template>
  </include-content>
  <aside id="ic-portal-mount"></aside>
</div>
```


#### Keep tree state

Toggling `is-active` off leaves `did-load` set (warm re-resolve; URL
refs hit the shared fetch cache). `persist-content` goes further and
reuses the same live nodes so implicit state (form values, open details,
etc.) survives toggles.


```html
<div>
  <quark-sheet>
    :scope {
      @on change {
        include-content { is-active: if(event.target.checked: ""; else: none); }
      }
    }
  </quark-sheet>
  <form>
    <label>
      <input type="checkbox" name="is-active" checked />
      Active
    </label>
  </form>
  <include-content is-active persist-content>
    <template>
      <label>
        Type, then toggle Active —
        <input type="text" placeholder="value is kept" />
      </label>
    </template>
  </include-content>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources

## Demo sources

### template-ref

```html
<div>
  <template id="ic-shared-template">
    <p>Shared template — both hosts render this node.</p>
  </template>
  <include-content is-active template-ref="#ic-shared-template"></include-content>
  <include-content idle-load template-ref="#ic-shared-template"></include-content>
</div>
```


---

# listenable-element

Declarative event and lifecycle listening for Neutron elements —
filter, debounce, vibrate, and hand off to your `actionHandler`.

## Features

- **Event / lifecycle hooks** Listen for DOM events or `connected` /
  `disconnected` / `adopted`
- **Host retarget** `host-ref="window"` / `document` / any selector —
  Escape to dismiss, shortcuts outside the bubble path
- **Target filters** Selector, keycode (`shift+k` chords), and pathname gates
- **Debounce / delay** Coalesce noisy input
- **Event hygiene** `prevent-default` / `stop-propagation` /
  `stop-immediate-propagation`
- **Haptic pulse** Optional `vibrate-ms` on handle

## Installation


`@excom/listenable-element` v0.2.2

```bash
pnpm add @excom/listenable-element
```

```bash
npm install @excom/listenable-element
```

```bash
yarn add @excom/listenable-element
```

### Import

```ts
import { /* … */ } from "@excom/listenable-element";
```



## Usage

Compose `ListenableElement` and implement `actionHandler`. Concrete
consumers include `<spa-a>` and `<event-handler>`.

```ts
import { Neutron } from "@excom/neutron";
import { ListenableElement } from "@excom/listenable-element";

export const TapLog = Neutron.compose([
  ListenableElement,
  Neutron({ tag: "tap-log" }),
])
  .defineMethods({
    actionHandler: (_el, e) => {
      console.log("handled", e.type);
    },
  });

TapLog.define();
```

```html
<tap-log listen-for="click keydown" keycode-filter="enter">
  Tap or Enter
</tap-log>
```

`host-ref` moves listening off `:scope` — e.g. `host-ref="window"` for
global keydown. See `<event-handler>` for Escape-to-dismiss examples.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. |
| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). |
| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. |
| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. |
| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. |
| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`/`cmd`. Name the space bar `space` / `spacebar` and the plus key `plus` (`shift+space`). Case-insensitive. |
| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. |
| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). |
| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). |
| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). |
| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. |
| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. |
| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). |



### Examples

#### Default click → navigate

`<spa-a>` inherits this base and defaults to click when `listen-for`
is unset:

```html
<spa-a route-href="/pricing">Pricing</spa-a>
```

#### Filter & debounce

```html
<event-handler
  listen-for="input"
  delay-ms="200"
  is-debounced
  fire-event="search-query"
>
  <input name="q" />
</event-handler>
```

See `<event-handler>` and `<spa-a>` package docs for more examples
built on this mixin.

## Release notes

### 0.2.0 (2026-09-30)

- Add the key names `space` / `spacebar` and `plus` to `keycode-filter` (`shift+space`), and `cmd` as an alias of `meta`
- Update a `keycode-filter` holding only spaces to match no key and warn once (it was no filter); write `space` for the space bar

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# loadable-element

Loading / success / error state, a `provision`, and the three events — once, for every element that does async work.

## Features

- **Three states** `is-loading` / `is-success` / `is-error`, mutually exclusive
- **Stale-while-revalidate** `did-load` is set on the first success, kept through a refresh, cleared on an error — keep content on screen during a refresh
- **One payload** The result or the error lands on `provision`
- **Three events** `{tag}-loading` / `{tag}-success` / `{tag}-error`, tag-prefixed automatically
- **Four effects** `_setLoading`, `_setSuccess`, `_setError`, `_resetLoadState` — the element decides *when*, the base does the bookkeeping

## Installation


`@excom/loadable-element` v0.2.2

```bash
pnpm add @excom/loadable-element
```

```bash
npm install @excom/loadable-element
```

```bash
yarn add @excom/loadable-element
```

### Import

```ts
import { /* … */ } from "@excom/loadable-element";
```



## Usage

Compose `LoadableElement` and call its effects from your own lifecycles. `FetchableElement` (and every element built on it) and `quark-sheet` compose it this way.

```ts
import { LoadableElement } from "@excom/loadable-element";
import { Neutron } from "@excom/neutron";

export const LoadJson = Neutron.compose([
  LoadableElement,
  Neutron({ tag: "load-json", props: { srcUrl: String, _promise: Promise } }),
])
  .onPropSet("srcUrl", ({ srcUrl }) => [
    { _setLoading: [] },
    { _promise: fetch(srcUrl).then((r) => r.json()) },
  ])
  .onPromiseResolved("_promise", (_, { _promise }) => ({ _setSuccess: [_promise] }))
  .onPromiseRejected("_promise", (_, { _promise }) => ({ _setError: [_promise] }));

LoadJson.define();
```

```html
<load-json src-url="/api/user"></load-json>
```

```quark
load-json[is-success] { $user: prop("provision"); }
load-json[is-error] [bind-message] { content: prop("provision").message; }
```

Cancelled or superseded work calls `_resetLoadState` (no event) — pair with [abortable-element](/packages/abortable-element) to abort the promise itself.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-loading` | state | `boolean` |  |  | Work is in flight. |
| `is-success` | state | `boolean` |  |  | The most recent work finished successfully. Mutually exclusive with `is-loading` and `is-error`. |
| `is-error` | state | `boolean` |  |  | The most recent work failed. Mutually exclusive with `is-loading` and `is-success`. |
| `did-load` | state | `boolean` |  |  | Work has succeeded and no failure followed. Stays set while a refresh loads, so content can stay on screen (stale-while-revalidate): gate it on `[did-load]` rather than `[is-success]`. Cleared on error. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `unknown` | The result of the most recent work on success, or the error payload on failure. Shape is defined by the composing element. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `{tag}-loading` | `LoadableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After `is-loading` is set (work started). |
| `{tag}-success` | `LoadableSuccessEvent` | After `is-success` is set. `event.detail` is the new `provision`. |
| `{tag}-error` | `LoadableErrorEvent` | After `is-error` is set. `event.detail` is the error payload (also stored as `provision`). |

## Release notes

### 0.2.0 (2026-09-30)

- Add `did-load`: set on the first success, kept while a refresh loads and after a cancel, and cleared on an error, so content can stay on screen during a refresh with `[did-load]` instead of `[is-success]`

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<mapbox-view>`

**Tag:** `<mapbox-view>`

## Installation

`@excom/mapbox-view` v0.1.4

```bash
pnpm add @excom/mapbox-view
```

```bash
npm install @excom/mapbox-view
```

```bash
yarn add @excom/mapbox-view
```

### Import

```ts
import "@excom/mapbox-view";
```

## API

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--mapbox-view` | element | `mapbox-view`, `.tag-mapbox-view` |  |

## Release notes

### 0.1.1 (2026-09-23)

- Fix `exports` to omit `types` conditions; the package emits no declaration files, so every condition pointed at a missing `.d.ts`
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<mapbox-view-marker>`

**Tag:** `<mapbox-view-marker>`


---

# network-status

Live connectivity readout — `navigator.onLine` plus connection type and
speed where the browser exposes them.


```html
<div>
  <network-status></network-status>
  <small role="note">Live — reflects real connectivity. Toggle your
    devtools network throttling (or your device's wifi/data) to see it change.</small>
</div>
```


## Features

- **CSS-driven UI** Style from `[is-online]` / `[connection-type]`
- **Live events** `online` / `offline` / `change` fire as connectivity
  shifts — on transitions, never at mount
- **Bindable state** `.provision` is the full snapshot; read it from Quark
  with `prop("provision")`
- **Network Information API** Connection type + effective speed where
  supported
- **Graceful degradation** Unsupported fields stay `null`; core
  online/offline still works everywhere

## Installation


`@excom/network-status` v0.1.4

```bash
pnpm add @excom/network-status
```

```bash
npm install @excom/network-status
```

```bash
yarn add @excom/network-status
```

### Import

```ts
import "@excom/network-status";
```



## Usage

Drop it anywhere and hook `[is-online]` / `[is-mounted]` with CSS, or
listen for its events from a parent.

```html
<network-status></network-status>
```

```css
network-status:not([is-mounted])::before {
  content: "Loading…";
}
network-status[is-online]::before {
  content: "📶 Online";
}
network-status[is-mounted]:not([is-online])::before {
  content: "📵 Offline";
}
```

Nothing fires at mount: the first read sets `is-online` and `.provision`
only. React to the attribute (or `prop("provision")`) for the initial
state; `network-status-online` / `-offline` report transitions.

The Network Information API (`connection-type`, `effective-type`,
`downlink`, `rtt`) is Chromium-only — Safari and Firefox leave those
fields `null`. Build critical UX on `is-online` alone; treat the rest as
a progressive enhancement. Safari/iOS also have known `navigator.onLine`
reliability quirks — see `INTERNAL.md`.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-online` | state | `boolean` |  |  | Current `navigator.onLine` value. |
| `connection-type` | state | `string` |  |  | Connection type (`wifi`, `cellular`, `ethernet`, …) from the Network Information API. `null` where unsupported (Safari, Firefox). |
| `effective-type` | state | `string` |  |  | Effective connection type (`4g`, `3g`, `2g`, `slow-2g`) from the Network Information API. `null` where unsupported (Safari, Firefox). |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `NetworkStatusProvision` (`{ isOnline: boolean; connectionType?: string \| null; effectiveType?: string \| null; downlink?: number \| null; rtt?: number \| null; lastOnline?: number \| null; lastOffline?: number \| null; }`) | Full connectivity snapshot: `{ isOnline, connectionType, effectiveType, downlink, rtt, lastOnline, lastOffline }`. Set at mount and on every change; the same object dispatched as `event.detail` on every fired event. `lastOnline` / `lastOffline` are stamped on transitions only. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `network-status-online` | `NetworkStatusOnlineEvent` (`CustomEvent & { type: "network-status-online"; detail: { isOnline: boolean; connectionType?: string \| null; effectiveType?: string \| null; downlink?: number \| null; rtt?: number \| null; lastOnline?: number \| null; lastOffline?: number \| null; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on a transition from offline to online, never at mount. `event.detail` is the full `.provision` payload. |
| `network-status-offline` | `NetworkStatusOfflineEvent` (`CustomEvent & { type: "network-status-offline"; detail: { isOnline: boolean; connectionType?: string \| null; effectiveType?: string \| null; downlink?: number \| null; rtt?: number \| null; lastOnline?: number \| null; lastOffline?: number \| null; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on a transition from online to offline, never at mount. `event.detail` is the full `.provision` payload. |
| `network-status-change` | `NetworkStatusChangeEvent` (`CustomEvent & { type: "network-status-change"; detail: { isOnline: boolean; connectionType?: string \| null; effectiveType?: string \| null; downlink?: number \| null; rtt?: number \| null; lastOnline?: number \| null; lastOffline?: number \| null; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when connection details change without an online/offline transition (Network Information API only), never at mount. `event.detail` is the full `.provision` payload. |



### Examples

#### Offline banner

A banner shown purely by CSS attribute selector — no listeners needed.


```html
<div>
  <network-status></network-status>
  <p role="alert">You're offline — some features may be unavailable.</p>
  <small role="note">Banner is CSS-only, driven by
    <code>[is-online]</code>. Go offline to see it appear.</small>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# provider-fetch

Fetch data with HTML. Pair it with Quark to render the data. Zero app JS.


```html
<section>
  <provider-fetch api-url="/api/todos/1">
    <h4>Fetching todo...</h4>
    <span></span>
  </provider-fetch>
  <quark-sheet>
    provider-fetch[is-success] {
      $todo: prop("provision").body;
      h4 { content: "Todo ##{$todo.id}: #{$todo.title}"; }
      span { content: "Completed: #{$todo.completed}"; }
    }
  </quark-sheet>
</section>
```


## Features

- **Provides data** Use Quark to render that data
- **Auto-fetch** Fetches whenever `api-url` is set or changes
- **Re-fetch on demand** The `--fetch` command (`<button command="--fetch" commandfor="…">`) forces a re-fetch
- **Pausable** `is-paused` holds off auto-fetch without removing state
- **Highly configurable** Headers, method, `form-ref`,
  credentials, redirect, etc

## Installation


`@excom/provider-fetch` v0.1.5

```bash
pnpm add @excom/provider-fetch
```

```bash
npm install @excom/provider-fetch
```

```bash
yarn add @excom/provider-fetch
```

### Import

```ts
import "@excom/provider-fetch";
```



## Usage

```html
<provider-fetch api-url="/api/todos"></provider-fetch>
```

Hook the lifecycle state with CSS:

```css
provider-fetch[is-loading] { /* show loading spinner */ }
provider-fetch[is-error]::before { content: "An error occurred." }
```

`did-load` is set on the first success, kept through a refresh (where `is-loading` replaces `is-success`) and cleared on an error: gate content on `[did-load]` to keep it on screen during a refresh.

Or Quark:

```quark
provider-fetch[is-success] {
  $todo: prop("provision").body;
  span { content: $todo.title; }
}
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `is-paused` | option | `boolean` |  |  | Pause auto-fetch. While set, `api-url` changes are ignored; the `--fetch` command still works. |  |
| `form-ref` | option | `string` |  | `<CSS Selector>` | CSS selector for a `<form>` to source the request from — its `action` (URL), `method`, `enctype` (Content-Type), and field values (as the JSON payload) all take priority over the matching attributes below. Omit to build the request entirely from attributes / custom `doFetch()` args. | `@excom/fetchable-element` |
| `has-body` | option | `boolean` |  |  | Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`. | `@excom/fetchable-element` |
| `api-url` | option | `string` | `""` |  | Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead. | `@excom/fetchable-element` |
| `api-method` | option | `string` | `"GET"` |  | HTTP method. Always uppercased before the request is sent. | `@excom/fetchable-element` |
| `header-accept` | option | `string` | `"application/json"` |  | `Accept` request header. | `@excom/fetchable-element` |
| `header-content-type` | option | `string` | `"application/json"` |  | `Content-Type` request header. Dropped entirely when the request has no body. | `@excom/fetchable-element` |
| `header-cache-control` | option | `string` |  |  | `Cache-Control` request header. Unset by default (browser default caching applies). | `@excom/fetchable-element` |
| `fetch-redirect` | option | `string` |  | `"follow"` \| `"error"` \| `"manual"` | `RequestInit.redirect` mode. Unset defers to the browser default (`follow`). | `@excom/fetchable-element` |
| `fetch-credentials` | option | `string` | `"include"` | `"omit"` \| `"same-origin"` \| `"include"` | `RequestInit.credentials` mode. | `@excom/fetchable-element` |
| `is-loading` | state | `boolean` |  |  | A request is currently in flight. | `@excom/fetchable-element` |
| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. Mutually exclusive with `is-loading` and `is-error`. | `@excom/fetchable-element` |
| `is-error` | state | `boolean` |  |  | The most recent request failed (status 400 or above, network error, or a thrown error other than `AbortError`). Fires with the `error` event. | `@excom/fetchable-element` |

#### Provision

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `provision` | `FetchResponse` (`{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }`) | Response payload on success, or error payload on failure. Success shape: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute. | `@excom/fetchable-element` |

#### Fires

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `provider-fetch-submit` | `ProviderFetchSubmitEvent` (`CustomEvent & { type: "provider-fetch-submit"; detail: [url: string, requestInit: RequestInit]; bubbles: true; cancelable: true; composed: true }`) | Internal — dispatched whenever a fetch is about to run (auto-fetch or `--fetch`). Built by `getFetchArgs()`. Cancelable; default action calls `doFetch()`. |  |
| `provider-fetch-loading` | `FetchableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched immediately before the request is sent. | `@excom/fetchable-element` |
| `provider-fetch-success` | `FetchableSuccessEvent` (`CustomEvent & { type: "{tag}-success"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request resolves successfully. `event.detail` is the parsed response (see `provision`). | `@excom/fetchable-element` |
| `provider-fetch-error` | `FetchableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; } \| { message: string; stack?: string }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails — status 400 or above, network error, or a thrown error. `event.detail` is the error payload (see `provision`). Not dispatched for aborted requests. | `@excom/fetchable-element` |

#### Commands

| Command | Action |
| --- | --- |
| `--fetch` | Re-runs the request with the current attributes, even while `is-paused`. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `provider-fetch-submit` | Calls `doFetch(url, requestInit)` with the event's detail. |



### Examples

#### Comprehensive

This example shows loading state, error state, rendering, and refetching.


```html
<section>
  <provider-fetch id="demo-refetch-provider" api-url="/api/todos/1" class="tag-article grid">
    <ul></ul>
    <ul></ul>
    <template id="demo-refetch-item">
      <li class="tag-code"></li>
    </template>
  </provider-fetch>
  <button type="button" command="--fetch" commandfor="demo-refetch-provider">Refetch</button>
  <style>
    #demo-provider-fetch-refetch { max-width: none; }
    #demo-provider-fetch-refetch provider-fetch {
      &[is-loading] {
        opacity: 0.5;
        border: 1px dashed yellow;
      }
      &[is-success] { border: 1px solid green; }
      &[is-error] {
        border: 1px solid red;
        &::before { content: "An error occurred."; }
      }
      ul:first-of-type::before { content: "Todo data:"; }
      ul:last-of-type::before { content: "Response data:"; }
      li { display: block; }
    }
  </style>
  <quark-sheet>
    provider-fetch[is-success] {
      $res: prop("provision");
      li { content: "#{index}: #{item}"; }
      ul:first-of-type { content: iterate($res.body, "#demo-refetch-item"); }
      ul:last-of-type { content: iterate($res, "#demo-refetch-item"); }
    }
  </quark-sheet>
</section>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# provider-geolocation

Declarative Geolocation API — request a position, read the result from
attributes/state.


```html
<div>
  <button type="button" command="--request" commandfor="geo-request">
    Request my location
  </button>
  <provider-geolocation id="geo-request" is-paused>
    <output>Click above — your browser will prompt for permission.</output>
  </provider-geolocation>
  <quark-sheet>
    provider-geolocation {
      $result: prop("provision");
      &[is-success] output { content: "#{$result.coords.latitude}, #{$result.coords.longitude}"; }
      &[is-error] output { content: $result.message; }
    }
  </quark-sheet>
</div>
```


## Features

- **Attribute-driven** Request + read a position through attributes
- **User-gesture requests** `is-paused` + the `--request` command
  so permission prompts follow a click
- **One-shot or watch** `watch-position` streams updates instead of a
  single read

## Installation


`@excom/provider-geolocation` v0.1.4

```bash
pnpm add @excom/provider-geolocation
```

```bash
npm install @excom/provider-geolocation
```

```bash
yarn add @excom/provider-geolocation
```

### Import

```ts
import "@excom/provider-geolocation";
```



## Usage

Requesting location on page load is poor UX (an unsolicited permission
prompt) — gate it behind a user gesture with `is-paused` and a trigger:

```html
<button type="button" command="--request" commandfor="geo">
  Share my location
</button>
<provider-geolocation id="geo" is-paused></provider-geolocation>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-paused` | option | `boolean` |  |  | Skip making a request on connect. `provider-geolocation-request` still works while paused. |
| `high-accuracy` | option | `boolean` |  |  | Request the most accurate position available (more battery / time cost). |
| `geo-timeout` | option | `number` | `"Infinity"` |  | Give up and fire `provider-geolocation-error` after this many ms. |
| `maximum-age` | option | `number` |  |  | Accept a cached position up to this many ms old instead of requesting a fresh one. Ignored when `watch-position` is set (always `0`, i.e. no caching). |
| `watch-position` | option | `boolean` |  |  | Keep requesting — `provider-geolocation-success` fires on every position update instead of once. Uses `navigator.geolocation.watchPosition` under the hood. |
| `is-requesting` | state | `boolean` |  |  | A position request is currently pending. |
| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. With `watch-position`, stays set across updates. |
| `is-error` | state | `boolean` |  |  | The most recent request failed. Fires with the `error` event. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `GeoSuccess` (`{ coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }`) | Latest result: the coords object on success, or the `GeolocationPositionError` (or thrown error) on failure. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `provider-geolocation-success` | `ProviderGeolocationSuccessEvent` (`CustomEvent & { type: "provider-geolocation-success"; detail: { coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on every successful position read (including each update while `watch-position` is set). |
| `provider-geolocation-error` | `ProviderGeolocationErrorEvent` (`CustomEvent & { type: "provider-geolocation-error"; detail: GeolocationPositionError; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails (permission denied, timeout, position unavailable, or a thrown error). |

#### Commands

| Command | Action |
| --- | --- |
| `--request` | (Re)requests the position on demand — the standard way to request from a button (`<button command="--request" commandfor="…">`) while `is-paused` is set, or to force a fresh read at any time. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `provider-geolocation-success` | Stores the result in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`). |
| `provider-geolocation-error` | Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`). |

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# provider-orientation

Declarative device orientation / compass — request a heading, read the
normalized bearing from attributes/state.

## Features

- **Attribute-driven** Request + read a compass heading through attributes
- **Normalized bearing** `0`–`360°` from magnetic north on both iOS and
  Android, one shape either way
- **Throttled updates** `compass-throttle-ms` caps update frequency
  (Android can fire 60-200 Hz)
- **iOS-aware** Works with the required user-gesture permission flow

## Installation


`@excom/provider-orientation` v0.1.4

```bash
pnpm add @excom/provider-orientation
```

```bash
npm install @excom/provider-orientation
```

```bash
yarn add @excom/provider-orientation
```

### Import

```ts
import "@excom/provider-orientation";
```



## Usage

**Requires a user gesture on iOS.** `DeviceOrientationEvent
.requestPermission()` must run synchronously inside a click handler or
Safari denies it — so set `is-paused` and invoke the `--request` command
from a button rather than relying on the connect-time auto-request (the
handler runs in a microtask of the click, inside its user activation):

```html
<button type="button" command="--request" commandfor="compass">
  Enable compass
</button>
<provider-orientation id="compass" is-paused></provider-orientation>
```

```css
compass-needle {
  transform: rotate(calc(var(--bearing, 0) * 1deg));
}
```

Android and desktop browsers with a sensor don't require permission and
will start listening as soon as the request fires; browsers with no
sensor at all simply never report a reading.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-paused` | option | `boolean` |  |  | Skip requesting on connect. On iOS this is effectively required (a connect-time request happens outside a user gesture and will be denied) — pair with `provider-orientation-request` from a click handler instead (see class docs). |
| `compass-throttle-ms` | option | `number` | `100` |  | Minimum ms between `provider-orientation-success` updates. Android can fire `deviceorientationabsolute` at 60-200 Hz; without throttling that floods listeners and CSS/Quark bindings. |
| `is-requesting` | state | `boolean` |  |  | iOS only: the permission request is pending (between `provider-orientation-request` and the user's response). |
| `is-success` | state | `boolean` |  |  | Listening for orientation updates (permission granted where required). Stays set across updates. |
| `is-error` | state | `boolean` |  |  | The permission request was denied, or listening failed to start. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `ProviderOrientationSuccess` (`{ bearing: number; alpha: number \| null; }`) | Latest reading: `{ bearing, alpha }` on success, or the error on failure. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `provider-orientation-success` | `ProviderOrientationSuccessEvent` (`CustomEvent & { type: "provider-orientation-success"; detail: { bearing: number; alpha: number \| null; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on every compass update (throttled by `compass-throttle-ms`). `bearing` is normalized 0-360°; `alpha` is the raw `DeviceOrientationEvent.alpha` where available. |
| `provider-orientation-error` | `ProviderOrientationErrorEvent` (`CustomEvent & { type: "provider-orientation-error"; detail: string \| Error; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the permission request is denied, or fails for any other reason. |

#### Commands

| Command | Action |
| --- | --- |
| `--request` | Requests permission (iOS) and starts listening for orientation updates. Invoke it from a button (`<button command="--request" commandfor="…">`) so the user activation is there. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `provider-orientation-success` | Stores `{ bearing, alpha }` in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`). |
| `provider-orientation-error` | Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`). |



### Examples

#### Request on click


```html
<div>
  <button type="button" command="--request" commandfor="orient">
    Enable compass
  </button>
  <provider-orientation id="orient" is-paused>
    <output></output>
  </provider-orientation>
  <p class="status">No reading yet — click above. Requires a device
    sensor (desktop browsers usually have none).</p>
  <quark-sheet>
    provider-orientation {
      $reading: prop("provision");
      &[is-success] output {
        content: if($reading.bearing != null: "Heading #{$reading.bearing.toFixed(0)}°"; else: "Listening — no reading yet.");
      }
      &[is-error] output { content: $reading.message or $reading; }
    }
  </quark-sheet>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# provider-storage

Read a JSON value out of `localStorage` / `sessionStorage` into `provision`,
declaratively — and keep it in sync across tabs. No app JS required to display
cached client state.

## Features

- **Declarative read** Point `key-name` at a storage key and read the result
- **Local or session** `store-name` picks `localStorage` (default) /
  `sessionStorage`
- **Live across tabs** A write from another tab re-reads and fires
  `provider-storage-changed`
- **Reactive to attributes** Changing `key-name` / `store-name` re-reads
  immediately
- **Tiny, read-only** Never writes

## Installation


`@excom/provider-storage` v0.1.4

```bash
pnpm add @excom/provider-storage
```

```bash
npm install @excom/provider-storage
```

```bash
yarn add @excom/provider-storage
```

### Import

```ts
import "@excom/provider-storage";
```



## Usage

```html
<provider-storage key-name="user-preferences"></provider-storage>
<provider-storage key-name="checkout-draft" store-name="session"></provider-storage>
```

**Read-only.** It reads on every `key-name` / `store-name` set/change and never
writes. Removing `key-name` clears `provision` and both states.

**Live across tabs, not within one.** Browsers fire `storage` only in *other*
tabs, so:

- A write from another tab (or a `clear()` there) re-reads and fires
  `provider-storage-changed` — no app code needed. `sessionStorage` is
  per-tab, so this only applies to `store-name="local"`.
- A write by your own app code (`localStorage.setItem(...)`) in the same tab
  won't appear until you re-trigger a read — re-set `key-name` (e.g. to `""`
  and back) after writing.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `key-name` | option | `string` |  | `<storage key>` | Storage key to read. Setting or changing it re-reads immediately (parsed as JSON; `null` if absent). Removing it clears `provision` and both states. |
| `store-name` | option | `string` | `"local"` | `local, session` | Which Web Storage area to read. `local` survives the tab / browser closing and syncs across tabs; `session` is per-tab and gone when the tab closes. Changing it re-reads `key-name` from the new store. |
| `is-success` | state | `boolean` |  |  | The last read (parse) succeeded — including a legitimately absent key (`provision` is `null`, not an error). |
| `is-error` | state | `boolean` |  |  | `JSON.parse` threw on the last read (the stored value isn't valid JSON). `provision` is `null`. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `object` | `JSON.parse(store.getItem(keyName))`, or `null` if the key is absent or the read failed. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `provider-storage-changed` | `ProviderStorageChangedEvent` (`CustomEvent & { type: "provider-storage-changed"; detail: { keyName: string; oldValue: unknown; newValue: unknown; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched after a `storage` event from another tab for this element's `store-name` + `key-name` (or a `clear()` of that store) has been re-read into `provision` — so `provision`, `is-success` / `is-error` are already updated when it fires. The read also publishes `neutron-provision`, as usual. |



### Examples

#### Seed & re-read

Since this element never writes, the demo below seeds a value from a button
(re-setting `key-name` afterward to force the same-tab re-read) so you can see
it work without opening devtools. Open this page in a second tab and click
there too — this tab updates on its own.


```html
<div>
  <provider-storage key-name="demo-provider-storage">
    <p>Seeded at: <output></output></p>
  </provider-storage>
  <button type="button">Seed localStorage &amp; re-read</button>
  <small role="note">Same-tab writes only show up after
    <code>key-name</code> is re-set; a write from another tab is picked up
    live.</small>
  <quark-sheet>
    @use "/demo-utils" as *;

    provider-storage {
      $stored: prop("provision");
      output { content: $stored.seededAt or "never"; }
    }
    button { @on click (handle: seedDemoStorage); }
  </quark-sheet>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# quark-sheet

Drop a Quark sheet next to your markup — bind, render, and react without a component runtime.


```html
<section>
  <quark-sheet>
    details[open] summary {
      content: "Panel Open";
    }
    details:not([open]) summary {
      content: "Panel Closed";
    }
  </quark-sheet>
  <details>
    <summary></summary>
    <p>This is the panel content.</p>
  </details>
</section>
```


## Features

- **Sibling scope** Sheet + targets share a parent — Quark watches that host
- **Global sheets** `is-global` runs top-level rules document-wide
- **Inline or remote** Paste Quark in the element, or load `src-url`
- **Lifecycle state** `is-loading` / `is-success` / `is-error` + matching events (from [loadable-element](/packages/loadable-element))
- **Reload** The `--reload` command drops the shared cache entry for `src-url` and fetches again
- **Auto (un)register** Connect registers; disconnect tears down cleanly

## Installation


`@excom/quark-sheet` v0.2.0

```bash
pnpm add @excom/quark-sheet
```

```bash
npm install @excom/quark-sheet
```

```bash
yarn add @excom/quark-sheet
```

### Import

```ts
import "@excom/quark-sheet";
```



## Usage

Place `<quark-sheet>` under the same parent as the elements it should orchestrate.
Inline Quark text is enough for most apps.

```html
<section>
  <quark-sheet>
    details[open] summary { content: "Panel Open"; }
    details:not([open]) summary { content: "Panel Closed"; }
  </quark-sheet>
  <details>
    <summary></summary>
    <p>This is the panel content.</p>
  </details>
</section>
```

By default the sheet is scoped to its parent. Add `is-global` to run
top-level rules in the root context (e.g. reading a provider above the
host); rules inside an explicit `@scope { }` block stay host-scoped either
way. Language details live in the [`quark`](/packages/quark) docs.

An inline sheet is HTML content: a browser reads `<` followed by a letter, `/`, `!` or `?` as markup, in a sheet comment or string too, and a `<title>` or `<textarea>` there takes the rest of the page as its text (the sheet fails with a parse error far from the cause). Keep such text out of an inline sheet, or load the sheet with `src-url`.

For [prerendering](/docs/prerendering), `@excom/quark-sheet/server` exports `settle`, the hook that holds a page until its sheets are quiet. `@excom/nucleus-kit/server` already has it.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `src-url` | option | `string` |  | `<URL>` | URL of a remote `.quark` / text sheet. When set, contents are fetched into the live sheet (replacing inline text). |  |
| `is-global` | option | `boolean` |  |  | Run top-level rules in the root context (the whole document) instead of implicitly wrapping the sheet in `@scope { }`. Rules nested inside an explicit `@scope { }` block remain scoped to the host either way. |  |
| `is-loading` | state | `boolean` |  |  | Fetch in progress. |  |
| `is-success` | state | `boolean` |  |  | Sheet parsed and registered on the host. |  |
| `is-error` | state | `boolean` |  |  | Fetch or Quark parse/register failed. |  |
| `quark-instance` | state | `Quark` |  |  | Live `Quark` instance while registered. |  |
| `did-load` | state | `boolean` |  |  | Work has succeeded and no failure followed. Stays set while a refresh loads, so content can stay on screen (stale-while-revalidate): gate it on `[did-load]` rather than `[is-success]`. Cleared on error. | `@excom/loadable-element` |

#### Provision

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `provision` | `unknown` | The result of the most recent work on success, or the error payload on failure. Shape is defined by the composing element. Not reflected as an attribute. | `@excom/loadable-element` |

#### Fires

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `quark-sheet-loading` | `QuarkSheetLoadingEvent` (`CustomEvent & { type: "quark-sheet-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After `is-loading` becomes true (fetch in flight). |  |
| `quark-sheet-success` | `QuarkSheetSuccessEvent` (`CustomEvent & { type: "quark-sheet-success"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After the sheet parses and registers successfully (`is-success`). |  |
| `quark-sheet-error` | `QuarkSheetErrorEvent` (`CustomEvent & { type: "quark-sheet-error"; detail: unknown; bubbles: true; cancelable: true; composed: true }`) | After parse / fetch failure (`is-error`). `event.detail` is the error. |  |
| `quark-sheet-loading` | `LoadableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After `is-loading` is set (work started). | `@excom/loadable-element` |
| `quark-sheet-success` | `LoadableSuccessEvent` | After `is-success` is set. `event.detail` is the new `provision`. | `@excom/loadable-element` |
| `quark-sheet-error` | `LoadableErrorEvent` | After `is-error` is set. `event.detail` is the error payload (also stored as `provision`). | `@excom/loadable-element` |

#### Commands

| Command | Action |
| --- | --- |
| `--reload` | Drops the shared text cache entry for `src-url` and fetches the sheet again (the cache is page-wide: every element loading the same URL shares it). No-op without `src-url`. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--quark-sheet` | element | `quark-sheet`, `.tag-quark-sheet` |  |



### Examples

#### Provider data

`prop("provision")` reads a `<provider-fetch>` provision on success and fills a title.


```html
<section>
  <provider-fetch api-url="/api/todos/1">
    <p>Title: <span bind-title></span></p>
  </provider-fetch>
  <quark-sheet>
    provider-fetch[is-success] {
      $todo: prop("provision").body;
      [bind-title] {
        content: $todo.title;
      }
    }
  </quark-sheet>
</section>
```

## Release notes

### 0.2.0 (2026-10-08)

- Add `@excom/quark-sheet/server`, which exports `settle`: the prerender hook that holds a page until its sheets are quiet, without the 1 s limit of `Quark.whenSettled()`

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# renderable-element

Composition base for Neutron elements that defer rendering a `<template>`
until the right moment. It owns the load + render lifecycle so subclasses
only decide *when* to flip `is-active`. Used by `<include-content>`,
`<spa-route>`, and any custom element you compose yourself.

The demos below use `<include-content>` (the simplest concrete subclass)
to exercise behavior that comes straight from this mixin.


```html
<p>Type into both inputs, then toggle them off and on. The right side
keeps its value because <code>persist-content</code> reuses the same
template node instead of cloning a fresh copy each render.</p>

<style>
  .persist-demo {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 12px;
  }
  .persist-demo include-content {
    display: block;
    border: 1px dashed currentColor;
    padding: 8px;
    margin-top: 4px;
  }
</style>

<div class="persist-demo">
  <div>
    <strong>Default (cloned each render):</strong>
    <label>
      <input type="checkbox" checked />
      Active
    </label>
    <include-content is-active>
      <template>
        <input type="text" placeholder="Type, then toggle off + on" />
      </template>
    </include-content>
  </div>

  <div>
    <strong><code>persist-content</code>:</strong>
    <label>
      <input type="checkbox" checked />
      Active
    </label>
    <include-content is-active persist-content>
      <template>
        <input type="text" placeholder="Type, then toggle off + on" />
      </template>
    </include-content>
  </div>

  <quark-sheet>
    label {
      @on change { + include-content { is-active: event.target.checked; } }
    }
  </quark-sheet>
</div>
```


## Features

- **Template resolution** via `template-ref` in-document selectors or remote URLs
- **Prefetch strategies** `lazy` (default), `eager`, or `idle`
- **Configurable render host** light DOM, shadow, author iframe, or any selector
- **Cancelable render / unrender** parents can wrap updates in view transitions
- **Persistable content** keep live subtree state across unrender / render cycles
- **Ready coordination** `ready-on` + `delaying-ready` for paint-synced reveals

## Installation


`@excom/renderable-element` v0.3.0

```bash
pnpm add @excom/renderable-element
```

```bash
npm install @excom/renderable-element
```

```bash
yarn add @excom/renderable-element
```

### Import

```ts
import { /* … */ } from "@excom/renderable-element";
```



## Usage

Compose `RenderableElement` into a Neutron class and toggle `isActive`
from whatever signal makes sense — a media query, a websocket message,
an experiment flag, etc. Everything else (template fetch, caching, host
resolution, lifecycle events) is inherited.

```ts
import { Neutron } from "@excom/neutron";
import { RenderableElement } from "@excom/renderable-element";

export const MediaGated = Neutron.compose([
  RenderableElement,
  Neutron({
    tag: "media-gated",
    props: {
      mediaQuery: String,
    },
  }),
])
  .onPropChanged("mediaQuery", (el, prev) => {
    prev.mediaQuery && el._mql?.removeEventListener("change", el._sync);
    if (!el.mediaQuery) return { isActive: false };
    el._mql = window.matchMedia(el.mediaQuery);
    el._sync = () => (el.isActive = el._mql.matches);
    el._mql.addEventListener("change", el._sync);
    el._sync();
  });

MediaGated.define();
```

```html
<media-gated media-query="(min-width: 900px)">
  <template>
    <wide-screen-only></wide-screen-only>
  </template>
</media-gated>
```

Event names are prefixed with the concrete tag (shown as `{tag}-…` in the
API). For `<include-content>` that means `include-content-render`, etc.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `template-ref` | option | `string` | `":scope > template"` | `<CSS Selector>` \| `<URL>` | Source `<template>` — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use `:scope` to relatively select elements: e.g. `main:has(:scope) > template` |
| `bypass-cache` | option | `boolean` |  |  | Skip the in-memory response cache (URL `template-ref` only). |
| `pre-fetch` | option | `string` | `"lazy"` | `""` \| `"eager"` \| `"idle"` \| `"lazy"` | When to fetch the template, independent of when it renders. `""` aliases `eager`. `idle` never runs in a prerender. |
| `persist-content` | option | `boolean` |  |  | Reuse the same live nodes across unrender / render (held on `_persistedTree`) so form values, scroll position, and subtree state survive toggles. |
| `host-ref` | option | `string` |  | `"shadow"` \| `"iframe"` \| `<CSS Selector>` | Where rendered children land. Unset = this element's light DOM. `shadow` attaches an open shadow root. `iframe` paints into a child `<iframe data-render-host>` body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector. |
| `ready-on` | option | `string` |  | `<Event Name>` | Event name that marks rendered children "ready". Until it fires, `delaying-ready` is set so CSS can hide the host for a coordinated paint / view transition. Prerendered content kept at hydration is ready at once, never hidden. |
| `is-active` | hybrid | `boolean` |  |  | Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc. |
| `is-loading` | state | `boolean` |  |  | Template fetch in flight. |
| `did-load` | state | `boolean` |  |  | Template resolved at least once. Stays set across `is-active` toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when `template-ref` changes or `--reload` forces a fresh resolve. |
| `is-error` | state | `boolean` |  |  | Latest template fetch rejected (excluding abort). Fires with the `error` event. |
| `delaying-ready` | state | `boolean` |  |  | Between `render` and the matching `ready-on` event (or a failed load). Hook with CSS for coordinated paints / view transitions. |

#### Recognized Elements

| Relationship | Selector | Required | Description |
| --- | --- | --- | --- |
| `template` | child | no | Optional immediate `<template>` child used when `template-ref` is the default `":scope > template"`. Not required when `template-ref` points at a selector or URL elsewhere. |
| `iframe[data-render-host]` | child | no | Required when `host-ref="iframe"`. Content paints into `iframe.contentDocument.body`. Provide your own iframe (e.g. with `srcdoc`); the element will not create one. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `{tag}-render` | `RenderableRenderEvent` (`CustomEvent & { type: "{tag}-render"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes active and is about to place template content into the host. `event.detail` is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding `ready-on` event fires (or immediately if `ready-on` is unset). The promise rejects if the template fails to load, `host-ref` resolves to no host (nor an author iframe still loading), or the element is torn down mid-flight (`startTeardown` while loading / `delaying-ready`). Call `preventDefault()` to defer rendering and invoke `event.detail()` later. |
| `{tag}-unrender` | `RenderableUnrenderEvent` (`CustomEvent & { type: "{tag}-unrender"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes inactive and content is already painted. `event.detail` is a thunk that removes the rendered children. Call `preventDefault()` to defer the removal. Not fired when teardown cancels an in-flight load — that path emits `aborted` instead. |
| `{tag}-did-render` | `RenderableDidRenderEvent` (`CustomEvent & { type: "{tag}-did-render"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after the template content has actually been placed into the host. |
| `{tag}-did-unrender` | `RenderableDidUnrenderEvent` (`CustomEvent & { type: "{tag}-did-unrender"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after rendered children have been removed from the host. |
| `{tag}-error` | `RenderableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the template promise rejects with anything other than an `AbortError`. |
| `{tag}-aborted` | `RenderableAbortedEvent` (`CustomEvent & { type: "{tag}-aborted"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when an in-flight load / ready wait is canceled because `is-active` was unset (via `startTeardown`). |

#### Commands

| Command | Action |
| --- | --- |
| `--reload` | Stops waiting for any in-flight load and re-resolves the template, bypassing the cache for URL refs (useful after remote content changes). A URL request is shared by the page, so the one in flight is not cancelled. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `{tag}-render` | Invokes `event.detail()` to load (if needed) and render the template into the host. |
| `{tag}-unrender` | Invokes `event.detail()` to remove rendered children from the host. |



### Examples

#### Choosing a render host

Unset `host-ref` renders into the element's light DOM. `"shadow"` attaches
an open shadow root for style isolation:


```html
<p>Two <code>&lt;include-content&gt;</code> elements rendering the same template into different hosts. The shadow-root version is style-isolated.</p>

<style>
  .host-demo include-content {
    display: block;
    border: 1px dashed currentColor;
    padding: 8px;
    margin: 8px 0;
  }
  /* this rule cannot reach into a shadow root */
  .host-demo h4 { color: rebeccapurple; }
</style>

<div class="host-demo">
  <strong>Light DOM (default):</strong>
  <include-content is-active>
    <template>
      <h4>I'm rebeccapurple</h4>
      <p>Light-DOM children inherit the host page's CSS.</p>
    </template>
  </include-content>

  <strong>Shadow DOM (<code>host-ref="shadow"</code>):</strong>
  <include-content is-active host-ref="shadow">
    <template>
      <style>h4 { color: tomato; }</style>
      <h4>I'm tomato — outer styles can't touch me</h4>
      <p>Encapsulated inside an attached shadow root.</p>
    </template>
  </include-content>
</div>
```


`"iframe"` paints into a child `<iframe data-render-host>` you provide —
sandbox styles / scripts / document context. Only nodes move: custom
elements upgrade there only if the iframe document loads their definitions:


```html
<include-content is-active host-ref="iframe">
  <template>
    <style>
      body { font-family: system-ui; padding: 12px; color: #333; }
      h4 { color: navy; margin: 0 0 4px; }
    </style>
    <h4>Hello from inside the iframe</h4>
    <p>Rendered into <code>iframe.contentDocument.body</code>.</p>
  </template>
  <iframe data-render-host
    srcdoc="<!doctype html><html><body></body></html>"></iframe>
  <style>
    #demo-renderable-element-host-iframe > :first-child {
      display: block;
      border: 1px dashed currentColor;
      padding: 8px;

      > iframe {
        width: 100%;
        height: 140px;
        border: none;
        background: white;
      }
    }
  </style>
</include-content>
```


Any other value is a CSS selector — the template lands in whatever
element it resolves to:


```html
<p>Any other <code>host-ref</code> value is treated as a CSS selector. The element renders its template into whatever the selector resolves to.</p>

<style>
  .selector-demo {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 12px;
  }
  .selector-demo .mount-point {
    border: 1px dashed currentColor;
    padding: 8px;
    min-height: 80px;
  }
</style>

<div class="selector-demo">
  <div>
    <strong>Source element:</strong>
    <include-content is-active host-ref=".sidebar-mount">
      <template>
        <p>I render into <code>.sidebar-mount</code> →</p>
      </template>
    </include-content>
  </div>
  <div>
    <strong>Mount target:</strong>
    <div class="mount-point sidebar-mount"></div>
  </div>
</div>
```


On a [prerendered page](/docs/prerendering) the light DOM and a selector host keep their prerendered content; `shadow` and `iframe` hosts are not prerendered and render in the browser.

#### Hooking render with view transitions

`render` and `unrender` are cancelable; `event.detail` is the update
thunk. A parent can `preventDefault()` and run the mutation inside
`document.startViewTransition()` — the same pattern `<spa-manager>`
uses to batch sibling routes.


```html
<p>Toggle the checkbox to activate the element. The cancelable
<code>include-content-render</code> event is intercepted, the actual
DOM mutation is wrapped in <code>document.startViewTransition()</code>,
and a parent listener can defer or skip the render entirely.</p>

<style>
  .render-event-demo {
    border: 1px solid var(--border, #444);
    padding: 12px;
    border-radius: 4px;
  }
  .render-event-demo include-content {
    display: block;
    margin-top: 8px;
    padding: 8px;
    border: 1px dashed currentColor;
  }
  .render-event-demo include-content > article {
    background: rgba(255, 200, 80, 0.15);
    padding: 12px;
    view-transition-name: render-demo-card;
  }
  ::view-transition-old(render-demo-card),
  ::view-transition-new(render-demo-card) {
    animation-duration: 350ms;
  }
</style>

<div class="render-event-demo">
  <label>
    <input type="checkbox" />
    Active
  </label>

  <include-content>
    <template>
      <article>
        <h4>Just rendered (with a view transition)</h4>
        <p>The host swallowed the default render and ran it through <code>startViewTransition</code>.</p>
      </article>
    </template>
  </include-content>

  <quark-sheet>
    @use "/demo-utils" as *;

    label {
      @on change { + include-content { is-active: event.target.checked; } }
    }
    include-content {
      @on include-content-render, include-content-unrender (handle: renderInTransition);
    }
  </quark-sheet>
</div>
```


The thunk's returned Promise resolves when the view is ready (immediately, or when `ready-on` fires). If `is-active` is unset while still loading / `delaying-ready`, teardown rejects that Promise and emits `aborted` instead of `unrender`.

Pair with `ready-on` so `delaying-ready` stays set until your transition
has committed:

```html
<media-gated ready-on="my-app-paint" media-query="(min-width: 900px)">
  <template>...</template>
</media-gated>
```

```css
media-gated[delaying-ready] {
  display: none;
}
```

#### Persisting content across cycles

Once a template resolves, `did-load` stays set so consumers know later
toggles are warm — URL `template-ref`s reuse the shared fetch cache in
kit-utils. Without `persist-content` (the default), each activation
re-resolves and imports a fresh clone — subtree state is lost on
unrender. With it, the same live nodes are held across toggles:


```html
<p>Type into both inputs, then toggle them off and on. The right side
keeps its value because <code>persist-content</code> reuses the same
template node instead of cloning a fresh copy each render.</p>

<style>
  .persist-demo {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 12px;
  }
  .persist-demo include-content {
    display: block;
    border: 1px dashed currentColor;
    padding: 8px;
    margin-top: 4px;
  }
</style>

<div class="persist-demo">
  <div>
    <strong>Default (cloned each render):</strong>
    <label>
      <input type="checkbox" checked />
      Active
    </label>
    <include-content is-active>
      <template>
        <input type="text" placeholder="Type, then toggle off + on" />
      </template>
    </include-content>
  </div>

  <div>
    <strong><code>persist-content</code>:</strong>
    <label>
      <input type="checkbox" checked />
      Active
    </label>
    <include-content is-active persist-content>
      <template>
        <input type="text" placeholder="Type, then toggle off + on" />
      </template>
    </include-content>
  </div>

  <quark-sheet>
    label {
      @on change { + include-content { is-active: event.target.checked; } }
    }
  </quark-sheet>
</div>
```


On a prerendered page the nodes it holds are the prerendered ones.

#### Loading strategies

`pre-fetch` controls *when* the template is fetched, separately from
when it is rendered:

```html
<!-- default: fetch on first activation -->
<my-el></my-el>

<!-- pre-warm immediately on attribute set -->
<my-el pre-fetch="eager"></my-el>

<!-- backfill on idle -->
<my-el pre-fetch="idle" template-ref="/fragments/hero.html"></my-el>
```

Pair with `bypass-cache` for revalidation when the element activates
multiple times. Invoke the `--reload` command to force a refresh.

`pre-fetch="idle"` never runs in a prerender: the template is fetched in the browser.

## Release notes

### 0.3.0 (2026-10-07)

- Add hydration of prerendered content: an element whose host already holds the server's render of the same template does not render again, fires `did-render` once and is ready at once (never `delaying-ready`); `persist-content` keeps those nodes across toggles and `pre-fetch="idle"` does not run during a prerender
- Fix an issue where a first mount into a `host-ref` selector cleared the host and fired `did-unrender`: what the host holds now stays until the first render replaces it

### 0.2.0 (2026-09-30)

- Update a URL `template-ref` that answers with an error status to set `is-error` and fire the error event, paint nothing and log one error with the status as its cause; the error page is no longer rendered as content
- Fix an issue where a failed template load held `ready` until `render-timeout`: the promise from `render` rejects at once and `delaying-ready` clears
- Fix an issue where the promise from `render` never settled and `delaying-ready` stayed set when `host-ref` resolved to no host: the promise now rejects at once and `delaying-ready` clears, while an author iframe still loading keeps waiting

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# routable-element

URL matching for custom elements — give any Neutron class a
`route-href` and react when the address bar changes.

## Features

- **Path patterns** Named params (`/users/:id`) and wildcards
- **Regex routes** Full control via `route-regex` (ignored when `route-href` is set); named groups (`(?<id>\d+)`) become `params`, in a path pattern too, unnamed ones stay in `match`
- **Nested match** Keep layouts active under child paths
- **Live updates** Rematch when `route-href` / `route-regex` change

## Installation


`@excom/routable-element` v0.2.2

```bash
pnpm add @excom/routable-element
```

```bash
npm install @excom/routable-element
```

```bash
yarn add @excom/routable-element
```

### Import

```ts
import { /* … */ } from "@excom/routable-element";
```



## Usage

Compose `RoutableElement` and implement `routeChanged`. Concrete
consumers include `<spa-route>`, `<spa-a>`, and `<spa-manager>`.

```ts
import { Neutron } from "@excom/neutron";
import { RoutableElement } from "@excom/routable-element";

export const PathAware = Neutron.compose([
  RoutableElement,
  Neutron({
    tag: "path-aware",
    props: {
      isActive: Boolean,
    },
  }),
])
  .defineMethods({
    routeChanged: (_el, { match }) => ({ isActive: !!match }),
  });

PathAware.define();
```

```html
<path-aware route-href="/dashboard" match-nested></path-aware>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards: `*rest` matches one path segment, a bare `*` across segments. A relative pattern (`checkout`) resolves against the page's `<base>`; without one, against the page URL at registration. Set this or `route-regex`; with both, this one wins. |
| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the pathname (never the query or hash) — alternative to `route-href` for catch-alls / advanced patterns, ignored when `route-href` is set. Here and in a `route-href`, named groups become `params` (`(?<id>\d+)` → `params.id`); unnamed groups stay in `match`. |
| `match-nested` | option | `boolean` |  |  | Also match child paths of `route-href`: `/users` matches `/users` and `/users/42`, never `/usersx`. Essential for layout routes and nested SPAs. |



### Examples

#### Path match & nested layouts

`route-href` activates on exact match; with `match-nested` it also matches child paths, keeping a layout mounted.

```html
<spa-route route-href="/users" match-nested>
  <template>…layout…</template>
</spa-route>
```

#### Catch-all via regex

```html
<spa-route route-regex=".*" is-fallback>
  <template>404</template>
</spa-route>
```

## Release notes

### 0.2.0 (2026-09-30)

- Update `match-nested` to match its own path as well as child paths: `route-href="/users"` is active at `/users`, so a separate route for that path renders beside it and a 404 fallback stays off there
- Add relative `route-href` values: `checkout` resolves against the page's `<base>`, or against the page URL at registration when there is none
- Fix an issue where a routable element inside `persist-content` threw a `NeutronError` when re-attached
- Fix an issue where an element given a `route-href` while detached registered a route, and a `route-regex` element stayed registered after it was removed
- Fix an issue where changing `match-nested` at runtime had no effect

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# scroll-into-view

Scrolls an element into view — on connect by default, or on click / any event via the inherited `listen-for`.


```html
<div>
  <div class="scroll-area">
    <p>Keep scrolling…</p>
    <p>Keep scrolling…</p>
    <p>Keep scrolling…</p>
    <scroll-into-view>
      <p role="note">👋 Scrolled into view on connect — no attributes needed.</p>
    </scroll-into-view>
    <p>More content below.</p>
    <p>More content below.</p>
  </div>
</div>
```


## Features

- **Scroll on connect** Works with no attributes needed
- **Any trigger** Combine with `listen-for` to scroll on click, custom events, or lifecycles
- **Alignment control** `scroll-align` picks start / center / end / nearest per axis
- **Offset for fixed headers** `scroll-offset` nudges the final position after alignment
- **Skip redundant scrolls** `if-needed` scrolls only when the target isn't already visible

## Installation


`@excom/scroll-into-view` v0.1.4

```bash
pnpm add @excom/scroll-into-view
```

```bash
npm install @excom/scroll-into-view
```

```bash
yarn add @excom/scroll-into-view
```

### Import

```ts
import "@excom/scroll-into-view";
```



## Usage

By default, `<scroll-into-view>` scrolls *itself* into view as soon as it connects to the DOM. Set `target-ref` to scroll a different element instead, and pair with the inherited `listen-for` to trigger on click or any event rather than on connect.

```html
<!-- Jump to a section on click -->
<scroll-into-view target-ref="#pricing" listen-for="click">
  See pricing
</scroll-into-view>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `target-ref` | option | `string` |  | `<CSS Selector>` | CSS selector of the element to scroll to. Unset scrolls this element itself. |  |
| `scroll-align` | option | `tokenlist` | `"nearest start"` | `"start"` \| `"center"` \| `"end"` \| `"nearest"` \| `"none"` | Two tokens `<inline> <block>` (x and y, respectively) controlling how the target aligns inside the scrollport. Each token is `start`, `center`, `end`, `nearest`, or `none` (skip alignment on that axis). |  |
| `scroll-offset` | option | `tokenlist` | `"0 0"` | `<px> <px>` | Two pixel offsets `<x> <y>` applied after alignment — e.g. leave room for a sticky header by using a negative `<y>`. |  |
| `scroll-behavior` | option | `string` | `"auto"` | `"auto"` \| `"smooth"` \| `"instant"` | Scroll animation. |  |
| `if-needed` | option | `boolean` |  |  | Only scroll if the target isn't already fully visible. |  |
| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`/`cmd`. Name the space bar `space` / `spacebar` and the plus key `plus` (`shift+space`). Case-insensitive. | `@excom/listenable-element` |
| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--scroll-into-view` | element | `scroll-into-view`, `.tag-scroll-into-view` | Apply `<scroll-into-view>` host styles (positioning + the inherited pointer cursor when clickable) to any element, without registering the custom element — e.g. server-rendered markup. |



### Examples

#### Offset for a sticky header

`scroll-offset="0 -50"` (negative `<y>`) leaves room for a sticky header after alignment; `scroll-behavior="smooth"` animates the scroll. This is the pattern used to jump between sections without the header covering the target's heading.


```html
<div>
  <scroll-into-view role="button" target-ref="#section-3" listen-for="click"
    scroll-offset="0 -50" scroll-behavior="smooth">
    Jump to Section 3
  </scroll-into-view>
  <div class="scroll-area">
    <header>Sticky header</header>
    <section id="section-1">
      <h4>Section 1</h4>
      <p>The target section is further down.</p>
    </section>
    <section id="section-2">
      <h4>Section 2</h4>
      <p>Keep scrolling…</p>
    </section>
    <section id="section-3">
      <h4>Section 3</h4>
      <p>The sticky header would normally cover this —
        <code>scroll-offset="0 -50"</code> leaves room for it.</p>
    </section>
  </div>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# service-worker

Observes `navigator.serviceWorker` and optionally relays its events — zero app JS required.


```html
<div>
  <service-worker></service-worker>
</div>
```


## Features

- **Observation only** Reports on an existing Service Worker; never registers one
- **Support detection** `is-supported` reflects API availability
- **Ready state** `is-ready` reflects once an active worker controls the page
- **Event relay** `relay-events` forwards `message` / `messageerror` / `controllerchange` as plain DOM events
- **Bindable state** `.provision` is `{ isSupported, isReady, hasController, scope }` — kept current on connect, `ready`, and every `controllerchange`; read it from Quark with `prop("provision")`

## Installation


`@excom/service-worker` v0.1.4

```bash
pnpm add @excom/service-worker
```

```bash
npm install @excom/service-worker
```

```bash
yarn add @excom/service-worker
```

### Import

```ts
import "@excom/service-worker";
```



## Usage

This element only *observes* an already-registered Service Worker — it does not call `navigator.serviceWorker.register(...)` itself. Register your Service Worker separately (in app code, or your build tool), then drop this element anywhere to expose its state as attributes and, optionally, relay its events.

```html
<service-worker relay-events></service-worker>
<event-handler listen-for="message" fire-event="sw-message-received">
  ...
</event-handler>
```

Relayed events (`message`, `messageerror`, `controllerchange`) are dispatched with their original names — they are **not** prefixed with `service-worker-`.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `relay-events` | option | `tokenlist` |  | `"message"` \| `"messageerror"` \| `"controllerchange"` | Space-separated `navigator.serviceWorker` events to relay onto this element. Bare attribute (no value) relays all three. Event names are relayed as-is — not prefixed with the tag. |
| `is-ready` | state | `boolean` |  |  | `navigator.serviceWorker.ready` has resolved — an active worker is controlling the page. |
| `is-supported` | state | `boolean` |  |  | The Service Worker API is available (`'serviceWorker' in navigator`). |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `ServiceWorkerProvision` (`{ isSupported: boolean; isReady: boolean; hasController: boolean; scope: string \| null; }`) | `{ isSupported, isReady, hasController, scope }` — set on connect, when `ready` resolves (`scope` comes from the registration), and on every `controllerchange`. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `message` | `ServiceWorkerMessageEvent` (`CustomEvent & { type: "message"; detail: unknown; bubbles: true; cancelable: true; composed: true }`) | Relayed verbatim from `navigator.serviceWorker`'s `message` event when `message` is included in `relay-events`. Not tag-prefixed. `event.detail` is `event.data` from the original message. |
| `messageerror` | `ServiceWorkerMessageErrorEvent` (`CustomEvent & { type: "messageerror"; detail: unknown; bubbles: true; cancelable: true; composed: true }`) | Relayed verbatim from `navigator.serviceWorker`'s `messageerror` event when `messageerror` is included in `relay-events`. Not tag-prefixed. |
| `controllerchange` | `ServiceWorkerControllerChangeEvent` (`CustomEvent & { type: "controllerchange"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Relayed verbatim from `navigator.serviceWorker`'s `controllerchange` event when `controllerchange` is included in `relay-events`. Not tag-prefixed. |



### Examples

#### Support / mount / ready state

`is-supported`, `is-mounted` (reflected by default), and `is-ready` are all plain attributes — style or branch on them with CSS. `is-ready` needs an app-registered Service Worker to ever resolve, so it will likely stay unset in this docs site.


```html
<div>
  <service-worker></service-worker>
</div>
```


#### Relay messages from your Service Worker

Relaying `message` / `messageerror` / `controllerchange` requires a Service Worker that your app has already registered and that is actively posting messages — this is not runnable in this docs site, but works like so once wired up:

```html
<service-worker relay-events="message"></service-worker>
<script>
  document
    .querySelector("service-worker")
    .addEventListener("message", (e) => console.log(e.detail));
</script>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<spa-a>`

> Declarative SPA link with active-state styling.

**Tag:** `<spa-a>`

## API

### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `route-action` | option | `string` | `"push"` | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Navigation mode when activated (default click). `back` / `forward` walk in-app history only: with none to walk, the link pushes its `route-href`; without one it logs an error and does nothing. |  |
| `document-title` | option | `string` |  |  | Sets `document.title` after navigation. |  |
| `transition-types` | option | `tokenlist` |  | `<token>…` | Space-separated View Transition types for this navigation (CSS View Transitions API). Useful for shared-element morphs like card expansion. |  |
| `match-hash` | option | `boolean` |  |  | Require the URL hash to match when setting `is-active`. |  |
| `is-active` | state | `boolean` |  |  | Current URL matches `route-href`. Style with `spa-a[is-active]`. |  |
| `was-active` | state | `boolean` |  |  | Previous URL matched `route-href`. Style outgoing links / card-expansion exits with `spa-a[was-active]`. |  |
| `host-ref` | option | `string` |  | `<CSS Selector>` \| `"window"` \| `"document"` \| `"html"` \| `"body"` \| `"head"` | Listen on another element / `window` / `document` — e.g. Escape to dismiss a dialog from a global `keydown`. Defaults to `:scope`. Used with `listen-for`. Not compatible with `listen-for-lifecycle`. The selector MUST resolve when `host-ref` is set — it will not wait for a match to appear. | `@excom/listenable-element` |
| `listen-for` | option | `tokenlist` |  | `<EventName>…` | Space-separated event names to listen for. Defaults to `click` when unset (and no lifecycle list is set). | `@excom/listenable-element` |
| `listen-for-lifecycle` | option | `tokenlist` |  | `"connected"` \| `"disconnected"` \| `"adopted"` | Space-separated element lifecycles to handle. | `@excom/listenable-element` |
| `listen-once` | option | `boolean` |  |  | Handle each distinct event name / lifecycle at most once. | `@excom/listenable-element` |
| `selector-filter` | option | `string` |  | `<CSS Selector>` | Only handle events whose `event.target` matches this CSS selector. Does not support `:scope` in the selector. | `@excom/listenable-element` |
| `keycode-filter` | option | `tokenlist` |  | `<key` \| `mod+key>…` | Space-separated key filters (OR). Join modifiers with `+` (AND, any order): `shift+k tab` → Shift+K or Tab. Modifiers: `shift`, `alt`, `ctrl`/`control`, `meta`/`cmd`. Name the space bar `space` / `spacebar` and the plus key `plus` (`shift+space`). Case-insensitive. | `@excom/listenable-element` |
| `pathname-filter` | option | `tokenlist` |  | `<pathname>…` | Only handle when `location.pathname` is one of these values — route-aware behaviors without a separate router element. | `@excom/listenable-element` |
| `prevent-default` | option | `boolean` |  |  | Call `preventDefault()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-propagation` | option | `boolean` |  |  | Call `stopPropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `stop-immediate-propagation` | option | `boolean` |  |  | Call `stopImmediatePropagation()` on matched events (ignored for lifecycles). | `@excom/listenable-element` |
| `vibrate-ms` | option | `number` | `"20 (when attribute is present with no value)"` |  | Vibrate on handle (`navigator.vibrate`). Empty / `0` uses a 20ms pulse. | `@excom/listenable-element` |
| `delay-ms` | option | `number` |  |  | Delay handling by this many milliseconds. | `@excom/listenable-element` |
| `is-debounced` | option | `boolean` |  |  | With `delay-ms`, coalesce bursts into one trailing call (debounce). | `@excom/listenable-element` |
| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards: `*rest` matches one path segment, a bare `*` across segments. A relative pattern (`checkout`) resolves against the page's `<base>`; without one, against the page URL at registration. Set this or `route-regex`; with both, this one wins. | `@excom/routable-element` |
| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the pathname (never the query or hash) — alternative to `route-href` for catch-alls / advanced patterns, ignored when `route-href` is set. Here and in a `route-href`, named groups become `params` (`(?<id>\d+)` → `params.id`); unnamed groups stay in `match`. | `@excom/routable-element` |
| `match-nested` | option | `boolean` |  |  | Also match child paths of `route-href`: `/users` matches `/users` and `/users/42`, never `/usersx`. Essential for layout routes and nested SPAs. | `@excom/routable-element` |

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--spa-a` | element | `spa-a`, `.tag-spa-a` |  |


---

# `<spa-manager>`

> SPA shell — view transitions, swipe nav, route orchestration.

**Tag:** `<spa-manager>`

## API

### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `transition-first-render` | option | `boolean` |  |  | Animate the very first activation (cold load) with a View Transition. Off by default so the initial paint is instant. |  |
| `transition-delay` | option | `number` |  |  | Delay (ms) before an update that animates (its View Transition) starts; an update that does not animate, and the first paint, never are. Gives late sibling render/unrender events time to queue, or room for last-second DOM work. Unset / `null` starts synchronously. |  |
| `no-transition` | option | `boolean` |  |  | Disable View Transitions for every child route. |  |
| `render-timeout` | option | `number` | `2000` |  | Max wait (ms) for child routes to be ready before the update (title, scroll, its View Transition) moves on; a warning is logged when it settles the update, and a route still waiting for its `ready-on` event is shown. Raise for slow remote templates. |  |
| `overscroll-behavior-x` | option | `string` |  | `"none"` \| `"navigate"` | Touch edge-swipe on touch devices. `none` blocks horizontal overscroll; `navigate` also calls back / forward past the threshold. |  |
| `overscroll-x-threshold` | option | `number` | `40` |  | Edge inset (px) where a touch start counts as an edge swipe. |  |
| `max-states` | option | `number` |  |  | Cap retained router history states (scroll positions, transition types, etc.). |  |
| `last-move` | state | `string` |  | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Last navigation direction (`push` / `replace` / `back` / `forward`). Pick CSS transition styles from this. |  |
| `active-url` | state | `string` |  |  | URL of the currently active route. |  |
| `is-transitioning` | state | `boolean` |  |  | A View Transition is in flight. |  |
| `has-rendered` | state | `boolean` |  |  | The first update with a render has settled (rendered, failed or hit `render-timeout`). Set in that update, inside its View Transition if one runs, before `spa-manager-rendered`: hide a loading shell / splash screen on it. Gates `transition-first-render`. Leave it in prerendered markup: the page then loads without a View Transition and keeps the browser's scroll (a reload's saved position is restored). |  |
| `default-title` | hybrid | `string` |  |  | `document.title` while no active route has a `document-title`. Unset, the page's own `<title>` is recorded here when a route first retitles the page, so a prerendered page keeps its shell title. |  |
| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards: `*rest` matches one path segment, a bare `*` across segments. A relative pattern (`checkout`) resolves against the page's `<base>`; without one, against the page URL at registration. Set this or `route-regex`; with both, this one wins. | `@excom/routable-element` |
| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the pathname (never the query or hash) — alternative to `route-href` for catch-alls / advanced patterns, ignored when `route-href` is set. Here and in a `route-href`, named groups become `params` (`(?<id>\d+)` → `params.id`); unnamed groups stay in `match`. | `@excom/routable-element` |
| `match-nested` | option | `boolean` |  |  | Also match child paths of `route-href`: `/users` matches `/users` and `/users/42`, never `/usersx`. Essential for layout routes and nested SPAs. | `@excom/routable-element` |

### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `KitRouteData` (`{ previous: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; active: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; }; next: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; all: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; }[]; params: Record<string, string> \| null; query: Record<string, string>; match: Array<any> \| null; move: null \| "push" \| "replace" \| "back" \| "forward"; event?: { hasUAVisualTransition: boolean; }; route: KitRoute; }`) | Current route payload. Not reflected as an attribute. |

### Recognized Elements

| Relationship | Selector | Required | Description |
| --- | --- | --- | --- |
| `spa-route` | descendant | yes | Routes this manager coordinates. Their render lifecycle is intercepted and batched into one view transition per navigation. |

### Fires

| Name | Type | Description |
| --- | --- | --- |
| `spa-manager-will-transition` | `SpaManagerWillTransitionEvent` (`CustomEvent & { type: "spa-manager-will-transition"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Outermost manager, once per update chain (the first paint included), before its update (and View Transition, if any) starts. `preventDefault()` holds the update until `updateRoutes(true)` is called (`updateRoutes()` runs it without a View Transition). |
| `spa-manager-transition` | `SpaManagerTransitionEvent` (`CustomEvent & { type: "spa-manager-transition"; detail: { transition: ViewTransition; }; bubbles: true; cancelable: true; composed: true }`) | Outermost manager, after `document.startViewTransition()` is called. |
| `spa-manager-rendered` | `SpaManagerRenderedEvent` (`CustomEvent & { type: "spa-manager-rendered"; detail: void; bubbles: true; cancelable: true; composed: true }`) | After the update (and its transition) finishes: routes settled, title and scroll applied. Nested managers whose routes took part fire it too, without bubbling. |
| `spa-manager-error` | `SpaManagerErrorEvent` (`CustomEvent & { type: "spa-manager-error"; detail: unknown; bubbles: true; cancelable: true; composed: true }`) | Re-emitted when a child fires `spa-route-error`. `event.detail` mirrors the source error. |
| `spa-manager-push` | `SpaManagerPushEvent` (`CustomEvent & { type: "spa-manager-push"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `pushState` navigations. |
| `spa-manager-replace` | `SpaManagerReplaceEvent` (`CustomEvent & { type: "spa-manager-replace"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `replaceState` navigations. |
| `spa-manager-back` | `SpaManagerBackEvent` (`CustomEvent & { type: "spa-manager-back"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `back` navigations. |
| `spa-manager-forward` | `SpaManagerForwardEvent` (`CustomEvent & { type: "spa-manager-forward"; detail: void; bubbles: true; cancelable: true; composed: true }`) | On `forward` navigations. |

### Listens for

| Name | Type | Description |
| --- | --- | --- |
| `spa-route-render` | `RenderableRenderEvent` (`CustomEvent & { type: "{tag}-render"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }`) | Queues the child's render callback for the next batched update. A nested manager lets it bubble on to the outermost one. |
| `spa-route-unrender` | `RenderableUnrenderEvent` (`CustomEvent & { type: "{tag}-unrender"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Queues the child's unrender callback (runs before renders so the outgoing route leaves first). |
| `spa-route-provision` | `SpaRouteProvisionEvent` (`CustomEvent & { type: "spa-route-provision"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Queues the child's route data update into the next batched update. |
| `spa-route-error` | `RenderableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Re-emits as `spa-manager-error`. |

### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `spa-manager-will-transition` | Starts the batched update, inside a View Transition unless the API is missing, reduced motion is on, the page is hidden, it is the first paint (without `transition-first-render`) or a prerendered page's first update, the browser already animated the navigation, the batch only provisions or routes opt out. |


---

# spa-route

Build a full SPA from HTML alone — screens, links, and view transitions.

> This site is a live demo... inspect its HTML! Other live demos of spa-route coming soon.

```html
<spa-manager>
  <spa-route route-href="/" template-ref="/views/home.html"></spa-route>
  <spa-route route-href="/about" template-ref="/views/about.html"></spa-route>
</spa-manager>

<nav>
  <spa-a route-href="/">Home</spa-a>
  <spa-a route-href="/about">About</spa-a>
</nav>
```

## Features

- **Pure CSS View Transitions** Write CSS, get beautiful animations between routes
- **Active / was-active** Style current and outgoing links & screens (nav chrome, card expansion)
- **Same-route reuse / refresh** Keep or rebuild the view when only params change
- **Scroll reset / restore** Per-axis control for push, replace, back, forward
- **Nested layouts** Keep a parent route mounted under child paths
- **404 fallbacks** Catch-alls that only fire when nothing else matched
- **Per-route document title** `document.title` follows the active route
- **History actions** Push, replace, back, forward from a link

## Installation


`@excom/spa-route` v0.5.0

```bash
pnpm add @excom/spa-route
```

```bash
npm install @excom/spa-route
```

```bash
yarn add @excom/spa-route
```

### Import

```ts
import "@excom/spa-route";
```



## Usage

Wrap screens in `<spa-manager>`, give each `<spa-route>` a `route-href`, and link with `<spa-a>`.

```html
<!-- Optional SPA manager for View Transitions and batched router config -->
<spa-manager>
  <!-- SPA routing -->
  <spa-route route-href="/" template-ref="/views/home.html"></spa-route>
  <spa-route route-href="/about" template-ref="/views/about.html"></spa-route>
</spa-manager>
<nav>
  <!-- SPA links -->
  <spa-a route-href="/">Home</spa-a>
  <spa-a route-href="/about">About</spa-a>
</nav>
```

Tests in Vitest on happy-dom import the router helpers from `@excom/spa-route/testing`: `resetRouter`, `navigate`, `popstate`, `installViewTransition`, `trackUnhandledRejections`.

For [prerendering](/docs/prerendering), `@excom/spa-route/server` exports the router's hooks: `beforeRender` starts each page from a cold load of its URL, `afterRender` fails a soft 404 (a page only the `is-fallback` route matches) and a not-found page that route does not render. Only the outermost routes decide: a nested layout's own fallback is part of an ordinary page. `@excom/nucleus-kit/server` already has both.

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `same-route` | option | `string` | `"reuse"` | `"reuse"` \| `"refresh"` | When this route matches while already active, `reuse` keeps the rendered tree and updates route data; `refresh` tears down and re-renders once params, the matched path or the query change. Use `refresh` for param-driven screens (e.g. `/users/:id` → `/users/2`); `reuse` when only route data should change (e.g. `/logs/:view`). Pair with `scroll-set-disabled` to leave the viewport untouched. |  |
| `no-transition` | option | `boolean` |  |  | This route's render / unrender never starts a `<spa-manager>` View Transition. It still takes part in one another route starts. |  |
| `scroll-reset-behavior` | option | `string` | `"instant"` | `"auto"` \| `"instant"` \| `"smooth"` | `window.scrollTo` behavior when `<spa-manager>` resets scroll for this route. Restores are instant. |  |
| `scroll-reset-x` | option | `tokenlist` | `"push replace"` | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Navigation moves that reset scroll X to `0` once a route renders (a query-only move keeps its place; a `#fragment` target wins). Moves omitted here restore the saved X for that history entry instead. |  |
| `scroll-reset-y` | option | `tokenlist` | `"push replace"` | `"push"` \| `"replace"` \| `"back"` \| `"forward"` | Navigation moves that reset scroll Y to `0` once a route renders (a query-only move keeps its place; a `#fragment` target wins). Moves omitted here restore the saved Y for that history entry instead. |  |
| `scroll-set-disabled` | option | `boolean` |  |  | While this route is active, `<spa-manager>` neither resets nor restores scroll. |  |
| `is-fallback` | option | `boolean` |  |  | Only activate when this route matches *and* no other `<spa-route>` in its closest `<spa-manager>` (nested routes included; without one, its document or shadow root) matches the current path. Other fallbacks, and routes that contain it or that it contains, never count. Place it last. Pair with a permissive `route-regex` (e.g. `.*`) for 404 catch-alls. |  |
| `document-title` | option | `string` |  |  | `document.title` while this route is active. The outermost `<spa-manager>` applies the last active route carrying one — so a nested route beats its ancestor — and restores its `default-title` (the page's own `<title>`) once no active route has one. Cold loads and back / forward retitle too: it keys off activation, not clicks. |  |
| `was-active` | state | `boolean` |  |  | Set briefly while navigating away. Style outgoing screens / card-expansion exits with `spa-route[was-active]`. |  |
| `template-ref` | option | `string` | `":scope > template"` | `<CSS Selector>` \| `<URL>` | Source `<template>` — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use `:scope` to relatively select elements: e.g. `main:has(:scope) > template` | `@excom/renderable-element` |
| `bypass-cache` | option | `boolean` |  |  | Skip the in-memory response cache (URL `template-ref` only). | `@excom/renderable-element` |
| `pre-fetch` | option | `string` | `"lazy"` | `""` \| `"eager"` \| `"idle"` \| `"lazy"` | When to fetch the template, independent of when it renders. `""` aliases `eager`. `idle` never runs in a prerender. | `@excom/renderable-element` |
| `persist-content` | option | `boolean` |  |  | Reuse the same live nodes across unrender / render (held on `_persistedTree`) so form values, scroll position, and subtree state survive toggles. | `@excom/renderable-element` |
| `host-ref` | option | `string` |  | `"shadow"` \| `"iframe"` \| `<CSS Selector>` | Where rendered children land. Unset = this element's light DOM. `shadow` attaches an open shadow root. `iframe` paints into a child `<iframe data-render-host>` body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector. | `@excom/renderable-element` |
| `ready-on` | option | `string` |  | `<Event Name>` | Event name that marks rendered children "ready". Until it fires, `delaying-ready` is set so CSS can hide the host for a coordinated paint / view transition. Prerendered content kept at hydration is ready at once, never hidden. | `@excom/renderable-element` |
| `is-active` | hybrid | `boolean` |  |  | Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc. | `@excom/renderable-element` |
| `is-loading` | state | `boolean` |  |  | Template fetch in flight. | `@excom/renderable-element` |
| `did-load` | state | `boolean` |  |  | Template resolved at least once. Stays set across `is-active` toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when `template-ref` changes or `--reload` forces a fresh resolve. | `@excom/renderable-element` |
| `is-error` | state | `boolean` |  |  | Latest template fetch rejected (excluding abort). Fires with the `error` event. | `@excom/renderable-element` |
| `delaying-ready` | state | `boolean` |  |  | Between `render` and the matching `ready-on` event (or a failed load). Hook with CSS for coordinated paints / view transitions. | `@excom/renderable-element` |
| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards: `*rest` matches one path segment, a bare `*` across segments. A relative pattern (`checkout`) resolves against the page's `<base>`; without one, against the page URL at registration. Set this or `route-regex`; with both, this one wins. | `@excom/routable-element` |
| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the pathname (never the query or hash) — alternative to `route-href` for catch-alls / advanced patterns, ignored when `route-href` is set. Here and in a `route-href`, named groups become `params` (`(?<id>\d+)` → `params.id`); unnamed groups stay in `match`. | `@excom/routable-element` |
| `match-nested` | option | `boolean` |  |  | Also match child paths of `route-href`: `/users` matches `/users` and `/users/42`, never `/usersx`. Essential for layout routes and nested SPAs. | `@excom/routable-element` |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `SpaRouteProvision` (`{ routeHref: string; matchNested: boolean; scrollResetY: string[]; scrollResetX: string[]; scrollResetBehavior: ScrollBehavior; noTransition: boolean; active: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; }; event: { hasUAVisualTransition: boolean; }; match: Array<any> \| null; move: null \| "push" \| "replace" \| "back" \| "forward"; next: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; previous: { id: string; url: string; title?: string; isInit?: boolean; scrollX?: number; scrollY?: number; ttypes?: string[]; } \| null; params: Record<string, string> \| null; query: Record<string, string>; }`) | Active route payload for this activation (`null` when inactive). Not reflected as an attribute. |

#### Recognized Elements

| Relationship | Selector | Required | Description | Inherited from |
| --- | --- | --- | --- | --- |
| `template` | child | yes | Screen content. Cloned (or reused with `persist-content`) on activation. |  |
| `iframe[data-render-host]` | child | no | Required when `host-ref="iframe"`. Content paints into `iframe.contentDocument.body`. Provide your own iframe (e.g. with `srcdoc`); the element will not create one. | `@excom/renderable-element` |

#### Fires

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `spa-route-provision` | `SpaRouteProvisionEvent` (`CustomEvent & { type: "spa-route-provision"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. On (de)activation, and whenever the path or query changes while active; a hash-only move does neither. `event.detail` is a thunk that updates route data. `<spa-manager>` batches this into its update like render/unrender. |  |
| `spa-route-render` | `RenderableRenderEvent` (`CustomEvent & { type: "{tag}-render"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes active and is about to place template content into the host. `event.detail` is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding `ready-on` event fires (or immediately if `ready-on` is unset). The promise rejects if the template fails to load, `host-ref` resolves to no host (nor an author iframe still loading), or the element is torn down mid-flight (`startTeardown` while loading / `delaying-ready`). Call `preventDefault()` to defer rendering and invoke `event.detail()` later. | `@excom/renderable-element` |
| `spa-route-unrender` | `RenderableUnrenderEvent` (`CustomEvent & { type: "{tag}-unrender"; detail: () => void; bubbles: true; cancelable: true; composed: true }`) | Cancelable. Dispatched when the element becomes inactive and content is already painted. `event.detail` is a thunk that removes the rendered children. Call `preventDefault()` to defer the removal. Not fired when teardown cancels an in-flight load — that path emits `aborted` instead. | `@excom/renderable-element` |
| `spa-route-did-render` | `RenderableDidRenderEvent` (`CustomEvent & { type: "{tag}-did-render"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after the template content has actually been placed into the host. | `@excom/renderable-element` |
| `spa-route-did-unrender` | `RenderableDidUnrenderEvent` (`CustomEvent & { type: "{tag}-did-unrender"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched after rendered children have been removed from the host. | `@excom/renderable-element` |
| `spa-route-error` | `RenderableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the template promise rejects with anything other than an `AbortError`. | `@excom/renderable-element` |
| `spa-route-aborted` | `RenderableAbortedEvent` (`CustomEvent & { type: "{tag}-aborted"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched when an in-flight load / ready wait is canceled because `is-active` was unset (via `startTeardown`). | `@excom/renderable-element` |

#### Commands

| Command | Action | Inherited from |
| --- | --- | --- |
| `--reload` | Stops waiting for any in-flight load and re-resolves the template, bypassing the cache for URL refs (useful after remote content changes). A URL request is shared by the page, so the one in flight is not cancelled. | `@excom/renderable-element` |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) | Inherited from |
| --- | --- | --- |
| `spa-route-provision` | Invokes `event.detail()` to apply the new provision. |  |
| `spa-route-render` | Invokes `event.detail()` to load (if needed) and render the template into the host. | `@excom/renderable-element` |
| `spa-route-unrender` | Invokes `event.detail()` to remove rendered children from the host. | `@excom/renderable-element` |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--spa-route` | element | `spa-route`, `.tag-spa-route` |  |



### Examples

#### Minimal SPA

Three routes, three links. Active links style via `spa-a[is-active]`.

```html
<spa-manager>
  <nav>
    <spa-a route-href="/home">Home</spa-a>
    <spa-a route-href="/users">Users</spa-a>
    <spa-a route-href="/about">About</spa-a>
    <spa-a route-href="/contact">Contact</spa-a>
  </nav>
  <spa-route route-href="/home">
    <template>
      <h3>Welcome</h3>
      <p>Mounted because the URL matched <code>/home</code>.</p>
    </template>
  </spa-route>
  <spa-route route-href="/users">
    <template>
      <h3>Users</h3>
      <ul>
        <li>Adam</li>
        <li>Linus</li>
        <li>Grace</li>
      </ul>
    </template>
  </spa-route>
  <spa-route route-href="/about" template-ref="/this/view/is/remote.html"></spa-route>
  <spa-route route-href="/contact" template-ref="#this-view-is-dom-selected"></spa-route>
</spa-manager>

<template id="this-view-is-dom-selected">foo@bar.com</template>
```

```css
spa-a[is-active] {
  font-weight: bold;
  pointer-events: none;
  text-decoration: none;
}
```

#### Nested layout & 404

`match-nested` keeps a layout mounted at its own path and under child paths. `is-fallback` with `route-regex=".*"` is a 404 that only activates when no other route inside its `<spa-manager>` matches the current path, nested routes included; place it last, since on a cold load it does not see siblings that mount after it.

```html
<spa-manager>
  <nav>
    <spa-a route-href="/users">Users list</spa-a>
    <spa-a route-href="/users/42">User 42</spa-a>
    <spa-a route-href="/missing">Missing page</spa-a>
  </nav>
  <spa-route route-href="/users" match-nested>
    <template>
      <section>
        <h3>Users layout</h3>
        <spa-manager>
          <spa-route route-href="/users">
            <template><p>List of users.</p></template>
          </spa-route>
          <spa-route route-href="/users/:id">
            <template><p>Detail for a single user.</p></template>
          </spa-route>
        </spa-manager>
      </section>
    </template>
  </spa-route>
  <spa-route route-regex="^/(?:admin|staff)(?:/|$)" template-ref="/views/admin-sidebar.html"></spa-route>
  <spa-route route-regex=".*" is-fallback>
    <template>
      <section>
        <h3>404</h3>
        <p>Catch-all — only when no other route matches.</p>
      </section>
    </template>
  </spa-route>
</spa-manager>
```

#### Document title

`document-title` sets `document.title` while its route is active. It keys off activation, not clicks, so cold loads and back / forward retitle too. The outermost `<spa-manager>` applies the last active route carrying one — a nested route beats its ancestor — and applies its `default-title` (unless authored, the page's own `<title>`, recorded when a route first retitles the page) once no active route has a title.

```html
<title>Nucleus · docs</title>

<spa-manager>
  <spa-route route-href="/" document-title="My company">
    <template><p>The company page.</p></template>
  </spa-route>
  <!-- untitled: the page's own <title> comes back -->
  <spa-route route-href="/docs">
    <template><p>The docs.</p></template>
  </spa-route>
</spa-manager>
```

#### History actions

`route-action="back"` / `"forward"` walk in-app history only: with none to walk, the link pushes its `route-href`, and without a `route-href` it logs an error and does nothing. `"replace"` swaps the current entry instead of pushing.

```html
<spa-manager>
  <nav>
    <spa-a route-action="back">‹ Back</spa-a>
    <spa-a route-action="forward">Forward ›</spa-a>
    <spa-a route-href="/one">Push /one</spa-a>
    <spa-a route-href="/two">Push /two</spa-a>
    <spa-a route-href="/login" route-action="replace">
      Replace with /login
    </spa-a>
  </nav>
  <spa-route route-href="/one">
    <template><p>You're on <code>/one</code>.</p></template>
  </spa-route>
  <spa-route route-href="/two">
    <template><p>You're on <code>/two</code>.</p></template>
  </spa-route>
  <spa-route route-href="/login">
    <template>
      <p>You're on <code>/login</code> — this entry replaced the
        previous one in history.</p>
    </template>
  </spa-route>
</spa-manager>
```

#### View Transitions

The outermost `<spa-manager>` wraps each navigation in one `document.startViewTransition()`; nested managers join it. None runs when the API is missing, with reduced motion, in a hidden page, on the first paint (unless `transition-first-render`) or a [prerendered page](/docs/prerendering)'s first update, or when the update only changes provisions. `document.title` follows every update all the same, and `spa-manager-rendered` fires once per update chain: a navigation that arrives during a running update joins or follows it and shares its event. Style with `::view-transition-*`; set per-link types via `transition-types` (e.g. card expansion); opt a route out with `no-transition`.

```css
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.25s;
}
```

#### View Transitions - Localized
If you had a list of cards, and clicking on one expanded it to the detail view (and vice versa, contracting), you would achieve it similarly to the code example below. This technique relies on styling the `<spa-a>` with its `[is-active]` (incoming view) and `[was-active]` (outgoing view).

```html
<spa-manager>
  <spa-route id="route-list" route-href="/list">
    <template>
      <spa-a route-href="/detail/123" transition-types="card-morph" class="mini-card">
        Go to detail
      </spa-a>
    </template>
  </spa-route>
  <spa-route id="route-detail" route-href="/detail/:id">
    <template>
      <article id="detail-card" class="card">
        <!-- other content here -->
      </article>
    </template>
  </spa-route>
</spa-manager>
```

```css
html:active-view-transition-type(card-morph) {
  #route-list spa-a[transition-types="card-morph"][was-active], /* outgoing list card (forward) */
  #route-list spa-a[transition-types="card-morph"][is-active], /* incoming list card (back) */
  #detail-card /* detail card (forward & back) */ {
    contain: layout;
    height: fit-content;
    view-transition-name: card-morph;
  }
}
::view-transition-old(card-morph),
::view-transition-new(card-morph) {
  mix-blend-mode: normal;
  height: 100%;
  width: 100%;
  will-change: opacity;
  animation-fill-mode: both;
}
::view-transition-old(card-morph) {
  animation-name: fade-out 1s ease;
}
::view-transition-new(card-morph) {
  animation-name: fade-in 1s ease;
}
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}
@keyframes fade-out {
  from { opacity: 1; }
  to { opacity: 0; }
}
```

#### Touch edge-swipe
On touch devices, horizontal drags from within `overscroll-x-threshold` of an edge trigger back / forward. Use `"none"` to block overscroll without navigating. Useful for preventing native swipes in Safari, which visually break SPAs.

```html
<spa-manager overscroll-behavior-x="navigate"></spa-manager>
```


#### Scroll reset / restore

The outermost `<spa-manager>` owns scroll: while it is connected the browser's own scroll restoration is off, and a `<spa-route>` without a `<spa-manager>` ancestor does not touch scroll. By default it:
- resets scroll to top-left on `push` / `replace`, only when a route rendered — a move that renders nothing (a param or query change on a `reuse` route) keeps its position, and a `#fragment` target wins over the reset
- restores the saved scroll position on `back` / `forward` / reload, and holds it for about 2 seconds against late content, or until the person scrolls, taps or types, or the app scrolls

The write lands once the routes are ready (capped by `render-timeout`), so `ready-on` remains the way to get late data into the restored view. An update settled by `render-timeout` logs one warning (`spa-manager: update settled by render-timeout (2000 ms); a route is still pending`), visible at log level 2 or higher, and shows a route still waiting for its `ready-on` event. On a prerendered page (`has-rendered` in its markup) a reload or back / forward restores its saved position as the manager mounts, unless the person has scrolled already, and a fresh visit keeps the browser's.

Override per axis with `scroll-reset-y` / `scroll-reset-x` — space-separated moves that should reset to `0` (omitted moves restore instead):

```html
<!-- also reset Y when the user hits back -->
<spa-route
  route-href="/article/:id"
  scroll-reset-y="push replace back"
></spa-route>
```

Animate a reset with `scroll-reset-behavior="smooth"`; restores are instant. Disable all scroll handling with `scroll-set-disabled`. With several active routes (a layout and its child), the last in document order decides the reset.

#### Same-route params

When the matched route stays the same but its path or query changes (e.g. `/users/1` → `/users/2`, `?page=1` → `?page=2`), the route provisions again; its provision carries `params` (path placeholders and named groups: `(?<id>\d+)` gives `params.id`, unnamed groups stay in `match`) and `query`:

- `same-route="reuse"` (default) — keep the rendered tree and update route data, without a View Transition
- `same-route="refresh"` — tear down and re-render the view when params or the query change

```html
<spa-route route-href="/users/:id" same-route="refresh">
  <template><!-- fresh tree per user id --></template>
</spa-route>

<spa-route
  route-href="/logs/:view"
  same-route="reuse"
  scroll-set-disabled
>
  <template><!-- preserve content + scroll across view tabs --></template>
</spa-route>
```

#### Transition delay

`transition-delay` on `<spa-manager>` waits N ms before starting the batched View Transition — useful when sibling routes need a beat to queue their render/unrender callbacks, or for last-second DOM work. An update that does not animate, and the first paint, start at once.

```html
<spa-manager transition-delay="50">
  <!-- routes -->
</spa-manager>
```

## Release notes

### 0.5.0 (2026-10-08)

- Add `@excom/spa-route/server`, the router's prerender hooks: `beforeRender` starts each page from a cold load of its URL, `afterRender` fails a soft 404 (a page only the `is-fallback` route matches) and a not-found page that route does not render

### 0.4.0 (2026-10-07)

- Add `default-title` to `<spa-manager>`: the title a route without `document-title` falls back to, recorded from the page's `<title>` when a route first retitles the page
- Add hydration of prerendered pages: the first update runs without a View Transition or `transition-delay`, a reload restores its saved scroll position as the manager mounts, and a page served for a URL another route matches drops its content and renders the matching route
- Fix an issue where `render-timeout` left a route hidden while it waited for its `ready-on` event: it now reveals the route
- Fix an issue where a `same-route="refresh"` route tore down on its first registration match

### 0.3.0 (2026-10-01)

- Add `@excom/spa-route/testing`, the router helpers for Vitest on happy-dom: `resetRouter()`, `navigate()`, `popstate()`, `installViewTransition()` and `trackUnhandledRejections()`
- Fix an issue where an `is-fallback` route stayed off after leaving a nested route for a URL no route matches: the fallback now checks which routes match the path instead of reading their `is-active` state, so its position among its siblings no longer matters while navigating, a page without a `spa-manager` gets a working fallback, a fallback inside a layout can activate on the layout's unmatched child paths, and other fallbacks never hold it off
- Add a warning when a `spa-manager` update settles by `render-timeout` while a route is still pending, so an empty first paint has a cause in the console at log level 2

Older releases: https://nucleus.excom.dev/packages/spa-route


---

# super-form

Submit AJAX requests with HTML forms. Pair it with Quark to render the response.


```html
<section>
  <super-form>
    <form action="/api/echo" method="post">
      <input type="text" name="name" placeholder="Your name" required>
      <button type="submit">Submit</button>
    </form>
    <h4></h4>
    <span></span>
  </super-form>
  <quark-sheet>
    super-form[is-success] {
      $res: prop("provision");
      h4 { content: "Echoed name: #{$res.body.json.name}"; }
    }
    super-form {
      $res: prop("provision");
      span { content: "HTTP status code: #{$res.status}"; }
    }
  </quark-sheet>
  <style>
    #demo-super-form-simple super-form[is-loading] {
      animation: pulse 1s linear infinite;
      pointer-events: none;
    }
    @keyframes pulse {
      0% { opacity: 0.2; }
      50% { opacity: 0.6; }
      100% { opacity: 0.2; }
    }
  </style>
</section>
```


## Features

- **Makes AJAX requests** JSON payload is built from each input's `name` and `type` attributes
- **Progressively enhanced** Doesn't replace the native `form`; it enhances it. Everything you know about `form` and `input` still applies.
- **Provides data** Use Quark to render the response
- **Submit command** `--submit` submits programmatically (`<button command="--submit" commandfor="…">`)
- **Highly configurable** Headers, credentials, redirect, etc

## Installation


`@excom/super-form` v0.1.7

```bash
pnpm add @excom/super-form
```

```bash
npm install @excom/super-form
```

```bash
yarn add @excom/super-form
```

### Import

```ts
import "@excom/super-form";
```



## Usage

Just wrap a regular form. Form fields become a JSON payload via their `name`: dot-separated names nest, and a trailing `[]` collects same-named fields into an array. `input[type]` determines the type conversion.

```html
<super-form>
  <form action="/api/signup" method="post">
    <input name="isAvailable" type="checkbox"> <!-- -> { isAvailable: true } -->
    <input name="address.city" value="Anytown"> <!-- -> { address: { city: "Anytown" } } -->
    <input name="tags[]" value="smart">
    <input name="tags[]" value="kind"> <!-- -> { tags: ["smart", "kind"] } -->
    <button type="submit">Sign up</button>
  </form>
</super-form>
```

Hook the lifecycle state with CSS:

```css
super-form[is-loading] { /* form currently submitting, show loading spinner */ }
super-form[is-error]::before { content: "An error occurred." }
```

`did-load` is set on the first success, kept through a resubmit (where `is-loading` replaces `is-success`) and cleared on an error: gate content on `[did-load]` to keep it on screen during a resubmit.

Or Quark:

```quark
super-form[is-success] {
  $res: prop("provision").body;
  span { content: $res.json.email; }
}
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `form-ref` | option | `string` | `":scope form"` | `<CSS Selector>` | CSS selector for the `<form>` to intercept. The form's `action` / `method` / `enctype` take priority over `api-url` / `api-method` below. Must be a descendant to be heard directly — point elsewhere and invoke the `--submit` command instead. |  |
| `has-body` | option | `boolean` |  |  | Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`. | `@excom/fetchable-element` |
| `api-url` | option | `string` | `""` |  | Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead. | `@excom/fetchable-element` |
| `api-method` | option | `string` | `"GET"` |  | HTTP method. Always uppercased before the request is sent. | `@excom/fetchable-element` |
| `header-accept` | option | `string` | `"application/json"` |  | `Accept` request header. | `@excom/fetchable-element` |
| `header-content-type` | option | `string` | `"application/json"` |  | `Content-Type` request header. Dropped entirely when the request has no body. | `@excom/fetchable-element` |
| `header-cache-control` | option | `string` |  |  | `Cache-Control` request header. Unset by default (browser default caching applies). | `@excom/fetchable-element` |
| `fetch-redirect` | option | `string` |  | `"follow"` \| `"error"` \| `"manual"` | `RequestInit.redirect` mode. Unset defers to the browser default (`follow`). | `@excom/fetchable-element` |
| `fetch-credentials` | option | `string` | `"include"` | `"omit"` \| `"same-origin"` \| `"include"` | `RequestInit.credentials` mode. | `@excom/fetchable-element` |
| `is-loading` | state | `boolean` |  |  | A request is currently in flight. | `@excom/fetchable-element` |
| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. Mutually exclusive with `is-loading` and `is-error`. | `@excom/fetchable-element` |
| `is-error` | state | `boolean` |  |  | The most recent request failed (status 400 or above, network error, or a thrown error other than `AbortError`). Fires with the `error` event. | `@excom/fetchable-element` |

#### Provision

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `provision` | `FetchResponse` (`{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }`) | Response payload on success, or error payload on failure. Success shape: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute. | `@excom/fetchable-element` |

#### Fires

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `super-form-submit` | `SuperFormSubmitEvent` (`CustomEvent & { type: "super-form-submit"; detail: [url: string, requestInit: RequestInit]; bubbles: true; cancelable: true; composed: true }`) | Internal — dispatched whenever a submit is about to run (real `submit` or the `--submit` command). Built by `getFetchArgs()`. Cancelable; default action calls `doFetch()`. |  |
| `super-form-loading` | `FetchableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched immediately before the request is sent. | `@excom/fetchable-element` |
| `super-form-success` | `FetchableSuccessEvent` (`CustomEvent & { type: "{tag}-success"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request resolves successfully. `event.detail` is the parsed response (see `provision`). | `@excom/fetchable-element` |
| `super-form-error` | `FetchableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; } \| { message: string; stack?: string }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails — status 400 or above, network error, or a thrown error. `event.detail` is the error payload (see `provision`). Not dispatched for aborted requests. | `@excom/fetchable-element` |

#### Listens for

| Name | Type | Description |
| --- | --- | --- |
| `submit` | `SuperFormNativeSubmitEvent` (`SubmitEvent & { type: "submit"; bubbles: true; cancelable: true; composed: false; }`) | The default action of the `<form>` matched by `form-ref` (or any descendant `<form>`); prevented, then converted into `super-form-submit`. |

#### Commands

| Command | Action |
| --- | --- |
| `--submit` | Submits programmatically (`<button command="--submit" commandfor="…">`) — the only option when `form-ref` points to a form that isn't a descendant, since this element can't hear its `submit` event directly. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `super-form-submit` | Calls `doFetch(url, requestInit)` with the event's detail. |



### Examples

#### Comprehensive

This example shows loading state, error state, rendering, and triggering from outside the form.


```html
<section>
  <super-form id="demo-super-form-external" class="tag-article grid">
    <form action="/api/echo" method="post">
      <label>
        Nickname
        <input type="text" name="nickname" placeholder="John" required>
      </label>
    </form>
    <ul></ul>
    <ul></ul>
    <template id="demo-super-form-item">
      <li class="tag-code"></li>
    </template>
  </super-form>
  <button type="button" command="--submit" commandfor="demo-super-form-external">
    Save (outside the form)
  </button>
  <quark-sheet>
    @use "quark:util" as *;

    super-form[is-success] {
      $res: prop("provision");
      li { content: "#{index}: #{to-json(item)}"; }
      ul:first-of-type { content: iterate($res.body.json, "#demo-super-form-item"); }
      ul:last-of-type { content: iterate($res, "#demo-super-form-item"); }
    }
  </quark-sheet>
  <style>
    #demo-super-form-external-trigger { max-width: none; }
    #demo-super-form-external-trigger super-form {
      width: 100%;
      &[is-loading] {
        opacity: 0.5;
        border: 1px dashed yellow;
      }
      &[is-success] { border: 1px solid green; }
      &[is-error] {
        border: 1px solid red;
        &::before { content: "An error occurred."; }
      }
      ul:first-of-type::before { content: "Submitted JSON:"; }
      ul:last-of-type::before { content: "Response data:"; }
      li { display: block; }
    }
  </style>
</section>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# `<super-img>`

**Tag:** `<super-img>`

## Installation

`@excom/super-img` v0.1.4

```bash
pnpm add @excom/super-img
```

```bash
npm install @excom/super-img
```

```bash
yarn add @excom/super-img
```

### Import

```ts
import "@excom/super-img";
```

## API

### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--super-img` | element | `super-img`, `.tag-super-img` |  |

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# super-input

A lightweight element that wraps and upgrades the native `<input>` element.


```html
<form>
  <super-input
    text-format="(xxx) xxx-xxxx"
    invalid-message="That doesn't look like a US phone number"
    auto-label
    class="raised"
  >
    <label>Phone number</label>
    <input required pattern="^\(\d{3}\)\s\d{3}-\d{4}" placeholder="(123) 456-7890" inputmode="numeric" />
  </super-input>
  <!-- Form and button exist purely for the demo -->
  <button type="submit">Submit</button>
</form>
```


## Features

- **Live text formatting** e.g. phone numbers, dates, SSNs
- **Custom, native validity messages** uses the browser's built-in validation UI to show your message
- **Auto-labeling** it stitches a sibling `<label>` to the `<input>` via `id`/`for`
- **Progressively enhanced** Does **not** replace the native input; it enhances it. Everything you know
about `<input>` still applies.
- **Range slider** ships with upgraded slider styling and functionality

## Installation


`@excom/super-input` v0.1.4

```bash
pnpm add @excom/super-input
```

```bash
npm install @excom/super-input
```

```bash
yarn add @excom/super-input
```

### Import

```ts
import "@excom/super-input";
```



## Usage

Wrap a native `<input>` and optionally a `<label>`. Nothing else is required. 

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `text-format` | option | `string` |  |  | Pattern defining visible formatting. Use `x` for any digit and any other character as a literal. Examples: `(xxx) xxx-xxxx`, `xx/xx/xxxx`, `xxx-xx-xxxx`. When set, the input value is live-formatted on every keystroke. |
| `invalid-message` | option | `string` |  |  | If set, this message is installed via `setCustomValidity()` when the native `invalid` event fires, and cleared on the next `keydown`. Makes built-in HTML validation surface a custom message. |
| `reflect-value` | option | `boolean` |  |  | When set, the current input value is mirrored to the `current-value` attribute so CSS and selectors can respond to it. Off by default because reflecting every keystroke is not free. |
| `current-value` | state | `string` |  |  | Mirrors the wrapped `<input>`'s value when `reflect-value` is set. Read-only from the app's point of view — writing it does not change the input. |
| `auto-label` | option | `boolean` |  |  | When set, generates or uses an existing `id` on the `<input>` and associates the `<label>`. |

#### Recognized Elements

| Relationship | Selector | Required | Description |
| --- | --- | --- | --- |
| `input` | descendant | yes | Required native `<input>` to enhance. |
| `label` | descendant | no | Optional native `<label>`. When `auto-label` is set, its `for` attribute is linked to the input's `id`. |

#### CSS Custom Properties

| Name | Syntax | Default | Description |
| --- | --- | --- | --- |
| `--super-input-color` | `<color>` | `var(--v-color, inherit)` | Foreground / label color. |
| `--super-input-bg` | `<color>` | `var(--v-form-element-background-color, transparent)` | Surface background behind the control (and raised-label mask). |
| `--super-input-border-color` | `<color>` | `var( --v-form-element-border-color, currentColor )` | Default border color for raised inputs. |
| `--super-input-focus-color` | `<color>` | `var( --v-form-element-focus-color, var(--super-input-border-color) )` | Focus ring / focus border color. |
| `--super-input-border-radius` | `<length>` | `var(--v-border-radius, 4px)` | Corner radius for raised inputs. |
| `--super-input-border-width` | `<length>` | `var(--v-border-width, 1px)` | Border width for raised inputs. |
| `--super-input-transition-duration` | `<time>` | `var(--v-transition-duration-fast, 0.15s)` | Duration for border / label transitions. |
| `--super-input-transition-ease` | `*` | `var(--v-transition-ease-out, ease-out)` | Easing for border / label transitions. |
| `--super-input-primary` | `<color>` | `var(--v-primary, blue)` | Accent color (range fill, thumb border, focus chrome). |
| `--super-input-label-margin-bottom` | `<length>` | `calc(21px * 0.375)` | Gap between a floating label and the control. |
| `--super-input-font-size` | `<length>` | `16px` | Base font size for the control and value readout. |
| `--super-input-label-height` | `<length>` | `calc( var(--v-line-height, 1.5) * var(--super-input-font-size) )` | Computed label line box height (used when a `<label>` is present). |
| `--super-input-height` | `<length>` | `calc(var(--super-input-thumb-size) + 36px)` | Host height for range layout (thumb + value readout). |
| `--super-input-width` | `<length> \| <percentage>` | `100%` | Host width for range layout. |
| `--super-input-min` | `<number>` | `0` | Range minimum. Prefer setting on the host (or via CSS): CSS cannot read the child input's `min` attribute from the parent. |
| `--super-input-max` | `<number>` | `100` | Range maximum. Prefer setting on the host (or via CSS). |
| `--super-input-value` | `<number>` | `50` | Current range value used for fill / readout positioning. With `reflect-value`, may be driven from `attr(current-value)` where typed `attr()` is supported. |
| `--super-input-thumb-size` | `<length>` | `44px` | Diameter of the range thumb. |
| `--super-input-thumb-color` | `<color>` | `var( --v-range-thumb-color, var(--super-input-bg) )` | Range thumb fill color. |
| `--super-input-accent` | `<color>` | `var(--super-input-primary, blue)` | Active track / accent color for the range fill. |
| `--super-input-track-height` | `<length>` | `2px` | Height of the range track. |
| `--super-input-font-weight` | `<number> \| <integer>` | `700` | Font weight for the range value readout. |

#### CSS Classes

| Name | Description |
| --- | --- |
| `.raised` | Raised / floating-label text field appearance. Apply as `class="raised"` on `<super-input>` wrapping a text-like `<input>`. |

#### CSS Aliases

| Alias | Kind | Matches | Description |
| --- | --- | --- | --- |
| `:--super-input` | element | `super-input`, `.tag-super-input` |  |
| `:--super-input--has-reflect-value` | state | `[reflect-value]`, `[data-reflect-value]` |  |
| `:--super-input--has-current-value` | state | `[current-value]`, `[data-current-value]` |  |



### Examples

#### Formatting input as the user types

Set `text-format` to a template using `x` as a character placeholder.


```html
<super-input text-format="(xxx) xxx-xxxx">
  <label>Phone number</label>
  <input value="8902340170" inputmode="numeric" />
</super-input>
```


Common templates:

- Phone (US): `(xxx) xxx-xxxx`
- Date: `xx/xx/xxxx`
- SSN: `xxx-xx-xxxx`

The wrapped `<input>` sees the formatted value. Pair with `pattern` for
validation.

#### Custom validity messages

Set `invalid-message` and the browser's native validation UI will surface it
when the input fails. Use the native `pattern`, `required`, `min`, `max`, etc for validation.
Try submitting the form in the demo below with an invalid phone number.


```html
<form>
  <super-input text-format="(xxx) xxx-xxxx" invalid-message="That doesn't look like a US phone number">
    <label>Phone number</label>
    <input required pattern="^\(\d{3}\)\s\d{3}-\d{4}" inputmode="numeric" />
  </super-input>
  <button type="submit">Submit</button>
</form>
```


The message is installed via `setCustomValidity()` on the `invalid` event and
cleared on the next `keydown`, so the input stops being marked invalid as
soon as the user tries again.

#### Using reflect-value
The `reflect-value` attribute has two primary uses:
- Is required for animating `raised` labels without an input `placeholder` attribute
- Allows you to hook into it to run your own behaviors

Here's an example with a raising label that will display an error if the user has not entered an email with an `@` or `.` characters.


```html
<super-input reflect-value class="raised" id="si-rv">
    <label>Email</label>
    <input type="email" />
    <style>
        super-input#si-rv {
            &::after { color: orange; }
            &:not([current-value*="."])::after {
                content: 'Email is missing "." character.';
            }
            &:not([current-value*="@"])::after {
                content: 'Email is missing "@" character.';
            }
        }
    </style>
</super-input>
```


#### Range slider
`<super-input>` ships with advanced slider CSS. Add `[type="range"]` to the `input`. `[reflect-value]` is required for this to work natively in Chromium browsers. Safari and Firefox will need some help via Quark or JS until they support [the CSS `type()` function](https://caniuse.com/mdn-css_types_type). You must also set the min/max CSS variables to match the min/max on the input.

Be cautious using this feature, as it aesthetically relies on non-standard pseudo elements for the time being.


```html
<div>
    <super-input reflect-value style="--super-input-min: 18; --super-input-max: 85;">
        <label>Age</label>
        <input type="range" name="age" step="1" value="36" min="18" max="85">
    </super-input>
    <!-- This is needed for Safari / Firefox -->
    <quark-sheet>
        super-input { --super-input-value: attr("current-value"); }
    </quark-sheet>
</div>
```

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---

# web-authn

Passkey register / authenticate with HTML. Pair it with Quark to render the result.


```html
<section>
  <web-authn options-url="/api/webauthn/register/options" verify-url="/api/webauthn/register/verify"
    start-method="register">
    <form>
      <label>
        Username
        <input name="username" required autocomplete="username">
      </label>
      <button type="submit">Register passkey</button>
    </form>
    <output></output>
  </web-authn>
  <quark-sheet>
    web-authn[is-success] {
      $res: prop("provision").body;
      output {
        content: "verified: #{$res.verified}";
      }
    }
    web-authn[is-error] output {
      content: "Ceremony failed (this mock needs an authenticator).";
    }
  </quark-sheet>
</section>
```
 

```html
<web-authn start-method="register" options-url="/api/registration-options" verify-url="/api/users">
    <form>
        <button type="submit">One click sign up!</button>
    </form>
</web-authn>
```

## Features

- **Provides data** Use Quark to render the verify response
- **Full ceremony** Fetches options, runs the browser's WebAuthn prompt, then verifies — one element
- **Register or authenticate** `start-method` picks the ceremony
- **Submit command** `--submit` starts the ceremony programmatically — for forms outside the DOM subtree, or buttons outside the `<form>`
- **Chainable** `web-authn-success` fires like any `{tag}-success` event — chain a redirect or next step
- **Highly configurable** Headers, credentials, redirect, etc

## Installation


`@excom/web-authn` v0.1.5

```bash
pnpm add @excom/web-authn
```

```bash
npm install @excom/web-authn
```

```bash
yarn add @excom/web-authn
```

### Import

```ts
import "@excom/web-authn";
```



Depends on [`@simplewebauthn/browser`](https://simplewebauthn.dev/) for the actual WebAuthn calls (`startRegistration` / `startAuthentication`). You can use any server-side library to handle the WebAuthn requests, but it is recommended to use the counterpart library, [`@simplewebauthn/server`](https://simplewebauthn.dev/), since they seamlessly understand the same contract.

## Usage

```html
<web-authn options-url="/api/webauthn/register/options"
  verify-url="/api/webauthn/register/verify" start-method="register">
  <form>
    <input name="username" required>
    <button type="submit">Register passkey</button>
  </form>
</web-authn>
```

On submit: `options-url` is fetched for ceremony options, the browser's native passkey prompt runs (`@simplewebauthn/browser`), and the resulting credential is posted to `verify-url`. Use `start-method="authenticate"` for sign-in instead of registration.

Hook the lifecycle state with CSS:

```css
web-authn[is-loading] { /* show loading spinner */ }
web-authn[is-error]::before { content: "An error occurred." }
```

Or Quark:

```quark
web-authn[is-success] {
  $res: prop("provision").body;
  span { content: $res.verified; }
}
```

Chain a next step off success the same way you would for any `<super-form>` or `<provider-fetch>`:

```html
<event-handler listen-for="web-authn-success" fire-event="onboarding-step-complete">
  <web-authn options-url="/api/webauthn/register/options"
    verify-url="/api/webauthn/register/verify" start-method="register">
    <form><input name="username"><button type="submit">Register</button></form>
  </web-authn>
</event-handler>
```

### Examples

#### Authenticate


```html
<section>
  <web-authn options-url="/api/webauthn/authenticate/options" verify-url="/api/webauthn/authenticate/verify"
    start-method="authenticate">
    <form>
      <label>
        Username
        <input name="username" required autocomplete="username webauthn">
      </label>
      <button type="submit">Sign in with passkey</button>
    </form>
    <output></output>
  </web-authn>
  <quark-sheet>
    web-authn[is-success] {
      $res: prop("provision").body;
      output {
        content: "verified: #{$res.verified}";
      }
    }
    web-authn[is-error] output {
      content: "Ceremony failed (this mock needs an authenticator).";
    }
  </quark-sheet>
</section>
```


### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description | Inherited from |
| --- | --- | --- | --- | --- | --- | --- |
| `form-ref` | option | `string` | `":scope form"` | `<CSS Selector>` | CSS selector for the `<form>` to intercept. Must be a descendant to be heard directly — point elsewhere and invoke the `--submit` command instead. |  |
| `start-method` | option | `string` |  | `"register"` \| `"authenticate"` | Which WebAuthn ceremony to run. |  |
| `verify-url` | option | `string` |  | `<URL>` | Endpoint that verifies the credential produced by the browser prompt (your server's `verifyRegistrationResponse` / `verifyAuthenticationResponse`). Receives the credential as the request body. |  |
| `has-body` | option | `boolean` |  |  | Force a request body even for methods that don't imply one (`GET` / `HEAD`). Already implied for `POST` / `PUT` / `PATCH`. | `@excom/fetchable-element` |
| `api-url` | option | `string` | `""` |  | Endpoint URL. When the request has no body, the JSON payload (from `form-ref` or custom `doFetch()` args) is merged in as query params instead. | `@excom/fetchable-element` |
| `api-method` | option | `string` | `"GET"` |  | HTTP method. Always uppercased before the request is sent. | `@excom/fetchable-element` |
| `header-accept` | option | `string` | `"application/json"` |  | `Accept` request header. | `@excom/fetchable-element` |
| `header-content-type` | option | `string` | `"application/json"` |  | `Content-Type` request header. Dropped entirely when the request has no body. | `@excom/fetchable-element` |
| `header-cache-control` | option | `string` |  |  | `Cache-Control` request header. Unset by default (browser default caching applies). | `@excom/fetchable-element` |
| `fetch-redirect` | option | `string` |  | `"follow"` \| `"error"` \| `"manual"` | `RequestInit.redirect` mode. Unset defers to the browser default (`follow`). | `@excom/fetchable-element` |
| `fetch-credentials` | option | `string` | `"include"` | `"omit"` \| `"same-origin"` \| `"include"` | `RequestInit.credentials` mode. | `@excom/fetchable-element` |
| `is-loading` | state | `boolean` |  |  | A request is currently in flight. | `@excom/fetchable-element` |
| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. Mutually exclusive with `is-loading` and `is-error`. | `@excom/fetchable-element` |
| `is-error` | state | `boolean` |  |  | The most recent request failed (status 400 or above, network error, or a thrown error other than `AbortError`). Fires with the `error` event. | `@excom/fetchable-element` |

#### Provision

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `provision` | `FetchResponse` (`{ bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }`) | Response payload on success, or error payload on failure. Success shape: `{ status, statusText, ok, headers, url, redirected, bodyUsed, type, body }`. Failure shape is either that same response shape (server responded with an error status) or `{ message, stack }` (request never completed). Not reflected as an attribute. | `@excom/fetchable-element` |

#### Fires

| Name | Type | Description | Inherited from |
| --- | --- | --- | --- |
| `web-authn-submit` | `WebAuthnSubmitEvent` (`CustomEvent & { type: "web-authn-submit"; detail: [url: string, requestInit: RequestInit]; bubbles: true; cancelable: true; composed: true }`) | Internal — dispatched once the browser ceremony (register or authenticate) resolves, just before the verify-url fetch runs. The credential is the request body. Default action calls `doFetch()`. |  |
| `web-authn-loading` | `FetchableLoadingEvent` (`CustomEvent & { type: "{tag}-loading"; detail: void; bubbles: true; cancelable: true; composed: true }`) | Dispatched immediately before the request is sent. | `@excom/fetchable-element` |
| `web-authn-success` | `FetchableSuccessEvent` (`CustomEvent & { type: "{tag}-success"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request resolves successfully. `event.detail` is the parsed response (see `provision`). | `@excom/fetchable-element` |
| `web-authn-error` | `FetchableErrorEvent` (`CustomEvent & { type: "{tag}-error"; detail: { bodyUsed: boolean; headers: [string, string][]; ok: boolean; redirected: boolean; status: number; statusText: string; type: ResponseType; url: string; body: unknown; } \| { message: string; stack?: string }; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails — status 400 or above, network error, or a thrown error. `event.detail` is the error payload (see `provision`). Not dispatched for aborted requests. | `@excom/fetchable-element` |

#### Listens for

| Name | Type | Description |
| --- | --- | --- |
| `submit` | `WebAuthnNativeSubmitEvent` (`SubmitEvent & { type: "submit"; bubbles: true; cancelable: true; composed: false; }`) | The default action of the `<form>` matched by `form-ref`; prevented, then starts the ceremony. |

#### Commands

| Command | Action |
| --- | --- |
| `--submit` | Starts the ceremony programmatically (`<button command="--submit" commandfor="…">`) — the only option when `form-ref` points to a form that isn't a descendant. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `web-authn-submit` | Calls `doFetch(url, requestInit)` with the event's detail (the verify-url request). |

## Release notes

### 0.1.4 (2026-10-01)

- A failed ceremony or options request now clears is-loading and sets is-error with the message in provision

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources


---