@djangocfg/widget-chat 0.1.13 → 0.1.16

package/README.md

@@ -100,6 +100,33 @@ allowlist in `core/media/allowed-src.ts` — and the first reads it lazily for
 exactly this reason. Setting it later leaves already-written links addressing
 the old scheme, which then render as plain text.
 
+## Phones: the package owns the browser problems
+
+A host mounts `<ChatSheet>` around `<Chat>` and passes nothing else. Everything below is built in and on by default.
+
+```tsx
+import { Chat, ChatSheet } from "@djangocfg/widget-chat";
+import "@djangocfg/widget-chat/styles"; // includes styles/sheet.css
+
+<ChatSheet open={open} onOpenChange={setOpen} title="Assistant" closeLabel="Close">
+  <Chat adapter={adapter} body={{ kind: "packaged" }} className="flex min-h-0 flex-1 flex-col" />
+</ChatSheet>
+```
+
+| Problem | Root cause | Built-in answer |
+|---|---|---|
+| Panel does not fill the screen with the keyboard up; the page shows through | iOS keeps the layout viewport tall and pans the visual one; a `100dvh` layer is taller than what is visible and a rAF-late follower leaves a strip | `ChatSheet` is sized from `visualViewport` (`--vvh/--vvw/--vv-top/--vv-left/--kb`, written inside the event), with `dvh`/`svh`/`%` fallbacks, safe-area padding, an opaque backdrop behind it |
+| History jumps when the input is focused | `use-stick-to-bottom` watches the CONTENT, not the scroller. The keyboard shrinks the scroller, nothing grew, nothing followed; the browser's focus scroll was then read as the reader scrolling up and released the lock | `useHoldBottom` (inside `Transcript`): if the reader was within `PIN_THRESHOLD` (80px) of the bottom, a scroller resize, a viewport change or a field focus/blur re-pins instantly and ignores the browser's scrolls for `SETTLE_MS`. A reader scrolled up on purpose is left alone, and `JumpToLatest` is offered |
+| Page behind scrolls, is focusable, is read out | none of it was locked | `useLayer`: `inert` on the page root (`[data-app-root]`, else every other child of `<body>`), `overflow:hidden` on `<html>` with scrollbar compensation (never `position:fixed` on body, so no jump), `overscroll-behavior: contain`, Back closes (one history entry per layer, the page's own history state is kept), Escape via the dialog |
+
+Opt-outs: `behaviour={{ viewport, back, inert, appRoot, lockScroll, autoFocus }}`. Not on a phone sheet? `useViewportBox`, `useLayer` and `useHoldBottom` are exported from `primitives` for a host with its own layer; the pure parts (`readViewportBox`, `boxVars`, `nextPinned`, `distanceFromBottom`) from `core`. `focusComposerField` now focuses with `preventScroll`.
+
+The sheet's close label defaults to English "Close"; pass `closeLabel` for other languages.
+
+### What a real phone must confirm
+
+The maths and the pin decision are unit-tested; the following needs an iPhone (Safari and Chrome): the strip above the keyboard and the accessory bar, the iOS pan while typing, rotation, Back gesture vs. the app's own router history, the settle window length against the real keyboard animation, and `inert` with VoiceOver.
+
 ## Documentation
 
 This file is the contract. [`@docs/`](./@docs/README.md) is the long form —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-chat",
-  "version": "0.1.13",
+  "version": "0.1.16",
   "description": "A transport-agnostic chat surface: a pure core, a store, primitives, a composer, and the assembled components a host mounts",
   "keywords": [
     "chat",
@@ -55,8 +55,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@djangocfg/widget-kit": "^0.1.14",
-    "@djangocfg/widget-media": "^0.1.9",
+    "@djangocfg/widget-kit": "^0.1.16",
+    "@djangocfg/widget-media": "^0.1.12",
     "@streamdown/code": "^1.1.1",
     "@streamdown/math": "^1.0.2",
     "mdast-util-to-string": "^4.0.0",
@@ -66,19 +66,19 @@
     "use-stick-to-bottom": "^1.1.6"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.584",
-    "@djangocfg/i18n": "^2.1.584",
-    "@djangocfg/ui-core": "^2.1.584",
+    "@djangocfg/api": "^2.1.586",
+    "@djangocfg/i18n": "^2.1.586",
+    "@djangocfg/ui-core": "^2.1.586",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "remark-gfm": "^4.0.0",
     "streamdown": "^2.6.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.584",
-    "@djangocfg/i18n": "^2.1.584",
-    "@djangocfg/typescript-config": "^2.1.584",
-    "@djangocfg/ui-core": "^2.1.584",
+    "@djangocfg/api": "^2.1.586",
+    "@djangocfg/i18n": "^2.1.586",
+    "@djangocfg/typescript-config": "^2.1.586",
+    "@djangocfg/ui-core": "^2.1.586",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/composer/controls/voice.tsx

@@ -1,6 +1,8 @@
 import { ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
 import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
 
+import { useIsTouch } from "@djangocfg/ui-core/hooks";
+
 import { useChatCopy } from "../../i18n";
 import { useDismiss } from "../../primitives";
 import { useCapabilities, useVoice } from "../../store";
@@ -57,6 +59,9 @@ export function ComposerVoice({ className, children, language }: ComposerVoicePr
     language?.value,
     voiceSounds?.play,
   );
+  // A touch device has its own keyboard dictation: a second microphone (and its language picker) is a duplicate tile,
+  // whatever the host passes. A desktop keeps both.
+  const touch = useIsTouch();
   const [pickerOpen, setPickerOpen] = useState(false);
   // Which view the ONE panel is showing. A view switch rather than a second
   // popover: nesting one floating surface inside another makes both fight over
@@ -143,7 +148,7 @@ export function ComposerVoice({ className, children, language }: ComposerVoicePr
     if (!recording && text !== "") armed.current = false;
   }, [recording, text, setText]);
 
-  if (!available) return null;
+  if (!available || touch) return null;
 
   const micLabel = recording ? copy.stop : copy.start;
   const mic = (

package/src/composer/field/input.tsx

@@ -8,6 +8,7 @@ import {
   type Ref,
 } from "react";
 
+import { useTouchSafeStyle } from "@djangocfg/ui-core/hooks";
 import { FIELD_SIZING, useAutosize } from "./use-autosize";
 import { useComposer } from "../context";
 
@@ -89,6 +90,16 @@ export function ComposerInput({
   const { draft, setText, handlePaste, send, canSend } = useComposer();
   const ref = useRef<HTMLTextAreaElement | null>(null);
 
+  /**
+   * iOS WebKit auto-zoom prevention (iOS-only targeting).
+   *
+   * Returns max(16px, 1em) for iOS devices to prevent viewport zoom on focus.
+   * Android and desktop return undefined (keep optimal font-size).
+   *
+   * @see {@link @researches/2026-10-25__ios-webkit-auto-zoom}
+   */
+  const touchSafeFontSize = useTouchSafeStyle();
+
   /**
    * Fill the internal ref (autosize measures through it) and the host's, if
    * one was passed. A callback rather than handing the host `ref` directly:
@@ -195,14 +206,23 @@ export function ComposerInput({
        *
        * Empty on browsers without support, where the effect above sizes the box
        * instead. Never both — a written `height` would override this.
+       *
+       * iOS auto-zoom prevention: merge touchSafeFontSize if present (iOS-only).
+       * On Android/desktop, touchSafeFontSize is undefined and style remains unchanged.
        */
       // `fieldSizing` is newer than the pinned csstype, so the cast is the
       // property being real and the types being behind — not a shape being
       // forced. Remove it once csstype carries the property.
       style={
         FIELD_SIZING
-          ? ({ fieldSizing: "content", maxHeight: `${maxRows}lh` } as CSSProperties)
-          : undefined
+          ? ({
+              fieldSizing: "content",
+              maxHeight: `${maxRows}lh`,
+              ...(touchSafeFontSize && { fontSize: touchSafeFontSize }),
+            } as CSSProperties)
+          : touchSafeFontSize
+            ? ({ fontSize: touchSafeFontSize } as CSSProperties)
+            : undefined
       }
       onChange={onChange}
       onPaste={onPaste}

package/src/composer/focus-field.ts

@@ -21,7 +21,8 @@
 export function focusComposerField(root: HTMLElement | null | undefined): void {
   const field = root?.querySelector("textarea");
   if (!field || field === document.activeElement) return;
-  field.focus();
+  // `preventScroll`: the browser's own scroll-into-view moves ancestors and the page; the transcript pins itself.
+  field.focus({ preventScroll: true });
   const end = field.value.length;
   field.setSelectionRange(end, end);
 }

package/src/core/index.ts

@@ -32,3 +32,4 @@ export * from "./text-replace";
 // The mention URL scheme. Exported because `configureMentionScheme` is a host
 // call — the scheme is the host's product name, and nothing else can supply it.
 export * from "./links";
+export * from "./viewport";

package/src/core/scroll/index.ts

@@ -15,3 +15,5 @@ export { MissedCount, missedRows } from "./missed";
 export type { MissedRole } from "./missed";
 export { isOwnSend } from "./sent";
 export type { SentRole } from "./sent";
+export { PIN_THRESHOLD, SETTLE_MS, distanceFromBottom, nextPinned } from "./pin";
+export type { ScrollMetrics } from "./pin";

package/src/core/scroll/pin.ts

@@ -0,0 +1,34 @@
+// Whether the reader is "at the bottom", and whether the view should follow it.
+//
+// The follow itself is `use-stick-to-bottom`'s (see `primitives/use-stick-to-bottom`). What the library cannot
+// know is that the SCROLLER can change height without the content changing: an on-screen keyboard, a growing
+// composer, a rotation. The bottom then moves away under a reader who never scrolled. These two functions
+// decide, without a DOM, whether that reader was at the bottom and so must be taken back to it.
+
+/** Distance from the newest message that still counts as "at the bottom" (px). */
+export const PIN_THRESHOLD = 80;
+
+/** How long after a focus or a viewport change the browser's own scrolling is not read as the reader leaving (ms). The iOS keyboard animates for about 400. */
+export const SETTLE_MS = 700;
+
+export interface ScrollMetrics {
+  readonly scrollHeight: number;
+  readonly scrollTop: number;
+  readonly clientHeight: number;
+}
+
+export function distanceFromBottom(m: ScrollMetrics): number {
+  return Math.max(0, m.scrollHeight - m.scrollTop - m.clientHeight);
+}
+
+/**
+ * The reader's intent, updated on each scroll event.
+ *
+ * While `settling`, a scroll event is the BROWSER's (it scrolls a focused field into view, clamps a shrinking box),
+ * not the reader's, so the previous intent stands. Outside it, being within `threshold` of the bottom is being pinned
+ * and anything further is a reader who scrolled up on purpose.
+ */
+export function nextPinned(previous: boolean, m: ScrollMetrics, settling: boolean, threshold: number = PIN_THRESHOLD): boolean {
+  if (settling) return previous;
+  return distanceFromBottom(m) <= threshold;
+}

package/src/core/viewport/back-stack.ts

@@ -0,0 +1,28 @@
+/** One browser-history entry pushed by an open layer. `depth` is stored in the entry's state so a popstate tells how many entries are gone. */
+export interface Entry {
+  id: string;
+  depth: number;
+  /** The layer is still open. A layer closed from inside leaves a dead entry until `settle` removes it. */
+  live: boolean;
+}
+
+export function push(entries: Entry[], id: string): Entry[] {
+  return [...entries, { id, depth: entries.length + 1, live: true }];
+}
+
+/** The layer closed by itself (button, Escape, overlay). */
+export function release(entries: Entry[], id: string): Entry[] {
+  return entries.map((entry) => (entry.id === id ? { ...entry, live: false } : entry));
+}
+
+/** History moved to `depth` (0 = the page): entries above it are gone; the live ones among them must close. */
+export function reconcile(entries: Entry[], depth: number): { entries: Entry[]; closed: string[] } {
+  return { entries: entries.filter((e) => e.depth <= depth), closed: entries.filter((e) => e.depth > depth && e.live).map((e) => e.id) };
+}
+
+/** Dead entries on top of the stack are popped with one `history.go(-pop)`; dead ones under a live layer wait for it. */
+export function settle(entries: Entry[]): { entries: Entry[]; pop: number } {
+  let end = entries.length;
+  while (end > 0 && !entries[end - 1]?.live) end -= 1;
+  return { entries: entries.slice(0, end), pop: entries.length - end };
+}

package/src/core/viewport/box.ts

@@ -0,0 +1,57 @@
+// The visible area of a phone, as numbers. No DOM: `visualViewport` is read by
+// the caller (`primitives/use-viewport-box`) and handed in as plain values, so
+// the arithmetic is testable headless.
+
+/** Smallest shrink of the visible area that counts as an on-screen keyboard (a collapsing URL bar is about 100px). */
+export const KEYBOARD_MIN = 120;
+
+/** What `window.visualViewport` reports, as plain numbers. */
+export interface ViewportSample {
+  readonly width: number;
+  readonly height: number;
+  readonly offsetTop: number;
+  readonly offsetLeft: number;
+}
+
+export interface ViewportBox {
+  /** Visible width in px. */
+  readonly width: number;
+  /** Visible height in px. */
+  readonly height: number;
+  /** Distance of the visible area from the top of the layout viewport (iOS pans it when the keyboard opens). */
+  readonly top: number;
+  readonly left: number;
+  /** Keyboard height: the part of the layout viewport the visible area does not cover. */
+  readonly kb: number;
+  readonly keyboard: boolean;
+}
+
+/**
+ * Pure reading of `visualViewport`.
+ *
+ * iOS keeps the layout viewport tall (`kb` > 0) and pans the visual one; Android with
+ * `interactiveWidget: resizes-content` shrinks the layout viewport (`kb` stays 0), so the keyboard is
+ * also recognised by the visible height falling below the tallest one seen (`baseline`).
+ */
+export function readViewportBox(vv: ViewportSample, innerHeight: number, baseline: number): ViewportBox {
+  const kb = Math.max(0, Math.round(innerHeight - vv.height - vv.offsetTop));
+  return {
+    width: vv.width,
+    height: vv.height,
+    top: Math.max(0, vv.offsetTop),
+    left: Math.max(0, vv.offsetLeft),
+    kb,
+    keyboard: kb > KEYBOARD_MIN || baseline - vv.height > KEYBOARD_MIN,
+  };
+}
+
+/** The custom properties a layer carries so CSS can size itself from the box (`styles/sheet.css` reads them with fallbacks). */
+export function boxVars(box: ViewportBox): Record<string, string> {
+  return {
+    "--vvh": `${box.height}px`,
+    "--vvw": `${box.width}px`,
+    "--vv-top": `${box.top}px`,
+    "--vv-left": `${box.left}px`,
+    "--kb": `${box.kb}px`,
+  };
+}

package/src/core/viewport/index.ts

@@ -0,0 +1,8 @@
+// The phone's visible area and the browser-history stack of open layers: numbers and lists, no DOM.
+//
+// May import: utils.
+
+export { KEYBOARD_MIN, boxVars, readViewportBox } from "./box";
+export type { ViewportBox, ViewportSample } from "./box";
+export { push as pushLayer, reconcile as reconcileLayers, release as releaseLayer, settle as settleLayers } from "./back-stack";
+export type { Entry as LayerEntry } from "./back-stack";

package/src/i18n/index.ts

@@ -1,5 +1,4 @@
-import { useMemo } from "react";
-import { useLocaleOptional } from "@djangocfg/i18n";
+import { createCopy, type Locale } from "@djangocfg/i18n/copy";
 
 import { ar } from "./locales/ar";
 import { da } from "./locales/da";
@@ -30,58 +29,24 @@ export type {
   TranscriptCopy,
   VoiceCopy,
 } from "./types";
-export { fill, plural } from "./plural";
+export { fill, plural } from "@djangocfg/i18n/copy";
 
-/**
- * Every bundled dictionary, keyed by the language code the host reports.
- *
- * Exported so the registry test asserts against THIS object rather than its own
- * copy of the list: a second list is a second thing to forget, and what it
- * hides is a locale that silently never loads.
- */
-export const CHAT_DICTIONARIES: Readonly<Record<string, ChatCopy>> = {
-  en, ru, de, fr, es, it, nl, pl, sv, no, da, tr, ja, ko, zh, ar,
-  // The KEY is the language code the app reports (`pt-BR`), which is not a
-  // valid JS identifier — so the binding is `ptBR` and the key is quoted. Get
-  // this wrong and the lookup misses: every Brazilian user falls back to
-  // English with no error anywhere.
+/** Every bundled dictionary, typed complete over the shared `Locale` union. */
+export const CHAT_DICTIONARIES: Readonly<Record<Locale, ChatCopy>> = {
+  en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, pl, sv, no, da,
+  // The key is `pt-BR`, which is not a valid JS identifier, so the binding is `ptBR`.
   "pt-BR": ptBR,
 };
 
-/**
- * The chat dictionary for the active language, English for anything not yet
- * translated.
- *
- * The package owns its copy rather than taking it as props. Labels-in
- * looked right — it kept this package free of i18next — but it made adding one
- * string a four-file change and let a host assemble a translated string into a
- * DOM selector, which broke the composer's caret in a single locale with types
- * and tests green.
- *
- * The whole typed object, not a `t(key)` resolver: a dot-path string
- * reintroduces exactly the runtime miss that typing the schema removes.
- * `@djangocfg/i18n` types a CLOSED resources map, so a `chat` namespace does
- * not typecheck there, and opening one would point the dependency arrow from
- * `i18n` at this widget.
- *
- * `useLocaleOptional` returns null with no provider mounted, which is what lets
- * every surface render in Storybook and in a test without one.
- */
-export function useChatCopy(): ChatCopy {
-  const locale = useLocaleOptional();
-  return useMemo(() => (locale ? CHAT_DICTIONARIES[locale] ?? en : en), [locale]);
-}
+const kit = createCopy(CHAT_DICTIONARIES);
 
 /**
- * The active language tag, for `Intl.PluralRules`.
- *
- * Separate from the dictionary because the two can disagree: an untranslated
- * language falls back to the English STRINGS while its own plural CATEGORIES
- * still apply, and selecting `few` from a dictionary that has none is what the
- * `other` fallback in `plural()` exists to absorb.
+ * The chat dictionary for the active language: the `locale` prop, else the
+ * `@djangocfg/i18n` provider, else English. The package owns its copy rather
+ * than taking labels as props, because a host assembling a translated string
+ * into a DOM selector once broke the composer caret in a single locale.
  */
-export function useChatLanguage(): string {
-  // English rather than the empty string with no provider: `Intl.PluralRules`
-  // throws on an invalid tag, and a plural category is needed on every render.
-  return useLocaleOptional() ?? "en";
-}
+export const useChatCopy = kit.useCopy;
+
+/** The bundled locale in use, for `plural()`; a plural category is needed on every render. */
+export const useChatLanguage = kit.useLocale;

package/src/i18n/types.ts

@@ -11,22 +11,9 @@
  * onboarding one.
  */
 
-/**
- * The plural categories `Intl.PluralRules` can report.
- *
- * `other` is required and the rest are not, because a language HAS the
- * categories it has: English resolves only `one` and `other`, Russian adds
- * `few` and `many`, Japanese uses `other` alone. Requiring all six would force
- * an English catalogue to invent a `few` that no input can ever select.
- */
-export interface PluralCopy {
-  readonly zero?: string;
-  readonly one?: string;
-  readonly two?: string;
-  readonly few?: string;
-  readonly many?: string;
-  readonly other: string;
-}
+import type { PluralCopy } from "@djangocfg/i18n/copy";
+
+export type { PluralCopy };
 
 /** Copy for the transcript: the log, its empty state, and the wait. */
 export interface TranscriptCopy {

package/src/primitives/index.ts

@@ -41,3 +41,8 @@ export { useTurnActivity } from "./use-turn-activity";
 export type { TurnActivity } from "./use-turn-activity";
 export { ChatTooltip } from "./tooltip";
 export type { ChatTooltipProps } from "./tooltip";
+export { useHoldBottom } from "./use-hold-bottom";
+export type { HoldBottomOptions } from "./use-hold-bottom";
+export { useViewportBox, trackViewport } from "./use-viewport-box";
+export { useLayer } from "./use-layer";
+export type { UseLayerOptions } from "./use-layer";

package/src/primitives/layer-registry.ts

@@ -0,0 +1,49 @@
+import { pushLayer, reconcileLayers, releaseLayer, settleLayers, type LayerEntry } from "../core/viewport";
+
+/**
+ * Open layers as browser-history entries, so the phone's Back gesture closes the top layer instead of leaving the page.
+ * One entry per layer; `popstate` closes whatever the history left behind; a layer closed from inside has its entry
+ * removed after a short wait (a layer that opens right after keeps the stack consistent).
+ */
+let entries: LayerEntry[] = [];
+const closers = new Map<string, () => void>();
+let listening = false;
+let timer = 0;
+
+const SETTLE_MS = 60;
+const KEY = "__layer";
+const DEPTH = "__depth";
+
+function onPop() {
+  const state = window.history.state as Record<string, unknown> | null;
+  const depth = typeof state?.[DEPTH] === "number" ? (state[DEPTH] as number) : 0;
+  const next = reconcileLayers(entries, depth);
+  entries = next.entries;
+  next.closed.reverse().forEach((id) => closers.get(id)?.());
+}
+
+function flush() {
+  timer = 0;
+  const next = settleLayers(entries);
+  entries = next.entries;
+  if (next.pop > 0) window.history.go(-next.pop);
+}
+
+/** Registers an open layer; returns the call to make when it closes. `onBack` runs when the history leaves it. */
+export function registerLayer(id: string, onBack: () => void): () => void {
+  if (!listening) {
+    window.addEventListener("popstate", onPop);
+    listening = true;
+  }
+  entries = pushLayer(entries, id);
+  closers.set(id, onBack);
+  // Keep the page's own history state: a router that stored something there must still find it.
+  const own = (window.history.state ?? {}) as Record<string, unknown>;
+  window.history.pushState({ ...own, [KEY]: id, [DEPTH]: entries.length }, "");
+  return () => {
+    closers.delete(id);
+    entries = releaseLayer(entries, id);
+    window.clearTimeout(timer);
+    timer = window.setTimeout(flush, SETTLE_MS);
+  };
+}

package/src/primitives/transcript.tsx

@@ -10,6 +10,7 @@ import {
 import { useMissedCount } from "./use-missed-count";
 import { useReturnOnSend } from "./use-return-on-send";
 import { useRovingFocus } from "./use-roving-focus";
+import { useHoldBottom } from "./use-hold-bottom";
 import { useStickToBottom } from "./use-stick-to-bottom";
 import { useTurnActivity, type TurnActivity } from "./use-turn-activity";
 
@@ -102,7 +103,8 @@ export function Transcript({
   const ids = useMessageIds();
   const historyLoaded = useHistoryLoaded();
   const activity = useTurnActivity();
-  const { ref, contentRef, onScroll, isPinned, scrollToBottom } = useStickToBottom(ids.length);
+  const { ref, contentRef, onScroll, isPinned, scrollToBottom, holdBottom } = useStickToBottom(ids.length);
+  const hold = useHoldBottom({ hold: holdBottom });
   const missed = useMissedCount(ids, isPinned);
   useReturnOnSend(ids, scrollToBottom);
   const roving = useRovingFocus(ids.length);
@@ -115,9 +117,10 @@ export function Transcript({
   const attach = useCallback(
     (node: HTMLDivElement | null) => {
       ref(node);
+      hold(node);
       surfaces?.registerTranscript(node);
     },
-    [ref, surfaces],
+    [ref, hold, surfaces],
   );
 
   // Two things suppress the empty state, both because it would be a LIE.

package/src/primitives/use-hold-bottom.ts

@@ -0,0 +1,88 @@
+/**
+ * Keep the reader at the bottom when the SCROLLER changes height and the content does not.
+ *
+ * Root cause of "the history jumps when the input gets focus". `use-stick-to-bottom` observes the CONTENT element, so
+ * it follows text that grows; it does not observe the scroller. When the keyboard opens (or the composer grows, or the
+ * phone turns) the scroller gets shorter, `scrollTop` stays, and the newest messages are now below the fold: nothing
+ * grew, so nothing followed. Worse, the browser scrolls the focused field into view in the same moment; the scroller
+ * moves up, the library reads that as the reader scrolling up, "escapes" the lock, and from then on neither follows
+ * nor shows the bottom.
+ *
+ * What this does, with the decisions in `core/scroll/pin.ts`:
+ *  - remembers whether the reader is within `PIN_THRESHOLD` of the bottom, from scroll events, EXCEPT those inside a
+ *    settle window opened by a field gaining or losing focus or by the visual viewport changing (those are the browser's);
+ *  - when the scroller resizes or the viewport moves and the reader was pinned, re-pins instantly and tells the library
+ *    to ignore escapes for the window. A reader who scrolled up on purpose is not pinned, so nothing happens to them.
+ */
+
+import { useCallback, useRef } from "react";
+
+import { PIN_THRESHOLD, SETTLE_MS, nextPinned } from "../core/scroll";
+
+export interface HoldBottomOptions {
+  /** Re-pin for `ms` (the stick-to-bottom engine's `holdBottom`). */
+  readonly hold: (ms: number) => void;
+  /** Distance from the bottom that still counts as pinned. */
+  readonly threshold?: number;
+}
+
+const isField = (target: EventTarget | null): boolean =>
+  target instanceof HTMLElement && (target.matches("textarea, input, select") || target.isContentEditable);
+
+function attach(node: HTMLElement, hold: (ms: number) => void, threshold: number): () => void {
+  let pinned = true;
+  let settleUntil = 0;
+  const settling = () => performance.now() < settleUntil;
+  const metrics = () => ({ scrollHeight: node.scrollHeight, scrollTop: node.scrollTop, clientHeight: node.clientHeight });
+
+  const open = () => {
+    settleUntil = performance.now() + SETTLE_MS;
+  };
+  const follow = () => {
+    if (pinned) hold(Math.max(settleUntil - performance.now(), 120));
+  };
+  const onScroll = () => {
+    pinned = nextPinned(pinned, metrics(), settling(), threshold);
+  };
+  const onFocus = (event: FocusEvent) => {
+    if (!isField(event.target)) return;
+    open();
+    follow();
+  };
+  const onViewport = () => {
+    open();
+    follow();
+  };
+
+  // Seed from the real position, in case the transcript opened already scrolled.
+  pinned = nextPinned(true, metrics(), false, threshold);
+  node.addEventListener("scroll", onScroll, { passive: true });
+  document.addEventListener("focusin", onFocus);
+  document.addEventListener("focusout", onFocus);
+  const vv = window.visualViewport;
+  vv?.addEventListener("resize", onViewport);
+  const observer = new ResizeObserver(follow);
+  observer.observe(node);
+  return () => {
+    node.removeEventListener("scroll", onScroll);
+    document.removeEventListener("focusin", onFocus);
+    document.removeEventListener("focusout", onFocus);
+    vv?.removeEventListener("resize", onViewport);
+    observer.disconnect();
+  };
+}
+
+/** A ref callback for the SCROLLER; compose it with the one the stick-to-bottom engine needs. */
+export function useHoldBottom({ hold, threshold = PIN_THRESHOLD }: HoldBottomOptions): (node: HTMLElement | null) => void {
+  const stop = useRef<(() => void) | null>(null);
+  const latest = useRef(hold);
+  latest.current = hold;
+  return useCallback(
+    (node: HTMLElement | null) => {
+      stop.current?.();
+      stop.current = null;
+      if (node && typeof ResizeObserver !== "undefined") stop.current = attach(node, (ms) => latest.current(ms), threshold);
+    },
+    [threshold],
+  );
+}

package/src/primitives/use-layer.ts

@@ -0,0 +1,113 @@
+import { useEffect, useRef } from "react";
+
+import { registerLayer } from "./layer-registry";
+
+export interface UseLayerOptions {
+  /** Back closes the layer (a history entry per open layer). Default true. */
+  readonly back?: boolean;
+  /** Make the page behind inert while open. Default true. */
+  readonly inert?: boolean;
+  /**
+   * The page's root, when the host can name it; absent, every direct child of `<body>` that does not
+   * contain `layer` is made inert. A selector, an element, or a function returning elements.
+   */
+  readonly appRoot?: string | Element | (() => Iterable<Element>);
+  /** Lock page scroll without shifting the layout while open. Default true. */
+  readonly lockScroll?: boolean;
+  /** The layer's own element. It, and anything holding it, is never made inert. */
+  readonly layer?: () => Element | null;
+}
+
+let open = 0;
+const inerted = new Map<Element, boolean>();
+let saved: { html: string; body: string; gutter: string } | null = null;
+
+/**
+ * Never inert: scripts, the dialog's own portal (it is mounted a tick after the effect runs, so the layer ref can
+ * still be empty), focus guards, and toast regions the reader must still be able to dismiss.
+ */
+function isLayerHost(el: Element): boolean {
+  return (
+    el.tagName === "SCRIPT" ||
+    el.hasAttribute("data-radix-portal") ||
+    el.hasAttribute("data-radix-focus-guard") ||
+    el.hasAttribute("data-sonner-toaster") ||
+    el.matches('[role="dialog"], [aria-modal="true"]') ||
+    el.querySelector('[role="dialog"][data-state="open"], [aria-modal="true"]') !== null
+  );
+}
+
+function targets(options: UseLayerOptions): Element[] {
+  const layer = options.layer?.() ?? null;
+  const root = options.appRoot;
+  let list: Element[];
+  if (typeof root === "function") list = [...root()];
+  else if (root instanceof Element) list = [root];
+  else if (typeof root === "string") list = [...document.querySelectorAll(root)];
+  else {
+    const marked = [...document.querySelectorAll("[data-app-root]")];
+    list = marked.length > 0 ? marked : [...document.body.children];
+  }
+  return list.filter((el) => !(layer && (el === layer || el.contains(layer))) && !isLayerHost(el));
+}
+
+/**
+ * No layout shift on lock: `overflow: hidden` on `<html>` removes a desktop scrollbar, so its width is replaced by
+ * padding; on a phone the scrollbar overlays and nothing moves. The body is never `position: fixed` (that resets the
+ * scroll position and jumps the page on close).
+ */
+function lock(on: boolean, options: UseLayerOptions) {
+  const html = document.documentElement;
+  if (on) {
+    if (open === 0) {
+      saved = { html: html.style.overflow, body: document.body.style.paddingRight, gutter: html.style.overscrollBehaviorY };
+      if (options.lockScroll !== false) {
+        const bar = window.innerWidth - html.clientWidth;
+        html.style.overflow = "hidden";
+        if (bar > 0) document.body.style.paddingRight = `${bar}px`;
+      }
+      html.style.overscrollBehaviorY = "contain";
+    }
+    open += 1;
+    if (options.inert !== false) {
+      for (const el of targets(options)) {
+        if (!inerted.has(el)) inerted.set(el, el.hasAttribute("inert"));
+        el.setAttribute("inert", "");
+      }
+    }
+    return;
+  }
+  open -= 1;
+  if (open > 0) return;
+  for (const [el, was] of inerted) if (!was) el.removeAttribute("inert");
+  inerted.clear();
+  if (saved) {
+    html.style.overflow = saved.html;
+    document.body.style.paddingRight = saved.body;
+    html.style.overscrollBehaviorY = saved.gutter;
+    saved = null;
+  }
+}
+
+/**
+ * What an open full-screen layer needs besides the dialog itself: the page behind inert (no focus, no taps, no screen
+ * reader, no keyboard accessory fields), page scroll locked without a shift, no pull-to-refresh behind it, and the
+ * phone's Back closing it. Escape is the dialog's own.
+ */
+export function useLayer(isOpen: boolean, close: () => void, options: UseLayerOptions = {}): void {
+  const id = useRef(`layer-${Math.random().toString(36).slice(2)}`);
+  const closeRef = useRef(close);
+  closeRef.current = close;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  useEffect(() => {
+    if (!isOpen) return;
+    const opts = optionsRef.current;
+    lock(true, opts);
+    const release = opts.back === false ? () => {} : registerLayer(id.current, () => closeRef.current());
+    return () => {
+      release();
+      lock(false, opts);
+    };
+  }, [isOpen]);
+}

package/src/primitives/use-stick-to-bottom.ts

@@ -33,6 +33,11 @@ export interface StickToBottom {
   /** False while the user is reading history — render a "jump to latest" control. */
   readonly isPinned: boolean;
   readonly scrollToBottom: () => void;
+  /**
+   * Re-pin to the bottom for `ms`, instantly, and treat any scroll the BROWSER makes in that time (focus scrolling,
+   * keyboard clamping) as not the reader's. Used by `useHoldBottom`.
+   */
+  readonly holdBottom: (ms: number) => void;
 }
 
 /**
@@ -79,5 +84,12 @@ export function useStickToBottom(_revision: number): StickToBottom {
     void scrollToBottom();
   }, [scrollToBottom]);
 
-  return { ref, contentRef: content, onScroll, isPinned: isAtBottom, scrollToBottom: jump };
+  const hold = useCallback(
+    (ms: number) => {
+      void scrollToBottom({ animation: "instant", ignoreEscapes: true, duration: ms });
+    },
+    [scrollToBottom],
+  );
+
+  return { ref, contentRef: content, onScroll, isPinned: isAtBottom, scrollToBottom: jump, holdBottom: hold };
 }

package/src/primitives/use-viewport-box.ts

@@ -0,0 +1,79 @@
+import { useCallback, useRef, type RefCallback } from "react";
+
+import { boxVars, readViewportBox } from "../core/viewport";
+
+interface TrackOptions {
+  /** The keyboard opened or closed. */
+  readonly onKeyboard?: (open: boolean) => void;
+}
+
+/**
+ * Keeps `--vvh`, `--vvw`, `--vv-top`, `--vv-left`, `--kb` and `data-keyboard` of `node` equal to the visible area while the keyboard is up; with it down only `--kb: 0px` stays and CSS sizes the layer from `dvh`.
+ *
+ * Reads once at once (from the ref callback, before the first paint), then on `visualViewport` resize and scroll and on
+ * rotation. The write happens INSIDE the event, not a frame later: iOS pans the visual viewport during the keyboard
+ * animation, and a layer that follows one frame late shows the page behind it as a strip. A rotation is read again
+ * after it settles, because iOS reports the old size mid-turn. Styles are written directly, so there is no React render
+ * per event.
+ */
+export function trackViewport(node: HTMLElement, { onKeyboard }: TrackOptions = {}): () => void {
+  const vv = window.visualViewport;
+  if (!vv) return () => {};
+  let baseline = vv.height;
+  let keyboard = false;
+  let settle = 0;
+
+  const apply = () => {
+    const box = readViewportBox(vv, window.innerHeight, baseline);
+    baseline = Math.max(baseline, box.height);
+    // Only a raised keyboard needs the measured box. Without one the CSS fallbacks (`dvh`, top 0) are exact, and the
+    // measured numbers are not trustworthy: iOS 26 leaves `offsetTop` stale after the keyboard closes, which pushed the sheet down.
+    for (const [name, value] of Object.entries(boxVars(box))) {
+      if (box.keyboard || name === "--kb") node.style.setProperty(name, value);
+      else node.style.removeProperty(name);
+    }
+    if (box.keyboard !== keyboard) {
+      keyboard = box.keyboard;
+      node.toggleAttribute("data-keyboard", keyboard);
+      onKeyboard?.(keyboard);
+    }
+  };
+  const rotated = () => {
+    baseline = 0;
+    apply();
+    window.clearTimeout(settle);
+    settle = window.setTimeout(() => {
+      baseline = vv.height;
+      apply();
+    }, 250);
+  };
+
+  apply();
+  vv.addEventListener("resize", apply);
+  vv.addEventListener("scroll", apply);
+  window.addEventListener("orientationchange", rotated);
+  return () => {
+    vv.removeEventListener("resize", apply);
+    vv.removeEventListener("scroll", apply);
+    window.removeEventListener("orientationchange", rotated);
+    window.clearTimeout(settle);
+  };
+}
+
+/** A ref for the layer element: while it is mounted and `enabled`, it carries the box (see `trackViewport`). */
+export function useViewportBox<T extends HTMLElement>(
+  enabled: boolean,
+  onKeyboard?: (open: boolean) => void,
+): RefCallback<T> {
+  const stop = useRef<(() => void) | null>(null);
+  const keyboard = useRef(onKeyboard);
+  keyboard.current = onKeyboard;
+  return useCallback(
+    (node: T | null) => {
+      stop.current?.();
+      stop.current = null;
+      if (node && enabled) stop.current = trackViewport(node, { onKeyboard: (open) => keyboard.current?.(open) });
+    },
+    [enabled],
+  );
+}

package/src/styles/composer.css

@@ -447,3 +447,44 @@
     transition: none;
   }
 }
+
+/* ============================================================================
+   iOS WebKit Auto-Zoom Prevention (CSS Baseline)
+   ========================================================================= */
+
+/**
+ * Prevents iOS Safari/Chrome from zooming viewport when textarea gets focus.
+ *
+ * **Problem**: iOS WebKit zooms when font-size < 16px, causing conversation
+ * to "fly away" and creating critical UX failure in chat interfaces.
+ *
+ * **Solution**: Multi-layer defense:
+ * 1. CSS baseline (works without JS) — @supports iOS detection + mobile media
+ * 2. React hook (useTouchSafeStyle) — precise iOS-only targeting via device detect
+ *
+ * **WCAG Compliance**: ✅ WCAG 2.1 AA (SC 1.4.4, 1.4.10)
+ * - No viewport restrictions (user-scalable=no would violate WCAG)
+ * - Text zoom still works via browser accessibility settings
+ * - Maintains 200% text zoom capability
+ *
+ * @see {@link @researches/2026-10-25__ios-webkit-auto-zoom} Research
+ * @see {@link @djangocfg/ui-core/hooks/device/useTouchSafeStyle} React hook
+ */
+
+/* iOS-specific via @supports (CSS feature detection) */
+@supports (-webkit-touch-callout: none) {
+  .composer-box textarea,
+  .composer-box input,
+  .composer-box select {
+    font-size: max(1rem, 16px);
+  }
+}
+
+/* Mobile baseline (all devices, fallback for browsers without @supports) */
+@media (max-width: 768px) {
+  .composer-box textarea,
+  .composer-box input,
+  .composer-box select {
+    font-size: max(1rem, 16px);
+  }
+}

package/src/styles/index.css

@@ -45,3 +45,4 @@
 @import "./markdown.css";
 @import "./block.css";
 @import "./tool.css";
+@import "./sheet.css";

package/src/styles/sheet.css

@@ -0,0 +1,71 @@
+/*
+ * The chat sheet: one layer exactly as big as the VISIBLE area of a phone.
+ *
+ * `useViewportBox` writes --vvh / --vvw (visible size), --vv-top / --vv-left (offset from the layout viewport, which
+ * iOS pans when the keyboard opens) and --kb (keyboard height) on it. The fallbacks make the first frame right before
+ * any script has run: `dvh` where it exists, `svh`, then 100%. Unlayered on purpose: it wins over the dialog's own
+ * utility classes. No transition on top or height, only a fade on open.
+ *
+ * Two things keep the page from showing through. The sheet is opaque and sized from the visual viewport; and a
+ * backdrop the size of the whole layout viewport sits behind it, so a frame in which the sheet lags the keyboard
+ * animation shows the sheet's colour, not the page.
+ */
+.chat-sheet {
+  position: fixed;
+  left: var(--vv-left, 0px);
+  top: var(--vv-top, 0px);
+  right: auto;
+  bottom: auto;
+  width: var(--vvw, 100%);
+  height: 100%;
+  height: 100svh;
+  height: var(--vvh, 100dvh);
+  max-width: none;
+  max-height: none;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  background: var(--background, canvas);
+  overscroll-behavior: contain;
+  touch-action: manipulation;
+  transform: none;
+  /* Safe areas: the notch and the home bar are inside the visible area only while no keyboard covers them. */
+  padding-top: env(safe-area-inset-top);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+  padding-bottom: env(safe-area-inset-bottom);
+  transition: none;
+  animation: none;
+}
+/* With the keyboard up the home bar is under it. */
+.chat-sheet[data-keyboard] {
+  padding-bottom: 0;
+}
+/* The backing is a shadow, not a pseudo-element: a fixed child is clipped by the sheet's `overflow: hidden` as soon as the dialog's animation or transform makes the sheet its containing block. A box-shadow paints outside the box and is never clipped by it. */
+.chat-sheet {
+  box-shadow: 0 0 0 100vmax var(--background, canvas);
+}
+.chat-sheet[data-state="open"] {
+  animation: chat-sheet-in 140ms ease-out;
+}
+@keyframes chat-sheet-in {
+  from { opacity: 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .chat-sheet[data-state="open"] { animation: none; }
+}
+
+/*
+ * The conversation inside a sheet (or any host column): the transcript takes the free height and scrolls, the composer
+ * sits right under it. `min-height: 0` is what lets the scroller shrink with the keyboard instead of pushing the composer out.
+ */
+.chat-sheet-body {
+  display: flex;
+  flex: 1 1 0;
+  min-height: 0;
+  flex-direction: column;
+}
+.chat-sheet-body > .chat-surface {
+  flex: 1 1 0;
+  min-height: 0;
+}

package/src/ui/chat-sheet.tsx

@@ -0,0 +1,107 @@
+import { X } from "lucide-react";
+import { useCallback, useRef, type ReactNode } from "react";
+
+import {
+  Button,
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+} from "@djangocfg/ui-core/components";
+
+import { useLayer, useViewportBox, type UseLayerOptions } from "../primitives";
+
+export interface ChatSheetProps {
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+  /** The heading, and the dialog's accessible name. */
+  readonly title: string;
+  /** What the thread is about, under the title. */
+  readonly description?: string;
+  /** Accessible name of the close button. Default "Close". */
+  readonly closeLabel?: string;
+  /** Controls in the header, before the close button (a "more" menu, for one). */
+  readonly actions?: ReactNode;
+  /** The `<Chat>` (or the host's own column). */
+  readonly children: ReactNode;
+  /**
+   * Opt-outs. Everything is ON by default; the host passes nothing.
+   * `viewport`: size the layer from `visualViewport` (keyboard, pan, safe areas).
+   * `back`: the phone's Back closes it.
+   * `inert`: the page behind is inert. `appRoot` names the page root (selector, element or function); absent, the `[data-app-root]` element, else every other child of `<body>`.
+   * `lockScroll`: page scroll is locked without a layout shift.
+   * `autoFocus`: focus the field on open (off on phones: it would raise the keyboard over the answer).
+   */
+  readonly behaviour?: {
+    readonly viewport?: boolean;
+    readonly back?: boolean;
+    readonly inert?: boolean;
+    readonly appRoot?: UseLayerOptions["appRoot"];
+    readonly lockScroll?: boolean;
+    readonly autoFocus?: boolean;
+  };
+  readonly className?: string;
+}
+
+/**
+ * The chat on a phone: a full-screen dialog exactly the size of the visible area, with header, transcript and composer
+ * in one column. The package owns the browser problems of that surface: the layer follows `visualViewport` (no gap above
+ * the keyboard, no page showing through), the page behind is inert and not scrolled or shifted, Back and Escape close
+ * it, and the transcript stays pinned to the newest message while the keyboard opens (`Transcript`).
+ */
+export function ChatSheet({ open, onOpenChange, title, description, closeLabel = "Close", actions, children, behaviour, className }: ChatSheetProps) {
+  const layer = useRef<HTMLDivElement | null>(null);
+  const heading = useRef<HTMLHeadingElement>(null);
+  const sized = useViewportBox<HTMLDivElement>(open && behaviour?.viewport !== false);
+  const attach = useCallback(
+    (node: HTMLDivElement | null) => {
+      layer.current = node;
+      sized(node);
+    },
+    [sized],
+  );
+  useLayer(open, useCallback(() => onOpenChange(false), [onOpenChange]), {
+    back: behaviour?.back,
+    inert: behaviour?.inert,
+    appRoot: behaviour?.appRoot,
+    lockScroll: behaviour?.lockScroll,
+    layer: () => layer.current,
+  });
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        ref={attach}
+        fullscreen
+        closeButton={false}
+        className={`chat-sheet ${className ?? ""}`}
+        onOpenAutoFocus={(event) => {
+          if (behaviour?.autoFocus) return;
+          event.preventDefault();
+          heading.current?.focus({ preventScroll: true });
+        }}
+      >
+        <header className="flex shrink-0 items-center justify-between gap-3 border-b px-4 py-2">
+          <div className="min-w-0">
+            <DialogTitle ref={heading} tabIndex={-1} className="truncate text-base font-semibold outline-none">
+              {title}
+            </DialogTitle>
+            {description ? (
+              <DialogDescription className="truncate text-xs text-muted-foreground">{description}</DialogDescription>
+            ) : null}
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {actions}
+            <DialogClose asChild>
+              <Button variant="ghost" size="icon" aria-label={closeLabel}>
+                <X className="size-5" aria-hidden="true" />
+              </Button>
+            </DialogClose>
+          </div>
+        </header>
+        <div className="chat-sheet-body">{children}</div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/ui/index.ts

@@ -52,3 +52,5 @@ export { CollapseTrigger, useCollapse } from "./collapsible-body";
 export type { Collapse, CollapseState } from "./collapsible-body";
 export { LinkChip } from "./link-chip";
 export type { LinkChipProps } from "./link-chip";
+export { ChatSheet } from "./chat-sheet";
+export type { ChatSheetProps } from "./chat-sheet";

package/src/i18n/plural.ts

@@ -1,62 +0,0 @@
-import type { PluralCopy } from "./types";
-
-/**
- * Fill `{{name}}` placeholders.
- *
- * The dictionary is plain strings, so there is no interpolator behind it. A
- * template literal at each call site would put copy assembly back into JSX,
- * which is the seam this package's i18n exists to close.
- */
-export function fill(
-  template: string,
-  values: Readonly<Record<string, string | number>>,
-): string {
-  return template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
-    const value = values[key];
-    return value === undefined ? match : String(value);
-  });
-}
-
-/**
- * One `Intl.PluralRules` per language, kept for the life of the tab.
- *
- * Constructing one costs a locale-data lookup, and the composer's queue summary
- * re-renders on every keystroke while a turn streams. The cache is unbounded on
- * purpose: its key space is the language list, seventeen entries.
- */
-const rules = new Map<string, Intl.PluralRules>();
-
-function rulesFor(language: string): Intl.PluralRules {
-  const cached = rules.get(language);
-  if (cached !== undefined) return cached;
-  // An unknown or malformed tag throws rather than falling back, and a bad
-  // language must not take the composer down — English plurals on an unknown
-  // tag are wrong in a way the user can read past.
-  let made: Intl.PluralRules;
-  try {
-    made = new Intl.PluralRules(language);
-  } catch {
-    made = new Intl.PluralRules("en");
-  }
-  rules.set(language, made);
-  return made;
-}
-
-/**
- * Choose a plural form and fill `{{count}}`.
- *
- * Falls back to `other` when the category a language selects is absent from the
- * dictionary. That is not a defect to fail on: `other` is required by the type,
- * so a fallback always exists, and rendering the wrong-but-readable form beats
- * rendering nothing at the moment a user is counting their own queued prompts.
- */
-export function plural(
-  copy: PluralCopy,
-  count: number,
-  language: string,
-  values: Readonly<Record<string, string | number>> = {},
-): string {
-  const category = rulesFor(language).select(count);
-  const template = copy[category] ?? copy.other;
-  return fill(template, { ...values, count });
-}