stitchkit 0.113.3 → 0.114.1

package/dist/react/keyboard/layers.d.ts

@@ -29,8 +29,16 @@
  * the key — a widget's own `onKeyDown`, a text field, a popover that closes on
  * Escape — hears it first and keeps it by `preventDefault` or
  * `stopPropagation`. A layer only gets what nobody nearer wanted.
+ *
+ * One kind of layer is the exception: a `local` layer may ask for the capture
+ * phase. A menu that hangs over a text field keeps focus in the field and wants
+ * the arrows and Enter *before* the field acts on them; the field cannot be
+ * made to wait, so the layer goes first and, when it takes a key, nothing nearer
+ * hears it at all.
  */
 export type KeyLayerKind = 'overlay' | 'local' | 'route' | 'zone' | 'global';
+/** Where in the event's path a layer listens: after everything nearer, or before it. */
+export type KeyLayerPhase = 'bubble' | 'capture';
 /** The part of a `keydown` event the stack reads; a DOM `KeyboardEvent` is one. */
 export interface LayerKeyEvent {
     readonly key: string;
@@ -39,6 +47,8 @@ export interface LayerKeyEvent {
     readonly defaultPrevented: boolean;
     readonly target: EventTarget | null;
     preventDefault(): void;
+    /** A DOM event has it; a layer that takes a key in the capture phase uses it. */
+    stopPropagation?(): void;
 }
 /** The part of an element the stack reads to decide whether a layer is live and where it sits. */
 export interface LayerScope<S> {
@@ -52,8 +62,8 @@ export interface LayerScope<S> {
  * that move on arrows themselves, and any area marked `data-local-keys`.
  */
 export declare const KEY_FIELD_SELECTOR: string;
-/** The nearest element matching `selectors` from an event target, or `null`. */
-export declare function closestFromTarget(target: EventTarget | null, selectors: string): unknown;
+/** The nearest element matching `selectors` from an event target or an element, or `null`. */
+export declare function closestFromTarget(target: unknown, selectors: string): unknown;
 /** The key was pressed in a field or an area that keeps its keys. */
 export declare function isKeyFieldTarget(target: EventTarget | null): boolean;
 export interface KeyLayerState<E extends LayerKeyEvent, S extends LayerScope<S>> {
@@ -73,6 +83,11 @@ export interface KeyLayerState<E extends LayerKeyEvent, S extends LayerScope<S>>
      * `preventDefault`. `'include'`: the layer hears them too.
      */
     readonly fields?: 'skip' | 'include';
+    /**
+     * Default `'bubble'`. `'capture'` is for a `local` layer only: it hears the key
+     * before the element that has focus does, and a key it takes goes no further.
+     */
+    readonly phase?: KeyLayerPhase;
     /** Return `true` when the key was taken: its default is prevented and no layer below hears it. */
     onKey(event: E): boolean;
 }
@@ -82,17 +97,21 @@ export interface KeyLayerHandle<E extends LayerKeyEvent, S extends LayerScope<S>
 }
 /** Where the stack listens. A `Window` is one. */
 export interface KeyListenerTarget<E> {
-    addEventListener(type: 'keydown', listener: (event: E) => void): void;
-    removeEventListener(type: 'keydown', listener: (event: E) => void): void;
+    addEventListener(type: 'keydown', listener: (event: E) => void, capture?: boolean): void;
+    removeEventListener(type: 'keydown', listener: (event: E) => void, capture?: boolean): void;
 }
 export interface KeyLayerStack<E extends LayerKeyEvent, S extends LayerScope<S>> {
     add(state: KeyLayerState<E, S>): KeyLayerHandle<E, S>;
-    /** Offer one key to the layers; `true` when one took it. The installed listener calls this. */
-    dispatch(event: E): boolean;
+    /**
+     * Offer one key to the layers that listen in `phase` (default `'bubble'`);
+     * `true` when one took it. The installed listeners call this.
+     */
+    dispatch(event: E, phase?: KeyLayerPhase): boolean;
 }
 /**
- * A stack listening on `target`. The listener is attached with the first
- * layer and detached with the last, so a page without layers carries none.
+ * A stack listening on `target`. A listener is attached with the first layer of
+ * its phase and detached with the last, so a page without layers carries none,
+ * and a page with no capture layer carries no capture listener.
  */
 export declare function createKeyLayerStack<E extends LayerKeyEvent, S extends LayerScope<S>>(target: KeyListenerTarget<E>): KeyLayerStack<E, S>;
 //# sourceMappingURL=layers.d.ts.map

package/dist/react/keyboard/layers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../../src/react/keyboard/layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAU7E,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,cAAc,IAAI,IAAI,CAAC;CACxB;AAED,kGAAkG;AAClG,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC;IACnC,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,eAAe,CAAC,IAAI,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAUpB,CAAC;AAeZ,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAExF;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAGpE;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC;IAC7E,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,yGAAyG;IACzG,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,kGAAkG;IAClG,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC;IAC9E,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACtE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1E;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC;IAC7E,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;CAC7B;AAwDD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAClF,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CA6CrB"}
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../../src/react/keyboard/layers.ts"],"names":[],"mappings":"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"}

package/dist/react/keyboard/modality.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether a menu, a popover or a panel was opened with the keyboard.
+ *
+ * A script's `focus()` shows a focus ring when the element that had focus
+ * before it was showing one, whatever opened the thing: a menu opened by a right
+ * click, with focus on `body`, would still draw its ring on the first item, and
+ * nobody pressed a key. The cure is to decide at the moment of opening: move
+ * focus to the first item only when this answers `true`, and otherwise leave it
+ * on the menu's container.
+ */
+/**
+ * `true` when the element that has focus right now shows a focus ring — the
+ * browser's own guess that the person is using the keyboard. Call it in the
+ * event handler that opens the menu, before anything moves focus: after the
+ * menu has taken focus the answer is about the menu.
+ *
+ * `false` on a server, with nothing focused, or in a browser without
+ * `:focus-visible`.
+ */
+export declare function openedByKeyboard(): boolean;
+//# sourceMappingURL=modality.d.ts.map

package/dist/react/keyboard/modality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modality.d.ts","sourceRoot":"","sources":["../../../src/react/keyboard/modality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAQ1C"}

package/dist/react/keyboard/refs.d.ts

@@ -0,0 +1,13 @@
+import type { Ref } from 'react';
+/**
+ * One ref callback for several refs: a zone's `ref` beside a drag handle's, a
+ * measuring hook's or the application's own. Spread the zone's props, then set
+ * `ref: mergeRefs(props.ref, other)` — a later `ref` replaces an earlier one,
+ * and a merged ref keeps both.
+ *
+ * The result is a new function on every call. React detaches and re-attaches a
+ * callback ref whose identity changes, so a component that renders often keeps
+ * it in `useMemo`/`useCallback`.
+ */
+export declare function mergeRefs<T>(...refs: readonly (Ref<T> | undefined)[]): (node: T | null) => void;
+//# sourceMappingURL=refs.d.ts.map

package/dist/react/keyboard/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../../src/react/keyboard/refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAEjC;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,GAAG,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,GACvC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAO1B"}

package/dist/react/keyboard/testing.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Keyboard layers and zones without a DOM, a browser or React.
+ *
+ * The stack and the zone controller are plain objects that read a few members
+ * of an element and of a key event. This file is those members as fakes: a
+ * window that remembers its listener, elements with a parent, `inert` and
+ * visibility, key events with `preventDefault`. A test builds the layers a
+ * screen declares, presses keys on elements, and reads who heard what — the
+ * order of layers, `scope` and `inert`, the edges of a zone — in milliseconds.
+ *
+ * What it cannot show is a real focus ring, scrolling or a screen reader; that
+ * is a browser's.
+ */
+import { type KeyLayerStack, type LayerScope } from './layers.js';
+import { type ZoneItemElement, type ZoneKeyEvent } from './zone.js';
+export interface TestElementInit {
+    /** The element this one is inside. */
+    readonly parent?: TestElement;
+    /** An input, text area or combobox: it keeps its own keys. */
+    readonly field?: boolean;
+    /** An area marked `data-local-keys`. */
+    readonly localKeys?: boolean;
+    /** The element of a zone (`data-keyboard-zone`). */
+    readonly zone?: boolean;
+    /** Inside an `inert` subtree, or itself `inert`. Change it later with `element.inert`. */
+    readonly inert?: boolean;
+    /** Not visible (`checkVisibility()` is `false`). Change it later with `element.hidden`. */
+    readonly hidden?: boolean;
+}
+/** An element as the stack and the zone read it. Also a zone's item: it counts the focus it gets. */
+export interface TestElement extends LayerScope<TestElement>, ZoneItemElement, EventTarget {
+    readonly parent: TestElement | null;
+    isConnected: boolean;
+    inert: boolean;
+    hidden: boolean;
+    /** How many times `focus()` was called on it. */
+    focusCount: number;
+    /** How many times it was scrolled into view. */
+    scrollCount: number;
+    /** A new element inside this one. */
+    child(init?: Omit<TestElementInit, 'parent'>): TestElement;
+}
+export interface TestKeyInit {
+    readonly target?: EventTarget | null;
+    readonly repeat?: boolean;
+    readonly isComposing?: boolean;
+    readonly altKey?: boolean;
+    readonly ctrlKey?: boolean;
+    readonly metaKey?: boolean;
+    readonly shiftKey?: boolean;
+}
+/** A `keydown` as the stack and the zone read it. */
+export interface TestKeyEvent extends ZoneKeyEvent {
+    defaultPrevented: boolean;
+    /** A layer took the key in the capture phase, so nothing nearer — the field — would hear it. */
+    readonly propagationStopped: boolean;
+    stopPropagation(): void;
+}
+export interface KeyboardTestBed {
+    /** The stack, on a window that is not one: add layers to it as the hooks do. */
+    readonly stack: KeyLayerStack<TestKeyEvent, TestElement>;
+    /** Whether a window listener is attached: with the first layer, off with the last. */
+    readonly listening: boolean;
+    /** Whether the capture-phase listener is attached: only while a layer asks for that phase. */
+    readonly listeningInCapture: boolean;
+    element(init?: TestElementInit): TestElement;
+    /** A key event, not yet pressed. Hand it to `zone.keyDown(event, zoneElement)`. */
+    key(name: string, init?: TestKeyInit): TestKeyEvent;
+    /**
+     * Press a key on `init.target` through the window listeners: the capture
+     * phase first, then — unless a layer took the key there — the bubble phase.
+     * `event.defaultPrevented` is "a layer took it".
+     */
+    press(name: string, init?: TestKeyInit): TestKeyEvent;
+}
+/** A fresh stack, window, element and key factory for one test. */
+export declare function createKeyboardTestBed(): KeyboardTestBed;
+export { createKeyLayerStack, type KeyLayerHandle, type KeyLayerStack, type KeyLayerState, type KeyListenerTarget, type LayerKeyEvent, type LayerScope, } from './layers.js';
+export { createNavZone, type NavZoneController, type ZoneItemElement } from './zone.js';
+//# sourceMappingURL=testing.d.ts.map

package/dist/react/keyboard/testing.d.ts.map

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

package/dist/react/keyboard/zone.d.ts

@@ -7,12 +7,15 @@
  * follows it, `:focus-visible` draws it and the browser scrolls to it; there is
  * no second "highlighted" state beside focus for a page to keep in sync.
  *
- * Two modes, by what moving means:
+ * Three modes, by what moving means:
  *
  * - **select** — moving is choosing: the arrow calls `onChange(id, 'arrow')`
  *   (a sidebar whose item opens as you move).
  * - **highlight** — moving only points; Enter chooses with
  *   `onChange(id, 'confirm')` (a list where opening is expensive).
+ * - **focus** — moving only moves focus, and choosing belongs to the items: a
+ *   list of links or buttons keeps its own Enter, so the zone reports nothing
+ *   and takes no Enter (a menu, a row of toolbar buttons).
  *
  * Each zone keeps its own pointed item, so two zones on a page never share one.
  * The cross axis leaves the zone on purpose: `onEnter` (→ in a vertical zone)
@@ -50,6 +53,7 @@ export interface NextZoneIndexInput {
  * no index: every move runs past an end.
  */
 export declare function nextZoneIndex({ length, index, move, loop, }: NextZoneIndexInput): number | 'before-start' | 'after-end';
+/** A key and the modifiers that make a zone leave it alone. */
 export interface ZoneKey {
     readonly key: string;
     readonly altKey: boolean;
@@ -64,11 +68,6 @@ export type ZoneChangeCause = 'arrow' | 'confirm';
 export interface NavZoneOptions<Id extends ZoneItemId> {
     /** The items in order. An id not listed here has no place in the zone. */
     readonly items: readonly Id[];
-    /** The chosen item, or `null`. The zone never holds it: it reports changes. */
-    readonly value: Id | null;
-    onChange(id: Id, cause: ZoneChangeCause): void;
-    /** Default `'select'`. */
-    readonly mode?: 'select' | 'highlight';
     /** Default `'vertical'`. */
     readonly orientation?: ZoneOrientation;
     /**
@@ -103,7 +102,46 @@ export interface NavZoneOptions<Id extends ZoneItemId> {
      * its element mounts.
      */
     onReveal?(id: Id): void;
+    /**
+     * What the first arrow does when focus is in no zone — right after a click on
+     * the page, or on the empty part of a screen. Default `'focus'`: it puts focus
+     * on the current item and nothing else, so the person sees where they are
+     * before anything changes. `'move'`: it acts as if focus were already on the
+     * current item — the arrow moves from it, and in select mode chooses the
+     * neighbour — for a list that answers the first arrow with a change.
+     */
+    readonly outside?: 'focus' | 'move';
+    /**
+     * A key that is the application's own right now — an item being dragged with
+     * the keyboard uses the arrows itself. Returning `true` leaves the key
+     * entirely to the page: the zone neither moves, nor takes it, nor calls
+     * `preventDefault`. It is asked for every key the zone would act on, inside
+     * the zone and outside it.
+     */
+    ignore?(event: ZoneKeyEvent): boolean;
+    /** The chosen item, or `null`. The zone never holds it: it reports changes. */
+    readonly value: Id | null;
+    onChange(id: Id, cause: ZoneChangeCause): void;
+    /** Default `'select'`. */
+    readonly mode?: 'select' | 'highlight';
 }
+/**
+ * A zone whose items choose for themselves: arrows move focus, Enter stays with
+ * the focused element, and nothing is reported. `value` only marks the item the
+ * page is on (`aria-current` for `role: 'none'`).
+ */
+export type FocusZoneOptions<Id extends ZoneItemId> = Omit<NavZoneOptions<Id>, 'mode' | 'onChange' | 'value'> & {
+    readonly mode: 'focus';
+    /** The item the page is on, if any. Optional: a menu has none. */
+    readonly value?: Id | null;
+};
+export type ZoneOptions<Id extends ZoneItemId> = NavZoneOptions<Id> | FocusZoneOptions<Id>;
+/**
+ * Where the zone's tab stop is: the pointed item, else the chosen one, else the
+ * first — an index into `items`, `-1` for an empty zone. One scan when an item
+ * is pointed. Pure: a render may call it with the options it is rendering.
+ */
+export declare function resolveZoneIndex<Id extends ZoneItemId>(items: readonly Id[], value: Id | null, pointed: Id | null): number;
 /** The part of an item element the zone drives. An `HTMLElement` is one. */
 export interface ZoneItemElement {
     focus(options?: {
@@ -114,11 +152,23 @@ export interface ZoneItemElement {
         inline?: 'nearest';
     }): void;
 }
-export interface ZoneKeyEvent extends LayerKeyEvent, ZoneKey {
+/** The key an `ignore` callback is asked about, and what a zone reads of a key it is handed. */
+export interface ZoneKeyEvent extends LayerKeyEvent {
+    readonly altKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly metaKey: boolean;
+    readonly shiftKey: boolean;
 }
 export interface NavZoneController<Id extends ZoneItemId> {
-    update(options: NavZoneOptions<Id>): void;
-    readonly options: NavZoneOptions<Id>;
+    /**
+     * Adopt the options of a committed render. A new `value` takes the pointed
+     * item back to the chosen one, and subscribers hear it. A render that never
+     * commits must not call this.
+     */
+    update(options: ZoneOptions<Id>): void;
+    readonly options: ZoneOptions<Id>;
+    /** The item focus is on or was last on, if any — raw, before the chosen item and the list are consulted. */
+    pointedItem(): Id | null;
     /** The tab stop: the pointed item, else the chosen one, else the first. */
     current(): Id | null;
     /** A key pressed inside the zone's element (`zone` is that element). `true` when taken. */
@@ -135,5 +185,5 @@ export interface NavZoneController<Id extends ZoneItemId> {
     setItemElement(id: Id, element: ZoneItemElement | null): void;
     subscribe(listener: () => void): () => void;
 }
-export declare function createNavZone<Id extends ZoneItemId>(initial: NavZoneOptions<Id>): NavZoneController<Id>;
+export declare function createNavZone<Id extends ZoneItemId>(initial: ZoneOptions<Id>): NavZoneController<Id>;
 //# sourceMappingURL=zone.d.ts.map

package/dist/react/keyboard/zone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zone.d.ts","sourceRoot":"","sources":["../../../src/react/keyboard/zone.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"zone.d.ts","sourceRoot":"","sources":["../../../src/react/keyboard/zone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAyC,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAErF,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,YAAY,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAC9D,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,4EAA4E;AAC5E,eAAO,MAAM,cAAc,uBAAuB,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,KAAK,EACL,IAAI,EACJ,IAAI,GACL,EAAE,kBAAkB,GAAG,MAAM,GAAG,cAAc,GAAG,WAAW,CAU5D;AAED,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,2FAA2F;AAC3F,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,GAAG,UAAU,GAAG,IAAI,CAqB1F;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,cAAc,CAAC,EAAE,SAAS,UAAU;IACnD,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,uDAAuD;IACvD,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/C,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,EAAE,SAAS,UAAU,IAAI,IAAI,CACxD,cAAc,CAAC,EAAE,CAAC,EAClB,MAAM,GAAG,UAAU,GAAG,OAAO,CAC9B,GAAG;IACF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,UAAU,IAAI,cAAc,CAAC,EAAE,CAAC,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC;AAE3F;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,UAAU,EACpD,KAAK,EAAE,SAAS,EAAE,EAAE,EACpB,KAAK,EAAE,EAAE,GAAG,IAAI,EAChB,OAAO,EAAE,EAAE,GAAG,IAAI,GACjB,MAAM,CAUR;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACnD,cAAc,CAAC,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,SAAS,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,IAAI,CAAC;CAC5E;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB,CAAC,EAAE,SAAS,UAAU;IACtD;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;IAClC,4GAA4G;IAC5G,WAAW,IAAI,EAAE,GAAG,IAAI,CAAC;IACzB,2EAA2E;IAC3E,OAAO,IAAI,EAAE,GAAG,IAAI,CAAC;IACrB,2FAA2F;IAC3F,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACrD,wFAAwF;IACxF,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;IAC7C,kEAAkE;IAClE,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C;AAeD,wBAAgB,aAAa,CAAC,EAAE,SAAS,UAAU,EACjD,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,GACvB,iBAAiB,CAAC,EAAE,CAAC,CAiJvB"}

package/dist/telegram/budget-transformer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The outbound budget as a grammY client transformer.
+ *
+ * `budget.run` is the narrow adapter; wiring it by hand means writing the same
+ * closure in every bot and deciding, again, what a cancelled wait is. This is
+ * that closure once: `bot.api.config.use(telegramBudgetTransformer(budget))`.
+ *
+ * grammY types the signal it hands a transformer as the `abort-controller`
+ * polyfill's, which is not the platform `AbortSignal` the budget waits on, so a
+ * hand-written adapter either casts it or passes `undefined` and loses
+ * cancellation. The transformer bridges it, and a wait that is cancelled before
+ * the request was handed to the client is reported as what it is —
+ * `TelegramNotDispatchedError`, safe to repeat — while a request cancelled in
+ * flight stays the client's own error, because it may have arrived.
+ *
+ * grammY is named in the declarations and never imported at run time.
+ */
+import type { Transformer } from 'grammy';
+import type { TelegramOutboundBudget } from './outbound-budget.js';
+/**
+ * A grammY client transformer that runs every Bot API call under `budget`.
+ *
+ * Install it as the bot's one transformer; it replaces any limiter written
+ * beside it. A refusal Telegram returns as a response, not only a thrown one,
+ * pauses the token (see `TelegramOutboundBudget.run`), and the call is never
+ * repeated here.
+ *
+ * A cancellation that arrives while the call still waits for its turn, or in
+ * the instant after it was granted and before the request was handed on, throws
+ * `TelegramNotDispatchedError`: nothing was sent. A cancellation after the
+ * request was handed on is the client's ordinary error and the outcome is
+ * unknown, not a definite failure.
+ */
+export declare function telegramBudgetTransformer(budget: TelegramOutboundBudget): Transformer;
+//# sourceMappingURL=budget-transformer.d.ts.map

package/dist/telegram/budget-transformer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-transformer.d.ts","sourceRoot":"","sources":["../../src/telegram/budget-transformer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AA4BhE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,sBAAsB,GAAG,WAAW,CAsBrF"}

package/dist/telegram/outbound-budget.d.ts

@@ -0,0 +1,101 @@
+/**
+ * One outbound budget for one Telegram bot token.
+ *
+ * Telegram counts a bot's bulk messages per token, not per subsystem. A bot
+ * that sends a marketing campaign, answers a person and posts an operator note
+ * through three senders has one limit, and three separate pacemakers cannot
+ * keep it: each of them is below the limit on its own and the sum is not.
+ *
+ * This is the one place that counts. The token names the budget; every alias
+ * of the same token in the process gets the same object, and another token is
+ * another budget. The unit is a Telegram message: `sendMediaGroup` and
+ * `sendPaidMedia` cost their media length, `copyMessages` and
+ * `forwardMessages` cost their message ids, and the follow-up call to action
+ * after an album is one more message.
+ *
+ * **It paces; it does not retry.** A 429 pauses every sender of the token for
+ * the wait Telegram stated (or a declared fallback when it stated none). A
+ * network failure or a 5xx is returned to the caller unchanged: repeating a
+ * send whose external outcome is unknown is the caller's decision, and a
+ * primitive that retried it would turn one unknown message into two.
+ *
+ * The schedule is a strict token budget, not a bucket with a full burst: the
+ * first call after an idle period is immediate, and every later call occupies
+ * its own `cost / messagesPerSecond` interval. A full bucket would release a
+ * saved burst at start and again after a 429 pause, which is exactly the
+ * stampede a shared budget exists to prevent.
+ */
+export interface TelegramOutboundBudgetConfig {
+    /** The bot token whose sends share this budget. It is never returned or logged. */
+    readonly token: string;
+    /** Telegram messages per second. Default 24. */
+    readonly messagesPerSecond?: number;
+    /**
+     * How long a 429 without `retry_after` pauses the token. Default 1000 ms.
+     * Telegram's own `retry_after` is always used instead when present.
+     */
+    readonly retryAfterFallbackMs?: number;
+    /**
+     * Test seam: the monotonic clock. Default `performance.now`. A wall clock can
+     * jump backwards and turn a pause into a burst, so the default is monotonic.
+     */
+    readonly now?: () => number;
+    /**
+     * Test seam: how a wait is taken. Default the shared abortable sleep. A
+     * custom sleeper must reject with `signal.reason` when the signal aborts.
+     */
+    readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+/** What the budget has done, with no token and no message ids. */
+export interface TelegramOutboundBudgetStats {
+    /** Calls admitted by `acquire` or `run`. */
+    readonly granted: number;
+    /** Weighted messages admitted: an album of three counts as three. */
+    readonly messages: number;
+    /** Calls waiting for their turn. */
+    readonly queued: number;
+    readonly messagesPerSecond: number;
+    /** How much of the current 429 pause is still ahead, in milliseconds. */
+    readonly pausedForMs: number;
+}
+/**
+ * A token's outbound budget. `run` is the narrow adapter a client transformer
+ * calls around its own send; it gates, pauses on 429 and never retries.
+ */
+export interface TelegramOutboundBudget {
+    /**
+     * Run one Bot API call under the budget. A non-send method passes through
+     * without spending a message. A 429 pauses every sender of the token, whether
+     * `send` throws it or resolves with the Bot API's `{ ok: false, … }` body, as
+     * a client transformer's `send` does. The error is rethrown, or the response
+     * returned, unchanged and the call is not repeated.
+     */
+    run<T>(method: string, payload: unknown, signal: AbortSignal | undefined, send: () => Promise<T>): Promise<T>;
+    /**
+     * Wait until `cost` messages fit. The wait rejects with `signal.reason`
+     * without spending a token; a granted call owns its slots even if its later
+     * send is aborted, which the caller must not repeat as a definite failure.
+     */
+    acquire(cost: number, signal?: AbortSignal): Promise<void>;
+    /** Pause every sender of this token for at least `milliseconds`. Never shortens an existing pause. */
+    pause(milliseconds: number): void;
+    /** Pause the token after a rate-limited refusal; another failure does nothing. */
+    pauseAfter(error: unknown): void;
+    /**
+     * Wait out the current pause without spending a token. For a retry path that
+     * is not a send (edit, delete) and does not go through `acquire`.
+     */
+    waitUntilResumed(signal?: AbortSignal): Promise<void>;
+    /** Measured counters. It never contains the token. */
+    stats(): TelegramOutboundBudgetStats;
+}
+/**
+ * The one budget for `config.token`, created on first use.
+ *
+ * Two aliases of one token share it; two tokens never do. A second call for a
+ * token already in use must agree on the options, otherwise the process has
+ * two incompatible policies for one credential and the call is refused. The
+ * refusal never contains the token.
+ */
+export declare function telegramOutboundBudget(config: TelegramOutboundBudgetConfig): TelegramOutboundBudget;
+//# sourceMappingURL=outbound-budget.d.ts.map

package/dist/telegram/outbound-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-budget.d.ts","sourceRoot":"","sources":["../../src/telegram/outbound-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAwEH,MAAM,WAAW,4BAA4B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,yEAAyE;IACzE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,EACH,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,sGAAsG;IACtG,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,sDAAsD;IACtD,KAAK,IAAI,2BAA2B,CAAC;CACtC;AAyMD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,sBAAsB,CAsCxB"}

package/dist/telegram/send-failure.d.ts

@@ -30,8 +30,13 @@
  * user who never pressed Start needs an invitation rather than a retry, and a
  * chat Telegram does not know is usually a bad identifier on our side — a
  * defect in our data, not a fact about a person.
+ *
+ * `bot-to-bot-disabled` is permanent for this send but does not accuse the
+ * recipient: Telegram disables bot-to-bot messaging when *either* bot has not
+ * enabled its Bot to Bot setting, so the missing setting may be the sender's.
+ * It is never retried, and it never marks the recipient unreachable.
  */
-export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'rate-limited' | 'message-invalid' | 'server-error' | 'not-dispatched' | 'unknown';
+export type TelegramSendFailureReason = 'blocked-by-user' | 'user-deactivated' | 'chat-not-found' | 'not-started' | 'bot-to-bot-disabled' | 'rate-limited' | 'message-invalid' | 'server-error' | 'not-dispatched' | 'unknown';
 export interface TelegramSendFailure {
     reason: TelegramSendFailureReason;
     /** Telegram's `error_code`, when the failure carried one. */

package/dist/telegram/send-failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;CAC1E;AA+CD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AAyClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA4D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,qBAAqB,GACrB,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,gBAAgB,GAChB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,WAAW,GAAG,MAAM,CAAC;CAC1E;AAoDD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,yBAAyB,EAC7B,CAAC;AA4ClD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA4D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}

package/llms/react-keyboard-testing.txt

@@ -0,0 +1,24 @@
+# stitchkit/react/keyboard/testing — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/react/keyboard/testing`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/react/keyboard/testing`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/react/keyboard/testing`
+
+Keyboard layers and zones without a DOM, a browser or React: fakes for the
+window, elements and key events, and the two engines the hooks are made of.
+Peer-free. A test builds the layers a screen declares, presses keys on elements
+and reads who heard what — see the [keyboard guide](../guide/keyboard.md#testing-without-a-dom).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createKeyboardTestBed` | function | a fresh stack, window, element factory and key factory: `stack.add(layer)`, `press(key, { target })`, `element({ parent, field, zone, inert, hidden })`, `key(name)` for a zone, and `listening` |
+| `KeyboardTestBed` / `TestElement` / `TestElementInit` / `TestKeyEvent` / `TestKeyInit` | _type_ | the test bed, an element (also a zone item: it counts `focus()` and scrolling), what builds one, and a key event with `defaultPrevented` |
+| `createKeyLayerStack` / `KeyLayerStack` / `KeyLayerHandle` / `KeyLayerState` / `KeyListenerTarget` / `LayerKeyEvent` / `LayerScope` | function / _type_ | the layer stack the hooks put on the window, over any listener target and elements that have `contains`, `closest`, `isConnected` |
+| `createNavZone` / `NavZoneController` / `ZoneItemElement` | function / _type_ | a zone controller without React: `keyDown`, `keyFromOutside`, `focused`, `focus`, `update`, `current`, `pointedItem`, `subscribe` |