@wix/himalaya-cli 0.1306.0 → 0.1307.0

package/templates/restaurant-owner/tier5-src/himi-owner-lite-aria/index.ts

@@ -34,6 +34,8 @@ import { alert } from "@himalaya/ui";
 import {
   activeSiteId,
   createAriaChat,
+  authoredRealtimeUrl,
+  stashRealtimeUrl,
   type AriaActionArg,
   type AriaChatState,
   type AriaDictationResult,
@@ -53,6 +55,10 @@ const SERVICE = "himiOwnerLiteAria";
 // clone's blocking loop, which paints nothing for the length of a turn.
 const FAST_MS = 2000;
 const IDLE_MS = 15000;
+// While the realtime stream is delivering a reply, the transcript is only read to
+// CONFIRM the turn ended — the words come from the stream — so the ladder runs at
+// this slower rate. A whole interval with no frame drops it back to FAST_MS.
+const STREAM_MS = 6000;
 
 function prompts(): AriaPromptChip[] {
   return [
@@ -250,7 +256,13 @@ const core = createAriaChat({
     const screenId = screenForUrl(url, allowedTargets());
     return screenId ? { screenId } : null;
   },
-  poll: { action: `${SERVICE}.tick`, fastMs: FAST_MS, idleMs: IDLE_MS },
+  poll: { action: `${SERVICE}.tick`, fastMs: FAST_MS, idleMs: IDLE_MS, streamMs: STREAM_MS },
+  // The realtime stream: the reply's words as they are written, plus the quick
+  // replies that follow it. Only where the screen was built with a stream url
+  // (authored onAppear load params); everywhere else — and wherever the host cannot
+  // open it — the turn is polled exactly as before. The screen must declare
+  // "stream" for the host to open it at all.
+  stream: { url: authoredRealtimeUrl },
   // Composer dictation, on the platform recognizer: SFSpeechRecognizer,
   // Android SpeechRecognizer, Web Speech. No audio crosses the bridge — only the
   // final transcript. An empty language means the device's own locale, which is
@@ -319,6 +331,12 @@ const svc = defineService<AriaChatState, {
   finishDictation: (s: AriaChatState) => AriaChatState;
   // `undefined` for a result whose session is no longer the live one — see the core.
   dictated: (s: AriaChatState, arg?: AriaDictationResult) => AriaChatState | undefined;
+  // The realtime stream's callbacks, named by the `_stream` directive the core
+  // returns from a send — never by the descriptor. `undefined` from
+  // `streamEvent` for the same reason `tick` has it.
+  streamEvent: (s: AriaChatState, event?: unknown) => Promise<AriaChatState | undefined>;
+  streamEnded: (s: AriaChatState) => AriaChatState;
+  streamFailed: (s: AriaChatState, err?: unknown) => AriaChatState;
   mentionOpen: (s: AriaChatState) => Promise<AriaChatState | undefined>;
   mentionClose: (s: AriaChatState) => AriaChatState;
   mentionBack: (s: AriaChatState) => AriaChatState;
@@ -334,7 +352,7 @@ const svc = defineService<AriaChatState, {
   state: core.initialState,
   actions: {
     // `load` is the onAppear dispatch, so it is where the copy pack arrives.
-    load: (s, arg) => { stashCopy(arg); stashTargets(arg); return core.load(s); },
+    load: (s, arg) => { stashCopy(arg); stashTargets(arg); stashRealtimeUrl(arg); return core.load(s); },
     submit: core.submit,
     submitPrompt: core.submitPrompt,
     newChat: core.newChat,
@@ -391,6 +409,12 @@ const svc = defineService<AriaChatState, {
     attachmentSettled: core.attachmentSettled,
     removeAttachment: core.removeAttachment,
     retryAttachment: core.retryAttachment,
+    // Dispatched by the HOST as the stream delivers, closes or fails. A name
+    // the entry does not export is a callback the host silently drops, and the
+    // turn would then be polled with nobody noticing the stream was ignored.
+    streamEvent: core.streamEvent,
+    streamEnded: core.streamEnded,
+    streamFailed: core.streamFailed,
   },
 });
 

package/templates/retail-store-owner/dev/index.ts

@@ -56523,7 +56523,8 @@ const SCREENS = runtimeSetting({
                                         "props": {
                                           "text": "$item.content",
                                           "style": "body",
-                                          "maxLines": 50
+                                          "maxLines": 50,
+                                          "animateReveal": true
                                         }
                                       },
                                       "modifiers": {
@@ -57031,7 +57032,7 @@ const SCREENS = runtimeSetting({
               }
             },
             {
-              "id": "himi_owner_lite_aria.stop",
+              "id": "",
               "body": {
                 "package": "himalaya",
                 "type": "HStack",
@@ -57047,30 +57048,19 @@ const SCREENS = runtimeSetting({
                       }
                     },
                     {
-                      "id": "",
-                      "body": {
-                        "package": "himalaya",
-                        "type": "Icon",
-                        "props": {
-                          "name": "close",
-                          "size": 14,
-                          "tint": "accentPrimary"
-                        }
-                      },
-                      "modifiers": {
-                        "accessibilityRole": "decorative"
-                      }
-                    },
-                    {
-                      "id": "",
+                      "id": "himi_owner_lite_aria.stop",
                       "body": {
                         "package": "himalaya",
-                        "type": "Text",
+                        "type": "Button",
                         "props": {
-                          "text": "Stop",
-                          "style": "footnote",
-                          "color": "accentPrimary",
-                          "maxLines": 1
+                          "title": "Stop",
+                          "style": "link",
+                          "size": "sm",
+                          "leadingIcon": "close",
+                          "fullWidth": false,
+                          "action": {
+                            "actionId": "tier5.himiOwnerLiteAria.stop"
+                          }
                         }
                       }
                     }
@@ -57084,9 +57074,6 @@ const SCREENS = runtimeSetting({
                   "top": 4,
                   "bottom": 0
                 },
-                "onTap": {
-                  "actionId": "tier5.himiOwnerLiteAria.stop"
-                },
                 "hiddenPath": "$service:himiOwnerLiteAria.stopHidden"
               }
             },
@@ -60814,7 +60801,8 @@ const SCREENS = runtimeSetting({
         "ui",
         "speech",
         "camera",
-        "presigned_upload"
+        "presigned_upload",
+        "stream"
       ],
       "minBinaryVersion": "0.1.0",
       "bundleVersion": "0.0.1"

package/templates/retail-store-owner/tier5-src/_shared/aria-chat.ts

@@ -24,7 +24,7 @@
 // This file is copied verbatim into every generated starter app, so it explains
 // itself without pointing at anything only this repo has.
 
-import { navigate, type NavDirective, type PollDirective } from "@himalaya/state";
+import { navigate, type NavDirective, type PollDirective, type StreamDirective } from "@himalaya/state";
 import {
   ARIA_ORIGIN,
   abortAssistantMessageGeneration,
@@ -90,6 +90,7 @@ import { MENTION_PAGE_SIZE, allowlisted, emptyMentionModel, mentionView,
   type MentionItemRow, type MentionLabels, type MentionModel, type MentionProvider, type MentionView } from "./aria-mentions.js";
 import { isTransportFailure, ownerTransportFailureText } from "./owner-load-error.js";
 import { LOCAL_ID_PREFIX, createRowMemo, mintLocalId, transcriptKeys, type RowMemo } from "./aria-hot-path.js";
+import { createLiveReply } from "./aria-stream.js";
 import { calendarDay, formatClock, formatDateMedium, formatMonthDay } from "./engine-intl.js";
 
 // ---------------------------------------------------------------------------
@@ -280,13 +281,35 @@ export interface AriaChatState {
   attachments: AriaAttachmentChip[];
   /** Collapses the composer's attachment strip while it is empty. */
   attachmentsHidden: boolean;
-  /** Transient host directives — a poll cadence to install, and a navigation to
-   *  perform. The runtime strips both before storing the state, so they are
-   *  never persisted and never re-fire when the state is spread. */
+  /** The quick replies the service suggested after the LATEST turn — short
+   *  answers the owner can send with one tap. They arrive only on the realtime
+   *  stream, a moment after the reply finishes, so a screen with no stream never
+   *  has any. A projection like `attachments`: painted on the way out of every
+   *  action, and empty again the moment a new turn is sent. */
+  quickReplies: AriaQuickReply[];
+  /** Collapses a quick-reply strip while there is nothing to offer. */
+  quickRepliesHidden: boolean;
+  /** Where the realtime stream for the current turn is: `off` (no stream was
+   *  opened — the screen has none configured), `open` (asked for, nothing
+   *  heard yet), `live` (frames are arriving) or `down` (it closed or failed;
+   *  the poll is carrying the turn). Diagnostic — nothing binds it. */
+  _realtime: AriaRealtime;
+  /** Transient host directives — a poll cadence to install, a stream to open,
+   *  and a navigation to perform. The runtime strips all three before storing
+   *  the state, so they are never persisted and never re-fire when the state is
+   *  spread. */
   _poll?: PollDirective;
+  _stream?: StreamDirective;
   _nav?: NavDirective;
 }
 
+/** One suggested reply, flattened for a `$item.` row: `label` is the chip,
+ *  `reply` the text a tap sends, `id` a stable row id within the strip. */
+export interface AriaQuickReply { id: string; label: string; reply: string; }
+
+/** See `AriaChatState._realtime`. */
+export type AriaRealtime = "off" | "open" | "live" | "down";
+
 /** Cadence for the reply ladder. Absent ⇒ the legacy in-action busy loop. */
 export interface AriaPollOptions {
   /** Fully-qualified `"<service>.tick"`. A name that does not resolve to a real
@@ -300,6 +323,26 @@ export interface AriaPollOptions {
    *  re-armed slower instead — a visible Aria screen keeps ONE low-rate GET
    *  alive until the screen is backgrounded, pooled away or torn down. */
   idleMs: number;
+  /** While the realtime stream is DELIVERING the reply. The words come from the
+   *  stream then, and the transcript is only read to confirm the turn ended, so
+   *  the ladder can run slower than `fastMs`. A whole interval with no frame is a
+   *  stalled stream, and the ladder drops back to `fastMs`. Absent ⇒ the ladder
+   *  stays at `fastMs` throughout. */
+  streamMs?: number;
+}
+
+/** The realtime stream (the `_stream` directive). Omit it and the
+ *  conversation machine polls exactly as it always has. */
+export interface AriaStreamOptions {
+  /** Base url of an SSE stream that re-emits the chat-service's side-effect
+   *  frames, one `data:` event per frame (see `decodeSideEffect` in the
+   *  genie-chat client). Read at SEND time; an empty string means "no stream
+   *  here", and the turn is polled. The worker appends `conversationId` and, when
+   *  the service named the turn, `userMessageId`. */
+  url: () => string;
+  /** Ask the host to attach its Wix credentials to the open request using the platform's
+   *  `authorize`). Only for a url that should receive them. */
+  authorize?: boolean;
 }
 
 /** A value or a thunk for it. User-facing copy is read through `copyParam` at
@@ -506,6 +549,10 @@ export interface AriaChatOptions {
    *  authored `himi.open` gets — and a miss falls through to `openLink`. */
   resolveEntity?: (url: string) => NavDirective | null;
   poll?: AriaPollOptions;
+  /** The realtime stream. Meaningful only with `poll`: the stream paints the
+   *  reply as it is written, and the poll stays the thing that ends the turn —
+   *  and the whole of it wherever no stream can be opened. */
+  stream?: AriaStreamOptions;
   /** Mirror conversation titles into `himalaya.storage` as an offline fallback
    *  for the history screen. Default true (the clone's behaviour).
    *
@@ -619,8 +666,7 @@ const PLAIN_HOST = /^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)*|\[[0-9a-f:.]+\])$/;
  *    treats `\` exactly like `/`. Without that, `https://evil.example\@wix.com/`
  *    reads as `wix.com` here while every browser opens `evil.example` with the
  *    path `/@wix.com/`. That is exactly the lie this disclosure exists to
- *    prevent, so the separator set has to match the URL standard's rather than
- *    RFC 3986's.
+ *    prevent, so the separators have to match what browsers use when parsing web addresses.
  *
  *  A string that survives parsing but is not a plain hostname returns "", which
  *  callers must treat as untrusted rather than as "there is no host here". */
@@ -1237,6 +1283,16 @@ export function inputConversationId(): string {
   return (input?.conversationId ?? input?.id ?? "").trim();
 }
 
+// Authored onAppear parameters supply the endpoint. Navigation input is untrusted:
+// a deep link must never choose where the assistant sends turn identifiers.
+let realtimeUrl = "";
+export function stashRealtimeUrl(arg: unknown): void {
+  const v = arg && typeof arg === "object" ? (arg as Record<string, unknown>).ariaRealtimeUrl : undefined;
+  const url = typeof v === "string" ? v.trim() : "";
+  realtimeUrl = /^https?:\/\/[^\s]+\/v1\/aria\/realtime$/i.test(url) ? url : "";
+}
+export function authoredRealtimeUrl(): string { return realtimeUrl; }
+
 // ---------------------------------------------------------------------------
 // The chat core
 // ---------------------------------------------------------------------------
@@ -1362,9 +1418,24 @@ export interface AriaChatCore {
   removeAttachment(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
   /** Re-send a failed chip's bytes from the copy it already holds. */
   retryAttachment(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** One event of the realtime stream, dispatched by the HOST (the `_stream`
+   *  directive's `onEvent`). Never named by a descriptor. Resolves to
+   *  `undefined` — leave the state untouched — when the transcript read a
+   *  completion triggers went stale across a turn boundary, on `tick`'s terms. */
+  streamEvent(s: AriaChatState, event?: unknown): Promise<AriaChatState | undefined>;
+  /** The stream closed (`onDone`) or failed (`onError`). Either way the poll
+   *  carries the rest of the turn, at the full rate. */
+  streamEnded(s: AriaChatState): AriaChatState;
+  streamFailed(s: AriaChatState, err?: unknown): AriaChatState;
 }
 
 const POLL_ID = "aria-turn";
+/** The one realtime stream a screen holds. A new turn opens it again under the
+ *  SAME id, which is what closes the previous turn's: the host supersedes a
+ *  stream by id, and the worker has no other way to close one. */
+const STREAM_ID = "aria-realtime";
+/** Prefix of the id of a reply bubble that so far exists only on the stream. */
+const LIVE_ID_PREFIX = "live-";
 /** What Regenerate sends. Ordinary user text, matching the native Aria app —
  *  the chat-service has no retry verb, and inventing one here would be a
  *  protocol we then had to keep. */
@@ -1549,6 +1620,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     listening: false, micHidden: !o.dictation, listeningHidden: true,
     widget: NO_WIDGET, mention: mentionViewNow,
     attachments: [], attachmentsHidden: true,
+    quickReplies: [], quickRepliesHidden: true, _realtime: "off",
   };
 
   /** The composer's photos — the ONE copy. See `AriaChatState.attachments` for
@@ -2187,6 +2259,111 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     return { ...s, _poll: { id: POLL_ID, intervalMs: next, action: o.poll.action, immediate: false } };
   };
 
+  // -------------------------------------------------------------------------
+  // The realtime stream
+  // -------------------------------------------------------------------------
+  //
+  // The stream paints the reply while it is being written; the poll confirms it
+  // and ends the turn. Both views of the reply are kept, and which one is shown
+  // is decided on the way out of every action (`withLive`, from `gated`), not by
+  // the reducer that happened to run: a tick that read its snapshot before a
+  // chunk arrived would otherwise paint the shorter text back over the longer.
+  // That is the same latch-and-paint pattern the mention picker and the
+  // attachment chips use, for the same reason.
+
+  /** What the stream has said about the current turn. Not persisted: a worker
+   *  that is torn down mid-turn comes back to the poll alone. */
+  const live = createLiveReply();
+  /** See `AriaChatState._realtime`. A latch, painted by `gated`. */
+  let realtime: AriaRealtime = "off";
+  /** The ladder is running at `poll.streamMs` because the stream is delivering.
+   *  Cleared when the stream stalls, fails or closes, or the turn ends. */
+  let slowed = false;
+  /** The live bubble last built, so a stream delivering at 20-30 frames a second
+   *  rebuilds it only when its text actually changed — the same rule the
+   *  transcript memo follows (`aria-hot-path.ts` rule 1). */
+  let liveBubble: { key: string; bubble: AriaBubble | null } | null = null;
+  /** The quick replies last painted, so an unchanged list keeps its identity and
+   *  a reducer that changed nothing still returns the SAME state object. */
+  let paintedReplies: AriaQuickReply[] = [];
+
+  /** Ask the host to open the stream for a turn that was just sent, and reset
+   *  the live model to it. `turnId` may be empty (a service that named no id);
+   *  every frame of the conversation is then taken as this turn's. */
+  const openRealtime = (s: AriaChatState, convId: string, turnId: string): AriaChatState => {
+    live.reset(convId, turnId);
+    slowed = false;
+    liveBubble = null;
+    const base = (o.stream?.url() ?? "").trim();
+    if (!o.stream || !o.poll || !base || !convId) {
+      realtime = "off";
+      return s;
+    }
+    realtime = "open";
+    const query = `conversationId=${encodeURIComponent(convId)}${turnId ? `&userMessageId=${encodeURIComponent(turnId)}` : ""}`;
+    const request: StreamDirective["request"] & { authorize?: boolean } = {
+      method: "GET",
+      url: `${base}${base.includes("?") ? "&" : "?"}${query}`,
+      headers: { Accept: "text/event-stream" },
+      ...(o.stream.authorize ? { authorize: true } : {}),
+    };
+    return { ...s, _stream: { id: STREAM_ID, request, onEvent: "streamEvent", onDone: "streamEnded", onError: "streamFailed" } };
+  };
+
+  /** Does the live model describe the turn `s` is showing? */
+  const liveIsFor = (s: AriaChatState): boolean =>
+    realtime !== "off" && !!s._convId && live.conversationId === s._convId && live.turnId === s._turnId;
+
+  /** The reply as the stream has it, painted over the transcript's view of it.
+   *
+   *  Only while the turn is in flight: once the transcript has the finished
+   *  answer the turn ends and the transcript is shown as it is. The live text
+   *  replaces every reply row after the turn's own message — the transcript's
+   *  draft of the same reply — but only when it is at least as long, so a
+   *  stream that joined late never paints LESS than the poll already showed.
+   *  The bubble takes over the draft row's id when there is one, so the row
+   *  keeps its identity from the first word to the confirmed answer. */
+  const withLive = (s: AriaChatState): AriaChatState => {
+    if (s.status !== "sending" || !liveIsFor(s)) return s;
+    let out = s;
+    const settledNow = live.settled();
+    const text = live.text();
+    let at = -1;
+    for (let i = s.messages.length - 1; i >= 0; i--) if (s.messages[i].role === "USER") { at = i; break; }
+    if (text && at >= 0) {
+      const tail = s.messages.slice(at + 1);
+      let shown = 0;
+      for (const b of tail) shown += b.content.length;
+      const id = tail[0]?.id ?? `${LIVE_ID_PREFIX}${s._turnId || "turn"}`;
+      const key = `${id}\u0000${settledNow ? "" : "w"}\u0000${text}`;
+      if (!liveBubble || liveBubble.key !== key) {
+        liveBubble = { key, bubble: bubbleOf(id, "ASSISTANT", assistant(), text, !settledNow) };
+      }
+      const b = liveBubble.bubble;
+      if (b && b.content.length >= shown && !(tail.length === 1 && tail[0] === b)) {
+        out = { ...out, messages: [...s.messages.slice(0, at + 1), b] };
+      }
+    }
+    // The model has finished writing; the server is still closing the turn.
+    // "Typing…" under a finished reply would be a lie, so the line clears — but
+    // only that line: a notice the owner still has to act on stays.
+    if (settledNow && out.statusText && out.statusText === typingText()) out = { ...out, statusText: "" };
+    // Another decision can start before the transcript closes the same turn.
+    // Restore typing only when the line is free; keep actionable owner notices.
+    if (!settledNow && !out.statusText) out = { ...out, statusText: typingText() };
+    return out;
+  };
+
+  /** The current turn's quick replies, as rows. */
+  const repliesFor = (s: AriaChatState): AriaQuickReply[] => {
+    const offered = !!s._turnId && live.turnId === s._turnId && live.conversationId === s._convId
+      ? live.quickReplies() : [];
+    const same = offered.length === paintedReplies.length
+      && offered.every((r, i) => paintedReplies[i].label === r.label && paintedReplies[i].reply === r.reply);
+    if (!same) paintedReplies = offered.map((r, i) => ({ id: `qr${i + 1}`, label: r.label, reply: r.reply }));
+    return paintedReplies;
+  };
+
   /** Ensure a conversation exists for the ACTIVE site, creating one when there
    *  is none or when the site changed under us. */
   async function ensureConversation(s: AriaChatState): Promise<{ convId: string; site: string; created: boolean }> {
@@ -2264,6 +2441,11 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     // this one. Bump before the first await so an in-flight tick is already stale
     // by the time it resolves.
     turnSeq += 1;
+    // …and the previous turn's live reply and quick replies are over too. The
+    // new turn's stream, if any, is asked for once the send has named the turn.
+    live.reset("", "");
+    realtime = "off";
+    slowed = false;
     // The picks above the composer ride WITH this turn, as references beside
     // the text — never as tokens inside it. Read once, here: a chip the owner
     // adds while this send is in the air belongs to the NEXT turn, and only the
@@ -2494,8 +2676,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       if (o.poll) {
         // Return NOW. The host owns the clock from here; `tick` merges the
         // reply in when it lands.
+        // …and, where a realtime stream is configured, ask for it too: the
+        // reply's words then arrive as they are written instead of on the
+        // next tick. The ladder is armed either way — the stream paints, the
+        // poll confirms, and wherever the stream cannot open, the poll is all
+        // there is.
         const armed: AriaChatState = { ...sent, status: "sending", _convId: convId, _siteId: site };
-        return cadence(armed, o.poll.fastMs, null);
+        return cadence(openRealtime(armed, convId, abortId), o.poll.fastMs, null);
       }
       return busyLoop({ ...sent, _convId: convId, _siteId: site }, convId, optimistic);
     } catch (e) {
@@ -2593,9 +2780,14 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     const { _stream: _a, _nav: _b, _poll: _c, _error: _d, ...rest } = r;
     return rest as AriaChatState;
   };
-  const gated = (s: AriaChatState): AriaChatState => {
+  const gated = (input: AriaChatState): AriaChatState => {
     mentionSite();
-    const hidden = !(turnInFlight(s) && !!s._abortId);
+    // The live reply first, so every rule below sees what will be painted.
+    const s = withLive(input);
+    // Stop goes once the stream says the model has finished writing: there is
+    // nothing left for an abort to save, and the turn only waits on the server
+    // to close it.
+    const hidden = !(turnInFlight(s) && !!s._abortId) || (liveIsFor(s) && live.settled());
     // The reply actions follow the same rule for the same reason: a derived
     // flag, recomputed on every action's way out, so no reducer can forget it.
     // `_pending` rather than `turnInFlight` — see `regenerate` for why `status`
@@ -2624,6 +2816,11 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       ? actioned
       : { ...actioned, attachments: chips, attachmentsHidden };
     if (out.mention !== mentionViewNow) out = { ...out, mention: mentionViewNow };
+    const quickReplies = repliesFor(out);
+    if (out.quickReplies !== quickReplies || out.quickRepliesHidden !== (quickReplies.length === 0)) {
+      out = { ...out, quickReplies, quickRepliesHidden: quickReplies.length === 0 };
+    }
+    if (out._realtime !== realtime) out = { ...out, _realtime: realtime };
     // Every state the runtime commits passes through here (an `undefined`
     // result commits nothing and skips it), so this is the newest committed
     // state — what `copyMessage` puts its note on when other actions landed
@@ -2907,6 +3104,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // A fresh conversation is a turn boundary too: a tick parked on the OLD
       // conversation's transcript must not reconcile it over the new greeting.
       turnSeq += 1;
+      // The old conversation's live reply and quick replies go with it. Its
+      // stream stays open until the next turn supersedes it (a worker cannot
+      // close one), and every frame it still delivers is for a conversation
+      // the model no longer folds.
+      live.reset("", "");
+      realtime = "off";
+      slowed = false;
       // A fresh chat drops its drafts, the picks included — the same way it
       // empties the composer. The provider list is kept: it belongs to the
       // business, not to the conversation.
@@ -2985,7 +3189,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // is on the RAW transcript — bailing on the bubbles is what let such a
         // reply go unnoticed and pinned the ladder fast forever. Safe to return
         // `s` here: the guard above proved this tick is still current.
-        if (!raw.length) return s;
+        if (!raw.length) {
+          if (slowed && live.takeActivity() === 0) {
+            slowed = false;
+            return cadence(s, o.poll.fastMs, o.poll.streamMs ?? null);
+          }
+          return s;
+        }
         const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you(), s._pendingId, s._pendingAttach ?? [], s._pendingRefs);
         // …but still never PAINT nothing over something. `messages` is only
         // adopted when it has content: a transcript that renders empty leaves
@@ -3015,7 +3225,8 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
           ...observed(raw, s.widget),
           prompts: promptsFor(painted, promptList()),
           statusText: ended ? "" : s.statusText,
-          ...(failed ? { _abortId: "", ...toolFailureSlots(failed) } : {}),
+          ...(ended ? { _abortId: "" } : {}),
+          ...(failed ? toolFailureSlots(failed) : {}),
         };
         // The async job rides this same tick — see `withJobProgress`. Done
         // AFTER the transcript rebuild, so a widget that has just been retired
@@ -3024,7 +3235,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         const withItems = await withWidgetItems(withJob);
         if (turnSeq !== seq || abortingEpochs.has(seq)) return undefined;
         // Slow the ladder the moment the turn is over; leave it alone otherwise.
-        return ended && wasFast ? cadence(withItems, o.poll.idleMs, o.poll.fastMs) : withItems;
+        if (ended && wasFast) {
+          slowed = false;
+          return cadence(withItems, o.poll.idleMs, o.poll.fastMs);
+        }
+        // The ladder runs slow only while the stream proves it is delivering.
+        // A whole slow interval in which no frame changed anything is a stalled
+        // stream — or a finished reply waiting on the server — and either way the
+        // transcript is all there is, so it goes back to being read at the full
+        // rate. No clock needed: this tick IS the interval.
+        if (slowed && live.takeActivity() === 0) {
+          slowed = false;
+          return cadence(withItems, o.poll.fastMs, o.poll.streamMs ?? null);
+        }
+        return withItems;
+
       } catch {
         // A read that THREW is exactly as stale as one that resolved: if a turn
         // boundary moved on while it was in flight, returning `s` merges the
@@ -3664,8 +3889,61 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         regenerating = false;
       }
     },
+
+    // The realtime stream's three callbacks. The host dispatches them one at a
+    // time, in arrival order, through the same queue as every other action.
+    streamEvent: async (s, event) => {
+      const change = live.fold(event);
+      // A frame that changed nothing commits nothing — at 20-30 frames a second
+      // a commit per frame would be a re-render per frame for no reason.
+      if (change === "none") return undefined;
+      // The stream has proved itself for this turn.
+      if (realtime === "open") realtime = "live";
+      let next = s;
+      // Words are arriving, so the transcript only has to CONFIRM the turn now,
+      // and the ladder can slow to the confirmation rate. Once per turn; `tick`
+      // speeds it back up the first time a whole slow interval passes with no
+      // frame (`takeActivity`), which the baseline taken here makes exact.
+      if (o.poll?.streamMs && !slowed && turnInFlight(s) && (change === "text" || change === "completed")) {
+        slowed = true;
+        live.takeActivity();
+        next = cadence(next, o.poll.streamMs, o.poll.fastMs);
+      }
+      // A completed reply, or the service saying the transcript changed, is a
+      // HINT that the turn can be confirmed — never the confirmation. Read the
+      // transcript now rather than at the next tick; only what it says ends the
+      // turn. `tick` holds every guard a read needs (the turn epoch, an abort in
+      // the air), including the `undefined` that leaves the state untouched when
+      // a boundary moved on while the read was out.
+      if ((change === "completed" && live.settled()) || change === "confirm") {
+        if (!turnInFlight(s)) return next;
+        const confirmed = await impl.tick(next);
+        if (!confirmed) return undefined;
+        // A `_poll` the tick did not replace still has to reach the host.
+        return next._poll && !confirmed._poll ? { ...confirmed, _poll: next._poll } : confirmed;
+      }
+      return next;
+    },
+    streamEnded: (s) => {
+      realtime = "down";
+      return restoreLadder(s);
+    },
+    streamFailed: (s) => {
+      realtime = "down";
+      return restoreLadder(s);
+    },
   };
 
+  /** The stream is gone for the rest of this turn, so if the ladder was slowed
+   *  for it, it goes back to the full rate. Nothing re-opens the stream until the
+   *  next turn: re-asking on every tick would hammer an endpoint that just
+   *  refused, and the poll alone already carries a turn to the end. */
+  function restoreLadder(s: AriaChatState): AriaChatState {
+    if (!slowed || !o.poll) return s;
+    slowed = false;
+    return turnInFlight(s) ? cadence(s, o.poll.fastMs, o.poll.streamMs ?? null) : s;
+  }
+
   // Every action's result goes through the Stop gate on its way out.
   return {
     initialState,
@@ -3711,6 +3989,9 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     attachmentSettled: (s, arg) => gated(impl.attachmentSettled(s, arg)),
     removeAttachment: (s, arg) => gated(impl.removeAttachment(s, arg)),
     retryAttachment: (s, arg) => gated(impl.retryAttachment(s, arg)),
+    streamEvent: (s, event) => impl.streamEvent(s, event).then((r) => (r ? gated(r) : r)),
+    streamEnded: (s) => gated(impl.streamEnded(s)),
+    streamFailed: (s, err) => gated(impl.streamFailed(s, err)),
   };
 }