@gjsify/adwaita-web 0.43.0 → 0.44.0

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

@@ -14,9 +14,21 @@
 // Attributes:
 //   heading    (the bold heading text)
 //   body       (the body text below the heading)
+//   heading-use-markup (boolean — read `heading` as markup rather than plain text)
+//   body-use-markup    (boolean — read `body` as markup rather than plain text)
+//   close-response     (the response ID emitted on dismissal; default `close`)
+//   default-response   (the response ID whose button is highlighted and focused)
 //   open       (boolean — whether the dialog is shown; default closed)
 //   prefer-wide-layout (boolean — lay responses out horizontally when they fit)
 //
+// MARKUP IS OPT-IN, and here that MATCHES libadwaita rather than departing from it:
+// `Adw.AlertDialog:heading-use-markup` and `:body-use-markup` both default to FALSE
+// (`Adw.Banner:use-markup` is the one that defaults to TRUE, which is why
+// `adw-banner.ts` documents a deliberate departure and this file does not need to).
+// Opting in renders through `innerHTML`, which is the author asserting the string is
+// trusted — Pango markup has a fixed tag set and no scripting, HTML has neither
+// property.
+//
 // Buttons are stacked vertically by default (the Adw.AlertDialog default at medium
 // sizes) and laid out horizontally when prefer-wide-layout is set and there are no more
 // than two of them — the libadwaita measure/allocate heuristic in spirit, not to the px.
@@ -45,6 +57,7 @@ import { AdwAlertResponses } from '@gjsify/adwaita-core';
 import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 /** Response button appearance — mirrors Adw.ResponseAppearance. */
@@ -81,7 +94,16 @@ export class AdwAlertDialog extends HTMLElement {
     private _blockCloseResponse = false;
 
     static get observedAttributes() {
-        return ['heading', 'body', 'open', 'prefer-wide-layout'];
+        return [
+            'heading',
+            'body',
+            'heading-use-markup',
+            'body-use-markup',
+            'close-response',
+            'default-response',
+            'open',
+            'prefer-wide-layout',
+        ];
     }
 
     get heading(): string {
@@ -109,6 +131,26 @@ export class AdwAlertDialog extends HTMLElement {
         else this.removeAttribute('open');
     }
 
+    /** Whether {@link heading} is read as markup rather than plain text. */
+    get headingUseMarkup(): boolean {
+        return this.hasAttribute('heading-use-markup');
+    }
+
+    set headingUseMarkup(value: boolean) {
+        if (value) this.setAttribute('heading-use-markup', '');
+        else this.removeAttribute('heading-use-markup');
+    }
+
+    /** Whether {@link body} is read as markup rather than plain text. */
+    get bodyUseMarkup(): boolean {
+        return this.hasAttribute('body-use-markup');
+    }
+
+    set bodyUseMarkup(value: boolean) {
+        if (value) this.setAttribute('body-use-markup', '');
+        else this.removeAttribute('body-use-markup');
+    }
+
     /** Whether to prefer horizontal button layout when the buttons fit. */
     get preferWideLayout(): boolean {
         return this.hasAttribute('prefer-wide-layout');
@@ -141,12 +183,6 @@ export class AdwAlertDialog extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Declared <adw-alert-response> children are snapshotted before the element takes
-        // over the subtree; everything else becomes the extra child.
-        const declared = Array.from(this.querySelectorAll(':scope > adw-alert-response')) as AdwAlertResponse[];
-        const declaredSet = new Set<Node>(declared);
-        const extraChildren = Array.from(this.childNodes).filter((n) => !declaredSet.has(n));
-
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-alert-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._dismiss());
@@ -176,36 +212,66 @@ export class AdwAlertDialog extends HTMLElement {
 
         this._childEl = document.createElement('div');
         this._childEl.className = 'adw-alert-dialog-child';
-        for (const child of extraChildren) this._childEl.appendChild(child);
 
         messageArea.append(this._headingEl, this._bodyEl, this._childEl);
-        // `_render` runs from `attributeChangedCallback` and from the response API, and
-        // an extra child appended after connect triggers neither.
-        bindEmptySections(this._childEl);
 
         this._responseAreaEl = document.createElement('div');
         this._responseAreaEl.className = 'adw-alert-dialog-responses';
 
         this._dialogEl.append(messageArea, this._responseAreaEl);
-        this.replaceChildren(this._scrimEl, this._dialogEl);
-
-        for (const el of declared) {
-            const id = el.getAttribute('id');
-            if (!id) continue;
-            const appearance = (el.getAttribute('appearance') ?? 'default') as AdwResponseAppearance;
-            this.addResponse(id, (el.textContent ?? '').trim());
-            if (appearance !== 'default') this.setResponseAppearance(id, appearance);
-            if (el.getAttribute('enabled') === 'false') this.setResponseEnabled(id, false);
-        }
+
+        // Two slots, both LIVE. An `<adw-alert-response>` is DATA — read for its id, label
+        // and appearance and then gone, as GtkBuilder leaves nothing of a `<responses>`
+        // entry in the widget tree — so it is consumed rather than re-homed, and
+        // `adw_alert_dialog_add_response` is callable at any point in the dialog's life.
+        // Everything else is the extra child. `src/slotted-children.ts` has the incident.
+        // Installed AFTER the response area exists, because consuming a response fills it.
+        bindSlottedChildren(this, [
+            {
+                claims: (node) => node instanceof Element && node.localName === 'adw-alert-response',
+                consume: (node) => this._adoptResponse(node as AdwAlertResponse),
+            },
+            { into: this._childEl },
+        ]).install(this._scrimEl, this._dialogEl);
+
+        // `_render` runs from `attributeChangedCallback` and from the response API, and an
+        // extra child appended after connect triggers neither. AFTER the routing: this
+        // derives once synchronously, and a `hidden` child area is not focusable, so
+        // deriving it on the not-yet-filled box sent the initial focus to the default
+        // response instead of into the content.
+        bindEmptySections(this._childEl);
 
         // Seed the headless model's text from the parsed markup; the attributes stay the
         // source of truth for what is rendered.
         this._model.heading = this.heading;
         this._model.body = this.body;
 
+        // And the two response IDs. `attributeChangedCallback` returns early until
+        // `_initialized`, so an attribute present in the MARKUP — the declarative case
+        // these attributes exist for — is never delivered to it. `heading` and `body`
+        // survive that only because `_render()` re-reads them from the attribute; these
+        // two live in the model and would simply be dropped.
+        const closeResponse = this.getAttribute('close-response');
+        if (closeResponse !== null) this._model.closeResponse = closeResponse;
+        this._model.defaultResponse = this.getAttribute('default-response');
+
         this._render();
     }
 
+    /**
+     * 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(el: AdwAlertResponse): void {
+        const id = el.getAttribute('id');
+        if (!id) return;
+        const appearance = (el.getAttribute('appearance') ?? 'default') as AdwResponseAppearance;
+        this.addResponse(id, (el.textContent ?? '').trim());
+        if (appearance !== 'default') this.setResponseAppearance(id, appearance);
+        if (el.getAttribute('enabled') === 'false') this.setResponseEnabled(id, false);
+    }
+
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null) {
         if (!this._initialized) return;
         if (oldValue === newValue) return;
@@ -220,6 +286,14 @@ export class AdwAlertDialog extends HTMLElement {
         } else if (name === 'body') {
             this._model.body = this.body;
             this.dispatchEvent(new CustomEvent('notify::body', { bubbles: true, detail: { body: this.body } }));
+        } else if (name === 'close-response') {
+            // The MODEL stays the source of truth for response semantics (see the
+            // header) — the attribute is a markup entry point that feeds it, so the
+            // setter is not mirrored back and there is no reflection loop. An absent
+            // attribute means "leave the model's default", not "reset to `close`".
+            if (newValue !== null) this.setCloseResponse(newValue);
+        } else if (name === 'default-response') {
+            this.setDefaultResponse(newValue);
         } else if (name === 'open') {
             this.dispatchEvent(new CustomEvent('notify::open', { bubbles: true, detail: { open: this.open } }));
             if (this.open) this._modal.present();
@@ -386,11 +460,13 @@ export class AdwAlertDialog extends HTMLElement {
         this.classList.toggle('open', this.open);
 
         const heading = this.heading;
-        this._headingEl.textContent = heading;
+        if (this.headingUseMarkup) this._headingEl.innerHTML = heading;
+        else this._headingEl.textContent = heading;
         this._headingEl.hidden = heading.length === 0;
 
         const body = this.body;
-        this._bodyEl.textContent = body;
+        if (this.bodyUseMarkup) this._bodyEl.innerHTML = body;
+        else this._bodyEl.textContent = body;
         this._bodyEl.hidden = body.length === 0;
 
         // Horizontal only when prefer-wide-layout is set AND there are at most two

package/src/elements/adw-dialog.ts

@@ -24,6 +24,7 @@
 // Copyright (c) 2023-2024 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 /** Adaptive presentation of the dialog — mirrors Adw.DialogPresentationMode. */
@@ -141,10 +142,6 @@ export class AdwDialog extends HTMLElement {
 
         this.classList.add('adw-dialog');
 
-        // Snapshot before the subtree is replaced: everything the author placed inside
-        // becomes the dialog content.
-        const contentChildren = Array.from(this.childNodes);
-
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-dialog-scrim';
         this._scrimEl.addEventListener('click', () => this._attemptClose());
@@ -187,11 +184,13 @@ export class AdwDialog extends HTMLElement {
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-dialog-content';
-        for (const child of contentChildren) this._contentEl.appendChild(child);
 
         this._boxEl.append(this._headerEl, this._contentEl);
         this._scrimEl.appendChild(this._boxEl);
-        this.replaceChildren(this._scrimEl);
+        // Everything the author places inside is the dialog content — LIVE, because
+        // `Adw.Dialog:child` is a property and a dialog whose body is filled in after it
+        // was created is the ordinary case. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [{ into: this._contentEl }]).install(this._scrimEl);
 
         this._render();
     }

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

@@ -37,6 +37,7 @@ import {
     type EntryRowRenderState,
 } from '@gjsify/adwaita-core';
 
+import { bindSlottedChildren, type AdwSlottedChildren } from '../slotted-children.js';
 import { type AdwIcon, createAdwIcon } from './adw-icon.js';
 
 /**
@@ -71,8 +72,11 @@ export class AdwEntryRow extends HTMLElement {
     protected _prefixes!: HTMLDivElement;
     protected _suffixes!: HTMLDivElement;
     protected _initialized = false;
-    /** Light-DOM children captured at build time, adopted after `_onConnected`. */
-    private _authored: Element[] = [];
+    /**
+     * The two slots, installed after `_onConnected` rather than inside `_build`: the order
+     * IS the contract — see the `install` call in `connectedCallback`.
+     */
+    private _slots!: AdwSlottedChildren;
     private _lastText = '';
     private _lastLength = 0;
 
@@ -159,11 +163,20 @@ export class AdwEntryRow extends HTMLElement {
         if (this.hasAttribute('text')) this._state.setText(this.getAttribute('text') ?? '');
         this._renderTitle();
 
-        // Subclass parts first, THEN the author's children: `AdwPasswordEntryRow`
-        // installs its peek toggle from its own `init`, so a consumer
-        // suffix lands after it and both remain.
+        // Subclass parts first, THEN the author's children: `AdwPasswordEntryRow` installs
+        // its peek toggle from its own `init`, so a consumer suffix lands after it and both
+        // remain. That ordering is why the structure is installed HERE and not at the end of
+        // `_build` — `install` routes the author's children on its way, and doing it a phase
+        // earlier would put every declared suffix in front of the password row's toggle.
         this._onConnected();
-        this._adoptAuthored();
+        this._slots.install(
+            this._prefixes,
+            this._area,
+            this._indicator,
+            this._applyButton,
+            this._editIcon,
+            this._suffixes,
+        );
 
         this._lastText = this._state.text;
         this._lastLength = this._state.textLength;
@@ -254,12 +267,6 @@ export class AdwEntryRow extends HTMLElement {
     private _build(): void {
         const prefix = this._classPrefix;
 
-        // Author-supplied light-DOM children are KEPT: `replaceChildren` used to
-        // discard them silently, so `<adw-entry-row><adw-button>Go</adw-button>`
-        // rendered without its button. Elements only — GtkBuildable also only
-        // ever adopts widgets, and keeping stray whitespace would make an empty
-        // affordance box measure as non-empty.
-        this._authored = [...this.children];
         this._prefixes = document.createElement('div');
         this._prefixes.className = `${prefix}-prefixes`;
         this._suffixes = document.createElement('div');
@@ -322,34 +329,26 @@ export class AdwEntryRow extends HTMLElement {
         this._editIcon = createAdwIcon('document-edit', 'adw-row-edit', `${prefix}-edit`);
         this._editIcon.dataset.iconName = ENTRY_ROW_EDIT_ICON_NAME;
 
-        // Snapshot order: indicator → apply → edit icon inside the editable area, with
-        // the prefixes/suffixes boxes outside it.
-        this.replaceChildren(
-            this._prefixes,
-            this._area,
-            this._indicator,
-            this._applyButton,
-            this._editIcon,
-            this._suffixes,
-        );
+        // Author-supplied light-DOM children are KEPT and stay LIVE: `replaceChildren` used
+        // to discard them silently, so `<adw-entry-row><adw-button>Go</adw-button>` rendered
+        // without its button, and the snapshot that fixed that was still a one-shot read — a
+        // suffix appended after connect sat outside the affordance box. ELEMENTS only, on
+        // both paths: GtkBuildable also only ever adopts widgets, and keeping stray
+        // whitespace would make an empty affordance box measure as non-empty. Consumed
+        // through the two `add*` methods, because their insertion rules differ —
+        // `addPrefix` PREPENDS, mirroring `gtk_box_prepend`. Structure order:
+        // indicator → apply → edit icon inside the editable area, prefixes/suffixes outside.
+        // `src/slotted-children.ts` has the incident.
+        this._slots = bindSlottedChildren(this, [
+            { name: 'prefix', consume: (node) => this.addPrefix(node) },
+            { name: 'suffix', claims: (node) => node instanceof Element, consume: (node) => this.addSuffix(node) },
+        ]);
         setPartVisible(this._prefixes, false);
         setPartVisible(this._suffixes, false);
 
         this.addEventListener('click', (event) => this._maybeFocus(event));
     }
 
-    /**
-     * 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(): void {
-        for (const node of this._authored) {
-            if (node.getAttribute('slot') === 'prefix') this.addPrefix(node);
-            else this.addSuffix(node);
-        }
-        this._authored = [];
-    }
-
     /**
      * `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/src/elements/adw-expander-row.ts

@@ -22,6 +22,7 @@
 import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 
 import { bindEmptySections } from '../empty-sections.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 // SIDE-EFFECT import, deliberately separate from the type import below: it guarantees
 // `adw-switch` is defined before this module's `customElements.define` can upgrade a
@@ -105,11 +106,6 @@ export class AdwExpanderRow extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const prefixChildren = Array.from(this.querySelectorAll(':scope > [slot="prefix"]'));
-        const suffixChildren = Array.from(this.querySelectorAll(':scope > [slot="suffix"]'));
-        const claimed = new Set<Node>([...prefixChildren, ...suffixChildren]);
-        const rows = Array.from(this.childNodes).filter((node) => !claimed.has(node));
-
         this._headerEl = document.createElement('div');
         this._headerEl.className = 'adw-expander-row-header';
 
@@ -130,25 +126,33 @@ export class AdwExpanderRow extends HTMLElement {
 
         this._prefixEl = document.createElement('div');
         this._prefixEl.className = 'adw-expander-row-prefix';
-        for (const child of prefixChildren) this._prefixEl.appendChild(child);
 
         this._suffixEl = document.createElement('div');
         this._suffixEl.className = 'adw-expander-row-suffix';
-        for (const child of suffixChildren) this._suffixEl.appendChild(child);
-
-        // Same reason as the action row's: `_render` is attribute-driven, and a widget
-        // appended into `prefixSection` after connect is a childList change nothing else
-        // hears. `contentSection` is NOT in here — an empty disclosure is still the
-        // disclosure, and `.expanded` alone decides whether it shows.
-        bindEmptySections(this._prefixEl, this._suffixEl);
 
         this._headerEl.append(this._prefixEl, textEl, this._suffixEl, this._enableSwitch, this._chevronEl);
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-expander-row-content';
-        for (const row of rows) this._contentEl.appendChild(row);
 
-        this.replaceChildren(this._headerEl, this._contentEl);
+        // Three LIVE slots: the two header sections by name, and the disclosure rows as the
+        // unnamed default — `adw_expander_row_add_row` works at any point in the widget's
+        // life, so a row appended after connect must reach the content box rather than sit
+        // beside it. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [
+            { name: 'prefix', into: this._prefixEl },
+            { name: 'suffix', into: this._suffixEl },
+            { into: this._contentEl },
+        ]).install(this._headerEl, this._contentEl);
+
+        // Same reason as the action row's: `_render` is attribute-driven, and a widget
+        // appended into `prefixSection` after connect is a childList change nothing else
+        // hears. `contentSection` is NOT in here — an empty disclosure is still the
+        // disclosure, and `.expanded` alone decides whether it shows.
+        //
+        // AFTER the routing: this derives once synchronously, so on a box the routing has
+        // not filled yet it hides a section that a declared child had already earned.
+        bindEmptySections(this._prefixEl, this._suffixEl);
 
         this._headerEl.addEventListener('click', (event) => {
             // Clicks on the enable switch toggle expansion-enable, not disclosure.

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

@@ -16,6 +16,8 @@
 // Copyright (c) 2025 csm. MIT License.
 // Modifications: Reimplemented as Web Component for @gjsify/adwaita-web.
 
+import { bindSlottedChildren } from '../slotted-children.js';
+
 // Registers <adw-window-title>: the derived centre is one, so importing the bar
 // alone must still define it.
 import './adw-window-title.js';
@@ -56,35 +58,41 @@ export class AdwHeaderBar extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // Capture any pre-existing slotted children before clearing
-        const startChildren = Array.from(this.querySelectorAll(':scope > [slot="start"]'));
-        const centerChildren = Array.from(this.querySelectorAll(':scope > [slot="center"]'));
-        const endChildren = Array.from(this.querySelectorAll(':scope > [slot="end"]'));
-
-        // Start section
         this._startEl = document.createElement('div');
         this._startEl.className = 'adw-header-bar-start';
-        for (const child of startChildren) this._startEl.appendChild(child);
 
-        // Center section — a `slot="center"` widget (title-widget) wins over the
-        // plain `title` text.
         this._centerEl = document.createElement('div');
         this._centerEl.className = 'adw-header-bar-center';
-        if (centerChildren.length > 0) {
-            for (const child of centerChildren) this._centerEl.appendChild(child);
-        } else {
-            this._titleEl = document.createElement('adw-window-title');
-            this._titleEl.className = 'adw-header-bar-title';
-            this._centerEl.appendChild(this._titleEl);
-        }
 
-        // End section
         this._endEl = document.createElement('div');
         this._endEl.className = 'adw-header-bar-end';
-        for (const child of endChildren) this._endEl.appendChild(child);
 
-        // Replace all children atomically
-        this.replaceChildren(this._startEl, this._centerEl, this._endEl);
+        // All three slots stay LIVE: a button appended with `slot="end"` after connect used
+        // to sit outside the end section, and `adw-header-bar.spec.ts` carried the
+        // workaround ("appended LAST") as a house rule. `src/slotted-children.ts` has the
+        // incident. The `onAdopt` hook keeps the title-widget either/or true afterwards —
+        // a centre widget that arrives late replaces the derived title, as setting
+        // `Adw.HeaderBar:title-widget` at any point does.
+        bindSlottedChildren(
+            this,
+            [
+                { name: 'start', into: this._startEl },
+                { name: 'center', into: this._centerEl },
+                { name: 'end', into: this._endEl },
+            ],
+            (_node, slot) => {
+                if (slot.name === 'center') this._dropDerivedTitle();
+            },
+        ).install(this._startEl, this._centerEl, this._endEl);
+
+        // Derived only when the centre is still free — the same either/or as
+        // `Adw.HeaderBar`, which builds an `AdwWindowTitle` exactly while no title-widget
+        // was given.
+        if (this._centerEl.childElementCount === 0) {
+            this._titleEl = document.createElement('adw-window-title');
+            this._titleEl.className = 'adw-header-bar-title';
+            this._centerEl.appendChild(this._titleEl);
+        }
         this._renderTitle();
     }
 
@@ -98,6 +106,17 @@ export class AdwHeaderBar extends HTMLElement {
         if (this._initialized) this._renderTitle();
     }
 
+    /**
+     * Give the centre up to a title-widget. `adw_header_bar_set_title_widget` destroys the
+     * derived `AdwWindowTitle` rather than stacking the two, so the late case has to remove
+     * it too — a bar showing both would be a shape neither GTK nor the declared markup can
+     * produce.
+     */
+    private _dropDerivedTitle() {
+        this._titleEl?.remove();
+        this._titleEl = null;
+    }
+
     private _renderTitle() {
         // A `slot="center"` widget replaced the derived title, so there is
         // nothing for the attribute to write to — the same either/or as

package/src/elements/adw-navigation-split-view.ts

@@ -36,6 +36,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindBreakpointSetter } from '../breakpoints.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 /** Detail of the `navigation-push` / `navigation-pop` delegation event. */
 export interface NavigationDelegateDetail {
@@ -142,18 +143,24 @@ export class AdwNavigationSplitView extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const sidebarChildren = Array.from(this.querySelectorAll(':scope > [slot="sidebar"]'));
-        const contentChildren = Array.from(this.querySelectorAll(':scope > [slot="content"]'));
-
         this._sidebarEl = document.createElement('div');
         this._sidebarEl.className = 'adw-nsv-sidebar';
-        for (const child of sidebarChildren) this._sidebarEl.appendChild(child);
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-nsv-content';
-        for (const child of contentChildren) this._contentEl.appendChild(child);
 
-        this.replaceChildren(this._sidebarEl, this._contentEl);
+        // Both panes stay LIVE. `adw_navigation_split_view_set_sidebar` is a property
+        // setter, callable whenever, so a pane appended after connect has to reach the
+        // pane box AND the state that decides the stack — which is what `_mountPane` does
+        // on the way. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(
+            this,
+            [
+                { name: 'sidebar', into: this._sidebarEl },
+                { name: 'content', into: this._contentEl },
+            ],
+            (_node, slot) => this._mountPane(slot.name === 'sidebar' ? 'sidebar' : 'content'),
+        ).install(this._sidebarEl, this._contentEl);
 
         // Parse-time attributes are the CONSTRUCTION properties, as in the overlay view:
         // applying them as sequential setters emits a transition for a state the markup
@@ -175,14 +182,30 @@ export class AdwNavigationSplitView extends HTMLElement {
         // Which children EXIST decides the stack, so the panes are mounted into the state
         // and not merely into the DOM — a lone child stays visible whatever
         // `show-content` says, which two CSS classes cannot express.
-        this._state.setSidebar(sidebarChildren.length > 0 ? { tag: this._tagOf(sidebarChildren) } : null);
-        this._state.setContent(contentChildren.length > 0 ? { tag: this._tagOf(contentChildren) } : null);
+        this._mountPane('sidebar');
+        this._mountPane('content');
         this._state.subscribe(() => {
             this._reflectShowContent();
             this._syncClasses();
         });
     }
 
+    /**
+     * 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(pane: 'sidebar' | 'content'): void {
+        const box = pane === 'sidebar' ? this._sidebarEl : this._contentEl;
+        const children = Array.from(box.children);
+        const page = children.length > 0 ? { tag: this._tagOf(children) } : null;
+        if (pane === 'sidebar') this._state.setSidebar(page);
+        else this._state.setContent(page);
+    }
+
     /** `Adw.NavigationPage:tag` off the slotted pane, or `null` when untagged. */
     private _tagOf(children: readonly Element[]): string | null {
         for (const child of children) {

package/src/elements/adw-overlay-split-view.ts

@@ -26,6 +26,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindBreakpointSetter } from '../breakpoints.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 
 /**
  * The reveal spring, as a CSS-timed animator: libadwaita animates with a spring
@@ -173,28 +174,26 @@ export class AdwOverlaySplitView extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        const sidebarChildren = Array.from(this.querySelectorAll('[slot="sidebar"]'));
-        const contentChildren = Array.from(this.querySelectorAll('[slot="content"]'));
-        const unslotted = Array.from(this.childNodes).filter(
-            (n) => !sidebarChildren.includes(n as Element) && !contentChildren.includes(n as Element),
-        );
-
-        this.replaceChildren();
-
         this._sidebarEl = document.createElement('div');
         this._sidebarEl.className = 'adw-osv-sidebar';
-        sidebarChildren.forEach((c) => this._sidebarEl.appendChild(c));
 
         this._contentEl = document.createElement('div');
         this._contentEl.className = 'adw-osv-content';
-        contentChildren.forEach((c) => this._contentEl.appendChild(c));
-        unslotted.forEach((c) => this._contentEl.appendChild(c));
 
         this._backdropEl = document.createElement('div');
         this._backdropEl.className = 'adw-osv-backdrop';
         this._backdropEl.addEventListener('click', () => this.hideSidebar());
 
-        this.append(this._sidebarEl, this._contentEl, this._backdropEl);
+        // Both panes stay LIVE, and the unnamed slot is the content — the
+        // Adw.OverlaySplitView buildable default. `src/slotted-children.ts` has the
+        // incident. The routing also stops at the DIRECT children, which the two
+        // selectors here did not: `[slot="sidebar"]` matched at any depth, so a nested
+        // split view's sidebar was stolen into the outer one's pane.
+        bindSlottedChildren(this, [
+            { name: 'sidebar', into: this._sidebarEl },
+            { name: 'content', into: this._contentEl },
+            { into: this._contentEl },
+        ]).install(this._sidebarEl, this._contentEl, this._backdropEl);
 
         // The attributes present at parse time ARE the construction options —
         // `Adw.OverlaySplitView` is built with its properties, not built and then

package/src/elements/adw-preferences-dialog.ts

@@ -50,6 +50,7 @@
 
 import type { PreferencesSearchResult, SearchPreferencesOptions } from '@gjsify/adwaita-core';
 import { searchPreferencesDom } from '../preferences-search.js';
+import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 const DEFAULT_CONTENT_WIDTH = 640;
@@ -207,12 +208,6 @@ export class AdwPreferencesDialog extends HTMLElement {
         if (this._initialized) return;
         this._initialized = true;
 
-        // The page ELEMENTS move into the body intact — their title / name / icon-name
-        // are what a search result subtitle and a view switcher read — and any unwrapped
-        // children follow them (Adw.PreferencesDialog's buildable default adds a child
-        // as a page).
-        const declared = Array.from(this.childNodes);
-
         // Clicking the scrim dismisses the dialog, or raises close-attempt when locked.
         this._scrimEl = document.createElement('div');
         this._scrimEl.className = 'adw-preferences-dialog-scrim';
@@ -253,12 +248,16 @@ export class AdwPreferencesDialog extends HTMLElement {
 
         this._pagesEl = document.createElement('div');
         this._pagesEl.className = 'adw-preferences-dialog-pages';
-        for (const child of declared) this._pagesEl.appendChild(child);
         this._bodyEl.appendChild(this._pagesEl);
 
         this._dialogEl.append(header, this._bodyEl);
 
-        this.replaceChildren(this._scrimEl, this._dialogEl);
+        // The page ELEMENTS move into the body intact — their title / name / icon-name are
+        // what a search result subtitle and a view switcher read — and any unwrapped child
+        // follows them (the Adw.PreferencesDialog buildable default adds a child as a
+        // page). LIVE, because `adw_preferences_dialog_add` works at any point in the
+        // dialog's life. `src/slotted-children.ts` has the incident.
+        bindSlottedChildren(this, [{ into: this._pagesEl }]).install(this._scrimEl, this._dialogEl);
 
         // The role, `aria-modal`, Escape (Adw.Dialog's shortcut → `maybe_close_cb`), the
         // Tab trap and the return-focus.