ngwr 11.1.0 → 12.0.0

package/types/ngwr-context-menu.d.ts

@@ -66,7 +66,33 @@ declare class WrContextMenu {
      */
     protected readonly openMenuId: _angular_core.WritableSignal<string | null>;
     private overlayRef;
-    private closingTimer;
+    /**
+     * The open menu's subscription to CDK's keyboard dispatcher, held so that
+     * `closeOverlay()` can drop it — see the unsubscribe there for why the pane's
+     * own disposal is 220 ms too late.
+     */
+    private rootKeys;
+    /**
+     * Where the keyboard was at the moment this menu took it, so a close can put
+     * it back there. Null when it was nowhere in particular (`<body>`) or already
+     * inside a menu pane, neither of which is a place to return to.
+     */
+    private restoreFocusTo;
+    /**
+     * Panes waiting out their exit animation, keyed by the timer that disposes
+     * them.
+     *
+     * A SET, because one handle cannot hold two closings. It used to be a single
+     * `closingTimer`, and the second close inside the 220ms window cleared the
+     * first one's timer instead of its own — so the previous pane's `dispose()`
+     * never ran. `onContextMenu` closes and immediately re-opens, so right-clicking
+     * one target faster than the animation orphaned a pane per click: an
+     * `opacity: 0` box with `pointer-events: auto` eating clicks, a never-destroyed
+     * embedded view, a capture-phase document scroll listener still moving it, and
+     * an undetached ref still registered with CDK's keyboard dispatcher — which
+     * swallowed Escape for the whole page.
+     */
+    private readonly closingPanes;
     private leaveTimer;
     private pressTimer;
     private pressX;
@@ -135,6 +161,24 @@ declare class WrContextMenu {
     close(): void;
     private openOverlay;
     private closeOverlay;
+    /**
+     * Put the keyboard back where it came from.
+     *
+     * The element that had it when the menu opened comes first: a context menu
+     * hangs on a REGION — a card, a table row — and Shift+F10 / the Menu key fires
+     * `contextmenu` at whatever control inside it the user was actually on, which
+     * is their place in the page.
+     *
+     * The trigger is the fallback, and it needs help to be one. `[wrContextMenu]`
+     * adds no `tabindex` and every shape the docs ship is a plain `<div>`, so
+     * `focus()` on it does nothing at all — the handback silently missed, leaving
+     * the caret in the disposing pane and then on `<body>`, which is the outcome
+     * the call is there to prevent. Lending it `tabindex="-1"` for the call and
+     * taking that back on blur keeps the consumer's DOM as they wrote it; a
+     * permanent `tabindex="0"` would make every right-clickable region a tab stop,
+     * which is their decision and not the library's.
+     */
+    private handBackFocus;
     private cancelLeaveTimer;
     private scheduleLeave;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WrContextMenu, never>;
@@ -177,9 +221,17 @@ declare class WrContextMenuItem {
     private readonly scrollStrategies;
     private readonly destroyRef;
     private submenuRef;
+    private submenuKeys;
     private openTimer;
     private closeTimer;
     protected submenuOpen: boolean;
+    /**
+     * Whether the pending open was asked for by the keyboard (→ / Enter / Space)
+     * rather than by hover — only then does the submenu take focus, the same rule
+     * `wr-dropdown` applies to its own open. Sweeping the cursor across a row must
+     * show its submenu without yanking the caret out of it.
+     */
+    private openedByKeyboard;
     /**
      * Id of the submenu's menu element while it is open, published on the item as
      * `aria-controls` — the same contract the root trigger keeps (see
@@ -243,6 +295,24 @@ declare class WrContextMenuItem {
     private cancelOpen;
     private cancelClose;
     private openSubmenu;
+    /**
+     * @internal Keys routed here while this submenu is the topmost overlay: the
+     * arrows walk the rows of the pane the caret is in, and Escape or the arrow
+     * pointing BACK the way the menu cascades steps out one level, returning the
+     * cursor to the row that owns the pane when the cursor was inside it.
+     *
+     * Escape closes this level only, not the whole chain — the APG's rule for a
+     * submenu. It reaches this handler rather than the root's because the
+     * dispatcher stops at the topmost overlay that listens, which is now this one.
+     *
+     * Which is also why the arrows are aimed at the pane holding the caret rather
+     * than at this one. The dispatcher routes by stacking order, not by focus, and
+     * a HOVER-opened submenu is topmost while focus is deliberately still on the
+     * root row the pointer swept off (see `openedByKeyboard`) — so ArrowDown used
+     * to jump into this pane's first row instead of moving down the menu the user
+     * is in. Same reason `wr-dropdown`'s menu handler checks ownership.
+     */
+    private onSubmenuKeydown;
     /** Bound handlers (= preserves identity for removeEventListener). */
     private readonly onSubmenuEnter;
     private readonly onSubmenuLeave;

package/types/ngwr-counter.d.ts

@@ -163,6 +163,7 @@ declare class WrCountUp {
     private readonly host;
     private readonly locale;
     private readonly isBrowser;
+    private readonly platform;
     private readonly destroyRef;
     private rafId;
     private delayTimer;

package/types/{ngwr-date-adapter-fns.d.ts → ngwr-date-adapters-fns.d.ts}

@@ -1,12 +1,34 @@
-import { WrDateAdapter, WrDateFormat } from 'ngwr/date-adapter';
+import { WrDateAdapter, WrDateFormat } from 'ngwr/date';
 import * as i0 from '@angular/core';
 import { EnvironmentProviders } from '@angular/core';
 
 /**
  * {@link WrDateAdapter} backed by `date-fns`. Same `Date` value type as the
- * native adapter, but defers all math, formatting, and parsing to date-fns
- * — pick this when you want more robust locale-aware patterns (`P`, `PP`,
- * `PPP`, `p`) without writing them by hand.
+ * native adapter, but defers all math, formatting, and parsing to date-fns —
+ * pick this when you want its long patterns (`P`, `PP`, `PPP`, `p`) without
+ * writing them by hand.
+ *
+ * **{@link WR_DATE_LOCALE} does not reach `format` or `parse`, and that is not
+ * an oversight.** date-fns resolves those patterns against a date-fns `Locale`
+ * OBJECT rather than a BCP 47 tag, and the objects are separate modules —
+ * mapping a tag onto one would mean importing all of them, which defeats the
+ * tree-shaking that is the reason this is an opt-in entry point. So the named
+ * formats render AND read in en-US whatever the tag says, while
+ * `getFirstDayOfWeek`, `getDayOfWeekNames` and `getMonthNames` go through `Intl`
+ * and do honour it: a calendar heads its columns `пн вт ср` beside a trigger
+ * reading `08/11/2025`. Reading is the sharper edge — `11/08/2025` typed by a
+ * user in a dd/MM locale parses as 8 November, valid and wrong.
+ *
+ * The lever is date-fns's own module default, and the adapter passing no locale
+ * is precisely what keeps it working. Set it once at bootstrap, or take
+ * `provideWrLuxonAdapter()`, which forwards the tag itself:
+ *
+ * ```ts
+ * import { setDefaultOptions } from 'date-fns';
+ * import { ru } from 'date-fns/locale';
+ *
+ * setDefaultOptions({ locale: ru });
+ * ```
  *
  * @example
  * ```ts
@@ -56,8 +78,13 @@ declare class WrDateFnsAdapter extends WrDateAdapter<Date> {
 
 /**
  * Register the {@link WrDateFnsAdapter} so date-pickers / calendars in this
- * app use `date-fns` for all math and formatting. Pass `locale` to override
- * the BCP 47 tag.
+ * app use `date-fns` for all math and formatting.
+ *
+ * `locale` sets {@link WR_DATE_LOCALE}, which this adapter reads for the first
+ * day of the week and nothing else — its `format` and `parse` do not pass a
+ * locale to date-fns. For localized month names and patterns, set date-fns's own
+ * module default with `setDefaultOptions`, or use the luxon adapter, which does
+ * thread the tag through everything.
  *
  * @example
  * ```ts

package/types/{ngwr-date-adapter-luxon.d.ts → ngwr-date-adapters-luxon.d.ts}

@@ -1,5 +1,5 @@
 import { DateTime } from 'luxon';
-import { WrDateAdapter, WrDateFormat } from 'ngwr/date-adapter';
+import { WrDateAdapter, WrDateFormat } from 'ngwr/date';
 import * as i0 from '@angular/core';
 import { EnvironmentProviders } from '@angular/core';
 

package/types/ngwr-date-picker-testing.d.ts

@@ -1,4 +1,6 @@
-import { BaseHarnessFilters, ComponentHarness, HarnessPredicate, TestElement, HarnessLoader } from '@angular/cdk/testing';
+import { WrCalendarDayHarness } from 'ngwr/calendar/testing';
+export { WrCalendarDayHarness as WrDatePickerDayHarness } from 'ngwr/calendar/testing';
+import { BaseHarnessFilters, ComponentHarness, TestElement, HarnessLoader, HarnessPredicate } from '@angular/cdk/testing';
 
 /**
  * @license
@@ -77,68 +79,6 @@ interface WrDatePickerTimeFields {
     readonly seconds?: number;
 }
 
-/**
- * @license
- *
- * Use of this source code is governed by an MIT-style license that can be
- * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
- */
-
-/**
- * Test harness for one day cell of the calendar inside a date-picker popup.
- *
- * Reached through `WrDatePickerHarness.getDay()` / `getDays()` (or the range
- * picker's), which scope it to ONE picker's panel — the cells are in the overlay
- * container, so a bare query would answer with whichever picker opened first.
- *
- * State is read the way a screen reader reads it (`role`, `aria-selected`,
- * `aria-disabled`) with the `.wr-calendar__day--*` modifiers filling in what
- * ARIA has no word for: today, the spill days of the neighbouring months, and
- * the interior of a picked range.
- *
- * @see https://ngwr.dev/guides/testing
- */
-declare class WrDatePickerDayHarness extends ComponentHarness {
-    static hostSelector: string;
-    /** Build a predicate that narrows the query. */
-    static with(options?: WrDatePickerDayHarnessFilters): HarnessPredicate<WrDatePickerDayHarness>;
-    /** The day number as rendered. */
-    getText(): Promise<string>;
-    /** The day number as a number, for mapping a list of cells to dates. */
-    getDayOfMonth(): Promise<number>;
-    /** `'gridcell'` — the cell is a button, and the grid semantics are what a spec should assert. */
-    getRole(): Promise<string | null>;
-    /** Whether this day is (one end of) the current selection. */
-    isSelected(): Promise<boolean>;
-    /**
-     * Whether the day refuses selection — `min` / `max` or `dateFilter` ruled it
-     * out, or the whole calendar is disabled.
-     */
-    isDisabled(): Promise<boolean>;
-    /** Whether the cell is today's date. */
-    isToday(): Promise<boolean>;
-    /**
-     * Whether the cell belongs to a neighbouring month. The grid is always 6x7, so
-     * every month is padded with days that are selectable but not "in" the month —
-     * which is why {@link WrDatePickerHarness.getDay} skips them.
-     */
-    isOutOfMonth(): Promise<boolean>;
-    /** Whether the day lies strictly between the two ends of a picked range. */
-    isInRange(): Promise<boolean>;
-    /**
-     * Whether this is the roving cell — the grid's single tab stop, and where the
-     * arrow keys move from.
-     *
-     * At most ONE cell answers `true`, and it is not always one: the calendar's
-     * roving date does not follow `next()` / `previous()`, so a grid navigated away
-     * from that month has no active cell (and, deliberately or not, no tab stop)
-     * until a cell is clicked or the arrows move it.
-     */
-    isActive(): Promise<boolean>;
-    /** Click the cell. A disabled cell swallows the click — assert, do not assume. */
-    click(): Promise<void>;
-}
-
 /**
  * @license
  *
@@ -161,18 +101,23 @@ type Unit = (typeof UNITS)[number];
  * independently instead of by CSS nth-of-type gymnastics.
  *
  * Units are addressed by position, not by the boxes' `aria-label`: every string
- * in this panel is still hard-coded English (the box labels, the steppers'
- * "Increment hours", the AM/PM text), so keying on them would make this harness
- * the thing that breaks when they are moved into the i18n catalog. Column order
- * is the layout contract.
+ * in this panel now resolves through the i18n catalog (`datePicker.hours`,
+ * `datePicker.incrementHours`, `datePicker.am` …), so keying on them would make
+ * this harness answer in whatever locale the app under test is configured for.
+ * Column order is the layout contract.
  *
  * @internal
  */
 declare class WrTimePanelHarness extends ComponentHarness {
     static hostSelector: string;
-    /** The stepper's value as `HH:MM`, plus `:SS` and ` AM`/` PM` when those columns exist. */
+    /** The stepper's value as `HH:MM`, plus `:SS` and a space-joined {@link getMeridiem} when those columns exist. */
     getTimeText(): Promise<string>;
-    /** `'AM'` / `'PM'`, or `null` when the stepper is in 24-hour mode. */
+    /**
+     * The meridiem column's rendered text, or `null` when the stepper is in
+     * 24-hour mode. `'AM'` / `'PM'` on the built-in fallbacks — it reads whatever
+     * `datePicker.am` / `datePicker.pm` resolve to, so a configured catalog
+     * changes the answer.
+     */
     getMeridiem(): Promise<string | null>;
     /**
      * Type into the boxes named by `fields`, leaving the rest alone.
@@ -277,12 +222,12 @@ declare abstract class WrDatePickerHarnessBase extends ComponentHarness {
      * them, since the grid is always six weeks and pads into the neighbouring
      * months.
      */
-    getDays(filters?: WrDatePickerDayHarnessFilters): Promise<WrDatePickerDayHarness[]>;
+    getDays(filters?: WrDatePickerDayHarnessFilters): Promise<WrCalendarDayHarness[]>;
     /**
      * One day of the month on show. The padding days of the neighbouring months are
      * skipped, so `getDay(1)` is the 1st of THIS month and never the 1st of the next.
      */
-    getDay(dayOfMonth: number): Promise<WrDatePickerDayHarness>;
+    getDay(dayOfMonth: number): Promise<WrCalendarDayHarness>;
     /** Click a day of the month on show. */
     selectDay(dayOfMonth: number): Promise<void>;
     /** The trigger button. Both components render it with the same class. */
@@ -514,5 +459,5 @@ declare class WrDateRangePickerHarness extends WrDatePickerHarnessBase {
     private timePanel;
 }
 
-export { WrDatePickerDayHarness, WrDatePickerHarness, WrDateRangePickerHarness };
+export { WrDatePickerHarness, WrDateRangePickerHarness };
 export type { WrDatePickerDayHarnessFilters, WrDatePickerHarnessFilters, WrDatePickerTimeFields, WrDateRangePickerHarnessFilters };

package/types/ngwr-date-picker.d.ts

@@ -1,7 +1,7 @@
 import * as _angular_core from '@angular/core';
 import { ElementRef } from '@angular/core';
 import { FormValueControl } from '@angular/forms/signals';
-import { WrDateFormat } from 'ngwr/date-adapter';
+import { WrDateFormat } from 'ngwr/date';
 
 /**
  * Unified date / time / date-time picker. Same `<input>` + popover skeleton
@@ -143,6 +143,10 @@ declare class WrDatePicker implements FormValueControl<Date | null> {
      * skip the echo of our own edits (so a live keystroke's raw text is never
      * reformatted mid-type). */
     private lastValue;
+    /** The format the sync effect last rendered with. Paired with `lastValue`
+     * because the echo guard has to answer "is the display still current", and a
+     * `[format]` / `[mode]` change makes it stale with the value untouched. */
+    private lastFormat;
     constructor();
     protected onInput(event: Event): void;
     protected onBlur(): void;
@@ -320,9 +324,9 @@ declare class WrDateRangePicker implements FormValueControl<WrDateRange | null>
     /** Resolved format — falls back to a mode-appropriate default. */
     protected readonly resolvedFormat: _angular_core.Signal<string>;
     protected readonly isDateTime: _angular_core.Signal<boolean>;
-    protected readonly triggerLabel: string;
-    protected readonly startLabel: string;
-    protected readonly endLabel: string;
+    protected readonly triggerLabel: _angular_core.Signal<string>;
+    protected readonly startLabel: _angular_core.Signal<string>;
+    protected readonly endLabel: _angular_core.Signal<string>;
     private readonly panelLabelRange;
     private readonly panelLabelRangeDateTime;
     /**

package/types/{ngwr-date-adapter.d.ts → ngwr-date.d.ts}

@@ -145,6 +145,18 @@ declare class WrNativeDateAdapter extends WrDateAdapter<Date> {
     format(date: Date, formatKeyOrString: WrDateFormat | (string & {})): string;
     parse(value: string, formatKeyOrString: WrDateFormat | (string & {})): Date | null;
     getFirstDayOfWeek(): number;
+    /**
+     * One `Intl.DateTimeFormat` per named format, built once.
+     *
+     * Constructing one is the expensive part of `format()`, and this adapter is
+     * called per CELL: `wr-event-calendar` builds an `aria-label` for every time
+     * slot on every day, so a week view asked for hundreds of identical
+     * formatters. `locale` is injected once and never changes for the life of the
+     * adapter, so the cache needs no invalidation — that is the whole reason it
+     * can be this simple.
+     */
+    private readonly formatters;
+    private intl;
     getDayOfWeekNames(style: 'narrow' | 'short' | 'long'): readonly string[];
     getMonthNames(style: 'narrow' | 'short' | 'long'): readonly string[];
     private formatWithTokens;
@@ -185,12 +197,19 @@ declare function provideWrDateAdapter(options?: WrDateAdapterOptions): Environme
  */
 
 /**
- * BCP 47 locale tag used by {@link WrDateAdapter} implementations for
- * formatting, parsing, and locale-derived defaults (first day of week,
- * month / day names). Defaults to `navigator.language` in the browser and
- * `'en-US'` on the server.
+ * BCP 47 locale tag the {@link WrDateAdapter} implementations read. Defaults to
+ * `navigator.language` in the browser and `'en-US'` on the server; override via
+ * {@link provideWrDateAdapter}'s `locale` option.
  *
- * Override via {@link provideWrDateAdapter}'s `locale` option.
+ * **How far it reaches depends on the adapter, and the difference matters.**
+ * The luxon adapter threads it through everything — every `DateTime` is
+ * constructed with it, and `format` / `parse` call `setLocale`. The date-fns
+ * adapter reads it only for locale-DERIVED defaults (first day of week); its
+ * `format` and `parse` pass no locale to date-fns, so they stay on that
+ * library's module default. Setting this token and expecting French month names
+ * out of `WrDateFnsAdapter` gets English ones, and the parse side of that
+ * mismatch is silent rather than loud — see the adapter's own class docs for the
+ * lever (`setDefaultOptions`).
  */
 declare const WR_DATE_LOCALE: InjectionToken<string>;
 

package/types/ngwr-decrypt-text-testing.d.ts

@@ -0,0 +1,222 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/** Narrows which `<wr-decrypt-text>` a harness query matches. */
+interface WrDecryptTextHarnessFilters extends BaseHarnessFilters {
+    /**
+     * Match the string the component ANNOUNCES — the readable copy, never the scramble.
+     * A string is an exact match, a RegExp is tested.
+     *
+     * This is the only stable thing to address one of these by: the visible layer is a
+     * fresh random draw on every tick, so a filter written against it would match a
+     * different element each time it ran, or none at all.
+     */
+    readonly text?: string | RegExp;
+    /**
+     * Match only settled (`true`) or only scrambled (`false`) instances — the way to pick
+     * out the one that has not been revealed yet on a page holding several.
+     *
+     * Read from the encrypted characters rather than from the glyphs, so it needs no
+     * `Math.random` stub. An instance that rendered no characters at all matches NEITHER
+     * value: "nothing is encrypted" is true of nothing, and a query is the last place that
+     * vacuity should quietly hand back a match.
+     */
+    readonly revealed?: boolean;
+}
+
+/**
+ * @license
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://github.com/thekhegay/ngwr/blob/main/LICENSE
+ */
+
+/**
+ * Test harness for `<wr-decrypt-text>`.
+ *
+ * **Two layers, two questions, and they are meant to disagree.** The component renders
+ * the real string once in a visually-hidden span and the scramble in a parallel
+ * `aria-hidden` layer, so {@link getAccessibleText} is what a screen reader hears and
+ * {@link getRenderedText} is what a sighted reader sees. Mid-reveal the second is
+ * literal gibberish while the first must be untouched — that is the contract, and it is
+ * the half nobody looks at. A spec asserting only the visible glyphs would pass on a
+ * component that announced `XQ#PZ`.
+ *
+ * **Prefer the class over the glyphs.** {@link getRevealedIndices},
+ * {@link getEncryptedCount} and {@link isFullyRevealed} read
+ * `.wr-decrypt-text__char--encrypted`, which is deterministic with no stubbing at all —
+ * they are what tell `revealDirection` `'start'` from `'end'` from `'center'`, one index
+ * per tick. {@link getRenderedText} reads the glyphs themselves, which are a fresh
+ * `Math.random()` draw per tick, so stub it (`vi.spyOn(Math, 'random')
+ * .mockReturnValue(0)`) before asserting a string.
+ *
+ * **The clock is the spec's, not the harness's.** The reveal is a `setInterval` this
+ * class does not own, so there is no `advance(ms)` and no `waitUntilRevealed()`: one
+ * would flake on a loaded machine and the other would silently require fake timers to
+ * have been installed. Fake `setInterval` / `clearInterval` and nothing else — faking
+ * the microtask queue freezes the stabilization every `await harness.*()` runs through —
+ * then advance the clock yourself between reads.
+ *
+ * **There is no keyboard path, and this harness does not pretend there is one.**
+ * {@link hover}, {@link mouseAway} and {@link click} are the component's only triggers;
+ * with `animateOn="click"` the host takes a click handler while carrying no role, no
+ * `tabindex` and no keydown handler, so a `focus()` / `sendKeys(Enter)` affordance here
+ * would make a spec pass while a keyboard or switch user could not reveal the text at
+ * all. There is no `enterViewport()` either: `'view'` and `'inViewHover'` hang off an
+ * `IntersectionObserver` jsdom does not implement, so the spec stubs the global and
+ * fires it.
+ *
+ * **Also deliberately absent:** `isAnimating()` — the component has such a signal and it
+ * never reaches the DOM, and deriving it from "something is encrypted" would be wrong in
+ * exactly the interesting case, since `animateOn="click"` rests fully encrypted and
+ * perfectly still. `getSpeed()` / `getMaxIterations()` / `getRevealDirection()` /
+ * `getClickMode()` / `getAnimateOn()` — inputs that are never reflected anywhere, so
+ * reporting them would mean reading the component instance rather than the rendered
+ * control; they are observable as behaviour, which is what the methods above measure.
+ * `getScrambleAlphabet()` — the pool is internal and each frame shows one random draw
+ * from it, so any reconstruction is a guess that gets worse the shorter the string.
+ * `getCharColors()` / `isDimmed()` — the `--encrypted` rule is deliberately EMPTY, a
+ * styling hook for consumers, so there is nothing painted to read in any environment.
+ *
+ * @example
+ * ```ts
+ * const secret = await loader.getHarness(WrDecryptTextHarness.with({ text: 'Hello' }));
+ *
+ * await secret.hover();
+ * vi.advanceTimersByTime(50);
+ *
+ * expect(await secret.getRevealedIndices()).toEqual([0]);   // sequential, from the start
+ * expect(await secret.getAccessibleText()).toBe('Hello');   // untouched throughout
+ * ```
+ *
+ * @see https://ngwr.dev/guides/testing
+ */
+declare class WrDecryptTextHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Build a predicate that narrows the query — pass to `getHarness` / `getAllHarnesses`. */
+    static with(options?: WrDecryptTextHarnessFilters): HarnessPredicate<WrDecryptTextHarness>;
+    private readonly chars;
+    private readonly encrypted;
+    /**
+     * The real string, as the one readable copy holds it.
+     *
+     * The single highest-value assertion here: it must stay equal to the `text` input on
+     * every frame, while the visible layer is unreadable by design. Lose this span and the
+     * component announces nothing at all — every drawn character sits under `aria-hidden`,
+     * so no other part of the DOM would change.
+     *
+     * Untrimmed, so that it can be compared against {@link getRenderedText} without one
+     * side of the comparison quietly forgiving a lost leading space.
+     */
+    getAccessibleText(): Promise<string>;
+    /**
+     * What is on screen this frame — scramble glyphs and all, in document order.
+     *
+     * Plain before anything triggers it, gibberish mid-reveal, and the real string once it
+     * settles; comparing it against {@link getAccessibleText} is how a spec says which of
+     * those it is looking at. `useOriginalCharsOnly` is visible only here — every glyph
+     * has to be one the text really contains.
+     *
+     * Nondeterministic unless the spec stubs `Math.random`, because each unrevealed
+     * position is an independent draw from the pool. When the assertion does not actually
+     * need the glyphs, {@link getRevealedIndices} answers the same progress question off
+     * the class and needs no stub.
+     */
+    getRenderedText(): Promise<string>;
+    /**
+     * How many characters the animation walks.
+     *
+     * CODE POINTS, not UTF-16 units: `'a🚀b'` is 3 here, and the indices
+     * {@link getRevealedIndices} returns line up with `[...text]` rather than with plain
+     * `text[i]`. That distinction is not pedantry — counting units gave a sequential
+     * reveal extra ticks with no character to spend them on, and made "everything is
+     * revealed" disagree with what was on screen.
+     */
+    getCharCount(): Promise<number>;
+    /**
+     * The positions that have settled on their real character, ascending.
+     *
+     * The payload method, and the deterministic one: it reads the `--encrypted` modifier
+     * rather than the glyphs, so no `Math.random` stub is involved. It is the only thing
+     * that separates `revealDirection` `'start'` (`[0]`, `[0, 1]`, …) from `'end'`
+     * (`[4]`, `[3, 4]`, …) from `'center'` (`[2]`, `[1, 2]`, …), and one index per tick is
+     * what makes a sequential reveal sequential.
+     *
+     * Ascending by position, NOT in the order the reveal visited them — the DOM records
+     * which characters have landed, never the path taken to them. Assert the set after
+     * each tick to pin an order.
+     */
+    getRevealedIndices(): Promise<number[]>;
+    /**
+     * How many characters are still scrambled.
+     *
+     * The coarse progress read, and the cheapest way to say "scrambled on hover", "plain on
+     * leave", or "a reader who asked for less motion never saw a scramble at all". Class-
+     * based like {@link getRevealedIndices}, so it too is random-proof.
+     */
+    getEncryptedCount(): Promise<number>;
+    /**
+     * Whether every character has settled.
+     *
+     * Deliberately does NOT also compare {@link getRenderedText} against
+     * {@link getAccessibleText}: folding two conditions into one boolean hides which of
+     * them broke, and a spec that wants both should write both lines.
+     *
+     * Throws when nothing was rendered. "No character is encrypted" is true of no
+     * characters, which is the same answer a component that stopped rendering its text
+     * would give — and this is the method most likely to be the only assertion in a test.
+     */
+    isFullyRevealed(): Promise<boolean>;
+    /**
+     * Whether the scramble layer is out of the accessibility tree.
+     *
+     * The contract that keeps a screen reader from spelling out `XQ#PZ` beside the real
+     * string it already read. Worth a method rather than an assumption because the wrapper
+     * holding the characters carries NO class — it can only be addressed as the readable
+     * span's next sibling, which any template reshuffle breaks.
+     *
+     * Throws when that structural selector finds nothing, rather than returning `false`: a
+     * missing wrapper and an unhidden one are different failures, and the answer to
+     * "is the scramble hidden" when there is no scramble layer at all is not `false`.
+     */
+    isAnimatedLayerHidden(): Promise<boolean>;
+    /**
+     * Point at it — the trigger for `animateOn` `'hover'` and `'inViewHover'`.
+     *
+     * Drives the component the way a user does, and works in a test because the trigger is
+     * an event rather than a gesture: `TestElement.hover()` dispatches `pointerenter`,
+     * `mouseover` and `mouseenter`, and the component listens for the last of those. A
+     * hand-rolled pointer-only dispatch would not reach it.
+     *
+     * Does nothing in the other two modes, exactly as a real pointer does nothing there.
+     */
+    hover(): Promise<void>;
+    /**
+     * Move the pointer off — the other half of hover mode.
+     *
+     * Pins the promise that leaving mid-scramble restores the real text IMMEDIATELY rather
+     * than letting the reveal play out: the reader took the effect away, so the string has
+     * to come back at once.
+     */
+    mouseAway(): Promise<void>;
+    /**
+     * Click the host — the `animateOn="click"` trigger, and the only way to tell
+     * `clickMode` `'once'` from `'toggle'`.
+     *
+     * There is no keyboard equivalent, and that is a statement about the component rather
+     * than about this harness: in click mode the host carries a click handler with no role,
+     * no `tabindex` and no keydown handler, so a keyboard or switch user cannot reveal the
+     * text at all. A `sendKeys(Enter)` here would invent an affordance that does not exist
+     * and let a spec pass over the top of it.
+     */
+    click(): Promise<void>;
+}
+
+export { WrDecryptTextHarness };
+export type { WrDecryptTextHarnessFilters };