@gjsify/adwaita-web 0.44.0 → 0.46.0

package/src/{adw-checks.spec.ts → checks.spec.ts}

@@ -1,4 +1,4 @@
-// DOM-level tests for <adw-checkbox> and <adw-radio>, plus the browser side of
+// DOM-level tests for <gtk-check-button> and <adw-radio>, plus the browser side of
 // the `RADIO_GROUP_VECTORS` conformance table.
 //
 // The browser's native radio exclusivity is NOT enough: `<input type="radio" name="g">`
@@ -14,7 +14,7 @@
 import { describe, expect, it } from '@gjsify/unit';
 import { RADIO_GROUP_VECTORS } from '@gjsify/adwaita-core/conformance';
 
-import type { AdwCheckbox, AdwRadio } from './elements/adw-checks.js';
+import type { GtkCheckButton, AdwRadio } from './elements/checks.js';
 
 function host(): HTMLElement {
     const el = document.createElement('div');
@@ -22,9 +22,9 @@ function host(): HTMLElement {
     return el;
 }
 
-function mountCheckbox(): { el: AdwCheckbox; parent: HTMLElement } {
+function mountCheckbox(): { el: GtkCheckButton; parent: HTMLElement } {
     const parent = host();
-    const el = document.createElement('adw-checkbox') as AdwCheckbox;
+    const el = document.createElement('gtk-check-button') as GtkCheckButton;
     parent.appendChild(el);
     return { el, parent };
 }
@@ -51,7 +51,7 @@ function glyph(check: HTMLElement): string {
 }
 
 export const AdwChecksTest = async () => {
-    await describe('<adw-checkbox> state', async () => {
+    await describe('<gtk-check-button> state', async () => {
         await it('builds the input + indicator + label markup', () => {
             const { el, parent } = mountCheckbox();
             const { input, indicator, label } = parts(el);
@@ -69,13 +69,13 @@ export const AdwChecksTest = async () => {
 
         await it('adopts authored child nodes as the label, and the attribute wins', () => {
             const parent = host();
-            const authored = document.createElement('adw-checkbox') as AdwCheckbox;
+            const authored = document.createElement('gtk-check-button') as GtkCheckButton;
             authored.textContent = 'Enable';
             parent.appendChild(authored);
             expect(parts(authored).label.textContent).toBe('Enable');
             expect(parts(authored).label.hidden).toBe(false);
 
-            const labelled = document.createElement('adw-checkbox') as AdwCheckbox;
+            const labelled = document.createElement('gtk-check-button') as GtkCheckButton;
             labelled.setAttribute('label', 'From the attribute');
             labelled.textContent = 'ignored';
             parent.appendChild(labelled);
@@ -133,7 +133,7 @@ export const AdwChecksTest = async () => {
         });
     });
 
-    await describe('<adw-checkbox> indeterminate', async () => {
+    await describe('<gtk-check-button> indeterminate', async () => {
         await it('announces as mixed and outranks checked', () => {
             const { el, parent } = mountCheckbox();
             el.checked = true;
@@ -152,7 +152,7 @@ export const AdwChecksTest = async () => {
             // three states proves the cascade, not just that a mask exists.
             const parent = host();
             const make = (attrs: string[]) => {
-                const el = document.createElement('adw-checkbox') as AdwCheckbox;
+                const el = document.createElement('gtk-check-button') as GtkCheckButton;
                 for (const attr of attrs) el.setAttribute(attr, '');
                 parent.appendChild(el);
                 return el;
@@ -181,7 +181,7 @@ export const AdwChecksTest = async () => {
     await describe('check and radio share one stylesheet', async () => {
         await it('both draw the 14px + 3px indicator, differing only in the radius', () => {
             const parent = host();
-            const check = document.createElement('adw-checkbox') as AdwCheckbox;
+            const check = document.createElement('gtk-check-button') as GtkCheckButton;
             const radio = document.createElement('adw-radio') as AdwRadio;
             parent.append(check, radio);
 
@@ -219,7 +219,7 @@ export const AdwChecksTest = async () => {
             radio.setAttribute('name', 'fill-checked');
             radio.setAttribute('value', 'x');
             radio.setAttribute('checked', '');
-            const check = document.createElement('adw-checkbox') as AdwCheckbox;
+            const check = document.createElement('gtk-check-button') as GtkCheckButton;
             check.setAttribute('checked', '');
             parent.append(plain, radio, check);
 

package/src/chrome.spec.ts

@@ -153,7 +153,7 @@ const ROOT_ACTION_PREVIEW = `
     <adw-window-title slot="center" title="Contacts"></adw-window-title>
   </adw-header-bar>
   <div style="display: flex; align-items: center; justify-content: center; width: 100%; height: 100%;">
-    <adw-button label="Open contact" pill suggested></adw-button>
+    <gtk-button label="Open contact" pill suggested></gtk-button>
   </div>
 </adw-toolbar-view>`;
 
@@ -530,7 +530,7 @@ export const AdwChromeTest = async () => {
             const host = mountPreview(ROOT_ACTION_PREVIEW);
             await settle();
             const area = host.querySelector('.adw-toolbar-view-content') as HTMLElement;
-            const button = host.querySelector('adw-button') as HTMLElement;
+            const button = host.querySelector('gtk-button') as HTMLElement;
 
             expect(heightOf(area.firstElementChild)).toBe(heightOf(area));
             // A pill button that grew to the pane's height would be the fill applied

package/src/connect-lifecycle.spec.ts

@@ -24,10 +24,14 @@
 import { describe, expect, it } from '@gjsify/unit';
 
 import * as adwaitaWeb from './index.js';
+// Not a bare `Object.values` walk: since ADR 0034 § Amendment 6 the widget classes are
+// members of the exported `Adw`/`Gtk` objects, so a top-level scan reaches only the
+// web-only stragglers while reading as if it swept the package.
+import { exportedElementClasses } from './exported-elements.js';
 
 /**
  * Elements that cannot RENDER a child, however the DOM lets you append one. A container
- * getter returning one of these is an imperative handle (`<adw-entry>.input`, for
+ * getter returning one of these is an imperative handle (`<gtk-entry>.input`, for
  * focus and selection), not an append point, and appending to it measures 0 forever.
  * The HTML void-element set, not a per-widget ledger — a new container still enrols
  * itself; only a new void element in the spec would need a line here.
@@ -85,9 +89,8 @@ function reveal(el: HTMLElement): void {
 function registeredElements(): { tags: string[]; unregistered: string[] } {
     const tags: string[] = [];
     const unregistered: string[] = [];
-    for (const exported of Object.values(adwaitaWeb)) {
-        if (typeof exported !== 'function' || !(exported.prototype instanceof HTMLElement)) continue;
-        const tag = customElements.getName(exported as CustomElementConstructor);
+    for (const exported of exportedElementClasses(adwaitaWeb)) {
+        const tag = customElements.getName(exported);
         if (tag === null) unregistered.push(exported.name);
         else tags.push(tag);
     }
@@ -101,7 +104,7 @@ function registeredElements(): { tags: string[]; unregistered: string[] } {
  * Each half earns its place. No setter, because a container you append into is not one
  * you replace by assignment — that is what separates `topBar` from `anchor` and
  * `activatableWidget`. Contained, because the handle has to be part of THIS widget's
- * own subtree — `<adw-popover>.anchor` defaults to `parentElement` and is not. And a
+ * own subtree — `<gtk-popover>.anchor` defaults to `parentElement` and is not. And a
  * value that is not an element at all (`items`, `groups`, a `null` slot on an empty
  * widget) is nothing to append to.
  *
@@ -326,9 +329,9 @@ export const AdwConnectLifecycleTest = async () => {
             });
         }
 
-        await it('<adw-popover> still dismisses on an outside click after a move', async () => {
+        await it('<gtk-popover> still dismisses on an outside click after a move', async () => {
             const first = visibleHost();
-            const popover = document.createElement('adw-popover');
+            const popover = document.createElement('gtk-popover');
             first.appendChild(popover);
             (popover as HTMLElement & { popup(): void }).popup();
 

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

@@ -55,7 +55,7 @@
 // Reference: refs/adwaita-web/adwaita-web/scss/_about_dialog.scss (web layout)
 // Copyright (c) 2022-2024 GNOME Foundation Inc. / Purism SPC (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
-// icon nodes are <adw-icon>; the derivations live in @gjsify/adwaita-core.
+// icon nodes are <gtk-image>; the derivations live in @gjsify/adwaita-core.
 
 import {
     ADW_ABOUT_DIALOG_LABELS,
@@ -67,7 +67,7 @@ import {
     stripMnemonic,
 } from '@gjsify/adwaita-core';
 
-import { createAdwIcon } from './adw-icon.js';
+import { createGtkImage } from './gtk-image.js';
 import { AdwModalSurface } from './modal-surface.js';
 
 /** A template label with its mnemonic marker removed — this renderer has no accelerator layer. */
@@ -440,7 +440,7 @@ export class AdwAboutDialog extends HTMLElement {
         // `image-missing` rather than three stray classes; that is also what GTK draws for
         // it on a machine without the app installed.
         if (visibility.appIcon) {
-            body.appendChild(createAdwIcon(this.applicationIcon, 'adw-about-dialog-icon'));
+            body.appendChild(createGtkImage(this.applicationIcon, 'adw-about-dialog-icon'));
         }
 
         // No fallback: an unset name means no label.
@@ -518,7 +518,7 @@ export class AdwAboutDialog extends HTMLElement {
         row.setAttribute('title', title);
         row.setAttribute('activatable', '');
 
-        const chevron = createAdwIcon('go-next', 'adw-about-dialog-chevron');
+        const chevron = createGtkImage('go-next', 'adw-about-dialog-chevron');
         chevron.setAttribute('slot', 'suffix');
         row.appendChild(chevron);
 
@@ -569,7 +569,7 @@ export class AdwAboutDialog extends HTMLElement {
         row.setAttribute('activatable', '');
         row.classList.add('adw-about-dialog-link-row');
 
-        const chevron = createAdwIcon('go-next', 'adw-about-dialog-chevron');
+        const chevron = createGtkImage('go-next', 'adw-about-dialog-chevron');
         chevron.setAttribute('slot', 'suffix');
         row.appendChild(chevron);
 
@@ -603,7 +603,7 @@ export class AdwAboutDialog extends HTMLElement {
             const uri = person.uri ?? '';
             row.setAttribute('activatable', '');
             row.classList.add('adw-about-dialog-link-row');
-            const chevron = createAdwIcon('go-next', 'adw-about-dialog-chevron');
+            const chevron = createGtkImage('go-next', 'adw-about-dialog-chevron');
             chevron.setAttribute('slot', 'suffix');
             row.appendChild(chevron);
             row.addEventListener('activated', () => this._activateLink(uri));

package/src/elements/adw-avatar.ts

@@ -7,7 +7,7 @@
 // Reference: refs/adwaita-web/adwaita-web/scss/_avatar.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
-// fallback icon node is <adw-icon>.
+// fallback icon node is <gtk-image>.
 //
 // The two derivations — initials from the name, and the palette colour the name hashes to
 // — are HEADLESS and live in `@gjsify/adwaita-core` (ADR 0004) as {@link avatarInitials} /
@@ -21,11 +21,11 @@
 
 import { avatarColor, avatarFontSize, avatarInitials, avatarMaxFontSize, avatarMode } from '@gjsify/adwaita-core';
 
-import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { type GtkImage, createGtkImage } from './gtk-image.js';
 
 export class AdwAvatar extends HTMLElement {
     private _textEl!: HTMLSpanElement;
-    private _iconEl!: AdwIcon;
+    private _iconEl!: GtkImage;
     private _imageEl!: HTMLImageElement;
     private _initialized = false;
 
@@ -40,7 +40,7 @@ export class AdwAvatar extends HTMLElement {
         this._textEl = document.createElement('span');
         this._textEl.className = 'adw-avatar-text';
 
-        this._iconEl = createAdwIcon(null, 'adw-avatar-icon');
+        this._iconEl = createGtkImage(null, 'adw-avatar-icon');
 
         this._imageEl = document.createElement('img');
         this._imageEl.className = 'adw-avatar-custom-image';

package/src/elements/adw-button-content.ts

@@ -20,15 +20,15 @@
 //            (image-text-button · the splitbutton override · buttoncontent)
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
-// icon node is <adw-icon>.
+// icon node is <gtk-image>.
 
 import { BUTTON_CONTENT_STYLE_CLASS, buttonContentIconName, buttonContentLabelText } from '@gjsify/adwaita-core';
 
-import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { type GtkImage, createGtkImage } from './gtk-image.js';
 
 /**
  * What `gtk_widget_get_ancestor (…, GTK_TYPE_BUTTON)` looks like in the DOM: a native
- * `<button>`, or anything wearing the Adwaita button class — `<adw-button>` renders an
+ * `<button>`, or anything wearing the Adwaita button class — `<gtk-button>` renders an
  * inner button with it, and the stories put it on plain ones.
  */
 const BUTTON_SELECTOR = 'button, .adw-button';
@@ -38,7 +38,7 @@ const SPLIT_BUTTON_SELECTOR = 'adw-split-button, .adw-split-button';
 
 export class AdwButtonContent extends HTMLElement {
     private _boxEl!: HTMLDivElement;
-    private _iconEl!: AdwIcon;
+    private _iconEl!: GtkImage;
     private _labelEl!: HTMLSpanElement;
     private _initialized = false;
     /** The node currently carrying `image-text-button`, so unroot can find it. */
@@ -57,9 +57,9 @@ export class AdwButtonContent extends HTMLElement {
             this._boxEl.className = 'adw-button-content-box';
 
             // The image node is GTK_ACCESSIBLE_ROLE_PRESENTATION in libadwaita: decorative,
-            // with the label carrying the accessible name — what `<adw-icon>`'s own
+            // with the label carrying the accessible name — what `<gtk-image>`'s own
             // `aria-hidden` already says.
-            this._iconEl = createAdwIcon(null);
+            this._iconEl = createGtkImage(null);
 
             this._labelEl = document.createElement('span');
             this._labelEl.className = 'adw-button-content-label';

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

@@ -21,13 +21,13 @@
 
 import { BUTTON_ROW_ACTIVATABLE, ButtonRowState } from '@gjsify/adwaita-core';
 
-import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { type GtkImage, createGtkImage } from './gtk-image.js';
 import { attachRowActivation } from './row-activation.js';
 
 export class AdwButtonRow extends HTMLElement {
     private _contentsEl!: HTMLDivElement;
-    private _startIconEl!: AdwIcon;
-    private _endIconEl!: AdwIcon;
+    private _startIconEl!: GtkImage;
+    private _endIconEl!: GtkImage;
     private _titleEl!: HTMLSpanElement;
     /** The headless title + start/end icon state (ADR 0004). */
     private readonly _state = new ButtonRowState();
@@ -43,12 +43,12 @@ export class AdwButtonRow extends HTMLElement {
         this._contentsEl = document.createElement('div');
         this._contentsEl.className = 'adw-button-row-contents';
 
-        this._startIconEl = createAdwIcon(null, 'start');
+        this._startIconEl = createGtkImage(null, 'start');
 
         this._titleEl = document.createElement('span');
         this._titleEl.className = 'adw-button-row-title';
 
-        this._endIconEl = createAdwIcon(null, 'end');
+        this._endIconEl = createGtkImage(null, 'end');
 
         this._contentsEl.append(this._startIconEl, this._titleEl, this._endIconEl);
         this.replaceChildren(this._contentsEl);
@@ -89,7 +89,7 @@ export class AdwButtonRow extends HTMLElement {
      * The `start` / `end` position class is set once at construction — it is
      * where the node sits, not what it draws — so only the name changes here.
      */
-    private _paintIcon(el: AdwIcon, iconName: string, visible: boolean) {
+    private _paintIcon(el: GtkImage, iconName: string, visible: boolean) {
         el.iconName = visible ? iconName : null;
         el.hidden = !visible;
     }

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

@@ -43,7 +43,7 @@ export class AdwComboRow extends HTMLElement {
         const items: string[] = JSON.parse(this.getAttribute('items') || '[]');
         // Seed the headless state BEFORE subscribing, so building the initial DOM below is
         // not driven by a change notification. The string→descriptor mapping is core's, so
-        // this row and `<adw-drop-down>` accept one option vocabulary.
+        // this row and `<gtk-drop-down>` accept one option vocabulary.
         this._state.setOptions(normalizeComboOptions(items));
         this._state.setSelectedIndex(parseInt(this.getAttribute('selected') || '0', 10));
         const selectedIdx = this._state.selectedIndex;

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

@@ -27,7 +27,7 @@
 // Reference: refs/libadwaita/src/stylesheet/widgets/_entries.scss
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
-// edit icon node is <adw-icon>.
+// edit icon node is <gtk-image>.
 
 import {
     ENTRY_ROW_APPLY_ICON_NAME,
@@ -38,7 +38,7 @@ import {
 } from '@gjsify/adwaita-core';
 
 import { bindSlottedChildren, type AdwSlottedChildren } from '../slotted-children.js';
-import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { type GtkImage, createGtkImage } from './gtk-image.js';
 
 /**
  * Show/hide a rendered part. `hidden` carries the semantics and is what the conformance
@@ -66,7 +66,7 @@ export class AdwEntryRow extends HTMLElement {
     protected _title!: HTMLSpanElement;
     /** The `editable-area` gizmo: both titles plus the input. */
     protected _area!: HTMLDivElement;
-    protected _editIcon!: AdwIcon;
+    protected _editIcon!: GtkImage;
     protected _indicator!: HTMLSpanElement;
     protected _applyButton!: HTMLButtonElement;
     protected _prefixes!: HTMLDivElement;
@@ -326,11 +326,11 @@ export class AdwEntryRow extends HTMLElement {
         // The libadwaita name travels in `data-icon-name`; the drawn glyph is
         // the curated @gjsify/adwaita-icons spelling of the same symbolic, which
         // is a different string (`adw-entry-edit-symbolic` vs `document-edit`).
-        this._editIcon = createAdwIcon('document-edit', 'adw-row-edit', `${prefix}-edit`);
+        this._editIcon = createGtkImage('document-edit', 'adw-row-edit', `${prefix}-edit`);
         this._editIcon.dataset.iconName = ENTRY_ROW_EDIT_ICON_NAME;
 
         // 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
+        // to discard them silently, so `<adw-entry-row><gtk-button>Go</gtk-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

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

@@ -17,7 +17,7 @@
 // Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
 // disclosure state machine composed from @gjsify/adwaita-core, the enable
-// switch from <adw-switch> and the chevron from <adw-icon>.
+// switch from <gtk-switch> and the chevron from <gtk-image>.
 
 import { ExpanderState, deriveRowLabels } from '@gjsify/adwaita-core';
 
@@ -25,22 +25,22 @@ 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
+// `gtk-switch` is defined before this module's `customElements.define` can upgrade a
 // server-rendered `<adw-expander-row>` and build one. A combined
-// `import { AdwSwitch }` would NOT do it — the binding is only used in type position,
+// `import { GtkSwitch }` would NOT do it — the binding is only used in type position,
 // and this package compiles without `verbatimModuleSyntax`, so TypeScript would elide
 // the statement and take the registration with it.
-import './adw-switch.js';
-import type { AdwSwitch } from './adw-switch.js';
-import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import './gtk-switch.js';
+import type { GtkSwitch } from './gtk-switch.js';
+import { type GtkImage, createGtkImage } from './gtk-image.js';
 import { attachRowActivation } from './row-activation.js';
 
 export class AdwExpanderRow extends HTMLElement {
     private _headerEl!: HTMLDivElement;
     private _titleEl!: HTMLSpanElement;
     private _subtitleEl!: HTMLSpanElement;
-    private _enableSwitch!: AdwSwitch;
-    private _chevronEl!: AdwIcon;
+    private _enableSwitch!: GtkSwitch;
+    private _chevronEl!: GtkImage;
     private _contentEl!: HTMLDivElement;
     private _prefixEl!: HTMLDivElement;
     private _suffixEl!: HTMLDivElement;
@@ -118,11 +118,11 @@ export class AdwExpanderRow extends HTMLElement {
         textEl.append(this._titleEl, this._subtitleEl);
 
         // Clicking the enable switch does NOT toggle the disclosure.
-        this._enableSwitch = document.createElement('adw-switch') as AdwSwitch;
+        this._enableSwitch = document.createElement('gtk-switch') as GtkSwitch;
         this._enableSwitch.classList.add('adw-expander-row-enable-switch');
         this._enableSwitch.active = this.enableExpansion;
 
-        this._chevronEl = createAdwIcon('go-down', 'adw-expander-row-chevron');
+        this._chevronEl = createGtkImage('go-down', 'adw-expander-row-chevron');
 
         this._prefixEl = document.createElement('div');
         this._prefixEl.className = 'adw-expander-row-prefix';

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
@@ -29,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;
 
@@ -86,8 +100,9 @@ export class AdwHeaderBar extends HTMLElement {
         ).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.
+        // `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';
@@ -99,18 +114,24 @@ export 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() {
         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.
+     * 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();

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

@@ -100,8 +100,20 @@ export class AdwNavigationPage extends HTMLElement {
         // back-button derivation read the CORE's copy — so a runtime change has to
         // be pushed into it. Without this the back button only ever reflected the
         // `can-pop` value it had at the last stack mutation.
-        const view = this.closest('adw-navigation-view') as AdwNavigationView | null;
-        view?.syncPageProperty(this, name, previous);
+        //
+        // `instanceof` rather than a cast plus `?.`: the two failures the `?.`
+        // conflated are different. A MISSING ancestor is one; an ancestor that IS
+        // there but is still an ordinary HTMLElement, because its own definition has
+        // not upgraded it yet, is the other, and the cast asserted it away. Measured
+        // on `dist/test.browser.mjs` against declared markup parsed before the module
+        // loaded: `syncPageProperty is not a function`, once per observed attribute
+        // per declared page. Dropping the notification for an un-upgraded view loses
+        // nothing — such a view has not registered this page, `syncPageProperty`
+        // already returns on `!isRegistered`, and `connectedCallback` reads the
+        // properties back out of the element through `readPageProps`.
+        const view = this.closest('adw-navigation-view');
+        if (!(view instanceof AdwNavigationView)) return;
+        view.syncPageProperty(this, name, previous);
     }
 
     revertAttribute(name: string, value: string | null): void {
@@ -445,7 +457,7 @@ export class AdwNavigationView extends HTMLElement {
         const start = (headerBar as { startSection?: HTMLElement | null }).startSection ?? null;
         if (!start) return;
 
-        const back = document.createElement('adw-button');
+        const back = document.createElement('gtk-button');
         back.classList.add('adw-navigation-back-button');
         back.setAttribute('icon', 'go-previous');
         back.setAttribute('flat', '');
@@ -464,5 +476,13 @@ export class AdwNavigationView extends HTMLElement {
     }
 }
 
-customElements.define('adw-navigation-page', AdwNavigationPage);
+// The VIEW first, and the order carries weight: `define` upgrades every matching
+// element already in the document, immediately, so these two calls are a sequence and
+// not a pair. Registering the page first upgraded every declared
+// `<adw-navigation-page>` while its `<adw-navigation-view>` parent was still an
+// ordinary HTMLElement, and `AdwNavigationPage.attributeChangedCallback` reaches for
+// that parent. Parent before child keeps the window shut; the `instanceof` guard in
+// the callback is what holds when something outside this file reopens it.
+// `scripts/check-adwaita-upgrade-order.mjs` holds the order itself.
 customElements.define('adw-navigation-view', AdwNavigationView);
+customElements.define('adw-navigation-page', AdwNavigationPage);

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

@@ -22,7 +22,7 @@
 
 import { PasswordEntryRowState, type PasswordEntryRowRenderState } from '@gjsify/adwaita-core';
 
-import { type AdwIcon, createAdwIcon } from './adw-icon.js';
+import { type GtkImage, createGtkImage } from './gtk-image.js';
 
 import { AdwEntryRow } from './adw-entry-row.js';
 
@@ -30,7 +30,7 @@ export class AdwPasswordEntryRow extends AdwEntryRow {
     /** The headless peek + caps-lock derivation, composing the parent row's state. */
     private readonly _password = new PasswordEntryRowState(this._state);
     private _toggle!: HTMLButtonElement;
-    private _toggleIcon!: AdwIcon;
+    private _toggleIcon!: GtkImage;
 
     static get observedAttributes(): string[] {
         return [...AdwEntryRow.observedAttributes, 'revealed'];
@@ -73,7 +73,7 @@ export class AdwPasswordEntryRow extends AdwEntryRow {
         this._toggle = document.createElement('button');
         this._toggle.type = 'button';
         this._toggle.className = `adw-button flat circular icon-only ${this._classPrefix}-toggle`;
-        this._toggleIcon = createAdwIcon(null);
+        this._toggleIcon = createGtkImage(null);
         this._toggle.append(this._toggleIcon);
         this._toggle.addEventListener('click', () => this._password.togglePeek());
         // Installed through add_suffix as C does, so it is the FIRST suffix and a

package/src/elements/adw-sidebar.ts

@@ -43,7 +43,7 @@
 // Reference: refs/libadwaita/src/stylesheet/widgets/_sidebars.scss (.navigation-sidebar, sidebar)
 // Copyright (c) 2025 GNOME Foundation Inc. (libadwaita). LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web; the
-// icon nodes are <adw-icon>.
+// icon nodes are <gtk-image>.
 
 import {
     ADW_SIDEBAR_NO_SELECTION,
@@ -56,7 +56,7 @@ import {
     type SidebarSelectionChange,
 } from '@gjsify/adwaita-core';
 
-import { createAdwIcon } from './adw-icon.js';
+import { createGtkImage } from './gtk-image.js';
 import { attachRovingFocus } from './roving-focus.js';
 
 // The sidebar consumes its declared children and drops them from the tree, so a later
@@ -348,7 +348,7 @@ export class AdwSidebar extends HTMLElement {
         row.hidden = item.visible === false;
         row.disabled = item.enabled === false;
 
-        const iconEl = createAdwIcon(item.iconName ?? null, 'adw-sidebar-item-icon');
+        const iconEl = createGtkImage(item.iconName ?? null, 'adw-sidebar-item-icon');
         iconEl.hidden = !flat.iconVisible;
         row.appendChild(iconEl);
 
@@ -371,7 +371,7 @@ export class AdwSidebar extends HTMLElement {
 
         // Page mode adds a trailing chevron on every row, the way the boxed-list
         // AdwActionRow carries a `go-next-symbolic` arrow.
-        row.appendChild(createAdwIcon('go-next', 'adw-sidebar-item-arrow'));
+        row.appendChild(createGtkImage('go-next', 'adw-sidebar-item-arrow'));
 
         row.addEventListener('click', () => this._activate(flat.index));