@aceshooting/lyra-ui 1.2.0 → 2.1.0

package/dist/components/split/split.styles.js

@@ -4,9 +4,16 @@ export const styles = css `
     display: block;
     inline-size: 100%;
     block-size: 100%;
+    /* Component-specific -- not a shared design token, so a consumer can
+       retheme it without a raw literal leaking into the public API (same
+       rationale as lyra-app-rail's --lyra-app-rail-overlay-color). */
+    --lyra-split-overlay-color: rgb(0 0 0 / 0.5);
   }
   [part='base'] {
     display: flex;
+    /* Anchor for the 'floating' collapse state's absolutely-positioned
+       overlay panel (set inline by split.ts's updated()). */
+    position: relative;
     inline-size: 100%;
     block-size: 100%;
   }
@@ -48,4 +55,44 @@ export const styles = css `
     outline: var(--lyra-focus-ring-width) solid var(--lyra-focus-ring-color);
     outline-offset: var(--lyra-focus-ring-offset);
   }
+  /* The divider adjacent to a rail/floating-collapsed pane (see split.ts's
+     isDividerDisabled()) — geometry (position/inset/inline-size) for the
+     collapsing panel itself is set inline by updated(), same as the
+     pre-existing flex/order styling; this only covers the divider's own
+     drag/hover affordance and the floating panel's elevation, which read
+     more naturally as stylesheet rules than one-off inline styles. */
+  [part='divider'][aria-disabled='true'] {
+    cursor: default;
+    pointer-events: none;
+  }
+  /* The 'floating' collapse state's overlay "card" look -- geometry
+     (position/inset-*/inline-size) is set inline by split.ts's updated(),
+     matching how the ordinary flex/order styling is applied; only the
+     visual/stacking treatment lives here. z-index is above [part="backdrop"]
+     (below), so the drawer renders on top of its own scrim. */
+  ::slotted([data-collapse-state='floating']) {
+    z-index: 1;
+    background: var(--lyra-color-surface);
+    border-radius: var(--lyra-radius);
+    box-shadow: var(--lyra-shadow);
+  }
+  /* The 'floating' drawer's scrim -- only rendered while collapseState is
+     'floating' and open (see split.ts's render()). Scoped to [part="base"]
+     (position: absolute against its position: relative ancestor) rather than
+     a viewport-fixed overlay like lyra-app-rail's mobile backdrop: the
+     floating panel itself is only ever positioned relative to this
+     component's own box, never the full page. */
+  [part='backdrop'] {
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    background: var(--lyra-split-overlay-color);
+  }
+  /* Rail-clamped content can easily overflow the fixed rail-width — clip it
+     rather than letting it blow out the layout; the panel's own content is
+     expected to adapt to the narrower width itself (e.g. via a container
+     query), this is just a safety net. */
+  ::slotted([data-collapse-state='rail']) {
+    overflow: hidden;
+  }
 `;

package/dist/components/stat/stat.d.ts

@@ -1,10 +1,14 @@
-import { type TemplateResult } from 'lit';
+import { type TemplateResult, type PropertyValues } from 'lit';
 import { LyraElement } from '../../internal/lyra-element.js';
 export type StatVariant = 'neutral' | 'success' | 'warning' | 'danger';
 export type StatGoodDirection = 'up' | 'down';
 export interface StatRow {
     label: string;
     value: string;
+    /** Exact value shown as a hover/focus tooltip on this row's `row-value` (mirrors the headline
+     *  `exactValue`/`exact-value` behavior). Also makes this row's `[part='row-value']`
+     *  keyboard-focusable so the tooltip is reachable without a pointer. */
+    exactValue?: string;
 }
 /**
  * `<lyra-stat>` — a KPI/stat card. First-party invention consolidating the
@@ -20,7 +24,9 @@ export interface StatRow {
  * @csspart icon - Container for the leading icon slot.
  * @csspart label - The label text.
  * @csspart value-row - Wrapper around the value and unit.
- * @csspart value - The value text.
+ * @csspart value - The value text. Accessibly labelled by the `label` part (via
+ *   `aria-labelledby`) whenever `label` is set, so tabbing directly to this
+ *   (focusable when `exactValue` is set) control still announces which metric it is.
  * @csspart unit - The unit text.
  * @csspart trend - The trend pill.
  * @csspart sub - Container for the `sub` attribute/slot.
@@ -29,7 +35,9 @@ export interface StatRow {
  * @csspart rows - Container for the `rows` breakdown list.
  * @csspart row - A single breakdown row (one per `rows` entry).
  * @csspart row-label - The label text of a breakdown row.
- * @csspart row-value - The value text of a breakdown row.
+ * @csspart row-value - The value text of a breakdown row. Shows the row's `exactValue` (if any) as
+ *   a hover/focus tooltip, same as the headline `value`, and is accessibly labelled by its
+ *   `row-label` (via `aria-labelledby`) the same way the headline `value` is.
  */
 export declare class LyraStat extends LyraElement {
     static styles: import("lit").CSSResultGroup[];
@@ -64,7 +72,10 @@ export declare class LyraStat extends LyraElement {
     private hasCaptionSlot;
     private hasSparkSlot;
     private hasSubSlot;
-    protected willUpdate(): void;
+    private readonly labelId;
+    private readonly valueId;
+    private rowLabelIds;
+    protected willUpdate(changed: PropertyValues): void;
     private onIconSlotChange;
     private onCaptionSlotChange;
     private onSparkSlotChange;

package/dist/components/stat/stat.js

@@ -9,7 +9,7 @@ import { property, state } from 'lit/decorators.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { defineElement } from '../../internal/prefix.js';
 import { chevronIcon } from '../../internal/icons.js';
-import { srOnly } from '../../internal/a11y.js';
+import { nextId, srOnly } from '../../internal/a11y.js';
 import { styles } from './stat.styles.js';
 /**
  * `<lyra-stat>` — a KPI/stat card. First-party invention consolidating the
@@ -25,7 +25,9 @@ import { styles } from './stat.styles.js';
  * @csspart icon - Container for the leading icon slot.
  * @csspart label - The label text.
  * @csspart value-row - Wrapper around the value and unit.
- * @csspart value - The value text.
+ * @csspart value - The value text. Accessibly labelled by the `label` part (via
+ *   `aria-labelledby`) whenever `label` is set, so tabbing directly to this
+ *   (focusable when `exactValue` is set) control still announces which metric it is.
  * @csspart unit - The unit text.
  * @csspart trend - The trend pill.
  * @csspart sub - Container for the `sub` attribute/slot.
@@ -34,7 +36,9 @@ import { styles } from './stat.styles.js';
  * @csspart rows - Container for the `rows` breakdown list.
  * @csspart row - A single breakdown row (one per `rows` entry).
  * @csspart row-label - The label text of a breakdown row.
- * @csspart row-value - The value text of a breakdown row.
+ * @csspart row-value - The value text of a breakdown row. Shows the row's `exactValue` (if any) as
+ *   a hover/focus tooltip, same as the headline `value`, and is accessibly labelled by its
+ *   `row-label` (via `aria-labelledby`) the same way the headline `value` is.
  */
 export class LyraStat extends LyraElement {
     constructor() {
@@ -73,6 +77,16 @@ export class LyraStat extends LyraElement {
         this.hasCaptionSlot = false;
         this.hasSparkSlot = false;
         this.hasSubSlot = false;
+        // Stable id pairing `[part='label']` with `[part='value']` via
+        // aria-labelledby, so a keyboard user tabbing straight to the (focusable,
+        // tooltip-bearing) value still gets an accessible name like "Revenue
+        // $1.2K" instead of the bare value.
+        this.labelId = nextId('stat-label');
+        this.valueId = `${this.labelId}-value`;
+        // One id per `rows` entry, regenerated only when the `rows` array itself is
+        // reassigned (not on every render) so `aria-labelledby` references stay
+        // stable across unrelated re-renders.
+        this.rowLabelIds = [];
         this.onIconSlotChange = (e) => {
             this.hasIcon = e.target.assignedElements({ flatten: true }).length > 0;
         };
@@ -87,16 +101,24 @@ export class LyraStat extends LyraElement {
         };
     }
     static { this.styles = [LyraElement.styles, styles, srOnly]; }
-    willUpdate() {
+    willUpdate(changed) {
         if (!this.hasUpdated) {
             this.hasIcon = Array.from(this.children).some((el) => !el.hasAttribute('slot'));
             this.hasCaptionSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'caption');
             this.hasSparkSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'spark');
             this.hasSubSlot = Array.from(this.children).some((el) => el.getAttribute('slot') === 'sub');
         }
+        if (changed.has('rows')) {
+            this.rowLabelIds = this.rows.map(() => nextId('stat-row-label'));
+        }
     }
     render() {
-        const hasTrend = !isNaN(this.trend);
+        // Lit's built-in Number converter maps a removed/absent attribute to
+        // `null`, not NaN, even though the property is typed `number` — so
+        // `isNaN(this.trend)` alone is false for a cleared attribute and the pill
+        // would reappear showing a fabricated "unchanged, 0%". Treat null/undefined
+        // the same as NaN here instead of trusting the static type.
+        const hasTrend = this.trend != null && !isNaN(this.trend);
         const rawDirection = this.trend > 0 ? 'up' : this.trend < 0 ? 'down' : 'flat';
         const isGood = rawDirection === 'flat' ? null : rawDirection === this.goodDirection;
         // The trend pill previously rendered literal ▲/▼ glyphs — font-dependent
@@ -117,9 +139,14 @@ export class LyraStat extends LyraElement {
         <span part="icon" ?hidden=${!this.hasIcon}
           ><slot @slotchange=${this.onIconSlotChange}></slot
         ></span>
-        <span part="label">${this.label}</span>
+        <span part="label" id=${this.labelId}>${this.label}</span>
         <div part="value-row">
-          <span part="value" title=${this.exactValue || nothing} tabindex=${this.exactValue ? '0' : nothing}
+          <span
+            part="value"
+            id=${this.valueId}
+            title=${this.exactValue || nothing}
+            tabindex=${this.exactValue ? '0' : nothing}
+            aria-labelledby=${this.label ? `${this.labelId} ${this.valueId}` : nothing}
             >${this.value}</span
           >
           <span part="unit">${this.unit}</span>
@@ -135,7 +162,7 @@ export class LyraStat extends LyraElement {
             </span>`
             : nothing}
         <div part="sub" ?hidden=${!hasSub}>
-          ${this.sub}<slot name="sub" @slotchange=${this.onSubSlotChange}></slot>
+          <slot name="sub" @slotchange=${this.onSubSlotChange}>${this.sub}</slot>
         </div>
         <div part="spark" ?hidden=${!this.hasSparkSlot}>
           <slot name="spark" @slotchange=${this.onSparkSlotChange}></slot>
@@ -144,12 +171,23 @@ export class LyraStat extends LyraElement {
           <slot name="caption" @slotchange=${this.onCaptionSlotChange}>${this.caption}</slot>
         </div>
         <div part="rows" ?hidden=${this.rows.length === 0}>
-          ${this.rows.map((row) => html `
+          ${this.rows.map((row, i) => {
+            const rowLabelId = this.rowLabelIds[i];
+            const rowValueId = `${rowLabelId}-value`;
+            return html `
               <div part="row">
-                <span part="row-label">${row.label}</span>
-                <span part="row-value">${row.value}</span>
+                <span part="row-label" id=${rowLabelId}>${row.label}</span>
+                <span
+                  part="row-value"
+                  id=${rowValueId}
+                  title=${row.exactValue || nothing}
+                  tabindex=${row.exactValue ? '0' : nothing}
+                  aria-labelledby=${row.label ? `${rowLabelId} ${rowValueId}` : nothing}
+                  >${row.value}</span
+                >
               </div>
-            `)}
+            `;
+        })}
         </div>
       </div>
     `;
@@ -206,4 +244,7 @@ __decorate([
 __decorate([
     state()
 ], LyraStat.prototype, "hasSubSlot", void 0);
+__decorate([
+    state()
+], LyraStat.prototype, "rowLabelIds", void 0);
 defineElement('stat', LyraStat);

package/dist/components/stream-status/stream-status.d.ts

@@ -0,0 +1,126 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../live-region/live-region.js';
+export type StreamStatusPhase = 'idle' | 'connecting' | 'streaming' | 'stalled';
+/**
+ * `<lyra-stream-status>` — a compact status indicator for a single streaming
+ * connection (SSE, WebSocket, long-poll, …), with built-in heartbeat-aware
+ * stall detection.
+ *
+ * The host drives `phase` directly for `idle`/`connecting`/`streaming`, and
+ * calls `recordActivity()` on every *semantic* frame received while
+ * streaming — a real content chunk, never a transport-level keep-alive ping.
+ * This component has no payload-inspection logic of its own: "ignore
+ * heartbeats" is entirely a call-site discipline — the host simply never
+ * calls `recordActivity()` for a ping, so pings never reset the stall timer
+ * and a connection that's only sending keep-alives (no real content) for
+ * longer than `stall-threshold-ms` correctly reads as stalled.
+ *
+ * Internally, an inactivity timer runs only while `phase === 'streaming'`.
+ * It's (re)armed whenever the phase transitions to `'streaming'` (directly,
+ * or via `recordActivity()` recovering from `'stalled'`), on every
+ * subsequent `recordActivity()` call while already streaming, whenever
+ * `stall-threshold-ms` itself changes while already streaming (the new
+ * value takes effect immediately, the same way `<lyra-toast-item>`'s
+ * `duration` re-applies mid-flight, rather than waiting for the next
+ * `recordActivity()`/phase change), and whenever this element (re)connects
+ * to the DOM while `phase` is still `'streaming'` (a disconnect always
+ * disarms it, so moving the element elsewhere in the page — disconnect then
+ * reconnect with `phase` unchanged — must resume detection rather than
+ * silently disabling it for the rest of the streaming session). It's
+ * disarmed the instant `phase` becomes anything else, including a
+ * host-driven reassignment away from `'streaming'` — so a stale timer can
+ * never fire a stall transition after the host has already moved on. If it
+ * ever fires, `phase` becomes `'stalled'` and `lyra-stall` is dispatched.
+ *
+ * `phase` remains a fully public, directly settable property at all times —
+ * a host can assign `'stalled'` (or any other phase) itself as a manual
+ * override, and this component never fights that assignment. `lyra-stall`/
+ * `lyra-recover` fire on *any* transition into/out of `'stalled'`
+ * respectively, whether timer-driven or host-driven, and never for a
+ * reassignment to the same value (Lit's default `hasChanged` already skips a
+ * no-op set, same as every other reflected `@property` in this library).
+ * Like `<lyra-chat-message>`'s `status`, whatever phase this element happens
+ * to *mount* with is never itself treated as an eventful transition — only a
+ * later change fires an event or an announcement.
+ *
+ * Accessibility: phase transitions into/out of `'stalled'` are announced
+ * through an internal `<lyra-live-region>` (see that component for the
+ * throttled/coalesced-announcement machinery this composes) rather than a
+ * hand-rolled `aria-live` region. `recordActivity()` itself never announces
+ * anything, no matter how often the host calls it — only the *transition*
+ * announces, exactly once per transition, which is the entire point of
+ * routing through the throttled announcer instead of writing to a live
+ * region on every call. Entering `'stalled'` announces with `mode="assertive"`
+ * (a stall can need the user's attention, e.g. before they give up and
+ * navigate away); leaving `'stalled'` always announces with `mode="polite"`
+ * (good news doesn't need to interrupt), but the *wording* depends on where
+ * it lands: `"Connection restored."` only when the destination is
+ * `'streaming'` (a genuine recovery), or a neutral `"No longer stalled."`
+ * when the destination is `'idle'`/`'connecting'` instead — that's the host
+ * giving up on the stream, not the stream recovering, and a screen-reader
+ * user must never be told the opposite of what a sighted user sees on
+ * screen. The decorative indicator dot is `aria-hidden` — it's a
+ * color/motion cue only, never the sole carrier of state.
+ *
+ * Visual: `'stalled'` is styled as a warning, not a danger — a stall is
+ * usually recoverable (the stream may resume on its own, or the host's own
+ * retry logic may kick in), so treating it as an actionable warning rather
+ * than a hard failure keeps the tone proportionate. A host that wants to
+ * escalate to danger styling after N stalls can scope its own CSS off
+ * `[phase="stalled"]`, or simply stop rendering this component and show its
+ * own danger-styled error state instead.
+ *
+ * @customElement lyra-stream-status
+ * @slot - Custom copy shown only while `phase="stalled"` (e.g. "Taking longer than usual…"). A sensible built-in default is used when nothing is slotted.
+ * @slot actions - A stop/retry button row. Always present in the template regardless of `phase` — visibility is driven purely by whether anything is slotted, not by `phase`; what to put here, and when, is entirely the host's call.
+ * @event lyra-stall - Fired whenever `phase` transitions into `'stalled'` from anything else (timer-driven, or a direct host assignment).
+ * @event lyra-recover - Fired whenever `phase` transitions out of `'stalled'` to anything else (via `recordActivity()`, or a direct host assignment) — fired unconditionally regardless of destination phase, even though the accompanying announcement's wording varies (see the class doc's "Accessibility" section).
+ * @csspart base - The root layout container.
+ * @csspart indicator - The decorative (`aria-hidden`) status dot.
+ * @csspart message - Wrapper around the default slot; only rendered while `phase="stalled"`.
+ * @csspart actions - Wrapper around the `actions` slot.
+ */
+export declare class LyraStreamStatus extends LyraElement {
+    static styles: import("lit").CSSResultGroup[];
+    /** Current connection phase. Settable directly by the host at any time —
+     *  see the class doc for how that interacts with the internal stall timer. */
+    phase: StreamStatusPhase;
+    /** How long `phase` may stay `'streaming'` with no `recordActivity()` call
+     *  before this component declares it stalled. */
+    stallThresholdMs: number;
+    private stallTimer?;
+    private hasActionsSlot;
+    private hasMessageContent;
+    private liveRegion?;
+    protected willUpdate(): void;
+    protected updated(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Call on every semantic (non-heartbeat) frame received while streaming.
+     * - While `phase === 'streaming'`: (re)arms the stall timer, pushing the
+     *   stall deadline `stall-threshold-ms` further out.
+     * - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'`
+     *   again, `lyra-recover` fires, and the stall timer is armed fresh (same
+     *   as the bullet above), all via the same `updated()` transition handling
+     *   a direct host assignment would also go through.
+     * - While `phase` is `'idle'` or `'connecting'`: a no-op. A host may call
+     *   this defensively before formally flipping to `'streaming'`; it must
+     *   never throw or start a timer early.
+     */
+    recordActivity(): void;
+    private onPhaseChanged;
+    private armStallTimer;
+    private disarmStallTimer;
+    private announceTransition;
+    private hasSlotted;
+    private onActionsSlotChange;
+    private onMessageSlotChange;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lyra-stream-status': LyraStreamStatus;
+    }
+}

package/dist/components/stream-status/stream-status.js

@@ -0,0 +1,292 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing } from 'lit';
+import { property, state, query } from 'lit/decorators.js';
+import { LyraElement } from '../../internal/lyra-element.js';
+import { defineElement } from '../../internal/prefix.js';
+import '../live-region/live-region.js';
+import { styles } from './stream-status.styles.js';
+const DEFAULT_STALL_MESSAGE = 'Taking longer than usual…';
+const STALL_ANNOUNCEMENT = 'Connection stalled.';
+const RECOVER_ANNOUNCEMENT = 'Connection restored.';
+// Used instead of RECOVER_ANNOUNCEMENT when a stall is left behind by moving
+// to 'idle'/'connecting' rather than back to 'streaming' -- see
+// announceTransition()'s caller in onPhaseChanged() for why "restored" would
+// be actively misleading in that case.
+const STALL_CLEARED_ANNOUNCEMENT = 'No longer stalled.';
+// The default slot's stalled-message content is often plain text with no
+// wrapping element at all (see the CustomStalledMessage story), so an
+// Element-only check never counts it, and ordinary indented-markup
+// whitespace (a newline + indentation before a slotted `actions` button, as
+// in the DefaultStalledMessage story) must not count either -- native <slot>
+// fallback content is suppressed by *any* assigned node, whitespace or not,
+// which previously left the message area blank in exactly that common case.
+// Mirrors lyra-citation-badge's identical isRealPreviewNode: a node counts as
+// real message content if it's an element not assigned to some other named
+// slot (e.g. `actions`), or non-whitespace text.
+function isRealMessageNode(n) {
+    return n.nodeType === Node.ELEMENT_NODE
+        ? !n.hasAttribute('slot')
+        : (n.textContent ?? '').trim().length > 0;
+}
+/**
+ * `<lyra-stream-status>` — a compact status indicator for a single streaming
+ * connection (SSE, WebSocket, long-poll, …), with built-in heartbeat-aware
+ * stall detection.
+ *
+ * The host drives `phase` directly for `idle`/`connecting`/`streaming`, and
+ * calls `recordActivity()` on every *semantic* frame received while
+ * streaming — a real content chunk, never a transport-level keep-alive ping.
+ * This component has no payload-inspection logic of its own: "ignore
+ * heartbeats" is entirely a call-site discipline — the host simply never
+ * calls `recordActivity()` for a ping, so pings never reset the stall timer
+ * and a connection that's only sending keep-alives (no real content) for
+ * longer than `stall-threshold-ms` correctly reads as stalled.
+ *
+ * Internally, an inactivity timer runs only while `phase === 'streaming'`.
+ * It's (re)armed whenever the phase transitions to `'streaming'` (directly,
+ * or via `recordActivity()` recovering from `'stalled'`), on every
+ * subsequent `recordActivity()` call while already streaming, whenever
+ * `stall-threshold-ms` itself changes while already streaming (the new
+ * value takes effect immediately, the same way `<lyra-toast-item>`'s
+ * `duration` re-applies mid-flight, rather than waiting for the next
+ * `recordActivity()`/phase change), and whenever this element (re)connects
+ * to the DOM while `phase` is still `'streaming'` (a disconnect always
+ * disarms it, so moving the element elsewhere in the page — disconnect then
+ * reconnect with `phase` unchanged — must resume detection rather than
+ * silently disabling it for the rest of the streaming session). It's
+ * disarmed the instant `phase` becomes anything else, including a
+ * host-driven reassignment away from `'streaming'` — so a stale timer can
+ * never fire a stall transition after the host has already moved on. If it
+ * ever fires, `phase` becomes `'stalled'` and `lyra-stall` is dispatched.
+ *
+ * `phase` remains a fully public, directly settable property at all times —
+ * a host can assign `'stalled'` (or any other phase) itself as a manual
+ * override, and this component never fights that assignment. `lyra-stall`/
+ * `lyra-recover` fire on *any* transition into/out of `'stalled'`
+ * respectively, whether timer-driven or host-driven, and never for a
+ * reassignment to the same value (Lit's default `hasChanged` already skips a
+ * no-op set, same as every other reflected `@property` in this library).
+ * Like `<lyra-chat-message>`'s `status`, whatever phase this element happens
+ * to *mount* with is never itself treated as an eventful transition — only a
+ * later change fires an event or an announcement.
+ *
+ * Accessibility: phase transitions into/out of `'stalled'` are announced
+ * through an internal `<lyra-live-region>` (see that component for the
+ * throttled/coalesced-announcement machinery this composes) rather than a
+ * hand-rolled `aria-live` region. `recordActivity()` itself never announces
+ * anything, no matter how often the host calls it — only the *transition*
+ * announces, exactly once per transition, which is the entire point of
+ * routing through the throttled announcer instead of writing to a live
+ * region on every call. Entering `'stalled'` announces with `mode="assertive"`
+ * (a stall can need the user's attention, e.g. before they give up and
+ * navigate away); leaving `'stalled'` always announces with `mode="polite"`
+ * (good news doesn't need to interrupt), but the *wording* depends on where
+ * it lands: `"Connection restored."` only when the destination is
+ * `'streaming'` (a genuine recovery), or a neutral `"No longer stalled."`
+ * when the destination is `'idle'`/`'connecting'` instead — that's the host
+ * giving up on the stream, not the stream recovering, and a screen-reader
+ * user must never be told the opposite of what a sighted user sees on
+ * screen. The decorative indicator dot is `aria-hidden` — it's a
+ * color/motion cue only, never the sole carrier of state.
+ *
+ * Visual: `'stalled'` is styled as a warning, not a danger — a stall is
+ * usually recoverable (the stream may resume on its own, or the host's own
+ * retry logic may kick in), so treating it as an actionable warning rather
+ * than a hard failure keeps the tone proportionate. A host that wants to
+ * escalate to danger styling after N stalls can scope its own CSS off
+ * `[phase="stalled"]`, or simply stop rendering this component and show its
+ * own danger-styled error state instead.
+ *
+ * @customElement lyra-stream-status
+ * @slot - Custom copy shown only while `phase="stalled"` (e.g. "Taking longer than usual…"). A sensible built-in default is used when nothing is slotted.
+ * @slot actions - A stop/retry button row. Always present in the template regardless of `phase` — visibility is driven purely by whether anything is slotted, not by `phase`; what to put here, and when, is entirely the host's call.
+ * @event lyra-stall - Fired whenever `phase` transitions into `'stalled'` from anything else (timer-driven, or a direct host assignment).
+ * @event lyra-recover - Fired whenever `phase` transitions out of `'stalled'` to anything else (via `recordActivity()`, or a direct host assignment) — fired unconditionally regardless of destination phase, even though the accompanying announcement's wording varies (see the class doc's "Accessibility" section).
+ * @csspart base - The root layout container.
+ * @csspart indicator - The decorative (`aria-hidden`) status dot.
+ * @csspart message - Wrapper around the default slot; only rendered while `phase="stalled"`.
+ * @csspart actions - Wrapper around the `actions` slot.
+ */
+export class LyraStreamStatus extends LyraElement {
+    constructor() {
+        super(...arguments);
+        /** Current connection phase. Settable directly by the host at any time —
+         *  see the class doc for how that interacts with the internal stall timer. */
+        this.phase = 'idle';
+        /** How long `phase` may stay `'streaming'` with no `recordActivity()` call
+         *  before this component declares it stalled. */
+        this.stallThresholdMs = 10000;
+        this.hasActionsSlot = false;
+        // Seeded from light-DOM childNodes in willUpdate() (mirrors hasActionsSlot
+        // above), then kept current via onMessageSlotChange() -- see
+        // isRealMessageNode()'s doc comment for why native <slot> fallback content
+        // can't be relied on for the default stalled-message text.
+        this.hasMessageContent = false;
+        this.onActionsSlotChange = (e) => {
+            this.hasActionsSlot = e.target.assignedElements({ flatten: true }).length > 0;
+        };
+        this.onMessageSlotChange = (e) => {
+            this.hasMessageContent = e.target.assignedNodes({ flatten: true }).some(isRealMessageNode);
+        };
+    }
+    static { this.styles = [LyraElement.styles, styles]; }
+    willUpdate() {
+        if (!this.hasUpdated) {
+            this.hasActionsSlot = this.hasSlotted('actions');
+            this.hasMessageContent = Array.from(this.childNodes).some(isRealMessageNode);
+        }
+    }
+    // `changed.get('phase')` is `undefined` on the very first update, for the
+    // same reason documented on lyra-chat-message's identical `updated()`
+    // guard: Lit only records the *first* old value seen since the last
+    // completed update, and the constructor's field-initializer assignment is
+    // that first change, from the truly-unset internal slot. That naturally
+    // skips firing an event/announcement for whatever phase this element
+    // happens to mount with, while still arming the stall timer below if it
+    // mounts already `'streaming'`.
+    //
+    // The `else if` below only matters while `phase` itself didn't also change
+    // in this same update -- if it did, onPhaseChanged() above already
+    // (re)armed the timer with the current `stallThresholdMs`, so re-arming it
+    // again here would just be redundant, not wrong, but the `else` skips that
+    // double work.
+    updated(changed) {
+        if (changed.has('phase')) {
+            this.onPhaseChanged(changed.get('phase'));
+        }
+        else if (changed.has('stallThresholdMs') && this.phase === 'streaming') {
+            // Unlike `phase` itself, `stallThresholdMs` has no dedicated handler --
+            // the already-armed timer was scheduled against the *old* value and
+            // keeps counting down against it otherwise, so a shortened (or
+            // lengthened) threshold would silently have no effect until the next
+            // recordActivity() call or phase transition happened to re-arm it.
+            this.armStallTimer();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        // A disconnect always disarms the timer (see disconnectedCallback()
+        // below), but reparenting this element elsewhere in the page while still
+        // `'streaming'` fires disconnectedCallback then connectedCallback with
+        // `phase` unchanged -- no `updated()` cycle runs in between, so nothing
+        // else would ever re-arm it. Without this, a reparent mid-stream would
+        // permanently disable stall detection for the rest of that streaming
+        // session.
+        if (this.phase === 'streaming')
+            this.armStallTimer();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.disarmStallTimer();
+    }
+    /**
+     * Call on every semantic (non-heartbeat) frame received while streaming.
+     * - While `phase === 'streaming'`: (re)arms the stall timer, pushing the
+     *   stall deadline `stall-threshold-ms` further out.
+     * - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'`
+     *   again, `lyra-recover` fires, and the stall timer is armed fresh (same
+     *   as the bullet above), all via the same `updated()` transition handling
+     *   a direct host assignment would also go through.
+     * - While `phase` is `'idle'` or `'connecting'`: a no-op. A host may call
+     *   this defensively before formally flipping to `'streaming'`; it must
+     *   never throw or start a timer early.
+     */
+    recordActivity() {
+        if (this.phase === 'streaming') {
+            this.armStallTimer();
+        }
+        else if (this.phase === 'stalled') {
+            this.phase = 'streaming';
+        }
+    }
+    onPhaseChanged(previous) {
+        if (this.phase === 'streaming') {
+            this.armStallTimer();
+        }
+        else {
+            this.disarmStallTimer();
+        }
+        if (previous === undefined)
+            return;
+        if (this.phase === 'stalled' && previous !== 'stalled') {
+            this.emit('lyra-stall');
+            this.announceTransition('assertive', STALL_ANNOUNCEMENT);
+        }
+        else if (previous === 'stalled' && this.phase !== 'stalled') {
+            // `lyra-recover` fires unconditionally -- a host may still want the
+            // event for any exit from 'stalled' -- but the *announced text* must
+            // not claim the connection was "restored" when the destination is
+            // 'idle'/'connecting': that's the host abandoning the stream, not it
+            // recovering, and telling a screen-reader user otherwise would be the
+            // opposite of what a sighted user sees on screen.
+            this.emit('lyra-recover');
+            const text = this.phase === 'streaming' ? RECOVER_ANNOUNCEMENT : STALL_CLEARED_ANNOUNCEMENT;
+            this.announceTransition('polite', text);
+        }
+    }
+    armStallTimer() {
+        this.disarmStallTimer();
+        const threshold = this.stallThresholdMs;
+        if (!Number.isFinite(threshold) || threshold <= 0)
+            return;
+        this.stallTimer = setTimeout(() => {
+            this.stallTimer = undefined;
+            this.phase = 'stalled';
+        }, threshold);
+    }
+    disarmStallTimer() {
+        if (this.stallTimer !== undefined) {
+            clearTimeout(this.stallTimer);
+            this.stallTimer = undefined;
+        }
+    }
+    announceTransition(mode, text) {
+        const region = this.liveRegion;
+        if (!region)
+            return;
+        region.mode = mode;
+        region.announce(text, { force: true });
+    }
+    hasSlotted(name) {
+        return Array.from(this.children).some((el) => el.getAttribute('slot') === name);
+    }
+    render() {
+        return html `
+      <div part="base">
+        <span part="indicator" aria-hidden="true"></span>
+        ${this.phase === 'stalled'
+            ? html `<div part="message">
+              <slot @slotchange=${this.onMessageSlotChange}></slot>${this.hasMessageContent
+                ? nothing
+                : DEFAULT_STALL_MESSAGE}
+            </div>`
+            : nothing}
+        <div part="actions" ?hidden=${!this.hasActionsSlot}>
+          <slot name="actions" @slotchange=${this.onActionsSlotChange}></slot>
+        </div>
+        <lyra-live-region></lyra-live-region>
+      </div>
+    `;
+    }
+}
+__decorate([
+    property({ reflect: true })
+], LyraStreamStatus.prototype, "phase", void 0);
+__decorate([
+    property({ type: Number, attribute: 'stall-threshold-ms' })
+], LyraStreamStatus.prototype, "stallThresholdMs", void 0);
+__decorate([
+    state()
+], LyraStreamStatus.prototype, "hasActionsSlot", void 0);
+__decorate([
+    state()
+], LyraStreamStatus.prototype, "hasMessageContent", void 0);
+__decorate([
+    query('lyra-live-region')
+], LyraStreamStatus.prototype, "liveRegion", void 0);
+defineElement('stream-status', LyraStreamStatus);