@cssints/headless 0.18.0 → 0.20.0

package/dist/index.d.mts

@@ -1030,6 +1030,94 @@ export interface Checkbox {
  * pass `value` + `onValueChange` to own the state.
  */
 export declare const createCheckbox: (options?: CheckboxOptions) => Checkbox;
+export interface FieldOptions {
+  /** Base of every id the field makes (`<id>-control`, `-label`, `-hint`, `-error`). */
+  readonly id?: string | undefined;
+  readonly required?: boolean | undefined;
+  /**
+   * `true` marks the control invalid; a string does too and is the error message
+   * (unless `error` is set). `false` forces valid: an `error` is then not shown,
+   * so a host can pass `touched() && failed()` and keep the message ready.
+   * Left out, the field is invalid exactly when it has an error message.
+   */
+  readonly invalid?: boolean | string | undefined;
+  /** Help text; absent (or empty) means the hint element is hidden and not referenced. */
+  readonly hint?: string | undefined;
+  /** The error message; absent (or empty) means no error element. */
+  readonly error?: string | undefined;
+  /**
+   * Ids of elements the host owns, appended to `aria-describedby` after the
+   * field's own hint and error: a form-level error that belongs to several
+   * controls ("the passwords do not match" names both). One id or a list;
+   * empty strings are dropped, and the attribute is absent when nothing is left.
+   * The host keeps that element rendered, and decides whether it is hidden.
+   */
+  readonly describedby?: string | readonly string[] | undefined;
+}
+/** Spread onto the form control (`input`, `textarea`, `select`, or a custom widget). */
+export interface FieldControlProps {
+  readonly id: string;
+  /** The ids of the hint and the error that are shown, hint first, then the host's `describedby`; absent when there are none. */
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
+  /** For a control that is not native (a native one has `required`). */
+  readonly "aria-required": "true" | undefined;
+  readonly required: true | undefined;
+}
+export interface FieldLabelProps {
+  readonly id: string;
+  readonly for: string;
+}
+/** Spread onto the hint and the error element; render both, always. */
+export interface FieldMessageProps {
+  readonly id: string;
+  readonly hidden: boolean;
+}
+/** The error element also announces itself: `role="alert"` while it is shown. */
+export interface FieldErrorProps extends FieldMessageProps {
+  readonly role: "alert" | undefined;
+}
+export interface Field {
+  readonly invalid: () => boolean;
+  /** The hint, or `undefined` when there is none. */
+  readonly hint: () => string | undefined;
+  /** The error shown: `undefined` unless the field is invalid and has a message. */
+  readonly error: () => string | undefined;
+  /**
+   * The ids `aria-describedby` lists now: hint, then error (never an id that is
+   * hidden), then the host's `describedby`.
+   */
+  readonly describedIds: () => readonly string[];
+  readonly controlProps: FieldControlProps;
+  readonly labelProps: FieldLabelProps;
+  readonly hintProps: FieldMessageProps;
+  readonly errorProps: FieldErrorProps;
+}
+/**
+ * The ARIA contract of a form field: a label, a control, a hint and an error.
+ * There is no APG pattern for it (APG has no "form field"; the nearest is the
+ * label and description rules of the accessible name computation), so the
+ * contract comes from WAI-ARIA 1.2 (`aria-describedby`, `aria-invalid`,
+ * `aria-required`) and HTML (`label[for]`, `required`), and from the
+ * majority of Base UI Field, react-aria TextField and ariakit FormControl,
+ * which list the description and the error message together. It is not checked
+ * against a Quint spec; `test/field.browser.test.tsx` is its oracle.
+ *
+ * Decisions: the error does not replace the hint, both are listed, hint first
+ * (the hint is what tells the user how to fix the error); an error implies
+ * invalid and `invalid: false` overrides it; a hidden message is never
+ * referenced, so `aria-describedby` has no dangling id. The error element is
+ * `role="alert"` only while it is shown (a hidden element announces nothing, and
+ * one that appears is announced); the hint is never an alert.
+ *
+ * `describedby` lists host-owned ids after the field's own: one refusal that
+ * belongs to two controls is one form-level element (with its own `role`), named
+ * by both. The field cannot know whether that element is shown: the host
+ * passes the id only while it is.
+ *
+ * Options are read when an attribute is read: pass getters, never destructure.
+ */
+export declare const createField: (options?: FieldOptions) => Field;
 export type CheckboxGroupFocus = "none" | "parent" | "c0" | "c1" | "c2";
 export type ParentChecked = "true" | "false" | "mixed";
 export interface CheckboxGroupOptions<T = unknown> {
@@ -1043,6 +1131,22 @@ export interface CheckboxGroupOptions<T = unknown> {
   readonly parent?: boolean;
   /** Remember the last mixed combination for the controller's third activation. */
   readonly remember?: boolean;
+  /** Base of the group's ids (`<id>-control`, `-error`); a unique one when absent. */
+  readonly id?: string;
+  /** The group's name, as `aria-label`: a `role="group"` needs one. */
+  readonly label?: string | undefined;
+  /** The id of the element that names the group (`aria-labelledby`); wins over `label`. */
+  readonly labelledby?: string | undefined;
+  /** Ids of elements the host owns that describe the group, after the group's own error id. */
+  readonly describedby?: string | undefined;
+  /**
+   * `true` marks the group invalid; a string does too and is the error message
+   * (unless `error` is set). `false` forces valid. Left out, the group is invalid
+   * exactly when it has an error message. Same contract as `createField`.
+   */
+  readonly invalid?: boolean | string | undefined;
+  /** The error message; absent (or empty) means no error element. */
+  readonly error?: string | undefined;
   /**
    * A request to change the checked subset, called when the intent differs from
    * the current value. Uncontrolled it is accepted; controlled the host may
@@ -1070,9 +1174,18 @@ export interface CheckboxGroupChildProps {
   readonly onFocus: () => void;
 }
 export interface CheckboxGroupProps {
+  /** The group element: a host's label can name it, and a controller can `aria-controls` it. */
+  readonly id: string;
   readonly role: "group";
+  readonly "aria-label": string | undefined;
+  readonly "aria-labelledby": string | undefined;
+  /** The error id while one is shown, then the host's `describedby`. */
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
   readonly onKeyDown: (event: KeyboardEvent) => void;
 }
+/** The error element: render it always, it is `hidden` while there is no error. */
+export type CheckboxGroupErrorProps = FieldErrorProps;
 export interface CheckboxGroup<T = unknown> {
   readonly children: Accessor<ReadonlyArray<boolean>>;
   readonly memory: Accessor<ReadonlyArray<boolean>>;
@@ -1080,6 +1193,14 @@ export interface CheckboxGroup<T = unknown> {
   readonly focused: Accessor<CheckboxGroupFocus>;
   readonly parentChecked: Accessor<ParentChecked>;
   readonly checkedValues: () => ReadonlyArray<T>;
+  /** The error shown: `undefined` unless the group is invalid and has a message. */
+  readonly error: () => string | undefined;
+  readonly invalid: () => boolean;
+  /**
+   * The ids `aria-describedby` lists now: the error (never while it is hidden),
+   * then the host's `describedby`.
+   */
+  readonly describedIds: () => readonly string[];
   readonly click: (target: CheckboxGroupFocus) => void;
   readonly keySpace: () => void;
   readonly keyTab: () => void;
@@ -1088,6 +1209,7 @@ export interface CheckboxGroup<T = unknown> {
   readonly setRemember: (value: boolean) => void;
   readonly setChildren: (children: ReadonlyArray<boolean>) => void;
   readonly groupProps: CheckboxGroupProps;
+  readonly errorProps: CheckboxGroupErrorProps;
   readonly parentProps: CheckboxGroupParentProps;
   readonly childProps: (index: 0 | 1 | 2) => CheckboxGroupChildProps;
 }
@@ -1103,7 +1225,17 @@ export interface CheckboxGroup<T = unknown> {
  * pass `value` + `onValueChange` to own the checked subset. The checked set is
  * packed internally so it rides the scalar `createControllable`.
  *
- * Behaviour is checked against `specs/apg/checkbox-group.qnt` by the bridge.
+ * The name, the description and the error are `createField`'s contract on the
+ * `role="group"` element (`aria-label` / `aria-labelledby`, `aria-describedby`,
+ * `aria-invalid`, an error element that is `role="alert"` while it is shown), so
+ * a group reads like the fields around it. The group is not a `<label for>`
+ * target: a host names a visible label element's id with `labelledby`, or passes
+ * `label` without one.
+ *
+ * Behaviour is checked against `specs/apg/checkbox-group.qnt` by the bridge. That
+ * model leaves labelling out on purpose ("shift+Tab, accessible names,
+ * fieldset/legend or role=group labelling" in its header), so the field contract
+ * is checked by plain assertions in `test/checkbox-group.browser.test.tsx`.
  */
 export declare const createCheckboxGroup: <T = unknown>(options: CheckboxGroupOptions<T>) => CheckboxGroup<T>;
 /**
@@ -1294,6 +1426,215 @@ export interface DialogModal {
  * are requests the host may ignore.
  */
 export declare const createDialogModal: (options?: DialogModalOptions) => DialogModal;
+export interface StatusOptions {
+  /** Rendered on `statusProps`; generated when absent. */
+  readonly id?: string | undefined;
+}
+/** Spread onto the `role=status` live region. Render it once, always. */
+export interface StatusProps {
+  readonly id: string;
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface Status {
+  /** The text currently shown, or `undefined` before the first `show`. */
+  readonly message: Accessor<string | undefined>;
+  /** Writes the message, replacing the previous one; nothing is queued. */
+  readonly show: (text: string) => void;
+  readonly clear: () => void;
+  readonly statusProps: StatusProps;
+}
+/**
+ * APG Alert's polite sibling: one `role=status` live region whose text the host
+ * replaces ("Link copied", "Saved"). It is not a queue: a second message shows
+ * in place of the first, so a burst reads as the last state, not as N alerts.
+ * The region is rendered once and stays mounted, which is what makes a change
+ * of its text announced.
+ *
+ * A status is never for errors: an error that needs attention now is
+ * `createAlert` (`role=alert`, assertive), and a message with a title, a
+ * description and a timeout is `createToast`.
+ */
+export declare const createStatus: (options?: StatusOptions) => Status;
+/** The HTML `autocomplete` tokens worth naming; the attribute also takes an arbitrary token. */
+export type AutoCompleteToken = "off" | "on" | "name" | "given-name" | "family-name" | "username" | "email" | "tel" | "url" | "organization" | "street-address" | "postal-code" | "current-password" | "new-password" | "one-time-code" | "nickname";
+export interface TextInputOptions extends FieldOptions {
+  readonly type?: "text" | "email" | "tel" | "url" | "search" | "password" | undefined;
+  /** The HTML token list: the browser's own autofill is the accessible path. */
+  readonly autoComplete?: AutoCompleteToken | undefined;
+  readonly spellCheck?: boolean | undefined;
+  readonly autoCapitalize?: "none" | "sentences" | "words" | "characters" | undefined;
+  readonly inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
+  readonly maxLength?: number | undefined;
+  readonly readOnly?: boolean | undefined;
+  readonly disabled?: boolean | undefined;
+  readonly name?: string | undefined;
+  readonly dir?: "ltr" | "rtl" | "auto" | undefined;
+  readonly placeholder?: string | undefined;
+  /** Change and input both land here; the host decides what a keystroke means. */
+  readonly onValueChange?: ((value: string) => void) | undefined;
+}
+export interface TextAreaOptions extends TextInputOptions {
+  readonly rows?: number | undefined;
+  readonly wrap?: "soft" | "hard" | "off" | undefined;
+  readonly resize?: "none" | "vertical" | "horizontal" | "both" | undefined;
+}
+export interface TextControlProps {
+  readonly id: string;
+  readonly "aria-describedby": string | undefined;
+  readonly "aria-invalid": "true" | undefined;
+  readonly "aria-required": "true" | undefined;
+  readonly required: true | undefined;
+  readonly type: TextInputOptions["type"];
+  readonly autoComplete: AutoCompleteToken | undefined;
+  readonly spellcheck: "true" | "false" | undefined;
+  readonly autocapitalize: TextInputOptions["autoCapitalize"];
+  readonly inputmode: TextInputOptions["inputMode"];
+  readonly maxlength: number | undefined;
+  readonly readOnly: true | undefined;
+  readonly disabled: true | undefined;
+  readonly name: string | undefined;
+  readonly dir: "ltr" | "rtl" | "auto" | undefined;
+  readonly placeholder: string | undefined;
+  readonly onInput: (event: {
+    currentTarget: {
+      value: string;
+    };
+  }) => void;
+}
+export interface TextAreaControlProps extends TextControlProps {
+  readonly rows: number | undefined;
+  readonly wrap: TextAreaOptions["wrap"];
+  readonly style: {
+    readonly resize: "none" | "vertical" | "horizontal" | "both";
+  } | undefined;
+}
+/** The field and the control, one object: every prop the element needs. */
+export interface TextInput extends Field {
+  readonly controlProps: TextControlProps;
+}
+export interface TextArea extends Field {
+  readonly controlProps: TextAreaControlProps;
+}
+/**
+ * A text input with the field contract attached: label, hint, error (announced),
+ * `aria-describedby` and `aria-invalid` come from `createField`; this adds the
+ * props a host forgets — autofill tokens, spellcheck, inputmode, maxlength, the
+ * disabled/readOnly pair. Platform: native (`input` is its own APG-equivalent;
+ * no primitive re-implements text editing, which is why there is no key
+ * handling here).
+ *
+ * Both `required` and `aria-required` are emitted: the native attribute is what
+ * the browser enforces, the ARIA one is what a custom widget reading the same
+ * props needs. A host that validates itself passes `noValidate` on the form
+ * rather than dropping the attribute.
+ */
+export declare const createTextInput: (options?: TextInputOptions) => TextInput;
+/**
+ * The same contract for a textarea, plus rows, wrap and resize. `resize` is a
+ * style because CSS has no attribute for it; `none` is the value a layout that
+ * owns its own height wants.
+ */
+export declare const createTextArea: (options?: TextAreaOptions) => TextArea;
+/** One command the host offers; `group` only picks the heading the host renders. */
+export interface PaletteCommand {
+  readonly id: string;
+  readonly label: string;
+  readonly group?: string | undefined;
+  readonly keywords?: ReadonlyArray<string> | undefined;
+  readonly run: () => void | Promise<void>;
+}
+/** A command that survived the filter, in host order. */
+export interface PaletteResult {
+  readonly id: string;
+  readonly label: string;
+  readonly group: string | undefined;
+}
+/** Every string the host puts on screen; override what you translate. */
+export interface CommandPaletteLabels {
+  /** The dialog's name; `titleProps` heads it and the listbox is named by it. */
+  readonly title: string;
+  readonly placeholder: string;
+  readonly empty: string;
+  /** The result count the polite region announces, once per query. */
+  readonly results: (count: number) => string;
+}
+export interface CommandPaletteOptions {
+  readonly commands: ReadonlyArray<PaletteCommand>;
+  /** Controlled: the host owns the open state and this is the only thing that changes it. */
+  readonly open?: boolean | undefined;
+  /** A request to change the open state, called when the intent differs. */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+  /** The `createHotkeys` chord `attach` binds; `"mod+k"` by default. */
+  readonly hotkey?: string | undefined;
+  readonly labels?: Partial<CommandPaletteLabels> | undefined;
+}
+export interface CommandPalette {
+  readonly open: Accessor<boolean>;
+  readonly openPalette: () => void;
+  readonly closePalette: () => void;
+  readonly query: Accessor<string>;
+  readonly setQuery: (text: string) => void;
+  /** Index into `results()`; `-1` = the search field holds the highlight. */
+  readonly active: Accessor<number>;
+  readonly setActive: (index: number) => void;
+  readonly results: Accessor<ReadonlyArray<PaletteResult>>;
+  readonly labels: CommandPaletteLabels;
+  /** The live region's text; render it inside `statusProps`. */
+  readonly status: Accessor<string | undefined>;
+  readonly inputProps: TextControlProps & {
+    readonly role: "searchbox";
+    readonly value: string;
+    readonly "aria-controls": string;
+    readonly "aria-activedescendant": string | undefined;
+    readonly onKeyDown: (event: KeyboardEvent) => void;
+  };
+  readonly listProps: {
+    readonly id: string;
+    readonly role: "listbox";
+    readonly "aria-labelledby": string;
+    /** A pointer click keeps the focus in the search field. */
+    readonly onMouseDown: (event: MouseEvent) => void;
+  };
+  readonly optionProps: (id: string) => {
+    readonly id: string;
+    readonly role: "option";
+    readonly "aria-selected": "true" | "false";
+    readonly tabindex: -1;
+    readonly onClick: () => void;
+    readonly onMouseEnter: () => void;
+  };
+  readonly emptyProps: {
+    readonly hidden: boolean;
+  };
+  readonly statusProps: StatusProps;
+  readonly dialogProps: DialogContentProps;
+  readonly backdropProps: DialogBackdropProps;
+  readonly titleProps: {
+    readonly id: string;
+  };
+  /** Runs the active command and closes the palette; a no-op with no highlight. */
+  readonly runActive: () => void | Promise<void>;
+  /** Binds the hotkey on the document; call once and call the teardown on cleanup. */
+  readonly attach: () => () => void;
+}
+/**
+ * A command palette: `createDialogModal` (a modal dialog, announced as one),
+ * `createTextInput` (a `searchbox`, not a combobox — choosing runs a command,
+ * it does not complete the field) and one filtered list. Focus stays in the
+ * field; `aria-activedescendant` names the highlighted option, and ↓ on the
+ * last / ↑ on the first return the highlight to the field. Home/End are menu
+ * keys only while the field is empty, so the caret keeps them while typing.
+ * Filtering is a plain case-insensitive substring match on the label and the
+ * keywords, no fuzzy scoring: a palette is short and stable, and ranking
+ * (recency, scopes) is a policy the host owns.
+ *
+ * The host's: rendering and grouping (the `group` field, headings, the CSS),
+ * async commands (a rejected `run` is the host's to report), and any close
+ * other than Escape / a command. `runActive` closes before it runs.
+ */
+export declare const createCommandPalette: (options: CommandPaletteOptions) => CommandPalette;
 export interface ConfirmOptions {
   readonly id?: string | undefined;
   /** Called with `true` when a request opens the dialog and `false` when it settles. */
@@ -1497,6 +1838,106 @@ export interface Drawer {
  * dismissal a non-modal drawer has); closing returns focus to the trigger.
  */
 export declare const createDrawer: (options?: DrawerOptions) => Drawer;
+/** Why a file was refused: the `accept` grammar, or `maxSize`. */
+export type DropZoneRejectReason = "type" | "size";
+export interface DropZoneReject {
+  readonly file: File;
+  readonly reason: DropZoneRejectReason;
+}
+export interface DropZoneLabels {
+  /** The zone's accessible name (`aria-label` on the `role=group` zone). */
+  readonly zone?: string | undefined;
+  /** The browse button's accessible name; render it visibly, or use it for an icon-only button. */
+  readonly browse?: string | undefined;
+}
+export interface DropZoneOptions {
+  /** The HTML `accept` grammar: extensions (`.png`) and MIME types, wildcards included (`image/*`). */
+  readonly accept?: string | undefined;
+  readonly multiple?: boolean | undefined;
+  /** Bytes; a larger file is rejected with `"size"`. */
+  readonly maxSize?: number | undefined;
+  readonly disabled?: boolean | undefined;
+  /** The files that passed, one call per batch; not called when the batch has none. */
+  readonly onFiles: (files: File[]) => void;
+  /** Each refused file, once, with the reason the host shows. */
+  readonly onReject?: ((reject: DropZoneReject) => void) | undefined;
+  readonly labels?: DropZoneLabels | undefined;
+}
+/** Spread onto the hidden `<input type=file>`; render it, always. */
+export interface DropZoneInputProps {
+  /** The id the browse button clicks; generated. */
+  readonly id: string;
+  readonly type: "file";
+  readonly accept: string | undefined;
+  readonly multiple: true | undefined;
+  readonly disabled: true | undefined;
+  readonly hidden: true;
+  readonly onChange: (event: {
+    currentTarget: HTMLInputElement;
+  }) => void;
+}
+/** Spread onto the drop target (any element). `dragging()` is the styling hook. */
+export interface DropZoneZoneProps {
+  readonly role: "group";
+  readonly "aria-label": string | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly onDragEnter: (event: DragEvent) => void;
+  readonly onDragOver: (event: DragEvent) => void;
+  readonly onDragLeave: (event: DragEvent) => void;
+  readonly onDrop: (event: DragEvent) => void;
+}
+/** Spread onto a real `<button type="button">`: Enter and Space are the platform's. */
+export interface DropZoneBrowseProps {
+  readonly type: "button";
+  readonly disabled: true | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly "aria-label": string | undefined;
+  readonly onClick: () => void;
+}
+/** Spread onto the live region; render it once, always. */
+export interface DropZoneStatusProps {
+  readonly role: "status";
+  readonly "aria-live": "polite";
+  readonly "aria-atomic": "true";
+}
+export interface DropZone {
+  /** A drag is over the zone; `dragleave` on a child does not clear it. */
+  readonly dragging: Accessor<boolean>;
+  /**
+   * A default sentence for the last batch ("2 files, 1 rejected: too large"),
+   * or `undefined` before one arrived. The host may write its own words from
+   * the same counts.
+   */
+  readonly message: Accessor<string | undefined>;
+  readonly inputProps: DropZoneInputProps;
+  readonly zoneProps: DropZoneZoneProps;
+  readonly browseProps: DropZoneBrowseProps;
+  readonly statusProps: DropZoneStatusProps;
+}
+/**
+ * A file drop zone. There is no APG pattern and no Quint spec for one: the
+ * contract is HTML's file input plus WAI-ARIA's live region, and
+ * `test/dropzone.browser.test.tsx` is its oracle.
+ *
+ * Decisions:
+ * - **The zone is never drag-only.** `browseProps` spreads onto a real
+ *   `<button type="button">` that clicks the hidden input, so the picker is the
+ *   keyboard path (Enter and Space are the platform's) and a pointer user can
+ *   click as well as drag. The drop handlers add nothing the button cannot do.
+ * - **Validation happens once per file**, in the order type then size, and a
+ *   refused file reaches `onReject` with the reason the host shows. `accept` is
+ *   the HTML grammar (`.` extension, MIME type, `*`); `maxSize` is bytes.
+ * - **Dropping a folder or a `DataTransfer` with no files is a no-op**: no
+ *   `onFiles`, no `onReject`, no message, and the previous announcement stays.
+ * - **`dragleave` counts.** A child's `dragleave` bubbles to the zone, so the
+ *   state is a depth counter: it clears only when the drag leaves the zone
+ *   itself, or on a drop.
+ * - **The zone is `role=group`** so `labels.zone` is exposed; `dragging()` is
+ *   the only drag state a skin reads (no `data-dragging`).
+ * - `disabled` marks the zone `aria-disabled`, disables the input natively and
+ *   the browse button, and drops every drag before it becomes a batch.
+ */
+export declare const createDropZone: (options: DropZoneOptions) => DropZone;
 /**
  * Options are read lazily (getters); pass a component's `props`.
  */
@@ -1558,120 +1999,32 @@ export interface Feed {
   readonly ctrlEnd: () => void;
   readonly ctrlHome: () => void;
   /** Scroll/position asked for more: `aria-busy` goes true while in flight. */
-  readonly loadStart: () => void;
-  /** A batch arrived; a request to grow the loaded count. */
-  readonly loadFinish: (count: number) => void;
-  readonly loadFail: () => void;
-  readonly setSizeMode: (mode: "loaded" | "total") => void;
-  readonly setTotalKnown: (known: boolean) => void;
-  readonly feedProps: FeedProps;
-  readonly articleProps: (posinset: number) => FeedArticleProps;
-  readonly beforeProps: FeedSentinelProps;
-  readonly afterProps: FeedSentinelProps;
-}
-/**
- * APG Feed (https://www.w3.org/WAI/ARIA/apg/patterns/feed/): state plus prop
- * objects for the feed container, its articles and the two outside focus
- * sentinels. Focus reaching the last loaded article triggers a load; `aria-busy`
- * brackets it; Page Up/Down move by article; Control+End/Home leave the feed.
- * No styling, no elements. Checked against `specs/apg/feed.qnt`.
- *
- * Platform: **library** — focusgroup V2 `feed` is explainer-only, so the load
- * trigger, busy bracketing and Page Up/Down / Control+End/Home keys are ours.
- *
- * Request/commit (map ticket `rt1p`): uncontrolled by default (`defaultValue`);
- * pass `value` + `onValueChange` to own the loaded count. `loadFinish` is the
- * request; `loadStart` / `loadFail` are adapter lifecycle events.
- */
-export declare const createFeed: (options?: FeedOptions) => Feed;
-export interface FieldOptions {
-  /** Base of every id the field makes (`<id>-control`, `-label`, `-hint`, `-error`). */
-  readonly id?: string | undefined;
-  readonly required?: boolean | undefined;
-  /**
-   * `true` marks the control invalid; a string does too and is the error message
-   * (unless `error` is set). `false` forces valid: an `error` is then not shown,
-   * so a host can pass `touched() && failed()` and keep the message ready.
-   * Left out, the field is invalid exactly when it has an error message.
-   */
-  readonly invalid?: boolean | string | undefined;
-  /** Help text; absent (or empty) means the hint element is hidden and not referenced. */
-  readonly hint?: string | undefined;
-  /** The error message; absent (or empty) means no error element. */
-  readonly error?: string | undefined;
-  /**
-   * Ids of elements the host owns, appended to `aria-describedby` after the
-   * field's own hint and error: a form-level error that belongs to several
-   * controls ("the passwords do not match" names both). One id or a list;
-   * empty strings are dropped, and the attribute is absent when nothing is left.
-   * The host keeps that element rendered, and decides whether it is hidden.
-   */
-  readonly describedby?: string | readonly string[] | undefined;
-}
-/** Spread onto the form control (`input`, `textarea`, `select`, or a custom widget). */
-export interface FieldControlProps {
-  readonly id: string;
-  /** The ids of the hint and the error that are shown, hint first, then the host's `describedby`; absent when there are none. */
-  readonly "aria-describedby": string | undefined;
-  readonly "aria-invalid": "true" | undefined;
-  /** For a control that is not native (a native one has `required`). */
-  readonly "aria-required": "true" | undefined;
-  readonly required: true | undefined;
-}
-export interface FieldLabelProps {
-  readonly id: string;
-  readonly for: string;
-}
-/** Spread onto the hint and the error element; render both, always. */
-export interface FieldMessageProps {
-  readonly id: string;
-  readonly hidden: boolean;
-}
-/** The error element also announces itself: `role="alert"` while it is shown. */
-export interface FieldErrorProps extends FieldMessageProps {
-  readonly role: "alert" | undefined;
-}
-export interface Field {
-  readonly invalid: () => boolean;
-  /** The hint, or `undefined` when there is none. */
-  readonly hint: () => string | undefined;
-  /** The error shown: `undefined` unless the field is invalid and has a message. */
-  readonly error: () => string | undefined;
-  /**
-   * The ids `aria-describedby` lists now: hint, then error (never an id that is
-   * hidden), then the host's `describedby`.
-   */
-  readonly describedIds: () => readonly string[];
-  readonly controlProps: FieldControlProps;
-  readonly labelProps: FieldLabelProps;
-  readonly hintProps: FieldMessageProps;
-  readonly errorProps: FieldErrorProps;
-}
-/**
- * The ARIA contract of a form field: a label, a control, a hint and an error.
- * There is no APG pattern for it (APG has no "form field"; the nearest is the
- * label and description rules of the accessible name computation), so the
- * contract comes from WAI-ARIA 1.2 (`aria-describedby`, `aria-invalid`,
- * `aria-required`) and HTML (`label[for]`, `required`), and from the
- * majority of Base UI Field, react-aria TextField and ariakit FormControl,
- * which list the description and the error message together. It is not checked
- * against a Quint spec; `test/field.browser.test.tsx` is its oracle.
- *
- * Decisions: the error does not replace the hint, both are listed, hint first
- * (the hint is what tells the user how to fix the error); an error implies
- * invalid and `invalid: false` overrides it; a hidden message is never
- * referenced, so `aria-describedby` has no dangling id. The error element is
- * `role="alert"` only while it is shown (a hidden element announces nothing, and
- * one that appears is announced); the hint is never an alert.
+  readonly loadStart: () => void;
+  /** A batch arrived; a request to grow the loaded count. */
+  readonly loadFinish: (count: number) => void;
+  readonly loadFail: () => void;
+  readonly setSizeMode: (mode: "loaded" | "total") => void;
+  readonly setTotalKnown: (known: boolean) => void;
+  readonly feedProps: FeedProps;
+  readonly articleProps: (posinset: number) => FeedArticleProps;
+  readonly beforeProps: FeedSentinelProps;
+  readonly afterProps: FeedSentinelProps;
+}
+/**
+ * APG Feed (https://www.w3.org/WAI/ARIA/apg/patterns/feed/): state plus prop
+ * objects for the feed container, its articles and the two outside focus
+ * sentinels. Focus reaching the last loaded article triggers a load; `aria-busy`
+ * brackets it; Page Up/Down move by article; Control+End/Home leave the feed.
+ * No styling, no elements. Checked against `specs/apg/feed.qnt`.
  *
- * `describedby` lists host-owned ids after the field's own: one refusal that
- * belongs to two controls is one form-level element (with its own `role`), named
- * by both. The field cannot know whether that element is shown: the host
- * passes the id only while it is.
+ * Platform: **library** — focusgroup V2 `feed` is explainer-only, so the load
+ * trigger, busy bracketing and Page Up/Down / Control+End/Home keys are ours.
  *
- * Options are read when an attribute is read: pass getters, never destructure.
+ * Request/commit (map ticket `rt1p`): uncontrolled by default (`defaultValue`);
+ * pass `value` + `onValueChange` to own the loaded count. `loadFinish` is the
+ * request; `loadStart` / `loadFail` are adapter lifecycle events.
  */
-export declare const createField: (options?: FieldOptions) => Field;
+export declare const createFeed: (options?: FeedOptions) => Feed;
 export interface PaginationLabels {
   /** The navigation landmark's name; defaults to "Pagination". */
   readonly nav?: string | undefined;
@@ -2196,6 +2549,107 @@ export interface Hotkeys {
  * browser would otherwise act on (Cmd/Ctrl+S, Cmd/Ctrl+K).
  */
 export declare const createHotkeys: (options?: HotkeysOptions) => Hotkeys;
+/** How a drag turns the knob: the angle around the centre, a straight slide, or whichever the drag starts as. */
+export type KnobGesture = "spin" | "slide" | "both";
+export interface KnobLabels {
+  /** The knob's accessible name (`aria-label`); "Knob" by default. */
+  readonly knob?: string | undefined;
+}
+export interface KnobOptions {
+  readonly min?: number | undefined;
+  readonly max?: number | undefined;
+  readonly step?: number | undefined;
+  /** Controlled: the host owns the value and this is the only thing that changes it. */
+  readonly value?: number | undefined;
+  /** Starting value when uncontrolled (the middle of the range by default). */
+  readonly defaultValue?: number | undefined;
+  /**
+   * `false` (default): clamp at `min` / `max`. `true`: a continuous dial — the
+   * value wraps around (past `max` comes back at `min`), so a full turn of the
+   * skin is a full cycle.
+   */
+  readonly wrap?: boolean | undefined;
+  /** Which drag turns the knob; "both" (default) locks per drag from the first movement. */
+  readonly gesture?: KnobGesture | undefined;
+  readonly labels?: KnobLabels | undefined;
+  /** The spoken value (`aria-valuetext`); `String` by default. */
+  readonly format?: ((value: number) => string) | undefined;
+  /** Base for the generated value region id. */
+  readonly id?: string | undefined;
+  /**
+   * A request to change the value, called when the intent differs from the
+   * current value. Uncontrolled it is accepted; controlled the host may ignore it.
+   */
+  readonly onValueChange?: ((value: number) => void) | undefined;
+}
+/** Spread onto the knob element, the focusable control. */
+export interface KnobProps {
+  readonly role: "slider";
+  readonly tabindex: number;
+  readonly "aria-valuemin": string;
+  readonly "aria-valuemax": string;
+  readonly "aria-valuenow": string;
+  readonly "aria-valuetext": string;
+  readonly "aria-label": string;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+  readonly onPointerDown: (event: PointerEvent) => void;
+  readonly onPointerMove: (event: PointerEvent) => void;
+  readonly onPointerUp: (event: PointerEvent) => void;
+  readonly onPointerCancel: (event: PointerEvent) => void;
+  readonly onWheel: (event: WheelEvent) => void;
+}
+/** Spread onto the live value; render it once, always (hide it visually, never with `hidden`). */
+export interface KnobValueProps {
+  readonly id: string;
+  readonly role: "status";
+  readonly "aria-live": "polite";
+}
+export interface Knob {
+  readonly value: Accessor<number>;
+  /** A request, like a key or a drag; `setValue` never bypasses a controlled `value`. */
+  readonly setValue: (value: number) => void;
+  /**
+   * The fraction of a full turn the skin rotates by for `value`, 0..1 (multiply
+   * by 360 for degrees). Clamped to 0..1, or the wrapped fraction when `wrap`.
+   */
+  readonly percentOf: (value: number) => number;
+  /** A request to move by `delta` value units (a key, a wheel, a host button). */
+  readonly stepBy: (delta: number) => void;
+  readonly knobProps: KnobProps;
+  readonly valueProps: KnobValueProps;
+}
+/**
+ * A virtual knob after GarageBand's (https://jherrm.github.io/knobs/): one
+ * control turned three ways — spun around its centre, or slid vertically or
+ * horizontally, one gesture locked per drag. Plain Solid signals, no elements,
+ * no styling. **No ARIA role exists for a dial**, so the knob is a `role=slider`
+ * with `aria-valuenow` / `aria-valuetext`; the value the host renders in
+ * `valueProps` is the live announcement (`role=status`), and a numeric field
+ * must sit next to the dial, because a dial is never the only control.
+ *
+ * Request/commit (map ticket `rt1p`): uncontrolled by default (`defaultValue`);
+ * pass `value` + `onValueChange` to own the value. A key, a wheel, a drag and
+ * `setValue`/`stepBy` are requests the host may ignore.
+ *
+ * Gestures (`gesture`, default "both"), decided once on the first meaningful
+ * movement so a drag never switches modes:
+ * - a movement that stays on one axis (the other axis under `SLIDE_VARIANCE` of
+ *   it) locks a slide — the reference's "slide in a straight line";
+ * - any other movement is a turn around the centre: the angle the pointer
+ *   covers is the value, and the farther from the centre the finer it is;
+ * - `gesture: "spin"` / `"slide"` disable the other.
+ *
+ * A vertical slide turns the knob the way the grabbed side would turn a real
+ * one: down on the right half is clockwise (up in value), down on the left half
+ * counter-clockwise. A horizontal slide uses the same left/right side (the
+ * reference picks top/bottom for this one; one rule for both is simpler to
+ * learn). `wrap` makes the dial continuous instead of clamped.
+ *
+ * ponytail: no momentum/inertia and no `disabled` — the reference has a
+ * deceleration tail, and no host here has asked for one; add inertia in the
+ * host's rAF loop if a look needs it.
+ */
+export declare const createKnob: (options?: KnobOptions) => Knob;
 export interface LinkOptions {
   readonly href?: string | undefined;
   /** Render a native `<a href>` (the default when `href` is set). */
@@ -2351,8 +2805,12 @@ export declare const createListbox: (options: ListboxOptions) => Listbox;
  * dismiss and Esc; `focusgroup` gives the menubar's roving tabindex. The
  * library owns the menu keys, typeahead, submenus and checkable state.
  *
- * ponytail: uncontrolled; add a `value`/`onValueChange` host pair when a
- * consumer owns open/checked state.
+ * Request/commit (map ticket `rt1p`): the open state, and the checked items of
+ * the checkable variants, are controllable. Uncontrolled by default
+ * (`defaultOpen` / `defaultValue`); pass `open` / `value` (+ `onOpenChange` /
+ * `onCheckedValueChange`) to own them. Every opening and closing intent — the
+ * trigger's click and keys, Escape, an item's activation, Tab, and the
+ * programmatic `openMenu` / `closeMenu` — is a request the host may ignore.
  */
 export type MenuItemKind = "item" | "checkbox" | "radio";
 export interface MenuItemInput {
@@ -2365,6 +2823,9 @@ export type MenuVariant = "plain" | "checkbox-items" | "radio-items" | "mixed";
 export interface MenuOptions {
   readonly items: ReadonlyArray<string | MenuItemInput>;
   readonly variant?: MenuVariant;
+  /** Controlled: the host owns the open state and this is the only thing that opens or closes it. */
+  readonly open?: boolean | undefined;
+  /** Uncontrolled starting state; ignored while `open` is set. */
   readonly defaultOpen?: boolean;
   /**
    * `outside` (menu button): focus can sit outside the widget, so keys are
@@ -2380,7 +2841,7 @@ export interface MenuOptions {
    * Controlled: the host owns the checked items. Packed as
    * `checkboxItem0 * 5 + radioChoice` (1-based), matching `menu-checkable.qnt`'s
    * `checked(wrap, choice)`; pass `undefined` for uncontrolled. The open state
-   * stays uncontrolled.
+   * has its own `open` pair.
    */
   readonly value?: number | undefined;
   /** The uncontrolled packed checked state at mount. */
@@ -2390,6 +2851,10 @@ export interface MenuOptions {
   /** Item indices disabled (focusable, not activatable). */
   readonly disabled?: ReadonlyArray<number>;
   readonly id?: string;
+  /**
+   * A request to change the open state, called when the intent differs from the
+   * current one. Uncontrolled it is accepted; controlled the host may ignore it.
+   */
   readonly onOpenChange?: (open: boolean) => void;
   readonly onItemClick?: (index: number) => void;
   readonly onCheckedChange?: (checked: boolean, index: number) => void;
@@ -2854,6 +3319,11 @@ export interface SliderOptions {
   readonly defaultValue?: number;
   readonly orientation?: SliderOrientation;
   readonly direction?: SliderDirection;
+  /**
+   * aria-disabled: the thumb stays the tab stop (the APG pattern's focus
+   * contract) but a key or a rail press changes nothing.
+   */
+  readonly disabled?: boolean;
   /** Base for the generated thumb id. */
   readonly id?: string;
   /**
@@ -2870,6 +3340,7 @@ export interface SliderThumbProps {
   readonly "aria-valuemax": string;
   readonly "aria-valuetext": string;
   readonly "aria-orientation": SliderOrientation;
+  readonly "aria-disabled": "true" | undefined;
   readonly tabindex: number;
   readonly onFocus: () => void;
   readonly onBlur: () => void;
@@ -2907,6 +3378,11 @@ export interface Slider {
  * pass `value` + `onValueChange` to own the value. A key or rail press is a
  * request the host may ignore.
  *
+ * `disabled` is a widget-level extension of the pattern (the spec lists it
+ * under its deliberate omissions): the thumb keeps its tab stop and announces
+ * `aria-disabled`, and every key and rail press is dropped before it becomes a
+ * request.
+ *
  * ponytail: dragging (pointer capture/move) is not modelled — the spec
  * deliberately only fixes a discrete rail press.
  */
@@ -2991,6 +3467,11 @@ export interface SpinbuttonOptions {
   readonly defaultValue?: number;
   /** Wrap around at the bounds instead of clamping. */
   readonly wrap?: boolean;
+  /**
+   * aria-disabled plus the native `disabled` on the text field: keys, typing
+   * and both steppers change nothing, and both steppers announce `aria-disabled`.
+   */
+  readonly disabled?: boolean;
   /** Base for the generated input / button ids. */
   readonly id?: string;
   /**
@@ -3007,6 +3488,8 @@ export interface SpinbuttonInputProps {
   readonly "aria-valuemax": string;
   readonly "aria-valuetext": string;
   readonly "aria-invalid": "true" | undefined;
+  readonly "aria-disabled": "true" | undefined;
+  readonly disabled: boolean;
   readonly tabindex: number;
   readonly value: string;
   readonly onFocus: () => void;
@@ -3062,41 +3545,16 @@ export interface Spinbutton {
  * stepper buttons, Enter and blur are requests the host may ignore; typing and
  * Escape change no committed value.
  *
+ * `disabled` is a widget-level extension of the pattern (the spec models the
+ * steppers' bound only, and lists this under its deliberate omissions): the
+ * field announces `aria-disabled` and carries the native `disabled`, every key,
+ * typed draft and both steppers are dropped before they become a request, and
+ * neither stepper offers itself.
+ *
  * ponytail: commit/revert on Enter/blur/Escape is the common convention, not
  * APG text.
  */
 export declare const createSpinbutton: (options?: SpinbuttonOptions) => Spinbutton;
-export interface StatusOptions {
-  /** Rendered on `statusProps`; generated when absent. */
-  readonly id?: string | undefined;
-}
-/** Spread onto the `role=status` live region. Render it once, always. */
-export interface StatusProps {
-  readonly id: string;
-  readonly role: "status";
-  readonly "aria-live": "polite";
-  readonly "aria-atomic": "true";
-}
-export interface Status {
-  /** The text currently shown, or `undefined` before the first `show`. */
-  readonly message: Accessor<string | undefined>;
-  /** Writes the message, replacing the previous one; nothing is queued. */
-  readonly show: (text: string) => void;
-  readonly clear: () => void;
-  readonly statusProps: StatusProps;
-}
-/**
- * APG Alert's polite sibling: one `role=status` live region whose text the host
- * replaces ("Link copied", "Saved"). It is not a queue: a second message shows
- * in place of the first, so a burst reads as the last state, not as N alerts.
- * The region is rendered once and stays mounted, which is what makes a change
- * of its text announced.
- *
- * A status is never for errors: an error that needs attention now is
- * `createAlert` (`role=alert`, assertive), and a message with a title, a
- * description and a timeout is `createToast`.
- */
-export declare const createStatus: (options?: StatusOptions) => Status;
 export interface SwitchOptions {
   /** Controlled: the host owns the state and this is the only thing that changes it. */
   readonly value?: boolean | undefined;
@@ -3327,86 +3785,6 @@ export interface Table {
  * destructured snapshot. `id` is captured once: it is the base of the caption id.
  */
 export declare const createTable: (options: TableOptions) => Table;
-/** The HTML `autocomplete` tokens worth naming; the attribute also takes an arbitrary token. */
-export type AutoCompleteToken = "off" | "on" | "name" | "given-name" | "family-name" | "username" | "email" | "tel" | "url" | "organization" | "street-address" | "postal-code" | "current-password" | "new-password" | "one-time-code" | "nickname";
-export interface TextInputOptions extends FieldOptions {
-  readonly type?: "text" | "email" | "tel" | "url" | "search" | "password" | undefined;
-  /** The HTML token list: the browser's own autofill is the accessible path. */
-  readonly autoComplete?: AutoCompleteToken | undefined;
-  readonly spellCheck?: boolean | undefined;
-  readonly autoCapitalize?: "none" | "sentences" | "words" | "characters" | undefined;
-  readonly inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
-  readonly maxLength?: number | undefined;
-  readonly readOnly?: boolean | undefined;
-  readonly disabled?: boolean | undefined;
-  readonly name?: string | undefined;
-  readonly dir?: "ltr" | "rtl" | "auto" | undefined;
-  readonly placeholder?: string | undefined;
-  /** Change and input both land here; the host decides what a keystroke means. */
-  readonly onValueChange?: ((value: string) => void) | undefined;
-}
-export interface TextAreaOptions extends TextInputOptions {
-  readonly rows?: number | undefined;
-  readonly wrap?: "soft" | "hard" | "off" | undefined;
-  readonly resize?: "none" | "vertical" | "horizontal" | "both" | undefined;
-}
-export interface TextControlProps {
-  readonly id: string;
-  readonly "aria-describedby": string | undefined;
-  readonly "aria-invalid": "true" | undefined;
-  readonly "aria-required": "true" | undefined;
-  readonly required: true | undefined;
-  readonly type: TextInputOptions["type"];
-  readonly autoComplete: AutoCompleteToken | undefined;
-  readonly spellcheck: "true" | "false" | undefined;
-  readonly autocapitalize: TextInputOptions["autoCapitalize"];
-  readonly inputmode: TextInputOptions["inputMode"];
-  readonly maxlength: number | undefined;
-  readonly readOnly: true | undefined;
-  readonly disabled: true | undefined;
-  readonly name: string | undefined;
-  readonly dir: "ltr" | "rtl" | "auto" | undefined;
-  readonly placeholder: string | undefined;
-  readonly onInput: (event: {
-    currentTarget: {
-      value: string;
-    };
-  }) => void;
-}
-export interface TextAreaControlProps extends TextControlProps {
-  readonly rows: number | undefined;
-  readonly wrap: TextAreaOptions["wrap"];
-  readonly style: {
-    readonly resize: "none" | "vertical" | "horizontal" | "both";
-  } | undefined;
-}
-/** The field and the control, one object: every prop the element needs. */
-export interface TextInput extends Field {
-  readonly controlProps: TextControlProps;
-}
-export interface TextArea extends Field {
-  readonly controlProps: TextAreaControlProps;
-}
-/**
- * A text input with the field contract attached: label, hint, error (announced),
- * `aria-describedby` and `aria-invalid` come from `createField`; this adds the
- * props a host forgets — autofill tokens, spellcheck, inputmode, maxlength, the
- * disabled/readOnly pair. Platform: native (`input` is its own APG-equivalent;
- * no primitive re-implements text editing, which is why there is no key
- * handling here).
- *
- * Both `required` and `aria-required` are emitted: the native attribute is what
- * the browser enforces, the ARIA one is what a custom widget reading the same
- * props needs. A host that validates itself passes `noValidate` on the form
- * rather than dropping the attribute.
- */
-export declare const createTextInput: (options?: TextInputOptions) => TextInput;
-/**
- * The same contract for a textarea, plus rows, wrap and resize. `resize` is a
- * style because CSS has no attribute for it; `none` is the value a layout that
- * owns its own height wants.
- */
-export declare const createTextArea: (options?: TextAreaOptions) => TextArea;
 export type TabsOrientation = "horizontal" | "vertical";
 export type TabsActivation = "automatic" | "manual";
 /**
@@ -3433,6 +3811,26 @@ export interface TabsOptions {
    * current value. Uncontrolled it is accepted; controlled the host may ignore it.
    */
   readonly onValueChange?: (index: number) => void;
+  /**
+   * Close buttons and the Delete key (default false): the host renders
+   * `closeProps` and removes the tab from `onClose`. The last tab is never
+   * asked to close.
+   */
+  readonly closable?: boolean | undefined;
+  /**
+   * Inline rename (default false): a double click on a tab starts it, Enter /
+   * blur commit and Escape reverts; the host renames from `onRename`.
+   */
+  readonly renamable?: boolean | undefined;
+  /**
+   * A tab's label: the close / rename button names and the starting draft of a
+   * rename, read lazily (a getter is fine) so a rename follows.
+   */
+  readonly label?: ((index: number) => string | undefined) | undefined;
+  /** A request to remove a tab; the primitive does not own the list. */
+  readonly onClose?: ((index: number) => void) | undefined;
+  /** A request to rename a tab with a non-empty label. */
+  readonly onRename?: ((index: number, label: string) => void) | undefined;
 }
 /** Spread onto the element with `role=tab` (a native `<button>`). */
 export interface TabProps {
@@ -3460,21 +3858,63 @@ export interface TabpanelProps {
   readonly tabindex: 0 | undefined;
   readonly hidden: boolean;
 }
+/**
+ * Spread onto the tab's close button. `tabindex=-1` keeps it out of the
+ * tablist's tab order (a tablist's stops are its tabs); the Delete key is the
+ * keyboard path.
+ */
+export interface TabCloseProps {
+  readonly "aria-label": string;
+  readonly tabindex: -1;
+  readonly onClick: () => void;
+}
+/** Spread onto the inline `<input>` a renaming tab renders instead of its label. */
+export interface TabRenameInputProps {
+  readonly type: "text";
+  readonly value: string;
+  readonly "aria-label": string;
+  readonly onInput: (event: InputEvent) => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+  readonly onBlur: () => void;
+}
+/** The rename part of one tab: put `onDblClick` on the tab, `inputProps` in it. */
+export interface TabRenameProps {
+  readonly onDblClick: () => void;
+  /** Whether this tab is the one being renamed. */
+  readonly editing: Accessor<boolean>;
+  /** Start renaming `index` (e.g. a tab the host has just added). */
+  readonly begin: (index: number) => void;
+  /** Commit `label` to the tab being edited; an empty label cancels. */
+  readonly commit: (label: string) => void;
+  readonly cancel: () => void;
+  readonly inputProps: TabRenameInputProps;
+}
 export interface Tabs {
+  /** The tab count; read from `items` on every read, so a host that shrinks its list stays in step. */
   readonly items: number;
   readonly selected: Accessor<number>;
   /** Tab holding (or last holding) DOM focus; -1 when focus is outside. */
   readonly focused: Accessor<number>;
+  /** The tab being renamed inline, `null` when none. */
+  readonly editing: Accessor<number | null>;
   /** Programmatic selection request; ignores disabled tabs. */
   readonly select: (index: number) => void;
   /** Programmatic selection request (may point at a disabled tab, like base-ui). */
   readonly setSelected: (index: number) => void;
   /** Programmatic focus (does not select). */
   readonly focusTab: (index: number) => void;
+  /**
+   * The tab that takes focus once `onClose(index)`'s removal lands: the tab
+   * that slid into `index`, or the previous one when the last tab closed. Call
+   * it before the host removes the tab.
+   */
+  readonly focusAfterClose: (index: number) => number;
   readonly keyDown: (key: string) => void;
   readonly tablistProps: TablistProps;
   readonly tabProps: (index: number) => TabProps;
   readonly tabpanelProps: (index: number) => TabpanelProps;
+  readonly closeProps: (index: number) => TabCloseProps;
+  readonly renameProps: (index: number) => TabRenameProps;
 }
 /**
  * APG Tabs (https://www.w3.org/WAI/ARIA/apg/patterns/tabs/): state plus prop
@@ -3489,6 +3929,14 @@ export interface Tabs {
  * Request/commit (map ticket `rt1p`): uncontrolled by default
  * (`defaultSelected`); pass `value` + `onValueChange` to own the selection.
  * Programmatic methods (`select`, `setSelected`, `keyDown`) are requests too.
+ *
+ * Close and rename are an **extension** (bean `cssints-gdv2`): the APG spec
+ * models a `deletable` flavour but neither a callback nor a rename, and this
+ * primitive owns no list. `closable` / `renamable` turn on the props; `onClose`
+ * / `onRename` ask the host, which removes or renames. Focus after a close goes
+ * to the tab that slid into the closed one's place, or to the previous tab when
+ * the last one closed; closing the last remaining tab is refused, as the spec
+ * refuses an empty tablist.
  */
 export declare const createTabs: (options?: TabsOptions) => Tabs;
 /**
@@ -3506,10 +3954,16 @@ export declare const createTabs: (options?: TabsOptions) => Tabs;
  * may ignore. The zoom window (`viewStart`/`viewEnd`) is not the controlled
  * value and stays uncontrolled.
  *
- * ponytail: the fixed 5-span tree is a demo fixture; a real consumer owns the
- * span list (layout is theirs). Roving tabindex only — a consumer must call
- * `focus()` on the row whose `tabindex` is 0 after arrow navigation (the tests'
- * fixture does this with an effect).
+ * The fixed 5-span tree is the demo fixture (the differential walk's oracle).
+ * A real consumer passes `rows`: span data on one shared axis, laid out by
+ * `barProps` as percentages of the rows' extent. No roles are borrowed from
+ * APG: a trace waterfall is a list of spans in time, so the rows mode is
+ * `role="list"` / `role="listitem"` (with `aria-level` for the depth) and the
+ * current row is `aria-current="true"`, which every element may carry.
+ *
+ * Roving tabindex only — a consumer must call `focus()` on the row whose
+ * `tabindex` is 0 after arrow navigation (the tests' fixture does this with an
+ * effect; the rows mode's span rows are reached by tabbing to the current one).
  */
 /** One span row: a fraction of the parent span on a shared 0..1 axis. */
 export interface TimelineRow {
@@ -3592,12 +4046,90 @@ export interface Timeline {
   readonly rowProps: (id: number) => TimelineRowProps;
   readonly rulerProps: TimelineRulerProps;
 }
-/**
- * Headless span timeline on Solid 2. The exported accessors are signals; the
- * prop objects are getter-backed, so spreading them keeps every attribute
- * reactive.
- */
-export declare const createTimeline: (options?: TimelineOptions) => Timeline;
+/** One span of a real trace: a point on a shared axis, labelled, at a depth. */
+export interface TimelineSpan {
+  readonly id: string;
+  readonly label: string;
+  /** Offset on the axis, in the axis' unit; `end` is the same axis, not a duration. */
+  readonly start: number;
+  readonly end: number;
+  /** Nesting level, 0 for a root span. */
+  readonly depth?: number;
+  readonly status?: "ok" | "error" | "unset";
+}
+export interface TimelineAxis {
+  /** The unit the numbers are in; the ruler labels its ticks with it. */
+  readonly unit?: "ms" | "us" | "s";
+}
+/** The rows mode: real span data, read lazily like every other option. */
+export interface TimelineRowsOptions {
+  readonly rows: ReadonlyArray<TimelineSpan>;
+  readonly axis?: TimelineAxis | undefined;
+  /** Controlled: the host owns the selection. */
+  readonly selected?: string | undefined;
+  /** A request to change the selection the host may ignore. */
+  readonly onSelect?: ((id: string) => void) | undefined;
+}
+export interface TimelineTick {
+  readonly value: number;
+  readonly left: number;
+  readonly label: string;
+}
+export interface TimelineListProps {
+  readonly role: "list";
+  readonly "aria-label": string;
+}
+export interface TimelineSpanRowProps {
+  readonly role: "listitem";
+  /** `depth + 1`: the nesting a flat list cannot show in the DOM. */
+  readonly "aria-level": number;
+  readonly "aria-current": "true" | undefined;
+  /** A styling hook: the status the span ended with. */
+  readonly "data-status": "ok" | "error" | "unset";
+  readonly tabindex: number;
+  readonly onClick: () => void;
+  readonly onKeyDown: (event: KeyboardEvent) => void;
+}
+export interface TimelineBarProps {
+  readonly "aria-hidden": "true";
+  /** `left` / `width` are percentages of the extent; `--depth` is the row's depth. */
+  readonly style: {
+    readonly left: string;
+    readonly width: string;
+    readonly "--depth": string;
+  };
+}
+export interface TimelineLabelProps {
+  /** `--depth`, so the host indents the label (`padding-inline-start: calc(var(--depth) * 1rem)`) instead of nesting it. */
+  readonly style: {
+    readonly "--depth": string;
+  };
+}
+export interface TimelineRulerRowsProps {
+  readonly role: "presentation";
+  readonly "aria-hidden": "true";
+  /** Ticks of a nice step across the extent; render them as children. */
+  readonly ticks: ReadonlyArray<TimelineTick>;
+}
+export interface TimelineRows {
+  /** `{ start, end }` across the rows; `{ 0, 0 }` when there are none. */
+  readonly extent: () => {
+    readonly start: number;
+    readonly end: number;
+  };
+  readonly depthOf: (id: string) => number;
+  readonly listProps: TimelineListProps;
+  readonly rowProps: (id: string) => TimelineSpanRowProps;
+  readonly barProps: (id: string) => TimelineBarProps;
+  readonly labelProps: (id: string) => TimelineLabelProps;
+  readonly rulerProps: TimelineRulerRowsProps;
+  /** Programmatic selection request; a controlled host may ignore it. */
+  readonly select: (id: string) => void;
+  readonly selectedId: Accessor<string | undefined>;
+}
+/** The demo five-span tree (`rows` absent) or real span data (`rows` given). */
+export declare function createTimeline(options: TimelineRowsOptions): TimelineRows;
+export declare function createTimeline(options?: TimelineOptions): Timeline;
 /** A toast's urgency; `error` is the only tone that announces assertively. */
 export type ToastTone = "info" | "success" | "error";
 export interface ToastOptions {