@gjsify/adwaita-core 0.36.0 → 0.38.0

package/lib/types/sidebar.d.ts

@@ -1,39 +1,37 @@
 /**
  * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
- * (`adw_sidebar_init`, adw-sidebar.c:2862).
+ * (`adw_sidebar_init`).
  *
- * libadwaita spells it `G_MAXUINT` because `AdwSidebar:selected` is a `guint`;
- * `-1` is the idiomatic TS sentinel and, being `G_MAXUINT` mod 2^32, it makes
- * {@link adjustSidebarSelection}'s arithmetic agree with the C code bit for bit.
+ * libadwaita spells it `G_MAXUINT` because `AdwSidebar:selected` is a `guint`; `-1` is the
+ * idiomatic TS sentinel and, being `G_MAXUINT` mod 2^32, it makes
+ * {@link adjustSidebarSelection}'s arithmetic agree with the C bit for bit.
  */
 export declare const ADW_SIDEBAR_NO_SELECTION = -1;
 /**
- * How a sidebar looks and behaves — `AdwSidebarMode` (adw-sidebar.h).
- *
- * `'sidebar'` is a flat navigation list with a persistent, VISIBLE selection;
- * `'page'` is a page of boxed lists where "the selection is invisible and only
- * tracked to determine the initially selected item once switched back"
- * (adw-sidebar.c:2948-2951). The tracked index is identical in both.
+ * How a sidebar looks and behaves — `AdwSidebarMode`. `'sidebar'` is a flat navigation list
+ * with a persistent, VISIBLE selection; `'page'` is a page of boxed lists where "the
+ * selection is invisible and only tracked to determine the initially selected item once
+ * switched back". The tracked index is identical in both.
  */
 export type AdwSidebarMode = 'sidebar' | 'page';
 /** One selectable row — the value half of `AdwSidebarItem`. */
 export interface AdwSidebarItemSpec {
-    /** Row title. Defaults to `''` in libadwaita (adw-sidebar-item.c:419). */
+    /** Row title. Defaults to `''` in libadwaita. */
     title: string;
     /** Optional second line. Absent and `''` are the same thing. */
     subtitle?: string;
     /** Symbolic icon name, e.g. `'folder-symbolic'`. Absent means no icon. */
     iconName?: string;
-    /** Whether the row is rendered at all — bound to `row:visible` (adw-sidebar.c:1382). Default true. */
+    /** Whether the row is rendered at all — bound to `row:visible`. Default true. */
     visible?: boolean;
-    /** Whether the row can be activated — bound to `row:sensitive` (adw-sidebar.c:1383). Default true. */
+    /** Whether the row can be activated — bound to `row:sensitive`. Default true. */
     enabled?: boolean;
 }
 /**
  * A titled group of rows — the value half of `AdwSidebarSection`.
  *
  * An absent or empty title selects the `'separator'` header instead of the
- * `'title'` one (`update_header_page_cb`, adw-sidebar.c:1449-1455).
+ * `'title'` one (`update_header_page_cb`).
  */
 export interface AdwSidebarSectionSpec {
     /** Group heading. Absent/empty renders a separator instead. */
@@ -44,11 +42,10 @@ export interface AdwSidebarSectionSpec {
 /** One entry of the flattened item model. */
 export interface SidebarFlatItem {
     /**
-     * The flat index `adw_sidebar_item_get_index` returns — the section's first
-     * index plus the local one (adw-sidebar-item.c:1040). It stays in the
-     * UNFILTERED space even when the item came out of a filtered walk, because
-     * libadwaita keeps the selection on `items_model` and the row list on
-     * `filtered_items` (adw-sidebar.c:2866, :2177-2180).
+     * The flat index `adw_sidebar_item_get_index` returns — the section's first index plus the
+     * local one. It stays in the UNFILTERED space even when the item came out of a filtered
+     * walk, because libadwaita keeps the selection on `items_model` and the row list on
+     * `filtered_items`.
      */
     index: number;
     /** Index of the owning section. */
@@ -57,22 +54,22 @@ export interface SidebarFlatItem {
     sectionItemIndex: number;
     /** The item as declared — same object identity, so `selectedItem === spec` holds. */
     item: AdwSidebarItemSpec;
-    /** `string_is_not_empty(title)` — the title label's visibility (adw-sidebar.c:1411-1412). */
+    /** `string_is_not_empty(title)` — the title label's visibility. */
     titleVisible: boolean;
-    /** `string_is_not_empty(subtitle)` (adw-sidebar.c:1420-1421). */
+    /** `string_is_not_empty(subtitle)`. */
     subtitleVisible: boolean;
-    /** `notify_icon_cb`'s `icon_name && *icon_name` (adw-sidebar.c:1303). */
+    /** `notify_icon_cb`'s `icon_name && *icon_name`. */
     iconVisible: boolean;
 }
 /** The header libadwaita draws above one RENDERED section. */
 export interface SidebarHeaderSpec {
     /** Index of the section this header belongs to. */
     sectionIndex: number;
-    /** Which page of the header stack shows — `'title'` or `'separator'` (adw-sidebar.c:1449-1455). */
+    /** Which page of the header stack shows — `'title'` or `'separator'`. */
     kind: 'title' | 'separator';
     /** The section title (`''` for a separator header). */
     title: string;
-    /** True only for the section owning the FIRST rendered row — the `.first` class (adw-sidebar.c:1526). */
+    /** True only for the section owning the FIRST rendered row — the `.first` class. */
     first: boolean;
 }
 /** Payload of a `notify::selected` re-emit. */
@@ -91,67 +88,58 @@ export interface SidebarActivation {
     /** The index that was clicked, echoed back unchanged. */
     index: number;
     /**
-     * Whether a row was actually activated. False when `index` addresses no
-     * rendered, enabled row — libadwaita's callbacks run off an existing,
-     * sensitive `GtkListBoxRow`, so there is nothing to activate otherwise.
+     * Whether a row was actually activated. False when `index` addresses no rendered, enabled
+     * row — libadwaita's callbacks run off an existing, sensitive `GtkListBoxRow`.
      */
     activated: boolean;
     /** Whether the selection moved. `activated && !selectionChanged` is a re-click of the current row. */
     selectionChanged: boolean;
 }
-/** Per-instance subscriber, same shape as `ComboStateListener` (rows.ts:114). */
+/** Per-instance subscriber, same shape as `ComboStateListener` (rows.ts). */
 export type SidebarStateListener = (change: SidebarSelectionChange) => void;
 /**
- * The TS stand-in for `GtkFilter` on `AdwSidebar:filter` (adw-sidebar.c:3127).
+ * The TS stand-in for `GtkFilter` on `AdwSidebar:filter`.
  *
  * Decides only what is RENDERED and whether the sidebar counts as empty — never
  * the selection index space, which counts the unfiltered model.
  */
 export type SidebarItemFilter = (item: AdwSidebarItemSpec, index: number) => boolean;
 /**
- * The out-of-range rule, and the one all three implementations disagreed on:
- * anything that is not a valid position becomes NO SELECTION — never the
- * nearest in-range index.
- *
- * `adw_sidebar_set_selected` (adw-sidebar.c:3028-3029) is literally
- * `if (selected >= self->n_items) selected = GTK_INVALID_LIST_POSITION;`. A
- * negative input agrees with that for free: as a `guint`, `-7` is `4294967289`,
- * which is `>= n_items` for any real sidebar.
+ * The out-of-range rule: anything that is not a valid position becomes NO SELECTION — never
+ * the nearest in-range index. `adw_sidebar_set_selected` is literally
+ * `if (selected >= self->n_items) selected = GTK_INVALID_LIST_POSITION;`, and a negative
+ * input agrees with that for free: as a `guint`, `-7` is `4294967289`, which is
+ * `>= n_items` for any real sidebar.
  *
- * Non-integers and `NaN` are rejected rather than truncated. C cannot express
- * them, so there is no ground truth to copy; rejecting is the reading that
- * matches "not a valid position is no position", and it is what stops
- * `sidebar.selected = 1.5` from leaving the NativeScript port highlighting no
- * row while reporting a selection.
+ * Non-integers and `NaN` are rejected rather than truncated. C cannot express them, so
+ * there is no ground truth to copy; rejecting matches "not a valid position is no
+ * position", and it stops `sidebar.selected = 1.5` from highlighting no row while still
+ * reporting a selection.
  */
 export declare function clampSidebarSelection(index: number, count: number): number;
 /**
- * Where the selection lands after the item model spliced — `items_changed_cb`
- * (adw-sidebar.c:2246-2284), which neither renderer implemented.
+ * Where the selection lands after the item model spliced — `items_changed_cb`.
  *
  * Four cases, in the C code's order:
- *   1. `0 → n` auto-selects index 0 and notifies (adw-sidebar.c:2270-2273);
- *   2. a splice covering the selected index clears it (adw-sidebar.c:2275-2278);
- *   3. a splice at or before it shifts by `added - removed` (adw-sidebar.c:2280-2283);
+ *   1. `0 → n` auto-selects index 0 and notifies;
+ *   2. a splice covering the selected index clears it;
+ *   3. a splice at or before it shifts by `added - removed`;
  *   4. a splice after it changes nothing.
  *
- * The comparisons run in the UNSIGNED domain (`>>> 0`) because that is where C
- * runs them: with no selection, `selected` is `G_MAXUINT`, so case 2 can never
- * fire and case 3 wraps. That wraparound is REPRODUCED, not repaired — inserting
- * two items above a selection-less sidebar genuinely selects index 1 in GTK, and
- * a renderer that "fixed" it would stop matching the toolkit it mirrors.
+ * The comparisons run in the UNSIGNED domain (`>>> 0`) because that is where C runs them:
+ * with no selection, `selected` is `G_MAXUINT`, so case 2 can never fire and case 3 wraps.
+ * That wraparound is REPRODUCED, not repaired — inserting two items above a selection-less
+ * sidebar genuinely selects index 1 in GTK.
  */
 export declare function adjustSidebarSelection(selected: number, oldCount: number, newCount: number, position: number, removed: number, added: number): number;
 /**
- * Flatten the sections into the item model, the way `items_changed_cb`'s section
- * walk does: `set_first_index (section, current); current += get_n_items (section)`
- * (adw-sidebar.c:2261-2267).
- *
- * `sectionFirstIndex[i]` is `adw_sidebar_section_get_first_index` for section
- * `i` — a zero-item section advances nothing, so it shares its successor's index.
+ * Flatten the sections into the item model, the way `items_changed_cb`'s section walk does:
+ * `set_first_index (section, current); current += get_n_items (section)`.
  *
- * With a `filter`, `items` is the RENDERED subset while every `index` stays in
- * the unfiltered space; `sectionFirstIndex` is likewise unfiltered.
+ * `sectionFirstIndex[i]` is `adw_sidebar_section_get_first_index` for section `i` — a
+ * zero-item section advances nothing, so it shares its successor's index. With a `filter`,
+ * `items` is the RENDERED subset while every `index` (and `sectionFirstIndex`) stays in the
+ * unfiltered space.
  */
 export declare function flattenSidebarItems(sections: readonly AdwSidebarSectionSpec[], filter?: SidebarItemFilter | null): {
     items: SidebarFlatItem[];
@@ -160,28 +148,25 @@ export declare function flattenSidebarItems(sections: readonly AdwSidebarSection
 /**
  * The headers that actually get drawn, in render order.
  *
- * In sidebar mode a header is a property OF A ROW (`gtk_list_box_row_set_header`,
- * adw-sidebar.c:1563), so a section with no rows contributes none; in page mode
- * the group's `visible` is bound to `filtered n-items > 0` (adw-sidebar.c:1780-1781),
- * which comes to the same thing. Either way it is the sections that RENDER
- * something that produce headers — not the declared section list, which is what
- * the web port used and why an empty leading section drew a stray separator.
+ * In sidebar mode a header is a property OF A ROW (`gtk_list_box_row_set_header`), so a
+ * section with no rows contributes none; in page mode the group's `visible` is bound to
+ * `filtered n-items > 0`, which comes to the same thing. Either way it is the sections that
+ * RENDER something that produce headers, NOT the declared section list — deriving from the
+ * declared list draws a stray separator for an empty leading section.
  *
- * The section owning the first rendered row gets `first: true`; when that
- * section has no title its header is bound to `string_is_not_empty(title)` and
- * therefore invisible (adw-sidebar.c:1521-1527), so it is omitted entirely.
+ * The section owning the first rendered row gets `first: true`; when that section has no
+ * title its header is bound to `string_is_not_empty(title)` and therefore invisible, so it
+ * is omitted entirely.
  */
 export declare function sidebarHeaders(sections: readonly AdwSidebarSectionSpec[], filter?: SidebarItemFilter | null): SidebarHeaderSpec[];
 /**
  * The sidebar state machine both renderers drive.
  *
- * Programmatic changes ({@link setSelected}, {@link setSections},
- * {@link insertSection}, {@link removeSectionAt}, {@link removeAllSections})
- * notify with `interactive: false`; {@link activate} — the row click — notifies
- * with `interactive: true` and applies the selection BEFORE reporting the
- * activation, matching GtkListBox's `row-selected`-then-`row-activated` order
- * (adw-sidebar.c:2188-2191) and page mode's `set_selected`-then-emit
- * (`boxed_row_activated_cb`, adw-sidebar.c:1672-1673).
+ * Programmatic changes ({@link setSelected}, {@link setSections}, {@link insertSection},
+ * {@link removeSectionAt}, {@link removeAllSections}) notify with `interactive: false`;
+ * {@link activate} — the row click — notifies with `interactive: true` and applies the
+ * selection BEFORE reporting the activation, matching GtkListBox's
+ * `row-selected`-then-`row-activated` order and page mode's `set_selected`-then-emit.
  */
 export declare class SidebarState {
     private _mode;
@@ -196,22 +181,21 @@ export declare class SidebarState {
     /** Subscribe to selection changes. Returns an unsubscribe function. */
     subscribe(listener: SidebarStateListener): () => void;
     private _emit;
-    /** Store an already-derived index; notify only on a real change (adw-sidebar.c:3031-3032). */
+    /** Store an already-derived index; notify only on a real change. */
     private _applySelected;
     /** Recompute everything derived from `sections` + `filter`. */
     private _invalidate;
-    /** The current look/behaviour. Defaults to `'sidebar'` (adw-sidebar.c:2860). */
+    /** The current look/behaviour. Defaults to `'sidebar'`. */
     get mode(): AdwSidebarMode;
     /**
      * Switch mode. Returns whether it changed — `adw_sidebar_set_mode` early-returns
-     * on the current value (adw-sidebar.c:2968-2969). Never touches the selection.
+     * on the current value. Never touches the selection.
      */
     setMode(mode: AdwSidebarMode): boolean;
     /**
-     * Whether the selection is PAINTED. Page mode tracks the selection but shows
-     * no selected row: its rows are plain `AdwActionRow`s in a boxed list
-     * (`create_boxed_row`, adw-sidebar.c:1676) and the mode is documented as
-     * "the selection is invisible, but still tracked" (adw-sidebar.c:2948-2951).
+     * Whether the selection is PAINTED. Page mode tracks the selection but shows no selected
+     * row: its rows are plain `AdwActionRow`s in a boxed list (`create_boxed_row`) and the
+     * mode is documented as "the selection is invisible, but still tracked".
      */
     get selectionVisible(): boolean;
     /** The declared sections. */
@@ -219,59 +203,52 @@ export declare class SidebarState {
     /**
      * Replace every section at once — the renderers' "here is my whole tree" call.
      *
-     * Equivalent to `adw_sidebar_remove_all()` followed by appending each section,
-     * i.e. two splices: everything removed (which clears the selection via
-     * adw-sidebar.c:2275-2278) and everything added (which re-runs the `0 → n`
-     * auto-select of index 0 at adw-sidebar.c:2270-2273). They are coalesced into
-     * ONE notification, because one property write should produce one change.
+     * Equivalent to `adw_sidebar_remove_all()` followed by appending each section, i.e. two
+     * splices: everything removed (which clears the selection) and everything added (which
+     * re-runs the `0 → n` auto-select of index 0). Coalesced into ONE notification, because
+     * one property write should produce one change.
      */
     setSections(sections: readonly AdwSidebarSectionSpec[]): void;
     /**
-     * Insert a section, returning the index it landed at.
-     *
-     * `adw_sidebar_insert` appends when `position` is negative OR at/past the end
-     * (adw-sidebar.c:3358-3364) — so on a two-section sidebar, positions `-1`,
+     * Insert a section, returning the index it landed at. `adw_sidebar_insert` appends when
+     * `position` is negative OR at/past the end — so on a two-section sidebar, positions `-1`,
      * `2` and `5` all append, and position `2` is NOT an "insert at 2".
      */
     insertSection(section: AdwSidebarSectionSpec, position: number): number;
     /**
      * Remove the section at `index`. Returns false for an index that addresses no
      * section — `adw_sidebar_remove` warns and returns when the section is not
-     * found (adw-sidebar.c:3387-3393), changing nothing.
+     * found, changing nothing.
      */
     removeSectionAt(index: number): boolean;
-    /** `adw_sidebar_remove_all` (adw-sidebar.c:3417) — one splice removing every item. */
+    /** `adw_sidebar_remove_all` — one splice removing every item. */
     removeAllSections(): void;
     /**
      * Re-derive the item model after an ITEM's own properties changed in place.
      *
-     * libadwaita has no such call because it does not need one: title, subtitle
-     * and icon are live `g_object_bind_property` bindings straight onto the
-     * labels (adw-sidebar.c:1409-1421) and `notify::icon-name` goes to
-     * `notify_icon_cb` (:1393-1397) — none of them runs through
-     * `items_changed_cb`, so the selection cannot move. This method is the same
-     * contract for renderers that hand `SidebarState` mutable specs: the derived
-     * flags are recomputed, the selection is untouched, nothing is emitted.
-     * Both ports ignored post-construction item changes entirely.
+     * libadwaita needs no such call: title, subtitle and icon are live
+     * `g_object_bind_property` bindings straight onto the labels and `notify::icon-name` goes
+     * to `notify_icon_cb` — none of them runs through `items_changed_cb`, so the selection
+     * cannot move. Same contract here for renderers that hand `SidebarState` mutable specs:
+     * the derived flags are recomputed, the selection is untouched, nothing is emitted.
      */
     refresh(): void;
-    /** `adw_sidebar_get_section` — `undefined` past the end (adw-sidebar.c:3297-3298). */
+    /** `adw_sidebar_get_section` — `undefined` past the end. */
     sectionAt(index: number): AdwSidebarSectionSpec | undefined;
     /** `adw_sidebar_section_get_first_index` — 0 for a section that is not in this sidebar. */
     sectionFirstIndex(sectionIndex: number): number;
-    /** Number of items in the UNFILTERED model — the selection index space (adw-sidebar.c:2255). */
+    /** Number of items in the UNFILTERED model — the selection index space. */
     get count(): number;
     /** The full flattened item model, in flat-index order. */
     get items(): readonly SidebarFlatItem[];
-    /** `adw_sidebar_get_item` — `undefined` for `index >= n_items` (adw-sidebar.c:3256). */
+    /** `adw_sidebar_get_item` — `undefined` for `index >= n_items`. */
     itemAt(index: number): AdwSidebarItemSpec | undefined;
     /** The current item filter, or `null`. */
     get filter(): SidebarItemFilter | null;
     /**
-     * Set the item filter — `adw_sidebar_set_filter` (adw-sidebar.c:3127-3139).
-     *
-     * It only swaps the filter on the `GtkFilterListModel`; the selection is
-     * never re-derived, so a selected item that filters out stays selected.
+     * Set the item filter — `adw_sidebar_set_filter`. It only swaps the filter on the
+     * `GtkFilterListModel`; the selection is never re-derived, so a selected item that filters
+     * out stays selected.
      */
     setFilter(filter: SidebarItemFilter | null): void;
     /** The items that pass the filter — the rows a renderer actually builds. */
@@ -279,14 +256,13 @@ export declare class SidebarState {
     /** The headers to draw, derived from the sections that render at least one row. */
     get headers(): readonly SidebarHeaderSpec[];
     /**
-     * The `.empty` / placeholder state — `update_placeholder` counts the FILTERED
-     * model (adw-sidebar.c:1828, :1839-1842), so a fully filtered-out sidebar is
-     * empty even though its selection index space is not.
+     * The `.empty` / placeholder state — `update_placeholder` counts the FILTERED model, so a
+     * fully filtered-out sidebar is empty even though its selection index space is not.
      */
     get isEmpty(): boolean;
     /** The selected flat index, or {@link ADW_SIDEBAR_NO_SELECTION}. */
     get selected(): number;
-    /** `adw_sidebar_get_selected_item` (adw-sidebar.c:3092). */
+    /** `adw_sidebar_get_selected_item`. */
     get selectedItem(): AdwSidebarItemSpec | undefined;
     /**
      * Programmatic selection — {@link clampSidebarSelection} then notify with
@@ -294,15 +270,13 @@ export declare class SidebarState {
      */
     setSelected(index: number): boolean;
     /**
-     * A row click. Selects (notifying `interactive: true` if that moved) and then
-     * reports the activation, which libadwaita emits on EVERY click including a
-     * re-click of the already-selected row (`row_activated_cb`, adw-sidebar.c:1601-1612).
-     * That unconditional emit is how re-tapping the current row reveals the content
-     * pane of a split view (adw-sidebar.c:73-75) — the NativeScript port had no
-     * activation path at all, so that gesture did nothing there.
+     * A row click. Selects (notifying `interactive: true` if that moved) and then reports the
+     * activation, which libadwaita emits on EVERY click including a re-click of the
+     * already-selected row (`row_activated_cb`). That unconditional emit is how re-tapping the
+     * current row reveals the content pane of a split view.
      *
-     * A row that is filtered out, `visible: false`, or `enabled: false` is not
-     * activatable: it either has no `GtkListBoxRow` or has an insensitive one.
+     * A row that is filtered out, `visible: false`, or `enabled: false` is not activatable: it
+     * either has no `GtkListBoxRow` or has an insensitive one.
      */
     activate(index: number): SidebarActivation;
 }

package/lib/types/spinner.d.ts

@@ -1,84 +1,66 @@
-/** `SPIN_DURATION_MS` (adw-spinner-paintable.c:20) — one full turn. */
+/** `SPIN_DURATION_MS` — one full turn. */
 export declare const ADW_SPINNER_SPIN_DURATION_MS = 1200;
 /**
- * `START_ANGLE` (adw-spinner-paintable.c:21) — a fixed phase offset added to
- * both arc ends (:379-380), so the figure does not start at 3 o'clock.
- *
- * Neither port had it, which is a constant rotation error rather than a wrong
- * speed — invisible in a still frame, visible against a GTK spinner beside it.
+ * `START_ANGLE` — a fixed phase offset added to both arc ends, so the figure does not
+ * start at 3 o'clock. Omitting it is a constant rotation error rather than a wrong
+ * speed: invisible in a still frame, visible against a GTK spinner beside it.
  */
 export declare const ADW_SPINNER_START_ANGLE: number;
 /**
- * `CIRCLE_OPACITY` (adw-spinner-paintable.c:22) — the track is the WIDGET's
- * colour at 15%, not a hardcoded grey.
- *
- * The browser port used `rgba(127, 127, 127, 0.25)`: too dark, and
- * hue-independent, so a spinner on a coloured background lost its track
- * relationship entirely.
+ * `CIRCLE_OPACITY` — the track is the WIDGET's colour at 15%, not a hardcoded grey,
+ * so a spinner on a coloured background keeps its track relationship.
  */
 export declare const ADW_SPINNER_TRACK_OPACITY = 0.15;
-/** `MIN_ARC_LENGTH` (:24) — GSK refuses to draw an arc shorter than this. */
+/** `MIN_ARC_LENGTH` — GSK refuses to draw an arc shorter than this. */
 export declare const ADW_SPINNER_MIN_ARC_LENGTH: number;
-/** `MAX_ARC_LENGTH` (:25) — the LERP TARGET, 162°. The drawn arc peaks at 102.8°. */
+/** `MAX_ARC_LENGTH` — the LERP TARGET, 162°. The drawn arc peaks at 102.8°. */
 export declare const ADW_SPINNER_MAX_ARC_LENGTH: number;
-/** `IDLE_DISTANCE` (:26). */
+/** `IDLE_DISTANCE`. */
 export declare const ADW_SPINNER_IDLE_DISTANCE: number;
-/** `OVERLAP_DISTANCE` (:27). */
+/** `OVERLAP_DISTANCE`. */
 export declare const ADW_SPINNER_OVERLAP_DISTANCE: number;
-/** `EXTEND_DISTANCE` (:28). */
+/** `EXTEND_DISTANCE`. */
 export declare const ADW_SPINNER_EXTEND_DISTANCE: number;
-/** `CONTRACT_DISTANCE` (:29). */
+/** `CONTRACT_DISTANCE`. */
 export declare const ADW_SPINNER_CONTRACT_DISTANCE: number;
 /**
- * `N_CYCLES` (:33) — how many full TURNS the animation runs before repeating.
+ * `N_CYCLES` — how many full TURNS the animation runs before repeating.
  *
- * The C states the constraint it satisfies: the cycle length
- * `IDLE + EXTEND + CONTRACT - OVERLAP` must divide `N_CYCLES * 2pi` exactly, or
- * the arc would jump when the animation loops. It does — 53 turns is 40 arc
- * cycles — and {@link ADW_SPINNER_CYCLES_PER_LOOP} is that quotient, asserted
- * rather than assumed.
+ * The constraint the C states: the cycle length `IDLE + EXTEND + CONTRACT - OVERLAP`
+ * must divide `N_CYCLES * 2pi` exactly, or the arc jumps when the animation loops. It
+ * does — 53 turns is 40 arc cycles — and {@link ADW_SPINNER_CYCLES_PER_LOOP} is that
+ * quotient, asserted rather than assumed.
  */
 export declare const ADW_SPINNER_N_CYCLES = 53;
 /**
  * One arc cycle, in radians of base angle:
- * `IDLE_DISTANCE + EXTEND_DISTANCE + CONTRACT_DISTANCE - OVERLAP_DISTANCE`
- * (adw-spinner-paintable.c:112, :130).
+ * `IDLE_DISTANCE + EXTEND_DISTANCE + CONTRACT_DISTANCE - OVERLAP_DISTANCE`.
  */
 export declare const ADW_SPINNER_CYCLE_LENGTH: number;
 /** Whole arc cycles per animation loop — an integer, which is the C's constraint. */
 export declare const ADW_SPINNER_CYCLES_PER_LOOP: number;
 /**
  * The base angle a NON-animating spinner is drawn at — `EXTEND_DISTANCE -
- * OVERLAP_DISTANCE / 2` (adw-spinner-paintable.c:375-376), i.e. `pi * 0.75`.
- *
- * Reached whenever there is no animation object: before the paintable has a
- * widget, and in a still frame. Both ports left the resting pose undefined, so a
- * spinner that had not started yet drew whatever its keyframe origin happened to
- * be.
+ * OVERLAP_DISTANCE / 2`, i.e. `pi * 0.75`. Reached whenever there is no animation
+ * object: before the paintable has a widget, and in a still frame.
  */
 export declare const ADW_SPINNER_STILL_PROGRESS: number;
 /**
- * `normalize_angle` (adw-spinner-paintable.c:97-107) — fold into `[0, 2pi]`.
- *
- * The C loops rather than taking a modulo, and the boundary follows: it stops at
- * `angle > G_PI * 2`, so exactly `2pi` is left alone where a modulo would give 0.
+ * `normalize_angle` — fold into `[0, 2pi]`. The C loops rather than taking a modulo,
+ * and the boundary follows: it stops at `angle > G_PI * 2`, so exactly `2pi` is left
+ * alone where a modulo would give 0.
  */
 export declare function normalizeSpinnerAngle(angle: number): number;
 /**
- * `get_arc_start` (adw-spinner-paintable.c:109-125) — the trailing end of the
- * arc, relative to the base angle.
- *
- * The `- angle * MAX_ARC_LENGTH / l` term is the drift that makes the arc
- * advance around the circle as it breathes; without it the figure would pulse in
- * place.
+ * `get_arc_start` — the trailing end of the arc, relative to the base angle. The
+ * `- angle * MAX_ARC_LENGTH / l` term is the drift that makes the arc advance around
+ * the circle as it breathes; without it the figure would pulse in place.
  */
 export declare function spinnerArcStart(angle: number): number;
 /**
- * `get_arc_end` (adw-spinner-paintable.c:127-145) — the leading end.
- *
- * Its phase is offset by `EXTEND_DISTANCE - OVERLAP_DISTANCE`: the end only
- * starts moving once the start has extended past the overlap, which is what
- * makes the arc grow before it slides.
+ * `get_arc_end` — the leading end. Its phase is offset by
+ * `EXTEND_DISTANCE - OVERLAP_DISTANCE`: the end only starts moving once the start has
+ * extended past the overlap, which is what makes the arc grow before it slides.
  */
 export declare function spinnerArcEnd(angle: number): number;
 /** The two ends of the drawn arc, in radians clockwise from 3 o'clock. */
@@ -88,30 +70,26 @@ export interface SpinnerArc {
     /** Leading end, folded into `[0, 2pi]`. */
     end: number;
     /**
-     * Arc length along the circle, `start - end` unwrapped into `(0, 2pi]`.
-     *
-     * The segment runs from `end` to `start` (`gsk_path_builder_add_segment
-     * (builder, circle, &end_point, &start_point)`, :395) — the naming is the C's
-     * and it is the opposite way round from what "start" suggests.
+     * Arc length along the circle, `start - end` unwrapped into `(0, 2pi]`. The segment
+     * runs from `end` to `start` (`gsk_path_builder_add_segment (builder, circle,
+     * &end_point, &start_point)`) — the naming is the C's and it is the opposite way
+     * round from what "start" suggests.
      */
     length: number;
 }
 /**
- * The arc for a base angle — `adw_spinner_paintable_snapshot_with_weight`
- * (adw-spinner-paintable.c:373-383).
+ * The arc for a base angle — `adw_spinner_paintable_snapshot_with_weight`.
  *
- * `progress` is the animation's value: 0 at the start of a loop, rising linearly
- * to `N_CYCLES * 2pi`. A renderer that has no animation passes
+ * `progress` is the animation's value: 0 at the start of a loop, rising linearly to
+ * `N_CYCLES * 2pi`. A renderer with no animation passes
  * {@link ADW_SPINNER_STILL_PROGRESS}.
  */
 export declare function spinnerArc(progress: number): SpinnerArc;
 /**
  * The animation's value after `elapsedMs` — `adw_timed_animation_new (widget, 0,
- * N_CYCLES * 2pi, SPIN_DURATION_MS * N_CYCLES, target)` with `ADW_LINEAR` easing
- * and `repeat_count = 0`, i.e. forever (adw-spinner-paintable.c:532-540).
- *
- * A linear ramp over the whole loop reduces to one turn per
- * {@link ADW_SPINNER_SPIN_DURATION_MS}; the loop length only decides where it
+ * N_CYCLES * 2pi, SPIN_DURATION_MS * N_CYCLES, target)` with `ADW_LINEAR` easing and
+ * `repeat_count = 0`, i.e. forever. A linear ramp over the whole loop reduces to one
+ * turn per {@link ADW_SPINNER_SPIN_DURATION_MS}; the loop length only decides where it
  * restarts, and it restarts at a point the arc phase agrees with.
  */
 export declare function spinnerProgressAt(elapsedMs: number): number;