@fusion.dev/helix-headless 0.204.1 → 0.205.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.204.1",
+  "version": "0.205.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -53,14 +53,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.204.1",
-    "@fusion.dev/helix-icons": "0.204.1",
+    "@fusion.dev/helix-core": "0.205.0",
+    "@fusion.dev/helix-icons": "0.205.0",
     "tslib": "^2.8.1",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.204.1",
-    "@fusion.dev/helix-testing": "0.204.1",
+    "@fusion.dev/helix-cem": "0.205.0",
+    "@fusion.dev/helix-testing": "0.205.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.14.5",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -19901,6 +19901,11 @@ true would write the attribute on upgrade. */
   pinned?: (HelixHeadlessLog["pinned"]) | undefined;
   /** Text a line has to hold to be shown, ignoring case. Empty shows every line. */
   query?: (HelixHeadlessLog["query"]) | undefined;
+  /** Whether the log says nothing to a screen reader as lines arrive, steps
+finish, or the run ends. For a log inside something that speaks for it,
+such as an agent's work in a chat turn, which the turn announces once it
+settles. */
+  quiet?: (HelixHeadlessLog["quiet"]) | undefined;
   /** The words on the button that returns to the newest line, where `resume` is empty. */
   "resume-label"?: (HelixHeadlessLog["resumeLabel"]) | undefined;
   /** The words on the button that returns to the newest line, where `resume` is empty. */
@@ -20051,6 +20056,11 @@ true would write the attribute on upgrade. */
   "prop:pinned"?: (HelixHeadlessLog["pinned"]) | undefined;
   /** Text a line has to hold to be shown, ignoring case. Empty shows every line. */
   "prop:query"?: (HelixHeadlessLog["query"]) | undefined;
+  /** Whether the log says nothing to a screen reader as lines arrive, steps
+finish, or the run ends. For a log inside something that speaks for it,
+such as an agent's work in a chat turn, which the turn announces once it
+settles. */
+  "prop:quiet"?: (HelixHeadlessLog["quiet"]) | undefined;
   /** The words on the button that returns to the newest line, where `resume` is empty. */
   "attr:resume-label"?: (HelixHeadlessLog["resumeLabel"]) | undefined;
   /** The words on the button that returns to the newest line, where `resume` is empty. */
@@ -43739,6 +43749,12 @@ export type CustomElements = {
    * a page in another language sets them once there. The time moves on by
    * itself, so "now" becomes "1 minute ago" while the page is open.
    *
+   * **An agent's work goes in `work`, and its answer in the content.** The work,
+   * its thinking, the commands it ran and what they printed, is a record read
+   * the way a log is, so a `Log` with `separation="plain"` and `quiet` sits there
+   * above the answer. The chat says the turn once it settles, from the content
+   * alone, so the work is never read aloud as part of the answer.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
@@ -43807,6 +43823,7 @@ export type CustomElements = {
    * - `avatar`: The author's avatar.
    * - `indicator`: The indicator shown before the first token arrives. Defaults to the typing indicator.
    * - `sources`: The turn's sources, such as citations, documents, or a retrieved page.
+   * - `work`: What an agent did to arrive at the turn, such as a `Log` of its steps, above the content. A screen reader hears the turn without it.
    *
    * ## CSS Parts
    *
@@ -43824,6 +43841,7 @@ export type CustomElements = {
    * - `sources`: The turn's sources, under it and outside the bubble.
    * - `state`: The text that names the turn's state, when there is one to show.
    * - `time`: The turn's time.
+   * - `work`: The box around the `work` slot, above the content.
    *
    * ## CSS States
    *
@@ -44091,6 +44109,7 @@ export type CustomElements = {
    * - `message-sources`: The sources of a turn from `turns`.
    * - `message-state`: The state text of a turn from `turns`, when there is one to show.
    * - `message-time`: The time of a turn from `turns`.
+   * - `message-work`: The box around a turn's `work`, for a turn from `turns`, which has none.
    * - `resume`: The control shown while the user is scrolled away from the bottom.
    * - `resume-button`: The button the `resume` region shows when nothing is slotted into it.
    * - `resume-mark`: The arrow on the default `resume-button`.
@@ -54828,6 +54847,7 @@ export type CustomElements = {
    * - `line`: The row the number, the time, and the text sit in.
    * - `line-debug`: The row of a line at `debug`.
    * - `line-error`: The row of a line at `error`.
+   * - `line-grouped`: The row of a line that belongs to a step, which the styled tier insets under the step's heading where there is no number.
    * - `line-marked`: The row of a line `mark-lines` names on the log.
    * - `line-selected`: The row of a line in the log's selection.
    * - `line-warn`: The row of a line at `warn`.
@@ -54911,7 +54931,9 @@ export type CustomElements = {
    * arrive, since reading a build aloud line by line helps nobody. A separate
    * status region says each line at `error` once it arrives, each step once it
    * finishes or fails, and the end of the run once `done` is set or `source`
-   * ends. Set `done` yourself when output you `write` is complete.
+   * ends. Set `done` yourself when output you `write` is complete. Set `quiet`
+   * where something around the log speaks for it, as a chat turn does for an
+   * agent's work.
    *
    * The log scrolls on this tier. It carries `data-scroller`, so following the
    * newest line and drawing a window work with no stylesheet. Give the log a
@@ -54960,6 +54982,10 @@ export type CustomElements = {
    * reflected, for the reason `Chat` gives at its own `pinned`: a default of
    * true would write the attribute on upgrade.
    * - `query`: Text a line has to hold to be shown, ignoring case. Empty shows every line.
+   * - `quiet`: Whether the log says nothing to a screen reader as lines arrive, steps
+   * finish, or the run ends. For a log inside something that speaks for it,
+   * such as an agent's work in a chat turn, which the turn announces once it
+   * settles.
    * - `resume-label`/`resumeLabel`: The words on the button that returns to the newest line, where `resume` is empty.
    * - `selectable`: Whether pressing a line's number selects the line, and pressing another
    * with Shift selects every line between them. Each number is then a
@@ -55094,6 +55120,7 @@ export type CustomElements = {
    * - `line`: The row of a line drawn from data.
    * - `line-debug`: The row of a line drawn from data at `debug`.
    * - `line-error`: The row of a line drawn from data at `error`.
+   * - `line-grouped`: The row of a line drawn from data that belongs to a step.
    * - `line-marked`: The row of a line drawn from data that `mark-lines` names.
    * - `line-match`: Text in a line drawn from data that matches `query`.
    * - `line-number`: The number of a line drawn from data.
@@ -75981,6 +76008,12 @@ export type CustomElementsSolidJs = {
    * a page in another language sets them once there. The time moves on by
    * itself, so "now" becomes "1 minute ago" while the page is open.
    *
+   * **An agent's work goes in `work`, and its answer in the content.** The work,
+   * its thinking, the commands it ran and what they printed, is a record read
+   * the way a log is, so a `Log` with `separation="plain"` and `quiet` sits there
+   * above the answer. The chat says the turn once it settles, from the content
+   * alone, so the work is never read aloud as part of the answer.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
@@ -76049,6 +76082,7 @@ export type CustomElementsSolidJs = {
    * - `avatar`: The author's avatar.
    * - `indicator`: The indicator shown before the first token arrives. Defaults to the typing indicator.
    * - `sources`: The turn's sources, such as citations, documents, or a retrieved page.
+   * - `work`: What an agent did to arrive at the turn, such as a `Log` of its steps, above the content. A screen reader hears the turn without it.
    *
    * ## CSS Parts
    *
@@ -76066,6 +76100,7 @@ export type CustomElementsSolidJs = {
    * - `sources`: The turn's sources, under it and outside the bubble.
    * - `state`: The text that names the turn's state, when there is one to show.
    * - `time`: The turn's time.
+   * - `work`: The box around the `work` slot, above the content.
    *
    * ## CSS States
    *
@@ -76334,6 +76369,7 @@ export type CustomElementsSolidJs = {
    * - `message-sources`: The sources of a turn from `turns`.
    * - `message-state`: The state text of a turn from `turns`, when there is one to show.
    * - `message-time`: The time of a turn from `turns`.
+   * - `message-work`: The box around a turn's `work`, for a turn from `turns`, which has none.
    * - `resume`: The control shown while the user is scrolled away from the bottom.
    * - `resume-button`: The button the `resume` region shows when nothing is slotted into it.
    * - `resume-mark`: The arrow on the default `resume-button`.
@@ -87172,6 +87208,7 @@ export type CustomElementsSolidJs = {
    * - `line`: The row the number, the time, and the text sit in.
    * - `line-debug`: The row of a line at `debug`.
    * - `line-error`: The row of a line at `error`.
+   * - `line-grouped`: The row of a line that belongs to a step, which the styled tier insets under the step's heading where there is no number.
    * - `line-marked`: The row of a line `mark-lines` names on the log.
    * - `line-selected`: The row of a line in the log's selection.
    * - `line-warn`: The row of a line at `warn`.
@@ -87258,7 +87295,9 @@ export type CustomElementsSolidJs = {
    * arrive, since reading a build aloud line by line helps nobody. A separate
    * status region says each line at `error` once it arrives, each step once it
    * finishes or fails, and the end of the run once `done` is set or `source`
-   * ends. Set `done` yourself when output you `write` is complete.
+   * ends. Set `done` yourself when output you `write` is complete. Set `quiet`
+   * where something around the log speaks for it, as a chat turn does for an
+   * agent's work.
    *
    * The log scrolls on this tier. It carries `data-scroller`, so following the
    * newest line and drawing a window work with no stylesheet. Give the log a
@@ -87307,6 +87346,10 @@ export type CustomElementsSolidJs = {
    * reflected, for the reason `Chat` gives at its own `pinned`: a default of
    * true would write the attribute on upgrade.
    * - `query`: Text a line has to hold to be shown, ignoring case. Empty shows every line.
+   * - `quiet`: Whether the log says nothing to a screen reader as lines arrive, steps
+   * finish, or the run ends. For a log inside something that speaks for it,
+   * such as an agent's work in a chat turn, which the turn announces once it
+   * settles.
    * - `resume-label`/`resumeLabel`: The words on the button that returns to the newest line, where `resume` is empty.
    * - `selectable`: Whether pressing a line's number selects the line, and pressing another
    * with Shift selects every line between them. Each number is then a
@@ -87441,6 +87484,7 @@ export type CustomElementsSolidJs = {
    * - `line`: The row of a line drawn from data.
    * - `line-debug`: The row of a line drawn from data at `debug`.
    * - `line-error`: The row of a line drawn from data at `error`.
+   * - `line-grouped`: The row of a line drawn from data that belongs to a step.
    * - `line-marked`: The row of a line drawn from data that `mark-lines` names.
    * - `line-match`: Text in a line drawn from data that matches `query`.
    * - `line-number`: The number of a line drawn from data.

package/types/vue.d.ts

@@ -10226,6 +10226,11 @@ true would write the attribute on upgrade. */
   pinned?: (HelixHeadlessLog["pinned"]) | undefined;
   /** Text a line has to hold to be shown, ignoring case. Empty shows every line. */
   query?: (HelixHeadlessLog["query"]) | undefined;
+  /** Whether the log says nothing to a screen reader as lines arrive, steps
+finish, or the run ends. For a log inside something that speaks for it,
+such as an agent's work in a chat turn, which the turn announces once it
+settles. */
+  quiet?: (HelixHeadlessLog["quiet"]) | undefined;
   /** The words on the button that returns to the newest line, where `resume` is empty. */
   "resume-label"?: (HelixHeadlessLog["resumeLabel"]) | undefined;
   /** The words on the button that returns to the newest line, where `resume` is empty. */
@@ -20754,7 +20759,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessChatComposerVueProps,
     HelixHeadlessChatComposerVueEvents
   >;
-  /** A chat message carries its state: sending, arrived, streaming, or failed. A failed message has a retry control in the message, which fires 'helix-send'.  'streaming' is the state the others are arranged around. A streaming message changes height on every frame, so it is marked 'aria-busy' while it arrives and announced once when it settles. A screen reader cannot follow a stream read out character by character.  A screen reader names the turn by its author and its time, such as "You, 2 minutes ago". The author is 'author-label', or "You" for 'me', or the 'author' itself where it is a name; give a turn by 'them' an 'author-label' to name it. The chat it sits in holds the sentence and the word for 'me', so a page in another language sets them once there. The time moves on by itself, so "now" becomes "1 minute ago" while the page is open. */
+  /** A chat message carries its state: sending, arrived, streaming, or failed. A failed message has a retry control in the message, which fires 'helix-send'.  'streaming' is the state the others are arranged around. A streaming message changes height on every frame, so it is marked 'aria-busy' while it arrives and announced once when it settles. A screen reader cannot follow a stream read out character by character.  A screen reader names the turn by its author and its time, such as "You, 2 minutes ago". The author is 'author-label', or "You" for 'me', or the 'author' itself where it is a name; give a turn by 'them' an 'author-label' to name it. The chat it sits in holds the sentence and the word for 'me', so a page in another language sets them once there. The time moves on by itself, so "now" becomes "1 minute ago" while the page is open.  **An agent's work goes in 'work', and its answer in the content.** The work, its thinking, the commands it ran and what they printed, is a record read the way a log is, so a 'Log' with 'separation="plain"' and 'quiet' sits there above the answer. The chat says the turn once it settles, from the content alone, so the work is never read aloud as part of the answer. */
   "helix-headless-chat-message": DefineCustomElement<
     HelixHeadlessChatMessage,
     HelixHeadlessChatMessageVueProps,
@@ -21036,7 +21041,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessLogLineVueProps,
     HelixHeadlessLogLineVueEvents
   >;
-  /** A log holds lines in the order they were written and keeps the reader at the newest one, until they scroll up to read. It stays where they left it while lines keep arriving, and a button returns them to the end ('resume-label', "Jump to latest").  **Lines arrive two ways.** For a log you serve whole, write 'Log.Line' elements as children, inside 'Log.Group' elements for the steps. For a log that is still being written, hand it text: 'write(chunk)' takes text as it arrives, in pieces that need not end at a line break, and 'source' takes a 'ReadableStream' or an async iterable and reads it to the end. 'lines' takes the lines as data. Text drawn from data is drawn one window at a time, so a log of a hundred thousand lines holds a screenful of elements, and the log needs a block size of its own. Do not use both ways at once.  **Written text is read the way a terminal shows it.** A carriage return starts the line over, so a progress bar stays one line, and the line still being written is shown as it stands. ANSI colors and weights are drawn, in the sixteen colors the styled tier takes from your theme, and every other escape code is dropped.  **Read a CI log's own markers with 'format'.** 'github-actions' reads the workflow commands a step writes, '::group::' and '::error::' among them, and the times at the start of a downloaded log. 'vercel' reads a Vercel build log's phases and its warnings. Each step opens as it starts, folds once it passes, stays open where it failed, and is timed from its lines. For any other log, give 'parse' a function that reads each finished line: it returns a level, a group, or 'open' and 'close' to start and end a step.  **Steps fold.** Lines that name a group in 'groups' stand under its heading, which shows its status and how long it took and opens and closes the lines. A group a reader opens or closes fires 'helix-expand' with every open group.  **Search with 'query'.** The log shows only the lines that hold it, marks each match, opens the groups that hold one, and says how many lines match.  'line-numbers' numbers the lines from the first ever written, so a number still names its line once 'limit' has let older lines go, and 'line-href' makes each number a link, such as '#L{n}'. 'scrollToLine(n)' takes a reader to one. 'timestamps' shows each line's 'at', on the clock or as the time into the run. 'mark-lines' marks lines, such as '12, 40-44'.  **'selectable' lets a reader select lines**, as a code host does: pressing a number selects its line, and pressing another with Shift selects every line between them. 'selected-lines' holds the selection, such as '12-20', and 'helix-select' asks before it changes. With a 'line-href' that is a fragment, the address follows the selection, '#L12' or '#L12-L20', and a page opened at one selects it and scrolls to it.  **The numbers are one tab stop.** Where they are links or buttons, Tab reaches the one a reader last used, or the first selected, and the arrow keys move between them, with Home and End for the first and the last. With Shift on a 'selectable' log, the selection follows.  **What a screen reader hears.** The log is a 'log' and stays quiet as lines arrive, since reading a build aloud line by line helps nobody. A separate status region says each line at 'error' once it arrives, each step once it finishes or fails, and the end of the run once 'done' is set or 'source' ends. Set 'done' yourself when output you 'write' is complete.  The log scrolls on this tier. It carries 'data-scroller', so following the newest line and drawing a window work with no stylesheet. Give the log a block size, such as 'helix-headless-log::part(log) { block-size: 20rem }'.  '''js import '@fusion.dev/helix/log' ''' */
+  /** A log holds lines in the order they were written and keeps the reader at the newest one, until they scroll up to read. It stays where they left it while lines keep arriving, and a button returns them to the end ('resume-label', "Jump to latest").  **Lines arrive two ways.** For a log you serve whole, write 'Log.Line' elements as children, inside 'Log.Group' elements for the steps. For a log that is still being written, hand it text: 'write(chunk)' takes text as it arrives, in pieces that need not end at a line break, and 'source' takes a 'ReadableStream' or an async iterable and reads it to the end. 'lines' takes the lines as data. Text drawn from data is drawn one window at a time, so a log of a hundred thousand lines holds a screenful of elements, and the log needs a block size of its own. Do not use both ways at once.  **Written text is read the way a terminal shows it.** A carriage return starts the line over, so a progress bar stays one line, and the line still being written is shown as it stands. ANSI colors and weights are drawn, in the sixteen colors the styled tier takes from your theme, and every other escape code is dropped.  **Read a CI log's own markers with 'format'.** 'github-actions' reads the workflow commands a step writes, '::group::' and '::error::' among them, and the times at the start of a downloaded log. 'vercel' reads a Vercel build log's phases and its warnings. Each step opens as it starts, folds once it passes, stays open where it failed, and is timed from its lines. For any other log, give 'parse' a function that reads each finished line: it returns a level, a group, or 'open' and 'close' to start and end a step.  **Steps fold.** Lines that name a group in 'groups' stand under its heading, which shows its status and how long it took and opens and closes the lines. A group a reader opens or closes fires 'helix-expand' with every open group.  **Search with 'query'.** The log shows only the lines that hold it, marks each match, opens the groups that hold one, and says how many lines match.  'line-numbers' numbers the lines from the first ever written, so a number still names its line once 'limit' has let older lines go, and 'line-href' makes each number a link, such as '#L{n}'. 'scrollToLine(n)' takes a reader to one. 'timestamps' shows each line's 'at', on the clock or as the time into the run. 'mark-lines' marks lines, such as '12, 40-44'.  **'selectable' lets a reader select lines**, as a code host does: pressing a number selects its line, and pressing another with Shift selects every line between them. 'selected-lines' holds the selection, such as '12-20', and 'helix-select' asks before it changes. With a 'line-href' that is a fragment, the address follows the selection, '#L12' or '#L12-L20', and a page opened at one selects it and scrolls to it.  **The numbers are one tab stop.** Where they are links or buttons, Tab reaches the one a reader last used, or the first selected, and the arrow keys move between them, with Home and End for the first and the last. With Shift on a 'selectable' log, the selection follows.  **What a screen reader hears.** The log is a 'log' and stays quiet as lines arrive, since reading a build aloud line by line helps nobody. A separate status region says each line at 'error' once it arrives, each step once it finishes or fails, and the end of the run once 'done' is set or 'source' ends. Set 'done' yourself when output you 'write' is complete. Set 'quiet' where something around the log speaks for it, as a chat turn does for an agent's work.  The log scrolls on this tier. It carries 'data-scroller', so following the newest line and drawing a window work with no stylesheet. Give the log a block size, such as 'helix-headless-log::part(log) { block-size: 20rem }'.  '''js import '@fusion.dev/helix/log' ''' */
   "helix-headless-log": DefineCustomElement<
     HelixHeadlessLog,
     HelixHeadlessLogVueProps,