@gjsify/adwaita-web 0.51.1 → 0.53.0

package/src/appearance.ts

@@ -0,0 +1,207 @@
+// Following the desktop's appearance in a plain web page (ADR 0078, #1821).
+//
+// A page learns the desktop's accent from, in order of precedence:
+//
+//   1. the APP's own choice   `applyAdwaitaAccent(name)` — never overwritten here
+//   2. a server HANDOFF       `<meta name="adw-accent" content="purple">`, or
+//                             `applyDesktopAppearance(json)` for live updates
+//   3. the CSS SYSTEM COLOUR  `AccentColor`, once asked for (`applySystemAccent()`
+//                             or `<meta name="adw-accent" content="system">`)
+//   4. Adwaita blue           the stylesheet's own value
+//
+// The handoff outranks `AccentColor` because it is the better-informed source:
+// a gjsify server reads the desktop itself (`@gjsify/adwaita-app/appearance`),
+// while `AccentColor` is supported unevenly across engines and a page cannot
+// tell a real system accent from an engine's fixed default.
+//
+// EVERY SOURCE IS SNAPPED TO ONE OF THE NINE with `nearestAccent`, as libadwaita
+// does with the system colour it reads, so a web page and a native Adwaita
+// window on the same desktop show the same accent. Consequently the standalone
+// `--accent-color` is libadwaita's derivation of a palette colour, never of the
+// raw system colour.
+//
+// Only `document.documentElement` follows; an accent set on any other element
+// is the app's business.
+
+import {
+    ADW_ACCENT_META_SYSTEM,
+    type AdwAccentColorName,
+    type AppearanceMeta,
+    appearanceFromMeta,
+    type DesktopAppearance,
+    formatAdwRgb,
+    nearestAccent,
+    parseAdwRgb,
+    parseDesktopAppearance,
+} from '@gjsify/adwaita-core';
+
+import { clearAdwaitaAccent, hasAppChosenAccent, isAdwaitaDark, writeAdwaitaAccent } from './accent.js';
+
+/** Which source the root's accent currently comes from. */
+export type AdwAccentSource = 'app' | 'handoff' | 'system' | 'default';
+
+/** What the handoff said last: from the `<meta>` tags, or from `applyDesktopAppearance`. */
+let handoff: AppearanceMeta & { accentRgb?: string } = {};
+/** Whether the page asked to follow CSS `AccentColor`. */
+let systemRequested = false;
+/** Whether the follower has written the root's accent, so it knows what it may remove. */
+let wroteAccent = false;
+/** The theme class the follower added for a handed-off colour scheme, if any. */
+let addedSchemeClass: 'theme-dark' | 'theme-light' | null = null;
+let installed = false;
+
+/**
+ * The browser's CSS system colour `AccentColor`, snapped to the nearest of the
+ * nine — or `null` where the engine does not support the keyword or the
+ * resolved colour cannot be read.
+ *
+ * SUPPORT IS UNEVEN AND NOT ASSUMED: Chrome announced shipping `AccentColor`
+ * only in 2026, and what Firefox resolves it to on Linux is not established;
+ * Firefox 156 on macOS resolves it to `rgb(0, 122, 255)`. An engine may also
+ * report a fixed default instead of the real accent (fingerprinting
+ * protection), which a page cannot detect.
+ */
+export function readSystemAccent(): { accent: AdwAccentColorName; accentRgb: string } | null {
+    if (typeof CSS === 'undefined' || !CSS.supports('color', 'AccentColor')) return null;
+    const probe = document.createElement('span');
+    probe.style.color = 'AccentColor';
+    probe.style.display = 'none';
+    document.documentElement.append(probe);
+    const resolved = getComputedStyle(probe).color;
+    probe.remove();
+    const rgb = parseAdwRgb(resolved);
+    if (!rgb) return null;
+    return { accent: nearestAccent(rgb), accentRgb: formatAdwRgb(rgb) };
+}
+
+function resolve(): { accent: AdwAccentColorName; source: AdwAccentSource } | null {
+    if (handoff.accent && handoff.accent !== ADW_ACCENT_META_SYSTEM)
+        return { accent: handoff.accent, source: 'handoff' };
+    // A handoff that carries only a colour (a server that did not snap it) is snapped here.
+    const handedRgb = handoff.accentRgb ? parseAdwRgb(handoff.accentRgb) : null;
+    if (handedRgb) return { accent: nearestAccent(handedRgb), source: 'handoff' };
+    if (systemRequested || handoff.accent === ADW_ACCENT_META_SYSTEM) {
+        const system = readSystemAccent();
+        if (system) return { accent: system.accent, source: 'system' };
+    }
+    return null;
+}
+
+/** The source the root's accent comes from right now. */
+export function adwaitaAccentSource(): AdwAccentSource {
+    if (typeof document === 'undefined') return 'default';
+    if (hasAppChosenAccent(document.documentElement)) return 'app';
+    return resolve()?.source ?? 'default';
+}
+
+function syncScheme(root: HTMLElement): void {
+    const scheme = handoff.colorScheme;
+    const wanted = scheme === 'dark' ? 'theme-dark' : scheme === 'light' ? 'theme-light' : null;
+    if (wanted === addedSchemeClass) return;
+    if (addedSchemeClass) root.classList.remove(addedSchemeClass);
+    addedSchemeClass = null;
+    // A theme class the APP put on the root is its choice; the handoff does not fight it.
+    if (wanted && !root.classList.contains('theme-dark') && !root.classList.contains('theme-light')) {
+        root.classList.add(wanted);
+        addedSchemeClass = wanted;
+    }
+}
+
+/** Re-apply every automatic source to the root, in precedence order. */
+function sync(): void {
+    const root = document.documentElement;
+    syncScheme(root);
+    if (hasAppChosenAccent(root)) return;
+    const resolved = resolve();
+    if (resolved) {
+        writeAdwaitaAccent(resolved.accent, root, isAdwaitaDark(root));
+        wroteAccent = true;
+    } else if (wroteAccent) {
+        clearAdwaitaAccent(root);
+        wroteAccent = false;
+    }
+}
+
+const isHandoffMeta = (node: Node): boolean =>
+    node.nodeName === 'META' && (node as Element).getAttribute('name')?.startsWith('adw-') === true;
+
+/**
+ * Only a change to one of OUR tags re-reads them. Frameworks and this package
+ * itself insert <style> and <script> into <head> all the time, and re-reading on
+ * those would reset a live handoff from `applyDesktopAppearance` to the tags.
+ */
+function touchesHandoffMeta(record: MutationRecord): boolean {
+    // A renamed tag counts by its old name too, so dropping `name="adw-accent"` is seen.
+    if (record.type === 'attributes')
+        return (
+            isHandoffMeta(record.target) ||
+            (record.attributeName === 'name' && record.oldValue?.startsWith('adw-') === true)
+        );
+    return [...record.addedNodes, ...record.removedNodes].some(isHandoffMeta);
+}
+
+function readMetaHandoff(): void {
+    handoff = appearanceFromMeta(
+        (name) => document.head.querySelector(`meta[name="${name}"]`)?.getAttribute('content') ?? null,
+    );
+}
+
+/**
+ * Start following: read the handoff tags, and re-apply when they change, when
+ * the colour scheme flips (the standalone accent differs between light and
+ * dark) and when the page regains focus (`AccentColor` changes with no event).
+ * Idempotent; `@gjsify/adwaita-web` calls it on import in a browser.
+ */
+export function followDesktopAppearance(): void {
+    if (installed || typeof document === 'undefined') return;
+    installed = true;
+    readMetaHandoff();
+    sync();
+    new MutationObserver((records) => {
+        if (records.some(touchesHandoffMeta)) {
+            readMetaHandoff();
+            sync();
+        }
+    }).observe(document.head, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['content', 'name'],
+        attributeOldValue: true,
+    });
+    globalThis.matchMedia?.('(prefers-color-scheme: dark)').addEventListener('change', sync);
+    globalThis.addEventListener('focus', () => {
+        if (systemRequested || handoff.accent === ADW_ACCENT_META_SYSTEM) sync();
+    });
+}
+
+/**
+ * Follow the CSS system colour `AccentColor` (#1821); `false` stops following
+ * it. A server handoff and the app's own choice still win; where the engine
+ * cannot resolve `AccentColor` the page keeps Adwaita blue. Returns the accent
+ * the system colour snapped to, or `null` (always when disabling).
+ */
+export function applySystemAccent(enabled = true): AdwAccentColorName | null {
+    followDesktopAppearance();
+    systemRequested = enabled;
+    sync();
+    return enabled ? (readSystemAccent()?.accent ?? null) : null;
+}
+
+/**
+ * Apply a desktop appearance handed over at runtime — the JSON a gjsify server
+ * sends when the desktop changes (over SSE, a WebSocket, a message port). The
+ * value is validated, so an untrusted payload is safe to pass straight in; it
+ * REPLACES the previous handoff, including one from the `<meta>` tags.
+ */
+export function applyDesktopAppearance(appearance: unknown): void {
+    // Install first: installing reads the <meta> tags, which must not overwrite this newer value.
+    followDesktopAppearance();
+    const { accent, accentRgb, colorScheme }: DesktopAppearance = parseDesktopAppearance(appearance);
+    handoff = {
+        ...(accent ? { accent } : {}),
+        ...(accentRgb ? { accentRgb } : {}),
+        ...(colorScheme ? { colorScheme } : {}),
+    };
+    sync();
+}

package/src/blueprint-layout.spec.ts

@@ -0,0 +1,223 @@
+// A REAL `.blp` OF GtkWidget LAYOUT PROPERTIES, MOUNTED AND MEASURED.
+//
+// `bottom-sheet-layout.blp` (`@gjsify/adwaita-core/src/conformance/blueprints/`) is the shape
+// the gallery's `Adw.BottomSheet` block writes: a button placed with `halign`/`valign`, a box
+// inset by four `margin-*` lines, a title at the start edge, and one expanding child. The
+// NativeScript port builds the same file (`adwaita-nativescript`'s `blueprint-trees.spec.ts`).
+//
+// Before `_widget.scss` and the builder's margin table, this renderer wrote every one of these
+// as an attribute nothing read — no refusal, since the web builder refuses nothing it writes as
+// an attribute, and no effect: the centred button stretched across the sheet's content. So the
+// assertions here are about GEOMETRY, read off the laid-out page, never about the attribute
+// being present.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import { mountSharedTree } from './shared-tree-builder.js';
+
+import sheetTree from '../../adwaita-core/src/conformance/blueprints/bottom-sheet-layout.blp?shared-tree';
+import carouselTree from '../../adwaita-core/src/conformance/blueprints/carousel-indicators.blp?shared-tree';
+
+import { GALLERY_BLUEPRINTS } from './blueprint-markup.spec.js';
+
+/** Mount the fixture at a size a layout can be measured in; the caller unmounts. */
+function mountSheet() {
+    const mounted = mountSharedTree(sheetTree);
+    mounted.root.style.width = '400px';
+    mounted.root.style.height = '340px';
+    const byId = (id: string): HTMLElement => {
+        const el = mounted.root.querySelector<HTMLElement>(`#${id}`);
+        if (el === null) throw new Error(`the mounted tree has no element with the id '${id}'`);
+        return el;
+    };
+    return { ...mounted, byId };
+}
+
+export const AdwBlueprintLayoutTest = async () => {
+    await describe('adwaita-web: bottom-sheet-layout.blp, laid out', async () => {
+        await it('halign/valign center place the button in the middle of the content at its own size', async () => {
+            const { root, unmount, byId } = mountSheet();
+            try {
+                const content = root.querySelector('.adw-bottom-sheet-content') as HTMLElement;
+                const area = content.getBoundingClientRect();
+                const button = byId('toggle').getBoundingClientRect();
+
+                expect(button.width < area.width).toBe(true);
+                expect(button.height < area.height).toBe(true);
+                expect(Math.abs(button.left - area.left - (area.right - button.right)) <= 1).toBe(true);
+                expect(Math.abs(button.top - area.top - (area.bottom - button.bottom)) <= 1).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('the four margins inset the box, start and end on the logical edges', async () => {
+            const { unmount, byId } = mountSheet();
+            try {
+                const style = getComputedStyle(byId('box'));
+
+                expect(style.marginLeft).toBe('18px');
+                expect(style.marginRight).toBe('12px');
+                expect(style.marginTop).toBe('18px');
+                expect(style.marginBottom).toBe('24px');
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('halign start keeps the title at the start edge of the box at its own width', async () => {
+            const { unmount, byId } = mountSheet();
+            try {
+                const box = byId('box').getBoundingClientRect();
+                const title = byId('title').getBoundingClientRect();
+
+                expect(Math.abs(title.left - box.left) <= 1).toBe(true);
+                expect(title.width < box.width).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('expand grows along the box axis only', async () => {
+            const { unmount, byId } = mountSheet();
+            try {
+                // The box is vertical: `vexpand` is its own axis and takes the spare height,
+                // `hexpand` is the cross axis, which `align-items: stretch` already fills.
+                expect(getComputedStyle(byId('body')).flexGrow).toBe('1');
+                expect(getComputedStyle(byId('caption')).flexGrow).toBe('0');
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('the open modal sheet shows its dimming, and the non-modal one would not', async () => {
+            const { root, unmount } = mountSheet();
+            try {
+                const sheet = root as HTMLElement & { modal: boolean };
+                const dimming = root.querySelector('.adw-bottom-sheet-dimming') as HTMLElement;
+
+                expect(dimming.classList.contains('visible')).toBe(true);
+                sheet.modal = false;
+                expect(dimming.classList.contains('visible')).toBe(false);
+            } finally {
+                unmount();
+            }
+        });
+    });
+
+    // `carousel: carousel` projects as the attribute `carousel="carousel"`: GTK's property
+    // name, which the indicators now read beside the `for` they had first.
+    await describe('adwaita-web: carousel-indicators.blp, mounted', async () => {
+        await it('both indicators bind to the carousel by id and mark its first page', async () => {
+            const { root, unmount } = mountSharedTree(carouselTree);
+            try {
+                const dots = [...root.querySelectorAll('#dots .adw-carousel-dot')];
+                const lines = [...root.querySelectorAll('#lines .adw-carousel-line')];
+
+                expect(dots.length).toBe(3);
+                expect(lines.length).toBe(3);
+                expect(dots.map((dot) => dot.classList.contains('active'))).toStrictEqual([true, false, false]);
+                expect(lines[0]?.classList.contains('active')).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+    });
+
+    // The gallery's third batch of `.blp` files, mounted at the size of the gallery's stage
+    // and held to a GTK render of the same file (GJS, `Gtk.Builder`, an `Adw.ApplicationWindow`
+    // of that size, libadwaita 1.9). The GTK numbers are written beside each assertion; the
+    // tolerance is the 1-2px a header bar and text metrics differ by.
+    await describe('adwaita-web: the gallery Blueprints, laid out beside GTK', async () => {
+        /** The tree mounted in a grid of `width` x `height`, as the gallery stage holds it. */
+        const mountAt = (file: string, width: number, height: number) => {
+            const tree = GALLERY_BLUEPRINTS[file];
+            if (tree === undefined) throw new Error(`no gallery Blueprint ${file}`);
+            const mounted = mountSharedTree(tree);
+            const host = mounted.root.parentElement as HTMLElement;
+            host.style.cssText = `display: grid; width: ${width}px; height: ${height}px;`;
+            const box = (el: Element) => {
+                const r = el.getBoundingClientRect();
+                const h = host.getBoundingClientRect();
+                return { x: r.left - h.left, y: r.top - h.top, width: r.width, height: r.height };
+            };
+            const byId = (id: string): HTMLElement => {
+                const el = host.querySelector<HTMLElement>(`#${id}`);
+                if (el === null) throw new Error(`${file} mounted no element with the id '${id}'`);
+                return el;
+            };
+            return { ...mounted, host, box, byId };
+        };
+        const near = (actual: number, gtk: number, tolerance = 2) => Math.abs(actual - gtk) <= tolerance;
+
+        await it('a split view page fills its pane, and its header bar shows the page title', async () => {
+            const { unmount, box, byId, host } = mountAt('adwaita/navigation-split-view.blp', 652, 340);
+            try {
+                // GTK: sidebar 0,46 180x294 — the list fills the pane under the header bar.
+                expect(near(box(byId('sidebar')).height, 294)).toBe(true);
+                const titles = [...host.querySelectorAll('adw-header-bar')].map(
+                    (bar) => bar.querySelector('adw-window-title')?.getAttribute('title') ?? null,
+                );
+                expect(titles).toStrictEqual(['Mailboxes', 'All Mail']);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('an overlay split view sidebar fills its pane', async () => {
+            const { unmount, box, byId } = mountAt('adwaita/overlay-split-view.blp', 652, 340);
+            try {
+                // GTK: sidebar 0,46 180x294.
+                expect(near(box(byId('sidebar')).height, 294)).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('a centred toolbar-view content widget keeps its own height', async () => {
+            const { unmount, box, byId } = mountAt('adwaita/navigation-view.blp', 652, 340);
+            try {
+                // GTK: open_button 245,171 161x44.
+                const button = box(byId('open_button'));
+                expect(near(button.height, 44)).toBe(true);
+                expect(near(button.y, 171)).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it("a status page has upstream's metrics: a 128px icon, the child where GTK puts it", async () => {
+            const { unmount, box, byId, host } = mountAt('adwaita/status-page.blp', 652, 400);
+            try {
+                const icon = host.querySelector('.adw-status-page-icon') as HTMLElement;
+                expect(box(icon).width).toBe(128);
+                expect(box(icon).height).toBe(128);
+                // GTK: new_button 239,311 174x44.
+                expect(near(box(byId('new_button')).y, 311, 3)).toBe(true);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('a carousel does not widen the box it fills to the sum of its pages', async () => {
+            const { unmount, box, root } = mountAt('adwaita/carousel.blp', 652, 260);
+            try {
+                // GTK: the box is 652 wide, the window's width.
+                expect(box(root).width).toBe(652);
+            } finally {
+                unmount();
+            }
+        });
+
+        await it('tooltip-text becomes the icon button tooltip and accessible name', async () => {
+            const { unmount, byId } = mountAt('adwaita/toolbar-view.blp', 652, 300);
+            try {
+                const inner = byId('add_button').querySelector('button') as HTMLButtonElement;
+                expect(inner.title).toBe('Add');
+                expect(inner.getAttribute('aria-label')).toBe('Add');
+            } finally {
+                unmount();
+            }
+        });
+    });
+};

package/src/blueprint-markup.spec.ts

@@ -0,0 +1,155 @@
+// The custom-element markup of the `index.html` file the gallery's Web Components tab shows for
+// a one-Blueprint block, PARSED back by the browser and held to the tree `buildSharedTree`
+// makes from the same `.blp`.
+//
+// The website renders that markup with `@gjsify/adwaita-core/markup` from the block's
+// `?shared-tree` projection, on every build. Markup a reader copies has to build the same
+// widget: an attribute spelled against `attributeOf`, a boolean written as `"true"` where the
+// element reads presence, or a slot dropped would each parse fine and mount something else. So every `.blp` under
+// `website/src/blueprints/` is imported below — `scripts/check-website-blueprint-markup.mjs`
+// fails on one that is not.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import { sharedTreeHtml } from '@gjsify/adwaita-core/markup';
+import { hostTagOf } from '@gjsify/adwaita-core/tags';
+
+import adwaitaActionRowTree from '../../../../website/src/blueprints/adwaita/action-row.blp?shared-tree';
+import adwaitaAvatarTree from '../../../../website/src/blueprints/adwaita/avatar.blp?shared-tree';
+import adwaitaBannerTree from '../../../../website/src/blueprints/adwaita/banner.blp?shared-tree';
+import adwaitaBottomSheetTree from '../../../../website/src/blueprints/adwaita/bottom-sheet.blp?shared-tree';
+import adwaitaButtonContentTree from '../../../../website/src/blueprints/adwaita/button-content.blp?shared-tree';
+import adwaitaButtonRowTree from '../../../../website/src/blueprints/adwaita/button-row.blp?shared-tree';
+import adwaitaCarouselTree from '../../../../website/src/blueprints/adwaita/carousel.blp?shared-tree';
+import clampTree from '../../../../website/src/blueprints/adwaita/clamp.blp?shared-tree';
+import adwaitaComboRowTree from '../../../../website/src/blueprints/adwaita/combo-row.blp?shared-tree';
+import adwaitaEntryRowTree from '../../../../website/src/blueprints/adwaita/entry-row.blp?shared-tree';
+import adwaitaExpanderRowTree from '../../../../website/src/blueprints/adwaita/expander-row.blp?shared-tree';
+import adwaitaHeaderBarTree from '../../../../website/src/blueprints/adwaita/header-bar.blp?shared-tree';
+import adwaitaNavigationSplitViewTree from '../../../../website/src/blueprints/adwaita/navigation-split-view.blp?shared-tree';
+import adwaitaNavigationViewTree from '../../../../website/src/blueprints/adwaita/navigation-view.blp?shared-tree';
+import adwaitaOverlaySplitViewTree from '../../../../website/src/blueprints/adwaita/overlay-split-view.blp?shared-tree';
+import adwaitaPasswordEntryRowTree from '../../../../website/src/blueprints/adwaita/password-entry-row.blp?shared-tree';
+import adwaitaPreferencesGroupTree from '../../../../website/src/blueprints/adwaita/preferences-group.blp?shared-tree';
+import adwaitaShortcutLabelTree from '../../../../website/src/blueprints/adwaita/shortcut-label.blp?shared-tree';
+import adwaitaSidebarTree from '../../../../website/src/blueprints/adwaita/sidebar.blp?shared-tree';
+import adwaitaSpinRowTree from '../../../../website/src/blueprints/adwaita/spin-row.blp?shared-tree';
+import adwaitaSplitButtonTree from '../../../../website/src/blueprints/adwaita/split-button.blp?shared-tree';
+import adwaitaStatusPageTree from '../../../../website/src/blueprints/adwaita/status-page.blp?shared-tree';
+import adwaitaSwitchRowTree from '../../../../website/src/blueprints/adwaita/switch-row.blp?shared-tree';
+import adwaitaToggleGroupTree from '../../../../website/src/blueprints/adwaita/toggle-group.blp?shared-tree';
+import adwaitaToolbarViewTree from '../../../../website/src/blueprints/adwaita/toolbar-view.blp?shared-tree';
+import adwaitaViewSwitcherBarTree from '../../../../website/src/blueprints/adwaita/view-switcher-bar.blp?shared-tree';
+import adwaitaWindowTitleTree from '../../../../website/src/blueprints/adwaita/window-title.blp?shared-tree';
+import adwaitaWrapBoxTree from '../../../../website/src/blueprints/adwaita/wrap-box.blp?shared-tree';
+import gtkButtonTree from '../../../../website/src/blueprints/gtk/button.blp?shared-tree';
+import gtkMenuButtonTree from '../../../../website/src/blueprints/gtk/menu-button.blp?shared-tree';
+
+import { buildSharedTree } from './shared-tree-builder.js';
+
+/** Every one-Blueprint `.blp` of the gallery, by its path under `website/src/blueprints/`. */
+export const GALLERY_BLUEPRINTS: Readonly<Record<string, SharedTreeNode>> = {
+    'adwaita/action-row.blp': adwaitaActionRowTree,
+    'adwaita/avatar.blp': adwaitaAvatarTree,
+    'adwaita/banner.blp': adwaitaBannerTree,
+    'adwaita/bottom-sheet.blp': adwaitaBottomSheetTree,
+    'adwaita/button-content.blp': adwaitaButtonContentTree,
+    'adwaita/button-row.blp': adwaitaButtonRowTree,
+    'adwaita/carousel.blp': adwaitaCarouselTree,
+    'adwaita/clamp.blp': clampTree,
+    'adwaita/combo-row.blp': adwaitaComboRowTree,
+    'adwaita/entry-row.blp': adwaitaEntryRowTree,
+    'adwaita/expander-row.blp': adwaitaExpanderRowTree,
+    'adwaita/header-bar.blp': adwaitaHeaderBarTree,
+    'adwaita/navigation-split-view.blp': adwaitaNavigationSplitViewTree,
+    'adwaita/navigation-view.blp': adwaitaNavigationViewTree,
+    'adwaita/overlay-split-view.blp': adwaitaOverlaySplitViewTree,
+    'adwaita/password-entry-row.blp': adwaitaPasswordEntryRowTree,
+    'adwaita/preferences-group.blp': adwaitaPreferencesGroupTree,
+    'adwaita/shortcut-label.blp': adwaitaShortcutLabelTree,
+    'adwaita/sidebar.blp': adwaitaSidebarTree,
+    'adwaita/spin-row.blp': adwaitaSpinRowTree,
+    'adwaita/split-button.blp': adwaitaSplitButtonTree,
+    'adwaita/status-page.blp': adwaitaStatusPageTree,
+    'adwaita/switch-row.blp': adwaitaSwitchRowTree,
+    'adwaita/toggle-group.blp': adwaitaToggleGroupTree,
+    'adwaita/toolbar-view.blp': adwaitaToolbarViewTree,
+    'adwaita/view-switcher-bar.blp': adwaitaViewSwitcherBarTree,
+    'adwaita/window-title.blp': adwaitaWindowTitleTree,
+    'adwaita/wrap-box.blp': adwaitaWrapBoxTree,
+    'gtk/button.blp': gtkButtonTree,
+    'gtk/menu-button.blp': gtkMenuButtonTree,
+};
+
+/**
+ * An attribute's value as the comparison reads it. `style` is read as the declarations it
+ * sets, one longhand each and sorted: which of the builder's margin and an element's own
+ * `flex-direction` was written first, and whether the serialiser folds two margins into a
+ * `margin-inline`, is text neither side chose and no style resolves differently for.
+ */
+const attributeText = (el: Element, attribute: Attr): string => {
+    if (attribute.name !== 'style') return attribute.value;
+    const style = (el as HTMLElement).style;
+    return [...style]
+        .map((property) => `${property}: ${style.getPropertyValue(property)}`)
+        .sort()
+        .join('; ');
+};
+
+/**
+ * An element tree as text a comparison can hold: the tag, the attributes SORTED (their order is
+ * the one thing markup and a builder may legitimately disagree on, and no element reads it), and
+ * the children, with the indentation between elements dropped since the builder never makes any.
+ */
+const canonical = (el: Element, depth = 0): string => {
+    const attributes = [...el.attributes].map((a) => `${a.name}=${JSON.stringify(attributeText(el, a))}`).sort();
+    const pad = '  '.repeat(depth);
+    const lines = [`${pad}<${el.localName}${attributes.map((a) => ` ${a}`).join('')}>`];
+    for (const node of el.childNodes) {
+        if (node.nodeType === Node.ELEMENT_NODE) lines.push(canonical(node as Element, depth + 1));
+        else if (node.nodeType === Node.TEXT_NODE && node.textContent?.trim() !== '') {
+            lines.push(`${pad}  ${JSON.stringify(node.textContent)}`);
+        }
+    }
+    return lines.join('\n');
+};
+
+const withIds = (node: SharedTreeNode, into: SharedTreeNode[] = []): SharedTreeNode[] => {
+    if (node.id !== undefined) into.push(node);
+    for (const child of node.children ?? []) withIds(child, into);
+    return into;
+};
+
+export const AdwBlueprintMarkupTest = async () => {
+    await describe('adwaita-web: the gallery’s markup, parsed', async () => {
+        for (const [file, tree] of Object.entries(GALLERY_BLUEPRINTS)) {
+            // Both sides DETACHED and upgraded: a detached build runs each element's constructor
+            // and attribute callbacks (a label renders its text on `label=`), and so does parsing
+            // in this document. Neither is connected, so what differs is only what was authored.
+            await it(`${file}: parses to the element tree buildSharedTree makes`, async () => {
+                const parsed = document.createRange().createContextualFragment(sharedTreeHtml(tree));
+                expect(canonical(parsed.firstElementChild!)).toBe(canonical(buildSharedTree(tree)));
+            });
+
+            await it(`${file}: mounted, every id reaches an upgraded element of its tag`, async () => {
+                const host = document.createElement('div');
+                host.innerHTML = sharedTreeHtml(tree);
+                document.body.append(host);
+                try {
+                    const nodes = withIds(tree);
+                    expect(nodes.length > 0).toBe(true);
+                    for (const node of nodes) {
+                        const found = host.querySelector(`#${node.id}`);
+                        const tag = hostTagOf(node.tag);
+                        expect(found?.localName).toBe(tag);
+                        const defined = customElements.get(tag);
+                        expect(defined !== undefined && found instanceof defined).toBe(true);
+                    }
+                } finally {
+                    host.remove();
+                }
+            });
+        }
+    });
+};