@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/dist/hooks/scrollKeyboardDelegation.js

@@ -2,9 +2,11 @@
 
 /**
  * @file scrollKeyboardDelegation.ts
- * @input A named, overflowing viewport and its real content box
+ * @input A named, overflowing viewport and its real content box (the viewport
+ *   itself when it has no separate content box)
  * @output Focus-time delegation with native forward and reverse Tab traversal
- * @position Private useScrollableArea keyboard behavior; no DOM observers or scrolling
+ * @position Private keyboard behavior of useScrollableArea and of AppShell's main
+ *   region; no DOM observers or scrolling
  */
 
 import { FOCUSABLE_SELECTOR } from "./focusableSelector.js";
@@ -22,7 +24,9 @@ function isSequential(element) {
 }
 function firstDelegationTarget(viewport, content) {
   const candidates = content.querySelectorAll(FOCUSABLE_SELECTOR);
-  let first = content.matches(FOCUSABLE_SELECTOR) && isSequential(content) ? content : null;
+  // A viewport that is its own content box is the stop being entered, never
+  // the target it delegates to.
+  let first = content !== viewport && content.matches(FOCUSABLE_SELECTOR) && isSequential(content) ? content : null;
   for (const candidate of candidates) {
     // After finding the first target, only positive tabindex can precede it.
     // Ordinary trailing controls need no visibility or layout reads.

package/dist/hooks/useAdaptivePresentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAdaptivePresentation.d.ts","sourceRoot":"","sources":["../../src/hooks/useAdaptivePresentation.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAC3E,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAChD,oBAAoB,EACpB,UAAU,CACX,CAAC;AAMF,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAKpE;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,oBAAoB,GACjC,4BAA4B,CA4B9B"}
+{"version":3,"file":"useAdaptivePresentation.d.ts","sourceRoot":"","sources":["../../src/hooks/useAdaptivePresentation.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;AAC3E,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAChD,oBAAoB,EACpB,UAAU,CACX,CAAC;AAMF,eAAO,MAAM,gCAAgC,QAAsB,CAAC;AAKpE;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,oBAAoB,GACjC,4BAA4B,CA4B9B"}

package/dist/hooks/useAdaptivePresentation.js

@@ -7,7 +7,10 @@
  * @input Uses React's external-store subscription over window.matchMedia
  *   and the touch presentation's compact-touch query
  * @output Resolves popover/bottom-sheet presentation policy
- * @position Internal overlay policy shared across component families
+ * @position Internal overlay policy shared across component families. A
+ *   component that also switches input modes under a finger resolves its
+ *   `presentation` with usePresentation (utils/presentation.ts), whose
+ *   surface is this one's
  */
 import { useCallback, useSyncExternalStore } from 'react';
 import { COMPACT_TOUCH_QUERY, useCompactDefinition } from "../utils/touchPresentation.js";

package/dist/hooks/useAnnounce.d.ts

@@ -3,10 +3,11 @@
  * @input Uses React context and useCallback; DOM APIs and cancellable
  *   animation frames for a singleton live-region pair on the page body and
  *   one persistent polite/assertive pair inside each open Astryx modal
- * @output Exports useAnnounce hook and AnnouncePoliteness type; the internal
- *   modal context, the in-dialog region writer the busy-announcement hook
- *   uses, and the hook the modal route (`modalAnnounce.ts`, loaded only with
- *   an Astryx modal) installs itself through
+ * @output Exports useAnnounce hook (with its `hasReplace` option),
+ *   AnnouncePoliteness and UseAnnounceOptions types; the internal modal
+ *   context, the in-dialog region writer the busy-announcement hook uses, and
+ *   the hook the modal route (`modalAnnounce.ts`, loaded only with an Astryx
+ *   modal) installs itself through
  * @position Core a11y hook; provides imperative screen-reader announcements.
  *   A message follows the nearest open native modal enclosing its caller
  *   (`spec:AST-086` FR14): inside an Astryx modal it is written to that
@@ -14,10 +15,14 @@
  *   while a native modal is open; otherwise to the shared page-body pair.
  *   Containers are created empty (FR3), carry the two urgencies (FR5), join
  *   messages written before the previous is exposed and say an identical
- *   same-frame repeat once (FR9), and clear shortly after each announcement;
+ *   same-frame repeat once (FR9), except that a `hasReplace` instance's
+ *   message withdraws that instance's previous one not yet exposed, and clear
+ *   shortly after each announcement;
  *   the route in `modalAnnounce.ts` hands a message still unexposed when its
  *   modal stops being exposed to the channel exposed after it — the modal
- *   then on top, or the page body once no modal is open.
+ *   then on top, or the page body once no modal is open. Each write keeps a
+ *   receipt per announcer beside the words, which follows them wherever
+ *   they are moved, so the announcer can take back its own share.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -35,7 +40,57 @@ export type AnnouncePoliteness = 'polite' | 'assertive';
  * Imperative screen-reader announcement function.
  */
 export type AnnounceFn = (message: string, politeness?: AnnouncePoliteness) => void;
-export declare function announceMessage(message: string, politeness: AnnouncePoliteness): void;
+/** Options for `useAnnounce`. */
+export interface UseAnnounceOptions {
+    /**
+     * The instance states one current state of its owner, such as a search's
+     * result count: each message it writes withdraws the instance's previous
+     * message while that one is not yet exposed, whatever their urgencies, and
+     * is spoken in the region of its own urgency; a message already exposed has
+     * been heard and stays. Messages from other instances, and from instances
+     * without `hasReplace`, still join (`spec:AST-086` FR9). Give each state a
+     * component reports its own instance.
+     * @default false
+     */
+    hasReplace?: boolean;
+}
+/**
+ * Takes back one announcer's share of a message while it is not yet exposed,
+ * wherever the route put it. @internal
+ */
+export type WithdrawAnnouncement = () => void;
+/**
+ * One announcer's share of words on their way to being exposed. Whatever
+ * holds the words keeps the receipt beside them; when the words move — a
+ * modal hands them to the channel exposed after it, or releases words it
+ * held through an exit — the mover points the receipt at the new place, so
+ * the announcer's handle follows its words. @internal
+ */
+export interface AnnounceReceipt {
+    withdraw: WithdrawAnnouncement | null;
+}
+/** Words waiting to be exposed, with their announcers' receipts. @internal */
+export interface WaitingWords {
+    readonly text: string;
+    readonly receipts: ReadonlyArray<AnnounceReceipt>;
+}
+/**
+ * The announcer's handle to `receipt`: it takes back the words wherever they
+ * are now, once. @internal
+ */
+export declare function handleOf(receipt: AnnounceReceipt): WithdrawAnnouncement;
+/**
+ * Move `waiting` words elsewhere, one delivery per announcer and in order,
+ * and point each receipt at its delivery, so every announcer can still take
+ * back its own share (`spec:AST-086` FR9, FR14). The deliveries join where
+ * they land, so the words are spoken once. @internal
+ */
+export declare function forwardWaiting(waiting: ReadonlyArray<WaitingWords>, deliver: (text: string) => WithdrawAnnouncement | null): void;
+/**
+ * Write `message` to the shared region for `politeness`, joining the messages
+ * not yet exposed. Returns how to take this write back while it waits.
+ */
+export declare function announceMessage(message: string, politeness: AnnouncePoliteness): WithdrawAnnouncement | null;
 /**
  * Clear any pending announcement from a region without announcing anything new.
  * Used when the triggering context goes away (e.g. a search query is cleared),
@@ -54,6 +109,12 @@ export declare function clearRegion(politeness: AnnouncePoliteness): void;
  * announced, so users browsing the DOM later do not encounter stale status
  * text; announcing again before the clear simply resets the countdown.
  *
+ * An instance created with `hasReplace` states one current state, such as a
+ * search's result count: each message it writes withdraws its previous one
+ * while that one is not yet exposed, so typing faster than a frame says only
+ * the latest count (`spec:AST-086` FR9).
+ *
+ * @param options - `hasReplace` (default false)
  * @example
  * ```
  * function Search() {
@@ -65,7 +126,7 @@ export declare function clearRegion(politeness: AnnouncePoliteness): void;
  * }
  * ```
  */
-export declare function useAnnounce(): AnnounceFn;
+export declare function useAnnounce({ hasReplace, }?: UseAnnounceOptions): AnnounceFn;
 /**
  * What an Astryx modal tells the hooks beneath it: where its dialog element
  * is, and the modal above it, so a caller inside a non-modal sheet nested in
@@ -79,12 +140,17 @@ export interface ModalAnnounceScope {
 export declare const ModalAnnounceContext: import("react").Context<ModalAnnounceScope | null>;
 /** The modal route `modalAnnounce.ts` installs when a provider loads it. */
 export interface ModalRoute {
-    /** `useAnnounce` from inside `scope`: route `message` by where it is. */
-    announce(scope: ModalAnnounceScope, message: string, politeness: AnnouncePoliteness): void;
-    /** Speak inside `dialog` with the exposure, covered and hold rules. */
-    announceInModal(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness): void;
-    /** Withdraw an announcer's share, written or held. */
-    withdrawFromModalPending(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness): void;
+    /**
+     * `useAnnounce` from inside `scope`: route `message` by where it is, and
+     * return how to take this write back while it waits (a `hasReplace`
+     * instance's next message does).
+     */
+    announce(scope: ModalAnnounceScope, message: string, politeness: AnnouncePoliteness): WithdrawAnnouncement | null;
+    /**
+     * Speak inside `dialog` with the exposure, covered and hold rules, and
+     * return how to take this write back while it waits.
+     */
+    announceInModal(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness): WithdrawAnnouncement | null;
 }
 /** Called once by `modalAnnounce.ts` as it loads. @internal */
 export declare function installModalRoute(route: ModalRoute): void;
@@ -103,45 +169,38 @@ export declare function enclosingModalDialog(element: Element | null | undefined
  * exposure, covered and hold rules; without it — a native modal an app
  * renders without Astryx, and no Astryx modal anywhere — the words are
  * written to the dialog while it is open as a modal, else to the shared
- * channel. Internal: used by the busy-announcement hook.
+ * channel. Returns how to take the words back while they wait, wherever they
+ * move, so a busy start overtaken by its own outcome is never heard ahead of
+ * it inside a modal (`spec:AST-086` FR8). Internal: used by the
+ * busy-announcement hook.
  */
-export declare function announceInModal(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): void;
-/**
- * Withdraw one announcer's share of `message` from `dialog` before it is
- * exposed, written to its region or held by the route for the dialog's
- * close, so a busy start overtaken by its own outcome is never heard ahead
- * of it inside a modal (`spec:AST-086` FR8). Internal: used by the
- * busy-announcement hook's settle function.
- */
-export declare function withdrawFromModalPending(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): void;
+export declare function announceInModal(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): WithdrawAnnouncement | null;
 /** What the route asks of the writer in the write frame. @internal */
 export interface ModalWriteGuard {
     isExposed: () => boolean;
-    redirect: (joinedMessage: string) => void;
+    /** Deliver the waiting words elsewhere, forwarding their receipts. */
+    redirect: (waiting: ReadonlyArray<WaitingWords>) => void;
 }
 /** Words written to `target` that assistive technology has not had yet. */
 export declare function unexposedMessages(target: HTMLElement): string[];
+/**
+ * The words written to `target` that assistive technology has not had yet,
+ * with their announcers' receipts, for a hand-off that forwards them.
+ */
+export declare function unexposedWords(target: HTMLElement): WaitingWords[];
 export declare function modalRegion(dialog: HTMLDialogElement, politeness: AnnouncePoliteness): HTMLElement | null;
 /**
  * Write `message` to the modal `dialog`'s own live region for `politeness`,
  * joining it to messages written there that are not yet exposed and saying
- * an identical repeat once; a holder count per text lets one announcer take
- * its share back (`withdrawFromModalPending`). The region-writing core,
- * shared by the full modal route and by the busy-announcement hook's fallback
- * for a native modal an app renders without Astryx. `guard`, supplied by the
- * route, re-checks exposure in the write frame and redirects the joined words
- * when the dialog stopped being exposed meanwhile.
- */
-export declare function writeModalRegion(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness, guard?: ModalWriteGuard): void;
-/**
- * Withdraw one announcer's share of `message` from `dialog`'s region before
- * it is exposed — written but not yet spoken — so a busy start overtaken by
- * its own outcome is never heard ahead of it (`spec:AST-086` FR8). The
- * message stays while another announcer holds it. The region half of
- * `withdrawFromModalPending`; the route also drops words it holds for the
- * dialog's close.
- */
-export declare function withdrawFromModalRegion(dialog: HTMLDialogElement, message: string, politeness?: AnnouncePoliteness): void;
+ * an identical repeat once. The region-writing core, shared by the full
+ * modal route and by the busy-announcement hook's fallback for a native
+ * modal an app renders without Astryx. `guard`, supplied by the route,
+ * re-checks exposure in the write frame and redirects the waiting words when
+ * the dialog stopped being exposed meanwhile. Returns this announcer's
+ * handle: it takes back only its own share, only while the words wait, and
+ * follows them when the route moves them.
+ */
+export declare function writeModalRegion(dialog: HTMLDialogElement, message: string, politeness: AnnouncePoliteness, guard?: ModalWriteGuard): WithdrawAnnouncement;
 /**
  * Withdraw whatever the dialog's region for `politeness` holds or is about to
  * hold, as an empty message does on the shared channel. A dialog that never

package/dist/hooks/useAnnounce.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useAnnounce.d.ts","sourceRoot":"","sources":["../../src/hooks/useAnnounce.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useAnnounce.js

@@ -7,10 +7,11 @@
  * @input Uses React context and useCallback; DOM APIs and cancellable
  *   animation frames for a singleton live-region pair on the page body and
  *   one persistent polite/assertive pair inside each open Astryx modal
- * @output Exports useAnnounce hook and AnnouncePoliteness type; the internal
- *   modal context, the in-dialog region writer the busy-announcement hook
- *   uses, and the hook the modal route (`modalAnnounce.ts`, loaded only with
- *   an Astryx modal) installs itself through
+ * @output Exports useAnnounce hook (with its `hasReplace` option),
+ *   AnnouncePoliteness and UseAnnounceOptions types; the internal modal
+ *   context, the in-dialog region writer the busy-announcement hook uses, and
+ *   the hook the modal route (`modalAnnounce.ts`, loaded only with an Astryx
+ *   modal) installs itself through
  * @position Core a11y hook; provides imperative screen-reader announcements.
  *   A message follows the nearest open native modal enclosing its caller
  *   (`spec:AST-086` FR14): inside an Astryx modal it is written to that
@@ -18,15 +19,19 @@
  *   while a native modal is open; otherwise to the shared page-body pair.
  *   Containers are created empty (FR3), carry the two urgencies (FR5), join
  *   messages written before the previous is exposed and say an identical
- *   same-frame repeat once (FR9), and clear shortly after each announcement;
+ *   same-frame repeat once (FR9), except that a `hasReplace` instance's
+ *   message withdraws that instance's previous one not yet exposed, and clear
+ *   shortly after each announcement;
  *   the route in `modalAnnounce.ts` hands a message still unexposed when its
  *   modal stops being exposed to the channel exposed after it — the modal
- *   then on top, or the page body once no modal is open.
+ *   then on top, or the page body once no modal is open. Each write keeps a
+ *   receipt per announcer beside the words, which follows them wherever
+ *   they are moved, so the announcer can take back its own share.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
-import { createContext, use, useCallback } from 'react';
+import { createContext, use, useCallback, useRef } from 'react';
 
 /**
  * Announcement urgency:
@@ -40,6 +45,51 @@ import { createContext, use, useCallback } from 'react';
  * Imperative screen-reader announcement function.
  */
 
+/** Options for `useAnnounce`. */
+
+/**
+ * Takes back one announcer's share of a message while it is not yet exposed,
+ * wherever the route put it. @internal
+ */
+
+/**
+ * One announcer's share of words on their way to being exposed. Whatever
+ * holds the words keeps the receipt beside them; when the words move — a
+ * modal hands them to the channel exposed after it, or releases words it
+ * held through an exit — the mover points the receipt at the new place, so
+ * the announcer's handle follows its words. @internal
+ */
+
+/** Words waiting to be exposed, with their announcers' receipts. @internal */
+
+/**
+ * The announcer's handle to `receipt`: it takes back the words wherever they
+ * are now, once. @internal
+ */
+export function handleOf(receipt) {
+  return () => {
+    const withdraw = receipt.withdraw;
+    receipt.withdraw = null;
+    withdraw?.();
+  };
+}
+
+/**
+ * Move `waiting` words elsewhere, one delivery per announcer and in order,
+ * and point each receipt at its delivery, so every announcer can still take
+ * back its own share (`spec:AST-086` FR9, FR14). The deliveries join where
+ * they land, so the words are spoken once. @internal
+ */
+export function forwardWaiting(waiting, deliver) {
+  for (const {
+    text,
+    receipts
+  } of waiting) {
+    for (const receipt of receipts) {
+      receipt.withdraw = deliver(text);
+    }
+  }
+}
 const CONTAINER_ATTR = 'data-astryx-live-region';
 
 // Visually-hidden clip block (matches the VisuallyHidden primitive). Applied
@@ -134,17 +184,22 @@ function getRegions() {
   };
   return regions;
 }
+
+/**
+ * Write `message` to the shared region for `politeness`, joining the messages
+ * not yet exposed. Returns how to take this write back while it waits.
+ */
 export function announceMessage(message, politeness) {
   const r = getRegions();
   if (!r) {
-    return;
+    return null;
   }
   const target = politeness === 'assertive' ? r.assertive : r.polite;
   const repeat = pendingMessages[politeness].find(pending => pending.text === message);
   if (repeat != null) {
     repeat.holders += 1;
     lastJoined = repeat;
-    return;
+    return () => withdrawPendingAnnouncement(repeat, politeness);
   }
   const pending = {
     text: message,
@@ -168,6 +223,7 @@ export function announceMessage(message, politeness) {
   // indefinitely. Scheduled per announce, so a newer announcement always
   // resets the countdown (the delay comfortably outlasts the rAF re-set).
   scheduleClear(politeness, target);
+  return () => withdrawPendingAnnouncement(pending, politeness);
 }
 
 /**
@@ -197,6 +253,12 @@ export function clearRegion(politeness) {
  * announced, so users browsing the DOM later do not encounter stale status
  * text; announcing again before the clear simply resets the countdown.
  *
+ * An instance created with `hasReplace` states one current state, such as a
+ * search's result count: each message it writes withdraws its previous one
+ * while that one is not yet exposed, so typing faster than a frame says only
+ * the latest count (`spec:AST-086` FR9).
+ *
+ * @param options - `hasReplace` (default false)
  * @example
  * ```
  * function Search() {
@@ -208,25 +270,38 @@ export function clearRegion(politeness) {
  * }
  * ```
  */
-export function useAnnounce() {
+export function useAnnounce({
+  hasReplace = false
+} = {}) {
   const modal = use(ModalAnnounceContext);
+  // A `hasReplace` instance's latest write, which its next message takes back
+  // if assistive technology has not had it yet.
+  const withdrawPreviousRef = useRef(null);
   return useCallback((message, politeness = 'polite') => {
+    if (hasReplace) {
+      const withdrawPrevious = withdrawPreviousRef.current;
+      withdrawPreviousRef.current = null;
+      withdrawPrevious?.();
+    }
+    let written;
     // Inside an Astryx modal's provider: the modal route decides, per call,
     // where the caller is heard — `modal` is non-null only where a provider
     // rendered, and rendering one loads the route.
     if (modal != null && modalRoute != null) {
-      modalRoute.announce(modal, message, politeness);
-      return;
-    }
-    if (!message) {
+      written = modalRoute.announce(modal, message, politeness);
+    } else if (!message) {
       // An empty message clears any lingering status from the region,
       // including messages joined but not yet exposed — useful when the
       // triggering context ends.
       clearRegion(politeness);
-      return;
+      written = null;
+    } else {
+      written = announceMessage(message, politeness);
+    }
+    if (hasReplace) {
+      withdrawPreviousRef.current = written;
     }
-    announceMessage(message, politeness);
-  }, [modal]);
+  }, [hasReplace, modal]);
 }
 
 // =============================================================================
@@ -292,33 +367,19 @@ export function enclosingModalDialog(element) {
  * exposure, covered and hold rules; without it — a native modal an app
  * renders without Astryx, and no Astryx modal anywhere — the words are
  * written to the dialog while it is open as a modal, else to the shared
- * channel. Internal: used by the busy-announcement hook.
+ * channel. Returns how to take the words back while they wait, wherever they
+ * move, so a busy start overtaken by its own outcome is never heard ahead of
+ * it inside a modal (`spec:AST-086` FR8). Internal: used by the
+ * busy-announcement hook.
  */
 export function announceInModal(dialog, message, politeness = 'polite') {
   if (modalRoute != null) {
-    modalRoute.announceInModal(dialog, message, politeness);
-    return;
+    return modalRoute.announceInModal(dialog, message, politeness);
   }
   if (isOpenModal(dialog)) {
-    writeModalRegion(dialog, message, politeness);
-  } else {
-    announceMessage(message, politeness);
-  }
-}
-
-/**
- * Withdraw one announcer's share of `message` from `dialog` before it is
- * exposed, written to its region or held by the route for the dialog's
- * close, so a busy start overtaken by its own outcome is never heard ahead
- * of it inside a modal (`spec:AST-086` FR8). Internal: used by the
- * busy-announcement hook's settle function.
- */
-export function withdrawFromModalPending(dialog, message, politeness = 'polite') {
-  if (modalRoute != null) {
-    modalRoute.withdrawFromModalPending(dialog, message, politeness);
-    return;
+    return writeModalRegion(dialog, message, politeness);
   }
-  withdrawFromModalRegion(dialog, message, politeness);
+  return announceMessage(message, politeness);
 }
 
 /** What the route asks of the writer in the write frame. @internal */
@@ -344,11 +405,25 @@ function cancelPending(pending) {
 
 /** Words written to `target` that assistive technology has not had yet. */
 export function unexposedMessages(target) {
+  return unexposedWords(target).map(words => words.text);
+}
+function waitingIn(pending) {
+  return pending.messages.map(text => ({
+    text,
+    receipts: pending.receipts.get(text) ?? []
+  }));
+}
+
+/**
+ * The words written to `target` that assistive technology has not had yet,
+ * with their announcers' receipts, for a hand-off that forwards them.
+ */
+export function unexposedWords(target) {
   const pending = pendingByRegion.get(target);
   if (pending == null) {
     return [];
   }
-  return pending.frame != null || pending.settleFrame != null ? pending.messages : [];
+  return pending.frame != null || pending.settleFrame != null ? waitingIn(pending) : [];
 }
 export function modalRegion(dialog, politeness) {
   return dialog.querySelector(`:scope > [${MODAL_REGION_ATTR}="${politeness}"]`);
@@ -376,20 +451,24 @@ function ensureModalRegion(dialog, politeness) {
 /**
  * Write `message` to the modal `dialog`'s own live region for `politeness`,
  * joining it to messages written there that are not yet exposed and saying
- * an identical repeat once; a holder count per text lets one announcer take
- * its share back (`withdrawFromModalPending`). The region-writing core,
- * shared by the full modal route and by the busy-announcement hook's fallback
- * for a native modal an app renders without Astryx. `guard`, supplied by the
- * route, re-checks exposure in the write frame and redirects the joined words
- * when the dialog stopped being exposed meanwhile.
+ * an identical repeat once. The region-writing core, shared by the full
+ * modal route and by the busy-announcement hook's fallback for a native
+ * modal an app renders without Astryx. `guard`, supplied by the route,
+ * re-checks exposure in the write frame and redirects the waiting words when
+ * the dialog stopped being exposed meanwhile. Returns this announcer's
+ * handle: it takes back only its own share, only while the words wait, and
+ * follows them when the route moves them.
  */
 export function writeModalRegion(dialog, message, politeness, guard) {
   const target = ensureModalRegion(dialog, politeness);
   const unexposed = unexposedMessages(target);
   const messages = unexposed.includes(message) ? unexposed : [...unexposed, message];
   const previous = pendingByRegion.get(target);
-  const holders = new Map(unexposed.length > 0 && previous != null ? previous.holders : []);
-  holders.set(message, (holders.get(message) ?? 0) + 1);
+  const receipts = unexposed.length > 0 && previous != null ? previous.receipts : new Map();
+  const receipt = {
+    withdraw: null
+  };
+  receipts.set(message, [...(receipts.get(message) ?? []), receipt]);
   if (previous != null) {
     cancelPending(previous);
   }
@@ -398,7 +477,7 @@ export function writeModalRegion(dialog, message, politeness, guard) {
   target.textContent = '';
   const pending = {
     messages,
-    holders,
+    receipts,
     frame: null,
     settleFrame: null,
     timer: null
@@ -407,9 +486,9 @@ export function writeModalRegion(dialog, message, politeness, guard) {
     pending.frame = null;
     if (guard != null && !guard.isExposed()) {
       // Stopped being exposed between the call and this frame: the words go
-      // where they will be heard.
+      // where they will be heard, their receipts with them.
       pendingByRegion.delete(target);
-      guard.redirect(pending.messages.join(' '));
+      guard.redirect(waitingIn(pending));
       return;
     }
     target.textContent = pending.messages.join(' ');
@@ -422,35 +501,42 @@ export function writeModalRegion(dialog, message, politeness, guard) {
     }, CLEAR_DELAY_MS);
   });
   pendingByRegion.set(target, pending);
+  receipt.withdraw = () => withdrawFromRegion(target, message, receipt);
+  return handleOf(receipt);
 }
 
 /**
- * Withdraw one announcer's share of `message` from `dialog`'s region before
- * it is exposed — written but not yet spoken — so a busy start overtaken by
- * its own outcome is never heard ahead of it (`spec:AST-086` FR8). The
- * message stays while another announcer holds it. The region half of
- * `withdrawFromModalPending`; the route also drops words it holds for the
- * dialog's close.
+ * Withdraw one announcer's share of `message` from `target` while it is not
+ * yet exposed — written but not yet spoken — so a busy start overtaken by its
+ * own outcome is never heard ahead of it (`spec:AST-086` FR8), and a
+ * `hasReplace` instance's next message replaces its previous one (FR9,
+ * FR14). The message stays while another announcer holds it; a receipt not
+ * among the waiting words (they were exposed, cleared, or moved) takes back
+ * nothing.
  */
-export function withdrawFromModalRegion(dialog, message, politeness = 'polite') {
-  const region = modalRegion(dialog, politeness);
-  const pending = region == null ? undefined : pendingByRegion.get(region);
-  if (region != null && pending != null && (pending.frame != null || pending.settleFrame != null)) {
-    const count = pending.holders.get(message) ?? 0;
-    if (count > 1) {
-      pending.holders.set(message, count - 1);
-    } else if (count === 1) {
-      pending.holders.delete(message);
-      pending.messages = pending.messages.filter(text => text !== message);
-      if (pending.messages.length === 0) {
-        cancelPending(pending);
-        pendingByRegion.delete(region);
-        region.textContent = '';
-      } else if (pending.frame == null) {
-        // Already written this frame, not yet taken: show the rest.
-        region.textContent = pending.messages.join(' ');
-      }
-    }
+function withdrawFromRegion(target, message, receipt) {
+  const pending = pendingByRegion.get(target);
+  if (pending == null || pending.frame == null && pending.settleFrame == null) {
+    return;
+  }
+  const receipts = pending.receipts.get(message);
+  const at = receipts?.indexOf(receipt) ?? -1;
+  if (receipts == null || at < 0) {
+    return;
+  }
+  receipts.splice(at, 1);
+  if (receipts.length > 0) {
+    return;
+  }
+  pending.receipts.delete(message);
+  pending.messages = pending.messages.filter(text => text !== message);
+  if (pending.messages.length === 0) {
+    cancelPending(pending);
+    pendingByRegion.delete(target);
+    target.textContent = '';
+  } else if (pending.frame == null) {
+    // Already written this frame, not yet taken: show the rest.
+    target.textContent = pending.messages.join(' ');
   }
 }