@gjsify/adwaita-web 0.64.1-next.247 → 0.64.2-next.252

package/src/icon-theme.spec.ts

@@ -4,7 +4,9 @@
 //
 // The order under test is GLib's (`g_themed_icon_update_names`, which `GtkImage`'s lookup
 // goes through): `X` tries [X, X-symbolic], `X-symbolic` tries [X-symbolic, X], and a name
-// neither answers draws `image-missing`. The registry is module-level and outlives a test,
+// neither answers draws `image-missing`. Over the names the order is gtkicontheme.c's: the
+// current theme (the stylesheet's glyphs) before hicolor, where a colour registration sits.
+// The registry is module-level and outlives a test,
 // so every case registers names of its own.
 import { describe, expect, it } from '@gjsify/unit';
 
@@ -114,13 +116,16 @@ export const AdwIconThemeTest = async () => {
             host.remove();
         });
 
-        await it('X prefers the colour icon, X-symbolic prefers the symbolic one', () => {
+        await it("the theme's X-symbolic answers X and X-symbolic before the colour X, as on GTK", () => {
             const NAME = 'gjsify-theme-both-probe';
             registerColorIcon(NAME, COLOR_SVG);
             registerIcon(`${NAME}-symbolic`, SYMBOLIC_SVG);
 
+            // gtkicontheme.c `real_choose_icon`: theme outer, name inner, and the colour icon is
+            // hicolor's, so the current theme's `X-symbolic` comes first (ADR 0115 Amendment 2).
             const plain = mount(NAME);
-            expect(drawsInColor(plain.el)).toBe(true);
+            expect(plain.el.classList.contains(COLOR_ICON_CLASS)).toBe(false);
+            expect(maskOf(plain.el).includes('m%203%203')).toBe(true);
             plain.host.remove();
 
             const symbolic = mount(`${NAME}-symbolic`);

package/src/icon-theme.ts

@@ -23,23 +23,43 @@
 // is named after its application ID (`org.gnome.Builder`, adw-about-dialog.c:1215), which is
 // not a CSS token and never could be a mask class, but is a perfectly good Map key.
 //
+// RESOURCE PATHS (ADR 0116 § 4). The names go through the `Gtk.IconTheme` resource paths an
+// application added (`GtkApplication` adds `<resource-base-path>/icons/` at startup);
+// `@gjsify/adwaita-core`'s `lookupResourceIcon` decides which file answers, as gtkicontheme.c
+// does, and asks this module only whether the stylesheet holds a symbolic glyph. A colour
+// registration stands in hicolor there, as the file an app ships in `hicolor/scalable/apps/`
+// would: the stylesheet's `X-symbolic` answers `X` before it, as Adwaita's does on GNOME. A file
+// answers as a blob URL of its bytes: a symbolic one is drawn as a mask in `currentColor`, the
+// rest as-is. A browser draws SVG and PNG; an XPM or a compressed entry draws `image-missing`
+// with a warning.
+//
 // Original implementation.
 
-import { normalizeIconName } from '@gjsify/adwaita-core';
+import {
+    iconLookupNames,
+    lookupResourceIcon,
+    normalizeIconName,
+    resources_lookup_data,
+    type IconDirection,
+} from '@gjsify/adwaita-core';
 import { toDataUri } from '@gjsify/adwaita-icons/utils';
 
+import { IconTheme } from './namespace/gtk-platform.js';
+
 /** What one icon name resolves to, in the order GTK's theme would try it. */
 export type IconLookup =
     /** A registered full-colour image, drawn as-is. `url` is ready for `url("…")`. */
     | { kind: 'color'; name: string; url: string }
+    /**
+     * A file under a `Gtk.IconTheme` resource path; `symbolic` files are masks in `currentColor`.
+     * `url` is `null` when the browser cannot draw the file (XPM, compressed): draw `image-missing`.
+     */
+    | { kind: 'resource'; name: string; path: string; url: string | null; symbolic: boolean }
     /** A symbolic glyph, drawn through the `.adw-icon--<name>` mask. `name` is normalized. */
     | { kind: 'symbolic'; name: string }
     /** Nothing in the theme answers this name — draw `image-missing`. */
     | { kind: 'missing' };
 
-/** The suffix `g_themed_icon_update_names` swaps to build the other variant. */
-const SYMBOLIC_SUFFIX = /-symbolic$/;
-
 /**
  * Every name GTK's theme treats as a symbolic FILE (gtkicontheme.c `icon_name_is_symbolic`):
  * the directional variants are symbolic too, so none of them is a colour icon.
@@ -82,33 +102,97 @@ function hasSymbolic(normalized: string): boolean {
  * Resolve `iconName` as `gtk_icon_theme_lookup_by_gicon` would for a `GtkImage`. `null` when
  * no name was given — the state where GTK draws nothing, not `image-missing`.
  *
- * When no colour icon is registered for the name, a symbolic request is returned WITHOUT
- * checking the cascade: the mask class falls back to `image-missing` through CSS by itself
- * and corrects itself when a later `registerIcon` lands, which is how `<gtk-image>` behaved
- * before this module. The cascade is read only to choose between a colour entry and a
- * symbolic glyph.
+ * When neither a colour registration nor a resource holds a name, the request is returned as a
+ * symbolic one WITHOUT checking the cascade: the mask class falls back to `image-missing`
+ * through CSS by itself and corrects itself when a later `registerIcon` lands, which is how
+ * `<gtk-image>` behaved before this module. The cascade is read only to choose between a
+ * symbolic glyph and a colour entry or file.
  */
-export function lookupIcon(iconName: string | null | undefined): IconLookup | null {
+export function lookupIcon(iconName: string | null | undefined, request: IconRequest = {}): IconLookup | null {
     if (iconName === null || iconName === undefined || iconName === '') return null;
-    const symbolicRequest = SYMBOLIC_SUFFIX.test(iconName);
-    const colorName = symbolicRequest ? iconName.replace(SYMBOLIC_SUFFIX, '') : iconName;
-    const color = colorIcons.get(colorName);
+    const found = resourceIcon(iconName, request);
+    if (found !== null) return found;
     const symbolic = normalizeIconName(iconName);
+    return symbolic === '' ? { kind: 'missing' } : { kind: 'symbolic', name: symbolic };
+}
 
-    if (color === undefined) {
-        return symbolic === '' ? { kind: 'missing' } : { kind: 'symbolic', name: symbolic };
+/** What a `GtkImage` hands its theme besides the name: its size, scale and text direction. */
+export interface IconRequest {
+    /** In CSS pixels; 16 when absent. */
+    readonly size?: number;
+    /** The device scale; 1 when absent. */
+    readonly scale?: number;
+    readonly direction?: IconDirection;
+}
+
+const theme = IconTheme.get_for_display(null);
+
+/** Blob URLs of resource files, by resource path, for the current scan. */
+const resourceUrls = new Map<string, string | null>();
+
+theme.connect('changed', () => {
+    for (const url of resourceUrls.values()) if (url !== null) URL.revokeObjectURL(url);
+    resourceUrls.clear();
+    notifyIconThemeChanged();
+});
+
+const RESOURCE_TYPES: Record<string, string> = { '.svg': 'image/svg+xml', '.png': 'image/png' };
+
+/** The file at `path` as a URL a browser draws, or `null` (warned once) when it cannot. */
+function resourceUrl(path: string): string | null {
+    const cached = resourceUrls.get(path);
+    if (cached !== undefined) return cached;
+    let url: string | null = null;
+    const type = RESOURCE_TYPES[path.slice(path.lastIndexOf('.'))];
+    if (type === undefined) {
+        console.warn(`Gtk.IconTheme: ${path} is not an SVG or a PNG, which is all a browser draws (ADR 0116 § 4).`);
+    } else {
+        try {
+            const data = resources_lookup_data(path, 0).get_data();
+            url = URL.createObjectURL(new Blob([data as Uint8Array<ArrayBuffer>], { type }));
+        } catch (error) {
+            console.warn(`Gtk.IconTheme: ${path} cannot be drawn: ${(error as Error).message}`);
+        }
     }
-    if (symbolicRequest && hasSymbolic(symbolic)) return { kind: 'symbolic', name: symbolic };
-    return { kind: 'color', name: colorName, url: color };
+    resourceUrls.set(path, url);
+    return url;
+}
+
+/**
+ * The lookup over the colour registrations and the theme's resource paths; `null` when neither
+ * answers any name, a `symbolic` entry when the current theme's glyph comes first.
+ */
+export function resourceIcon(iconName: string, request: IconRequest): IconLookup | null {
+    const match = lookupResourceIcon(theme, {
+        names: iconLookupNames(iconName, request.direction ?? null),
+        get size() {
+            return request.size ?? 16;
+        },
+        scale: request.scale ?? 1,
+        themeHas: (name) => hasSymbolic(normalizeIconName(name)),
+        hicolorHas: (name) => colorIcons.has(name),
+    });
+    if (match === null) return null;
+    if (match.kind === 'theme') return { kind: 'symbolic', name: normalizeIconName(match.name) };
+    if (match.kind === 'hicolor') return { kind: 'color', name: match.name, url: colorIcons.get(match.name)! };
+    return {
+        kind: 'resource',
+        name: match.name,
+        path: match.path,
+        url: resourceUrl(match.path),
+        symbolic: match.symbolic,
+    };
 }
 
 /**
  * Whether `iconName` resolves to something other than `image-missing` — a registered colour
- * icon, or a symbolic glyph compiled into the stylesheet or registered at runtime.
+ * icon, a file under a resource path, or a symbolic glyph compiled into the stylesheet or
+ * registered at runtime.
  */
 export function iconResolves(iconName: string): boolean {
     const found = lookupIcon(iconName);
     if (found === null || found.kind === 'missing') return false;
+    if (found.kind === 'resource') return found.url !== null;
     return found.kind === 'color' || hasSymbolic(found.name);
 }
 

package/src/index.ts

@@ -80,8 +80,8 @@ export type { AdwUndershootEdges } from './scroll-shading.js';
 // replaying an authored tree — a storybook fixture, a devtools probe, the shared-trees
 // spec itself — has a route to it that is not a `.spec.ts` import; see that file's header
 // for why `mountSharedTree` and not `buildSharedTree` alone is the instantiation half.
-export { buildSharedTree, mountSharedTree } from './shared-tree-builder.js';
-export type { MountOptions, MountedSharedTree, SizeSource } from './shared-tree-builder.js';
+export { buildSharedTree, buildWithSiblings, mountSharedTree } from './shared-tree-builder.js';
+export type { BuildOptions, BuiltTree, MountOptions, MountedSharedTree, SizeSource } from './shared-tree-builder.js';
 export { registerTemplateClass } from './template-classes.js';
 
 // The stylesheet compiles a chosen SUBSET of `@gjsify/adwaita-icons` (the whole set is

package/src/keyboard-operable.spec.ts

@@ -314,8 +314,8 @@ export const AdwKeyboardOperableTest = async () => {
                 '<adw-alert-response id="ok">OK</adw-alert-response>' +
                     '<adw-alert-response id="cancel">Cancel</adw-alert-response>',
             );
-            el.setDefaultResponse('ok');
-            el.setResponseEnabled('ok', false);
+            el.set_default_response('ok');
+            el.set_response_enabled('ok', false);
             opener.focus();
             el.setAttribute('open', '');
 
@@ -344,7 +344,7 @@ export const AdwKeyboardOperableTest = async () => {
                     '<adw-alert-response id="ok">OK</adw-alert-response>' +
                     '<adw-alert-response id="cancel">Cancel</adw-alert-response>',
             );
-            el.setDefaultResponse('ok');
+            el.set_default_response('ok');
             el.setAttribute('open', '');
 
             // `adw_alert_dialog_grab_focus` tries the CONTENT first (adw-alert-dialog.c:397)

package/src/learn6502-window.spec.ts

@@ -0,0 +1,113 @@
+// Learn6502's `main.window.blp`, reduced to the shapes that rendered short through
+// `buildWithSiblings`: header-bar buttons after a single `[start]` (GtkBuilder packs an untyped
+// child at start too), and `Overlay { child: Adw.ToastOverlay { Stack } }`. Every
+// widget the file authors has to be in the document once the built window is attached — the
+// failure was widgets that were built and then silently dropped on the way.
+import { describe, expect, it } from '@gjsify/unit';
+import { parseBlueprint, projectToSharedNode } from '@gjsify/blueprint';
+
+import { buildWithSiblings } from './shared-tree-builder.js';
+
+const BLUEPRINT = `using Gtk 4.0;
+using Adw 1;
+
+Adw.ApplicationWindow mainWindow {
+  content: Adw.ToolbarView toolbarView {
+    [top]
+    Adw.HeaderBar headerBar {
+      title-widget: Label titleLabel {
+        label: "Learn 6502";
+      };
+
+      [start]
+      ToggleButton sidebarToggleButton {
+        icon-name: "sidebar-show-symbolic";
+      }
+
+      Button learnBackButton {
+        icon-name: "go-previous-symbolic";
+      }
+
+      Button unsavedChangesIndicator {
+        icon-name: "dot-symbolic";
+      }
+
+      [end]
+      MenuButton menuButton {
+        icon-name: "open-menu-symbolic";
+      }
+    }
+
+    content: Overlay mainOverlay {
+      child: Adw.ToastOverlay toastOverlay {
+        Stack layoutHost {
+          StackPage singlePage {
+            name: "single";
+            child: Adw.Bin singleContainer {
+              child: Label singleLabel {
+                label: "single";
+              };
+            };
+          }
+
+          StackPage threePage {
+            name: "three";
+            child: Adw.Bin threeColumnContainer {
+              child: Box threeColumns {
+                Label threeLabel {
+                  label: "three";
+                }
+              };
+            };
+          }
+        }
+      };
+    };
+  };
+}
+`;
+
+const AUTHORED = [
+    'toolbarView',
+    'headerBar',
+    'titleLabel',
+    'sidebarToggleButton',
+    'learnBackButton',
+    'unsavedChangesIndicator',
+    'menuButton',
+    'mainOverlay',
+    'toastOverlay',
+    'layoutHost',
+    'singleContainer',
+    'singleLabel',
+    'threeColumnContainer',
+    'threeColumns',
+    'threeLabel',
+];
+
+export const AdwLearn6502WindowTest = async () => {
+    await describe("Learn6502's main window through buildWithSiblings", async () => {
+        const { node, lost } = projectToSharedNode(parseBlueprint(BLUEPRINT, 'main.window.blp'));
+
+        await it('projects without losing anything', () => {
+            expect(lost.map((loss) => `${loss.kind}@${loss.line}`).join()).toBe('');
+        });
+
+        await it('puts every authored widget in the document, the start buttons at start', () => {
+            const { root } = buildWithSiblings(node);
+            document.body.append(root);
+            const missing = AUTHORED.filter((id) => !root.querySelector(`#${id}`)?.isConnected);
+            const start = ['sidebarToggleButton', 'learnBackButton', 'unsavedChangesIndicator'].filter(
+                (id) => root.querySelector(`#${id}`)?.parentElement?.className !== 'adw-header-bar-start',
+            );
+            const toast = root.querySelector('#toastOverlay');
+            const overlaid =
+                toast?.closest('.adw-overlay-child') === root.querySelector('#mainOverlay > .adw-overlay-child');
+            root.remove();
+
+            expect(missing.join()).toBe('');
+            expect(start.join()).toBe('');
+            expect(overlaid).toBe(true);
+        });
+    });
+};

package/src/namespace/adw.ts

@@ -111,4 +111,4 @@ export { AdwWindowTitle as WindowTitle } from '../elements/adw-window-title.js';
 export { AdwWrapBox as WrapBox } from '../elements/adw-wrap-box.js';
 export { AdwApplication as Application } from '../application.js';
 export { AdwStyleManager as StyleManager } from '../style-manager.js';
-export { ColorScheme } from '@gjsify/adwaita-core';
+export { ColorScheme, Toast, ToastPriority } from '@gjsify/adwaita-core';

package/src/namespace/gio.ts

@@ -35,5 +35,15 @@ export {
     promisify as _promisify,
 } from '@gjsify/adwaita-core';
 export { SimpleAction, SimpleActionGroup, ApplicationFlags } from '@gjsify/adwaita-core';
+export {
+    GioResource as Resource,
+    ResourceError,
+    ResourceLookupFlags,
+    resources_enumerate_children,
+    resources_get_info,
+    resources_lookup_data,
+    resources_register,
+    resources_unregister,
+} from '@gjsify/adwaita-core';
 export { GioApplication as Application } from '../application.js';
 export { Settings } from '@gjsify/app-settings/browser';

package/src/namespace/gtk.ts

@@ -86,6 +86,7 @@ export { GtkSeparator as Separator } from '../elements/gtk-separator.js';
 export { GtkSpinButton as SpinButton } from '../elements/gtk-spin-button.js';
 export { GtkSpinner as Spinner } from '../elements/gtk-spinner.js';
 export { GtkStack as Stack } from '../elements/gtk-stack.js';
+export { GtkStackPage as StackPage } from '../elements/gtk-stack-page.js';
 export { GtkStackSidebar as StackSidebar } from '../elements/gtk-stack-sidebar.js';
 export { GtkStackSwitcher as StackSwitcher } from '../elements/gtk-stack-switcher.js';
 export { GtkStringList as StringList } from '@gjsify/adwaita-core';
@@ -101,6 +102,7 @@ export type { WindowCommon } from '@gjsify/adwaita-core';
 export { GtkWindowControls as WindowControls } from '../elements/gtk-window-controls.js';
 export { GtkViewport as Viewport } from '../elements/gtk-viewport.js';
 export { GtkWindowHandle as WindowHandle } from '../elements/gtk-window-handle.js';
+export { ApplicationInhibitFlags } from '@gjsify/adwaita-core';
 export { GtkApplication as Application } from '../application.js';
 export {
     STYLE_PROVIDER_PRIORITY_APPLICATION,

package/src/shared-tree-builder.ts

@@ -55,7 +55,14 @@ import {
 
 import { observeAdaptiveSize } from './breakpoints.js';
 import { capabilities } from './capabilities.mjs';
-import { endpointOf, hasElementApi, installElementApi, installSensitive } from './gobject-elements.js';
+import {
+    endpointOf,
+    hasElementApi,
+    hasInstalledVisible,
+    installElementApi,
+    installSensitive,
+    installVisible,
+} from './gobject-elements.js';
 import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
 import { isTemplateTag, templateTagFor } from './template-classes.js';
@@ -154,14 +161,93 @@ function isWritable(el: object, member: string): boolean {
  * upgraded has declared no slots yet, so the refusal below belongs to the mount.
  */
 export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = newRecord()): HTMLElement {
+    refuseSiblings(node, 'buildSharedTree');
+    return buildTree(node, record).root;
+}
+
+/** What {@link buildWithSiblings} hands back: the root element and the objects built beside it. */
+export interface BuiltTree {
+    /** The element the tree roots at, as {@link buildSharedTree} returns it. */
+    root: HTMLElement;
+    /**
+     * The sibling objects by id — `Adw.AlertDialog unsavedChangesDialog { }` or `$Learn learn { }`
+     * written after the template. A sibling is built in the root's id scope (a setter or a bind
+     * may name it) but is no child of the root: the code beside the file decides where, or
+     * whether, it is placed.
+     */
+    siblings: ReadonlyMap<string, HTMLElement>;
+    /** Every element the tree names by id, siblings included: what `GtkBuilder.get_object` answers for. */
+    objects: ReadonlyMap<string, HTMLElement>;
+}
+
+/** What {@link buildWithSiblings} takes beside the tree. */
+export interface BuildOptions {
+    /** The object a handler NAME is looked up on (ADR 0093 § 3). */
+    scope?: Readonly<Record<string, unknown>>;
+    /** The size source a `breakpoints` node is driven from. */
+    observeSize?: SizeSource;
+}
+
+/**
+ * A tree with sibling roots (ADR 0093): the root element, and each sibling by id, all DETACHED
+ * like {@link buildSharedTree}'s result.
+ *
+ * {@link buildSharedTree}, {@link mountSharedTree} and {@link buildTemplateTree} refuse such a
+ * tree by name, because they return one element and the siblings would be built and then thrown
+ * away. A sibling with no id is refused too: nothing could ever ask for it, which is how a
+ * dropped object looks finished.
+ */
+export function buildWithSiblings(node: SharedTreeNode, options: BuildOptions = {}): BuiltTree {
+    const record = newRecord(options.scope, options.observeSize);
+    const built = buildTree(node, record);
+    // An element declares its slots when it is connected, so a detached tree cannot be checked
+    // as it stands. It is connected for the length of the check and handed back detached, as
+    // documented: a placement the renderer could not honour is refused here, like
+    // `mountSharedTree` refuses it, instead of surfacing as a widget missing from the page.
+    const probe = document.createElement('div');
+    probe.hidden = true;
+    probe.append(built.root, ...built.siblings.values());
+    document.body.append(probe);
+    try {
+        refuseUnknownSlots(record.placed);
+        refuseUnheldExtensions(record.extended);
+    } catch (error) {
+        for (const dispose of record.disposers) dispose();
+        throw error;
+    } finally {
+        probe.remove();
+        for (const el of [built.root, ...built.siblings.values()]) el.remove();
+    }
+    return built;
+}
+
+function refuseSiblings(node: SharedTreeNode, door: string): void {
+    if ((node.siblings?.length ?? 0) === 0) return;
+    throw new Error(
+        `\`${node.tag}\` carries ${node.siblings!.length} sibling object(s), and \`${door}\` returns one object ` +
+            'so they would be built and lost. Use `buildWithSiblings`, which hands them back by id.',
+    );
+}
+
+/** Every node, its siblings in the same id scope, then the binds and breakpoints that name them. */
+function buildTree(node: SharedTreeNode, record: BuildRecord): BuiltTree {
     // ADR 0093 § 2: the whole tree is checked against the capability table before an element is
     // created. A refused `layout` is named with its node and the reason the table gives.
     assertTreeConstructs('adwaita-web', capabilities, node);
     if (node.menus !== undefined) record.menus = node.menus;
     const root = buildNode(node, record);
+    const siblings = new Map<string, HTMLElement>();
+    for (const sibling of node.siblings ?? []) {
+        if (sibling.id === undefined) {
+            throw new Error(
+                `the sibling \`${sibling.tag}\` has no id, so nothing could ever ask for it: give it one in the .blp.`,
+            );
+        }
+        siblings.set(sibling.id, buildNode(sibling, record));
+    }
     for (const bind of record.binds) bindProperty(bind, record);
     for (const host of record.breakpointHosts) bindBreakpoints(host.el, host.node, record);
-    return root;
+    return { root, siblings, objects: new Map(record.ids) };
 }
 
 /** A fresh record, with the scope when the caller has one. */
@@ -344,7 +430,9 @@ export function writeProp(el: HTMLElement, prop: string, value: string | number
     const member = propertyOf(prop);
     const expand = GTK_WIDGET_EXPAND.find((name) => name === attr);
     if (expand !== undefined && typeof value === 'boolean') el.setAttribute(expand, value ? '' : 'false');
-    else if (isTemplateTag(el.localName) && member in el) {
+    else if (attr === 'visible' && typeof value === 'boolean' && hasInstalledVisible(el)) {
+        (el as unknown as Record<string, unknown>)[member] = value;
+    } else if (isTemplateTag(el.localName) && member in el) {
         // An application class has no attributeChangedCallback: its properties are GObject properties,
         // set the way `Gtk.Builder` sets them, after the constructor.
         (el as unknown as Record<string, unknown>)[member] = value;
@@ -372,9 +460,14 @@ function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
     const el = document.createElement(node.extern === true ? templateTagFor(node.tag) : hostTagOf(node.tag));
     // A template's children talk GObject to the template: `connect`, `emit`, `notify` (ADR 0096).
     if (record.template !== undefined) installElementApi(el);
+    // `Gtk.Widget:visible`, which no element spells: a setter's target and an authored `false` need it.
+    installVisible(el);
     // The id is how the TypeScript beside a `.blp` reaches this element
     // (`root.querySelector('#…')`), the counterpart of `InternalChildren` on GTK.
     if (node.id !== undefined) {
+        if (record.ids.has(node.id)) {
+            throw new Error(`Two nodes of this tree carry the id '${node.id}'; GtkBuilder refuses a duplicate id.`);
+        }
         el.id = node.id;
         record.ids.set(node.id, el);
     }
@@ -492,6 +585,7 @@ export interface BuiltTemplateTree {
  * belong to the first `connectedCallback`.
  */
 export function buildTemplateTree(tree: SharedTreeNode, scope: TemplateScope, host: HTMLElement): BuiltTemplateTree {
+    refuseSiblings(tree, 'buildTemplateTree');
     assertTreeConstructs('adwaita-web', capabilities, tree);
     const record = newRecord(undefined, undefined, scope);
     record.menus = tree.menus;
@@ -591,9 +685,9 @@ function writeExtensions(el: HTMLElement, node: SharedTreeNode): void {
 
 /** The response API an element answers to — `<adw-alert-dialog>`'s, named after libadwaita's. */
 interface ResponseReader {
-    getResponseLabel(id: string): string | null;
-    getResponseAppearance(id: string): string | null;
-    getResponseEnabled(id: string): boolean;
+    get_response_label(id: string): string | null;
+    get_response_appearance(id: string): string | null;
+    get_response_enabled(id: string): boolean;
 }
 
 /**
@@ -617,10 +711,10 @@ function refuseUnheldExtensions(extended: readonly ExtendedNode[]): void {
         const reader = el as unknown as Partial<ResponseReader>;
         for (const response of node.extensions?.responses ?? []) {
             const held =
-                typeof reader.getResponseLabel === 'function' &&
-                reader.getResponseLabel(response.id) === response.label &&
-                reader.getResponseAppearance?.(response.id) === (response.appearance ?? 'default') &&
-                reader.getResponseEnabled?.(response.id) === (response.enabled ?? true);
+                typeof reader.get_response_label === 'function' &&
+                reader.get_response_label(response.id) === response.label &&
+                reader.get_response_appearance?.(response.id) === (response.appearance ?? 'default') &&
+                reader.get_response_enabled?.(response.id) === (response.enabled ?? true);
             if (!held) {
                 throw new Error(
                     `<${el.localName}> did not register the response "${response.id}" as authored, so the ` +
@@ -696,6 +790,7 @@ export interface MountOptions {
  * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
  */
 export function mountSharedTree(node: SharedTreeNode, options: MountOptions = {}): MountedSharedTree {
+    refuseSiblings(node, 'mountSharedTree');
     const { into } = options;
     const host = into ?? document.createElement('div');
     const record = newRecord(options.scope, options.observeSize);

package/src/shared-trees.spec.ts

@@ -54,7 +54,7 @@ import { ADWAITA_GALLERY_SHARED_TREES } from '../../../../scripts/adwaita-galler
 
 import '@gjsify/adwaita-web';
 
-import { mountSharedTree } from './shared-tree-builder.js';
+import { buildWithSiblings, mountSharedTree } from './shared-tree-builder.js';
 
 /**
  * Connect the authored root — these elements build on connect — run, and take it down again.
@@ -364,6 +364,20 @@ export const AdwSharedTreesTest = async () => {
             ).toThrow('has no slot "middle"');
         });
 
+        // The detached door refuses it too: a root built and handed back is mounted by the
+        // caller, after the builder could still say anything.
+        await it('`buildWithSiblings` refuses the same placement, and hands a good tree back detached', () => {
+            const bad = { tag: 'AdwToolbarView', children: [{ tag: 'AdwBanner', slot: 'middle' }] };
+            expect(() => buildWithSiblings(bad)).toThrow('has no slot "middle"');
+            const { root, siblings } = buildWithSiblings({
+                tag: 'AdwToolbarView',
+                children: [{ tag: 'AdwBanner', slot: 'top' }],
+                siblings: [{ tag: 'GtkLabel', id: 'beside' }],
+            });
+            expect(root.isConnected || siblings.get('beside')!.isConnected).toBe(false);
+            expect(root.querySelector('adw-banner') !== null).toBe(true);
+        });
+
         // ADR 0092's `layout { }`: a grid child's cell. GTK counts from 0, CSS Grid from 1.
         await it('`layout { }` places a grid child in its cell, spans defaulting to one', () => {
             mounted(

package/src/slotted-children.spec.ts

@@ -113,6 +113,30 @@ export const AdwSlottedChildrenTest = async () => {
             expect(report).toBe('[1]');
         });
 
+        // The DECLARED twin of the case above. `install()` replaces the host's children with
+        // its structure, and a child no slot took used to go with them — gone without a word.
+        await it('keeps a declared child no slot takes, and warns that it was not placed', () => {
+            const host = document.createElement('div');
+            const typo = probe('sied', 'a');
+            host.append(document.createTextNode('\n  '), typo);
+            mounted(host);
+            const side = document.createElement('div');
+            side.className = 'side';
+
+            const warned: string[] = [];
+            const warn = console.warn;
+            console.warn = (...args: unknown[]) => void warned.push(args.join(' '));
+            try {
+                bindSlottedChildren(host, [{ name: 'side', into: side }]).install(side);
+            } finally {
+                console.warn = warn;
+            }
+
+            const report = `${placement(host, typo)} | ${warned.join()}`;
+            host.remove();
+            expect(report).toBe("[1] | 'sied' is not a valid child type of 'div'");
+        });
+
         await it('re-adopts a child that was appended, removed and appended again', async () => {
             const host = mounted(document.createElement('div'));
             const side = document.createElement('div');

package/src/slotted-children.ts

@@ -113,6 +113,12 @@ export interface AdwSlottedChildren {
 /** Where a bound host's slots can be read back from — see {@link slottedChildrenOf}. */
 const BOUND = new WeakMap<Element, AdwSlottedChildren>();
 
+/** An element or a text node with something in it — markup's indentation and comments are not. */
+function isContent(node: Node): boolean {
+    if (node instanceof Element) return true;
+    return node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '';
+}
+
 /**
  * The slot binding `host` installed, if it has one.
  *
@@ -184,9 +190,19 @@ export function bindSlottedChildren(
         slots,
         slotFor,
         install(...nodes: readonly Node[]) {
-            for (const node of Array.from(host.childNodes)) route(node);
+            const unplaced: Node[] = [];
+            for (const node of Array.from(host.childNodes)) {
+                if (route(node) !== null || node.parentNode !== host || !isContent(node)) continue;
+                // `replaceChildren` below would delete it, and a child the author wrote that
+                // vanishes without a word is the silent drop this used to be. It stays beside
+                // the structure, as a late child with the same slot does, and says so the
+                // way GtkBuilder does (GTK_BUILDER_WARN_INVALID_CHILD_TYPE).
+                unplaced.push(node);
+                const type = node instanceof Element ? (node.getAttribute('slot') ?? '') : '';
+                console.warn(`'${type}' is not a valid child type of '${host.localName}'`);
+            }
             structure = new Set(nodes);
-            host.replaceChildren(...nodes);
+            host.replaceChildren(...nodes, ...unplaced);
             // Armed AFTER `replaceChildren`, so its own records are never delivered: an
             // observer armed first would see the whole of `structure` as added nodes and
             // spend a microtask rejecting them.