arcane-os 0.33.4 → 0.33.6

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.33.6
+
+- Resume transcript bottom-follow when an accepted non-synthetic user message
+  is sent, including when the reader had scrolled upward. Preserve reading
+  position for incoming content, synthetic requests, and canceled submissions.
+- Keep HTTP 529 on its existing bounded retry path when reading its diagnostic
+  body fails. Preserve the actual parser or body-read error in retry observations
+  and final failure, with cancellation and other HTTP behavior unchanged.
+
+## 0.33.5
+
+- Deliver the first visible streamed chat chunk to speech exactly once, without
+  waiting for speech playback or changing response order.
+- Keep a following transcript at its actual bottom through message and composer
+  layout changes while preserving a reader's deliberate scroll-away choice.
+- Retry pre-response Fetch failures and HTTP 529 up to three times after a
+  three-second delay. Preserve existing HTTP 429 overload retries, cancellation,
+  complete request content, and terminal errors without replaying streams or tools.
+- Add observational `onRetry` waiting/requesting notifications to portable TWiN
+  and shared AI request APIs, including queued built-in provider requests.
+- Let modal task jobs report complete transient progress to their own row through
+  `task(reportProgress)`, preserving parallel work and settled results.
+
 ## 0.33.4
 
 - Treat a repeated reader `AbortError` during intentional HTTP tool-text stream

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.33.4` SDK contract. Applications pin one exact npm
+This checkout defines the `0.33.6` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -85,7 +85,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.33.4 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.33.6 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

package/browser-runtime/ai/twin-cloud.mjs

@@ -17,7 +17,8 @@ export async function fetchRequest({
     signal = null,
     id = Date.now(),
     onRequest = function observeTWiNRequest(){},
-    onResponse = function observeTWiNResponse(){}
+    onResponse = function observeTWiNResponse(){},
+    onRetry = null
 } = {}){
     if(signal?.aborted){
         throw normalizeAIRequestAbort(signal.reason);
@@ -67,7 +68,8 @@ export async function fetchRequest({
                 },
                 body:JSON.stringify(request),
                 ...(signal ? {signal} : {})
-            }
+            },
+            {onRetry}
         );
         if(signal?.aborted){
             throw normalizeAIRequestAbort(signal.reason);
@@ -141,72 +143,135 @@ export function openAIResponseFormat(format){
 }
 
 /** Shared with browser streaming; consume no successful body at this boundary. */
-export async function fetchHTTPResponse(url, options){
+export async function fetchHTTPResponse(url, options, {onRetry = null} = {}) {
     const {signal} = options;
     const retryDelayMs = 3000;
-    try{
-        while(true){
-            if(signal?.aborted){
+    const maxRecoveryRetries = 3;
+    let recoveryRetries = 0;
+    let attempt = 0;
+    try {
+        while (true) {
+            if (signal?.aborted) {
                 throw normalizeAIRequestAbort(signal.reason);
             }
-            const response = await fetch(url, options);
-            if(signal?.aborted){
+            let response;
+            let error;
+            try {
+                response = await fetch(url, options);
+            } catch (fetchError) {
+                if (isAIRequestAbort(fetchError, signal)) {
+                    throw normalizeAIRequestAbort(fetchError);
+                }
+                error = fetchError;
+            }
+            if (signal?.aborted) {
                 throw normalizeAIRequestAbort(signal.reason);
             }
-            if(response.ok){
+            if (response?.ok) {
                 return response;
             }
-            const contentType = response.headers.get('content-type') || '';
-            const error = contentType.includes('application/json')
-                ? await response.json()
-                : await response.text();
-            if(signal?.aborted){
-                throw normalizeAIRequestAbort(signal.reason);
+            const status = response?.status ?? null;
+            if (response) {
+                const contentType = response.headers.get('content-type') || '';
+                try {
+                    error = contentType.includes('application/json')
+                        ? await response.json()
+                        : await response.text();
+                } catch (bodyError) {
+                    if (status !== 529 || isAIRequestAbort(bodyError, signal)) {
+                        throw bodyError;
+                    }
+                    error = bodyError;
+                }
+                if (signal?.aborted) {
+                    throw normalizeAIRequestAbort(signal.reason);
+                }
             }
             const message = is.string(error)
                 ? error
                 : error?.error?.message ?? error?.message;
-            if(
-                response.status !== 429
-                || !is.string(message)
-                || !message.toLowerCase().includes('overload')
-            ){
-                throw error;
+            const overload = status === 429
+                && is.string(message)
+                && message.toLowerCase().includes('overload');
+            if (!overload) {
+                if ((status !== null && status !== 529)
+                    || recoveryRetries >= maxRecoveryRetries) {
+                    throw error;
+                }
+                recoveryRetries += 1;
             }
+            attempt += 1;
             arcaneLogging.warn(
-                `${message}\nRetrying in ${retryDelayMs / 1000} seconds`,
+                `${message ?? 'AI request transport failed.'}\nRetrying in ${retryDelayMs / 1000} seconds`,
                 error
             );
-            await new Promise(function waitForOverloadRetry(resolve, reject){
-                function finishRetryDelay(){
-                    signal?.removeEventListener('abort', cancelRetryDelay);
-                    resolve();
-                }
-                function cancelRetryDelay(){
-                    clearTimeout(timer);
-                    signal.removeEventListener('abort', cancelRetryDelay);
-                    reject(normalizeAIRequestAbort(signal.reason));
-                }
-                const timer = setTimeout(finishRetryDelay, retryDelayMs);
-                signal?.addEventListener('abort', cancelRetryDelay, {once:true});
-                if(signal?.aborted){
-                    cancelRetryDelay();
+            observeRequestRetry(
+                onRetry,
+                {phase: 'waiting', attempt, delayMs: retryDelayMs, status, error}
+            );
+            await new Promise(
+                function waitForRequestRetry(resolve, reject) {
+                    function finishRetryDelay() {
+                        signal?.removeEventListener('abort', cancelRetryDelay);
+                        resolve();
+                    }
+                    function cancelRetryDelay() {
+                        clearTimeout(timer);
+                        signal.removeEventListener('abort', cancelRetryDelay);
+                        reject(normalizeAIRequestAbort(signal.reason));
+                    }
+                    const timer = setTimeout(finishRetryDelay, retryDelayMs);
+                    signal?.addEventListener(
+                        'abort',
+                        cancelRetryDelay,
+                        {once: true}
+                    );
+                    if (signal?.aborted) {
+                        cancelRetryDelay();
+                    }
                 }
-            });
+            );
+            if (signal?.aborted) {
+                throw normalizeAIRequestAbort(signal.reason);
+            }
+            observeRequestRetry(
+                onRetry,
+                {phase: 'requesting', attempt, delayMs: retryDelayMs, status, error}
+            );
         }
-    }catch(error){
-        if(isAIRequestAbort(error, signal)){
+    } catch (error) {
+        if (isAIRequestAbort(error, signal)) {
             throw normalizeAIRequestAbort(error);
         }
         throw error;
     }
 }
 
+function observeRequestRetry(onRetry, state) {
+    if (!is.function(onRetry)) {
+        return;
+    }
+    function reportRetryObserverFailure(error) {
+        arcaneLogging.error('Arcane AI retry observer failed.', error);
+    }
+    try {
+        Promise.resolve(
+            onRetry(state)
+        ).catch(reportRetryObserverFailure);
+    } catch (error) {
+        reportRetryObserverFailure(error);
+    }
+}
+
 /** Return the entire parsed completion without selecting or rewriting choices. */
-export async function fetchJSONResponse(url, options){
+export async function fetchJSONResponse(url, options, {onRetry = null} = {}) {
     const {signal} = options;
     try{
-        const response = await fetchHTTPResponse(url, options);
+        const response = await fetchHTTPResponse(
+            url,
+            options,
+            {onRetry}
+        );
         if(signal?.aborted){
             throw normalizeAIRequestAbort(signal.reason);
         }

package/docs/reference/ai/twin-cloud.md

@@ -75,9 +75,18 @@ The key is
 transport authentication, not part of either callback's message payload. Keep
 credentials out of application logging as well.
 
-Only HTTP `429` with a message containing `overload` (case-insensitive) repeats automatically,
-after `3000` milliseconds. Another overload repeats the same complete request;
-other HTTP failures do not become an automatic retry loop. Pass a fresh
+Before a successful response is consumed, a rejected Fetch or HTTP `529` can
+retry up to three times, waiting `3000` milliseconds before each retry. These
+two failure types share that three-retry budget. HTTP `429` with a message
+containing `overload` (case-insensitive) retains its unlimited three-second
+retry behavior and does not consume that budget. Each attempt reuses the exact
+destination, Fetch options, serialized request, and signal. Other HTTP errors,
+successful-response decoding failures, and application callback failures do not
+retry. A known HTTP `529` also retries when reading or parsing its diagnostic
+body fails; `onRetry.error` retains that exact failure, which is thrown unchanged
+if recovery is exhausted. Diagnostic-body failures for other HTTP statuses do
+not retry. The last complete failure is thrown unchanged when recovery is exhausted.
+Pass a fresh
 `AbortController`'s `signal` and call `abort()` to cancel. Cancellation during
 the request, response-body read, retry wait, or callback settlement prevents
 successful result delivery and rejects with `ARCANE_AI_REQUEST_ABORTED`.
@@ -86,6 +95,17 @@ A missing key uses `AI_PROVIDER_NOT_CONFIGURED`, a missing explicit model
 throws `TypeError`, and an unsupported `structuredOutput` input uses
 `AI_STRUCTURED_OUTPUT_INVALID`.
 
+Optional `onRetry({phase,attempt,delayMs,status,error})` observes each retry.
+`phase:'waiting'` arrives before the abortable delay; `phase:'requesting'`
+arrives immediately before the next Fetch. `attempt` is the one-based upcoming
+retry number across both retry policies, `delayMs` is `3000`, `status` is the
+HTTP status or `null` for a rejected Fetch, and `error` is the complete original
+failure value. This observer runs synchronously without awaiting its returned
+promise. Synchronous throws and rejected promises are reported through the
+shared console logger and cannot change the request outcome or trigger another
+retry. `onRequest` still runs once per logical request. Retry observations stay
+outside the model payload and retained history.
+
 The SDK retains no request or response history between calls and uses no
 DBOPFS, chat entity, or memory extraction. Each call's `messages` are its
 complete caller-supplied context. The caller decides whether and how to keep
@@ -104,8 +124,8 @@ the existing implementation rather than maintain another retry or body reader.
 
 | Export | Contract |
 | --- | --- |
-| `fetchHTTPResponse(url,options)` | Uses the caller's Fetch options, overload retry and cancellation; returns a successful `Response` with its body unconsumed. |
-| `fetchJSONResponse(url,options)` | Uses that HTTP owner, requires `application/json`, and returns the complete parsed body without selecting choices. |
+| `fetchHTTPResponse(url,options,{onRetry=null}={})` | Uses the caller's exact Fetch options and shared retry/cancellation behavior; returns a successful `Response` with its body unconsumed. The separate optional control observes retries without entering Fetch options. |
+| `fetchJSONResponse(url,options,{onRetry=null}={})` | Uses that HTTP owner and retry observer, requires `application/json`, and returns the complete parsed body without selecting choices. |
 | `structuredOutputFormat(value=false)` | Maps false/null/undefined to null, true/`'json'` to `'json'`, and preserves a supplied plain JSON Schema object. Other inputs use `AI_STRUCTURED_OUTPUT_INVALID`. |
 | `openAIResponseFormat(format)` | Maps the normalized value to `json_object`, strict `json_schema` named `structured_response`, or null. |
 | `isAIRequestAbort(error,signal)` | Recognizes an aborted signal, `AbortError`, or the existing Arcane AI/request cancellation codes. |
@@ -113,8 +133,8 @@ the existing implementation rather than maintain another retry or body reader.
 
 These helpers start no work on import. HTTP helpers require explicit URL and
 options; they do not add a key, model, browser state, or retained conversation.
-Overload warnings use the shared console logger and preserve the complete
-provider error.
+Retry warnings and observer failures use the shared console logger and preserve
+the complete original error.
 
 ## Existing browser AI interface
 

package/docs/reference/availability-and-normalization.md

@@ -78,7 +78,7 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
-| Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Shared structured-output mapping, overload-only HTTP 429 retry after 3000 ms, and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
+| Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
 | Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | The helper keeps audio on device: Whisper owns STT and Kokoro owns TTS. It automatically cleans only the outbound speech-input copy and normalizes application-facing audio/text behavior while browser and native request/response plumbing differs below that boundary. |
 | Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
 | Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |

package/docs/reference/runtime-components.md

@@ -339,8 +339,14 @@ suppressed.
 module or an existing compatible session, restores the UI transcript when
 available, and uses provider-safe history as its restoration fallback. The
 transcript is a masked vertical scroll viewport; status and composer remain
-outside it. Initial restoration and every user, assistant, tool, streaming,
-progress, or failure mutation scrolls that viewport to its true bottom. Each
+outside it. Initial restoration follows the true bottom. User, assistant, tool,
+streaming, progress, and failure updates continue following it, including later
+message-card, status, composer, or viewport resizing, until the reader scrolls
+toward earlier content. Scrolling down to the bottom or submitting an accepted
+non-synthetic user message resumes following. Canceled or rejected submissions
+and synthetic requests preserve the reader's position. Layout
+clamping, hidden views, and BFCache restoration preserve that choice;
+destruction releases scroll observation. Each
 restored or new message uses a separate semantic `<time>` element at the card's
 lower-right with an ISO `datetime`, full local title, and local 24-hour `HH:MM`
 text.
@@ -475,10 +481,13 @@ terminal result of the segments submitted by one invocation; Chat continues
 to feed chunks without waiting for playback. Runtime mute, cancellation,
 permission waiting, and stale generations remain non-errors.
 
-Each visible model chunk is forwarded to `AI.streamTTS(text)` in arrival
-order. The AI owner automatically removes repeated formatting marks from an
-outbound speech-input copy before the
-configured segmentation, admits completed segments to bounded synthesis
+Each visible model chunk, including the first chunk that creates its assistant
+card, renders once in arrival order. When speech is ready and unmuted, each
+chunk also reaches `AI.streamTTS(text)` once. Card creation is synchronous, so
+consecutive chunks retain their original order without waiting for speech
+preparation or playback. Thinking content remains outside speech forwarding.
+The AI owner automatically removes repeated formatting marks from an outbound
+speech-input copy before the configured segmentation, admits completed segments to bounded synthesis
 immediately, and schedules the contiguous ready audio prefix on the audio
 clock. Chat retains the original Markdown for display and storage and owns no
 second speech queue. No app option selects or disables this cleanup. Single
@@ -988,6 +997,16 @@ to `true`; `destroy()` releases the component. Product-specific conditions for
 closing a modal belong to the application. Content, actions and task results
 are preserved, and `runTasks()` continues to execute independent jobs concurrently.
 
+`runTasks(title, jobs)` calls each `job.task(reportProgress)` concurrently.
+The optional callback accepts complete plain-text status for that pending job
+only and returns `true` when displayed. For example, a request can report its
+retry delay without replacing another job's progress. Reports after that job
+settles or the modal is destroyed return `false` and change no UI. A display
+failure is logged without rejecting the task. Existing zero-argument task
+functions remain supported, results retain `Promise.allSettled` order, and
+destruction does not cancel the application-owned work. Progress is transient
+display content, never a task result or conversation record.
+
 Events: `modal-ready`, `modal-opened`, `modal-closed`, `modal-action`.
 
 Slots: `header`, `body`, `footer`.

package/docs/reference/runtime-modules.md

@@ -166,7 +166,8 @@ provider implementations; neither form is a retired compatibility API.
 Built-in cloud chat decodes an HTTP error body once as JSON or text and rejects
 with that complete value unchanged. It does not reconstruct an Error, replace
 the message, or add `providerMessage`, `status`, or an SDK failure code to the
-provider body. Network and decoding errors also pass through; cancellation
+provider body. Network errors pass through after the retry policy below;
+decoding errors pass through immediately. Cancellation
 retains the existing `ARCANE_AI_REQUEST_ABORTED` contract.
 
 When the HTTP status is `429` and the existing `error.message`, `message`, or
@@ -178,8 +179,26 @@ the same destination, headers, complete serialized body, and cancellation
 signal; `onRequest` runs once for the logical request. Cancellation stops the
 delay and prevents another attempt. Retrying happens before a successful
 response is consumed, so partial streams and tool callbacks are never replayed.
-Native Ollama and externally supplied provider adapters retain their own
-transport behavior.
+Rejected Fetch calls and HTTP `529` share a separate budget of three retries,
+each after the same `3000` millisecond delay. HTTP `429` overload retries do not
+consume that budget. The final complete network error or provider body passes
+through unchanged when recovery is exhausted. Aborts, other HTTP errors,
+successful-response body reads, stream decoding, and application callbacks
+never start another attempt.
+
+`fetchRequest()` and `streamRequest()` accept
+`onRetry({phase,attempt,delayMs,status,error})`. The observer receives
+`phase:'waiting'` before the abortable delay and `phase:'requesting'` immediately
+before the next Fetch. `attempt` is the one-based upcoming retry number across
+both retry policies; `delayMs` is `3000`; `status` is the HTTP status or `null`
+for rejected Fetch; `error` is the complete original failure value. The SDK
+invokes this observational callback synchronously and observes a returned
+promise without awaiting it. Callback throws and rejections are logged through
+the shared console owner without changing request success or causing retries.
+The callback remains outside model payloads and is forwarded through built-in
+provider controls, including queued requests, with the request owner's existing
+cancellation lifetime. Native Ollama and externally supplied provider adapters
+retain their own transport behavior.
 
 Initialization uses the canonical realm user's actual readiness state. If
 `window.user?.ready` is already true, AI initializes immediately. Otherwise one
@@ -472,8 +491,10 @@ cleanup errors remain visible in developer-console diagnostics.
 
 Request observers receive
 `onRequest(request,id,metadata)` and any transport metadata supplied by the
-selected route is forwarded unchanged. Every async native, HTTP, provider, and
-built-in callback is observed before the next callback or terminal settlement.
+selected route is forwarded unchanged. Async request, response, content, and
+tool callbacks are observed before the next callback or terminal settlement.
+The observational `onRetry` callback has the separate nonblocking behavior
+described above.
 
 Native Ollama responses are adapted before the shared structural validator:
 provider-native calls may omit `id` and `type` or provide object arguments, so
@@ -914,6 +935,12 @@ caller's payload and request records remain unchanged. The optional
 boundary has already cleaned the copy. Applications omit that argument. LLM
 and STT payloads are unaffected.
 
+SDK-owned LLM delegation also carries `onRetry` in the separate `preparation`
+control record, alongside `observeToolText` for streams. The runtime preserves
+these controls across its request queue and passes them to the selected
+provider without inserting callbacks in the provider payload. Applications use
+the `AI.fetchRequest()` and `AI.streamRequest()` options described above.
+
 `register()` returns the provider's single unregister closure; caller-
 registered providers remain caller-owned. The high-level
 `AI.configureBrowserSpeech()` boundary is different: AI constructs, registers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.33.4",
+  "version": "0.33.6",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -86,7 +86,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/twin-cloud.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/runtime/arcane/components/chat.html

@@ -1083,8 +1083,93 @@
             &&is.function(session.send);
     }
 
-    function scrollTranscriptToBottom(){
-        chatOutput.scrollTop=chatOutput.scrollHeight;
+    let transcriptFollowing = true;
+    let transcriptScrollTop = chatOutput.scrollTop;
+    let transcriptWasHidden = chatOutput.clientHeight === 0;
+    const transcriptResizeObserver = is.function(globalThis.ResizeObserver)
+        ? new ResizeObserver(scrollTranscriptToBottom)
+        : null;
+    const transcriptMutationObserver = is.function(globalThis.MutationObserver)
+        ? new MutationObserver(handleTranscriptChildren)
+        : null;
+
+    chatOutput.addEventListener(
+        'scroll',
+        trackTranscriptScrollPosition,
+        {
+            passive: true,
+            signal: aiRuntimeStateAbortController.signal
+        }
+    );
+    transcriptResizeObserver?.observe(
+        chatOutput,
+        {box: 'border-box'}
+    );
+    for(const item of chatOutput.children) {
+        if(item.localName === 'li') {
+            transcriptResizeObserver?.observe(
+                item,
+                {box: 'border-box'}
+            );
+        }
+    }
+    transcriptMutationObserver?.observe(
+        chatOutput,
+        {childList: true}
+    );
+
+    function trackTranscriptScrollPosition() {
+        if(destroyed) return false;
+        if(chatOutput.clientHeight === 0) {
+            transcriptWasHidden = true;
+            return false;
+        }
+        const scrollTop = chatOutput.scrollTop;
+        if(transcriptWasHidden) {
+            transcriptWasHidden = false;
+            transcriptScrollTop = scrollTop;
+            return true;
+        }
+        const atBottom = chatOutput.scrollHeight - chatOutput.clientHeight - scrollTop <= 1;
+        // A layout clamp reaching the bottom does not resume a reader's following.
+        if(scrollTop < transcriptScrollTop && !atBottom) {
+            transcriptFollowing = false;
+        } else if(scrollTop > transcriptScrollTop && atBottom) {
+            transcriptFollowing = true;
+        }
+        transcriptScrollTop = scrollTop;
+        return true;
+    }
+
+    function handleTranscriptChildren(records) {
+        if(destroyed) return;
+        for(const record of records) {
+            for(const item of record.removedNodes) {
+                if(item.localName === 'li' && item.parentElement !== chatOutput) {
+                    transcriptResizeObserver?.unobserve(item);
+                }
+            }
+            for(const item of record.addedNodes) {
+                if(item.localName === 'li' && item.parentElement === chatOutput) {
+                    transcriptResizeObserver?.observe(
+                        item,
+                        {box: 'border-box'}
+                    );
+                }
+            }
+        }
+        scrollTranscriptToBottom();
+    }
+
+    function scrollTranscriptToBottom(resumeFollowing = false) {
+        // Read movement before writing: a reader's scroll event may still be queued.
+        const visible = trackTranscriptScrollPosition();
+        if(resumeFollowing === true && !destroyed) {
+            transcriptFollowing = true;
+        }
+        if(!visible || !transcriptFollowing) return false;
+        chatOutput.scrollTop = chatOutput.scrollHeight;
+        transcriptScrollTop = chatOutput.scrollTop;
         return true;
     }
 
@@ -1513,6 +1598,8 @@
             actionable?[...restoredPendingToolCalls.values()]:[]
         );
         chatOutput.replaceChildren(fragment);
+        transcriptFollowing = true;
+        transcriptScrollTop = chatOutput.scrollTop;
         scrollTranscriptToBottom();
         return rendered;
     }
@@ -2014,6 +2101,10 @@
             ? selectedRole.localOnly === false
                 || (selectedRole.state === 'ready' && selectedRole.loaded)
             : availability.llm;
+        if(!conversationVisible && !host.conversationComplete) {
+            trackTranscriptScrollPosition();
+            transcriptWasHidden = true;
+        }
         chatArea.dataset.modelStartRequired = String(!conversationVisible);
         send.disabled=host.conversationComplete
             ||!availability.llm
@@ -2835,21 +2926,15 @@
             return false;
         }
 
-        let message=[...chatOutput.children].find(
-            candidate=>candidate.id===`message-${id}`
-        )||null;
-        
-        if(!message){
-            await receivedMessage(host.aiName,isThinking?'':text,id);
-            if(!isThinking){
-                return false;
-            }
-            message=[...chatOutput.children].find(
-                candidate=>candidate.id===`message-${id}`
-            )||null;
-            if(!message){
-                return false;
+        let message = [...chatOutput.children].find(
+            function findStreamedMessage(candidate) {
+                return candidate.id === `message-${id}`;
             }
+        ) || null;
+
+        if(!message) {
+            // The first chunk uses the same display and speech path as later chunks.
+            message = receivedMessage(host.aiName, '', id);
         }
 
         let target=message.querySelector('.markdown');
@@ -3060,8 +3145,12 @@
         }
 
         // Reset height to shrink to content size
+        trackTranscriptScrollPosition();
         textArea.style.height = 'auto';
         textArea.style.height = `${textArea.scrollHeight}px`;
+        // The intermediate auto height can clamp scrollTop before final layout.
+        transcriptScrollTop = chatOutput.scrollTop;
+        scrollTranscriptToBottom();
     }
 
     function renderSessionMessageFailure(messageId,error){
@@ -3164,7 +3253,7 @@
         applyAIAvailability(host.aiAvailability);
         setSessionStatus('sending','AI is responding…');
         try{
-            await receivedMessage(host.aiName,'',messageId);
+            receivedMessage(host.aiName, '', messageId);
             await streamMessage('',messageId,true);
             setMessageProgress(
                 messageId,
@@ -3746,7 +3835,7 @@
                 const visibleMessage=appendTranscriptMessage('user',text,host.name);
                 visibleMessage.dataset.operationId=operationId;
             }
-            scrollTranscriptToBottom();
+            scrollTranscriptToBottom(!eventContext.synthetic);
 
             if(host.aiAvailability.tts&&speech.muted===false){
                 const aiRuntime=boundChatAI??globalThis.ai;
@@ -3775,7 +3864,7 @@
         }
     }
 
-    async function receivedMessage(name = 'Assistant', text = '', id=''){
+    function receivedMessage(name = 'Assistant', text = '', id = '') {
         const message=appendTranscriptMessage('assistant',text,name);
         if(id){
             message.id=`message-${id}`;
@@ -3854,6 +3943,8 @@
         sessionBindingGeneration+=1;
         setSessionStatus('destroyed','Chat closed.');
         destroyed=true;
+        transcriptResizeObserver?.disconnect();
+        transcriptMutationObserver?.disconnect();
         const destroyReason=createChatSubmissionAbort(
             chatReasons.componentDestroyed,
             'The chat component was destroyed before message submission settled.'

package/runtime/arcane/components/modal.html

@@ -421,16 +421,38 @@
         await open();
 
         activeRun=Promise.allSettled(tasks.map(async function runProgressTask(job,index){
+            let settled = false;
+            function displayTaskProgress(message, state) {
+                if (disposed) {
+                    return false;
+                }
+                try {
+                    if (state) {
+                        rows[index].row.dataset.status = state;
+                    }
+                    rows[index].status.innerText = message;
+                    return true;
+                } catch (error) {
+                    arcaneLogging.error(`Unable to display progress for ${job.name}:`, error);
+                    return false;
+                }
+            }
+            function reportProgress(message) {
+                if (settled || !is.string(message)) {
+                    return false;
+                }
+                return displayTaskProgress(message);
+            }
             try{
-                const result=await job.task();
-                rows[index].row.dataset.status='complete';
-                rows[index].status.innerText='Complete';
+                const result=await job.task(reportProgress);
+                displayTaskProgress('Complete', 'complete');
                 return result;
             }catch(error){
-                rows[index].row.dataset.status='failed';
-                rows[index].status.innerText='Unable to complete';
+                displayTaskProgress('Unable to complete', 'failed');
                 arcaneLogging.error(`Unable to complete ${job.name}:`,error);
                 throw error;
+            } finally {
+                settled = true;
             }
         }));
 
@@ -439,6 +461,9 @@
             return result.status==='rejected';
         });
         running=false;
+        if (disposed) {
+            return results;
+        }
         updateCloseButton();
 
         if(failed){

package/runtime/arcane/modules/AI.js

@@ -1484,7 +1484,8 @@ class AI {
                     return Promise.resolve(
                         runtime.#requestBuiltInLLMChat(
                             context.payload,
-                            context.signal
+                            context.signal,
+                            controls.onRetry
                         )
                     ).finally(releaseBuiltInLLMRequest);
                 }
@@ -1494,7 +1495,8 @@ class AI {
                             return runtime.#requestBuiltInLLMStream(
                                 context.payload,
                                 bridge,
-                                controls.observeToolText
+                                controls.observeToolText,
+                                controls.onRetry
                             );
                         },
                         context.signal
@@ -4154,7 +4156,7 @@ class AI {
         return is.string(content)?content:completion;
     }
 
-    #requestBuiltInLLMChat(payload={},signal=null){
+    #requestBuiltInLLMChat(payload = {}, signal = null, onRetry = null) {
         const parallelToolCalls=payload.parallelToolCalls!==undefined
             ?payload.parallelToolCalls
             :payload.parallel_tool_calls;
@@ -4168,11 +4170,12 @@ class AI {
             payload.id??Date.now(),
             function ignoreBuiltInLLMProviderRequest(){},
             signal,
-            payload.reasoningEffort
+            payload.reasoningEffort,
+            onRetry
         );
     }
 
-    #requestBuiltInLLMStream(payload={},bridge,observeToolText=null){
+    #requestBuiltInLLMStream(payload = {}, bridge, observeToolText = null, onRetry = null) {
         const parallelToolCalls=payload.parallelToolCalls!==undefined
             ?payload.parallelToolCalls
             :payload.parallel_tool_calls;
@@ -4198,7 +4201,8 @@ class AI {
             emitBuiltInLLMStreamData,
             function ignoreBuiltInLLMStreamResult(){},
             payload.reasoningEffort,
-            observeToolText
+            observeToolText,
+            onRetry
         );
     }
 
@@ -4357,6 +4361,7 @@ class AI {
         toolChoice='auto',
         onToolCall=function ignoreEarlyFunction(){},
         onRequest=function ignoreStreamRequest(){},
+        onRetry = null,
         parallelToolCalls,
         id=Date.now(),
         seeThinking=false,
@@ -4438,7 +4443,7 @@ class AI {
                         localOnly,
                         signal
                     },
-                    {observeToolText}
+                    {observeToolText, onRetry}
                 );
                 for await(const chunk of handle){
                     if(signal?.aborted){
@@ -4523,7 +4528,8 @@ class AI {
                 onDataChunk,
                 onDataResult,
                 normalizedReasoningEffort,
-                observeToolText
+                observeToolText,
+                onRetry
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 completion
@@ -4631,7 +4637,8 @@ class AI {
         dataChunkHandler=function ignoreBuiltInStreamDataChunk(){},
         dataResultHandler=function ignoreBuiltInStreamDataResult(){},
         reasoningEffort,
-        observeToolText=null
+        observeToolText=null,
+        onRetry = null
     ){
         let speechTurnCompleted=false;
 
@@ -4863,7 +4870,8 @@ class AI {
                 headers:this.#serviceHeaders[this.llmService],
                 body,
                 ...(signal?{signal}:{})
-            }
+            },
+            {onRetry}
         );
 
         let sseBuffer='';
@@ -5357,6 +5365,7 @@ class AI {
         signal=null,
         onRequest=function ignoreFetchRequest(){},
         onResponse=function ignoreFetchResponse(){},
+        onRetry = null,
         maxOutputTokens,
         maxTokens,
         temperature,
@@ -5420,7 +5429,8 @@ class AI {
                     payload:request,
                     localOnly,
                     signal
-                }
+                },
+                {onRetry}
             );
             if(signal?.aborted){
                 throw normalizeAIRequestAbort();
@@ -5443,7 +5453,8 @@ class AI {
             id,
             onRequest,
             signal,
-            normalizedReasoningEffort
+            normalizedReasoningEffort,
+            onRetry
         );
     }
 
@@ -5496,7 +5507,8 @@ class AI {
         id=Date.now(),
         requestHandler=function ignoreFetchRequest(){},
         signal=null,
-        reasoningEffort
+        reasoningEffort,
+        onRetry = null
     ){
         validateAIStructuralRequest(messages,tools,parallel_tool_calls);
         this.#assertServiceConfigured(this.llmService);
@@ -5613,7 +5625,8 @@ class AI {
                 headers:this.#serviceHeaders[this.llmService],
                 body,
                 ...(signal?{signal}:{})
-            }
+            },
+            {onRetry}
         );
 
         if(signal?.aborted){

package/runtime/arcane/modules/AIProviderRuntime.js

@@ -3347,14 +3347,14 @@ export class AIProviderRuntime {
         return this.#disposeAllPromise;
     }
 
-    request(role, options = {}, {speechInputPrepared = false, observeToolText = null} = {}) {
+    request(role, options = {}, {speechInputPrepared = false, observeToolText = null, onRetry = null} = {}) {
         if (SPEECH_ROLES.includes(role)) {
             arcaneLogging.debug('[Arcane speech runtime] request', role, options);
         }
-        return this.#requestRole(role, options, false, speechInputPrepared, observeToolText);
+        return this.#requestRole(role, options, false, speechInputPrepared, observeToolText, onRetry);
     }
 
-    #requestRole(role, options, queued, speechInputPrepared = false, observeToolText = null) {
+    #requestRole(role, options, queued, speechInputPrepared = false, observeToolText = null, onRetry = null) {
         this.#assertOpen();
         this.#assertNotConfiguring();
         assertRole(role);
@@ -3486,7 +3486,7 @@ export class AIProviderRuntime {
         }
         if ((!queued && slot.requestQueue.length)
             || slot.activeRequests.size >= maxConcurrentRequests) {
-            return this.#enqueueRoleRequest(slot, options, observeToolText);
+            return this.#enqueueRoleRequest(slot, options, observeToolText, onRetry);
         }
         if (!slot.ready
             || providerStatus.state !== 'ready'
@@ -3808,7 +3808,7 @@ export class AIProviderRuntime {
                                     payload: options.payload,
                                     signal: controller.signal
                                 },
-                                {observeToolText: observeCurrentToolText}
+                                {observeToolText: observeCurrentToolText, onRetry}
                             );
                         }
                     );
@@ -4039,7 +4039,12 @@ export class AIProviderRuntime {
                 }
                 const result = role === 'tts'
                     ? await provider.request(providerRequest, {speechInputPrepared: true})
-                    : await provider.request(providerRequest);
+                    : role === 'llm'
+                        ? await provider.request(
+                            providerRequest,
+                            {onRetry}
+                        )
+                        : await provider.request(providerRequest);
                 if (SPEECH_ROLES.includes(role)) {
                     arcaneLogging.debug('[Arcane speech runtime] provider.request.result', {role, generation, requestSequence, operationId}, result);
                 }
@@ -4222,7 +4227,7 @@ export class AIProviderRuntime {
         );
     }
 
-    #enqueueRoleRequest(slot, options, observeToolText = null) {
+    #enqueueRoleRequest(slot, options, observeToolText = null, onRetry = null) {
         if (SPEECH_ROLES.includes(slot.role)) {
             arcaneLogging.debug('[Arcane speech runtime] queue.enqueue', {
                 role: slot.role,
@@ -4237,6 +4242,7 @@ export class AIProviderRuntime {
             const entry = {
                 options,
                 observeToolText,
+                onRetry,
                 resolve,
                 reject,
                 detachSignal: null
@@ -4309,7 +4315,7 @@ export class AIProviderRuntime {
             let operation;
             try {
                 operation = runtime.#requestRole(
-                    slot.role, entry.options, true, false, entry.observeToolText
+                    slot.role, entry.options, true, false, entry.observeToolText, entry.onRetry
                 );
             } catch (error) {
                 if (SPEECH_ROLES.includes(slot.role)) {