@gjsify/adwaita-core 0.36.0 → 0.37.0

package/lib/types/carousel.d.ts

@@ -1,14 +1,10 @@
-/** `SCROLL_TIMEOUT_DURATION` (adw-carousel.c:22) — the lockout after a wheel step. */
+/** `SCROLL_TIMEOUT_DURATION` — the lockout after a wheel step. */
 export declare const CAROUSEL_SCROLL_TIMEOUT_MS = 150;
 /**
- * How close to a snap point counts as "the scroll has arrived", in pages —
- * see {@link CarouselState.settleIfArrived}.
- *
- * Not a libadwaita constant: C knows a scroll finished because its own spring
- * animation says so, while a renderer that lets the platform scroll (CSS
- * scroll-snap, a NativeScript `ScrollView`) has only the offset, which lands on
- * a sub-pixel value an exact compare would never match. A hundredth of a page is
- * invisible and far tighter than the 0.02 the web port's old heuristic used.
+ * How close to a snap point counts as "arrived", in pages — {@link
+ * CarouselState.settleIfArrived}. Not a libadwaita constant: C knows a scroll finished
+ * from its own spring animation, while a renderer that lets the platform scroll (CSS
+ * scroll-snap, a NativeScript `ScrollView`) has only a sub-pixel offset.
  */
 export declare const CAROUSEL_SETTLE_EPSILON = 0.01;
 /** Which axis the carousel pages along — `GtkOrientable:orientation`. */
@@ -16,16 +12,16 @@ export type CarouselOrientation = 'horizontal' | 'vertical';
 /** One keynav / wheel step — `AdwNavigationDirection`. */
 export type CarouselDirection = 'back' | 'forward';
 /**
- * The `GdkInputSource` cases `scroll_cb` distinguishes (adw-carousel.c:537-542).
+ * The `GdkInputSource` cases `scroll_cb` distinguishes.
  * Everything that is neither a touchpad nor a mouse behaves the same, so the
  * three-way split is the whole vocabulary the rule needs.
  */
 export type CarouselScrollSource = 'touchpad' | 'mouse' | 'other';
 /** The scrollable interval a position is clamped into — `get_range`. */
 export interface CarouselRange {
-    /** Always 0 (adw-carousel.c:215-216). */
+    /** Always 0. */
     lower: number;
-    /** `MAX (0, position_shift + last snap point)` (:219). */
+    /** `MAX (0, position_shift + last snap point)`. */
     upper: number;
 }
 /** Input to {@link carouselWheelStep} — one scroll event, already normalized. */
@@ -52,115 +48,83 @@ export interface CarouselReorderShiftInput {
 }
 /**
  * The snap point of every page, from their reveal sizes:
- * `snapPoint[i] = (Σ_{j≤i} size[j]) − 1` (`adw_carousel_size_allocate`,
- * adw-carousel.c:777-789).
+ * `snapPoint[i] = (Σ_{j≤i} size[j]) − 1` (`adw_carousel_size_allocate`).
  *
- * Sizes are reveal FRACTIONS, not pixels, so mid-animation snap points are
- * fractional — and a page that was just inserted (size 0, :1385) pushes the
- * first snap point NEGATIVE. That is legal and load-bearing: it is what makes
- * the following pages keep their positions while the new one grows in.
+ * Sizes are reveal FRACTIONS, so mid-animation snap points are fractional and a
+ * just-inserted page (size 0) pushes the first one NEGATIVE — legal, and what keeps the
+ * following pages in place while the new one grows in.
  */
 export declare function carouselSnapPoints(sizes: readonly number[]): number[];
 /**
  * The inverse of {@link carouselSnapPoints}: `sizes[0] = points[0] + 1` and
- * `sizes[i] = points[i] − points[i−1]` (adw-carousel-indicator-dots.c:189-191).
- *
- * This is the ONLY channel through which an indicator learns per-page reveal
- * state — `AdwSwipeable` hands out snap points, never sizes — so an indicator
- * that wants to fade a page in has to reconstruct them.
+ * `sizes[i] = points[i] − points[i−1]`. The ONLY channel by which an indicator learns
+ * per-page reveal state, since `AdwSwipeable` hands out snap points and never sizes.
  */
 export declare function carouselSizesFromSnapPoints(points: readonly number[]): number[];
 /**
- * The scrollable range — `get_range` (adw-carousel.c:207-220).
- *
- * `positionShift` is the pending compensation an insert/remove/reorder
- * accumulates before the next allocation; it is part of the bound because C adds
- * it there (:219), so a shift large enough to cancel the last snap point
- * collapses the range to `[0, 0]` rather than going negative.
+ * The scrollable range — `get_range`. `positionShift` is the pending compensation an
+ * insert/remove/reorder accumulates before the next allocation, and is part of the bound
+ * because C adds it there: a shift large enough to cancel the last snap point collapses
+ * the range to `[0, 0]` rather than going negative.
  */
 export declare function carouselRange(snapPoints: readonly number[], positionShift?: number): CarouselRange;
 /**
- * `set_position`'s guard (adw-carousel.c:269) — the single clamp every position
- * write in the widget goes through.
- *
- * Fractional positions pass through untouched: this bounds the scroll, it does
- * not snap to a page. Uses GLib's `CLAMP`, which tests the HIGH bound first —
- * the range here can never invert, but the primitive is the one C uses.
+ * `set_position`'s guard — the single clamp every position write goes through. Fractional
+ * positions pass through untouched: this bounds the scroll, it does not snap to a page.
+ * Uses GLib's `CLAMP`, which tests the HIGH bound first.
  */
 export declare function carouselClampPosition(position: number, snapPoints: readonly number[], positionShift?: number): number;
 /**
  * The index of the snap point nearest `position`, `-1` for an empty list —
- * `get_closest_child_at` (adw-carousel.c:180-205).
- *
- * The tie-break is the whole point: C replaces its current best only on a strict
- * `>`, so at an exact half-way position the EARLIER page wins. Exported rather
- * than inlined because `get_closest_child_at` is called with four different
- * include/exclude combinations of adding and removing children, and each caller
- * must get the same tie-break.
+ * `get_closest_child_at`. C replaces its current best only on a strict `>`, so at an
+ * exact half-way position the EARLIER page wins. Exported because C calls it with four
+ * different adding/removing include combinations and each must get the same tie-break.
  */
 export declare function carouselClosestSnapPoint(position: number, snapPoints: readonly number[]): number;
 /**
- * The page `position` settles on — `get_page_at_position` (adw-carousel.c:222-239):
- * clamp into the range first, then take the nearest snap point.
- *
- * Returns `-1` for an empty carousel, matching `find_child_index` (:155) and the
- * `page-changed` documentation, which spells that case out (:1150-1151).
- *
- * Rounds an exact `.5` DOWN, via {@link carouselClosestSnapPoint}. Do not
- * "simplify" this to `Math.round`: that is what both ports did, and it disagrees
+ * The page `position` settles on — `get_page_at_position`: clamp into the range, then
+ * take the nearest snap point. `-1` for an empty carousel. Rounds an exact `.5` DOWN via
+ * {@link carouselClosestSnapPoint}; do not "simplify" it to `Math.round`, which disagrees
  * with GTK on every half-way position.
  */
 export declare function carouselPageAtPosition(position: number, snapPoints: readonly number[]): number;
 /**
  * The page an arrow key moves to, or `null` when the step is refused —
- * `navigate_to_direction` (adw-carousel.c:475-508).
+ * `navigate_to_direction`.
  *
- * `null` means C returned `FALSE`: an empty carousel, or already at the bound in
- * that direction. Home/End are the same operation with targets `0` and
- * `nPages − 1` (`keynav_bounds_cb`, :641-674).
- *
- * The returned index is C's raw `index ± 1` and is NOT clamped — only the WHEEL
- * path clamps (:567). With a position inside `[0, nPages − 1]` it is always in
- * range; outside it, `adw_carousel_get_nth_page`'s precondition (:1616) is what
- * rejects it, which is exactly what {@link CarouselState.scrollTo} does.
+ * `null` means C returned `FALSE`: an empty carousel, or already at the bound in that
+ * direction. Home/End are the same operation with targets `0` and `nPages − 1`
+ * (`keynav_bounds_cb`). The returned index is C's raw `index ± 1`, NOT clamped — only the
+ * WHEEL path clamps; outside `[0, nPages − 1]` `adw_carousel_get_nth_page`'s precondition
+ * rejects it, as {@link CarouselState.scrollTo} does.
  */
 export declare function carouselNavigateTarget(position: number, nPages: number, direction: CarouselDirection): number | null;
 /**
- * How many pages one scroll event moves — `scroll_cb`'s axis rules
- * (adw-carousel.c:537-559). `0` means "propagate the event", the only case where
- * C returns `GDK_EVENT_PROPAGATE` from this part of the handler.
- *
- * Three rules, all of which one port or the other loses:
- *   - a TOUCHPAD source is always ignored (:537-538), because its kinetic
- *     scrolling is already driving the swipe tracker;
- *   - the vertical delta counts when the carousel is vertical OR the source is a
- *     mouse — "mice often don't have easily accessible horizontal scrolling"
- *     (:540-542, :547-552);
- *   - the horizontal delta is a FALLBACK: consulted only for a horizontal
- *     carousel, and only when the vertical branch produced nothing (:554-559).
- *     The web port dropped it entirely by returning early on `|dy| <= |dx|`.
+ * How many pages one scroll event moves — `scroll_cb`'s axis rules. `0` means "propagate
+ * the event", the only case where C returns `GDK_EVENT_PROPAGATE` here. Three rules:
+ * - a TOUCHPAD source is always ignored, because its kinetic scrolling is already
+ * driving the swipe tracker;
+ * - the vertical delta counts when the carousel is vertical OR the source is a
+ * mouse — "mice often don't have easily accessible horizontal scrolling";
+ * - the horizontal delta is a FALLBACK: consulted only for a horizontal carousel,
+ * and only when the vertical branch produced nothing.
  */
 export declare function carouselWheelStep(input: CarouselWheelInput): -1 | 0 | 1;
 /**
- * How far the position must move so the visible page does not jump when a page
- * is reordered — the `position_shift` delta of `adw_carousel_reorder`
- * (adw-carousel.c:1488-1495).
- *
- * Three branches: the moved page IS the current one (follow it, `newPoint −
- * oldPoint`); it crossed the current position from after to before (`+size`, the
- * content ahead grew by that page); or from before to after (`−size`). Anything
- * that does not cross the position leaves it alone. Every comparison is
- * epsilon-tolerant, because snap points are accumulated sums.
+ * How far the position must move so the visible page does not jump when a page is
+ * reordered — the `position_shift` delta of `adw_carousel_reorder`. Three branches: the
+ * moved page IS the current one (follow it, `newPoint − oldPoint`); it crossed the
+ * position from after to before (`+size`); or from before to after (`−size`). Anything
+ * that does not cross the position leaves it alone.
  */
 export declare function carouselReorderShift(args: CarouselReorderShiftInput): number;
 /**
- * Which of C's three "tell someone" sites a {@link CarouselStateChange} came
- * from. libadwaita has three distinct ones and collapsing them into a single
- * opaque notification would lose information the GObject API has:
- *   - `position` — `set_position` notified `notify::position` (adw-carousel.c:281);
- *   - `n-pages`  — an insert or a remove notified `notify::n-pages` (:1406, :1531);
- *   - `geometry` — only `gtk_widget_queue_allocate` ran: a size or order change
- *     that moved no position (:296, :1498).
+ * Which of C's three notification sites a {@link CarouselStateChange} came from;
+ * collapsing them into one opaque notification would lose what the GObject API has:
+ * - `position` — `set_position` notified `notify::position`;
+ * - `n-pages` — an insert or a remove notified `notify::n-pages`;
+ * - `geometry` — only `gtk_widget_queue_allocate` ran: a size or order change that
+ * moved no position.
  */
 export type CarouselChangeReason = 'position' | 'n-pages' | 'geometry';
 /** Payload of a {@link CarouselState} notification. */
@@ -172,10 +136,9 @@ export interface CarouselStateChange {
     /** {@link carouselPageAtPosition} for the current position; `-1` when empty. */
     page: number;
     /**
-     * `true` for a user navigation (wheel, keynav, an interactive scroll),
-     * `false` for a programmatic or model-driven one. libadwaita notifies
-     * unconditionally (:281) — the flag exists so a bound indicator can tell the
-     * two apart, not so a renderer can drop the notification.
+     * `true` for a user navigation (wheel, keynav, interactive scroll), `false` for a
+     * programmatic one. libadwaita notifies unconditionally — the flag lets a bound
+     * indicator tell the two apart, not a renderer drop the notification.
      */
     interactive: boolean;
     /** Which C notification site this corresponds to. */
@@ -186,12 +149,10 @@ export type CarouselStateListener = (change: CarouselStateChange) => void;
 /** Subscriber for `page-changed` — `index` is `-1` for an empty carousel. */
 export type CarouselPageChangedListener = (index: number) => void;
 /**
- * A scroll the state machine wants performed — the renderer seam, in the shape
- * of `AdwToastQueueHandlers`' `onShow`/`onHide`.
- *
- * The core owns WHICH page is scrolled to (the wheel and keynav paths compute it
- * and no renderer should redo that); the renderer owns HOW, because that is a
- * DOM `scrollTo` on one side and a `scrollToHorizontalOffset` on the other.
+ * A scroll the state machine wants performed — the renderer seam, in the shape of
+ * `AdwToastQueueHandlers`' `onShow`/`onHide`. The core owns WHICH page is scrolled to
+ * and no renderer should redo that; the renderer owns HOW, because that is a DOM
+ * `scrollTo` on one side and a `scrollToHorizontalOffset` on the other.
  */
 export interface CarouselScrollRequest {
     /** Target page index, always a valid index into the non-removing pages. */
@@ -203,36 +164,30 @@ export interface CarouselScrollRequest {
     /** Whether the renderer is expected to animate (and then call `settle()`). */
     animate: boolean;
 }
-/**
- * Construction seams and the libadwaita property DEFAULTS, which both ports got
- * wrong or omitted.
- */
+/** Construction seams and the libadwaita property DEFAULTS. */
 export interface CarouselStateOptions {
-    /** `GtkOrientable:orientation`, default `'horizontal'` (adw-carousel.c:1205). */
+    /** `GtkOrientable:orientation`, default `'horizontal'`. */
     orientation?: CarouselOrientation;
-    /** `AdwCarousel:interactive`, default TRUE (:1051-1054). Gates wheel + keynav. */
+    /** `AdwCarousel:interactive`, default TRUE. Gates wheel + keynav. */
     interactive?: boolean;
-    /** `AdwCarousel:allow-scroll-wheel`, default TRUE (:1103-1106, :1201). */
+    /** `AdwCarousel:allow-scroll-wheel`, default TRUE. */
     allowScrollWheel?: boolean;
-    /** `AdwCarousel:allow-long-swipes`, default FALSE (:1115-1118). */
+    /** `AdwCarousel:allow-long-swipes`, default FALSE. */
     allowLongSwipes?: boolean;
-    /** `AdwCarousel:spacing` in px, default 0 (:1061-1066). Feeds `distance` (:767). */
+    /** `AdwCarousel:spacing` in px, default 0. Feeds `distance`. */
     spacing?: number;
-    /** `AdwCarousel:reveal-duration` in ms, default 0 (:1127-1132, :1206). */
+    /** `AdwCarousel:reveal-duration` in ms, default 0. */
     revealDuration?: number;
     /** Clock for the wheel lockout. Injected, never a global — default `Date.now`. */
     now?: () => number;
     /** Renderer seam invoked for every accepted {@link CarouselState.scrollTo}. */
     onScrollTo?: (request: CarouselScrollRequest) => void;
     /**
-     * Default for `adw_carousel_scroll_to`'s `animate` argument (:1571-1598).
-     *
-     * The core has no animator, so `true` means the RENDERER drives the ramp:
-     * `scrollTo` only issues the {@link CarouselScrollRequest} and waits for the
-     * renderer to feed positions back through {@link CarouselState.setPosition}
-     * and finish with {@link CarouselState.settle}. `false` (the default) is
-     * `do_scroll_to`'s skip path (:1541-1542): the position jumps to the target
-     * and `page-changed` fires at once.
+     * Default for `adw_carousel_scroll_to`'s `animate` argument. The core has no animator,
+     * so `true` means the RENDERER drives the ramp — `scrollTo` issues the
+     * {@link CarouselScrollRequest} and waits for positions fed back through
+     * {@link CarouselState.setPosition} then {@link CarouselState.settle}. `false` (the
+     * default) is `do_scroll_to`'s skip path: the position jumps and `page-changed` fires.
      */
     animateScroll?: boolean;
 }
@@ -249,17 +204,15 @@ export interface CarouselScrollOptions {
  * lockout and the `page-changed` emission, once, for every renderer.
  *
  * The reveal ANIMATION is not here: a renderer feeds its eased values through
- * {@link setPageSize}, and a carousel with the default `reveal-duration` of 0
- * calls {@link skipReveal} instead. What is here is everything that decides what
- * those sizes MEAN — snap points, the range, which page is current, and how far
- * the position has to move so the visible page stays put.
+ * {@link setPageSize}, and a carousel with the default `reveal-duration` of 0 calls
+ * {@link skipReveal} instead.
  *
- * Two array shapes appear and they are not the same length while a removal
- * animates: {@link snapPoints} and {@link sizes} cover every tracked child
- * (`adw_carousel_get_snap_points`, :1260-1283, walks all of them), while
- * {@link nPages} and {@link indexOf} skip the ones being removed
- * (`adw_carousel_get_n_pages`, :1640-1645). That is C, and an indicator that
- * conflated them would drop a dot the moment a page started shrinking.
+ * Two array shapes appear and they are NOT the same length while a removal animates:
+ * {@link snapPoints} and {@link sizes} cover every tracked child
+ * (`adw_carousel_get_snap_points` walks all of them), while {@link nPages} and
+ * {@link indexOf} skip the ones being removed (`adw_carousel_get_n_pages`). That is
+ * C; an indicator that conflated them would drop a dot the moment a page started
+ * shrinking.
  */
 export declare class CarouselState {
     private readonly _children;
@@ -283,10 +236,10 @@ export declare class CarouselState {
     constructor(options?: CarouselStateOptions);
     /** Subscribe to state changes. Returns an unsubscribe function. */
     subscribe(listener: CarouselStateListener): () => void;
-    /** Subscribe to `page-changed` (adw-carousel.c:1153-1165). Returns an unsubscribe function. */
+    /** Subscribe to `page-changed`. Returns an unsubscribe function. */
     onPageChanged(listener: CarouselPageChangedListener): () => void;
     private _emit;
-    /** Number of pages, skipping ones whose removal is still animating (:1640-1645). */
+    /** Number of pages, skipping ones whose removal is still animating. */
     get nPages(): number;
     /** The ids of the pages that count towards {@link nPages}, in order. */
     get ids(): readonly string[];
@@ -294,24 +247,22 @@ export declare class CarouselState {
     get position(): number;
     /** Every tracked child's reveal size, INCLUDING ones being removed. */
     get sizes(): number[];
-    /** Every tracked child's snap point — `adw_carousel_get_snap_points` (:1260-1283). */
+    /** Every tracked child's snap point — `adw_carousel_get_snap_points`. */
     get snapPoints(): number[];
     /** The scrollable range the position is clamped into. */
     get range(): CarouselRange;
     /**
-     * Snap points of the pages that still count — the array every page LOOKUP
-     * runs against, because `get_page_at_position` excludes removing children
-     * (`get_closest_child_at (…, TRUE, FALSE)`, :233) and `find_child_index`
-     * numbers them out too (:146-147).
-     *
-     * Their values still come from the full accumulation, so a shrinking page
+     * Snap points of the pages that still count — the array every page LOOKUP runs
+     * against, because `get_page_at_position` excludes removing children
+     * (`get_closest_child_at (…, TRUE, FALSE)`) and `find_child_index` numbers them out
+     * too. Their values still come from the full accumulation, so a shrinking page
      * keeps pushing the pages after it until it reaches size 0.
      */
     private _visibleSnapPoints;
     /**
      * The page `position` settles on, `-1` when the carousel is empty.
      *
-     * C clamps against the FULL range here (:229-231) while searching only the
+     * C clamps against the FULL range here while searching only the
      * visible children; clamping against the visible points instead cannot
      * change the answer, because snap points ascend and both clamps land at or
      * beyond the last visible one, where the nearest visible point is the same.
@@ -320,70 +271,59 @@ export declare class CarouselState {
     /**
      * Index of the page with `id` among the pages that count, `-1` when it is
      * unknown OR is being removed — `find_child_index (…, count_removing =
-     * FALSE)` skips a removing child before it ever compares (:146-147).
+     * FALSE)` skips a removing child before it ever compares.
      */
     indexOf(id: string): number;
     /**
      * The snap point of the `index`-th page that counts, `undefined` when the
      * index is out of range — `adw_carousel_get_nth_page` followed by reading
-     * `info->snap_point`, which is what `scroll_to` animates towards (:1618,
-     * :392-393).
+     * `info->snap_point`, which is what `scroll_to` animates towards.
      *
      * A renderer needs this to tell "the scroll has arrived" from "the scroll is
      * still moving", and it must not index {@link snapPoints} by a page index to
      * get it: those two arrays disagree while a removal is animating.
      */
     snapPointOf(index: number): number | undefined;
-    /** Full-list index of the `n`-th page that counts, `-1` when out of range — `get_nth_link` (:158-178). */
+    /** Full-list index of the `n`-th page that counts, `-1` when out of range — `get_nth_link`. */
     private _nthLink;
     /** Full-list index of the child nearest `position`, honouring C's include flags. */
     private _closestChildIndex;
     /**
-     * `update_shift_position_flag` (adw-carousel.c:241-258): a page that is at or
-     * BEFORE the currently-shown one must drag the position along as it grows or
-     * shrinks, otherwise the visible page slides sideways under the user.
-     *
-     * The lookup deliberately EXCLUDES adding children and INCLUDES removing
-     * ones (:249), so the position still follows a page that is being removed
-     * while it is the active one.
+     * `update_shift_position_flag`: a page at or BEFORE the currently-shown one must
+     * drag the position along as it grows or shrinks, otherwise the visible page slides
+     * sideways under the user. The lookup deliberately EXCLUDES adding children and
+     * INCLUDES removing ones, so the position still follows a page being removed while
+     * it is the active one.
      */
     private _updateShiftPositionFlag;
-    /** `set_position`'s per-child refresh of the shift flags (adw-carousel.c:274-279). */
+    /** `set_position`'s per-child refresh of the shift flags. */
     private _updateShiftFlags;
     /**
-     * `set_position` (adw-carousel.c:260-282) — clamp, store, refresh the shift
-     * flags, notify. Returns whether the stored value changed; the notification
-     * fires either way, because C's `g_object_notify_by_pspec` at :281 is
-     * unconditional and a bound indicator that only repaints on a CHANGE misses
-     * the settle back onto the page it started from.
+     * `set_position` — clamp, store, refresh the shift flags, notify. Returns whether
+     * the stored value changed; the notification fires either way, because C's
+     * `g_object_notify_by_pspec` is unconditional and a bound indicator that only
+     * repaints on a CHANGE misses the settle back onto the page it started from.
      *
-     * A non-finite position is refused outright and recorded in
-     * {@link diagnostics}. `AdwCarousel:position` is a double declared over
-     * `[0, G_MAXDOUBLE]` (:1036-1041), so NaN is outside the property's own
-     * contract — and letting one through is what left the NativeScript port with
-     * a NaN position and no active dot at all.
+     * A non-finite position is refused outright and recorded in {@link diagnostics}:
+     * `AdwCarousel:position` is a double declared over `[0, G_MAXDOUBLE]`, so NaN is
+     * outside the property's own contract.
      */
     setPosition(position: number, interactive?: boolean): boolean;
     /**
-     * Scroll to a page — `adw_carousel_get_nth_page` + `scroll_to` (:1609-1621,
-     * :378-397). Returns whether the scroll was accepted.
+     * Scroll to a page — `adw_carousel_get_nth_page` + `scroll_to`. Returns whether the
+     * scroll was accepted.
      *
      * Out-of-range, negative and non-integer indices are REFUSED, not clamped:
-     * `get_nth_page` fails its precondition and hands `scroll_to` a NULL widget,
-     * which returns before touching anything (:385-386). Only the wheel path
-     * clamps, and it does so before it gets here (:567). The refusal is recorded
-     * in {@link diagnostics}, which is where `scrollToPage(NaN)` now ends up
-     * instead of in the position.
+     * `get_nth_page` fails its precondition and hands `scroll_to` a NULL widget, which
+     * returns before touching anything. Only the wheel path clamps, and it does so
+     * before it gets here. The refusal is recorded in {@link diagnostics}.
      */
     scrollTo(index: number, options?: CarouselScrollOptions): boolean;
     /**
-     * `scroll_animation_done_cb` (adw-carousel.c:363-376) — the scroll has come to
-     * rest, so emit `page-changed` with the page the position landed on.
-     *
-     * Emitted after EVERY completed scroll, including one that settles back onto
-     * the page it started from, and with index `-1` when the carousel is empty —
-     * the case the signal's own documentation calls out (:1150-1151) and that the
-     * web port's index-change gate made unreachable.
+     * `scroll_animation_done_cb` — the scroll has come to rest, so emit `page-changed`
+     * with the page the position landed on. Emitted after EVERY completed scroll,
+     * including one that settles back onto the page it started from, and with index
+     * `-1` when the carousel is empty (a case the signal's documentation calls out).
      */
     settle(): void;
     /**
@@ -391,126 +331,111 @@ export declare class CarouselState {
      * emits `page-changed` the first time the position comes to rest on a snap
      * point, and re-arms as soon as it leaves one. Returns whether it emitted.
      *
-     * A DEVIATION with a reason: `scroll_animation_done_cb` (:363-376) is driven
-     * by the spring animation finishing, and neither CSS scroll-snap nor a
-     * NativeScript `ScrollView` has an equivalent — both only report offsets. So
-     * ARRIVAL at a snap point stands in for "the animation finished", and the
-     * one-shot bookkeeping lives here rather than in two renderers, where it
-     * would be the third copy of the same idea to drift.
+     * A DEVIATION with a reason: `scroll_animation_done_cb` is driven by the spring
+     * animation finishing, and neither CSS scroll-snap nor a NativeScript `ScrollView`
+     * has an equivalent — both only report offsets. ARRIVAL at a snap point therefore
+     * stands in for "the animation finished".
      */
     settleIfArrived(epsilon?: number): boolean;
     /**
-     * One keynav step — `keynav_cb` → `navigate_to_direction` (:579-639, :475-508).
-     * Returns whether the carousel moved.
-     *
-     * The `interactive` gate lives here because `keynav_cb` checks it before
-     * calling `navigate_to_direction` (:588); `adw_carousel_scroll_to` is NOT
-     * gated, which is why {@link scrollTo} isn't either.
+     * One keynav step — `keynav_cb` → `navigate_to_direction`. Returns whether the
+     * carousel moved. The `interactive` gate lives here because `keynav_cb` checks it
+     * before calling `navigate_to_direction`; `adw_carousel_scroll_to` is NOT gated,
+     * which is why {@link scrollTo} isn't either.
      */
     navigate(direction: CarouselDirection): boolean;
     /**
-     * One scroll-wheel event — `scroll_cb` (adw-carousel.c:510-577). Returns the
-     * step taken; `0` means the event was NOT consumed and must propagate, which
-     * is the only value for which C returns `GDK_EVENT_PROPAGATE`.
+     * One scroll-wheel event — `scroll_cb`. Returns the step taken; `0` means the event
+     * was NOT consumed and must propagate, the only value for which C returns
+     * `GDK_EVENT_PROPAGATE`.
      *
      * The four gates run in C's order — the property, the 150 ms lockout,
-     * `interactive`, and an empty carousel (:523-533) — then the axis rules, then
-     * one clamped page step and a fresh lockout (:566-574). A step that is
-     * refused by the clamp (already on the last page) still consumes the event
-     * and still arms the lockout, exactly as C does.
+     * `interactive`, an empty carousel — then the axis rules, then one clamped page step
+     * and a fresh lockout. A step refused by the clamp (already on the last page) still
+     * consumes the event and still arms the lockout, exactly as C does.
      */
     handleWheel(input: Omit<CarouselWheelInput, 'orientation'>): -1 | 0 | 1;
     /**
-     * `adw_carousel_insert` (adw-carousel.c:1370-1407). Returns whether the page
-     * was added.
+     * `adw_carousel_insert`. Returns whether the page was added.
      *
-     * `position` is `-1` (append, the default) or an index to insert BEFORE; an
-     * index past the end appends too, because `get_nth_link` returns NULL there
-     * (:1388-1391 + the documented behaviour at :1366-1368). Anything below `-1`
-     * fails C's precondition (:1381) and is recorded instead.
+     * `position` is `-1` (append, the default) or an index to insert BEFORE; an index
+     * past the end appends too, because `get_nth_link` returns NULL there. Anything
+     * below `-1` fails C's precondition and is recorded instead.
      *
-     * The page starts at size 0 and `adding` (:1385-1386) — it occupies no
-     * geometry yet, which is what pushes the first snap point negative. A
-     * renderer either ramps it with {@link setPageSize} or, with the default
-     * `reveal-duration` of 0, finishes it at once with {@link skipReveal}.
+     * The page starts at size 0 and `adding` — it occupies no geometry yet, which is
+     * what pushes the first snap point negative. A renderer either ramps it with
+     * {@link setPageSize} or, with the default `reveal-duration` of 0, finishes it at
+     * once with {@link skipReveal}.
      */
     insertPage(id: string, position?: number): boolean;
     /**
-     * `adw_carousel_remove` (adw-carousel.c:1508-1532). Returns whether a page was
-     * removed.
+     * `adw_carousel_remove`. Returns whether a page was removed.
      *
-     * The page leaves {@link nPages} immediately (:1522 + :1640-1645) but keeps
-     * its geometry until its size reaches 0, so the pages after it slide over
-     * instead of jumping. A page that is still ANIMATING IN disappears at once
-     * instead: `animate_child_resize` skips the in-flight reveal, and finishing
-     * it runs `resize_animation_done_cb`, which frees a removing child on the
-     * spot (:329-337 → :309-313). C runs that skipped reveal to its target first
-     * and banks the shift; dropping the child outright lands in the same state,
-     * because the banked shift and the geometry it paid for are freed together.
+     * The page leaves {@link nPages} immediately but keeps its geometry until its size
+     * reaches 0, so the pages after it slide over instead of jumping. A page still
+     * ANIMATING IN disappears at once instead: `animate_child_resize` skips the
+     * in-flight reveal, and finishing it runs `resize_animation_done_cb`, which frees a
+     * removing child on the spot. C runs that skipped reveal to its target first and
+     * banks the shift; dropping the child outright lands in the same state, because the
+     * banked shift and the geometry it paid for are freed together.
      */
     removePage(id: string): boolean;
     /**
-     * `adw_carousel_reorder` (adw-carousel.c:1419-1499). Returns whether the page
-     * moved.
+     * `adw_carousel_reorder`. Returns whether the page moved.
      *
-     * `position` is `-1` or past the end for "move to the end". The three
-     * early-outs are C's and they are not interchangeable: a `position` equal to
-     * the page's CURRENT one returns before normalisation (:1439-1440), and
-     * moving the last page to the end is a no-op checked after it (:1448-1449).
-     * The position compensation is {@link carouselReorderShift}.
+     * `position` is `-1` or past the end for "move to the end". The three early-outs are
+     * C's and are not interchangeable: a `position` equal to the page's CURRENT one
+     * returns before normalisation, and moving the last page to the end is a no-op
+     * checked after it. The position compensation is {@link carouselReorderShift}.
      */
     reorderPage(id: string, position: number): boolean;
     /**
-     * Feed one frame of a page's reveal animation —
-     * `resize_animation_value_cb` + `resize_animation_done_cb` (:284-316).
-     * Returns whether the size was applied.
+     * Feed one frame of a page's reveal animation — `resize_animation_value_cb` +
+     * `resize_animation_done_cb`. Returns whether the size was applied.
      *
-     * A size change on a page at or before the current one moves the position by
-     * the same delta (:293-294), which is what keeps the visible page still while
-     * a page grows in ahead of it. C banks that delta in `position_shift` and
-     * applies it at the next `size_allocate` (:732-736); with no allocation cycle
-     * to wait for, it is applied here — the settled state is identical.
+     * A size change on a page at or before the current one moves the position by the
+     * same delta, which keeps the visible page still while a page grows in ahead of it.
+     * C banks that delta in `position_shift` and applies it at the next `size_allocate`;
+     * with no allocation cycle to wait for it is applied here — the settled state is
+     * identical.
      *
-     * Reaching the animation's target ENDS it: a page that arrives at 1 stops
-     * being `adding`, and one that arrives at 0 while removing is dropped from
-     * the geometry (:306-313).
+     * Reaching the animation's target ENDS it: a page that arrives at 1 stops being
+     * `adding`, one that arrives at 0 while removing is dropped from the geometry.
      */
     setPageSize(id: string, size: number): boolean;
     /**
-     * Finish a page's pending reveal or removal at once — `adw_animation_skip`
-     * (:331), which jumps a timed animation to its target value.
+     * Finish a page's pending reveal or removal at once — `adw_animation_skip`,
+     * which jumps a timed animation to its target value.
      *
-     * This is the whole reveal for a carousel with the default `reveal-duration`
-     * of 0 (:1206), which is what both renderers run today, and it keeps the
-     * "which value does this page animate TO" rule out of both of them. Returns
-     * whether anything was pending.
+     * This is the whole reveal for a carousel with the default `reveal-duration` of 0.
+     * Returns whether anything was pending.
      *
-     * An unknown id is NOT a diagnostic here, unlike everywhere else: removing a
-     * page that was still revealing frees it on the spot (:329-337), so a
-     * renderer that finishes what it just removed legitimately finds nothing.
+     * An unknown id is NOT a diagnostic here, unlike everywhere else: removing a page
+     * that was still revealing frees it on the spot, so a renderer that finishes what it
+     * just removed legitimately finds nothing.
      */
     skipReveal(id: string): boolean;
     /** `GtkOrientable:orientation` — which axis the carousel pages along. */
     get orientation(): CarouselOrientation;
-    /** Set the orientation. Returns whether it changed (:982-992). */
+    /** Set the orientation. Returns whether it changed. */
     setOrientation(orientation: CarouselOrientation): boolean;
     /** `AdwCarousel:interactive` — whether the carousel can be navigated at all. */
     get interactive(): boolean;
-    /** Set `interactive`. Returns whether it changed (:1694-1708). */
+    /** Set `interactive`. Returns whether it changed. */
     setInteractive(value: boolean): boolean;
-    /** `AdwCarousel:allow-scroll-wheel` — default TRUE, which both ports lost. */
+    /** `AdwCarousel:allow-scroll-wheel` — default TRUE. */
     get allowScrollWheel(): boolean;
-    /** Set `allow-scroll-wheel`. Returns whether it changed (:1852-1866). */
+    /** Set `allow-scroll-wheel`. Returns whether it changed. */
     setAllowScrollWheel(value: boolean): boolean;
     /**
      * `AdwCarousel:allow-long-swipes` — whether one flick may cross more than one
-     * snap point. Forwarded to the swipe tracker in C (:1900-1914); the state
+     * snap point. Forwarded to the swipe tracker in C; the state
      * machine only carries it, because the gesture itself is the renderer's.
      */
     get allowLongSwipes(): boolean;
     /** Set `allow-long-swipes`. Returns whether it changed. */
     setAllowLongSwipes(value: boolean): boolean;
-    /** `AdwCarousel:spacing` in px — the gap between pages, part of `distance` (:767). */
+    /** `AdwCarousel:spacing` in px — the gap between pages, part of `distance`. */
     get spacing(): number;
     /** Set `spacing`. Returns whether it changed. A `guint` in C, so negatives are refused. */
     setSpacing(spacing: number): boolean;
@@ -519,17 +444,15 @@ export declare class CarouselState {
     /** Set `reveal-duration`. Returns whether it changed. A `guint` in C. */
     setRevealDuration(ms: number): boolean;
     /**
-     * The px distance between two page origins — `self->distance` (:767), the
-     * unit a renderer converts a position into a scroll offset with.
-     * `pageLength` is the measured size of the largest page along the
-     * carousel's own axis.
+     * The px distance between two page origins — `self->distance`, the unit a renderer
+     * converts a position into a scroll offset with. `pageLength` is the measured size of
+     * the largest page along the carousel's own axis.
      */
     pageDistance(pageLength: number): number;
     /**
-     * Every warning C would have printed, in order — the refused scroll targets,
-     * the bad insert/reorder positions, the unknown page ids and the non-finite
-     * values. Kept as data so a test can assert on the CLASS of mistake instead
-     * of on stderr; both ports swallowed all of them.
+     * Every warning C would have printed, in order — refused scroll targets, bad
+     * insert/reorder positions, unknown page ids, non-finite values. Data rather than
+     * stderr so a test can assert on the CLASS of mistake.
      */
     get diagnostics(): readonly string[];
 }