@fusion.dev/helix-headless 0.204.0 → 0.205.0

package/custom-elements.json

@@ -24965,7 +24965,7 @@
         },
         {
           "kind": "class",
-          "description": "A chat message carries its state: sending, arrived, streaming, or failed. A\nfailed message has a retry control in the message, which fires `helix-send`.\n\n`streaming` is the state the others are arranged around. A streaming message\nchanges height on every frame, so it is marked `aria-busy` while it arrives\nand announced once when it settles. A screen reader cannot follow a stream\nread out character by character.\n\nA screen reader names the turn by its author and its time, such as \"You, 2\nminutes ago\". The author is `author-label`, or \"You\" for `me`, or the\n`author` itself where it is a name; give a turn by `them` an `author-label`\nto name it. The chat it sits in holds the sentence and the word for `me`, so\na page in another language sets them once there. The time moves on by\nitself, so \"now\" becomes \"1 minute ago\" while the page is open.",
+          "description": "A chat message carries its state: sending, arrived, streaming, or failed. A\nfailed message has a retry control in the message, which fires `helix-send`.\n\n`streaming` is the state the others are arranged around. A streaming message\nchanges height on every frame, so it is marked `aria-busy` while it arrives\nand announced once when it settles. A screen reader cannot follow a stream\nread out character by character.\n\nA screen reader names the turn by its author and its time, such as \"You, 2\nminutes ago\". The author is `author-label`, or \"You\" for `me`, or the\n`author` itself where it is a name; give a turn by `them` an `author-label`\nto name it. The chat it sits in holds the sentence and the word for `me`, so\na page in another language sets them once there. The time moves on by\nitself, so \"now\" becomes \"1 minute ago\" while the page is open.\n\n**An agent's work goes in `work`, and its answer in the content.** The work,\nits thinking, the commands it ran and what they printed, is a record read\nthe way a log is, so a `Log` with `separation=\"plain\"` and `quiet` sits there\nabove the answer. The chat says the turn once it settles, from the content\nalone, so the work is never read aloud as part of the answer.",
           "name": "HelixHeadlessChatMessage",
           "cssParts": [
             {
@@ -25015,6 +25015,10 @@
             {
               "description": "The turn's time.",
               "name": "time"
+            },
+            {
+              "description": "The box around the `work` slot, above the content.",
+              "name": "work"
             }
           ],
           "slots": [
@@ -25037,6 +25041,10 @@
             {
               "description": "The turn's sources, such as citations, documents, or a retrieved page.",
               "name": "sources"
+            },
+            {
+              "description": "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.",
+              "name": "work"
             }
           ],
           "members": [
@@ -25978,6 +25986,10 @@
               "description": "The time of a turn from `turns`.",
               "name": "message-time"
             },
+            {
+              "description": "The box around a turn's `work`, for a turn from `turns`, which has none.",
+              "name": "message-work"
+            },
             {
               "description": "The control shown while the user is scrolled away from the bottom.",
               "name": "resume"
@@ -102720,6 +102732,10 @@
               "description": "The row of a line at `error`.",
               "name": "line-error"
             },
+            {
+              "description": "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.",
+              "name": "line-grouped"
+            },
             {
               "description": "The row of a line `mark-lines` names on the log.",
               "name": "line-marked"
@@ -103375,7 +103391,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "A log holds lines in the order they were written and keeps the reader at\nthe newest one, until they scroll up to read. It stays where they left it\nwhile lines keep arriving, and a button returns them to the end\n(`resume-label`, \"Jump to latest\").\n\n**Lines arrive two ways.** For a log you serve whole, write `Log.Line`\nelements as children, inside `Log.Group` elements for the steps. For a log\nthat is still being written, hand it text: `write(chunk)` takes text as it\narrives, in pieces that need not end at a line break, and `source` takes a\n`ReadableStream` or an async iterable and reads it to the end. `lines` takes\nthe lines as data. Text drawn from data is drawn one window at a time, so a\nlog of a hundred thousand lines holds a screenful of elements, and the log\nneeds a block size of its own. Do not use both ways at once.\n\n**Written text is read the way a terminal shows it.** A carriage return\nstarts the line over, so a progress bar stays one line, and the line still\nbeing written is shown as it stands. ANSI colors and weights are drawn, in\nthe sixteen colors the styled tier takes from your theme, and every other\nescape code is dropped.\n\n**Read a CI log's own markers with `format`.** `github-actions` reads the\nworkflow commands a step writes, `::group::` and `::error::` among them,\nand the times at the start of a downloaded log. `vercel` reads a Vercel\nbuild log's phases and its warnings. Each step opens as it starts, folds\nonce it passes, stays open where it failed, and is timed from its lines.\nFor any other log, give `parse` a function that reads each finished line:\nit returns a level, a group, or `open` and `close` to start and end a step.\n\n**Steps fold.** Lines that name a group in `groups` stand under its heading,\nwhich shows its status and how long it took and opens and closes the lines.\nA group a reader opens or closes fires `helix-expand` with every open group.\n\n**Search with `query`.** The log shows only the lines that hold it, marks\neach match, opens the groups that hold one, and says how many lines match.\n\n`line-numbers` numbers the lines from the first ever written, so a number\nstill names its line once `limit` has let older lines go, and `line-href`\nmakes each number a link, such as `#L{n}`. `scrollToLine(n)` takes a reader\nto one. `timestamps` shows each line's `at`, on the clock or as the time\ninto the run. `mark-lines` marks lines, such as `12, 40-44`.\n\n**`selectable` lets a reader select lines**, as a code host does: pressing a\nnumber selects its line, and pressing another with Shift selects every line\nbetween them. `selected-lines` holds the selection, such as `12-20`, and\n`helix-select` asks before it changes. With a `line-href` that is a\nfragment, the address follows the selection, `#L12` or `#L12-L20`, and a\npage opened at one selects it and scrolls to it.\n\n**The numbers are one tab stop.** Where they are links or buttons, Tab\nreaches the one a reader last used, or the first selected, and the arrow\nkeys move between them, with Home and End for the first and the last. With\nShift on a `selectable` log, the selection follows.\n\n**What a screen reader hears.** The log is a `log` and stays quiet as lines\narrive, since reading a build aloud line by line helps nobody. A separate\nstatus region says each line at `error` once it arrives, each step once it\nfinishes or fails, and the end of the run once `done` is set or `source`\nends. Set `done` yourself when output you `write` is complete.\n\nThe log scrolls on this tier. It carries `data-scroller`, so following the\nnewest line and drawing a window work with no stylesheet. Give the log a\nblock size, such as `helix-headless-log::part(log) { block-size: 20rem }`.\n\n```js\nimport '@fusion.dev/helix/log'\n```",
+          "description": "A log holds lines in the order they were written and keeps the reader at\nthe newest one, until they scroll up to read. It stays where they left it\nwhile lines keep arriving, and a button returns them to the end\n(`resume-label`, \"Jump to latest\").\n\n**Lines arrive two ways.** For a log you serve whole, write `Log.Line`\nelements as children, inside `Log.Group` elements for the steps. For a log\nthat is still being written, hand it text: `write(chunk)` takes text as it\narrives, in pieces that need not end at a line break, and `source` takes a\n`ReadableStream` or an async iterable and reads it to the end. `lines` takes\nthe lines as data. Text drawn from data is drawn one window at a time, so a\nlog of a hundred thousand lines holds a screenful of elements, and the log\nneeds a block size of its own. Do not use both ways at once.\n\n**Written text is read the way a terminal shows it.** A carriage return\nstarts the line over, so a progress bar stays one line, and the line still\nbeing written is shown as it stands. ANSI colors and weights are drawn, in\nthe sixteen colors the styled tier takes from your theme, and every other\nescape code is dropped.\n\n**Read a CI log's own markers with `format`.** `github-actions` reads the\nworkflow commands a step writes, `::group::` and `::error::` among them,\nand the times at the start of a downloaded log. `vercel` reads a Vercel\nbuild log's phases and its warnings. Each step opens as it starts, folds\nonce it passes, stays open where it failed, and is timed from its lines.\nFor any other log, give `parse` a function that reads each finished line:\nit returns a level, a group, or `open` and `close` to start and end a step.\n\n**Steps fold.** Lines that name a group in `groups` stand under its heading,\nwhich shows its status and how long it took and opens and closes the lines.\nA group a reader opens or closes fires `helix-expand` with every open group.\n\n**Search with `query`.** The log shows only the lines that hold it, marks\neach match, opens the groups that hold one, and says how many lines match.\n\n`line-numbers` numbers the lines from the first ever written, so a number\nstill names its line once `limit` has let older lines go, and `line-href`\nmakes each number a link, such as `#L{n}`. `scrollToLine(n)` takes a reader\nto one. `timestamps` shows each line's `at`, on the clock or as the time\ninto the run. `mark-lines` marks lines, such as `12, 40-44`.\n\n**`selectable` lets a reader select lines**, as a code host does: pressing a\nnumber selects its line, and pressing another with Shift selects every line\nbetween them. `selected-lines` holds the selection, such as `12-20`, and\n`helix-select` asks before it changes. With a `line-href` that is a\nfragment, the address follows the selection, `#L12` or `#L12-L20`, and a\npage opened at one selects it and scrolls to it.\n\n**The numbers are one tab stop.** Where they are links or buttons, Tab\nreaches the one a reader last used, or the first selected, and the arrow\nkeys move between them, with Home and End for the first and the last. With\nShift on a `selectable` log, the selection follows.\n\n**What a screen reader hears.** The log is a `log` and stays quiet as lines\narrive, since reading a build aloud line by line helps nobody. A separate\nstatus region says each line at `error` once it arrives, each step once it\nfinishes or fails, and the end of the run once `done` is set or `source`\nends. Set `done` yourself when output you `write` is complete. Set `quiet`\nwhere something around the log speaks for it, as a chat turn does for an\nagent's work.\n\nThe log scrolls on this tier. It carries `data-scroller`, so following the\nnewest line and drawing a window work with no stylesheet. Give the log a\nblock size, such as `helix-headless-log::part(log) { block-size: 20rem }`.\n\n```js\nimport '@fusion.dev/helix/log'\n```",
           "name": "HelixHeadlessLog",
           "cssProperties": [
             {
@@ -103528,6 +103544,10 @@
               "description": "The row of a line drawn from data at `error`.",
               "name": "line-error"
             },
+            {
+              "description": "The row of a line drawn from data that belongs to a step.",
+              "name": "line-grouped"
+            },
             {
               "description": "The row of a line drawn from data that `mark-lines` names.",
               "name": "line-marked"
@@ -103898,6 +103918,16 @@
               "description": "Text a line has to hold to be shown, ignoring case. Empty shows every line.",
               "attribute": "query"
             },
+            {
+              "kind": "field",
+              "name": "quiet",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the log says nothing to a screen reader as lines arrive, steps\nfinish, or the run ends. For a log inside something that speaks for it,\nsuch as an agent's work in a chat turn, which the turn announces once it\nsettles.",
+              "attribute": "quiet"
+            },
             {
               "kind": "field",
               "name": "resumeLabel",
@@ -105547,6 +105577,15 @@
               "description": "Text a line has to hold to be shown, ignoring case. Empty shows every line.",
               "fieldName": "query"
             },
+            {
+              "name": "quiet",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the log says nothing to a screen reader as lines arrive, steps\nfinish, or the run ends. For a log inside something that speaks for it,\nsuch as an agent's work in a chat turn, which the turn announces once it\nsettles.",
+              "fieldName": "quiet"
+            },
             {
               "name": "resume-label",
               "type": {
@@ -219846,6 +219885,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-headless",
-    "version": "0.204.0"
+    "version": "0.205.0"
   }
 }

package/dist/chat/message/chat-message.d.ts

@@ -26,6 +26,12 @@ export declare const FAILED_LABEL = "Not sent";
  * 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.
+ *
  * @since 0.1.0
  * @status stable
  * @category feedback
@@ -38,6 +44,7 @@ export declare const FAILED_LABEL = "Not sent";
  * @slot indicator - The indicator shown before the first token arrives.
  * Defaults to the typing indicator.
  * @slot sources - The turn's sources, such as citations, documents, or a retrieved page.
+ * @slot 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.
  *
  * @event {HelixSendEvent} helix-send - Fired when the user retries a failed message. Cancelable: if it is not canceled, the turn is sent again. Canceling it leaves the failure and the retry button as they were.
  *
@@ -53,6 +60,7 @@ export declare const FAILED_LABEL = "Not sent";
  * @csspart sources - The turn's sources, under it and outside the bubble.
  * @csspart state - The text that names the turn's state, when there is one to show.
  * @csspart time - The turn's time.
+ * @csspart work - The box around the `work` slot, above the content.
  */
 export declare class HelixHeadlessChatMessage extends HelixElement {
     /**

package/dist/chat/message/chat-message.js

@@ -108,7 +108,7 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
     }
     markEmpty() {
         markRegion(this.renderRoot, 'content', [''], { hide: false });
-        for (const name of ['sources', 'actions']) {
+        for (const name of ['work', 'sources', 'actions']) {
             markRegion(this.renderRoot, name, [name]);
         }
     }
@@ -120,6 +120,7 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         return html `<div part="message">
       <span part="avatar"><slot name="avatar"></slot></span>
       <div part="body">
+        <div part="work"><slot name="work" @slotchange=${this.handleFill}></slot></div>
         <div part="content">
           <slot @slotchange=${this.handleFill}></slot>
           ${this.renderIndicator()}

package/dist/chat/root/chat-root.d.ts

@@ -156,6 +156,7 @@ declare const HelixHeadlessChat_base: (new (...args: any[]) => import("@fusion.d
  * @csspart message-sources - The sources of a turn from `turns`.
  * @csspart message-state - The state text of a turn from `turns`, when there is one to show.
  * @csspart message-time - The time of a turn from `turns`.
+ * @csspart message-work - The box around a turn's `work`, for a turn from `turns`, which has none.
  * @csspart resume - The control shown while the user is scrolled away from the bottom.
  * @csspart resume-button - The button the `resume` region shows when nothing is slotted into it.
  * @csspart resume-mark - The arrow on the default `resume-button`.

package/dist/chat/root/chat-root.js

@@ -666,7 +666,7 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
               exportparts="actions: message-actions, avatar: message-avatar, body: message-body,
                 content: message-content, indicator: message-indicator, mark: message-mark, message,
                 meta: message-meta, retry: message-retry, sources: message-sources,
-                state: message-state, time: message-time${secondNames(SECOND_NAMES.author, turn.author)}${secondNames(SECOND_NAMES.state, turn.state)}"
+                state: message-state, time: message-time, work: message-work${secondNames(SECOND_NAMES.author, turn.author)}${secondNames(SECOND_NAMES.state, turn.state)}"
               author=${turn.author ?? nothing}
               author-label=${turn.authorLabel ?? nothing}
               at=${turn.at ?? nothing}

package/dist/log/line/log-line.d.ts

@@ -25,6 +25,7 @@ export type LogTimes = 'absolute' | 'relative';
  * @csspart line - The row the number, the time, and the text sit in.
  * @csspart line-debug - The row of a line at `debug`.
  * @csspart line-error - The row of a line at `error`.
+ * @csspart 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.
  * @csspart line-marked - The row of a line `mark-lines` names on the log.
  * @csspart line-selected - The row of a line in the log's selection.
  * @csspart line-warn - The row of a line at `warn`.
@@ -55,6 +56,8 @@ export declare class HelixHeadlessLogLine extends HelixElement {
     lineLabel: string;
     /** @internal Set by the log: whether the query hides the line. */
     logFiltered: boolean;
+    /** @internal Set by the log: whether the line belongs to a step. */
+    logGrouped: boolean;
     /** @internal Set by the log: the link a number goes to, with `{n}` for the number. */
     logHref: string;
     /** @internal Set by the log: whether `mark-lines` names the line. */

package/dist/log/line/log-line.js

@@ -18,6 +18,7 @@ let HelixHeadlessLogLine = class HelixHeadlessLogLine extends HelixElement {
         this.at = '';
         this.lineLabel = 'Line {number}';
         this.logFiltered = false;
+        this.logGrouped = false;
         this.logHref = '';
         this.logMarked = false;
         this.logNumber = 0;
@@ -111,7 +112,7 @@ let HelixHeadlessLogLine = class HelixHeadlessLogLine extends HelixElement {
         }
         const level = this.level;
         return html `<div
-      part="line${level ? { debug: ' line-debug', error: ' line-error', info: '', warn: ' line-warn' }[level] : ''}${this.logMarked ? ' line-marked' : ''}${this.logSelected ? ' line-selected' : ''}"
+      part="line${level ? { debug: ' line-debug', error: ' line-error', info: '', warn: ' line-warn' }[level] : ''}${this.logMarked ? ' line-marked' : ''}${this.logSelected ? ' line-selected' : ''}${this.logGrouped ? ' line-grouped' : ''}"
     >${this.renderNumber()}${this.renderTime()}<span part="text">${this.renderText()}</span></div>`;
     }
 };
@@ -128,6 +129,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessLogLine.prototype, "logFiltered", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessLogLine.prototype, "logGrouped", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessLogLine.prototype, "logHref", void 0);

package/dist/log/root/log-root.d.ts

@@ -73,7 +73,9 @@ declare const HelixHeadlessLog_base: (new (...args: any[]) => import("@fusion.de
  * 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
@@ -117,6 +119,7 @@ declare const HelixHeadlessLog_base: (new (...args: any[]) => import("@fusion.de
  * @csspart line - The row of a line drawn from data.
  * @csspart line-debug - The row of a line drawn from data at `debug`.
  * @csspart line-error - The row of a line drawn from data at `error`.
+ * @csspart line-grouped - The row of a line drawn from data that belongs to a step.
  * @csspart line-marked - The row of a line drawn from data that `mark-lines` names.
  * @csspart line-match - Text in a line drawn from data that matches `query`.
  * @csspart line-number - The number of a line drawn from data.
@@ -271,6 +274,13 @@ export declare class HelixHeadlessLog extends HelixHeadlessLog_base {
     set pinned(next: boolean);
     /** Text a line has to hold to be shown, ignoring case. Empty shows every line. */
     query: string;
+    /**
+     * 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: boolean;
     /** The words on the button that returns to the newest line, where `resume` is empty. */
     resumeLabel: string;
     /**

package/dist/log/root/log-root.js

@@ -40,6 +40,7 @@ let HelixHeadlessLog = class HelixHeadlessLog extends MixinCollection(HelixEleme
         this.markLines = '';
         this.matchesLabel = '{count, plural, =0 {No lines match} one {# line matches} other {# lines match}}';
         this.query = '';
+        this.quiet = false;
         this.resumeLabel = 'Jump to latest';
         this.selectable = false;
         this.selectedLines = '';
@@ -530,6 +531,7 @@ let HelixHeadlessLog = class HelixHeadlessLog extends MixinCollection(HelixEleme
                 line.logSelectable = this.selectable;
                 line.logSelected = this.selected(at + 1);
                 line.logStop = at + 1 === stop;
+                line.logGrouped = this.childGroups.some((group) => group.contains(line));
             });
             if (!filtered && needle !== '') {
                 for (const group of this.childGroups) {
@@ -583,7 +585,7 @@ let HelixHeadlessLog = class HelixHeadlessLog extends MixinCollection(HelixEleme
         const now = this.listen();
         const before = this.heard;
         this.heard = now;
-        if (this.opening || !before) {
+        if (this.opening || !before || this.quiet) {
             return;
         }
         const said = [];
@@ -796,7 +798,7 @@ let HelixHeadlessLog = class HelixHeadlessLog extends MixinCollection(HelixEleme
         const line = this.tag('log-line');
         const { at, level } = row.line;
         return html `<${line}
-      exportparts="line, line-debug, line-error, line-marked, line-selected, line-warn, match: line-match,
+      exportparts="line, line-debug, line-error, line-grouped, line-marked, line-selected, line-warn, match: line-match,
         number: line-number, run: line-run, run-bold: line-run-bold, run-dim: line-run-dim,
         run-italic: line-run-italic, run-strike: line-run-strike, run-underline: line-run-underline,
         text: line-text, time: line-time"
@@ -811,6 +813,7 @@ let HelixHeadlessLog = class HelixHeadlessLog extends MixinCollection(HelixEleme
       .logSelectable=${this.selectable}
       .logSelected=${this.selected(row.number)}
       .logStop=${row.number === stop}
+      .logGrouped=${row.line.group !== undefined}
       .logStart=${start}
       .logTimes=${this.timestamps ?? ''}
       .runs=${this.buffer.runsOf(row.line)}
@@ -952,6 +955,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessLog.prototype, "query", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessLog.prototype, "quiet", void 0);
 __decorate([
     words,
     property({ attribute: 'resume-label' })