@gjsify/adwaita-core 0.36.0 → 0.38.0

package/lib/types/view-switcher.d.ts

@@ -1,24 +1,17 @@
 import { stripMnemonic } from './glib.js';
 import type { AdwViewStackPageInfo } from './view-stack.js';
 /**
- * The "nothing is selected" sentinel, standing in for
- * `GTK_INVALID_LIST_POSITION` (adw-inline-view-switcher.c:366, :441).
- *
- * Returned by {@link toggleIndexForPage} / {@link pageIndexForToggle} when the
- * two index spaces have no counterpart for each other — a hidden page has no
- * toggle at all, which is a state `ToggleGroupState`'s always-non-negative
- * `selected` cannot express.
+ * The "nothing is selected" sentinel, standing in for `GTK_INVALID_LIST_POSITION`.
+ * Returned by {@link toggleIndexForPage} / {@link pageIndexForToggle} when the two index
+ * spaces have no counterpart for each other — a hidden page has no toggle at all, a state
+ * `ToggleGroupState`'s always-non-negative `selected` cannot express.
  */
 export declare const VIEW_SWITCHER_NO_SELECTION = -1;
-/**
- * The icon substituted for a NULL or empty icon name
- * (adw-view-switcher-button.c:347, :399-405; adw-inline-view-switcher.c:131-145).
- */
+/** The icon substituted for a NULL or empty icon name. */
 export declare const VIEW_SWITCHER_FALLBACK_ICON = "image-missing";
 /**
- * `TIMEOUT_EXPAND` — how long a drag has to dwell over a non-active button
- * before it switches to it (adw-view-switcher-button.c:14,
- * adw-inline-view-switcher.c:80). Defined identically in both C files.
+ * `TIMEOUT_EXPAND` — how long a drag must dwell over a non-active button before it
+ * switches to it. Defined identically in both C files.
  */
 export declare const VIEW_SWITCHER_DRAG_SWITCH_DELAY = 500;
 /** The largest badge `AdwIndicatorBin` prints; anything above collapses to `999+`. */
@@ -26,49 +19,41 @@ export declare const VIEW_SWITCHER_BADGE_LIMIT = 999;
 /** `AdwViewSwitcherPolicy` — which button layout the switcher forces. */
 export type AdwViewSwitcherPolicy = 'narrow' | 'wide';
 /**
- * Every policy, in enum order. Doubles as the style-class list: libadwaita adds
- * the current policy's class and removes the other (adw-view-switcher.c:539-545),
- * so a renderer toggles each entry against the current value rather than
- * hard-coding an add/remove pair.
+ * Every policy, in enum order. Doubles as the style-class list: libadwaita adds the
+ * current policy's class and removes the other, so a renderer toggles each entry against
+ * the current value rather than hard-coding an add/remove pair.
  */
 export declare const VIEW_SWITCHER_POLICIES: readonly AdwViewSwitcherPolicy[];
 /** `AdwInlineViewSwitcherDisplayMode` — what the inline switcher's toggles show. */
 export type AdwInlineViewSwitcherDisplayMode = 'labels' | 'icons' | 'both';
 /**
- * Every display mode, in enum order — and the toggle-group style classes
- * (adw-inline-view-switcher.c:826-850), same toggle-against-current pattern as
- * {@link VIEW_SWITCHER_POLICIES}.
+ * Every display mode, in enum order — and the toggle-group style classes, same
+ * toggle-against-current pattern as {@link VIEW_SWITCHER_POLICIES}.
  */
 export declare const INLINE_VIEW_SWITCHER_DISPLAY_MODES: readonly AdwInlineViewSwitcherDisplayMode[];
 /**
- * Whether `value` is a policy libadwaita would accept.
- *
- * The C setter is guarded by the enum's own type (`g_value_get_enum`), and the
- * browser port instead coerced anything unrecognised to a default — see
- * {@link isInlineViewSwitcherDisplayMode} for why that is not the same thing.
+ * Whether `value` is a policy libadwaita would accept. The C setter is guarded by the
+ * enum's own type (`g_value_get_enum`); coercing an unrecognised value to a default is
+ * NOT the same thing — see {@link isInlineViewSwitcherDisplayMode}.
  */
 export declare function isViewSwitcherPolicy(value: unknown): value is AdwViewSwitcherPolicy;
 /**
  * Whether `value` is a display mode libadwaita would accept.
- *
  * `adw_inline_view_switcher_set_display_mode` opens with
- * `g_return_if_fail (mode <= ADW_INLINE_VIEW_SWITCHER_BOTH)`
- * (adw-inline-view-switcher.c:819), which REJECTS the call and leaves the
- * current mode alone. The browser port's `includes(raw) ? raw : 'both'` replaced
- * the current mode with `'both'` instead, so a typo in one attribute silently
- * changed what every toggle displayed.
+ * `g_return_if_fail (mode <= ADW_INLINE_VIEW_SWITCHER_BOTH)`, which REJECTS the call and
+ * leaves the current mode alone — substituting a default instead would let a typo in one
+ * attribute silently change what every toggle displays.
  */
 export declare function isInlineViewSwitcherDisplayMode(value: unknown): value is AdwInlineViewSwitcherDisplayMode;
 /**
- * The page record every switcher flavour reads — `AdwViewStackPage`'s properties
- * with their C defaults (adw-view-stack.c:373-436).
+ * The page record every switcher flavour reads — `AdwViewStackPage`'s properties with
+ * their C defaults.
  *
  * `null` vs `''` is LOAD-BEARING and is why this record exists next to
- * {@link AdwViewStackPageInfo} rather than being replaced by it: the
- * button-visibility rule tests `title != NULL`, and an empty title is not NULL.
- * Wave 1's stack page model resolves an absent title to the page NAME (a
- * deliberate, documented deviation), so a page's "had no title at all" state
- * only survives where the switcher owns its own pages.
+ * {@link AdwViewStackPageInfo} rather than being replaced by it: the button-visibility
+ * rule tests `title != NULL` and an empty title is not NULL, while the stack page model
+ * resolves an absent title to the page NAME. So "had no title at all" only survives where
+ * the switcher owns its own pages.
  */
 export interface AdwViewSwitcherPage {
     /** Stable id, matching `AdwViewStackPage`'s name. */
@@ -92,76 +77,52 @@ export interface AdwViewSwitcherPageInit extends Partial<AdwViewSwitcherPage> {
     name: string;
 }
 /**
- * Normalize a partial page into the full record with the C defaults applied, so
- * a renderer that only knows `{ name, title }` gets exactly the same derivations
- * as one that knows badges.
- *
- * `undefined` collapses to the C default; an explicit `null` title or icon name
- * stays `null`. The badge is normalized to a non-negative integer because
- * `badge-number` is a `guint` (adw-view-stack.c:420-423) and every derivation
- * below assumes it.
+ * Normalize a partial page into the full record with the C defaults applied, so a renderer
+ * that only knows `{ name, title }` gets the same derivations as one that knows badges.
+ * `undefined` collapses to the C default, an explicit `null` title or icon name stays
+ * `null`, and the badge becomes a non-negative integer because `badge-number` is a `guint`.
  */
 export declare function createViewSwitcherPage(init: AdwViewSwitcherPageInit): AdwViewSwitcherPage;
 /**
- * Project a wave-1 stack page descriptor onto a switcher page, for a switcher
- * BOUND to an `Adw.ViewStack` rather than owning its own pages.
- *
- * One fidelity note remains: `AdwViewStackPageInfo.title` is already resolved
- * against the page name, so it is never `null` and the button-visibility rule
- * reduces to the `visible` flag.
- *
- * The second one is gone. This used to say the stack page carried none of
- * `badge-number`, `needs-attention` or `use-underline`, "so a bound switcher
- * derives an empty badge and no description" — which made a switcher bound to a
- * stack STRUCTURALLY unable to show a badge, and both `ViewSwitcherBar`s go
- * through here. The stack page carries all three now.
+ * Project a stack page descriptor onto a switcher page, for a switcher BOUND to an
+ * `Adw.ViewStack` rather than owning its own pages. Fidelity note:
+ * `AdwViewStackPageInfo.title` is already resolved against the page name, so it is never
+ * `null` and the button-visibility rule reduces to the `visible` flag.
  */
 export declare function viewSwitcherPageFromStackPage(page: AdwViewStackPageInfo): AdwViewSwitcherPage;
 /** {@link viewSwitcherPageFromStackPage} over a whole page list. */
 export declare function viewSwitcherPagesFromStack(pages: readonly AdwViewStackPageInfo[]): AdwViewSwitcherPage[];
 /**
- * `update_button`'s visibility rule (adw-view-switcher.c:178):
- * `visible && (title != NULL || icon_name != NULL)`.
- *
- * The empty string is NOT NULL, so `title: ''` still yields a button — the
- * opposite of what both ports did, which was to keep the button and hide only
- * its label. `undefined` is read as absent, i.e. as C's NULL.
+ * `update_button`'s visibility rule: `visible && (title != NULL || icon_name != NULL)`.
+ * The empty string is NOT NULL, so `title: ''` still yields a button; `undefined` is read
+ * as absent, i.e. as C's NULL.
  */
 export declare function isViewSwitcherButtonVisible(page: Pick<AdwViewSwitcherPage, 'visible' | 'title' | 'iconName'>): boolean;
 /**
- * The icon a switcher actually renders: a NULL or EMPTY name becomes
- * `image-missing` (adw-view-switcher-button.c:399-405,
- * adw-inline-view-switcher.c:137-142 — `icon_name && *icon_name` fails on `''`).
- *
- * Never returns `''`, so a renderer has an icon to paint in every mode where the
- * C widget creates a `GtkImage` at all. Both ports instead omitted the icon
- * node, which is why an icon-only toggle for a page without an icon rendered as
- * a blank box.
+ * The icon a switcher actually renders: a NULL or EMPTY name becomes `image-missing` (C's
+ * `icon_name && *icon_name` fails on `''`). Never returns `''`, so a renderer has an icon
+ * to paint in every mode where the C widget creates a `GtkImage` at all — otherwise an
+ * icon-only toggle for a page without an icon renders as a blank box.
  */
 export declare function viewSwitcherIconName(iconName: string | null | undefined): string;
 /**
- * The text a switcher paints for a page: `''` for a NULL title, otherwise the
- * title with its mnemonic stripped when `use-underline` is set.
- *
- * `update_button` binds `title` onto the button's label together with
- * `use-underline` (adw-view-switcher.c:170-176), and the template label carries
- * `use-underline` too (adw-view-switcher-button.ui) — so GTK DISPLAYS `_Files`
- * as `Files` with an underlined F. A renderer with no accelerator layer displays
- * the same text; keeping the underscore would render a literal one, which is
- * what the browser port did in the inline switcher's tooltip.
+ * The text a switcher paints for a page: `''` for a NULL title, otherwise the title with
+ * its mnemonic stripped when `use-underline` is set. GTK DISPLAYS `_Files` as `Files` with
+ * an underlined F (the template label carries `use-underline` too), so a renderer with no
+ * accelerator layer must display the same text — keeping the underscore renders a literal
+ * one.
  */
 export declare function viewSwitcherLabel(page: Pick<AdwViewSwitcherPage, 'title' | 'useUnderline'>): string;
 /**
- * `get_badge_label` (adw-indicator-bin.c:58-68): `''` for 0, `999+` above 999,
- * the decimal otherwise. 999 itself prints, because the test is `> 999`.
+ * `get_badge_label`: `''` for 0, `999+` above 999, the decimal otherwise. 999 itself
+ * prints, because the test is `> 999`.
  */
 export declare function viewSwitcherBadgeLabel(badgeNumber: number): string;
 /**
- * The message catalogue {@link viewSwitcherIndicatorDescription} composes, so the
- * core needs no gettext dependency while the composition ORDER stays pinned.
- *
- * C reads these through `C_("view switcher button badge", …)`; a renderer with a
- * translation layer passes its own catalogue.
+ * The message catalogue {@link viewSwitcherIndicatorDescription} composes, so the core
+ * needs no gettext dependency while the composition ORDER stays pinned. C reads these
+ * through `C_("view switcher button badge", …)`; a renderer with a translation layer
+ * passes its own catalogue.
  */
 export interface IndicatorDescriptionStrings {
     /** `needs-attention` clause — C's "Attention requested." */
@@ -171,49 +132,36 @@ export interface IndicatorDescriptionStrings {
     /** Badge clause for a printable count — C's "Has a badge: %u." */
     badge: (badgeNumber: number) => string;
 }
-/** The English source strings from adw-indicator-bin.c:77-92. */
+/** The English source strings from `adw-indicator-bin.c`. */
 export declare const DEFAULT_INDICATOR_DESCRIPTION_STRINGS: IndicatorDescriptionStrings;
 /**
- * `update_description` (adw-indicator-bin.c:70-113) — the screen-reader
- * description bound onto the switcher button (adw-view-switcher-button.c:98-113)
- * or the inline toggle (adw-inline-view-switcher.c:267).
- *
- * The BADGE clause comes first when both apply: the format string is
- * `"%s %s", badge_description, needs_attention_description` (:96). `''` when
- * neither applies — C stores the empty string there, not NULL, and the button
- * then RESETS the accessible property rather than setting it.
+ * `update_description` — the screen-reader description bound onto the switcher button or
+ * the inline toggle. The BADGE clause comes first when both apply (`"%s %s",
+ * badge_description, needs_attention_description`), and `''` when neither applies: C
+ * stores the empty string there, not NULL, and the button then RESETS the accessible
+ * property rather than setting it.
  */
 export declare function viewSwitcherIndicatorDescription(needsAttention: boolean, badgeNumber: number, strings?: IndicatorDescriptionStrings): string;
 /**
- * `update_tooltip` (adw-inline-view-switcher.c:163-192): the empty string in
- * every display mode except `icons`, where it is the title with the mnemonic
- * stripped when `use-underline` is set.
- *
- * Returns PLAIN text — see {@link stripMnemonic} on why the C markup escape does
- * not belong in a port. A NULL title yields `''`: C would hand NULL to
- * `g_markup_escape_text`, which every page libadwaita renders avoids by always
- * having a title.
+ * `update_tooltip`: the empty string in every display mode except `icons`, where it is
+ * the title with the mnemonic stripped when `use-underline` is set. Returns PLAIN text —
+ * see {@link stripMnemonic} on why the C markup escape does not belong in a port. A NULL
+ * title yields `''`, a case C avoids by every rendered page having a title.
  */
 export declare function inlineToggleTooltip(page: Pick<AdwViewSwitcherPage, 'title' | 'useUnderline'>, displayMode: AdwInlineViewSwitcherDisplayMode): string;
 /**
- * `update_bar_revealed` (adw-view-switcher-bar.c:104-126): the bar is revealed
- * only when `reveal` is set AND more than one page is VISIBLE.
- *
- * When `reveal` is false the C loop never runs, so the count stays 0 — the two
- * clauses are not independent and a renderer must not reorder them into
- * `visibleCount > 1 || reveal`. Absent from both ports, which is why a bar bound
- * to a one-page stack showed an empty strip libadwaita keeps collapsed.
- *
- * Takes the minimal shape so a caller can pass either
- * {@link AdwViewSwitcherPage}s or wave-1 {@link AdwViewStackPageInfo}s.
+ * `update_bar_revealed`: the bar is revealed only when `reveal` is set AND more than one
+ * page is VISIBLE. When `reveal` is false the C loop never runs, so the count stays 0 —
+ * the clauses are not independent and must not be reordered into `visibleCount > 1 ||
+ * reveal`. Takes the minimal shape so a caller can pass either
+ * {@link AdwViewSwitcherPage}s or {@link AdwViewStackPageInfo}s.
  */
 export declare function shouldRevealViewSwitcherBar(reveal: boolean, pages: readonly {
     readonly visible: boolean;
 }[]): boolean;
 /**
- * The button orientation the policy implies — `WIDE` is horizontal, anything
- * else vertical (adw-view-switcher.c:219-220, :534-537). The same ternary is
- * used when a button is created and when the policy changes.
+ * The button orientation the policy implies — `WIDE` is horizontal, anything else
+ * vertical. C uses the same ternary at button creation and on a policy change.
  */
 export declare function viewSwitcherButtonOrientation(policy: AdwViewSwitcherPolicy): 'horizontal' | 'vertical';
 /** The fully-derived per-button view model an `AdwViewSwitcher` renderer paints. */
@@ -240,20 +188,17 @@ export interface ViewSwitcherButtonModel {
     description: string;
 }
 /**
- * One model per page for `AdwViewSwitcher`, in PAGE index space.
- *
- * `populate_switcher` adds a button for EVERY page and `update_button` merely
- * hides the ones that fail the visibility rule (adw-view-switcher.c:230-238,
- * :178), so the index space is preserved — unlike the inline switcher, which
- * drops hidden pages entirely. `selected` is the page index; `-1` selects
- * nothing.
+ * One model per page for `AdwViewSwitcher`, in PAGE index space: `populate_switcher` adds
+ * a button for EVERY page and `update_button` merely hides the ones that fail the
+ * visibility rule, so the index space is preserved — unlike the inline switcher, which
+ * drops hidden pages entirely. `selected` is the page index; `-1` selects nothing.
  */
 export declare function buildViewSwitcherButtons(pages: readonly AdwViewSwitcherPage[], selected: number, policy: AdwViewSwitcherPolicy, strings?: IndicatorDescriptionStrings): ViewSwitcherButtonModel[];
 /** The fully-derived per-toggle view model an `AdwInlineViewSwitcher` renderer paints. */
 export interface InlineToggleModel {
     /** Position among the TOGGLES — compacted, hidden pages skipped. */
     toggleIndex: number;
-    /** Position in the PAGE list — libadwaita's `child-index` (adw-inline-view-switcher.c:346). */
+    /** Position in the PAGE list — libadwaita's `child-index`. */
     pageIndex: number;
     /** The page name. */
     name: string;
@@ -275,46 +220,36 @@ export interface InlineToggleModel {
     description: string;
 }
 /**
- * `populate_group`'s filter + order (adw-inline-view-switcher.c:360-392): a page
- * with `visible == FALSE` produces NO toggle.
+ * `populate_group`'s filter + order: a page with `visible == FALSE` produces NO toggle,
+ * which is why every model carries BOTH indices — `toggleIndex` is the compacted `0..k-1`
+ * position the toggle group knows, `pageIndex` the position the selection model knows, and
+ * libadwaita reconciles them through the `child-index` it stashes on each toggle.
  *
- * Which is why every model carries BOTH indices — `toggleIndex` is the compacted
- * `0..k-1` position the toggle group knows, `pageIndex` is the position the
- * selection model knows, and libadwaita reconciles them through the
- * `child-index` it stashes on each toggle (:346, :114-129). Neither port
- * filtered, so the two spaces coincided and the reconciliation looked
- * unnecessary.
- *
- * Note this uses the page's `visible` flag ALONE — the title-or-icon rule
- * belongs to `AdwViewSwitcher.update_button` and has no counterpart here, so a
- * page with neither title nor icon still gets an (empty) toggle.
+ * Uses the page's `visible` flag ALONE — the title-or-icon rule belongs to
+ * `AdwViewSwitcher.update_button` and has no counterpart here, so a page with neither
+ * title nor icon still gets an (empty) toggle.
  */
 export declare function buildInlineToggles(pages: readonly AdwViewSwitcherPage[], displayMode: AdwInlineViewSwitcherDisplayMode, strings?: IndicatorDescriptionStrings): InlineToggleModel[];
 /**
- * Page index → toggle index, or {@link VIEW_SWITCHER_NO_SELECTION} when the page
- * is hidden or out of range — `selection_changed_cb`
- * (adw-inline-view-switcher.c:434-453), where `index` stays
+ * Page index → toggle index, or {@link VIEW_SWITCHER_NO_SELECTION} when the page is
+ * hidden or out of range — `selection_changed_cb`, where `index` stays
  * `GTK_INVALID_LIST_POSITION` unless the visible child's page is itself visible.
- *
- * Non-integers are refused for the same reason `ViewStackState` refuses them:
- * the C position is a `guint`.
+ * Non-integers are refused because the C position is a `guint`.
  */
 export declare function toggleIndexForPage(pages: readonly AdwViewSwitcherPage[], pageIndex: number): number;
 /**
- * Toggle index → page index, or {@link VIEW_SWITCHER_NO_SELECTION} when there is
- * no such toggle — `notify_active_cb` (adw-inline-view-switcher.c:114-129), which
- * reads the active toggle's `child-index` and selects THAT page position.
+ * Toggle index → page index, or {@link VIEW_SWITCHER_NO_SELECTION} when there is no such
+ * toggle — `notify_active_cb` reads the active toggle's `child-index` and selects THAT
+ * page position.
  */
 export declare function pageIndexForToggle(pages: readonly AdwViewSwitcherPage[], toggleIndex: number): number;
 /** Opaque handle a {@link ViewSwitcherScheduler} returns for a pending dwell. */
 export type ViewSwitcherTimerHandle = unknown;
 /**
- * The injected timing seam for the drag-hover auto-switch.
- *
- * Deliberately the same SHAPE as `ToastScheduler` in `toast.ts`, so a renderer
- * writes ONE adapter over its platform timer and passes it to both. The core
- * never reaches for a global `setTimeout` — that is what `gjsify.headless: true`
- * machine-checks.
+ * The injected timing seam for the drag-hover auto-switch. Same SHAPE as `ToastScheduler`
+ * in `toast.ts`, so a renderer writes ONE adapter over its platform timer and passes it to
+ * both. The core never reaches for a global `setTimeout` — `gjsify.headless: true`
+ * machine-checks that.
  */
 export interface ViewSwitcherScheduler {
     /** Run `callback` after `ms`; return a handle {@link cancel} understands. */
@@ -332,14 +267,10 @@ export interface ViewSwitcherDragSwitchOptions {
     delay?: number;
 }
 /**
- * The 500 ms drag-hover auto-switch: hovering a non-active button while dragging
- * switches to it, and leaving before the dwell elapses cancels.
- *
- * Present in BOTH C files and in neither port
- * (adw-view-switcher-button.c:14, :58-63, :79-96; adw-inline-view-switcher.c:80,
- * :194-236). Each button/toggle owns its OWN timer there, so this keeps one
- * pending handle per index rather than a single global one — an enter on a
- * second index does not silently disarm the first.
+ * The 500 ms drag-hover auto-switch: hovering a non-active button while dragging switches
+ * to it, and leaving before the dwell elapses cancels. Each button/toggle owns its OWN
+ * timer in C, so this keeps one pending handle per index rather than a single global one —
+ * an enter on a second index does not silently disarm the first.
  */
 export declare class ViewSwitcherDragSwitch {
     private readonly _scheduler;
@@ -351,10 +282,8 @@ export declare class ViewSwitcherDragSwitch {
      * A drag entered the button at `index` while `activeIndex` is selected.
      * Returns whether a dwell was armed.
      *
-     * `drag_enter_cb` early-returns when the hovered button is already active
-     * (adw-view-switcher-button.c:82-83; the inline twin compares indices at
-     * adw-inline-view-switcher.c:219), so hovering the current tab never
-     * schedules anything.
+     * `drag_enter_cb` early-returns when the hovered button is already active (the inline
+     * twin compares indices instead), so hovering the current tab schedules nothing.
      */
     enter(index: number, activeIndex: number): boolean;
     /** The drag left the button at `index` — `drag_leave_cb` removes its source. */
@@ -373,11 +302,10 @@ export interface ViewSwitcherStateChange {
     /** Its rendered label ({@link viewSwitcherLabel}), `''` when nothing is selected. */
     title: string;
     /**
-     * `true` for a user activation or an explicit select, `false` for a model-
-     * driven auto-pick (a page list rebuild, a visibility flip). Same tagging
-     * convention as `ComboState`/`SpinState`/`ViewStackState`; libadwaita
-     * notifies on both paths, so this is for suppressing feedback loops, not for
-     * dropping the notification.
+     * `true` for a user activation or an explicit select, `false` for a model-driven
+     * auto-pick (page list rebuild, visibility flip). Same convention as
+     * `ComboState`/`SpinState`/`ViewStackState`; libadwaita notifies on both paths, so this
+     * is for suppressing feedback loops, not for dropping the notification.
      */
     interactive: boolean;
 }
@@ -392,22 +320,18 @@ export interface ViewSwitcherStateOptions {
 }
 /**
  * The page model + selection of a switcher that OWNS its pages — the browser and
- * NativeScript switchers, which bundle the `AdwViewStack` libadwaita keeps
- * separate.
+ * NativeScript switchers, which bundle the `AdwViewStack` libadwaita keeps separate.
  *
- * Selection is DELEGATED to {@link ViewStackState}, not re-implemented: the
- * integer/range/already-selected/hidden guards, the by-name lookup, the
- * first-VISIBLE-page auto-pick and the hide-fallback all come from there, which
- * is where their conformance vectors already live. What this class adds is the
- * C-faithful page record (so the button-visibility and badge rules have their
- * inputs) and a name-preserving {@link setPages}, because both renderers rebuild
- * their page list wholesale and libadwaita's selection follows the page OBJECT
- * across such a rebuild (adw-view-stack.c:660-672) rather than the index.
+ * Selection is DELEGATED to {@link ViewStackState}: the integer/range/already-selected/
+ * hidden guards, the by-name lookup, the first-VISIBLE-page auto-pick and the
+ * hide-fallback all come from there, where their conformance vectors already live. This
+ * class adds the C-faithful page record and a name-preserving {@link setPages}, because
+ * renderers rebuild their page list wholesale and libadwaita's selection follows the page
+ * OBJECT across such a rebuild rather than the index.
  *
- * Policy and display mode are deliberately NOT here: each is one enum value plus
- * one style class, validated by {@link isViewSwitcherPolicy} /
- * {@link isInlineViewSwitcherDisplayMode} and rendered from
- * {@link VIEW_SWITCHER_POLICIES} / {@link INLINE_VIEW_SWITCHER_DISPLAY_MODES}.
+ * Policy and display mode are deliberately NOT here: each is one enum value plus one style
+ * class, validated by {@link isViewSwitcherPolicy} /
+ * {@link isInlineViewSwitcherDisplayMode}.
  */
 export declare class ViewSwitcherState {
     private _pages;
@@ -425,10 +349,9 @@ export declare class ViewSwitcherState {
      * rebuild whenever a page of the same name survives.
      *
      * libadwaita's selection is a page pointer compared by identity
-     * (`adw_view_stack_pages_is_selected`, adw-view-stack.c:660-672), so an
-     * insert before the selected page shifts its index without changing what is
-     * shown; a rebuild that dropped the selected page falls through to the
-     * first-visible auto-pick. Emits at most ONE change, tagged
+     * (`adw_view_stack_pages_is_selected`), so an insert before the selected page shifts its
+     * index without changing what is shown; a rebuild that dropped the selected page falls
+     * through to the first-visible auto-pick. Emits at most ONE change, tagged
      * `interactive: false` — the page set changed, the user did not click.
      */
     setPages(specs: readonly AdwViewSwitcherPageInit[]): void;
@@ -443,12 +366,9 @@ export declare class ViewSwitcherState {
     /**
      * Select by page index. Returns whether the selection changed.
      *
-     * Every guard is {@link ViewStackState.setVisibleIndex}'s: a non-integer, a
-     * negative, an out-of-range and a hidden page are all silent no-ops — NOT
-     * clamped into range, which is what the browser switcher did (`active="-1"`
-     * jumped to the first page, `active="99"` to the last) where
-     * `adw_view_stack_pages_select_item` simply returns FALSE
-     * (adw-view-stack.c:682-684).
+     * Every guard is {@link ViewStackState.setVisibleIndex}'s: a non-integer, a negative, an
+     * out-of-range and a hidden page are all silent no-ops, NOT clamped into range —
+     * `adw_view_stack_pages_select_item` simply returns FALSE.
      */
     setSelected(index: number, interactive?: boolean): boolean;
     /** Select by page name. Returns whether the selection changed. */
@@ -456,9 +376,9 @@ export declare class ViewSwitcherState {
     /**
      * Flip a page's `visible` flag. Returns whether the SELECTION moved.
      *
-     * Both the switcher's page record and the delegated stack are updated, so the
-     * derived buttons and toggles rebuild against the same truth the selection
-     * fallback used (`update_child_visible`, adw-view-stack.c:1061-1082).
+     * Both the switcher's page record and the delegated stack are updated, so the derived
+     * buttons and toggles rebuild against the same truth the selection fallback used
+     * (`update_child_visible`).
      */
     setPageVisible(name: string, visible: boolean): boolean;
     /** A drag entered the button/toggle for page `pageIndex`; arms the dwell. */
@@ -484,16 +404,12 @@ export interface ViewSwitcherBarChange {
 /** Subscriber for {@link ViewSwitcherBarState} changes. */
 export type ViewSwitcherBarListener = (change: ViewSwitcherBarChange) => void;
 /**
- * `AdwViewSwitcherBar`'s reveal state machine: `reveal` is what the layout ASKS
- * for, `revealed` is what the bar actually does.
- *
- * `update_bar_revealed` is re-run from `set_reveal`, from `set_stack` and from
- * the pages' `items-changed` (adw-view-switcher-bar.c:340-343, :383, :277), so
- * the derived value flips both when the flag changes and when the page set does
- * — which is why {@link setPages} exists rather than the count being passed to
- * {@link setReveal}. `reveal` defaults to FALSE (:256-259); the NativeScript bar
- * started life VISIBLE, so a freshly constructed bar covered the screen bottom
- * until someone set `revealed = false`.
+ * `AdwViewSwitcherBar`'s reveal state machine: `reveal` is what the layout ASKS for,
+ * `revealed` is what the bar actually does. `update_bar_revealed` is re-run from
+ * `set_reveal`, from `set_stack` and from the pages' `items-changed`, so the derived value
+ * flips both when the flag changes and when the page set does — which is why
+ * {@link setPages} exists rather than the count being passed to {@link setReveal}.
+ * `reveal` defaults to FALSE, so a freshly constructed bar is collapsed.
  */
 export declare class ViewSwitcherBarState {
     private _reveal;
@@ -507,9 +423,8 @@ export declare class ViewSwitcherBarState {
     /** Whether the bar is actually shown — the derived truth. */
     get revealed(): boolean;
     /**
-     * Set the request. Returns whether `reveal` itself changed (C returns early
-     * before its notify when it did not, adw-view-switcher-bar.c:379-380); the
-     * subscriber only fires when the DERIVED value moves.
+     * Set the request. Returns whether `reveal` itself changed (C returns early before its
+     * notify when it did not); the subscriber only fires when the DERIVED value moves.
      */
     setReveal(value: boolean): boolean;
     /**