@fusion.dev/helix-docs 0.205.2 → 0.207.0

package/content/other-frameworks.mdx

@@ -8,9 +8,9 @@ trailing: true
 
 # Other frameworks
 
-This page covers Solid, Qwik, Lit, Ember, Alpine, htmx, and any other framework
-that puts elements in a document. They all follow the same three rules and need
-nothing else.
+This page covers Preact, Solid, Qwik, Lit, Ember, Alpine, htmx, and any other
+framework that puts elements in a document. They all follow the same three
+rules and need nothing else.
 
 ## The three rules
 
@@ -44,11 +44,12 @@ in full.
 
 | Framework | Notes |
 |---|---|
-| Solid | Sets properties on custom elements by default. Use `prop:` to force one and `attr:` to force the other. `on:helix-before-change` binds the literal name |
-| Qwik | Works as JSX. Bind with `document:on…` or a ref, since a plain `on*` prop is normalized |
-| Lit | `.prop=`, `?bool=`, and `@helix-before-change=` work with no setup |
-| Ember | Angle-bracket invocation passes attributes only, so set properties from a modifier |
 | Alpine, htmx | Markup and attributes only, which work with every component. Refusing a change needs script |
+| Ember | Angle-bracket invocation passes attributes only, so set properties from a modifier |
+| Lit | `.prop=`, `?bool=`, and `@helix-before-change=` work with no setup |
+| Preact | Sets a property when the element has one, and an attribute otherwise. `onhelix-before-change` binds the literal name. [Typings](#typings) says how to type the tags |
+| Qwik | Works as JSX. Bind with `document:on…` or a ref, since a plain `on*` prop is normalized |
+| Solid | Sets properties on custom elements by default. Use `prop:` to force one and `attr:` to force the other. `on:helix-before-change` binds the literal name. [Typings](#typings) says how to type the tags |
 
 We do not test these frameworks, so they share one page. If your framework needs
 something the three rules do not cover, tell us. It is a gap in this page or in
@@ -56,11 +57,50 @@ the library.
 
 ## Typings
 
-`@fusion.dev/helix/jsx` is the base for typing any framework that uses JSX, and
-the Svelte typings are built from it. If your framework needs a different
-format, use the manifest at `@fusion.dev/helix/custom-elements.json`. It
-describes every tag, prop, event, and part, and we generate all our typings from
-it.
+`@fusion.dev/helix/jsx` types the tags for React, Preact, and Solid, and it is
+the base for typing any other framework that uses JSX. The Svelte typings read
+their props from it. It needs only the types of the framework you use, and it
+compiles with `skipLibCheck: false`.
+
+`ref` and `style` take the types of the framework the tag is written in:
+
+- React: React's `Ref` and `CSSProperties`.
+- Preact: Preact's `Ref`, and the `style` a `<div>` takes, which is a string or
+  an object.
+- Solid: the element or a callback that receives it, and the `style` a `<div>`
+  takes, which is a string or an object.
+- Any other framework: the element or a callback that receives it, and an
+  object of style properties.
+
+In Preact and Solid, import the typings once, anywhere TypeScript sees it:
+
+```ts
+import '@fusion.dev/helix/jsx'
+```
+
+Preact reads the tags with `jsxImportSource: "preact"` and with `h` as the JSX
+factory. If your `paths` alias `react` to `preact/compat`, the tags take `ref`
+and `style` as `preact/compat` types React's, so `style` takes an object.
+
+Solid reads the tags with `jsxImportSource: "solid-js"`, and each tag also
+takes `prop:`, `attr:`, and `on:` forms of its props and events.
+
+With `jsxImportSource: "solid-js/h"`, Solid runs without its compiler, and the
+same import types the tags. Each prop also takes a function that returns its
+value, and `h` calls that function again when a signal it reads changes. A
+property whose value is a function, such as a slider's `formatter`, takes only a
+function that returns it, because `h` calls any function it is given:
+
+```tsx
+<helix-slider disabled={() => busy()} formatter={() => format} label="Volume" />
+```
+
+`ref`, `children`, and the handlers named `on…`, such as
+`on:helix-before-change`, take their values as they are.
+
+If your framework needs a different format, use the manifest at
+`@fusion.dev/helix/custom-elements.json`. It describes every tag, prop, event,
+and part, and we generate all our typings from it.
 
 ## Register the elements
 

package/content/overriding-a-component.mdx

@@ -69,7 +69,7 @@ helix-select::part(trigger) {
   font-variant-numeric: tabular-nums;
 }
 
-helix-dialog::part(dialog) {
+helix-dialog::part(surface) {
   max-inline-size: 40rem;
 }
 ```
@@ -99,16 +99,17 @@ helix-video::part(overflow-header) { … }
 ```
 
 `<helix-date-input>` renders a date picker in the `picker` role, so the picker's
-`cell` part is `picker-cell`. When the child's part is the role itself, the
-forwarded name is the role alone. The tooltip inside `<helix-copy-button>` is
-`tooltip`, and its arrow is `tooltip-arrow`.
+`cell` part is `picker-cell`. The tooltip inside `<helix-copy-button>` is in the
+`tooltip` role, so its `surface` is `tooltip-surface` and its arrow is
+`tooltip-arrow`. When the child's part is the role itself, the forwarded name is
+the role alone: each line inside `<helix-log>` is `line`.
 
 A part that changes with a state has a second name while the state is active,
 and that name is forwarded too. A tooltip placed below its button is also
-`tooltip-bottom`, and its arrow is also `tooltip-arrow-bottom`. Your stylesheet
-can use these names to style each side, which it cannot detect any other way.
-The arrow already faces the button on every side. Use the names for styles you
-add on top.
+`tooltip-surface-bottom`, and its arrow is also `tooltip-arrow-bottom`. Your
+stylesheet can use these names to style each side, which it cannot detect any
+other way. The arrow already faces the button on every side. Use the names for
+styles you add on top.
 
 **The prefix keeps part names unique.** A component and its child can use the
 same word. This happened once: `Command` forwarded the listbox's `search-field`
@@ -138,8 +139,8 @@ so you learn each name once:
 | `container` | An element's own outer box. |
 | `content` | A region you fill. |
 | `panel` | A region switched between, or a sheet anchored to an edge. |
-| `surface` | A floating panel drawn over the page. |
-| `viewport` | A scrollport the component reads the position of. |
+| `surface` | A floating panel drawn over the page, such as a menu, a popover, a tooltip, or a dialog. |
+| `viewport` | The box that shows part of a larger area: a scrollport, or the frame a map or a graph is panned and zoomed in. |
 
 A part that names something specific to one component, such as `thumb`,
 `swatch`, or `weekday`, is listed on that component's page.

package/content/react.mdx

@@ -137,6 +137,8 @@ starts with that value and keeps applying its own changes, so the markup below
 works without a handler.
 
 ```tsx
+import { flushSync } from 'react-dom'
+
 // Seeded: the element owns it from there.
 <helix-input default-value="Ada" label="Name" />
 
@@ -148,7 +150,7 @@ works without a handler.
   label="Name"
   onhelix-before-change={(event) => {
     event.preventDefault()
-    setName(clean(event.detail.value))
+    flushSync(() => setName(clean(event.detail.value)))
   }}
   value={name}
 />
@@ -159,6 +161,18 @@ refuse it. React restores a native `<input>` whose state did not change, and it
 does not do this for a custom element. A handler that does not call `setState`
 leaves the element with the new value.
 
+**Set the state inside `flushSync` when you write your own value.** React sets
+the priority of a state update from the type of the event being handled.
+`helix-before-change` is not one of the types React lists, so the update gets
+the default priority and renders in a later task. A key that arrives before that
+task lands in the text from before the update, and the keys typed in between are
+lost. A barcode scanner, a password manager, and a test send keys that fast:
+Playwright typing `Ada L!` with no delay into a field that keeps lowercase
+letters left it empty. `flushSync` renders the update before your handler
+returns, so the element holds your value when the next key arrives. The same
+applies to every field you type into, such as `helix-textarea`,
+`helix-number-input`, and `helix-pin-input`.
+
 *Until August 26, 2026, this page described the opposite behavior, and the typings
 enforced it. Writing `value` made you the owner of the state. The element
 applied no change until you set the value, and `<helix-input value="Ada" />`

package/content/recipes.mdx

@@ -140,7 +140,7 @@ Three Markdown constructs need components, because HTML alone cannot hold what
 they need:
 
 - **Fenced code** becomes `helix-code-block`, with the fence's language as its
-  `label`. A `<pre>` has no label or copy button.
+  `label` and its `language`. A `<pre>` has no label or copy button.
 - **Alerts** such as `> [!WARNING]` become `helix-callout`. A `<blockquote>` has no
   tone. `NOTE` becomes `tone="info"`, `TIP` becomes `success`, `WARNING` becomes
   `warning`, and `CAUTION` becomes `danger`. `IMPORTANT` has no tone. Each
@@ -155,13 +155,29 @@ The `rehype` plugin from `@fusion.dev/helix/rehype` makes all three changes in t
 tree your Markdown library has already built. It parses nothing, so your
 library, its dialect, and your sanitizing stay yours. Add it to any pipeline
 that reaches rehype, such as `remark` with `remark-rehype`, `react-markdown`, or
-MDX:
+MDX.
+
+Tables are GitHub Flavored Markdown, so your pipeline needs `remark-gfm` to
+parse them. Without it, a table stays a paragraph of pipes. For a `remark`
+pipeline, install:
+
+```sh
+bun add unified remark-parse remark-gfm remark-rehype rehype-stringify
+```
+
+Then add the plugin after `remark-rehype`:
 
 ```js
 import rehypeHelix from '@fusion.dev/helix/rehype'
+import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import { unified } from 'unified'
 
 const html = await unified()
   .use(remarkParse)
+  .use(remarkGfm)
   .use(remarkRehype)
   .use(rehypeHelix)
   .use(rehypeStringify)

package/content/sandbox.mdx

@@ -12,8 +12,10 @@ You can edit every example on a component's page. When you change the markup,
 the preview redraws. When you change the stylesheet beside it, the preview
 restyles.
 
-To build a playground of your own, you would use the same elements. The
-isolation described below makes it safe to run markup that someone else wrote.
+To build a playground of your own, use the same elements: the sandbox from
+`@fusion.dev/helix/sandbox`, and the editor from `@fusion.dev/helix-sandbox`.
+The isolation described below makes it safe to run markup that someone else
+wrote.
 
 ## How the preview is isolated
 
@@ -160,7 +162,7 @@ preview, and `helix-caret` from it fills the status bar's position. A wrapper
 around CodeMirror:
 
 ```ts
-import { HelixBeforeEditEvent } from '@fusion.dev/helix'
+import { HelixBeforeEditEvent } from '@fusion.dev/helix-core'
 import { EditorView, basicSetup } from 'codemirror'
 
 class CodeEditor extends HTMLElement {
@@ -217,16 +219,18 @@ own message from `:state(failed)`.
 
 ## The frame document
 
-`helix-sandbox-preview` loads `src` into a sandboxed frame. You provide that
-document. It loads the styles and the elements your examples use, and it talks
-to the preview through `postMessage`.
+`helix-sandbox-preview` runs each example in a sandboxed frame. The frame
+document either comes with the preview or is one you host.
 
-Without `src`, the preview loads a built-in document. It runs the example's
-HTML, CSS, and scripts, and reports the console, uncaught errors, the height,
-and presses, so a sandbox renders with nothing to host. It defines no element,
-so set `src` to a document of your own when your examples use Helix
-components. Its script is inline, so a page whose Content Security Policy
-refuses inline scripts needs a `src` too.
+**Without `src`, the preview loads a built-in document**, so a sandbox needs
+nothing hosted. It runs the example's HTML, CSS, and scripts, and reports the
+console, uncaught errors, the height, and presses. It defines no element, so
+set `src` to a document of your own when your examples use Helix components.
+Its script is inline, so a page whose Content Security Policy refuses inline
+scripts needs a `src` too.
+
+**With `src`, the preview loads your document.** It loads the styles and the
+elements your examples use, and it talks to the preview through `postMessage`.
 
 The messages:
 
@@ -250,9 +254,18 @@ it was given. The types are exported from `@fusion.dev/helix/sandbox` as
 you. Call it once in the frame document, after your elements are defined. It
 writes each render into `#preview-root`, runs the example's scripts, relays
 its console, its uncaught errors, and its unhandled promise rejections,
-reports its height and its presses, and adds the rules for the four layouts. A frame follows. `/helix.css` is the stylesheet from
-`@fusion.dev/helix-styles`, and `/frame.js` is a classic script you bundle,
-for the reason under "How the preview is isolated":
+reports its height and its presses, and adds the rules for the four layouts.
+
+The frame's own script must be a classic script, bundled into one file. A
+module does not load there. The frame's origin is opaque, so a module import
+back to your site is a cross-origin request, which fails unless your server
+answers it with CORS headers. A stylesheet `<link>` is not checked, so the
+styles load as they are.
+
+A frame follows. `/frame.js` is the bundle. `/helix.css` is the stylesheet
+from `@fusion.dev/helix-styles`, and it imports `primitives.css`, `tokens.css`,
+`base.css`, and `elements.css` from beside it, so serve the five files from
+the package's `dist` folder together:
 
 ```html
 <!doctype html>
@@ -284,16 +297,53 @@ Logs from the example appear in the console panel. Logs from the page around it
 do not. We patch the console inside the frame on purpose, so the panel shows
 what the example logs and nothing else.
 
-## The package is private
+## The editor and the highlighter
+
+`@fusion.dev/helix-sandbox` is the editor the component pages use, and the
+highlighter that colors their code. Install it beside the library:
+
+```sh
+npm install @fusion.dev/helix @fusion.dev/helix-styles @fusion.dev/helix-sandbox
+```
+
+Each entry does one thing:
+
+- `@fusion.dev/helix-sandbox/editor` registers `helix-sandbox-editor`, a
+  source pane with CodeMirror behind it.
+- `@fusion.dev/helix-sandbox/highlight` turns a snippet into highlighted HTML,
+  on a server or in a page, with no editor.
+- `@fusion.dev/helix-sandbox/code-block` colors every Code Block on the page.
+
+The editor is a source pane, so it goes in the `source` slot, with a `name`
+the sandbox reads:
+
+```html
+<helix-sandbox>
+  <helix-sandbox-editor
+    language="html"
+    name="html"
+    slot="source"
+    value="<p>Hello</p>"
+  ></helix-sandbox-editor>
+  <helix-sandbox-preview slot="preview"></helix-sandbox-preview>
+</helix-sandbox>
+```
+
+```ts
+import '@fusion.dev/helix/sandbox'
+import '@fusion.dev/helix-sandbox/editor'
+```
+
+The [Sandbox reference](/helix/components/sandbox#helix-sandbox-editor) lists
+the editor's properties, events, methods, and states.
 
-`@fusion.dev/helix-sandbox` is not published. It is the editor and spec runner
-for this repository, and it is Helix tooling. It depends on the repository:
+`highlight` reads the same grammars as the editor. By default each token is a
+span with Lezer's `tok-` class, for a stylesheet of your own. Pass
+`syntaxHighlighter` for the editor's classes, and put `syntaxRules` in the
+stylesheet where the result is drawn for the editor's colors:
 
-- The elements depend on the frame.
-- The frame depends on the build.
-- The build depends on this repository's layout.
+```ts
+import { highlight, syntaxHighlighter } from '@fusion.dev/helix-sandbox/highlight'
 
-To add editable examples to your own documentation today, you would build the
-editor yourself, from the manifest and the `.examples` files. This is a gap we
-have not filled, and we have no policy against filling it. Tell us if you need
-it.
+const markup = highlight('const total = 1', 'ts', syntaxHighlighter)
+```

package/content/server-rendering.mdx

@@ -85,8 +85,8 @@ Run your page's own scripts after the definitions load. Hydration expects that
 order. A property you set before hydration is one the server did not render
 with.
 
-`bun run check:spec:dsd` renders every example with Lit SSR, hydrates it in
-Chromium, and compares it with the same example rendered on a client.
+We render every component example in both tiers with Lit SSR, hydrate it in
+Chromium, and compare it with the same example rendered on a client.
 
 React server components do not use declarative shadow DOM. Their output is
 replayed through DOM APIs, and declarative shadow DOM does not activate for

package/content/state-and-control.mdx

@@ -49,12 +49,18 @@ state yourself, cancel the change and assign your own value:
   label="Name"
   onhelix-before-change={(event) => {
     event.preventDefault()
-    setName(sanitize(event.detail.value))
+    flushSync(() => setName(sanitize(event.detail.value)))
   }}
   value={name}
 />
 ```
 
+Assign your value before the next key arrives, or that key lands in the text
+from before your value. Vue, Svelte, and Solid apply a bound value in time. In
+React, set the state inside `flushSync`, as [React](./react) explains. In
+Angular without zone.js, call `detectChanges()` after you set the signal, as
+[Angular](./angular) explains.
+
 The platform uses the same pattern. You call `preventDefault()` to cancel:
 
 - a form submit

package/content/surfaces-and-separation.mdx

@@ -98,4 +98,5 @@ its own components, and the same applies to anything you build with it.
 The theme engine measures each ink against the ground it is actually painted
 on. The ladder records which pairs occur. For example, `foreground` on
 `surface-overlay` is a real pair, and `foreground-on-primary` on `surface` is
-not. See [Color](./color).
+not. A field's fill, `well`, is translucent, so the text in a field is measured
+against the well over each surface. See [Color](./color).

package/content/svelte.mdx

@@ -12,30 +12,74 @@ import '@fusion.dev/helix/svelte'
 ```
 
 Add this types-only import once. It augments `SvelteHTMLElements`, so every
-Helix tag is typed in a component. The import re-exports the JSX types. Svelte
-binds a handler as `onhelix-before-change={…}`, which is the shape those types
-already describe. With one shared copy of the types, the Svelte and JSX typings
-cannot disagree.
+Helix tag is typed in a component. Svelte binds a handler as
+`onhelix-before-change={…}`, which is the shape the JSX typings already
+describe, so the Svelte typings read each tag's props from
+`@fusion.dev/helix/jsx`. The two cannot disagree.
+
+The typings need only Svelte's own types, and they compile with
+`skipLibCheck: false`.
 
 ## Pass props and bind events
 
 ```svelte
-<helix-input label="Name" onchange={(event) => (name = event.target.value)} value={name} />
+<helix-input
+  label="Name"
+  onchange={(event) => (name = event.currentTarget.value)}
+  value={name}
+></helix-input>
 ```
 
 Svelte sets a property when the element has one, and an attribute otherwise. It
 binds `on*` with `addEventListener`. Svelte shows no unknown-element warning,
 and you do not need a compiler flag.
 
+Read the value from `event.currentTarget`, which is typed as the element.
+`event.target` is an `EventTarget | null`, which has no `value`.
+
 Svelte passes objects and arrays as properties on its own:
 
 ```svelte
-<helix-data-table label="People" rows={people} />
+<helix-data-table label="People" rows={people}></helix-data-table>
 ```
 
 Svelte's own attributes are typed on every Helix tag as well, so `onclick`,
 `class`, and a `style` string check as they do on a `div`.
 
+## Hold the element
+
+`bind:this` holds the element, typed as its class:
+
+```svelte
+<script lang="ts">
+  import type { HelixInput } from '@fusion.dev/helix'
+
+  let input: HelixInput | undefined = $state()
+</script>
+
+<helix-input bind:this={input} label="Name"></helix-input>
+```
+
+## Type a handler in the script
+
+A handler written on the tag takes its event type from the tag. A handler
+written in the script names its event type, which `@fusion.dev/helix/jsx`
+exports for each element and event:
+
+```svelte
+<script lang="ts">
+  import type { HelixInputHelixBeforeChangeElementEvent } from '@fusion.dev/helix/jsx'
+
+  const refuseLong = (event: HelixInputHelixBeforeChangeElementEvent) => {
+    if (event.detail.value.length > 40) {
+      event.preventDefault()
+    }
+  }
+</script>
+
+<helix-input label="Handle" onhelix-before-change={refuseLong}></helix-input>
+```
+
 ## Ignore the click warnings on a control
 
 `svelte-check` warns about an `onclick` on any Helix element. Its accessibility
@@ -55,8 +99,10 @@ right. Use a control there.
 
 These two rules apply in every framework.
 
-`bind:` does not work on a Helix control, because custom elements have no
-two-way binding convention to opt into. Read the value from the event.
+Two-way bindings do not work on a Helix control, because custom elements have
+no two-way binding convention to opt into. Svelte accepts `bind:value` only on
+`<input>`, `<textarea>`, and `<select>`, and `bind:checked` only on `<input>`.
+Read the value from the event.
 
 A declared `value`, `open`, `checked`, or `active` is a seed. The element starts
 with that value and then applies its own changes. To refuse a change, cancel the

package/content/theme-builder.mdx

@@ -73,9 +73,10 @@ its target. Its three tabs are:
 - **Contrast.** The pairs that fail, or a line saying that every pair passes.
 - **Collisions.** Colors too close to each other to tell apart, such as the
   primary color and a status color.
-- **Unverifiable.** Pairs whose background is translucent, so there is no known
-  color to measure against. This is the cost of a translucent material, and
-  the theme builder reports it.
+- **Unverifiable.** Pairs whose background is translucent over something the
+  engine cannot know, such as a photograph or the page under a translucent
+  material, so there is no known color to measure against. This is the cost of
+  a translucent material, and the theme builder reports it.
 
 ## What the theme builder gives you
 
@@ -89,6 +90,17 @@ stylesheet:
 }
 ```
 
+The block holds one mode, the one the preview shows, under the scope
+`[data-theme="preview"]`. Put that attribute on the element to theme, or change
+the selector. Under any selector other than `:root`, also add
+`data-helix-theme` to the element. The block sets the seeds the stylesheet
+derives the chart colors, the spacing, and the corner radii from, and the
+stylesheet reads seeds only at `:root` or on an element with
+`data-helix-theme`. See [Two ways to theme](./theming#two-ways-to-theme).
+
+For a page with both modes, derive the intent with `deriveModes` or
+`helix theme build`, as [Derive both modes](./theming#derive-both-modes) shows.
+
 The page's link holds every input you changed, so a link is the theme. To derive
 the theme in your own build, write the same inputs as an intent object:
 

package/content/theming.mdx

@@ -29,7 +29,11 @@ changing them one at a time. A change to one value can break the contrast of a
 component elsewhere, and nothing tells you.
 
 `@fusion.dev/helix-theme` computes a complete token set from a few intent
-inputs, and every text and background pair meets its contrast target.
+inputs. It solves each text color against the backgrounds it lands on, measures
+every pair in its surface model, and reports any pair that misses its contrast
+target. `foreground-subtle` is not in the model. It is a fixed step of the
+stylesheet's gray ramp, and the engine does not solve it, so its contrast is not
+guaranteed.
 
 ## Two ways to theme
 

package/content/tiers.mdx

@@ -21,8 +21,8 @@ depends only on the packages below it.
 Neither is a tier, and you do not need either one to render a component.
 
 There is no React package. We generate the framework typings into
-`@fusion.dev/helix`, and the bridge that repairs React's hydration of custom
-events is in `@fusion.dev/helix-core`. See [React](./react).
+`@fusion.dev/helix` and `@fusion.dev/helix-headless`, and the bridge that
+repairs React's hydration of custom events is in `@fusion.dev/helix-core`. See [React](./react).
 
 ## Why the tiers are separate packages
 
@@ -64,7 +64,7 @@ export class HelixHeadlessAccordionItem extends MixinControllerOpen(HelixElement
   }
 }
 
-// web/src/accordion/root/accordion-root.ts
+// styled/src/accordion/root/accordion-root.ts
 // extends the headless one, adds presentation only
 import { styles } from './accordion-root.css.js'
 
@@ -78,7 +78,7 @@ export class HelixAccordion extends HelixHeadlessAccordion {
 ```
 
 ```css
-/* web/src/accordion/item/accordion-item.css */
+/* styled/src/accordion/item/accordion-item.css */
 [part='trigger'] {
   min-block-size: var(--helix-size-control);
   padding: var(--helix-space-sm);
@@ -115,8 +115,8 @@ as unstyled text and then changes into a card. The delay is short. It is most
 visible on a server-rendered page, where the markup arrives long before the
 JavaScript.
 
-`@fusion.dev/helix` includes `elements.css`, which hides each of its tags until
-the tag's definition loads:
+`@fusion.dev/helix-styles` includes `elements.css`, which hides each tag of the
+styled tier until the tag's definition loads:
 
 ```css
 helix-card:not(:defined) {
@@ -124,7 +124,7 @@ helix-card:not(:defined) {
 }
 ```
 
-**The base tier ships no such file on purpose.** There are three reasons, and
+**The headless tier ships no such file on purpose.** There are three reasons, and
 the third one affects you most.
 
 First, hiding an element is a design choice. Below the styled tier, we ship only
@@ -138,20 +138,21 @@ inside, because there is no shadow root before the upgrade. The rule has to
 live in your stylesheet, so the choice is yours.
 
 Third, one file for every tag would not fit your project. You import only the
-base elements you use, so a generated list would include tags you never ship.
+headless elements you use, so a generated list would include tags you never ship.
 Write the rule for the elements you have:
 
 ```css
-helix-base-accordion:not(:defined),
-helix-base-dialog:not(:defined) {
+helix-headless-accordion:not(:defined),
+helix-headless-dialog:not(:defined) {
   visibility: hidden;
 }
 ```
 
-Use `visibility` so the element keeps its place in the layout and the page does
-not reflow when it upgrades. `display: none` collapses the box, and the content
-jumps in when the definition arrives. That replaces a flash of unstyled text
-with a shift of everything below it.
+Use `visibility`, so a hidden element keeps the size of its unstyled content.
+The layout still settles when the element upgrades and takes its own size.
+`display: none` collapses the box, so the element takes no space until the
+definition arrives, and then everything below it shifts by the element's full
+size.
 
 You may want to hide nothing. If your first paint matters more than the final
 layout, or your page has to be readable with JavaScript turned off, let the

package/content/using-helix-with-an-agent.mdx

@@ -43,8 +43,11 @@ writes where an installed family stands in for it, as `native-element`.
 
 Each family's API is in the packages you installed, and on this site:
 
-- `helix api family <family>`, or the MCP tool `helix_family`
-- `node_modules/@fusion.dev/helix/api.json`
+- `helix api family <family>`, or the MCP tool `helix_family`, which read every
+  Helix package you installed
+- `node_modules/@fusion.dev/helix/api.json`, and the `api.json` of each other
+  Helix package you installed, which lists the elements it adds to a family,
+  such as `helix-sandbox-editor` in `@fusion.dev/helix-sandbox`
 - `https://fusion.dev/helix/components/<family>.md` and `.json`
 
 Each lists the import lines, every tag, every property with its literal union,
@@ -98,12 +101,15 @@ block a change, call `preventDefault()` on the matching `helix-before-*` event:
   label="Name"
   onhelix-before-change={(event) => {
     event.preventDefault()
-    setName(clean(event.detail.value))
+    flushSync(() => setName(clean(event.detail.value)))
   }}
   value={name}
 />
 ```
 
+Set the state inside `flushSync` from `react-dom`. Without it, React renders the
+update in a later task, and keys typed faster than that are lost.
+
 A form reset returns the element to `default-value` and the matching attributes
 for the other states. See [State and control](./state-and-control).
 
@@ -213,12 +219,13 @@ Run these after you write Helix code, and fix every finding at `error` and
 
 | Command | MCP tool | What it finds |
 |---|---|---|
-| `helix scan` | `helix_check` | Unknown tags, attributes, values, slots, parts, hooks, events, and tokens, a native element a Helix family replaces, a missing import, and the rest, each with its file and line |
+| `helix scan` | `helix_check` | Unknown tags, attributes, values, slots, parts, hooks, events, and tokens, a native element a Helix family replaces, a missing import, a button inside a button, `disabled="false"`, and the rest, each with its file and line |
 | `helix diagnostics --once <url>` | `helix_check_page` | The same on the running page, and what the library logged as it ran |
 | `helix theme audit` | `helix_audit_theme` | Every foreground and background pair in your theme that misses its contrast target |
 
 `helix scan --file <path>` reports one file's findings and still reads the whole
-project, so an import in another file counts.
+project, so an import in another file counts. [Diagnostics](./diagnostics)
+lists every kind of finding, and what the checks do not cover.
 
 ## What this guide does not cover