@gjsify/adwaita-web 0.43.0 → 0.45.0

package/README.md

@@ -53,6 +53,33 @@ Vite preset (or any Vite/bundler setup). Type declarations are shipped
 pre-built at `lib/types/index.d.ts`, so `gjsify tsc` consumers resolve the
 package's types without compiling its source.
 
+## Slots are live
+
+These are light-DOM custom elements, so `slot="…"` is emulated rather than native
+(see [ADR 0010](../../../docs/adr/0010-adwaita-web-style-isolation.md) for why the
+package stays out of the shadow DOM). The emulation is **live**: a child appended
+after the element is in the document lands in the same internal box as the
+identical child written in the markup.
+
+```typescript
+const row = document.querySelector('adw-action-row')!;
+const toggle = document.createElement('adw-switch');
+toggle.setAttribute('slot', 'suffix');
+row.append(toggle); // lands in the suffix section, exactly as a declared one does
+```
+
+Two limits are worth knowing:
+
+- **Append, not reorder.** A late child goes to the end of its slot's box. Once a
+  child has been adopted it is no longer a child of the host, so
+  `host.insertBefore(next, adopted)` throws in the DOM before this package sees
+  it — reorder inside the box you were handed (`row.prefixSection`,
+  `view.topBar`, …). Native `<slot>` is what would lift this, and it is part of
+  the shadow-DOM path ADR 0010 defers.
+- **An unknown slot name is assigned nowhere**, as in the native algorithm: a
+  `slot="sufix"` typo stays where you put it instead of quietly becoming default
+  content in the wrong box.
+
 ## Shared behaviour (`@gjsify/adwaita-core`)
 
 The widget *behaviour* — as opposed to the DOM rendering — comes from

package/lib/types/adw-alert-dialog.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwAlertDialogTest: () => Promise<void>;

package/lib/types/elements/adw-alert-dialog.d.ts

@@ -31,6 +31,12 @@ export declare class AdwAlertDialog extends HTMLElement {
     set body(value: string);
     get open(): boolean;
     set open(value: boolean);
+    /** Whether {@link heading} is read as markup rather than plain text. */
+    get headingUseMarkup(): boolean;
+    set headingUseMarkup(value: boolean);
+    /** Whether {@link body} is read as markup rather than plain text. */
+    get bodyUseMarkup(): boolean;
+    set bodyUseMarkup(value: boolean);
     /** Whether to prefer horizontal button layout when the buttons fit. */
     get preferWideLayout(): boolean;
     set preferWideLayout(value: boolean);
@@ -41,6 +47,12 @@ export declare class AdwAlertDialog extends HTMLElement {
     get closeResponse(): string;
     set closeResponse(value: string);
     connectedCallback(): void;
+    /**
+     * Take one declared `<adw-alert-response>` as a response. An entry with no `id` is
+     * skipped rather than given a generated one: the id is what `response` events carry, so
+     * inventing one would hand the consumer a name it never wrote.
+     */
+    private _adoptResponse;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     /** Present the dialog. `parent` is accepted for API parity; unused. */
     present(_parent?: unknown): void;

package/lib/types/elements/adw-entry-row.d.ts

@@ -16,8 +16,11 @@ export declare class AdwEntryRow extends HTMLElement {
     protected _prefixes: HTMLDivElement;
     protected _suffixes: HTMLDivElement;
     protected _initialized: boolean;
-    /** Light-DOM children captured at build time, adopted after `_onConnected`. */
-    private _authored;
+    /**
+     * The two slots, installed after `_onConnected` rather than inside `_build`: the order
+     * IS the contract — see the `install` call in `connectedCallback`.
+     */
+    private _slots;
     private _lastText;
     private _lastLength;
     static get observedAttributes(): string[];
@@ -76,11 +79,6 @@ export declare class AdwEntryRow extends HTMLElement {
     /** Subclass hook: runs after the DOM exists and the state is seeded, before the first render. */
     protected _onConnected(): void;
     private _build;
-    /**
-     * Re-home the children the author wrote. libadwaita's buildable maps an untyped
-     * `<child>` to a suffix; `slot="prefix"` is the web spelling of `type="prefix"`.
-     */
-    private _adoptAuthored;
     /**
      * `pressed_cb`: a click landing on the row, the editable area, the indicator or
      * either affordance box grabs focus; anything else (a suffix control, the apply

package/lib/types/elements/adw-header-bar.d.ts

@@ -6,8 +6,10 @@ export declare class AdwHeaderBar extends HTMLElement {
     private _endEl;
     /**
      * The derived `<adw-window-title>`, or `null` when a `slot="center"`
-     * title-widget took the centre. `Adw.HeaderBar` has the same either/or:
-     * setting `title-widget` replaces the derived `AdwWindowTitle` outright.
+     * title-widget took the centre. `Adw.HeaderBar` has the same either/or —
+     * `adw_header_bar_set_title_widget` empties the centre bin before installing
+     * (adw-header-bar.c:1201) — over a derived `GtkLabel`, not an `AdwWindowTitle`;
+     * see the divergence at the top of this file.
      */
     private _titleEl;
     static get observedAttributes(): string[];
@@ -22,9 +24,22 @@ export declare class AdwHeaderBar extends HTMLElement {
     /**
      * `title` used to be read ONCE, in `connectedCallback`, so every later write
      * was a silent no-op — a header bar whose title tracked the open document
-     * kept whatever it was created with. `Adw.HeaderBar`'s derived title widget
-     * is bound to the property and re-renders on every change.
+     * kept whatever it was created with. `Adw.HeaderBar` never reads its title once
+     * either: it has no `title` property at all, and re-runs `update_title`
+     * (adw-header-bar.c:475) on every ancestor change that could move the answer.
      */
     attributeChangedCallback(): void;
+    /**
+     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` empties the
+     * centre bin and drops its derived label (adw-header-bar.c:1201, :1209) rather than
+     * stacking the two, so the late case has to remove ours too — a bar showing both would
+     * be a shape neither GTK nor the declared markup can produce.
+     *
+     * NOT SYMMETRIC HERE, AND KNOWN: C rebuilds the label the moment the title-widget goes
+     * away (:1211); nothing in this element brings the derived centre back, so a bar that
+     * gave it up has given it up for good. `HeaderBarState` in `@gjsify/adwaita-core` holds
+     * the rebuild, and this element adopting it is the rewiring tracked in #1343.
+     */
+    private _dropDerivedTitle;
     private _renderTitle;
 }

package/lib/types/elements/adw-navigation-split-view.d.ts

@@ -45,6 +45,15 @@ export declare class AdwNavigationSplitView extends HTMLElement {
     pop(): NavigationActionResult;
     connectedCallback(): void;
     private _buildOnce;
+    /**
+     * Mount whatever a pane box currently HOLDS into the state — `null` while it is empty.
+     *
+     * Re-mounting an unchanged pane re-emits the plan, because the state compares the page
+     * ref by identity. Both subscribers are idempotent reflections (an attribute and a
+     * class list), so a second child in the same pane costs a repaint decision and never a
+     * navigation event.
+     */
+    private _mountPane;
     /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
     private _tagOf;
     /**

package/lib/types/elements/adw-preferences-group.d.ts

@@ -5,6 +5,12 @@ export declare class AdwPreferencesGroup extends HTMLElement {
     private _suffixEl;
     private _listboxEl;
     private _initialized;
+    /**
+     * Watches the two BOXES, not the host: the routing of a host child is
+     * `src/slotted-children.ts`'s job now, and what is left here is the header derivation,
+     * whose inputs are the row count and whether a suffix exists. A removal straight out of
+     * the listbox changes both and reaches no other callback.
+     */
     private _observer;
     static get observedAttributes(): string[];
     get description(): string;
@@ -13,10 +19,11 @@ export declare class AdwPreferencesGroup extends HTMLElement {
      * `adw_preferences_group_add`: a row goes into the boxed list, a `header-suffix`
      * child into the header.
      *
-     * Exposed as a method AND wired to a `MutationObserver` on the host, because both
-     * spellings occur — `group.addRow(row)` in code, `group.append(row)` from a
-     * framework's rendering — and a bare child of the host would sit outside the card,
-     * invisible to the row count that decides whether the card is painted at all.
+     * Kept as a method as well as a slot, because both spellings occur —
+     * `group.addRow(row)` in code, `group.append(row)` from a framework's rendering — and a
+     * bare child of the host would sit outside the card, invisible to the row count that
+     * decides whether the card is painted at all. The `append` spelling is routed by
+     * `src/slotted-children.ts`, which every other slotted element now shares.
      */
     addRow(child: Node): void;
     /**
@@ -29,13 +36,15 @@ export declare class AdwPreferencesGroup extends HTMLElement {
     disconnectedCallback(): void;
     attributeChangedCallback(): void;
     /**
-     * Adopt children appended to the HOST after the subtree was built, so
-     * `group.append(row)` behaves like `adw_preferences_group_add`.
+     * Re-derive the header whenever the two boxes change, in EITHER direction.
      *
      * C gets this for free: `gtk_widget_observe_children` on the listbox drives
-     * `update_listbox_visibility` through `items-changed`. A DOM element needs the
-     * observer for the same rule to hold over time rather than only at connect.
+     * `update_listbox_visibility` through `items-changed`. A DOM element needs the observer
+     * for the same rule to hold over time rather than only at connect. Adoption is not what
+     * this watches — a row appended to the host reaches the listbox through the shared slot
+     * routing, and lands here as the listbox record it causes. A row REMOVED straight out
+     * of the listbox reaches no other callback at all, and it still changes the row count.
      */
-    private _observeHost;
+    private _observeBoxes;
     private _renderHeader;
 }

package/lib/types/slotted-children.d.ts

@@ -0,0 +1,65 @@
+export interface AdwSlotClaim {
+    /** The `slot="…"` value claimed. Omit for the DEFAULT slot — everything else. */
+    readonly name?: string;
+    /**
+     * Claim by NODE as well as by slot name, for the typed-child spelling
+     * (`<adw-alert-response>` IS the slot) and for a default that takes only some node
+     * kinds (`<adw-entry-row>` adopts elements and drops stray whitespace, as GtkBuildable
+     * does). Tried after an explicit `slot=` name and before the default, so a claim can
+     * never swallow a child that named a different slot.
+     */
+    readonly claims?: (node: Node) => boolean;
+}
+/** A destination that RE-HOMES what it claims — the ordinary slot. */
+export interface AdwSlotInto extends AdwSlotClaim {
+    readonly into: HTMLElement;
+}
+/**
+ * A slot whose child is consumed by a CALL rather than by a move: either data —
+ * `<adw-alert-response id="ok">` is read for its id, label and appearance and then gone,
+ * exactly as GtkBuilder leaves nothing of a `<responses>` entry in the widget tree — or a
+ * widget whose insertion rule is the element's own (`addPrefix` PREPENDS, mirroring
+ * `gtk_box_prepend`). A node the call did not move out of the host is dropped, so a
+ * data-only child cannot linger as a stray sibling of the internal structure.
+ */
+export interface AdwSlotConsume extends AdwSlotClaim {
+    readonly consume: (node: Node) => void;
+}
+export type AdwSlot = AdwSlotInto | AdwSlotConsume;
+export interface AdwSlottedChildren {
+    /** The declared slots, so a driver can probe them without a hand-written ledger. */
+    readonly slots: readonly AdwSlot[];
+    /**
+     * Route the host's CURRENT children into their slots, then make `structure` the
+     * host's own children, then stay live.
+     *
+     * The three steps are one call because their ORDER is the invariant: the author's
+     * children have to leave the host before it is emptied, or `replaceChildren` destroys
+     * them — the bug `<adw-entry-row>` records above its own `_authored` snapshot. Passing
+     * `structure` here also means the set this module must never route is DERIVED from the
+     * call that installs it, rather than a second list to keep in sync.
+     *
+     * Call once per built subtree; a second call replaces the observer rather than
+     * stacking one.
+     */
+    install(...structure: readonly Node[]): void;
+    /** The slot `node` belongs to, or `null` when none claims it. */
+    slotFor(node: Node): AdwSlot | null;
+}
+/**
+ * The slot binding `host` installed, if it has one.
+ *
+ * This is how `slotted-children.spec.ts` drives EVERY registered element rather than a
+ * list of the ones someone remembered: an element that binds a slot enrols itself in the
+ * placement driver, and one that stops binding drops out of it visibly.
+ */
+export declare function slottedChildrenOf(host: Element): AdwSlottedChildren | undefined;
+/**
+ * Bind `host`'s light-DOM children to `slots`.
+ *
+ * `onAdopt` fires for a child adopted AFTER {@link AdwSlottedChildren.install} and not
+ * during it: the install pass IS the element's own build, which seeds its state on the
+ * next line with everything that landed, so firing there would make every element's build
+ * order depend on how many children the author wrote.
+ */
+export declare function bindSlottedChildren(host: HTMLElement, slots: readonly AdwSlot[], onAdopt?: (node: Node, slot: AdwSlot) => void): AdwSlottedChildren;

package/lib/types/slotted-children.spec.d.ts

@@ -0,0 +1 @@
+export declare const AdwSlottedChildrenTest: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.43.0",
+    "version": "0.45.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -45,14 +45,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.43.0",
-        "@gjsify/adwaita-fonts": "^0.43.0",
-        "@gjsify/adwaita-icons": "^0.43.0",
+        "@gjsify/adwaita-core": "^0.45.0",
+        "@gjsify/adwaita-fonts": "^0.45.0",
+        "@gjsify/adwaita-icons": "^0.45.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.43.0",
-        "@gjsify/unit": "^0.43.0",
+        "@gjsify/cli": "^0.45.0",
+        "@gjsify/unit": "^0.45.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },
@@ -75,6 +75,9 @@
                 "navigator",
                 "process"
             ]
+        },
+        "widgetVocabulary": {
+            "role": "renderer"
         }
     },
     "license": "MIT",

package/src/adw-alert-dialog.spec.ts

@@ -0,0 +1,146 @@
+// <adw-alert-dialog> against `Adw.AlertDialog`'s own property list.
+//
+// This element shipped with FOUR of its eight GIR properties reachable from markup —
+// `heading`, `body`, `open` (a web convention with no GIR counterpart) and
+// `prefer-wide-layout`. `close-response` and `default-response` existed as JS
+// properties but no attribute fed them, and `heading-use-markup`/`body-use-markup`
+// were absent entirely. The website's generated widget table read
+// `observedAttributes` and truthfully reported "takes 4 attributes", which is how the
+// gap became visible: the DOC was right and the ELEMENT was short.
+//
+// The markup pair defaults to FALSE here and in libadwaita alike — unlike
+// `Adw.Banner:use-markup`, whose C default is TRUE and which `adw-banner.ts` therefore
+// departs from on purpose. So these vectors pin a MATCH, not a departure, and the
+// negative case is the one that matters: tags must show literally until asked for.
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { AdwAlertDialog } from './elements/adw-alert-dialog.js';
+
+/** Mount via `setAttribute` so an attribute value's exact text survives. */
+function mount(attributes: Record<string, string> = {}): { el: AdwAlertDialog; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement('adw-alert-dialog') as AdwAlertDialog;
+    for (const [name, value] of Object.entries(attributes)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+const headingEl = (el: AdwAlertDialog): HTMLElement => el.querySelector('.adw-alert-dialog-heading') as HTMLElement;
+const bodyEl = (el: AdwAlertDialog): HTMLElement => el.querySelector('.adw-alert-dialog-body') as HTMLElement;
+
+export const AdwAlertDialogTest = async () => {
+    await describe('adw-alert-dialog observes every Adw.AlertDialog property it can render', async () => {
+        // Named rather than counted: a count passes again the moment someone swaps one
+        // attribute for another, which is the drift this file exists to catch.
+        for (const name of [
+            'heading',
+            'body',
+            'heading-use-markup',
+            'body-use-markup',
+            'close-response',
+            'default-response',
+            'prefer-wide-layout',
+        ]) {
+            await it(`observes \`${name}\``, () => {
+                expect(
+                    (
+                        customElements.get('adw-alert-dialog') as typeof HTMLElement & {
+                            observedAttributes: string[];
+                        }
+                    ).observedAttributes,
+                ).toContain(name);
+            });
+        }
+    });
+
+    await describe('adw-alert-dialog markup is opt-in, matching the libadwaita default', async () => {
+        await it('a heading with tags shows them literally by default', () => {
+            const { el, host } = mount({ heading: '<b>Delete</b> file?' });
+            expect(headingEl(el).textContent).toBe('<b>Delete</b> file?');
+            expect(headingEl(el).querySelector('b')).toBe(null);
+            host.remove();
+        });
+
+        await it('heading-use-markup renders it, which is the author asserting it is trusted', () => {
+            const { el, host } = mount({ heading: '<b>Delete</b> file?', 'heading-use-markup': '' });
+            expect(headingEl(el).querySelector('b')?.textContent).toBe('Delete');
+            host.remove();
+        });
+
+        await it('a body with tags shows them literally by default', () => {
+            const { el, host } = mount({ body: 'Really delete <i>notes.txt</i>?' });
+            expect(bodyEl(el).textContent).toBe('Really delete <i>notes.txt</i>?');
+            expect(bodyEl(el).querySelector('i')).toBe(null);
+            host.remove();
+        });
+
+        await it('body-use-markup renders it', () => {
+            const { el, host } = mount({ body: 'Really delete <i>notes.txt</i>?', 'body-use-markup': '' });
+            expect(bodyEl(el).querySelector('i')?.textContent).toBe('notes.txt');
+            host.remove();
+        });
+
+        await it('toggling the attribute off returns to text', () => {
+            const { el, host } = mount({ heading: '<b>Delete</b>', 'heading-use-markup': '' });
+            el.headingUseMarkup = false;
+            expect(headingEl(el).textContent).toBe('<b>Delete</b>');
+            expect(headingEl(el).querySelector('b')).toBe(null);
+            host.remove();
+        });
+    });
+
+    await describe('adw-alert-dialog response IDs are reachable from markup', async () => {
+        await it('close-response defaults to `close`, as in Adw.AlertDialog', () => {
+            const { el, host } = mount();
+            expect(el.closeResponse).toBe('close');
+            host.remove();
+        });
+
+        await it('the attribute feeds the headless model', () => {
+            const { el, host } = mount({ 'close-response': 'cancel' });
+            expect(el.closeResponse).toBe('cancel');
+            host.remove();
+        });
+
+        await it('default-response defaults to null and the attribute sets it', () => {
+            const { el, host } = mount();
+            expect(el.defaultResponse).toBe(null);
+            el.setAttribute('default-response', 'delete');
+            expect(el.defaultResponse).toBe('delete');
+            host.remove();
+        });
+
+        await it('removing default-response clears it', () => {
+            const { el, host } = mount({ 'default-response': 'delete' });
+            el.removeAttribute('default-response');
+            expect(el.defaultResponse).toBe(null);
+            host.remove();
+        });
+
+        await it('a dismissal emits the close response the attribute named', () => {
+            // The scrim click, not `open = false`. `_dismiss()` SETS `open = false` and
+            // then emits, so the property is the lower-level state change and driving it
+            // directly would assert a contract this element does not have.
+            const { el, host } = mount({ 'close-response': 'cancel', open: '' });
+            let seen: string | null = null;
+            el.addEventListener('response', (event) => {
+                seen = (event as CustomEvent<{ response: string }>).detail.response;
+            });
+            (el.querySelector('.adw-alert-dialog-scrim') as HTMLElement).click();
+            expect(seen).toBe('cancel');
+            expect(el.open).toBe(false);
+            host.remove();
+        });
+
+        await it('removing close-response keeps the model value, unlike default-response', () => {
+            // An ASYMMETRY worth pinning rather than discovering: `close-response` has a
+            // non-null GIR default (`close`), so an absent attribute means "leave the
+            // model alone", while `default-response` defaults to null and clears.
+            const { el, host } = mount({ 'close-response': 'cancel' });
+            el.removeAttribute('close-response');
+            expect(el.closeResponse).toBe('cancel');
+            host.remove();
+        });
+    });
+};

package/src/adw-header-bar.spec.ts

@@ -4,9 +4,13 @@
 // the open document keeps its construction-time title otherwise, and nothing notices
 // because the attribute is still there and A title still renders.
 //
-// `Adw.HeaderBar` builds its centre from `title`/`subtitle` through a derived
-// `AdwWindowTitle` bound to the properties, unless a `title-widget` replaces it — the
-// either/or the `slot="center"` case below asserts.
+// The either/or the `slot="center"` case below asserts IS `Adw.HeaderBar`'s: setting
+// `title-widget` empties the centre bin (adw-header-bar.c:1201), and clearing it builds the
+// derived centre again (:1211). What C builds there is a plain `gtk_label_new (NULL)`
+// (`construct_title_label`, :512) with no subtitle, and no `title` property behind it —
+// `update_title` (:475) resolves one from the ancestry. The `<adw-window-title>` centre and
+// the title/subtitle PAIR are this port's DIVERGENCE, named in `elements/adw-header-bar.ts`
+// and recorded as `HeaderBarRenderState.derivedSubtitle` in `@gjsify/adwaita-core`.
 
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -68,8 +72,10 @@ function mountSizedHeaderBar(width: number): HTMLElement {
             bar.appendChild(button);
         }
     }
-    // Appended LAST: the sections are built in `connectedCallback`, so the slotted
-    // children have to be in place before the bar enters the document.
+    // The bar enters the document last, so this geometry is measured on the PARSE-TIME
+    // path. It used to be the only path that worked — the sections were built in
+    // `connectedCallback` from a one-shot snapshot — and that is no longer a constraint:
+    // `slotted-children.spec.ts` requires the appended path to place a child identically.
     host.appendChild(bar);
     return bar;
 }
@@ -120,7 +126,8 @@ export const AdwHeaderBarTest = async () => {
         });
     });
 
-    // The centre is the `<adw-window-title>` Adw.HeaderBar itself derives, so the three
+    // The centre is an `<adw-window-title>` — this port's divergence, not the bare
+    // `GtkLabel` `construct_title_label` builds (adw-header-bar.c:512) — so the three
     // rules that element holds through @gjsify/adwaita-core reach the header bar too.
     // None of them did while the centre was a bare span.
     await describe('<adw-header-bar> derives an <adw-window-title>', async () => {

package/src/adw-tab-view.spec.ts

@@ -75,6 +75,77 @@ export const AdwTabViewTest = async () => {
         });
     });
 
+    // ONE HALF of the upgrade-order defect; the other half is the define order at the
+    // foot of `elements/adw-tab-view.ts`, which no test in this realm can observe —
+    // both names are already registered by the time a spec runs, and `define` is what
+    // upgrades. What IS reproducible here is the STATE that order produced: a real
+    // `<adw-tab-page>` next to an `<adw-tab-view>` that is still an ordinary
+    // HTMLElement. `document.implementation.createHTMLDocument()` has no browsing
+    // context, so nothing it creates is ever upgraded; adopting the element carries it
+    // into this document without upgrading it, which INSERTING it would do.
+    //
+    // Constructing both with `document.createElement` instead would pass either way —
+    // both are defined, so both come back upgraded and the ancestor always has the
+    // method. The parse-then-define order the site hits is covered in
+    // `tests/browser/specs/adwaita-upgrade-order.spec.ts`.
+    await describe('adw-tab-page beside an un-upgraded view', async () => {
+        await it('reports nothing when the view has none of its methods yet', async () => {
+            const view = document.adoptNode(
+                document.implementation.createHTMLDocument('').createElement('adw-tab-view'),
+            );
+            expect('syncDeclaredPage' in view).toBe(false);
+            const page = document.createElement('adw-tab-page');
+            view.appendChild(page);
+
+            // A custom-element reaction never throws INTO its caller: the exception is
+            // REPORTED, so `setAttribute` returns normally whether or not the callback
+            // blew up and only a listener sees the difference. `preventDefault` keeps a
+            // red run from also logging it at the console.
+            const reported: string[] = [];
+            const onError = (event: ErrorEvent) => {
+                reported.push(event.message);
+                event.preventDefault();
+            };
+            window.addEventListener('error', onError);
+            page.setAttribute('title', 'One');
+            window.removeEventListener('error', onError);
+
+            expect(reported).toStrictEqual([]);
+            expect(page.getAttribute('title')).toBe('One');
+        });
+
+        await it('leaves a page appended after connect unadopted rather than throwing', async () => {
+            // The imperative surface is `appendPage`; a bare DOM append is out of
+            // contract, and the point here is only that it fails QUIETLY — the page
+            // carries no `data-page-id`, so `syncDeclaredPage` has no record to touch.
+            //
+            // "rather than throwing" is ASSERTED and not assumed. Without the listener
+            // this test measured only the two counts, and both hold whether or not the
+            // callback blew up: a custom-element reaction is REPORTED, never rethrown
+            // into `setAttribute`, so the model is untouched either way. Measured — with
+            // `syncDeclaredPage` mutated to throw on exactly this path, the whole
+            // in-bundle suite of 4631 stayed green and only an unrelated spec's global
+            // error sweep noticed.
+            const view = makeTabView();
+            const late = document.createElement('adw-tab-page');
+            view.appendChild(late);
+
+            const reported: string[] = [];
+            const onError = (event: ErrorEvent) => {
+                reported.push(event.message);
+                event.preventDefault();
+            };
+            window.addEventListener('error', onError);
+            late.setAttribute('title', 'Late');
+            window.removeEventListener('error', onError);
+
+            expect(reported).toStrictEqual([]);
+            expect(view.nPages).toBe(3);
+            expect(chips(view).length).toBe(3);
+            view.parentElement?.remove();
+        });
+    });
+
     await describe('adw-tab-view expand-tabs / no-close', async () => {
         await it('no-close hides every close affordance', async () => {
             const view = makeTabView('no-close');

package/src/elements/adw-action-row.ts

@@ -17,6 +17,7 @@
 import { ActionRowState } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { type AdwRowActivation, attachRowActivation } from './row-activation.js';
 
 /**
@@ -90,12 +91,8 @@ export class AdwActionRow extends HTMLElement {
         }
         this._initialized = true;
 
-        const prefixChildren = Array.from(this.querySelectorAll(':scope > [slot="prefix"]'));
-        const suffixChildren = Array.from(this.querySelectorAll(':scope > [slot="suffix"]'));
-
         this._prefixEl = document.createElement('div');
         this._prefixEl.className = 'adw-action-row-prefix';
-        for (const child of prefixChildren) this._prefixEl.appendChild(child);
 
         const textEl = document.createElement('div');
         textEl.className = 'adw-action-row-text';
@@ -107,9 +104,14 @@ export class AdwActionRow extends HTMLElement {
 
         this._suffixEl = document.createElement('div');
         this._suffixEl.className = 'adw-action-row-suffix';
-        for (const child of suffixChildren) this._suffixEl.appendChild(child);
 
-        this.replaceChildren(this._prefixEl, textEl, this._suffixEl);
+        // The two slots stay LIVE — a control appended with `slot="suffix"` after connect
+        // has to land in the same section the declared one does, which a snapshot taken
+        // here cannot do. `src/slotted-children.ts` carries the incident.
+        bindSlottedChildren(this, [
+            { name: 'prefix', into: this._prefixEl },
+            { name: 'suffix', into: this._suffixEl },
+        ]).install(this._prefixEl, textEl, this._suffixEl);
         // `_render` runs from `attributeChangedCallback`, which a control appended into
         // `suffixSection` never triggers — the section stayed `hidden` and the control
         // measured 0x0. The observer is what keeps the two sections in step with what