@runtypelabs/persona 4.4.1 → 4.5.0

package/dist/smart-dom-reader.d.cts

@@ -2328,25 +2328,74 @@ type AgentWidgetArtifactsFeature = {
 /**
  * How the transcript scrolls while an assistant response streams in.
  *
- * - `"follow"` (default): keep the newest content pinned to the bottom of the
- *   viewport, pausing when the user scrolls up and resuming when they return
- *   to the bottom.
- * - `"anchor-top"`: on send, scroll the user's message near the top of the
- *   viewport and hold it there while the response streams in beneath it
- *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"anchor-top"` (default): on send, scroll the user's message near the top
+ *   of the viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
+ *   greeting, an injected assistant message, a resubmit, or first-load
+ *   streaming), it falls back to `"follow"` for that turn so content never
+ *   streams in off-screen.
+ * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
+ *   pausing when the user scrolls up and resuming when they return to the
+ *   bottom. This was the default before 4.x.
  * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
  *   way back to the latest content.
  */
 type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
+/**
+ * Where the transcript lands when a *saved* conversation is reopened (restored
+ * from the storage adapter / `initialMessages`), as opposed to a fresh send.
+ *
+ * - `"bottom"` (default): jump to the absolute end of the transcript, matching
+ *   the historical behavior.
+ * - `"last-user-turn"`: pin the last user message near the top of the viewport
+ *   (the last point the reader was actively driving the conversation) so a long
+ *   restored thread opens at a readable place rather than at the very bottom.
+ */
+type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
 type AgentWidgetScrollBehaviorFeature = {
-    /** Scroll behavior during streamed responses. @default "follow" */
+    /** Scroll behavior during streamed responses. @default "anchor-top" */
     mode?: AgentWidgetScrollMode;
     /**
      * Gap (px) kept between the anchored user message and the top of the
-     * viewport in `"anchor-top"` mode.
+     * viewport in `"anchor-top"` mode. Also used as the gap for
+     * `restorePosition: "last-user-turn"`.
      * @default 16
      */
     anchorTopOffset?: number;
+    /**
+     * Where to land when a saved conversation reopens. Additive and opt-in: the
+     * default preserves the historical "jump to the bottom" behavior.
+     * @default "bottom"
+     */
+    restorePosition?: AgentWidgetScrollRestorePosition;
+    /**
+     * When true, interactions beyond text selection — keyboard navigation
+     * (PageUp/PageDown/Home/End/arrows) inside the transcript and focusing a
+     * link or other interactive element within it — also pause auto-follow in
+     * `"follow"` mode. Treats "the reader is doing something here" as intent to
+     * stay put, not just "the reader dragged a selection". Opt-in; default keeps
+     * only the existing wheel/scroll/selection triggers.
+     * @default false
+     */
+    pauseOnInteraction?: boolean;
+    /**
+     * When true, the scroll-to-bottom affordance also surfaces new-content and
+     * still-streaming activity while the reader is pinned away from the latest
+     * content in `"anchor-top"` mode. Lets the reader know a response is arriving
+     * offscreen below. Defaults on alongside the `"anchor-top"` default; set
+     * `false` to keep the count + streaming hint silent while pinned.
+     * @default true
+     */
+    showActivityWhilePinned?: boolean;
+    /**
+     * When true, Persona maintains a visually-hidden `aria-live="polite"` region
+     * that announces important transcript events — a response starting, a
+     * response finishing, and "N new messages below" while the reader is scrolled
+     * away — at a comfortable cadence (never token-by-token). Opt-in so existing
+     * embeds don't suddenly gain screen-reader announcements.
+     * @default false
+     */
+    announce?: boolean;
 };
 type AgentWidgetScrollToBottomFeature = {
     /**

package/dist/smart-dom-reader.d.ts

@@ -2328,25 +2328,74 @@ type AgentWidgetArtifactsFeature = {
 /**
  * How the transcript scrolls while an assistant response streams in.
  *
- * - `"follow"` (default): keep the newest content pinned to the bottom of the
- *   viewport, pausing when the user scrolls up and resuming when they return
- *   to the bottom.
- * - `"anchor-top"`: on send, scroll the user's message near the top of the
- *   viewport and hold it there while the response streams in beneath it
- *   (ChatGPT-style). The transcript never auto-scrolls during streaming.
+ * - `"anchor-top"` (default): on send, scroll the user's message near the top
+ *   of the viewport and hold it there while the response streams in beneath it
+ *   (ChatGPT-style). When a turn has no user send to anchor to (a proactive
+ *   greeting, an injected assistant message, a resubmit, or first-load
+ *   streaming), it falls back to `"follow"` for that turn so content never
+ *   streams in off-screen.
+ * - `"follow"`: keep the newest content pinned to the bottom of the viewport,
+ *   pausing when the user scrolls up and resuming when they return to the
+ *   bottom. This was the default before 4.x.
  * - `"none"`: never auto-scroll; the scroll-to-bottom affordance is the only
  *   way back to the latest content.
  */
 type AgentWidgetScrollMode = "follow" | "anchor-top" | "none";
+/**
+ * Where the transcript lands when a *saved* conversation is reopened (restored
+ * from the storage adapter / `initialMessages`), as opposed to a fresh send.
+ *
+ * - `"bottom"` (default): jump to the absolute end of the transcript, matching
+ *   the historical behavior.
+ * - `"last-user-turn"`: pin the last user message near the top of the viewport
+ *   (the last point the reader was actively driving the conversation) so a long
+ *   restored thread opens at a readable place rather than at the very bottom.
+ */
+type AgentWidgetScrollRestorePosition = "bottom" | "last-user-turn";
 type AgentWidgetScrollBehaviorFeature = {
-    /** Scroll behavior during streamed responses. @default "follow" */
+    /** Scroll behavior during streamed responses. @default "anchor-top" */
     mode?: AgentWidgetScrollMode;
     /**
      * Gap (px) kept between the anchored user message and the top of the
-     * viewport in `"anchor-top"` mode.
+     * viewport in `"anchor-top"` mode. Also used as the gap for
+     * `restorePosition: "last-user-turn"`.
      * @default 16
      */
     anchorTopOffset?: number;
+    /**
+     * Where to land when a saved conversation reopens. Additive and opt-in: the
+     * default preserves the historical "jump to the bottom" behavior.
+     * @default "bottom"
+     */
+    restorePosition?: AgentWidgetScrollRestorePosition;
+    /**
+     * When true, interactions beyond text selection — keyboard navigation
+     * (PageUp/PageDown/Home/End/arrows) inside the transcript and focusing a
+     * link or other interactive element within it — also pause auto-follow in
+     * `"follow"` mode. Treats "the reader is doing something here" as intent to
+     * stay put, not just "the reader dragged a selection". Opt-in; default keeps
+     * only the existing wheel/scroll/selection triggers.
+     * @default false
+     */
+    pauseOnInteraction?: boolean;
+    /**
+     * When true, the scroll-to-bottom affordance also surfaces new-content and
+     * still-streaming activity while the reader is pinned away from the latest
+     * content in `"anchor-top"` mode. Lets the reader know a response is arriving
+     * offscreen below. Defaults on alongside the `"anchor-top"` default; set
+     * `false` to keep the count + streaming hint silent while pinned.
+     * @default true
+     */
+    showActivityWhilePinned?: boolean;
+    /**
+     * When true, Persona maintains a visually-hidden `aria-live="polite"` region
+     * that announces important transcript events — a response starting, a
+     * response finishing, and "N new messages below" while the reader is scrolled
+     * away — at a comfortable cadence (never token-by-token). Opt-in so existing
+     * embeds don't suddenly gain screen-reader announcements.
+     * @default false
+     */
+    announce?: boolean;
 };
 type AgentWidgetScrollToBottomFeature = {
     /**