@fusion.dev/helix 0.162.1 → 0.163.0

package/custom-elements.json

@@ -18903,6 +18903,22 @@
             "package": "@fusion.dev/helix-headless/canvas"
           }
         },
+        {
+          "kind": "js",
+          "name": "CanvasRoute",
+          "declaration": {
+            "name": "CanvasRoute",
+            "package": "@fusion.dev/helix-headless/canvas"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CanvasRouteEnds",
+          "declaration": {
+            "name": "CanvasRouteEnds",
+            "package": "@fusion.dev/helix-headless/canvas"
+          }
+        },
         {
           "kind": "js",
           "name": "CanvasSide",
@@ -20008,6 +20024,14 @@
               "description": "The size of the label on a connection.",
               "name": "--canvas-label-font-size"
             },
+            {
+              "description": "The height of the minimap, under `controls=\"minimap\"`.",
+              "name": "--canvas-minimap-block-size"
+            },
+            {
+              "description": "The width of the minimap, under `controls=\"minimap\"`.",
+              "name": "--canvas-minimap-inline-size"
+            },
             {
               "description": "The frame's corners.",
               "name": "--canvas-radius"
@@ -21052,6 +21076,18 @@
                 "module": "src/canvas/root/canvas-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "edgeRoute",
+              "type": {
+                "text": "CanvasRoute | undefined"
+              },
+              "description": "Draws every connection's line: a function from where it leaves and\narrives, and the sides it does, to its SVG path and where its label sits.\n\nAbsent, or returning nothing for a connection, draws the board's own\nroute. A function that throws draws the board's own too, and the error is\nreported to the page as an uncaught one. Set it as a property.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "fallbackLabel",
@@ -22383,6 +22419,53 @@
                 "module": "src/canvas/root/canvas-root.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "draw",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ d: string; mid: { x: number; y: number } }"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "edge",
+                  "type": {
+                    "text": "CanvasEdge"
+                  }
+                },
+                {
+                  "name": "from",
+                  "type": {
+                    "text": "CanvasNode"
+                  }
+                },
+                {
+                  "name": "to",
+                  "type": {
+                    "text": "CanvasNode"
+                  }
+                },
+                {
+                  "name": "path",
+                  "type": {
+                    "text": "CanvasPath"
+                  }
+                },
+                {
+                  "name": "drawnHeads",
+                  "type": {
+                    "text": "{ start: boolean; end: boolean }"
+                  }
+                }
+              ],
+              "description": "One connection's line, by `edgeRoute` where it draws one, and by the board's own where not.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "cardOf",
@@ -24032,6 +24115,60 @@
                 "module": "src/canvas/root/canvas-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "onScreen",
+              "type": {
+                "text": "{ x: number; y: number; width: number; height: number }"
+              },
+              "privacy": "private",
+              "description": "The part of the document on screen, in its own units.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "minimapArea",
+              "type": {
+                "text": "{ x: number; y: number; width: number; height: number }"
+              },
+              "privacy": "private",
+              "description": "What the minimap shows: every card and what is on screen, with room around them.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "handleMinimapPointer",
+              "privacy": "private",
+              "readonly": true,
+              "description": "A press or a drag on the minimap, which brings the place under it to the\nmiddle of the view.\n\n**The point is read through the picture's own scale**: the area is drawn\nwhole and centered in the box, so the box's spare width or height is split\neither side of it.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "renderMinimap",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The minimap, under `controls=\"minimap\"`: each card as a box, and a frame\naround what is on screen.\n\n**A picture for a pointer**, hidden from screen readers and taking no\nfocus, as a map's own overview is: the arrow keys and `show()` already take\na keyboard to any card, and a second way that says nothing a reader can\nuse would be a stop that does nothing.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -24978,6 +25115,10 @@
                 "description": "A flowchart with a pill to start, boxes for steps, a diamond for the decision, and a circle to end, joined at right angles.",
                 "slug": "flowchart"
               },
+              {
+                "description": "A board with a minimap in its corner. A press or a drag on the minimap moves the view there.",
+                "slug": "minimap"
+              },
               {
                 "description": "A read-only board for publishing. Every card stays where its author put it, and every connection turns at right angles.",
                 "slug": "read-only"
@@ -25222,6 +25363,30 @@
                 "module": "src/canvas/root/canvas-root.ts"
               }
             },
+            {
+              "description": "The picture of the whole board, under `controls=\"minimap\"`.",
+              "name": "minimap",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
+            {
+              "description": "One card in the minimap.",
+              "name": "minimap-node",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
+            {
+              "description": "The frame in the minimap around what is on screen.",
+              "name": "minimap-view",
+              "inheritedFrom": {
+                "name": "HelixHeadlessCanvas",
+                "module": "src/canvas/root/canvas-root.ts"
+              }
+            },
             {
               "description": "The button that moves the board down.",
               "name": "pan-down",
@@ -32965,7 +33130,43 @@
                   }
                 }
               ],
-              "description": "Moves focus to turn `at`, drawing it first where the transcript is\nwindowed and it is not drawn.\n\n**A turn takes focus only once a reader moves to it**, so the\n`tabindex=\"-1\"` a turn written as a child needs is written then, long\nafter any server's markup has hydrated, and never on a turn nobody moved\nto.",
+              "description": "Moves focus to turn `at`, drawing it first where the transcript is\nwindowed and it is not drawn.\n\n**A turn takes focus only once a reader moves to it**, so the `tabindex`\nit needs is written then, long after any server's markup has hydrated,\nand never on a turn nobody moved to.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessChat",
+                "module": "src/chat/root/chat-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "stop",
+              "type": {
+                "text": "HTMLElement | undefined"
+              },
+              "privacy": "private",
+              "description": "The turn that is a tab stop because a reader moved to it.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessChat",
+                "module": "src/chat/root/chat-root.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "visit",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "turn",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ],
+              "description": "Focuses a turn, making it the transcript's one stop a reader moved to.\n\n**`0`, and never `-1`.** Chromium leaves the whole of a shadow host at a\nnegative `tabindex` out of the Tab order, its own controls and what is\nslotted into it alike, so a turn at `-1` lost its links and its Try again\nonce a reader had paged through it. The stop moves with the reader, and a\n`tabindex` you wrote on a turn is left as it is.",
               "inheritedFrom": {
                 "name": "HelixHeadlessChat",
                 "module": "src/chat/root/chat-root.ts"
@@ -124731,6 +124932,17 @@
                 "module": "src/map/root/map-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "handleMenuFocusOut",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Closes the layers menu when focus moves on from its button and the menu,\nas a Tab past the last tile does. Focus leaving the page, with nothing\nfocused in its place, leaves the menu as it is.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessMap",
+                "module": "src/map/root/map-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleMenuKeydown",
@@ -129925,7 +130137,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` implies it, so a row that is on never has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
+              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` and `exclusive` imply it, so a row that is on, or one of a set,\nnever has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
               "attribute": "checkable",
               "reflects": true,
               "inheritedFrom": {
@@ -129947,6 +130159,19 @@
                 "module": "src/menu/item/menu-item.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "closeOnSelect",
+              "type": {
+                "text": "boolean | undefined"
+              },
+              "description": "Whether choosing the row closes the menu.\n\nUnset takes the menu's `close-on-select`, which is on, and keeps the menu\nopen after a Space on a choice row. Write `close-on-select=\"false\"` for a\nrow that changes something the reader is watching, such as a zoom step.",
+              "attribute": "close-on-select",
+              "inheritedFrom": {
+                "name": "HelixHeadlessMenuItem",
+                "module": "src/menu/item/menu-item.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "disabled",
@@ -129983,7 +130208,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nMeaningless without `checkable`, since a row that cannot be ticked is not\none of a set of anything.",
+              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nIt makes the row a choice, so it needs no `checkable` beside it.",
               "attribute": "exclusive",
               "reflects": true,
               "inheritedFrom": {
@@ -130346,6 +130571,13 @@
                   "text": "void"
                 }
               },
+              "parameters": [
+                {
+                  "name": "space",
+                  "default": "false"
+                }
+              ],
+              "description": "Chooses the row. `space` is whether a Space chose it, which keeps the menu\nopen on a choice row unless the row says otherwise.",
               "inheritedFrom": {
                 "name": "HelixHeadlessMenuItem",
                 "module": "src/menu/item/menu-item.ts"
@@ -130361,6 +130593,20 @@
                 "module": "src/menu/item/menu-item.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "spacePressed",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the click on its way is the one a Space on a linked row sent.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessMenuItem",
+                "module": "src/menu/item/menu-item.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "handleKeydown",
@@ -130879,7 +131125,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` implies it, so a row that is on never has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
+              "description": "Whether the row is one of a set of choices.\n\nSeparate from `checked`, and it has to be. A row that is off is still a\nchoice, and `checked` alone cannot say so: an unticked row and a row that\nwas never tickable look identical from here. Announcing only the ticked one\nas a checkbox tells a reader its siblings are commands, which is the one\nthing they are not.\n\n`checked` and `exclusive` imply it, so a row that is on, or one of a set,\nnever has to say both.\n\nChoosing the row checks or unchecks it, after a `helix-before-toggle` that\nyou can cancel.",
               "fieldName": "checkable",
               "inheritedFrom": {
                 "name": "HelixHeadlessMenuItem",
@@ -130899,6 +131145,18 @@
                 "module": "src/menu/item/menu-item.ts"
               }
             },
+            {
+              "name": "close-on-select",
+              "type": {
+                "text": "boolean | undefined"
+              },
+              "description": "Whether choosing the row closes the menu.\n\nUnset takes the menu's `close-on-select`, which is on, and keeps the menu\nopen after a Space on a choice row. Write `close-on-select=\"false\"` for a\nrow that changes something the reader is watching, such as a zoom step.",
+              "fieldName": "closeOnSelect",
+              "inheritedFrom": {
+                "name": "HelixHeadlessMenuItem",
+                "module": "src/menu/item/menu-item.ts"
+              }
+            },
             {
               "name": "disabled",
               "type": {
@@ -130931,7 +131189,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nMeaningless without `checkable`, since a row that cannot be ticked is not\none of a set of anything.",
+              "description": "Whether only one row in its set can be checked at a time.\n\nThe set is the run of `exclusive` rows next to this one, up to the first\nelement that is not one, such as a divider. Choosing a row in it checks\nthat row and unchecks the others. Choosing the row that is checked leaves\nit checked. `menuitemradio` tells a reader which kind of set they are in,\nwhere `menuitemcheckbox` says every row is independent.\n\nIt makes the row a choice, so it needs no `checkable` beside it.",
               "fieldName": "exclusive",
               "inheritedFrom": {
                 "name": "HelixHeadlessMenuItem",
@@ -131517,6 +131775,20 @@
                 "module": "src/menu/root/menu-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "closeOnSelect",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Whether choosing a row closes the menu.\n\nOn by default, and a Space on a choice row leaves the menu open either way.\nWrite `close-on-select=\"false\"` to keep the menu open after every choice, as\nArk UI's `closeOnSelect` does. A row's own `close-on-select` wins over this.",
+              "attribute": "close-on-select",
+              "inheritedFrom": {
+                "name": "HelixHeadlessMenu",
+                "module": "src/menu/root/menu-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "context",
@@ -132874,6 +133146,19 @@
                 "module": "src/menu/root/menu-root.ts"
               }
             },
+            {
+              "name": "close-on-select",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Whether choosing a row closes the menu.\n\nOn by default, and a Space on a choice row leaves the menu open either way.\nWrite `close-on-select=\"false\"` to keep the menu open after every choice, as\nArk UI's `closeOnSelect` does. A row's own `close-on-select` wins over this.",
+              "fieldName": "closeOnSelect",
+              "inheritedFrom": {
+                "name": "HelixHeadlessMenu",
+                "module": "src/menu/root/menu-root.ts"
+              }
+            },
             {
               "name": "context",
               "type": {
@@ -164979,12 +165264,28 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A sandboxed `<iframe>` that loads `src`, a document you provide. That\ndocument imports what the examples need, listens for a render message, and\nwrites the markup into itself.\n\n**Without `src`, the frame loads a built-in document**, so a sandbox renders\nwith nothing to host. It runs HTML, CSS, and scripts, and reports the\nconsole, uncaught errors, its height, and presses as a frame on\n`servePreview` does. It defines no element, so an example that uses Helix\ncomponents needs a `src` that imports them.\n\n**Examples render in a frame**, so an example's styles and scripts do not\naffect the page around the sandbox, and `position: fixed` stays inside the\npane. The frame starts empty, with its own stylesheets and its own custom\nelement registry, so `src` must load the styles and components the examples\nuse.\n\n**The source is untrusted, and the frame keeps it isolated.** The frame uses\n`sandbox=\"allow-scripts\"` and never `allow-same-origin`. Together, the two\nlet a document on the same origin remove its own sandbox, which is the same\nas having none.\n\n**A preview says where it is.** It is `:state(loading)` from the moment it\nhas a `src` until that document can take the example, and again through\n`reload()`. It is `:state(failed)` once the example throws an error it does\nnot catch, until the next source is sent, which a frame on `servePreview`\nreports. A page draws its own spinner or message from either, such as a\nsibling shown by `helix-sandbox-preview:state(failed) + .message`.",
+          "description": "A sandboxed `<iframe>` that loads `src`, a document you provide. That\ndocument imports what the examples need, listens for a render message, and\nwrites the markup into itself.\n\n**Without `src`, the frame loads a built-in document**, so a sandbox renders\nwith nothing to host. It runs HTML, CSS, and scripts, and reports the\nconsole, uncaught errors, its height, and presses as a frame on\n`servePreview` does. It defines no element, so an example that uses Helix\ncomponents needs a `src` that imports them.\n\n**Examples render in a frame**, so an example's styles and scripts do not\naffect the page around the sandbox, and `position: fixed` stays inside the\npane. The frame starts empty, with its own stylesheets and its own custom\nelement registry, so `src` must load the styles and components the examples\nuse.\n\n**The source is untrusted, and the frame keeps it isolated.** The frame uses\n`sandbox=\"allow-scripts\"` and never `allow-same-origin`. Together, the two\nlet a document on the same origin remove its own sandbox, which is the same\nas having none.\n\n**A preview says where it is.** It is `:state(loading)` from the moment it\nhas a `src` until that document can take the example, and again through\n`reload()`. It is `:state(failed)` once the example throws an error it does\nnot catch, until the next source is sent, which a frame on `servePreview`\nreports. A page draws its own spinner or message from either, such as a\nsibling shown by `helix-sandbox-preview:state(failed) + .message`.\n\n**A failed preview shows the error over the example**, in the `error` part,\nuntil the next source is sent. The terminal says it too, so the part is not\nannounced. Hide it with `::part(error) { display: none }` where the page\ndraws its own.\n\n**`controls` draws two buttons in the preview's corner**: one reloads the\nframe's document, as `reload()` does, and one opens the example in a new\ntab, as `open()` does. The tab runs it in a frame sandboxed as this one is.",
           "name": "HelixSandboxPreview",
           "cssParts": [
+            {
+              "description": "The buttons in the preview's corner, under `controls`.",
+              "name": "controls"
+            },
+            {
+              "description": "The error the example threw and did not catch, shown over it while the preview is `failed`.",
+              "name": "error"
+            },
             {
               "description": "The iframe.",
               "name": "frame"
+            },
+            {
+              "description": "The button that opens the example in a new tab, under `controls`.",
+              "name": "open"
+            },
+            {
+              "description": "The button that reloads the frame's document, under `controls`.",
+              "name": "reload"
             }
           ],
           "members": [
@@ -165007,6 +165308,17 @@
               "description": "The color mode the frame renders in.\n\n**The frame is a document and a document has its own color mode.** Setting\n`data-color-mode` on this element styles this element, and the contents of\nan iframe inherit nothing from it: measured, a frame under a host carrying\nthe attribute had it unset on its own root. Left alone the frame follows\n`prefers-color-scheme`, which is right for a preview that should look like\nthe reader's own machine, and wrong for one whose tool has a scheme control.\n\nIt matters more than a background: `light-dark()` is compiled to a shim\nkeyed on this attribute, and of the 56 tokens that differ by scheme the\ntheme engine emits 19. The other 37 would stay light in a dark preview,\nincluding every one of the 24 series colors a chart reads.",
               "attribute": "color-mode"
             },
+            {
+              "kind": "field",
+              "name": "controls",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the preview draws a reload button and a button that opens the\nexample in a new tab, in its corner.",
+              "attribute": "controls",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "direction",
@@ -165038,6 +165350,32 @@
               "description": "How the example is placed in the frame.\n\n`padded` insets it and leaves it at the top, which is the resting case and\nwhat an absent value sends. `centered` gives it a measure and centers that\nbox in the frame. `hug` shrinks the example to its own content and centers\nwhat is left, which is the difference that matters for a component whose\nroot is a full-width block. `fullscreen` is the whole frame with no inset.\n\nNot reflected, for `direction`'s reason: the placement is applied by the\ndocument inside the frame, against its own root, so no rule on this side\ncould read it.",
               "attribute": "layout"
             },
+            {
+              "kind": "field",
+              "name": "openLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Open preview in a new tab'",
+              "description": "The name of the button that opens the example in a new tab, under\n`controls`.",
+              "attribute": "open-label",
+              "helix": {
+                "words": true
+              }
+            },
+            {
+              "kind": "field",
+              "name": "reloadLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Reload preview'",
+              "description": "The name of the button that reloads the frame's document, under\n`controls`.",
+              "attribute": "reload-label",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "script",
@@ -165096,6 +165434,35 @@
               "privacy": "private",
               "description": "The source the frame held when it last reported an uncaught error."
             },
+            {
+              "kind": "field",
+              "name": "failure",
+              "type": {
+                "text": "string | undefined"
+              },
+              "privacy": "private",
+              "description": "What the example threw and did not catch, while the preview is `failed`."
+            },
+            {
+              "kind": "method",
+              "name": "fail",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "text",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Says the preview failed with `text`, or, with none, that it has not."
+            },
             {
               "kind": "field",
               "name": "sending",
@@ -165160,6 +165527,16 @@
               },
               "description": "Sends once the typing stops, replacing anything already waiting.\n\nA frame is the wrong unit. Keystrokes arrive fifty to a hundred and fifty\nmilliseconds apart, so each one lands in a frame of its own and coalescing\nby frame coalesces nothing, leaving the example rebuilt per character. The\ndelay has to be longer than the gap between keystrokes to catch a burst, and\nshort enough to read as immediate when the typing stops."
             },
+            {
+              "kind": "field",
+              "name": "message",
+              "type": {
+                "text": "PreviewRender"
+              },
+              "privacy": "private",
+              "description": "What the frame is sent: the source, its stylesheet and its settings.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "send",
@@ -165171,6 +165548,19 @@
               },
               "description": "Sends the current source to the frame, once it is listening."
             },
+            {
+              "kind": "method",
+              "name": "open",
+              "return": {
+                "type": {
+                  "text": "Window | null"
+                }
+              },
+              "description": "Opens the example in a new tab, and returns the tab's window, or `null`\nwhere the browser refused to open one.\n\n**The tab runs the example as this preview does**: in a frame that fills\nit, with this frame's `sandbox`, loading `src` or the built-in document,\nand sent the example once it loads. The example stays on an opaque origin,\nand the tab's `opener` is cleared, so it cannot reach this page. The tab\nshows the example as it was when it opened, and edits after that do not\nreach it. A short inline script in the tab sends the example, so on a page\nwhose Content Security Policy refuses inline scripts the tab opens empty,\nas the built-in document does there.",
+              "type": {
+                "text": "open() => Window | null"
+              }
+            },
             {
               "kind": "method",
               "name": "reload",
@@ -165195,6 +165585,17 @@
               },
               "description": "A new document is on its way, so nothing is sent until it listens, and\nnothing has failed in it. The built-in document loads too."
             },
+            {
+              "kind": "method",
+              "name": "renderControls",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The reload and open buttons, under `controls`."
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -165562,6 +165963,15 @@
               "description": "The color mode the frame renders in.\n\n**The frame is a document and a document has its own color mode.** Setting\n`data-color-mode` on this element styles this element, and the contents of\nan iframe inherit nothing from it: measured, a frame under a host carrying\nthe attribute had it unset on its own root. Left alone the frame follows\n`prefers-color-scheme`, which is right for a preview that should look like\nthe reader's own machine, and wrong for one whose tool has a scheme control.\n\nIt matters more than a background: `light-dark()` is compiled to a shim\nkeyed on this attribute, and of the 56 tokens that differ by scheme the\ntheme engine emits 19. The other 37 would stay light in a dark preview,\nincluding every one of the 24 series colors a chart reads.",
               "fieldName": "colorMode"
             },
+            {
+              "name": "controls",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the preview draws a reload button and a button that opens the\nexample in a new tab, in its corner.",
+              "fieldName": "controls"
+            },
             {
               "name": "direction",
               "type": {
@@ -165587,6 +165997,24 @@
               "description": "How the example is placed in the frame.\n\n`padded` insets it and leaves it at the top, which is the resting case and\nwhat an absent value sends. `centered` gives it a measure and centers that\nbox in the frame. `hug` shrinks the example to its own content and centers\nwhat is left, which is the difference that matters for a component whose\nroot is a full-width block. `fullscreen` is the whole frame with no inset.\n\nNot reflected, for `direction`'s reason: the placement is applied by the\ndocument inside the frame, against its own root, so no rule on this side\ncould read it.",
               "fieldName": "layout"
             },
+            {
+              "name": "open-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Open preview in a new tab'",
+              "description": "The name of the button that opens the example in a new tab, under\n`controls`.",
+              "fieldName": "openLabel"
+            },
+            {
+              "name": "reload-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Reload preview'",
+              "description": "The name of the button that reloads the frame's document, under\n`controls`.",
+              "fieldName": "reloadLabel"
+            },
             {
               "name": "script",
               "type": {
@@ -165710,7 +166138,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A source pane dispatches `helix-before-edit`, which bubbles, and the sandbox\npasses the value to the preview slotted into it. The source pane and the\npreview do not reference each other, so you can replace either one or use it\nalone.\n\nThe event carries the pane's `name`, so one sandbox can hold several panes.\n`html` sets the preview's markup, `css` sets its stylesheet, and `js` sets\na script that runs as a module after the markup. The sandbox ignores a pane\nwith any other name, so that pane can show content without changing the\npreview.\n\n**The dividers are two nested `helix-splitter` elements**, which handle the\npointer, the keyboard, and the corner. The inner splitter holds the panes and\nthe outer one holds the panel, so the panel spans the full width.\n\nOn a focused divider, the arrow keys move it, and `Home` and `End` move it\nto its ends. `Enter` on the panes divider shuts the lead pane, and pressed\nagain it opens the pane where it was. `Enter` on the panel divider shuts the\npanel to `panel-collapsed-size`, and pressed again it opens the panel to its\nlast height.",
+          "description": "A source pane dispatches `helix-before-edit`, which bubbles, and the sandbox\npasses the value to the preview slotted into it. The source pane and the\npreview do not reference each other, so you can replace either one or use it\nalone.\n\nThe event carries the pane's `name`, so one sandbox can hold several panes.\n`html` sets the preview's markup, `css` sets its stylesheet, and `js` sets\na script that runs as a module after the markup. The sandbox ignores a pane\nwith any other name, so that pane can show content without changing the\npreview.\n\n**The dividers are two nested `helix-splitter` elements**, which handle the\npointer, the keyboard, and the corner. The inner splitter holds the panes and\nthe outer one holds the panel, so the panel spans the full width.\n\n**Several source panes are files**, one shown at a time under a row of\ntabs, each named by the pane's `label` or, without one, its `name`. `file`\nholds the `name` of the pane shown. The tabs are a tab list: the arrow keys\nmove between them and show each pane, and `Home` and `End` go to the first\nand the last. Choosing one sends `helix-before-change` with the pane's\n`name`, which you can cancel, and `change` once `file` holds it. The panes\nnot shown carry `hidden`. One pane draws no tabs.\n\n**Any editor can be the source pane**: an element in the `source` slot with\na `name` that dispatches `helix-before-edit` with its text, which bubbles.\nA wrapper around CodeMirror or Monaco sends one on each change and is a pane\nlike `helix-sandbox-source`, and the sandbox reads its `value` to seed the\npreview. Dispatch `helix-caret` from it too for the status bar's position.\n\nOn a focused divider, the arrow keys move it, and `Home` and `End` move it\nto its ends. `Enter` on the panes divider shuts the lead pane, and pressed\nagain it opens the pane where it was. `Enter` on the panel divider shuts the\npanel to `panel-collapsed-size`, and pressed again it opens the panel to its\nlast height.",
           "name": "HelixSandbox",
           "cssProperties": [
             {
@@ -165735,6 +166163,14 @@
               "description": "The handle where the two dividers cross.",
               "name": "corner"
             },
+            {
+              "description": "One file tab, `aria-selected` while its pane is shown.",
+              "name": "file"
+            },
+            {
+              "description": "The file tabs over the source panes, where there are several.",
+              "name": "files"
+            },
             {
               "description": "Either pane.",
               "name": "pane"
@@ -165818,6 +166254,28 @@
                 "text": "number"
               }
             },
+            {
+              "kind": "field",
+              "name": "file",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The `name` of the source pane shown, where the sandbox holds several.\n\nUnset, or a name no pane has, shows the first.",
+              "attribute": "file"
+            },
+            {
+              "kind": "field",
+              "name": "filesLabel",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Files'",
+              "description": "The name of the file tabs, read by screen readers.",
+              "attribute": "files-label",
+              "helix": {
+                "words": true
+              }
+            },
             {
               "kind": "field",
               "name": "lead",
@@ -165903,6 +166361,93 @@
               "default": "false",
               "description": "Whether anything is in the panel region.\n\nThe divider above the panel is only meaningful when there is a panel to\nsize, and there is no way to ask in CSS: `:host(:has([slot=\"panel\"]))` is\ninvalid, and the server has no children to look at. `slotchange` is the\nplatform answering on the client, which is where a divider is any use."
             },
+            {
+              "kind": "field",
+              "name": "files",
+              "type": {
+                "text": "Element[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The source panes where there are several, each a file with a tab."
+            },
+            {
+              "kind": "field",
+              "name": "hid",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Set<Element>()",
+              "description": "The panes this element wrote `hidden` on, to take it off again."
+            },
+            {
+              "kind": "field",
+              "name": "shownFile",
+              "type": {
+                "text": "Element | undefined"
+              },
+              "privacy": "private",
+              "description": "The pane shown among the files.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "readFiles",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Notes the source panes, which are files where there are several."
+            },
+            {
+              "kind": "method",
+              "name": "chooseFile",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "pane",
+                  "type": {
+                    "text": "Element"
+                  }
+                }
+              ],
+              "description": "Shows the pane a file tab names, once nobody refused."
+            },
+            {
+              "kind": "field",
+              "name": "handleFileKey",
+              "privacy": "private",
+              "readonly": true,
+              "description": "Arrow keys, `Home` and `End` on the file tabs, which move to a tab and\nshow its pane, as a tab list that follows focus does. Left and Right swap\non a right-to-left page."
+            },
+            {
+              "kind": "method",
+              "name": "renderFiles",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult | typeof nothing"
+                }
+              },
+              "description": "The row of file tabs, where there are several source panes."
+            },
+            {
+              "kind": "method",
+              "name": "showFile",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Hides the files not shown, and shows any this element hid that is now."
+            },
             {
               "kind": "field",
               "name": "bodyHeight",
@@ -166302,6 +166847,31 @@
               "readonly": true,
               "description": "Notes whether there is a panel, which is what its dividers depend on.\n\nAsked of the light DOM rather than of the slot. `slotchange` is the event\nthat says it changed, and it is listened for, but it is not the only way\nto know: a sandbox whose panel was in the markup all along has nothing to\nchange, and an environment that does not dispatch the event at all leaves\nthe dividers permanently absent. What is slotted into a named slot is a\nquestion the host can answer directly."
             },
+            {
+              "kind": "method",
+              "name": "renderPane",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "'preview' | 'source'"
+                  }
+                },
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "'end' | 'start'"
+                  }
+                }
+              ],
+              "description": "One pane and the slot it shows. The source pane holds the file tabs, where\nthere are several, and is then the panel they control."
+            },
             {
               "kind": "field",
               "name": "tier",
@@ -166643,6 +167213,22 @@
             }
           ],
           "events": [
+            {
+              "type": {
+                "text": "Event"
+              },
+              "description": "A file tab showed its pane, whose `name` `file` now holds.",
+              "name": "change",
+              "reactProp": "onchange"
+            },
+            {
+              "type": {
+                "text": "HelixBeforeChangeEvent"
+              },
+              "description": "Fired before a file tab shows its pane, with the pane's `name`. Cancelable: cancel it to keep the pane shown.",
+              "name": "helix-before-change",
+              "reactProp": "onhelix-before-change"
+            },
             {
               "type": {
                 "text": "HelixBeforeEditEvent"
@@ -166738,6 +167324,23 @@
               "description": "Where a reset puts the divider between the panes.\n\nSeparate from `split` for the reason `Splitter` keeps `default-position`\nseparate from `position`. Resetting to whatever `split` held on the first\nrender is the declared arrangement only where nobody owns the property: the\nworkbench does, and restores it from the address bar and from storage, so the\nfirst value it holds is the reader's last session and a reset puts the\nsandbox back to the size it already was.\n\nDeclared rather than captured, so it is a number a consumer states and can\nchange, and it needs no first frame to be read on.",
               "fieldName": "defaultSplit"
             },
+            {
+              "name": "file",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The `name` of the source pane shown, where the sandbox holds several.\n\nUnset, or a name no pane has, shows the first.",
+              "fieldName": "file"
+            },
+            {
+              "name": "files-label",
+              "type": {
+                "text": "string"
+              },
+              "default": "'Files'",
+              "description": "The name of the file tabs, read by screen readers.",
+              "fieldName": "filesLabel"
+            },
             {
               "name": "lead",
               "type": {
@@ -166841,6 +167444,10 @@
                 "min": 420,
                 "slug": "events"
               },
+              {
+                "description": "Several source panes as files under a row of tabs, and a preview with reload and open buttons.",
+                "slug": "files"
+              },
               {
                 "description": "A source pane colored by a highlighter you bring.",
                 "slug": "highlighted-source"
@@ -167010,6 +167617,16 @@
                 "words": true
               }
             },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The pane's file name, such as `index.html`, on its tab where a sandbox\nholds several panes. Empty puts the pane's `name` on the tab.",
+              "attribute": "label"
+            },
             {
               "kind": "field",
               "name": "name",
@@ -167518,6 +168135,15 @@
               "description": "The field's description, read by screen readers while Tab indents.",
               "fieldName": "keysDescription"
             },
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "default": "''",
+              "description": "The pane's file name, such as `index.html`, on its tab where a sandbox\nholds several panes. Empty puts the pane's `name` on the tab.",
+              "fieldName": "label"
+            },
             {
               "name": "name",
               "type": {
@@ -187420,7 +188046,7 @@
                 "text": "number"
               },
               "privacy": "private",
-              "description": "The index of the stage the reader is on, or `-1`.",
+              "description": "The index of the stage the reader is on, or `-1`.\n\nRead from `active` once anything has set it, because a move writes\n`active` at once and each step's `current` only on the next update: two\ncalls to `next()` in one task then move two stages.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "HelixHeadlessSteps",
@@ -241002,6 +241628,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix",
-    "version": "0.162.1"
+    "version": "0.163.0"
   }
 }