@gjsify/adwaita-web 0.43.0 → 0.45.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

@@ -1,8 +1,20 @@
 // <adw-header-bar> — Adwaita header bar with centered title and start/end button slots.
 //
-// The derived centre is an `<adw-window-title>`, which is what `Adw.HeaderBar`
-// itself puts there (`adw-header-bar.c`: the title widget it creates when none is
-// given IS an `AdwWindowTitle`). It used to be a bare span with
+// The derived centre is an `<adw-window-title>`. That is a DIVERGENCE, and the comment
+// here used to claim the opposite — that `Adw.HeaderBar` puts one there. Measured
+// against the source: `construct_title_label` (adw-header-bar.c:512) builds a plain
+// `gtk_label_new (NULL)` with the `title` class, `single-line-mode` and
+// `ellipsize=END`, and `Adw.HeaderBar` has NO `title` property at all — `update_title`
+// (:475) resolves one from the navigation page, then the dialog, then the root window,
+// then `g_get_application_name`, then `g_get_prgname`. An app that wants a subtitle
+// there sets an `AdwWindowTitle` as its title-widget.
+//
+// The divergence is kept: a declarative surface wants `title=` / `subtitle=` attributes
+// rather than a widget handoff, and both renderers already use them. It is recorded as
+// `HeaderBarRenderState.derivedSubtitle` in `@gjsify/adwaita-core`, so it is a named
+// difference instead of a mistaken claim of fidelity.
+//
+// It used to be a bare span with
 // `textContent = title ?? ''`, and that span carried none of the three rules the
 // window title already held in `@gjsify/adwaita-core`: an EMPTY title still
 // reserved a blank line, re-setting the same value repainted, and there was no
@@ -16,6 +28,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';
@@ -27,8 +41,10 @@ export class AdwHeaderBar extends HTMLElement {
     private _endEl: HTMLDivElement | null = null;
     /**
      * 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: HTMLElement | null = null;
 
@@ -56,48 +72,72 @@ 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 runs `construct_title_label` exactly while no
+        // title-widget holds the centre (adw-header-bar.c:1211). What it builds there is
+        // a `GtkLabel`; this is the documented `<adw-window-title>` divergence.
+        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();
     }
 
     /**
      * `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() {
         if (this._initialized) this._renderTitle();
     }
 
+    /**
+     * 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() {
+        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) {