` into the transcript **and** sets the same text on the `assertive` region — not `polite`. The user is about to type into something that cannot reply yet, so the warning must interrupt rather than wait behind queued status ticks. Flipping it to `polite` would let the user start typing before hearing that sending will only retry. The notice text is a localisable `Strings` key added in [PR #4672](https://github.com/MervinPraison/PraisonAI/pull/4672): | `Strings` key | English text | | ------------------------ | ------------------------------------------------------------------------------------------ | | `engineNotReady(detail)` | `"The engine is not answering yet ({detail}). You can still type; sending will retry it."` | | `settingRejected(label)` | `"{label} was not changed: that value was refused."` | **`settingRejected(label)` is announced assertively too.** When Settings refuses a value — `validateInput` returns `null`, `set` returns `false`, or the persist throws — the field's inline `role="alert"` node **and** the assertive live region are set to `"{label} was not changed: that value was refused."` The label names the setting because the field may already have scrolled off, and *"was not changed"* is the fact the user needs: the old value is still in force. `polite` would let the user re-tap Save before hearing what happened. See [Settings Screen → How a refusal is spoken](/docs/features/mobile/settings-screen#how-a-refusal-is-spoken). ### Secret rows The OpenAI API key row ([API Keys](/docs/features/mobile/api-keys)) adds four `Strings` members, and none of them ever contains any part of the key. | `Strings` key | English text | | ---------------------- | ------------------------------------ | | `secretPlaceholder` | `"Paste a key to set or replace it"` | | `secretStored(label)` | `"{label} saved."` | | `secretCleared(label)` | `"{label} removed."` | | `actionClearSecret` | `"Remove"` | `secretPlaceholder` is the field's placeholder **and** its accessible name — deliberately not a masked stand-in like `sk-…abcd`, because the field is empty on every paint. It says "**Paste**" rather than "Enter": on a phone nobody types an API key, so the instruction that matches what the user is about to do is the one written for them. `secretStored(label)` and `secretCleared(label)` are announced through the **assertive** live region — the same channel as `settingRejected` — because a control that changes nothing visible and says nothing has, for the user, done nothing. Neither ever carries any part of the key. `actionClearSecret` labels the Remove button, but the button's accessible name is `${actionClearSecret}: ${label}` (e.g. *"Remove: OpenAI API key"*), so a list of otherwise-identical "Remove" buttons is disambiguated for a screen-reader user navigating by control name. ### Empty-chat strings The empty transcript panel ([Empty Chat](/docs/features/mobile/empty-chat)) adds four user-visible strings, all **constants** — not functions. | Key | Constant | English (from `en`) | | -------------------- | -------- | ---------------------------------------------------------------------------------------------------- | | `emptyTranscript` | ✓ | `"Ask something to begin."` | | `emptyAbout` | ✓ | `"PraisonAI answers questions, explains things, and works through tasks with you."` | | `emptyNeedsKeyTitle` | ✓ | `"Add an API key to start"` | | `emptyNeedsKeyBody` | ✓ | `"PraisonAI answers using your own OpenAI account. Paste a key in Settings and this chat is ready."` | The action button on the panel is not a new string — it is `strings.recoveryLabel("settings")` → **"Open settings"**, reused so the app names the destination the same way everywhere. ### Empty-chat region The panel renders as a real landmark, named through its own heading, and its words are read into the polite live region when the state appears or changes kind. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR Refresh["🔄 refreshEmptyState()"] --> Changed{kind changed?} Changed -->|yes| Name["🏷️ emptyStateName(strings, view)"] Changed -->|no| Skip["⏭️ no re-announce"] Name --> Polite["🗣️ polite live region"] classDef event fill:#8B0000,stroke:#7C90A0,color:#fff classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff classDef name fill:#189AB4,stroke:#7C90A0,color:#fff classDef out fill:#10B981,stroke:#7C90A0,color:#fff class Refresh event class Changed decision class Name name class Polite,Skip out ``` The panel is `

` — a landmark named through `aria-labelledby`, **not** `aria-label`. A label on a generic container replaces its contents in the accessibility tree (the same rule 3 already in `a11y/names.ts`), costing the reader the heading, sentence, and button; a name that points at the panel's own heading keeps all three browsable. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { emptyStateName } from "praisonai-mobile/ui/a11y/names"; import { en } from "praisonai-mobile/ui/i18n/strings"; const view = { kind: "needs-key", title: "Add an API key to start", body: "PraisonAI answers using your own OpenAI account. Paste a key in Settings and this chat is ready.", action: { label: "Open settings", route: "settings" } } as const; emptyStateName(en, view); // "Add an API key to start PraisonAI answers … this chat is ready. Open settings" ``` `emptyStateName(strings, view)` composes `` `${title} ${body}${action?.label ? ' ' + action.label : ''}` ``. The composition root feeds this into the polite live region when the empty state appears **or changes kind** — so a fresh chat is not silent to a screen reader, and the "welcome → needs a key" transition (rule 3 of `empty-state.ts`) is announced. The action is part of the sentence because a reader hears the region before reaching anything focusable in it: "Open settings" arriving three tab stops later is a discovery, not an instruction. An empty `role="log"` announces nothing at all — that is why the region and its announcement exist. A screen-reader user who lands on a fresh chat, or taps New chat, would otherwise be told nothing about a screen that has just changed completely. ### The transcript is a log, not a live region The transcript element is `role="log"` with `aria-label={strings.appName}` and **no** `aria-live`. It is mutated on every publish, so making it a live region would restart the reader on each token batch and no sentence would ever finish — the announcer pipes completed sentences into the `polite` / `assertive` regions instead. A test asserts the transcript **does not** carry `aria-live`; this is the one-line regression its own comment warns about. ### The composer is labelled as the field, not as the button beside it The message textarea's `aria-label` is `strings.composerLabel` — never `strings.actionSend`. The Send button sits inside the same form control and shares its accessible tree, and a prior regression pointed the composer's label at the button's name, so a screen reader announced the message field as *"Send, edit text"*. A test asserts the composer's label is `composerLabel` and **not** `actionSend`. ### Starting a new chat empties the live regions When the user starts a new chat, the shell empties the `polite` and `assertive` live regions in addition to resetting the announcer state. Resetting the announcer decides what to *say* next; it does not empty the regions themselves — so without this clear, the previous conversation's answer lingered in the accessibility tree of an apparently empty chat. See [Overview → New chat](/docs/features/mobile/overview#new-chat). ### The sentence check runs at most once per `ANNOUNCE_INTERVAL_MS`, even when nothing new is spoken The screen-reader announcer holds back unfinished sentences (see [Sentence segmentation](#sentence-segmentation)) and rate-limits the segmentation check itself. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph TB Publish[📝 publish] --> InInterval{⏱️ inside interval?} InInterval -->|yes| Skip[⏭️ skip — return same state] InInterval -->|no| Check[🔍 segment + advance clock] Check --> Completed{✅ sentence completed?} Completed -->|yes| Speak[🗣️ say chunk] Completed -->|no| NewState[💾 new state — clock advanced] Speak --> NewState classDef event fill:#6366F1,stroke:#7C90A0,color:#fff classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff classDef action fill:#189AB4,stroke:#7C90A0,color:#fff classDef terminal fill:#10B981,stroke:#7C90A0,color:#fff class Publish event class InInterval,Completed decision class Check,Speak action class Skip,NewState terminal ``` Two cursors advance without necessarily producing speech: * `lastStreamAtMs` — records that the check ran, so the next publish inside the interval is skipped. * `spokenChars` — advances even when the completed prefix trims to an empty string, so the same completed prefix is not re-checked forever. Both are persisted across publishes. If either advances, the announcer returns a new state object; if nothing at all moves (74 out of every 75 publishes on a busy stream), the announcer returns the **same** state object by identity, so the caller can skip touching the live region entirely. Without these advances, a stretch where no sentence completes — a markdown table, a code block, a JSON dump, a bulleted list — used to leave the rate limit permanently open and re-segment the whole accumulated answer on every publish. Measured for 160 kB of unterminated text at the real publish cadence: 175 ms per publish (quadratic in answer length, \~700 ms of blocked main thread across one long answer) → 4.5 ms. The visible cost: a sentence that completes just after a check waits up to `ANNOUNCE_INTERVAL_MS` to be spoken. That is what the rate limit is for; when speech is flowing, behaviour is identical to before. The upstream side of this pipeline is the [SSE reader](/docs/features/mobile/protocol#frame-buffering). *** ## Focus after a button goes `disabled` The approval row disables its three buttons the instant a decision is in flight (`b.disabled = !row.actionable`), which stops a double tap sending two answers. But the user just pressed one of those buttons, so focus is **on** it — and disabling the focused element drops focus to `` with no event and no sound: the screen reader reads nothing, the next Tab starts from the top of the document, and a blind user cannot tell whether their answer went through. `focusAfterDisable` decides where focus goes instead, as a pure function over ids. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { focusAfterDisable } from "praisonai-mobile/ui/a11y/focus"; focusAfterDisable({ focusedId: "approval:a1:allow", disabledIds: ["approval:a1:allow", "approval:a1:always", "approval:a1:deny"], enabledIds: ["approval:a1:allow", "approval:a1:always", "approval:a1:deny", "composer"], containerId: "approval:a1", }); // -> { kind: "element", id: "composer" } — never the dead button, never ``` | Input | `focusAfterDisable` returns | Why | | ---------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `focusedId === null` | `{ kind: "none" }` | Focus is already elsewhere; do not move it. | | `focusedId` is **not** in `disabledIds` | `{ kind: "none" }` | Moving focus the user did not ask to move is its own bug — an approval resolving in the background must not steal the caret out of the composer. | | `focusedId` **is** in `disabledIds`, and another `enabledIds` entry is not in the disabled set | `{ kind: "element", id: }` | The user stays inside the group they were operating. | | `focusedId` **is** in `disabledIds`, and every `enabledIds` entry is being disabled too | `{ kind: "element", id: containerId }` | The row itself takes focus; its accessible name carries the decision state so the user hears "Approval required: bash. Sending your answer." instead of nothing. | The survivor search excludes the disabled set: `enabledIds.find((id) => !disabledIds.includes(id))`. Flipping that to `find(() => true)` (or dropping the guard) returns the first "enabled" id without checking whether it is one of the ids about to become disabled — and focus lands on the dead button the user just pressed. VoiceOver then drops focus to ``, and the user loses their place in the conversation. Pinned by `"focus never lands on a control that is itself being disabled"` and its pair `"focus stays put when the focused control is NOT being disabled"`. This is a decision function, not a `document.activeElement` call: `focusAfterDisable` returns a `FocusTarget` (`none` | `element` | `restore`) and the renderer applies it. Everything above the renderer is pure and testable. *** ## Transcript rows carry accessible names Every transcript row now carries an accessible name — `paint()` calls `accessibleName(strings, row)` on **insert and update**, so the whole `names.ts` module reaches the DOM for the first time. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph LR Paint["🎨 paint(row)"] --> Name["🏷️ accessibleName(strings, row)"] Name -->|non-null| Set["✅ set aria-label"] Name -->|null| Remove["🧹 remove aria-label"] classDef paint fill:#8B0000,stroke:#7C90A0,color:#fff classDef name fill:#189AB4,stroke:#7C90A0,color:#fff classDef set fill:#10B981,stroke:#7C90A0,color:#fff classDef remove fill:#F59E0B,stroke:#7C90A0,color:#fff class Paint paint class Name name class Set set class Remove remove ``` Until this landed, `accessibleName`, `toolRowName`, `approvalRowName`, and `errorRowName` had eleven tests and **zero callers** anywhere in the app — no transcript row carried an `aria-label` at all. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} // dom.ts — paint() names the row first, on insert AND update. const name = accessibleName(strings, row); if (name === null) el.removeAttribute("aria-label"); else el.setAttribute("aria-label", name); ``` The label repaints on **update**, not just insert: a tool inserted `running` and finishing in place would otherwise announce "Running" for the rest of the conversation. A row that changes kind in place must not keep a stale label either — the removal path applies there too. `null` is a real answer, not a gap. For a text row its own words are its name, and labelling it would replace the answer with a summary of it — so `null` **removes** the `aria-label` attribute rather than writing `"null"` or `""`. `aria-label=""` and no `aria-label` are different to a screen reader; the test fake (`testing/src/fake-dom.ts`) grew a real `removeAttribute` so a test could tell them apart. | Row kind | `aria-label` source | Why it matters | | ---------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `user` | `null` — the paragraph is announced by its own text | Same reason as `text`: an `aria-label` on your message would replace it with a summary. The speaker `"You said:"` is rendered as **visually-hidden content** ahead of the message, not as a label, so the paragraph keeps word / sentence / character navigation. See [Transcript User Row](/docs/features/mobile/transcript-user-row#accessibility). | | `text` | `null` — the paragraph is announced by its own text | Labelling a paragraph replaces its answer with a summary of it. | | `reasoning` | `null` — the paragraph is announced by its own text | The row now carries a visually-hidden `.sr-only` span with `strings.reasoningLabel` **ahead of** the text, as additive content — the same remedy the `user` row uses. Before [PR #4873](https://github.com/MervinPraison/PraisonAI/pull/4873), a `.row-reasoning` was told apart from an answer by CSS alone (left rule, softer colour, smaller font), none of which reaches the accessibility tree — so a reader heard the model's private working and its answer in one undifferentiated run. Reachable through the remote engine (`reasoning: true`). | | `tool` | `toolRowName(status, name, argsPreview)` — includes the status word | The status previously reached the DOM only as `data-status`, which `app.css` turned into a border colour — a screen-reader user heard "rm, —" for a tool that failed. | | `approval` | `approvalRowName(name, state.status)` — includes the decision state | While a decision is in flight every button on the row is disabled, and a disabled button is announced as "dimmed" or skipped — the row went silent at the exact moment the user was waiting to hear what happened. | | `error` | `errorRowName(kind, message)` — the `errorTitle` in front of the provider prose | The message is whatever the provider said; the kind is the only dependable part of the announcement. `errorRowName(kind, message)` is what the `aria-label` carries; [PR #4873](https://github.com/MervinPraison/PraisonAI/pull/4873) additionally paints the same title as a bold `.error-title` span inside the row, so sighted users see the kind in words too. See [Errors & Recovery → An error row shows the kind in words](/docs/features/mobile/errors-and-recovery#an-error-row-shows-the-kind-in-words). | | `chat` (in chats list) | `strings.chatUpdated(chatRowName(strings, row), updatedLabel)` — title + time | See [History & Reopen](/docs/features/mobile/history-and-reopen#the-chats-screen). | ### Tool status is now text, not colour alone `dom.ts` renders a `` carrying `strings.toolStatus(row.status)` in words, repainted on update — so status is no longer a colour-only channel. `app.css` styled `[data-status="failed"]` and `[data-status="ok"]` with a border colour and had **no rule at all** for `unresolved`, so a tool that never came back rendered pixel-for-pixel identically to one still running. The `.tool-status` span is what removes the "colour is the only channel" gap the transcript layer was written against (the view-model comment at `ui/src/transcript/view-model.ts:173`). ### A reasoning row is now told apart by content, not colour alone Since [PR #4873](https://github.com/MervinPraison/PraisonAI/pull/4873), `paint()` for `case "reasoning"` renders a visually-hidden `.sr-only` span carrying `strings.reasoningLabel` **ahead of** the text — additive content that supplements the prose rather than replacing it, exactly the pattern the `user` row already uses for its `"You said:"` speaker. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} // dom.ts — the reasoning kind is announced by an additive sr-only word. const label = el.ownerDocument.createElement("span"); label.className = "sr-only"; label.textContent = strings.reasoningLabel; const said = el.ownerDocument.createElement("span"); said.textContent = row.text; el.append(label, said); ``` `accessibleName` returns `null` for the reasoning kind on purpose (rule 3: a label on prose replaces the prose in the accessibility tree), so the label is *content*, not an `aria-label`. Before this, a `.row-reasoning` was distinguished from an answer by CSS alone — a left rule, a softer colour, a smaller font — none of which reaches the accessibility tree, so a reader arrowing through a transcript heard the model's private working and its actual answer as one undifferentiated run. The reasoning row is only reachable through the remote engine (`reasoning: true`); the default in-process engine declares `reasoning: false`, so a default-engine transcript never paints one. *** ## Chat-row accessible name Every chat row has a name: a titled row is announced by its title; an untitled one by the localised **"Untitled"** string — never as an empty accessible name. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { chatRowName } from "praisonai-mobile/ui/a11y/names"; import { en } from "praisonai-mobile/ui/i18n/strings"; chatRowName(en, { title: "Quarterly plan" }); // "Quarterly plan" chatRowName(en, { title: "" }); // en.untitled — never "" ``` | Row state | `chatRowName(en, row)` returns | Screen reader says | | -------------------------- | ------------------------------ | ------------------------------------------------- | | `title: "Quarterly plan"` | `"Quarterly plan"` | *"Quarterly plan, button"* | | `title: ""` | `en.untitled` | *"Untitled, button"* | | `title: ""` returning `""` | never | *"button"* — indistinguishable from the row above | The fallback is `en.untitled`, not the empty string. A nameless row reads as just *"button"* and cannot be told apart from its neighbours — which is exactly what a per-row accessible name exists to prevent. The guard is `row.title === "" ? strings.untitled : row.title`; flipping the `===` to `!==` reads a real title as *Untitled* and leaves an untitled row nameless. The row now carries more than a name. The **Open** button's label is `strings.chatUpdated(chatRowName(strings, row), row.updatedLabel)` — the title plus the last-updated time. A **Delete** button sits alongside, labelled `strings.deleteChat(row.title)` at rest or `strings.deleteChatConfirm(row.title)` once armed. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} // The clean title lives on the button's own dataset, not the parent's text. del.dataset["chatTitle"] = row.title; del.setAttribute("aria-label", strings.deleteChat(row.title)); ``` The clean title for the Delete label is carried on the button's own dataset (`data-chat-title`), **not** re-derived from `parentElement.textContent`. Reading the parent folded in the visible time and the button's own word, so arming produced labels like *"Delete Trip plan5m agoConfirm"* — pinned by `"a delete label names ONLY the chat, not its time and button text"` in `main.test.ts`. The armed label uses `deleteChatConfirm(title)`, which **names the consequence** ("Delete Trip plan? Tap Confirm to delete it. This cannot be undone.") — pinned by the same test. ### New user-visible strings The `Strings` interface gained members for the delete flow and the timed chat row, plus `speakerUser` and `userNotStored` for the user-message row. | Key | English default | Purpose | | -------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chatUpdated(title, when)` | `${title}, ${when}` | The chat row's accessible name — one string so the visible and spoken time cannot drift. | | `deleteChat(title)` | `Delete ${title}` | Resting label on a chat row's delete button — names the chat so a list of "Delete" buttons is not indistinguishable to a screen reader. | | `actionConfirmDelete` | `Confirm` | The armed button text. | | `deleteChatConfirm(title)` | `Delete ${title}? Tap Confirm to delete it. This cannot be undone.` | Armed `aria-label` and the assertive announcement — names the chat **and** says the consequence. | | `chatDeleted(title)` | `${title} was deleted.` | Assertive announcement after a successful delete. | | `chatDeleteFailed` | `That conversation could not be deleted.` | Assertive announcement when `storage.remove` rejects. | | `speakerUser` | `You said:` | The visually-hidden speaker announced ahead of your own message, so a screen reader can tell your question from the answer to it. | | `reasoningLabel` | `Reasoning:` | The visually-hidden `.sr-only` label painted ahead of a reasoning row's text — additive content that tells a screen-reader user the model's private working apart from its answer. Rendered into the DOM for the first time by [PR #4873](https://github.com/MervinPraison/PraisonAI/pull/4873); reachable only through the remote engine (`reasoning: true`). | | `userNotStored` | `Not saved — this message is not in the stored conversation` | The caveat on an `unstored` user row — a turn that ended with no `end.userIndex`. Says what happened **and** what it means, so the reader is not left guessing whether reopening finds the message. See [Transcript User Row](/docs/features/mobile/transcript-user-row#three-storage-states). | *** ## Missing-translation marks need both brackets The missing-strings reporter wraps an untranslated key as `⟦…⟧`, and `isMarked` only recognises a string carrying **both** brackets. ```ts theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import { markMissing, isMarked } from "praisonai-mobile/ui/i18n/bundle"; markMissing("save"); // "⟦save⟧" isMarked("⟦save⟧"); // true — opens ⟦ AND ends ⟧ isMarked("⟦save"); // false — a half-bracketed string ``` `isMarked(s)` returns `true` only when `s` starts with `⟦` **and** ends with `⟧`. A half-bracketed string — a translator's own literal `⟦` or `⟧` — is not a marked-missing key, so the report never blames translations that are actually present. The guard is `s.startsWith("⟦") && s.endsWith("⟧")`. Flipping the `&&` to `||` counts a lone bracket as a marked-missing key and reports a real, present translation as absent. Pinned by `"a half-bracketed string is not a marked-missing one"`. *** ## Best Practices `az-Arab` is right-to-left and `az` is not. A hand-written list of RTL language codes gets script variants wrong; the script subtag decides, and ICU is asked before the table. Older Android WebViews ship without `Intl.Locale.textInfo` and `Intl.Segmenter`, so `directionFromTables` and `fallbackSentences` are exported precisely to exercise the degraded path. But the fallback is not only an old-WebView concern: every `Intl` constructor throws `RangeError` on an underscore tag, and `locale.ts` accepts `"en_US"` as a valid stored preference — so the number, date, and duration fallbacks fire in production the moment a stored locale reaches the UI with an underscore. Announcing a half-typed sentence makes a screen reader say "The file cont" and then repeat the whole sentence. Speak only completed sentences and keep the tail until it terminates. *** ## Related Logical insets that mirror with direction. What each failure looks like on the phone. Focus and announcements on every route change. The composer's draft, autosize, and key policy. The empty-state panel these strings and the polite announcement serve.