@fusion.dev/helix-docs 0.223.1 → 0.224.0

package/content/other-frameworks.mdx

@@ -24,7 +24,7 @@ element.items = tabs
 ```
 
 **Bind events with `addEventListener`, using the event's own name.** Helix event
-names, such as `helix-before-open`, `helix-before-change`, and `helix-select`,
+names, such as `helix-before-open`, `helix-before-change`, and `helix-before-select`,
 are lowercase and hyphenated. They have no camel-case variant. Your framework's
 `on*` syntax needs to pass that exact name through.
 

package/content/routing.mdx

@@ -6,15 +6,15 @@ title: Routing and navigation
 
 # Routing and navigation
 
-Some components navigate, such as a tree used as a sidebar, a button that opens
-another page, or a tab that is a page. Each of these should be a link. A
+Some components navigate, such as a tree used as a sidebar, a menu item that
+opens another page, or a tab that is a page. Each of these should be a link. A
 framework router does not handle a link inside a shadow root the way it handles
 its own links.
 
 ## A component that navigates renders its own anchor
 
-`Tree.Item` and `Button` both take an `href`. With an `href`, the element you
-press *is* an `<a>`:
+`Tree.Item`, `Tab`, and `Menu.Item` take an `href`. With an `href`, the element
+you press *is* an `<a>`:
 
 ```html
 <helix-tree-item
@@ -103,9 +103,11 @@ changes the structure of the markup as well as adding an attribute. Without an
 `href`, nothing moves. The wrapper stays the `treeitem` and contains its group,
 the same way an `<li>` contains a `<ul>`.
 
-Tabs have no equivalent published pattern. Web Awesome has the same problem. Its
-answer is to drop the anchor and navigate in JavaScript. That works, and you
-lose every item in the list above.
+A tab with an `href` renders `role="tab"` on the `<a>` itself, so a press,
+Enter, and the browser's own link gestures follow it. It sends `helix-before-select`
+first, and canceling that keeps the browser from following, so a client-side
+router can follow it instead. Web Awesome drops the anchor and navigates in
+JavaScript, which loses every item in the list above.
 
 ## Use client-side routing with real anchors
 
@@ -166,9 +168,14 @@ That is expected.
 
 | Component | Notes |
 |---|---|
-| `Button` | Renders an `<a>` styled as a button. |
 | `Tree.Item` | Changes the ARIA shape, as above. A linked branch navigates from its row and opens from its chevron. |
 | `Menu.Item` | The row becomes the anchor and carries `menuitem`. Takes `target`, `rel` and `download`. |
+| `Tab` | The tab becomes the anchor and carries `tab`. Takes `target` and `rel`. `helix-before-select` comes first, and canceling it keeps the browser from following. |
+
+`Button` never renders an anchor, because a router renders its own `<a>` and
+cannot render one inside the button's shadow root. For a link that looks like a
+button, put the `data-button` recipe on your own anchor, such as
+`<Link data-button="solid" href="/pricing">`, which draws the same control.
 
 Other components that should navigate do not take an `href` yet. To make one
 navigate, slot a link into it. `Tree.Item` follows a slotted anchor when you
@@ -204,8 +211,8 @@ it cannot work here.
 
 No arrangement of the markup meets both of these constraints.
 
-**In a command palette, navigate from the `helix-select` event.** Listen for
-`helix-select` on `helix-command` and call your router. A palette entry is a
+**In a command palette, navigate from the `helix-before-select` event.** Listen for
+`helix-before-select` on `helix-command` and call your router. A palette entry is a
 command, and "go to Settings" is a command that navigates. Command palettes in
 other applications work the same way. You lose the gestures that only a real
 anchor has:

package/content/sandbox.mdx

@@ -182,7 +182,7 @@ preview, and `helix-caret` from it fills the status bar's position. A wrapper
 around CodeMirror:
 
 ```ts
-import { HelixBeforeEditEvent } from '@fusion.dev/helix-core'
+import { HelixBeforeEditEvent } from '@fusion.dev/helix/sandbox/events'
 import { EditorView, basicSetup } from 'codemirror'
 
 class CodeEditor extends HTMLElement {

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

@@ -122,7 +122,7 @@ casing must match. Outside React, use
 
 **Lifecycle events do not bubble. Coordination events do.**
 `helix-before-open` and `helix-before-close` reach the element and stop there,
-so a menu closing inside a dialog does not close the dialog. `helix-select`,
+so a menu closing inside a dialog does not close the dialog. `helix-before-select`,
 `helix-before-change`, and `helix-dismiss` cross shadow boundaries, so you can
 listen for them on a container. If a listener on a wrapper receives nothing, the
 event is a lifecycle event. Put the listener on the element.

package/content/using-the-elements.mdx

@@ -36,12 +36,37 @@ The bug is [facebook/react#35446](https://github.com/facebook/react/issues/35446
 and it is still open. The elements work around it for you.
 
 Every Helix element binds the handler itself, just before it dispatches any
-event, using the function React already holds for it. We measured this in
-Chrome against React 19.2.8. On a hydrated page, the first event reaches the
-handler. After React binds its own listener, no event is delivered twice.
+event, using the function React already holds for it. On a hydrated page, the
+first event reaches the handler. After React binds its own listener, no event
+is delivered twice.
 
 You do not need to do anything, and nothing changes when React fixes the bug.
 
+We measured this in Chromium against React 19.3.1 on October 25, 2026. Each
+version below rendered a page with `renderToString` and hydrated it with
+`hydrateRoot`:
+
+| React | Bug present | Helix handles it |
+| --- | --- | --- |
+| 19.0.9 | Yes | Yes |
+| 19.2.9 | Yes | Yes |
+| 19.3.1 | Yes | Yes |
+| 19.3.0 canary of October 23, 2026 | Yes | Yes |
+| 18.3.1 | Yes | The first event only |
+
+Helix supports React 19. React 18 binds no `on` prop on a custom element at
+all. Helix binds the first handler, but each render that passes a new function
+adds another listener, so a handler runs once for every render it has been
+through.
+
+In a development build, the page logs an error when React has a root and no
+Helix element finds the props React holds for it. This means the installed
+React stores its props under a key Helix does not read, and every `onhelix-*`
+handler on a server-rendered page is dead. Pin React to a version in the table,
+and open an issue at
+[github.com/project-fusion/fusion](https://github.com/project-fusion/fusion/issues)
+that names the version you installed.
+
 React's own events work when they bubble. `onClick` on a `<helix-button>` goes
 through React's synthetic event system, which hydration sets up.
 
@@ -63,8 +88,8 @@ written.
 - `onhelix-sample-start` reaches `helix-sample-start`. ✅
 - `onHelixOpen` binds an event called `HelixOpen`, which is never dispatched. ❌
 
-The number of hyphens does not matter. We measured this in Chrome against React
-19.2.8.
+The number of hyphens does not matter. We measured this in Chromium against
+React 19.3.1.
 
 ## Register the elements in one client component
 

package/content/visual-testing.mdx

@@ -23,7 +23,13 @@ npx playwright install --with-deps chromium
 
 Capture runs in Playwright, which you install beside the command line. The
 rest of `helix` needs no browser, so Playwright is an optional peer, and
-`helix visual test` names it when it is missing.
+`helix visual test` names it when it is missing. A config in TypeScript needs
+Node 22.18 or later. On an older Node, write it as `visual.config.mjs`.
+
+**On macOS and Windows, a run skips until you choose where baselines are taken.**
+`test` and `update` say so, compare nothing, and exit 0, because text draws
+differently on each platform. Take baselines on Linux, or set `platform: 'any'`
+to compare on the machine in front of you.
 
 ## Commands
 
@@ -54,6 +60,38 @@ Each run ends with one line that says what it compared and what it skipped.
 `helix --json visual …` prints one JSON document on stdout and moves the
 sentences to stderr.
 
+## Picture a site
+
+Picture a production build, because a dev server draws its own overlays, and they
+differ from run to run. `visual.config.ts`, for a Next.js site:
+
+```ts
+import { defineConfig } from '@fusion.dev/helix-cli/visual'
+
+export default defineConfig({
+  sources: [
+    {
+      baselines: 'visual/baselines',
+      kind: 'server',
+      name: 'site',
+      routes: ['/', '/pricing', { name: 'not-found', path: '/nope', status: 404 }],
+      start: 'npm run start -- --port 3100',
+      url: 'http://localhost:3100',
+    },
+  ],
+})
+```
+
+```sh
+npm run build
+npx helix visual update
+```
+
+`update` writes the baselines and the fingerprint, and its report shows each
+picture it wrote. Look at them, commit them, and run `helix visual test` from then
+on. Any page that answers 400 or above fails the entry, unless its route names that
+`status`.
+
 ## The config
 
 `visual.config.ts`, in the directory you run `helix visual` from:
@@ -90,9 +128,28 @@ export default defineConfig({
   width, and dark when you give none. Each baseline is written beside its
   entry as `<stem>.<name>.png`.
 - **`serve`** is URL paths served from disk, relative to the config.
+- **`baselines`** is, on a server source, the directory its baselines are written
+  in, relative to the config.
+- **`platform`** is where baselines are taken and compared: `linux` unless you set
+  `any`.
+- **`network`** is what a page may reach. `origin`, the default, refuses every
+  request to another host and names each host in the log and in `run.json`.
+  `{ allow: ['tiles.example.com'] }` lets those hosts through, and `open` lets every
+  host through.
+- **`mask`** is selectors whose elements are painted over in every picture, for
+  what changes on its own, such as a clock. A mask paints over the element's box and
+  anything drawn on top of it. The run names a mask that matches nothing on a page,
+  or only elements with no box.
+- **`style`** is a stylesheet applied while each picture is taken, to hold still
+  what `mask` cannot.
+- **`settle.selector`** names what a page matches once it has drawn what it draws
+  late, such as a map's tiles. The entry fails when nothing matches within
+  `settle.timeout`, 30 seconds unless you set it.
 - **`settle.readyProperty`** names a property your elements carry holding a
   promise that resolves once they have rendered. The run awaits it before each
-  shot.
+  shot, for 5 seconds, and then names the tags still waiting.
+- **`settle.elements`** limits the custom elements a run waits for to one tag
+  prefix, for a framework that writes hyphenated tags it never defines.
 - **`aria`** keeps each entry's accessibility snapshot beside its baselines
   and compares it as text, so a lost label fails even when no pixel moved.
 - **`checks`** adds judgments that need no baseline: `code` fails a code block

package/dist/pages.generated.js

@@ -112,7 +112,7 @@ export const docPages = [
         title: 'Intent reference',
     },
     {
-        description: 'What Helix is, and the packages it includes.',
+        description: 'What Fusion Helix is, and the packages it includes.',
         order: 1,
         section: 'Getting started',
         slug: 'introduction',