@gjsify/adwaita-web 0.48.0 → 0.49.0

package/lib/types/elements/adw-tab-view.d.ts

@@ -23,13 +23,19 @@ export declare class AdwTabView extends HTMLElement {
     private readonly _hovered;
     private _initialized;
     private _generatedIds;
-    /** Guards the `selected` attribute reflection against re-entering the model. */
+    /** Guards the `selected-page` attribute reflection against re-entering the model. */
     private _reflecting;
     static get observedAttributes(): string[];
     constructor();
-    /** Zero-based index of the visible page, `-1` when the view is empty. */
-    get selected(): number;
-    set selected(value: number);
+    /**
+     * The selected page (`Adw.TabView:selected-page`), `null` when the view is empty.
+     *
+     * THE PAGE, NOT ITS POSITION (ADR 0048). Its position is {@link selectedIndex}, which
+     * stays a read-only report; `Adw.TabView` selects by object, and the model has held
+     * that object all along.
+     */
+    get selectedPage(): AdwTabViewPage | null;
+    set selectedPage(page: AdwTabViewPage | null);
     /**
      * Whether the tab bar hides itself when it has nothing to show —
      * `tabsRevealed`, which keeps the bar up for a single PINNED tab.
@@ -57,7 +63,8 @@ export declare class AdwTabView extends HTMLElement {
     get selectedIndex(): number;
     get selectedContent(): HTMLElement | null;
     isClosing(id: string): boolean;
-    setSelectedPage(id: string | null): boolean;
+    /** `adw_tab_view_set_selected_page`, which takes the PAGE; an id is accepted too. */
+    setSelectedPage(page: AdwTabViewPage | string | null): boolean;
     selectNthPage(n: number): boolean;
     selectPreviousPage(): boolean;
     selectNextPage(): boolean;
@@ -142,6 +149,17 @@ export declare class AdwTabView extends HTMLElement {
     private _scrollSelectedTabIntoBar;
     private _applyBarVisibility;
     private _reflectSelected;
+    /**
+     * `selected-page="<page id>"` — the markup half of {@link selectedPage} (ADR 0048).
+     *
+     * The id is the one `<adw-tab-page page-id>` declares; a page that declares none gets
+     * a generated one, which an author cannot predict and therefore cannot select by. That
+     * is the same bargain `<adw-view-stack visible-child-name>` already makes for a page
+     * with no name, and it is why `page-id` exists.
+     *
+     * An id no page holds is IGNORED rather than treated as the first page — libadwaita
+     * refuses a foreign `AdwTabPage` outright, and `setSelectedPage` is the refusal here.
+     */
     private _applySelectedAttribute;
     /**
      * The `Adw.TabView` shortcut table (`init_shortcuts`), plus the ArrowLeft/ArrowRight

package/lib/types/elements/adw-view-stack.d.ts

@@ -6,9 +6,24 @@ export declare class AdwViewStack extends HTMLElement {
     static get observedAttributes(): string[];
     constructor();
     get pages(): readonly AdwViewStackPageInfo[];
-    /** Zero-based index of the visible page, `-1` when nothing is selected. */
+    /**
+     * Zero-based position of the visible page, `-1` when nothing is selected.
+     *
+     * A REPORT, NOT A DOOR (ADR 0048). `Adw.ViewStack` selects by NAME, and an ordinal is
+     * derived — an insertion before the visible page increments it, a reorder rewrites it,
+     * a removal decrements it. Selecting is {@link visibleChildName}.
+     */
     get visibleChildIndex(): number;
-    set visibleChildIndex(value: number);
+    /**
+     * Show the page at position `n`. Returns whether the selection moved.
+     *
+     * THE ORDINAL IS A CALL, NOT A PROPERTY (ADR 0048): it resolves against the page list
+     * as it is now and keeps nothing, where a held index comes to mean another page after
+     * an insert, a reorder or a removal. Port-owned — `refs/libadwaita` gives
+     * `AdwViewStack` no ordinal API — and named for the tab view's existing
+     * `selectNthPage`. The guard on `n` is the core's and is pinned by the shared vectors.
+     */
+    selectNthPage(n: number): boolean;
     get visibleChildName(): string;
     set visibleChildName(name: string | null | undefined);
     get visibleChild(): HTMLElement | null;

package/lib/types/shared-trees.spec.d.ts

@@ -0,0 +1,2 @@
+import '@gjsify/adwaita-web';
+export declare const AdwSharedTreesTest: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.48.0",
+    "version": "0.49.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -45,14 +45,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.48.0",
-        "@gjsify/adwaita-fonts": "^0.48.0",
-        "@gjsify/adwaita-icons": "^0.48.0",
+        "@gjsify/adwaita-core": "^0.49.0",
+        "@gjsify/adwaita-fonts": "^0.49.0",
+        "@gjsify/adwaita-icons": "^0.49.0",
         "@lezer/highlight": "^1.2.3"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.48.0",
-        "@gjsify/unit": "^0.48.0",
+        "@gjsify/cli": "^0.49.0",
+        "@gjsify/unit": "^0.49.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/src/adw-avatar.spec.ts

@@ -13,6 +13,7 @@ import { AVATAR_COLORS, avatarMaxFontSize } from '@gjsify/adwaita-core';
 import {
     AVATAR_COLOR_VECTORS,
     AVATAR_FONT_SIZE_VECTORS,
+    AVATAR_ICON_SIZE_VECTORS,
     AVATAR_INITIALS_VECTORS,
 } from '@gjsify/adwaita-core/conformance';
 
@@ -124,6 +125,22 @@ export const AdwAvatarTest = async () => {
         });
     });
 
+    await describe('adw-avatar fallback glyph size (adw-avatar.c:756)', async () => {
+        for (const { size, iconSize } of AVATAR_ICON_SIZE_VECTORS) {
+            await it(`size ${size} draws the glyph at ${iconSize}`, () => {
+                // Through the ELEMENT, not the helper: the box was hand-typed here as
+                // `round(size * 0.55)` and drew ~10% larger than GTK at every size,
+                // with nothing in a position to say so.
+                const { avatar, host } = mountAvatar('Ada Lovelace', false);
+                avatar.setAttribute('size', String(size));
+                const icon = avatar.querySelector('.adw-avatar-icon') as HTMLElement;
+                expect(icon.hidden).toBe(false);
+                expect(icon.getAttribute('size')).toBe(String(iconSize));
+                host.remove();
+            });
+        }
+    });
+
     await describe('adw-avatar mode (Adw.Avatar update_visibility)', async () => {
         await it('keeps a whitespace-only name in initials mode with a blank label', () => {
             const { avatar, host } = mountAvatar('   ');

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

@@ -28,7 +28,7 @@ export const AdwTabViewTest = async () => {
         await it('builds one tab per page and shows the first page', async () => {
             const view = makeTabView();
             expect(view.querySelectorAll('.adw-tab').length).toBe(3);
-            expect(view.selected).toBe(0);
+            expect(view.selectedIndex).toBe(0);
             const pages = view.querySelectorAll('.adw-tab-page');
             expect((pages[0] as HTMLElement).hidden).toBe(false);
             expect((pages[1] as HTMLElement).hidden).toBe(true);
@@ -42,15 +42,18 @@ export const AdwTabViewTest = async () => {
                 notified = (event as CustomEvent).detail.selected;
             });
             (view.querySelectorAll('.adw-tab')[2] as HTMLButtonElement).click();
-            expect(view.selected).toBe(2);
+            expect(view.selectedIndex).toBe(2);
             expect(notified).toBe(2);
             expect((view.querySelectorAll('.adw-tab-page')[2] as HTMLElement).hidden).toBe(false);
             view.parentElement?.remove();
         });
 
-        await it('setting the selected attribute switches pages', async () => {
+        await it('setting the selected-page attribute switches pages', async () => {
             const view = makeTabView();
-            view.setAttribute('selected', '1');
+            // ADR 0048: the markup door names the PAGE. `makeTabView` declares no
+            // `page-id`, so the ids are the generated ones the element reflects back.
+            const second = view.pages[1]!.id;
+            view.setAttribute('selected-page', second);
             expect((view.querySelectorAll('.adw-tab-page')[1] as HTMLElement).hidden).toBe(false);
             expect((view.querySelectorAll('.adw-tab-page')[0] as HTMLElement).hidden).toBe(true);
             view.parentElement?.remove();
@@ -70,7 +73,7 @@ export const AdwTabViewTest = async () => {
             expect(view.querySelectorAll('.adw-tab').length).toBe(2);
             // Closing a page BEFORE the selection must not also select the tab,
             // and must leave the selected PAGE selected.
-            expect(view.selected).toBe(0);
+            expect(view.selectedIndex).toBe(0);
             view.parentElement?.remove();
         });
     });

package/src/elements/adw-avatar.ts

@@ -19,7 +19,14 @@
 // (adw-avatar.c:117-125) — the branch that wins over both others — could not be reached,
 // and the vector row covering it had nothing to drive.
 
-import { avatarColor, avatarFontSize, avatarInitials, avatarMaxFontSize, avatarMode } from '@gjsify/adwaita-core';
+import {
+    avatarColor,
+    avatarFontSize,
+    avatarIconSize,
+    avatarInitials,
+    avatarMaxFontSize,
+    avatarMode,
+} from '@gjsify/adwaita-core';
 
 import { type GtkImage, createGtkImage } from './gtk-image.js';
 
@@ -100,8 +107,9 @@ export class AdwAvatar extends HTMLElement {
             this._iconEl.iconName = this.getAttribute('icon') ?? 'avatar-default';
             // The glyph scales with the avatar: `size` sizes the BOX and the mask
             // together, which is what `.adw-avatar-icon`'s `mask-size: contain`
-            // was there to approximate.
-            this._iconEl.size = Math.round(size * 0.55);
+            // was there to approximate. The factor moved into the core when the
+            // NativeScript avatar grew the same fallback — one number, two renderers.
+            this._iconEl.size = avatarIconSize(size);
             this._iconEl.hidden = false;
         }
     }

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

@@ -106,11 +106,11 @@ export class AdwTabView extends HTMLElement {
     private readonly _hovered = new Set<string>();
     private _initialized = false;
     private _generatedIds = 0;
-    /** Guards the `selected` attribute reflection against re-entering the model. */
+    /** Guards the `selected-page` attribute reflection against re-entering the model. */
     private _reflecting = false;
 
     static get observedAttributes() {
-        return ['selected', 'autohide', 'expand-tabs', 'no-close'];
+        return ['selected-page', 'autohide', 'expand-tabs', 'no-close'];
     }
 
     constructor() {
@@ -131,13 +131,26 @@ export class AdwTabView extends HTMLElement {
         this._state.subscribe((change) => this._onSelectionChange(change));
     }
 
-    /** Zero-based index of the visible page, `-1` when the view is empty. */
-    get selected(): number {
-        return this._state.selectedIndex;
+    /**
+     * The selected page (`Adw.TabView:selected-page`), `null` when the view is empty.
+     *
+     * THE PAGE, NOT ITS POSITION (ADR 0048). Its position is {@link selectedIndex}, which
+     * stays a read-only report; `Adw.TabView` selects by object, and the model has held
+     * that object all along.
+     */
+    get selectedPage(): AdwTabViewPage | null {
+        return this._state.selectedPage;
     }
 
-    set selected(value: number) {
-        this._state.selectNthPage(value);
+    set selectedPage(page: AdwTabViewPage | null) {
+        // Straight to the core, which owns the page list and therefore owns
+        // `page_belongs_to_this_view` — the check an ID cannot answer: an id is unique
+        // WITHIN a view, never across two (a declared `page-id` is the author's to repeat
+        // and `_nextId` counts per element, so two views both hold a `tab-1`). Measured
+        // before the core took the page: `viewA.selectedPage = viewB.pages[2]` moved viewA
+        // to index 2 instead of refusing. The refusal carries C's own diagnostic now,
+        // where a renderer-side guard could only return in silence.
+        this._state.setSelectedPage(page);
     }
 
     /**
@@ -177,8 +190,8 @@ export class AdwTabView extends HTMLElement {
         this._initialized = true;
 
         // Read the declared selection BEFORE adopting anything: the auto-select
-        // of the first page reflects its own index into this very attribute.
-        const declaredSelection = this.getAttribute('selected');
+        // of the first page reflects its own id into this very attribute.
+        const declaredSelection = this.getAttribute('selected-page');
 
         // Snapshot the declared pages, then take over the subtree. The elements
         // themselves become the panels, so they must survive replaceChildren.
@@ -195,12 +208,12 @@ export class AdwTabView extends HTMLElement {
 
     attributeChangedCallback(name: string, _old: string | null, _value: string | null) {
         if (!this._initialized) return;
-        if (name === 'selected') {
+        if (name === 'selected-page') {
             // The LIVE attribute, not the value captured when the reaction was
             // queued: reflection writes this attribute, and a custom-element
             // reaction can run after a later write has already superseded it.
             if (this._reflecting) return;
-            const current = this.getAttribute('selected');
+            const current = this.getAttribute('selected-page');
             if (current !== null) this._applySelectedAttribute(current);
             return;
         }
@@ -272,8 +285,9 @@ export class AdwTabView extends HTMLElement {
         return this._state.isClosing(id);
     }
 
-    setSelectedPage(id: string | null): boolean {
-        return this._state.setSelectedPage(id);
+    /** `adw_tab_view_set_selected_page`, which takes the PAGE; an id is accepted too. */
+    setSelectedPage(page: AdwTabViewPage | string | null): boolean {
+        return this._state.setSelectedPage(page);
     }
 
     selectNthPage(n: number): boolean {
@@ -724,19 +738,25 @@ export class AdwTabView extends HTMLElement {
 
     private _reflectSelected(): void {
         this._reflecting = true;
-        const index = this._state.selectedIndex;
-        if (index < 0) this.removeAttribute('selected');
-        else if (this.getAttribute('selected') !== String(index)) this.setAttribute('selected', String(index));
+        const id = this._state.selectedId;
+        if (id === null) this.removeAttribute('selected-page');
+        else if (this.getAttribute('selected-page') !== id) this.setAttribute('selected-page', id);
         this._reflecting = false;
     }
 
+    /**
+     * `selected-page="<page id>"` — the markup half of {@link selectedPage} (ADR 0048).
+     *
+     * The id is the one `<adw-tab-page page-id>` declares; a page that declares none gets
+     * a generated one, which an author cannot predict and therefore cannot select by. That
+     * is the same bargain `<adw-view-stack visible-child-name>` already makes for a page
+     * with no name, and it is why `page-id` exists.
+     *
+     * An id no page holds is IGNORED rather than treated as the first page — libadwaita
+     * refuses a foreign `AdwTabPage` outright, and `setSelectedPage` is the refusal here.
+     */
     private _applySelectedAttribute(value: string): void {
-        const index = Number.parseInt(value, 10);
-        // An unparseable value is IGNORED rather than treated as 0, and an out-of-range
-        // one is refused rather than clamped: libadwaita refuses both, so
-        // `selected="oops"` must not select the first page nor `selected="99"` the last.
-        if (Number.isNaN(index)) return;
-        this._state.selectNthPage(index);
+        this._state.setSelectedPage(value);
     }
 
     /**

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

@@ -26,7 +26,8 @@
 // Properties (mirroring Adw.ViewStack):
 //   pages               — readonly page descriptors ({ name, title, icon, content, visible }).
 //   visibleChildName    — name of the visible page ('' when nothing is selected).
-//   visibleChildIndex   — zero-based index of the visible page, -1 for none (guarded).
+//   visibleChildIndex   — READ-ONLY report: position of the visible page, -1 for none.
+//                         Selecting is `visibleChildName` (ADR 0048).
 //   visibleChild        — the visible page's content element (or null).
 // Methods:
 //   add(content, name, title?, icon?) — append a page; returns its descriptor.
@@ -70,13 +71,28 @@ export class AdwViewStack extends HTMLElement {
         return this._state.pages;
     }
 
-    /** Zero-based index of the visible page, `-1` when nothing is selected. */
+    /**
+     * Zero-based position of the visible page, `-1` when nothing is selected.
+     *
+     * A REPORT, NOT A DOOR (ADR 0048). `Adw.ViewStack` selects by NAME, and an ordinal is
+     * derived — an insertion before the visible page increments it, a reorder rewrites it,
+     * a removal decrements it. Selecting is {@link visibleChildName}.
+     */
     get visibleChildIndex(): number {
         return this._state.visibleIndex;
     }
 
-    set visibleChildIndex(value: number) {
-        this._state.setVisibleIndex(value);
+    /**
+     * Show the page at position `n`. Returns whether the selection moved.
+     *
+     * THE ORDINAL IS A CALL, NOT A PROPERTY (ADR 0048): it resolves against the page list
+     * as it is now and keeps nothing, where a held index comes to mean another page after
+     * an insert, a reorder or a removal. Port-owned — `refs/libadwaita` gives
+     * `AdwViewStack` no ordinal API — and named for the tab view's existing
+     * `selectNthPage`. The guard on `n` is the core's and is pinned by the shared vectors.
+     */
+    selectNthPage(n: number): boolean {
+        return this._state.setVisibleIndex(n);
     }
 
     get visibleChildName(): string {

package/src/elements/adw-view-switcher-bar.ts

@@ -99,8 +99,10 @@ export class AdwViewSwitcherBar extends HTMLElement {
                     const stack = this._stack;
                     if (!stack) return;
                     const index = Number(item.dataset.pageIndex);
-                    // Re-assigning the current index would re-run the stack's transition.
-                    if (stack.visibleChildIndex !== index) stack.visibleChildIndex = index;
+                    // The roving-focus list is ordinal and the stack resolves it (ADR 0048).
+                    // Re-selecting the current page would re-run the stack's transition, which
+                    // is why the position is compared before the call.
+                    if (stack.visibleChildIndex !== index) stack.selectNthPage(index);
                 },
             });
         }
@@ -238,7 +240,8 @@ export class AdwViewSwitcherBar extends HTMLElement {
 
         button.append(icon, label, indicator);
         button.addEventListener('click', () => {
-            if (this._stack) this._stack.visibleChildIndex = pageIndex;
+            // Ordinal here, resolved by the stack (ADR 0048) — as in `select` above.
+            this._stack?.selectNthPage(pageIndex);
         });
 
         return { button, icon, label, indicator };

package/src/shared-trees.spec.ts

@@ -0,0 +1,151 @@
+// ONE AUTHORED TREE, BUILT BY THIS RENDERER — ADR 0051, and the renderer ADR 0027 § 9
+// names by name: "the same authored tree, rendered through this host and through
+// `adwaita-web`, satisfies the same `@gjsify/adwaita-core/conformance` vectors with no
+// per-surface markup branch".
+//
+// The sibling driver is `packages/framework/gtk-host/src/shared-trees.spec.ts`. One corpus
+// — `scripts/adwaita-gallery-shared-trees.mjs`, read here and not transcribed — one set of
+// expectations, a driver per renderer: ADR 0030's shape one level up, so a green-here /
+// red-there diff is attributable to the RENDERER and not to two suites disagreeing about
+// what they test.
+//
+// TWO DECLARED TRANSFORMS ON THE WAY IN, and no third. `hostTagOf` turns the authored GIR
+// class name into the element name, which is the same case rule `gtk-host` stamps its tags
+// with; and an authored property name becomes its kebab-case ATTRIBUTE, because this
+// renderer's door is markup. Both are total functions over the corpus with no tag list and
+// no per-block case — a `switch` on a widget name here would be the per-surface branch
+// § 9 forbids, and the reason the corpus admits a block only when it needs no alias.
+//
+// The readers below go through the REAL DOM the element rendered, never a state object of
+// its own: an element asserting against its own bookkeeping agrees with itself while the
+// page is wrong.
+//
+// What is NOT here is everything that is not about this renderer — which tables the corpus
+// reaches, which block is declared to reach none, whether an expectation's address exists.
+// Those are facts about the CORPUS and are asserted once, in `adwaita-core`'s own suite,
+// which runs on Node as well as in a browser.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import {
+    authoredTags,
+    sharedTreeExpectations,
+    subjectIndexOf,
+    type SharedTreeExpectation,
+    type SharedTreeNode,
+} from '@gjsify/adwaita-core/conformance';
+
+// `attributeOf` — `buttonLabel` -> `button-label` — comes from the corpus rather than
+// being spelled again here, because arm 13 of `check-generated-website-data.mjs` reads
+// gallery fences back through the SAME rule: two copies would let this driver and that
+// check agree with each other while the fence a reader copies means something else.
+import {
+    ADWAITA_GALLERY_SHARED_TREES,
+    attributeOf,
+    hostTagOf,
+} from '../../../../scripts/adwaita-gallery-shared-trees.mjs';
+
+import '@gjsify/adwaita-web';
+
+/**
+ * The whole renderer-specific half of this driver: an element, its authored properties as
+ * attributes, its children, in that order.
+ *
+ * A boolean is the ATTRIBUTE'S PRESENCE, which is what every element here reads
+ * (`hasAttribute('revealed')`, `hasAttribute('expanded')`) — spelling `"true"` would set a
+ * present attribute for `false` as well.
+ */
+function build(node: SharedTreeNode): HTMLElement {
+    const el = document.createElement(hostTagOf(node.tag));
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+        if (typeof value === 'boolean') el.toggleAttribute(attributeOf(prop), value);
+        else el.setAttribute(attributeOf(prop), String(value));
+    }
+    for (const child of node.children ?? []) el.append(build(child));
+    return el;
+}
+
+/**
+ * Connect the authored root — these elements build on connect — run, and take it down again.
+ *
+ * The teardown is in a `finally` because a RED test must not leave a mounted tree behind:
+ * the next test would then be reading a document two blocks deep, and the failure it
+ * reported would name the wrong renderer.
+ */
+function mounted<T>(node: SharedTreeNode, use: (root: Element) => T): T {
+    const host = document.createElement('div');
+    host.append(build(node));
+    document.body.append(host);
+    try {
+        return use(host.firstElementChild!);
+    } finally {
+        host.remove();
+    }
+}
+
+const bannerButton = (banner: Element) => banner.querySelector<HTMLButtonElement>('.adw-banner-button');
+
+/**
+ * Read one observable off the element this renderer built.
+ *
+ * The ONE seam between the shared expectations and this renderer, and the mirror of
+ * `read()` in the gtk-host driver. Everything above it is renderer-free.
+ */
+function read(expectation: SharedTreeExpectation, el: Element): string | number | boolean {
+    switch (expectation.observable) {
+        case 'entry-text-length':
+            return (el as unknown as { textLength: number }).textLength;
+        case 'switch-row-active':
+            return (el as unknown as { active: boolean }).active;
+        case 'banner-button-visible': {
+            const button = bannerButton(el);
+            return button ? !button.hidden : false;
+        }
+        case 'banner-button-text':
+            return bannerButton(el)?.textContent ?? '';
+    }
+}
+
+/**
+ * The realised tree, depth-first in document order and filtered to the authored element
+ * names: the parts an element renders for itself (a listbox, a revealer, a title span) are
+ * not the renderer's promise; the ORDER and the NESTING of what was authored is.
+ */
+function realised(root: Element, wanted: readonly string[]): Element[] {
+    const set = new Set(wanted);
+    return [root, ...root.querySelectorAll('*')].filter((el) => set.has(el.tagName.toLowerCase()));
+}
+
+export const AdwSharedTreesTest = async () => {
+    await describe('the shared corpus builds through adwaita-web', async () => {
+        for (const block of ADWAITA_GALLERY_SHARED_TREES) {
+            await it(`${block.widget} builds, and the REAL DOM carries the authored nodes in order`, () => {
+                const wanted = authoredTags(block.root, hostTagOf);
+
+                mounted(block.root, (root) => {
+                    const built = realised(root, wanted).map((el) => el.tagName.toLowerCase());
+                    expect(built).toStrictEqual(wanted);
+                });
+            });
+        }
+    });
+
+    await describe('the shared corpus against the adwaita-core vectors it reaches', async () => {
+        for (const block of ADWAITA_GALLERY_SHARED_TREES) {
+            for (const expectation of sharedTreeExpectations(block.root)) {
+                await it(`${block.widget} — ${expectation.path}: ${expectation.table} — ${expectation.rule}`, () => {
+                    mounted(block.root, (root) => {
+                        // The SAME filtered walk the shape test asserts, so the element an
+                        // expectation is read off is the one at the authored ADDRESS rather
+                        // than the first of its name the DOM happens to contain.
+                        const built = realised(root, authoredTags(block.root, hostTagOf));
+                        const subject = built[subjectIndexOf(block.root, expectation.path)]!;
+                        expect(subject.tagName.toLowerCase()).toBe(hostTagOf(expectation.gtype));
+
+                        expect(read(expectation, subject)).toBe(expectation.expected);
+                    });
+                });
+            }
+        }
+    });
+};

package/src/tab-view.spec.ts

@@ -207,7 +207,7 @@ export const AdwTabViewConformanceTest = async () => {
         });
     });
 
-    await describe('adw-tab-view selected attribute', async () => {
+    await describe('adw-tab-view selected-page attribute', async () => {
         function mountThree(attrs = ''): { view: AdwTabView; host: HTMLElement } {
             const host = document.createElement('div');
             host.innerHTML = `<adw-tab-view ${attrs}>
@@ -219,38 +219,92 @@ export const AdwTabViewConformanceTest = async () => {
             return { view: host.querySelector('adw-tab-view') as AdwTabView, host };
         }
 
-        await it('selects the declared index instead of the auto-pick', () => {
-            const { view, host } = mountThree('selected="2"');
+        await it('selects the declared PAGE instead of the auto-pick', () => {
+            const { view, host } = mountThree('selected-page="c"');
             expect(view.selectedIndex).toBe(2);
+            expect(view.selectedId).toBe('c');
             expect(shownPanels(view)).toStrictEqual([false, false, true]);
             host.remove();
         });
 
-        await it('IGNORES an out-of-range or unparseable index instead of clamping it', () => {
-            // A clamping `Number.isNaN(raw) ? 0 : Math.min(Math.max(raw, 0), max)` selects
-            // the last page for `99` and the first for `-1`/`oops`; libadwaita refuses all
-            // three.
+        await it('IGNORES an id no page holds instead of falling back to the first', () => {
+            // The ordinal spellings are just unknown ids now (ADR 0048), and a fallback to
+            // page 0 would be the same wrong answer clamping used to give: libadwaita
+            // refuses a foreign `AdwTabPage` outright.
             const { view, host } = mountThree();
             for (const value of ['99', '-1', 'oops']) {
-                view.setAttribute('selected', value);
+                view.setAttribute('selected-page', value);
                 expect(view.selectedIndex).toBe(0);
             }
             //...and the attribute is put back in sync rather than left lying.
-            view.setAttribute('selected', '1');
+            view.setAttribute('selected-page', 'b');
             expect(view.selectedIndex).toBe(1);
-            expect(view.getAttribute('selected')).toBe('1');
+            expect(view.getAttribute('selected-page')).toBe(view.pages[1]!.id);
+            host.remove();
+        });
+
+        await it('REFUSES a page belonging to ANOTHER view, and RECORDS it', () => {
+            // `page_belongs_to_this_view`. An id is only unique WITHIN a view — declared ones
+            // are the author's to repeat and `_nextId` counts per element, so two views both
+            // hold a `tab-1`. Both views here hold 'a'/'b'/'c', which is the collision.
+            const first = mountThree();
+            const second = mountThree();
+            second.view.selectedPage = second.view.pages[2]!;
+            expect(second.view.selectedIndex).toBe(2);
+
+            first.view.selectedPage = second.view.pages[2]!;
+            expect(first.view.selectedIndex).toBe(0);
+            expect(second.view.selectedIndex).toBe(2);
+            // The refusal carries C's own assertion. It did NOT while the check was a
+            // renderer-side guard returning in silence, which is why the check moved into
+            // `TabViewState` — the one place that owns the page list.
+            expect(first.view.diagnostics).toStrictEqual([
+                "adw_tab_view_set_selected_page: assertion 'page_belongs_to_this_view (self, selected_page)' failed",
+            ]);
+            expect(second.view.diagnostics).toStrictEqual([]);
+
+            // ...and this view's OWN page of that same id is accepted, so what was refused
+            // is the IDENTITY and not the id.
+            first.view.selectedPage = first.view.pages[2]!;
+            expect(first.view.selectedIndex).toBe(2);
+            first.host.remove();
+            second.host.remove();
+        });
+
+        await it('RECORDS the refusal, where the ordinal door recorded nothing', () => {
+            // The behaviour change ADR 0048 does not name: `selected="99"` went through
+            // `selectNthPage`, which refuses an out-of-range index SILENTLY, while an
+            // unknown id goes through `setSelectedPage`, which is where C's
+            // `page_belongs_to_this_view` assertion lives. Three refusals, three records —
+            // if this list stays empty the element is swallowing the typo the reader made.
+            const { view, host } = mountThree();
+            expect(view.diagnostics).toStrictEqual([]);
+            for (const value of ['99', 'oops']) view.setAttribute('selected-page', value);
+            expect(view.diagnostics).toStrictEqual([
+                "adw_tab_view_set_selected_page: assertion 'page_belongs_to_this_view (self, selected_page)' failed",
+                "adw_tab_view_set_selected_page: assertion 'page_belongs_to_this_view (self, selected_page)' failed",
+            ]);
+
+            // ...and `null` while pages exist is the OTHER half of the same C assertion,
+            // which `view.selected = -1` also used to reach in silence.
+            view.selectedPage = null;
+            expect(view.selectedIndex).toBe(0);
+            expect(view.diagnostics).toHaveLength(3);
+            expect(view.diagnostics[2]).toBe(
+                "adw_tab_view_set_selected_page: assertion 'ADW_IS_TAB_PAGE (selected_page)' failed",
+            );
             host.remove();
         });
 
         await it('notifies on a PROGRAMMATIC selection, not only on a click', () => {
-            // C notifies on EVERY path: a programmatic `view.selected = 2` must notify as
-            // a tab click does.
+            // C notifies on EVERY path: a programmatic `view.selectedPage = …` must notify
+            // as a tab click does.
             const { view, host } = mountThree();
             const seen: number[] = [];
             view.addEventListener('notify::selected-page', (event) =>
                 seen.push((event as CustomEvent).detail.selected),
             );
-            view.selected = 2;
+            view.selectedPage = view.pages[2]!;
             expect(seen).toStrictEqual([2]);
             host.remove();
         });
@@ -259,11 +313,11 @@ export const AdwTabViewConformanceTest = async () => {
             const { view, host } = mountThree();
             const chips = tabChips(view);
             chips[1]!.click();
-            expect(view.getAttribute('selected')).toBe('1');
+            expect(view.getAttribute('selected-page')).toBe(view.pages[1]!.id);
 
             for (const id of ['a', 'b', 'c']) view.closePage(id);
             expect(view.nPages).toBe(0);
-            expect(view.hasAttribute('selected')).toBe(false);
+            expect(view.hasAttribute('selected-page')).toBe(false);
             expect(view.selectedIndex).toBe(-1);
             host.remove();
         });

package/src/test.browser.mts

@@ -53,8 +53,10 @@ import { AdwEmptySectionsTest } from './empty-sections.spec.js';
 import { AdwSlottedChildrenTest } from './slotted-children.spec.js';
 import { AdwKeyboardOperableTest } from './keyboard-operable.spec.js';
 import { AdwFontsTest } from './adw-fonts.spec.js';
+import { AdwSharedTreesTest } from './shared-trees.spec.js';
 
 run({
+    AdwSharedTreesTest,
     AdwKeyboardOperableTest,
     AdwConnectLifecycleTest,
     AdwEmptySectionsTest,

package/src/view-stack.spec.ts

@@ -66,7 +66,9 @@ function mountStack(pages: readonly ViewStackVectorPage[], visibleChildName?: st
 function applyOp(stack: AdwViewStack, op: ViewStackVectorOp): void {
     switch (op.kind) {
         case 'selectIndex':
-            stack.visibleChildIndex = op.index;
+            // ADR 0048: the element has no ordinal SETTER any more; the ordinal is this
+            // call, and it forwards to the same core guard the vector pins.
+            stack.selectNthPage(op.index);
             break;
         case 'selectName':
             stack.visibleChildName = op.name;
@@ -224,7 +226,7 @@ export const AdwViewStackTest = async () => {
         await it('reflects the selection back, including an empty name', () => {
             const { stack, host } = mountStack([{ name: 'a' }, { name: '' }]);
             expect(stack.getAttribute('visible-child-name')).toBe('a');
-            stack.visibleChildIndex = 1;
+            stack.selectNthPage(1);
             // Reflection guarded by `if (current && …)` never fires for nameless pages.
             expect(stack.getAttribute('visible-child-name')).toBe('');
             host.remove();
@@ -252,7 +254,7 @@ export const AdwViewStackTest = async () => {
             // with duplicate names a naive re-lookup resolves to the FIRST match and
             // undoes the selection.
             const { stack, host } = mountStack([{ name: 'dup' }, { name: 'dup' }]);
-            stack.visibleChildIndex = 1;
+            stack.selectNthPage(1);
             expect(stack.visibleChildIndex).toBe(1);
             expect(stack.getAttribute('visible-child-name')).toBe('dup');
             host.remove();