@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/chat/composer/chat-composer.js

@@ -9,97 +9,18 @@ import { arrowElbowDownLeft } from '@fusion.dev/helix-icons';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary Where the reader writes their turn.
- *
- * @description
- * **A separate element because it is separately replaceable.** A consumer with
- * attachments, slash commands or a model picker replaces the composer and keeps
- * the transcript, which is only possible if the two were never one component.
- *
- * **Enter sends and Shift+Enter opens a line, and it is configurable rather than
- * decided.** The convention is near-universal in messaging and near-inverted in
- * anything that is really a document editor, and a component that picks one
- * makes the other consumer reimplement the composer. `submit-on` takes `enter`
- * or `button`, and the second is what a long-form composer wants.
- *
- * The composer clears only when nobody refused the send, because a composer that
- * empties itself and then hears the request failed has thrown away the only copy
- * of what the reader wrote.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Message box, Prompt input
- * @documentation https://helix.fusion.dev/components/chat
- *
- * @slot end - Under the field, beside the send control.
- * @slot start - Under the field, at the leading edge: attachments, a model picker.
- *
- * @event {HelixSendEvent} helix-send - Fired when the reader offers their turn, and cancelable.
- *
- * @csspart composer - The whole composer.
- * @csspart end - The trailing slot's box.
- * @csspart field - The text field.
- * @csspart mark - The glyph inside the send control.
- * @csspart send - The control that offers the turn.
- * @csspart start - The leading slot's box.
- * @csspart tools - The row under the field.
- */
 let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the composer refuses input, while a turn is in flight say.
-         */
         this.disabled = false;
-        /**
-         * Accessible name for the field.
-         */
         this.label = 'Message';
-        /**
-         * Shown in an empty field.
-         */
         this.placeholder = '';
-        /**
-         * How many rows the field opens at.
-         *
-         * It grows from there.
-         */
         this.rows = 1;
-        /**
-         * Label for the control that sends.
-         */
         this.sendLabel = 'Send';
-        /**
-         * What sends: pressing Enter, or only the control.
-         *
-         * `enter` is the messaging convention and makes Shift+Enter the line break.
-         * `button` is what a composer holding several paragraphs wants, where Enter
-         * has to mean a new line and nothing else.
-         */
         this.submitOn = 'enter';
-        /**
-         * What the reader has written.
-         *
-         * Read it, or set it to seed a draft.
-         */
         this.value = '';
         this.draft = '';
-        /**
-         * @internal Read by the transcript to find the composer among its children.
-         */
         this.isChatComposer = true;
-        /**
-         * Records the draft, and stops the textarea speaking in this element's name.
-         *
-         * **The stop is not incidental.** `input` is composed by specification, so the
-         * `<textarea>` in this shadow root sent its own past this host and on through
-         * whatever `<helix-chat>` it is slotted into, and neither element declares an
-         * `input`: a consumer binding one on either received an undeclared event whose
-         * target was a control they cannot reach. What a composer offers is
-         * `helix-send`, once, when the reader is done.
-         */
         this.handleInput = (event) => {
             event.stopPropagation();
             this.draft = event.target.value;
@@ -107,15 +28,6 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixEle
         this.handleSend = () => {
             this.send();
         };
-        /**
-         * Enter sends where that is what `submit-on` says, and never mid-composition.
-         *
-         * **`isComposing` is the part that is easy to leave out and breaks a whole
-         * writing system.** A reader typing Japanese, Chinese or Korean presses Enter
-         * to accept the candidate their input method is offering, and a composer that
-         * reads it as send fires off a half-finished word every time. The flag is on
-         * the event for exactly this and costs one condition.
-         */
         this.handleKey = (event) => {
             if (event.key !== 'Enter' || this.submitOn !== 'enter') {
                 return;
@@ -127,17 +39,9 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixEle
             this.send();
         };
     }
-    /** What is in the field, whoever last wrote it. */
     get text() {
         return this.draft || this.value;
     }
-    /**
-     * Offers what is written, and reports whether it stood.
-     *
-     * Public because a consumer's own send control is as likely to ask as this
-     * element's is, and because a keyboard shortcut somewhere else on the page is
-     * a reasonable way to send.
-     */
     send() {
         const value = this.text.trim();
         if (value === '' || this.disabled) {
@@ -146,21 +50,10 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixEle
         if (!this.dispatchEvent(new HelixSendEvent({ value }))) {
             return false;
         }
-        /* Cleared only here, after nobody refused. A composer that empties itself
-           first and hears about the failure afterwards has thrown away the only copy
-           of what the reader wrote. */
         this.draft = '';
         this.value = '';
         return true;
     }
-    /**
-     * Says on each tool box whether anything is in it.
-     *
-     * They are boxes in a flex row, so an empty one still takes the gap beside it
-     * and the send control drifts inward by one for every slot a consumer left
-     * alone. No selector can ask this: a slot's assigned nodes are not its DOM
-     * children, so `:empty` describes the fallback rather than the fill.
-     */
     markEmpty() {
         for (const name of ['start', 'end']) {
             const region = this.renderRoot?.querySelector(`[part="${name}"]`);
@@ -177,17 +70,6 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixEle
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'group' });
     }
-    /**
-     * The control that offers the turn, behind a seam so a tier can draw its own.
-     *
-     * **A glyph with the label as its accessible name, rather than the label as
-     * text.** The word "Send" beside a field is the widest thing in the row and
-     * says nothing a return key does not. The return glyph is the mark because
-     * Enter is what actually sends, which `submit-on` says out loud: the control
-     * and the key are one affordance and should look like it. `send-label` is the
-     * accessible name rather than a visible one, so a screen reader still hears
-     * the word.
-     */
     renderSend() {
         return html `<button
       part="send"
@@ -206,19 +88,6 @@ let HelixHeadlessChatComposer = class HelixHeadlessChatComposer extends HelixEle
       </svg>
     </button>`;
     }
-    /**
-     * The field, and a row of tools under it.
-     *
-     * **The tools take a line of their own rather than sharing the field's.** On
-     * one line every tool a consumer adds takes width away from the thing being
-     * typed into; under it, the field spans the whole composer at every width and
-     * the tools have room to grow along.
-     *
-     * Send is at the trailing end of that line rather than in the field, which is
-     * the same corner and costs no overlay: a control positioned inside a
-     * scrolling textarea either covers the last line of a long draft or scrolls
-     * away with it.
-     */
     render() {
         return html `<div part="composer">
       <textarea

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

@@ -8,103 +8,24 @@ import { customElement, HelixElement, HelixSendEvent, hostAria, relativeTime, sl
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary One turn in a conversation, and what has happened to it.
- *
- * @description
- * **The states are the component.** Bubbles are paint; what a chat message has
- * to carry is whether it is on its way, arrived, still arriving, or failed, and
- * a failed message needs a retry that is a real action rather than a toast the
- * reader has to catch.
- *
- * `streaming` is the state everything else is arranged around. A message
- * arriving token by token changes height on every frame, so it is marked
- * `aria-busy` while it arrives and announced once when it settles: a screen
- * reader reading a stream character by character is unusable, and announcing on
- * completion is the only version of this that works.
- *
- * @since 0.1.0
- * @status experimental
- * @category feedback
- * @aliases Message, Bubble, Turn
- * @documentation https://helix.fusion.dev/components/chat
- *
- * @slot - What was said.
- * @slot actions - What can be done with it: copy, retry, react.
- * @slot avatar - Who said it.
- * @slot sources - What it was said from: citations, documents, a retrieved page.
- *
- * @event {HelixSendEvent} helix-send - Fired when the reader asks to send a failed message again, and cancelable.
- *
- * @csspart actions - The controls offered on the turn, beside its time.
- * @csspart avatar - The leading slot's box.
- * @csspart body - What was said, and the line under it.
- * @csspart content - The consumer's own markup.
- * @csspart mark - The status glyph beside a failure.
- * @csspart message - The whole turn.
- * @csspart meta - The line under a turn: its time, its state, and its controls.
- * @csspart retry - The control offered on a failed message.
- * @csspart sources - What the turn was drawn from, under it and outside the bubble.
- * @csspart state - What has happened to it, where that is worth saying.
- * @csspart time - When it was said.
- */
 let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * When it was said, as anything `Date` parses.
-         */
         this.at = '';
-        /**
-         * Label for a message that did not send.
-         */
         this.failedLabel = 'Not sent';
-        /**
-         * Locale for the timestamp.
-         *
-         * Empty is the runtime's own.
-         */
         this.locale = '';
-        /**
-         * Label for the control offered on a failed message.
-         */
         this.retryLabel = 'Try again';
-        /**
-         * What to call each state, for a reader who cannot see it.
-         */
         this.sendingLabel = 'Sending';
-        /**
-         * @internal Read by the transcript to identify its children across the light
-         * DOM, which is cheaper than `instanceof`. Not a consumer's to read or set.
-         */
         this.isChatMessage = true;
         this.clock = undefined;
-        /**
-         * A turn's own content arrives and changes no property here.
-         *
-         * It is the streaming case that needs this rather than a tidiness one: the
-         * first token of an answer is a light-DOM child appearing under an element
-         * nothing else told to look again, and it is exactly the moment the typing
-         * indicator has to stop being drawn.
-         */
         this.handleFill = () => {
             this.markEmpty();
         };
-        /**
-         * Retry is `helix-send` again, from the message rather than the composer.
-         *
-         * **Not an event of its own**, because a retry is the same request: the reader
-         * is offering what they wrote, and the only difference is which element is
-         * offering it. A listener that wants to tell them apart has `event.target`,
-         * which is the message on a retry and the composer on a first send, and that
-         * is a distinction the DOM already makes without a second name for it.
-         */
         this.handleRetry = (event) => {
             event.stopPropagation();
             this.dispatchEvent(new HelixSendEvent({ value: this.textContent?.trim() ?? '' }));
         };
     }
-    /** The timestamp, or nothing where there is not one to read. */
     get moment() {
         if (this.at === '') {
             return undefined;
@@ -117,13 +38,6 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         if (changed.has('at')) {
             this.clock = Date.now();
         }
-        /* `article` rather than `listitem`, because the transcript is a `log` and a
-           log's children are not list items: a turn is a self-contained thing a
-           reader can be moved to, which is what an article is for.
-    
-           `aria-busy` while it arrives is the whole of the streaming contract on
-           this side: the live region above it holds its announcement until the flag
-           clears, so the message is read once, whole, rather than per token. */
         hostAria(this.internals, { role: 'article' });
         this.toggleAttribute('aria-busy', this.state === 'streaming');
     }
@@ -135,16 +49,6 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         const { text } = relativeTime(this.locale)(moment, new Date(this.clock ?? Date.now()));
         return html `<time part="time" datetime=${moment.toISOString()}>${text}</time>`;
     }
-    /**
-     * The status glyph, behind a seam so a tier can draw its own.
-     *
-     * `TONE_MARKS.danger` rather than a glyph chosen here: the library has one
-     * status vocabulary, `Callout`, `Toast.Item` and `Announcement` all read from
-     * it, and a reader meets these four marks in a passage, in a message and now
-     * on a turn and has to read them as the same four things. It carries the
-     * accessible name with it, which is the half that matters: `danger` is the
-     * word the API uses and "Error" is the word a reader understands.
-     */
     renderMark() {
         const { icon, label } = TONE_MARKS.danger;
         return html `<svg
@@ -157,14 +61,6 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
       ${unsafeSVG(icon.content)}
     </svg>`;
     }
-    /**
-     * What has happened to it, in words, and the way back from a failure.
-     *
-     * A seam of its own, because the styled tier draws a failure as an icon and a
-     * consumer may want neither. `sent` says nothing: every settled message is
-     * sent, and a transcript that labels each one is a transcript of the word
-     * "sent".
-     */
     renderState() {
         if (this.state === 'sending') {
             return html `<span part="state">${this.sendingLabel}</span>`;
@@ -172,26 +68,11 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         if (this.state !== 'failed') {
             return nothing;
         }
-        /* **The mark, and not because color needs a second carrier here.** "Not
-           sent" is words, so the meaning survives without it. It is here because a
-           failure is the one state that has to be *found* rather than noticed, and a
-           shape is what a reader scanning a transcript finds. */
         return html `<span part="state"
       >${this.renderMark()} ${this.failedLabel}
       <button part="retry" type="button" @click=${this.handleRetry}>${this.retryLabel}</button>
     </span>`;
     }
-    /**
-     * Says on each region whether anything is in it.
-     *
-     * Three of them need the answer and no selector can give it: a slot's assigned
-     * nodes are not its DOM children, so `:empty` and `:has(*)` both describe the
-     * fallback rather than the fill. `sources` and `actions` are regions that cost
-     * a gap when they are boxes at all, which most turns should not pay. `content`
-     * is the one that is not about space: a turn that is `streaming` with nothing
-     * in it yet is what the typing indicator is drawn for, and "nothing in it yet"
-     * is exactly this question.
-     */
     markEmpty() {
         for (const name of ['content', 'sources', 'actions']) {
             const region = this.renderRoot?.querySelector(`[part="${name}"]`);
@@ -200,8 +81,6 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
                 : this.renderRoot?.querySelector(`slot[name="${name}"]`);
             const empty = !slotFilled(slot);
             region?.toggleAttribute('data-empty', empty);
-            /* `content` keeps its box when empty, because the typing indicator is
-               painted into it. The other two are gaps nobody asked for. */
             if (name !== 'content') {
                 region?.toggleAttribute('hidden', empty);
             }
@@ -211,22 +90,6 @@ let HelixHeadlessChatMessage = class HelixHeadlessChatMessage extends HelixEleme
         super.updated(changed);
         this.markEmpty();
     }
-    /**
-     * The turn: who said it, what was said, what it was drawn from, and its line.
-     *
-     * **`sources` and `actions` are inside the body rather than beside it.**
-     * `actions` as a third grid column puts a copy control on a fifteen-word turn
-     * at the container's trailing edge, a hundred and fifty pixels of nothing
-     * between it and the bubble it acts on, on both sides of the conversation. As
-     * a column of its own inside the body it is no better: a bubble spanning two
-     * auto tracks inflates both, so the controls land under the middle of the
-     * turn.
-     *
-     * So they are inside `meta`, which is the line under a turn rather than only
-     * its timestamp, and that line is one flex row: time, state, controls, all
-     * hugging whichever edge the turn is against. Nothing has to be sized against
-     * anything else for that to hold at every width.
-     */
     render() {
         return html `<div part="message">
       <span part="avatar"><slot name="avatar"></slot></span>

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

@@ -7,125 +7,16 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixBeforePinEvent, HelixElement, hostAria, MixinCollection, requestChange, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * The regions a consumer fills, in the order they are rendered.
- *
- * Named once because two things read the list: the manual assignment that puts
- * a child in the region its `slot` names, and the emptiness each region is
- * hidden on. Written out twice they go out of step.
- */
 const REGIONS = ['header', 'actions', 'resume', 'status', 'composer'];
-/**
- * @summary A conversation: the turns, and where the reader is in them.
- *
- * @description
- * **It has no opinion about where it sits.** A chat is asked for as a floating
- * button, a page, a palette, a sidebar, a modal and an inline block, and none of
- * those is a variant of a conversation: they are containers a conversation is
- * put in, and the containers already exist. `Popover` and `SpeedDial` make the
- * floating one, `Drawer` the sidebar, `Dialog` the modal, `Command` the palette,
- * and a page is a page. Nothing here is positioned, nothing here has a backdrop,
- * and nothing here owns a trigger, because a trigger opens a container and
- * containers own their own. If a form factor needs a mode on this element, the
- * split is wrong.
- *
- * **Scroll ownership is the behavior everything else depends on, and it is the
- * most-got-wrong thing in the category.** A transcript that grows wants to stay
- * at the bottom, except when the reader has scrolled up to read, where pinning
- * is hostile. The rule: pin while the reader is within `threshold` of the
- * bottom, release the moment they leave it, and offer a way back. **Never scroll
- * a reader who is reading.**
- *
- * The element owns it, because it is the only party that knows a message arrived
- * and where the viewport was when it did. `pinned` announces before it moves, so
- * a consumer who wants to own it refuses the request and assigns their own.
- *
- * **The live region announces on completion, not on arrival.** The transcript is
- * `role="log"` with `aria-live="polite"`, and a streaming message carries
- * `aria-busy` while it arrives: a screen reader reading a stream token by token
- * is unusable, and holding the announcement until the flag clears is the only
- * arrangement that works. Somebody typing is a separate status region, so it
- * never interleaves with what was said.
- *
- * **Not a client.** No transport, no protocol, no model. It renders a
- * conversation and reports what the reader did.
- *
- * @since 0.1.0
- * @status experimental
- * @category feedback
- * @aliases Conversation, Transcript, Thread, Messages
- * @documentation https://helix.fusion.dev/components/chat
- *
- * @slot - The turns, as `helix-chat-message` children.
- * @slot actions - Beside the header: what can be done to the conversation itself.
- * @slot composer - Below the transcript, where the reader writes.
- * @slot header - Above the transcript: what this conversation is.
- * @slot resume - The way back to the bottom, shown while the reader has scrolled away.
- * @slot status - Beside the composer: somebody typing, connection lost.
- *
- * @event {HelixBeforePinEvent} helix-before-pin - Fired when the reader pins or unpins the transcript by scrolling. Cancelable.
- *
- * @csspart actions - The controls for the conversation, at the header's trailing edge.
- * @csspart composer - The region the composer sits in.
- * @csspart empty - Shown when the conversation has no turns.
- * @csspart header - The region above the transcript.
- * @csspart loading - Shown while the history is still on its way.
- * @csspart log - The transcript, which is the thing that scrolls.
- * @csspart resume - The affordance offered while the reader is away from the bottom.
- * @csspart status - The status region, which is not part of the log.
- */
 let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Whether to open pinned, where nothing declared it.
-         */
         this.defaultPinned = true;
-        /**
-         * Accessible name for the conversation.
-         */
         this.label = '';
-        /**
-         * How near the bottom still counts as being at it, in pixels.
-         *
-         * A hook rather than a constant, because the right number depends on how tall
-         * a turn is: a transcript of one-line replies wants a smaller threshold than
-         * one of paragraphs, and a reader who has scrolled up by half a message has
-         * not left.
-         */
         this.threshold = 48;
         this.pinnedState = undefined;
-        /** Watches for turns arriving, since a manual slot hears nothing about them. */
         this.watcher = undefined;
-        /**
-         * Which regions were given something, or undefined where nobody has counted.
-         *
-         * **A slot that is assigned by hand has no children, so no stylesheet can ask
-         * whether it was filled.** `[part="header"]:not(:has(> slot:has(*)))` is the
-         * rule every other collection here hides an empty region with, and `:has()`
-         * walks the DOM tree: with `slotAssignment: 'manual'` the assigned elements
-         * are children of this host and never of the slot, so the test was false for
-         * a filled header exactly as often as for an empty one and the rule never
-         * matched. Measured on a chat with nothing slotted at all: the header was 25
-         * pixels tall and drew its hairline under nothing, and so did the composer.
-         *
-         * Undefined rather than empty on the way in, for `MixinCollection`'s reason:
-         * the server has no children to count, and an unknown answer is not "empty".
-         * It serves every region and the first assignment on the client settles them,
-         * which is a shadow-root attribute rather than a host one and so is nothing a
-         * consumer's hydration compares.
-         */
         this.filled = undefined;
-        /**
-         * A press anywhere in the way back takes the reader back.
-         *
-         * The control is slotted so the consumer picks the words, which on its own
-         * leaves a button this element positions, lifts, shows and hides doing nothing
-         * until somebody wires it. The region exists for exactly one purpose, so a
-         * press inside it has exactly one meaning and this element is entitled to act
-         * on it. `resume()` stays public for the other callers: a keyboard shortcut,
-         * or a consumer's own control somewhere else on the page.
-         */
         this.handleResume = () => {
             this.resume();
         };
@@ -133,25 +24,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
             this.assign();
             this.requestUpdate();
         };
-        /**
-         * The reader's own scrolling, which is the only thing that unpins.
-         *
-         * **Bound to the transcript in the template, and it has to be.** A listener on
-         * the host never runs, in any phase, and capture does not rescue it: `scroll`
-         * is not *composed*, so its propagation path stops at the shadow root and
-         * never includes the host. Not bubbling is the red herring.
-         *
-         * Measured by dispatching both shapes at the transcript: with
-         * `composed: false`, which is what the platform sends, the host saw zero and
-         * `pinned` stayed true; with `composed: true` the host saw one and `pinned`
-         * went false.
-         *
-         * **The scroll this element does itself must not unpin it**, which is the
-         * subtle half: `scrollTop = scrollHeight` fires the same event a reader's
-         * wheel does. Reading the position rather than counting events is what makes
-         * that harmless, since after a programmatic scroll the position is the bottom
-         * and the answer is the one that was already true.
-         */
         this.handleScroll = () => {
             const wanted = this.atBottom;
             if (wanted !== this.pinned) {
@@ -159,37 +31,10 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
             }
         };
     }
-    /**
-     * Nothing is assigned by name, so the turns land in the log and the rest does not.
-     *
-     * The messages are ordinary children a consumer writes with no `slot`, and a
-     * `role="log"` whose turns are somewhere else is a log of nothing. Manual
-     * assignment is the only way to wrap them without editing the consumer's
-     * markup, which is a change a React consumer's hydration reports and does not
-     * patch up.
-     */
     static { this.shadowRootOptions = {
         ...HelixElement.shadowRootOptions,
         slotAssignment: 'manual',
     }; }
-    /**
-     * Whether the transcript follows new turns to the bottom.
-     *
-     * The reader's scrolling asks first: `helix-before-pin` is cancelable, so a
-     * consumer refusing it takes the decision and assigns their own value.
-     * `default-pinned` seeds the state this element then owns, and it defaults to
-     * pinned because a conversation opens at its most recent turn.
-     *
-     * **Not reflected, and the default is why.** A reflected property that
-     * defaults to true writes its attribute on upgrade whether or not the
-     * consumer wrote one, so the server serves `<helix-chat label="x">` and the
-     * client turns it into `<helix-chat label="x" pinned>`: a hydration mismatch a
-     * React consumer reports and does not patch up. Nothing needs the attribute
-     * either, because the one thing that changes with the pin is the way back, and
-     * that is a part inside the shadow tree where a stylesheet can already reach
-     * it. Measured rather than assumed: `label, pinned` after upgrade against
-     * `label` from the server.
-     */
     get pinned() {
         return this.pinnedState ?? this.defaultPinned;
     }
@@ -198,21 +43,15 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         this.pinnedState = next;
         this.requestUpdate('pinned', previous);
     }
-    /** Whether a region has something in it, taking unknown for yes. */
     has(name) {
         return this.filled?.has(name) ?? true;
     }
-    /** The turns declared as children, in the order they are written. */
     get messages() {
-        /* `?? []` is the server: Lit's element shim carries attributes and not a
-           tree, so `children` is undefined there and spreading it throws. */
         return [...(this.children ?? [])].filter((child) => 'isChatMessage' in child && child.isChatMessage === true);
     }
-    /** The element that scrolls, once there is one. */
     get log() {
         return this.renderRoot?.querySelector?.('[part="log"]') ?? null;
     }
-    /** Whether the reader is within `threshold` of the bottom right now. */
     get atBottom() {
         const log = this.log;
         if (!log) {
@@ -220,13 +59,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         }
         return log.scrollHeight - log.scrollTop - log.clientHeight <= Math.max(0, this.threshold);
     }
-    /**
-     * Puts the transcript back at its most recent turn.
-     *
-     * Public because the way back is a slot, so the control offering it is the
-     * consumer's and needs something to call. Pins again on the way, which is what
-     * a reader asking to go to the bottom means.
-     */
     resume() {
         const log = this.log;
         if (log) {
@@ -234,14 +66,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
         }
         this.requestPinned(true);
     }
-    /**
-     * Asks to pin or unpin, and reports whether the request stood.
-     *
-     * Announced before it is applied, so a consumer owning the pin hears the
-     * reader's scroll and decides. `property` names it, which is what
-     * `helix-before-pin`'s detail is for: a listener switching on the name is
-     * switching on something with one meaning.
-     */
     requestPinned(next) {
         if (next === this.pinned) {
             return false;
@@ -273,8 +97,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
                 filled.add(name);
             }
         }
-        /* Compared before it is set, because this runs from `updated` and a new Set
-           every render is a new value every render, which is a render loop. */
         const previous = this.filled;
         if (!previous ||
             previous.size !== filled.size ||
@@ -284,17 +106,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     }
     connectedCallback() {
         super.connectedCallback();
-        /* **A turn that arrives after first paint reaches nothing on its own.**
-           Slots are assigned by hand here, so appending a child assigns it to
-           nothing, fires no `slotchange`, and schedules no render: the transcript
-           went on showing "Nothing to show" over six children it already had, and
-           the one thing a conversation does is grow. Measured with `assignedElements()`
-           at zero against `children` at nine.
-    
-           `childList` and not `subtree`, which is the difference between watching a
-           conversation and watching every token of it: a streaming turn rewrites its
-           own text on every frame, and a subtree observer would re-render the whole
-           transcript each time for a change inside a child that owns it. */
         this.watcher = new MutationObserver(this.handleSlotChange);
         this.watcher.observe(this, { childList: true });
     }
@@ -310,8 +121,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     updated(changed) {
         super.updated(changed);
         this.assign();
-        /* After the render that added the turn, because the scroll height it is
-           being sent to does not exist until then. */
         if (this.pinned) {
             const log = this.log;
             if (log) {
@@ -321,8 +130,6 @@ let HelixHeadlessChat = class HelixHeadlessChat extends MixinCollection(HelixEle
     }
     render() {
         const away = !this.pinned;
-        /* The header stands while either half of it is filled: a conversation with
-           no title and a single control still needs the row that control sits in. */
         const titled = this.has('header') || this.has('actions');
         return html `<div part="header" ?hidden=${!titled}>
         <slot name="header"></slot>