@gjsify/adwaita-core 0.36.0 → 0.37.0

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

@@ -2,23 +2,19 @@
  * Input shape for a tab page.
  *
  * Every optional field takes `null` as "absent" because that is what
- * `getAttribute` returns. `title` and `tooltip` coerce `null` to `''` exactly as
- * `adw_tab_page_set_title`/`set_tooltip` do (`g_set_str (&self->title, title ?
- * title : "")`, adw-tab-view.c:3021, :3064); `icon` and `indicatorIcon` stay
- * `null`, because "no icon" is a state `tabIconState` branches on.
+ * `getAttribute` returns. `title`/`tooltip` coerce `null` to `''` as
+ * `adw_tab_page_set_title`/`set_tooltip` do; `icon`/`indicatorIcon` stay `null`,
+ * because "no icon" is a state {@link tabIconState} branches on.
  *
- * There is deliberately no `pinned` and no `parentId` here: a page's pinned
- * state may only change through {@link TabViewState.setPagePinned}, which has to
- * re-order at the same time (adw-tab-view.c:4059-4078), and the parent is an
- * argument of {@link TabViewState.addPage}, mirroring
- * `adw_tab_view_add_page (self, child, parent)`.
+ * No `pinned` and no `parentId`: pinned state may only change through
+ * {@link TabViewState.setPagePinned}, which has to re-order at the same time, and
+ * the parent is an argument of {@link TabViewState.addPage}.
  */
 export interface AdwTabPageSpec<T = unknown> {
     /**
-     * Stable identity of the page. libadwaita keys everything by the `AdwTabPage`
-     * POINTER — never by title — so a string id is the platform-neutral stand-in,
-     * and two pages sharing an id would be two pages sharing a pointer. Ids are
-     * therefore unique per view; a duplicate is refused, not silently accepted.
+     * Stable identity. libadwaita keys everything by the `AdwTabPage` POINTER, never
+     * by title, so a string id is the platform-neutral stand-in: unique per view, and
+     * a duplicate is refused rather than silently accepted.
      */
     id: string;
     /** Tab label. `null`/absent is `''`, never `undefined`. */
@@ -37,14 +33,11 @@ export interface AdwTabPageSpec<T = unknown> {
     content?: T;
 }
 /**
- * A resolved page, as a renderer reads it.
- *
- * Fully readonly: the C setters all notify, so a renderer that mutates a record
- * in place would repaint nothing. Every field has a
- * `TabViewState.setPage<Field>` counterpart which emits an `'updated'` change.
+ * A resolved page, as a renderer reads it. Fully readonly: the C setters all
+ * notify, so a renderer that mutated a record in place would repaint nothing —
+ * every field has a `TabViewState.setPage<Field>` emitting an `'updated'` change.
  */
 export interface AdwTabPageState<T = unknown> {
-    /** Stable identity — the stand-in for the `AdwTabPage` pointer. */
     readonly id: string;
     /** Tab label, already coerced from `null` to `''`. */
     readonly title: string;
@@ -52,11 +45,9 @@ export interface AdwTabPageState<T = unknown> {
     readonly tooltip: string;
     /** GTK icon name, or `null` when the page has none. */
     readonly icon: string | null;
-    /** Indicator icon name, or `null`. */
     readonly indicatorIcon: string | null;
     /** Whether a spinner replaces the icon. */
     readonly loading: boolean;
-    /** Whether the attention indicator is drawn. */
     readonly needsAttention: boolean;
     /** Whether the page sits in the pinned prefix — see {@link TabViewState.setPagePinned}. */
     readonly pinned: boolean;
@@ -71,12 +62,10 @@ export interface AdwTabPageState<T = unknown> {
  * The `close-page` seam — the one place the widget asks the application a
  * question, in the same shape as `AdwToastQueueHandlers`.
  *
- * Return `true` to confirm the close, `false` to deny it, or `'defer'` to hold
- * the page in the closing state until {@link TabViewState.closePageFinish} is
- * called — which is how an app shows a "save before closing?" dialog. With no
- * handler installed the default is `!page.pinned`, i.e. `close_page_cb`'s
- * `adw_tab_view_close_page_finish (self, page, !adw_tab_page_get_pinned (page))`
- * (adw-tab-view.c:1987-1993).
+ * Return `true` to confirm the close, `false` to deny it, or `'defer'` to hold the
+ * page in the closing state until {@link TabViewState.closePageFinish} — which is
+ * how an app shows a "save before closing?" dialog. With no handler installed the
+ * default is `!page.pinned`, as `close_page_cb` does.
  */
 export interface TabViewHandlers<T = unknown> {
     /** Decide the fate of a close request. */
@@ -92,18 +81,16 @@ export interface TabViewHandlers<T = unknown> {
 export interface TabViewSelectionChange {
     /** Id of the newly-selected page, `null` when the view is empty. */
     selectedId: string | null;
-    /** Its index, `-1` when the view is empty (`detach_page`, adw-tab-view.c:1912-1913). */
+    /** Its index, `-1` when the view is empty. */
     selectedIndex: number;
     /** Id of the page that was selected before, `null` when there was none. */
     previousId: string | null;
     /**
-     * `true` for an explicit selection (a tab click, a keyboard shortcut, a
-     * {@link TabViewState.setSelectedPage} call); `false` for one the model made
-     * on its own — the auto-select of the first page and the close successor.
-     *
-     * libadwaita notifies identically on both (`set_selected_page`,
-     * adw-tab-view.c:1854); the flag exists so a bound tab bar can tell a user
-     * pick from a model-driven one, exactly as `ViewStackState` tags its own.
+     * `true` for an explicit selection (tab click, keyboard shortcut,
+     * {@link TabViewState.setSelectedPage}); `false` for one the model made on its
+     * own — the first-page auto-select and the close successor. libadwaita notifies
+     * identically on both; the flag exists so a bound tab bar can tell a user pick
+     * from a model-driven one.
      */
     interactive: boolean;
 }
@@ -111,23 +98,18 @@ export interface TabViewSelectionChange {
 export type TabViewSelectionListener = (change: TabViewSelectionChange) => void;
 /**
  * What happened to the page LIST — the `page-attached` / `page-detached` /
- * `page-reordered` signals (adw-tab-view.c:1778, :1932, :4561) plus the two the
- * C expresses as per-page `notify::` instead of a view signal.
- *
- * `'pinned'` is `adw_tab_view_set_page_pinned`'s combined flip-and-re-order
- * (:4059-4078); `'updated'` stands in for `notify::title` / `::tooltip` /
- * `::icon` / `::loading` / `::indicator-icon` / `::needs-attention`, which
- * `AdwTab` connects to in order to re-render one tab live (adw-tab.c:930-931).
+ * `page-reordered` signals plus the two C expresses as per-page `notify::` instead
+ * of a view signal: `'pinned'` is `adw_tab_view_set_page_pinned`'s combined
+ * flip-and-re-order, `'updated'` stands in for `notify::title` / `::tooltip` /
+ * `::icon` / `::loading` / `::indicator-icon` / `::needs-attention`, which `AdwTab`
+ * connects to in order to re-render one tab live.
  */
 export type TabViewPagesChangeKind = 'attached' | 'detached' | 'reordered' | 'pinned' | 'updated';
 /**
- * One page-list change. A renderer subscribes to this to insert, remove or move
- * exactly ONE tab instead of rebuilding the bar — which is what both ports did
- * (web built the bar once at connect and never again; NS tore down and rebuilt
- * every button on every close).
+ * One page-list change: a renderer subscribes to this to insert, remove or move
+ * exactly ONE tab instead of rebuilding the bar.
  */
 export interface TabViewPagesChange {
-    /** Which kind of change this is. */
     kind: TabViewPagesChangeKind;
     /** The page it happened to. */
     id: string;
@@ -150,31 +132,24 @@ export interface TabIconState {
     indicatorVisible: boolean;
 }
 /**
- * `Adw.TabBar:autohide` defaults to TRUE (adw-tab-bar.c:606-607, and
- * `self->autohide = TRUE` in init, :781).
+ * `Adw.TabBar:autohide` defaults to TRUE.
  *
- * Named so a renderer whose spelling cannot express it — an HTML boolean
- * attribute is absent-means-false, so `<adw-tab-view autohide>` inverts the
- * platform default — is making a DELIBERATE, citable decision rather than a
- * silent one.
+ * Named because an HTML boolean attribute is absent-means-false, so
+ * `<adw-tab-view autohide>` inverts the platform default: a renderer that cannot
+ * spell the default is then making a deliberate decision rather than a silent one.
  */
 export declare const DEFAULT_TAB_AUTOHIDE = true;
 /**
  * Whether `Adw.TabBar` shows its tabs: `!autohide || nPages > 1 ||
- * nPinnedPages >= 1 || isTransferringPage` (`update_autohide_cb`,
- * adw-tab-bar.c:142-164).
+ * nPinnedPages >= 1 || isTransferringPage` (`update_autohide_cb`).
  *
- * The `nPinnedPages >= 1` clause is the one that surprises — a single PINNED tab
- * keeps the bar up — and it is missing from the web port, which only ever
- * compared the page count. The `isTransferringPage` clause keeps the bar up
- * while a drag is in flight so there is somewhere to drop.
+ * The surprising clause is `nPinnedPages >= 1` — a single PINNED tab keeps the bar
+ * up; `isTransferringPage` keeps it up while a drag is in flight so there is
+ * somewhere to drop.
  */
 export declare function tabsRevealed(state: {
-    /** `AdwTabBar:autohide`. */
     autohide: boolean;
-    /** `adw_tab_view_get_n_pages`. */
     nPages: number;
-    /** `adw_tab_view_get_n_pinned_pages`. */
     nPinnedPages: number;
     /** `adw_tab_view_get_is_transferring_page` — a drag-n-drop tab transfer is running. */
     isTransferringPage: boolean;
@@ -183,109 +158,81 @@ export declare function tabsRevealed(state: {
  * Whether a tab shows its close button: `!pinned && ((hovering && fullyVisible)
  * || selected || dragging)`.
  *
- * The three-term half is `update_state` (adw-tab.c:124); the `!pinned` gate is
- * applied once at construction, where a pinned tab hides both its title and its
- * close button outright (adw-tab.c:645-650). Each port shipped a different
- * SINGLE term of this: web showed the button unconditionally, NS only on the
- * selected tab. The `fullyVisible` conjunct is why a hovered tab that is half
- * scrolled out of the bar shows nothing.
+ * The three-term half is `update_state`; the `!pinned` gate is applied once at
+ * construction, where a pinned tab hides both its title and its close button
+ * outright. The `fullyVisible` conjunct is why a hovered tab that is half scrolled
+ * out of the bar shows nothing.
  */
 export declare function tabCloseVisible(state: {
-    /** Pointer is over the tab. */
     hovering: boolean;
     /** The tab is not clipped by the bar's scroll region. */
     fullyVisible: boolean;
-    /** The tab is the selected one. */
     selected: boolean;
-    /** The tab is being dragged. */
     dragging: boolean;
-    /** The tab is pinned. */
     pinned: boolean;
 }): boolean;
 /**
  * The tooltip a tab shows: its own `tooltip` when non-empty, otherwise the page
- * title (`update_tooltip`, adw-tab.c:137-146; identical in
- * adw-tab-thumbnail.c). Neither port had tooltips at all.
+ * title (`update_tooltip`; identical in adw-tab-thumbnail.c).
  */
 export declare function tabTooltip(page: Pick<AdwTabPageState, 'tooltip' | 'title'>): string;
 /**
- * Whether {@link tabTooltip}'s result is Pango MARKUP rather than plain text.
- *
- * C branches on exactly this: a non-empty `tooltip` goes through
- * `gtk_widget_set_tooltip_markup`, the title fallback through
- * `gtk_widget_set_tooltip_text` (adw-tab.c:141-146). The distinction is not
- * cosmetic — a renderer that pushed a marked-up tooltip through an HTML sink
- * would be executing page-supplied markup, and one that escaped the title would
- * show the escapes.
+ * Whether {@link tabTooltip}'s result is Pango MARKUP rather than plain text: C
+ * sends a non-empty `tooltip` through `gtk_widget_set_tooltip_markup` and the title
+ * fallback through `gtk_widget_set_tooltip_text`. Not cosmetic — a renderer that
+ * pushed marked-up text into an HTML sink would execute page-supplied markup, and
+ * one that escaped the title would show the escapes.
  */
 export declare function tabTooltipIsMarkup(page: Pick<AdwTabPageState, 'tooltip'>): boolean;
 /**
- * What a tab paints in its icon + indicator slots (`update_icons`,
- * adw-tab.c:171-198).
+ * What a tab paints in its icon + indicator slots (`update_icons`).
  *
- * Three rules, in the order C applies them: `loading` wins and installs a
- * spinner WITHOUT replacing the icon name (so the icon reappears when loading
- * ends); a PINNED page with no icon of its own falls back to the view's
- * `default-icon`; and the icon slot is shown iff there is something to show AND
- * the page is either not pinned or has no indicator — on a pinned tab the
- * indicator REPLACES the icon, because a pinned tab is a single-glyph chip.
- *
- * Neither port models loading, indicators or a default icon; this is the
- * derivation they need before they can.
+ * Three rules, in the order C applies them: `loading` wins and installs a spinner
+ * WITHOUT replacing the icon name (so the icon reappears when loading ends); a
+ * PINNED page with no icon of its own falls back to the view's `default-icon`; and
+ * the icon slot is shown iff there is something to show AND the page is either not
+ * pinned or has no indicator — on a pinned tab the indicator REPLACES the icon,
+ * because a pinned tab is a single-glyph chip.
  */
 export declare function tabIconState<T>(page: Pick<AdwTabPageState<T>, 'icon' | 'indicatorIcon' | 'loading' | 'pinned'>, defaultIcon: string | null): TabIconState;
 /**
  * Whether `pageId` is `parentId` or a (possibly indirect) descendant of it —
- * `is_descendant_of` (adw-tab-view.c:1735-1742).
+ * `is_descendant_of`.
  *
- * The loop is `while (page && page != parent) page = parent_of (page);` and it
- * therefore returns TRUE for `page == parent` WITHOUT taking a step. That
- * non-obvious identity case is what makes "close a tab you opened from another
- * tab" land back on the opener: when the previous page IS the parent, the
- * descendant branch fires and selects it instead of falling through to the next
- * page.
+ * Returns TRUE for `page === parent` WITHOUT taking a step, and that identity case
+ * is what makes "close a tab you opened from another tab" land back on the opener:
+ * when the previous page IS the parent, the descendant branch fires instead of
+ * falling through to the next page.
  */
 export declare function isDescendantOfPage<T>(pages: readonly AdwTabPageState<T>[], pageId: string | null, parentId: string): boolean;
 /**
  * Which page ends up selected once `closingId` is removed — the pure kernel of
- * `select_previous_page` (adw-tab-view.c:1857-1897), extracted so the rule is
- * testable without a live view.
- *
- * Ranked, and the ranking is the point:
- *  1. the closing page is not the selected one → nothing moves (the C returns at
- *     :1864-1865, so `set_selected_page` is never called and NOTHING notifies);
- *  2. it has a parent and is not first, and the PREVIOUS page is a descendant of
- *     that parent → the previous page (:1869-1878) — a page is its own
- *     descendant, so "the previous page IS the opener" hits this branch;
- *  3. same, but the previous page and the parent are BOTH pinned → the parent
- *     (:1885-1890), because a page opened from a pinned parent is placed after
- *     the LAST pinned page rather than directly after its parent;
- *  4. otherwise the next page, else the previous page (:1893-1896);
- *  5. neither exists → `null`, i.e. the view empties.
- *
- * Returns `selectedId` unchanged in case 1, so the caller can compare and skip
- * the notification. Takes no `nPinnedPages`: the two pinned tests read
- * `page.pinned` off the records, and a parameter nothing reads is worse than a
- * signature that does not have it.
+ * `select_previous_page`, ranked:
+ * 1. the closing page is not the selected one → nothing moves and NOTHING
+ * notifies; `selectedId` comes back unchanged so the caller can skip it;
+ * 2. it has a parent and is not first, and the PREVIOUS page is a descendant of
+ * that parent → the previous page (a page is its own descendant, so "the
+ * previous page IS the opener" hits this branch);
+ * 3. same, but the previous page and the parent are BOTH pinned → the parent,
+ * because a page opened from a pinned parent is placed after the LAST pinned
+ * page rather than directly after its parent;
+ * 4. otherwise the next page, else the previous page;
+ * 5. neither exists → `null`, i.e. the view empties.
  */
 export declare function successorAfterClose<T>(pages: readonly AdwTabPageState<T>[], closingId: string, selectedId: string | null): string | null;
 /**
  * The `Adw.TabView` model: an ordered page list with a pinned prefix, a selected
- * page, and the close protocol — with the C guard, ordering and successor rules
- * applied once for every renderer.
- *
- * `T` is the renderer's page-content type; the machine never looks inside it.
- * Nothing here renders, reads a global or holds a timer, so an instance is a
- * plain value a test can drive step by step.
+ * page and the close protocol, with the C guard, ordering and successor rules
+ * applied once for every renderer. `T` is the renderer's page-content type; the
+ * machine never looks inside it, renders nothing, reads no global and holds no
+ * timer, so an instance is a plain value a test can drive step by step.
  */
 export declare class TabViewState<T = unknown> {
     /**
-     * The ordered list + the selection, composed rather than restated —
-     * `ViewStackState` already owns the index guards, the
+     * The ordered list + selection: `ViewStackState` owns the index guards, the
      * selection-follows-the-page bookkeeping and the fan-out. Its `name` is this
-     * view's page id and its `content` is the tab record; its `title`/`icon` are
-     * never read here, because a tab's title is mutable and a second copy of it
-     * would be a second truth.
+     * view's page id and its `content` the tab record; its `title`/`icon` are never
+     * read here, because a tab's title is mutable and a second copy would drift.
      */
     private readonly _stack;
     private readonly _handlers;
@@ -296,11 +243,9 @@ export declare class TabViewState<T = unknown> {
     /** Set while an insert runs — see {@link _deferredSelection}. */
     private _deferSelection;
     /**
-     * A selection change parked until the `'attached'` change has gone out.
-     *
-     * This is C's `g_object_freeze_notify` / `thaw_notify` around `insert_page`
-     * (adw-tab-view.c:1947-1961), not a scheduling trick: `attach_page` emits
-     * `page-attached` as a SIGNAL (immediate) and the auto-select's
+     * A selection change parked until the `'attached'` change has gone out — C's
+     * `g_object_freeze_notify`/`thaw_notify` around `insert_page`, not a scheduling
+     * trick: `page-attached` is an immediate signal and the auto-select's
      * `notify::selected-page` only lands at thaw, so a renderer is guaranteed to
      * have built the tab before it is told to mark it selected.
      */
@@ -311,11 +256,9 @@ export declare class TabViewState<T = unknown> {
     /** Subscribe to selection changes. Returns an unsubscribe function. */
     subscribe(listener: TabViewSelectionListener): () => void;
     /**
-     * Subscribe to page-list changes. Returns an unsubscribe function.
-     *
-     * Kept separate from {@link subscribe} because libadwaita keeps them separate
-     * too — `props[PROP_SELECTED_PAGE]` versus the `AdwTabPages` list model — and
-     * a renderer needs them at different granularities.
+     * Subscribe to page-list changes. Returns an unsubscribe function. Separate from
+     * {@link subscribe} because libadwaita separates them too —
+     * `props[PROP_SELECTED_PAGE]` versus the `AdwTabPages` list model.
      */
     subscribePages(listener: TabViewPagesListener): () => void;
     private _emitSelection;
@@ -323,47 +266,42 @@ export declare class TabViewState<T = unknown> {
     private _flushDeferredSelection;
     /**
      * Every page in order — a frozen projection, so a renderer cannot reorder the
-     * model by writing to the array it was handed.
-     *
-     * Cached against the inner list's identity rather than an invalidation flag:
-     * `ViewStackState` drops its own cached projection on exactly the structural
-     * changes that matter, so there is no second bookkeeping to forget to update.
+     * model by writing to the array it was handed. Cached against the inner list's
+     * identity rather than an invalidation flag, so there is no second bookkeeping to
+     * forget to update.
      */
     get pages(): readonly AdwTabPageState<T>[];
-    /** Number of pages — `adw_tab_view_get_n_pages` (adw-tab-view.c:3610). */
+    /** Number of pages — `adw_tab_view_get_n_pages`. */
     get nPages(): number;
     /**
-     * Number of pinned pages — `adw_tab_view_get_n_pinned_pages`
-     * (adw-tab-view.c:3628).
+     * Number of pinned pages — `adw_tab_view_get_n_pinned_pages`.
      *
-     * DERIVED from the prefix invariant instead of bookkept as C's
-     * `set_n_pinned_pages` counter is (:1696-1706). The invariant "the pinned
-     * pages are exactly `[0, nPinnedPages)`" is what every insert, reorder and
-     * first/last hop depends on; deriving the count makes it machine-true rather
-     * than something four mutators must each remember to keep true.
+     * DERIVED from the prefix invariant rather than bookkept as C's
+     * `set_n_pinned_pages` counter is. "The pinned pages are exactly
+     * `[0, nPinnedPages)`" is what every insert, reorder and first/last hop depends
+     * on; deriving the count makes it machine-true instead of something four mutators
+     * must each remember to keep true.
      */
     get nPinnedPages(): number;
     /**
      * The page at `position`, or `null`.
      *
-     * Refuses a non-integer, negative or out-of-range position instead of
-     * clamping: `adw_tab_view_get_nth_page` takes an `int` and asserts
-     * `position >= 0` / `position < n_pages` (adw-tab-view.c:4126-4134), and no
-     * clamping path exists anywhere in the file. This single guard is what the
-     * NativeScript port lacked when a fractional index blanked the widget.
+     * Refuses a non-integer, negative or out-of-range position instead of clamping:
+     * `adw_tab_view_get_nth_page` takes an `int` and asserts `position >= 0` /
+     * `position < n_pages`, and no clamping path exists anywhere in the C file.
      */
     getNthPage(position: number): AdwTabPageState<T> | null;
-    /** Index of the page with `id`, `-1` when absent — `adw_tab_view_get_page_position` (:4152). */
+    /** Index of the page with `id`, `-1` when absent — `adw_tab_view_get_page_position`. */
     getPagePosition(id: string): number;
     /** The page with `id`, or `null`. */
     getPage(id: string): AdwTabPageState<T> | null;
-    /** Whether `id` is waiting for a {@link closePageFinish} (`page->closing`, :4396-4399). */
+    /** Whether `id` is waiting for a {@link closePageFinish} (`page->closing`). */
     isClosing(id: string): boolean;
     /**
-     * Every diagnostic C would have printed as a `g_return_if_fail` warning, in
-     * order — an unknown page id, a duplicate id, an insert or reorder outside
-     * its partition. Kept as data so a test can assert on the class instead of on
-     * stderr, exactly as `ViewStackState.diagnostics` does.
+     * Every diagnostic C would have printed as a `g_return_if_fail` warning, in order
+     * — an unknown page id, a duplicate id, an insert or reorder outside its
+     * partition. Data rather than stderr so a test can assert on the class, as
+     * `ViewStackState.diagnostics` does.
      */
     get diagnostics(): readonly string[];
     /** Id of the selected page, `null` when the view is empty. */
@@ -375,42 +313,36 @@ export declare class TabViewState<T = unknown> {
     /**
      * Select a page by id. Returns whether the selection changed.
      *
-     * An unknown id is refused, and `null` is accepted only while the view is
-     * empty — `adw_tab_view_set_selected_page` asserts `ADW_IS_TAB_PAGE` +
-     * `page_belongs_to_this_view` when `n_pages > 0` and `selected_page == NULL`
-     * otherwise (adw-tab-view.c:3686-3693).
-     *
-     * `interactive` defaults to `true` because this IS the explicit call, the
-     * same convention `ViewStackState.setVisibleIndex` uses; the model-driven
-     * paths (the first-page auto-select and the close successor) pass `false`.
+     * An unknown id is refused, and `null` is accepted only while the view is empty —
+     * `adw_tab_view_set_selected_page` asserts `ADW_IS_TAB_PAGE` +
+     * `page_belongs_to_this_view` when `n_pages > 0`, and `selected_page == NULL`
+     * otherwise. `interactive` defaults to `true` because this IS the explicit call;
+     * the model-driven paths (first-page auto-select, close successor) pass `false`.
      */
     setSelectedPage(id: string | null, interactive?: boolean): boolean;
     /**
-     * Select the page at `n` — the Alt+1…Alt+9 / Alt+0 path (`select_nth_page_cb`,
-     * adw-tab-view.c:2136-2163; Alt+0 is `n = 9`, since pages count from 0).
+     * Select the page at `n` — the Alt+1…Alt+9 / Alt+0 path (`select_nth_page_cb`;
+     * Alt+0 is `n = 9`, since pages count from 0).
      *
-     * Pure delegation to the composed selection primitive, which already refuses
-     * a non-integer, a negative, an out-of-range and the already-selected index
-     * and emits nothing for any of them (adw-tab-view.c:2145, :2158-2159). That
-     * is the whole reason this family builds ON `ViewStackState` instead of
-     * beside it.
+     * Pure delegation to the composed selection primitive, which already refuses a
+     * non-integer, a negative, an out-of-range and the already-selected index, and
+     * emits nothing for any of them.
      */
     selectNthPage(n: number): boolean;
     /**
      * Select the page before the selected one; `false` when it is already first
-     * (`adw_tab_view_select_previous_page`, adw-tab-view.c:3708-3730). Does NOT
+     * (`adw_tab_view_select_previous_page`). Does NOT
      * wrap — {@link cyclePreviousPage} is the wrapping variant.
      */
     selectPreviousPage(): boolean;
     /**
      * Select the page after the selected one; `false` when it is already last
-     * (`adw_tab_view_select_next_page`, adw-tab-view.c:3741-3763). Does NOT wrap.
+     * (`adw_tab_view_select_next_page`). Does NOT wrap.
      */
     selectNextPage(): boolean;
     /**
      * Select the first page in the selected page's own partition, hopping the
-     * partition boundary once (`adw_tab_view_select_first_page`,
-     * adw-tab-view.c:3764-3789).
+     * partition boundary once (`adw_tab_view_select_first_page`).
      *
      * From a non-pinned page it goes to index `nPinnedPages` — the first
      * NON-pinned tab — and only when that is already the selected page does it
@@ -420,22 +352,22 @@ export declare class TabViewState<T = unknown> {
     selectFirstPage(): boolean;
     /**
      * Select the last page in the selected page's own partition, hopping the
-     * boundary once (`adw_tab_view_select_last_page`, adw-tab-view.c:3793-3818):
+     * boundary once (`adw_tab_view_select_last_page`):
      * from the LAST pinned tab it continues to the last non-pinned one.
      */
     selectLastPage(): boolean;
     /**
      * Ctrl+Tab: the next page, WRAPPING to the first (`select_page_cb`'s forward
-     * branch, adw-tab-view.c:2030-2041).
+     * branch).
      *
      * Returns `false` outright on a view of one page or fewer — the shortcut
-     * PROPAGATES there rather than ringing the error bell (:2008), which is how
+     * PROPAGATES there rather than ringing the error bell, which is how
      * Ctrl+Tab keeps working for whatever contains the tab view.
      */
     cycleNextPage(): boolean;
     /**
      * Ctrl+Shift+Tab: the previous page, WRAPPING to the last
-     * (`select_page_cb`'s backward branch, adw-tab-view.c:2017-2028).
+     * (`select_page_cb`'s backward branch).
      *
      * Ctrl+Home / Ctrl+End take the `last` branch of the same callback and map to
      * {@link selectFirstPage} / {@link selectLastPage}, which deliberately do NOT
@@ -444,7 +376,7 @@ export declare class TabViewState<T = unknown> {
     cyclePreviousPage(): boolean;
     /**
      * Add a page opened FROM `parentId`, deriving its position instead of taking
-     * one (`adw_tab_view_add_page`, adw-tab-view.c:4188-4223). Returns the
+     * one (`adw_tab_view_add_page`). Returns the
      * position used, or `-1` when the page was refused.
      *
      * Three rules: a `null` parent appends; a PINNED parent inserts after the last
@@ -454,101 +386,90 @@ export declare class TabViewState<T = unknown> {
      * order they were opened rather than reversing them.
      *
      * The new page is never itself pinned — `create_and_insert_page` is called
-     * with `pinned = FALSE` even for a pinned parent (:4222).
+     * with `pinned = FALSE` even for a pinned parent.
      */
     addPage(spec: AdwTabPageSpec<T>, parentId?: string | null): number;
     /**
      * Insert a NON-pinned page at `position`, which must be in
      * `[nPinnedPages, nPages]` — inserting before a pinned page is a programmer
-     * error C refuses outright (`adw_tab_view_insert`, adw-tab-view.c:4246-4247).
+     * error C refuses outright (`adw_tab_view_insert`).
      * Returns the position, or `-1` when refused.
      */
     insertPage(spec: AdwTabPageSpec<T>, position: number): number;
-    /** Insert as the FIRST non-pinned page (`adw_tab_view_prepend`, adw-tab-view.c:4262). */
+    /** Insert as the FIRST non-pinned page (`adw_tab_view_prepend`). */
     prependPage(spec: AdwTabPageSpec<T>): number;
-    /** Insert as the LAST non-pinned page (`adw_tab_view_append`, adw-tab-view.c:4284). */
+    /** Insert as the LAST non-pinned page (`adw_tab_view_append`). */
     appendPage(spec: AdwTabPageSpec<T>): number;
     /**
      * Insert a PINNED page at `position`, which must be in `[0, nPinnedPages]` —
      * a pinned page after a non-pinned one is refused
-     * (`adw_tab_view_insert_pinned`, adw-tab-view.c:4312-4313).
+     * (`adw_tab_view_insert_pinned`).
      * Returns the position, or `-1` when refused.
      */
     insertPinnedPage(spec: AdwTabPageSpec<T>, position: number): number;
-    /** Insert as the FIRST pinned page (`adw_tab_view_prepend_pinned`, adw-tab-view.c:4331). */
+    /** Insert as the FIRST pinned page (`adw_tab_view_prepend_pinned`). */
     prependPinnedPage(spec: AdwTabPageSpec<T>): number;
-    /** Insert as the LAST pinned page (`adw_tab_view_append_pinned`, adw-tab-view.c:4353). */
+    /** Insert as the LAST pinned page (`adw_tab_view_append_pinned`). */
     appendPinnedPage(spec: AdwTabPageSpec<T>): number;
     private _insert;
     /**
      * Pin or unpin a page AND re-order it in the same step, returning its new
      * position — or `-1` when it is already in that state
-     * (`adw_tab_view_set_page_pinned`, adw-tab-view.c:4047-4086).
+     * (`adw_tab_view_set_page_pinned`).
      *
      * Pinning moves the page to index `nPinnedPages`; unpinning moves it to
-     * `nPinnedPages - 1`. Both are computed from the count BEFORE the flip, and
-     * both are indices into the list WITHOUT the moved page — which is why
-     * unpinning the SECOND of two pinned pages returns 1 and moves nothing while
-     * still changing the pinned count.
-     *
-     * This is the single derivation neither port has and the one most likely to
-     * be got wrong by hand.
+     * `nPinnedPages - 1`. Both are computed from the count BEFORE the flip and both
+     * are indices into the list WITHOUT the moved page — which is why unpinning the
+     * SECOND of two pinned pages returns 1 and moves nothing while still changing the
+     * pinned count.
      */
     setPagePinned(id: string, pinned: boolean): number;
     /**
      * Request that `id` be closed, opening the two-phase protocol: the page is
      * marked closing, the handler runs, and the close is then confirmed, denied
-     * or left deferred (`adw_tab_view_close_page`, adw-tab-view.c:4386-4400).
+     * or left deferred (`adw_tab_view_close_page`).
      *
-     * Returns whether the request was STARTED — `false` means it was ignored
-     * because the id is unknown or the page is already awaiting a
-     * {@link closePageFinish}. That re-entrancy guard (`if (page->closing)
-     * return;`, :4396-4397) is what stops a second click on the close button from
-     * running a save dialog twice.
+     * Returns whether the request was STARTED — `false` means it was ignored because
+     * the id is unknown or the page is already awaiting a {@link closePageFinish}.
+     * That re-entrancy guard (`if (page->closing) return;`) is what stops a second
+     * click on the close button from running a save dialog twice.
      *
      * With no handler installed a non-pinned page is closed and a PINNED page is
-     * denied and stays — `close_page_cb` (:1986-1993).
+     * denied and stays — `close_page_cb`.
      */
     closePage(id: string): boolean;
     /**
      * Complete a {@link closePage}. Returns whether the page was detached.
      *
-     * `confirm: false` clears the closing flag and leaves the page exactly where
-     * it was, so `closePage` can be called for it again; `confirm: true` detaches
-     * it (`adw_tab_view_close_page_finish`, adw-tab-view.c:4419-4437). Calling it
-     * for a page that is not closing is refused, as C's
-     * `g_return_if_fail (page->closing)` is (:4426).
-     *
-     * Neither renderer had this seam, which is why an app could not show a
-     * "save before closing?" dialog on either.
+     * `confirm: false` clears the closing flag and leaves the page exactly where it
+     * was, so `closePage` can be called for it again; `confirm: true` detaches it
+     * (`adw_tab_view_close_page_finish`). Calling it for a page that is not closing is
+     * refused, as C's `g_return_if_fail (page->closing)` is.
      */
     closePageFinish(id: string, confirm: boolean): boolean;
     /**
      * Remove a page unconditionally, running the successor rule FIRST. Returns
      * the removed page, or `null` when the id is unknown.
      *
-     * The order is load-bearing: `detach_page` calls `select_previous_page` at
-     * adw-tab-view.c:1906 and only removes at :1915, so the successor is chosen
-     * while the closing page is still in the list. Choosing it afterwards gives
-     * different answers for every parent-aware case, because "the previous page"
-     * is no longer the same page.
+     * The order is load-bearing: `detach_page` runs `select_previous_page` before it
+     * removes, so the successor is chosen while the closing page is still in the list.
+     * Choosing it afterwards gives different answers for every parent-aware case,
+     * because "the previous page" is no longer the same page.
      *
-     * Closing the LAST page empties the view: the selection becomes `null` at
-     * index `-1` and that DOES notify (:1912-1913) — both ports reported index 0
-     * for a page-less view.
+     * Closing the LAST page empties the view: the selection becomes `null` at index
+     * `-1`, and that DOES notify.
      *
-     * DEVIATIONS, both deliberate: the empty-view notification is emitted AFTER
-     * the removal rather than before it, so a listener reading `pages` and
-     * `selectedIndex` during the callback sees one consistent state; and pages
-     * parented to the removed one are re-pointed at its own parent, which C gets
-     * for free from `page_parent_notify_cb` (:293-303) when the detached page is
-     * finalized — without it a dangling parent id would quietly disable the
-     * successor rule for every child.
+     * DEVIATIONS from C, both deliberate: the empty-view notification is emitted AFTER
+     * the removal, so a listener reading `pages` and `selectedIndex` during the
+     * callback sees one consistent state; and pages parented to the removed one are
+     * re-pointed at its own parent, which C gets for free from
+     * `page_parent_notify_cb` when the detached page is finalized — without it a
+     * dangling parent id would quietly disable the successor rule for every child.
      */
     detachPage(id: string): AdwTabPageState<T> | null;
     /**
      * Request a close for every page except `id`
-     * (`adw_tab_view_close_other_pages`, adw-tab-view.c:4444-4463).
+     * (`adw_tab_view_close_other_pages`).
      *
      * The walk is DESCENDING, and that is part of the spec rather than an
      * implementation detail: each confirmed close shifts every later index, so an
@@ -556,57 +477,54 @@ export declare class TabViewState<T = unknown> {
      * handler that adds a page mid-batch cannot make the batch visit it.
      */
     closeOtherPages(id: string): void;
-    /** Request a close for every page before `id`, descending (adw-tab-view.c:4485). */
+    /** Request a close for every page before `id`, descending. */
     closePagesBefore(id: string): void;
-    /** Request a close for every page after `id`, descending (adw-tab-view.c:4511). */
+    /** Request a close for every page after `id`, descending. */
     closePagesAfter(id: string): void;
     /**
      * Move a page to `position` WITHIN ITS OWN PARTITION. Returns whether it
-     * moved (`adw_tab_view_reorder_page`, adw-tab-view.c:4526-4569).
+     * moved (`adw_tab_view_reorder_page`).
      *
      * A pinned page may only land in `[0, nPinnedPages)` and a non-pinned one in
-     * `[nPinnedPages, nPages)`; anything else is the programmer error C refuses
-     * (:4542-4548). An unchanged position returns `false` without emitting
-     * (:4552-4553) — which is what makes `reorderFirst` on the first non-pinned
-     * tab a no-op rather than a drag into pinned territory.
+     * `[nPinnedPages, nPages)`; anything else is the programmer error C refuses. An
+     * unchanged position returns `false` without emitting — which is what makes
+     * `reorderFirst` on the first non-pinned tab a no-op rather than a drag into
+     * pinned territory.
      */
     reorderPage(id: string, position: number): boolean;
     /**
      * Move a page one slot earlier, stopping at its partition's first index
-     * (`adw_tab_view_reorder_backward`, adw-tab-view.c:4586-4604) — so the first
+     * (`adw_tab_view_reorder_backward`) — so the first
      * NON-pinned tab cannot be dragged into pinned territory.
      */
     reorderBackward(id: string): boolean;
     /**
      * Move a page one slot later, stopping at its partition's last index
-     * (`adw_tab_view_reorder_forward`, adw-tab-view.c:4617-4635).
+     * (`adw_tab_view_reorder_forward`).
      */
     reorderForward(id: string): boolean;
-    /** Move a page to the first slot of its partition (adw-tab-view.c:4646-4661). */
+    /** Move a page to the first slot of its partition. */
     reorderFirst(id: string): boolean;
-    /** Move a page to the last slot of its partition (adw-tab-view.c:4672-4687). */
+    /** Move a page to the last slot of its partition. */
     reorderLast(id: string): boolean;
     private _reorderMissing;
     /**
      * Set a page's title; `null` becomes `''`, matching
-     * `g_set_str (&self->title, title ? title : "")` (adw-tab-view.c:3021).
-     * Returns whether it changed.
+     * `g_set_str (&self->title, title ? title: "")`. Returns whether it changed.
      *
-     * The whole reason this exists: `AdwTab` connects to `notify::title` and
-     * re-renders the label live (adw-tab.c:930-931), while both ports snapshotted
-     * the title once — the web one even declaring `observedAttributes = ['title']`
-     * with no `attributeChangedCallback` behind it.
+     * Needed because `AdwTab` connects to `notify::title` and re-renders the label
+     * live: a renderer that snapshots the title once is wrong.
      */
     setPageTitle(id: string, title: string | null): boolean;
-    /** Set a page's tooltip; `null` becomes `''` (adw-tab-view.c:3064). */
+    /** Set a page's tooltip; `null` becomes `''`. */
     setPageTooltip(id: string, tooltip: string | null): boolean;
-    /** Set a page's icon name, `null` for none (`adw_tab_page_set_icon`, adw-tab-view.c:3101). */
+    /** Set a page's icon name, `null` for none (`adw_tab_page_set_icon`). */
     setPageIcon(id: string, icon: string | null): boolean;
-    /** Set a page's indicator icon, `null` for none (adw-tab-view.c:3198). */
+    /** Set a page's indicator icon, `null` for none. */
     setPageIndicatorIcon(id: string, icon: string | null): boolean;
-    /** Set whether the tab draws a spinner (`adw_tab_page_set_loading`, adw-tab-view.c:3143). */
+    /** Set whether the tab draws a spinner (`adw_tab_page_set_loading`). */
     setPageLoading(id: string, loading: boolean): boolean;
-    /** Set the attention indicator (`adw_tab_page_set_needs_attention`, adw-tab-view.c:3333). */
+    /** Set the attention indicator (`adw_tab_page_set_needs_attention`). */
     setPageNeedsAttention(id: string, needsAttention: boolean): boolean;
     private _update;
     /** The mutable records, in order — the same objects {@link pages} exposes readonly. */