@gjsify/adwaita-web 0.51.0 → 0.52.0

package/src/gtk-value-doors.spec.ts

@@ -0,0 +1,104 @@
+// `Gtk.StringList` and `Gtk.Adjustment` AT THE ELEMENT, held against the spelling they
+// replace.
+//
+// THE CLAIM UNDER TEST is backward compatibility, and it is the one claim a core-side spec
+// cannot make. `@gjsify/adwaita-core` proves the two classes reduce to the same value as
+// the array and the object literal; what a reader needs to know is that the ELEMENT cannot
+// tell them apart — that `el.model = ['Blue', 'Teal']` and
+// `el.model = new Gtk.StringList({ strings: ['Blue', 'Teal'] })` leave `<adw-combo-row>` in
+// the same state, down to the `<option>` nodes it renders, and likewise for the two
+// adjustment spellings on `<adw-spin-row>`. Four spellings, each asserted against what the
+// element shows.
+//
+// The NativeScript port asserts the same four at its own widget door
+// (`gtk-value-doors.spec.ts` there), so the two renderers cannot part on this without one
+// of them failing.
+//
+// Compared as JSON rather than with `toEqual`: `@gjsify/unit`'s `toEqual` is `==`, so two
+// different objects pass it whatever they hold.
+
+import { describe, it, expect } from '@gjsify/unit';
+
+import { GtkAdjustment, GtkStringList } from '@gjsify/adwaita-core';
+
+import type { AdwComboRow } from './elements/adw-combo-row.js';
+import type { AdwSpinRow } from './elements/adw-spin-row.js';
+import type { GtkDropDown } from './elements/gtk-drop-down.js';
+
+const COLOURS = ['Blue', 'Teal', 'Green'];
+const FONT_SIZE = { lower: 0, upper: 100, value: 16, stepIncrement: 1 };
+
+function mount<T extends HTMLElement>(tag: string): T {
+    const el = document.createElement(tag) as T;
+    document.body.appendChild(el);
+    return el;
+}
+
+/** Everything a `model` write leaves behind, the rendered options included. */
+const modelState = (el: AdwComboRow | GtkDropDown, options: string) =>
+    JSON.stringify({ model: el.model, selected: el.selected, value: el.selectedValue, options });
+
+/** The option labels the row actually paints, which is what a reader sees. */
+const comboOptions = (el: HTMLElement) =>
+    [...el.querySelectorAll('option, .adw-drop-down-item-label')].map((node) => node.textContent).join('|');
+
+export const GtkValueDoorsTest = async () => {
+    await describe('<adw-combo-row> takes a plain array and a Gtk.StringList alike', async () => {
+        await it('leaves the row in the same state, rendered options included', () => {
+            const array = mount<AdwComboRow>('adw-combo-row');
+            const list = mount<AdwComboRow>('adw-combo-row');
+            array.model = COLOURS;
+            list.model = new GtkStringList({ strings: COLOURS });
+            array.selected = 1;
+            list.selected = 1;
+
+            expect(modelState(list, comboOptions(list))).toBe(modelState(array, comboOptions(array)));
+            expect(list.selectedValue).toBe('Teal');
+        });
+
+        await it('follows a list that was appended to before it was assigned', () => {
+            const strings = new GtkStringList({ strings: ['Blue'] });
+            strings.append('Teal');
+            const row = mount<AdwComboRow>('adw-combo-row');
+            row.model = strings;
+            row.selected = 1;
+
+            expect(row.selectedValue).toBe('Teal');
+        });
+    });
+
+    await describe('<gtk-drop-down> takes a plain array and a Gtk.StringList alike', async () => {
+        await it('leaves the drop-down in the same state', () => {
+            const array = mount<GtkDropDown>('gtk-drop-down');
+            const list = mount<GtkDropDown>('gtk-drop-down');
+            array.model = COLOURS;
+            list.model = new GtkStringList({ strings: COLOURS });
+            array.selected = 2;
+            list.selected = 2;
+
+            expect(modelState(list, comboOptions(list))).toBe(modelState(array, comboOptions(array)));
+            expect(list.selectedValue).toBe('Green');
+        });
+    });
+
+    await describe('<adw-spin-row> takes a plain object and a Gtk.Adjustment alike', async () => {
+        await it('leaves the row in the same state', () => {
+            const literal = mount<AdwSpinRow>('adw-spin-row');
+            const adjustment = mount<AdwSpinRow>('adw-spin-row');
+            literal.adjustment = FONT_SIZE;
+            adjustment.adjustment = new GtkAdjustment(FONT_SIZE);
+
+            expect(JSON.stringify(adjustment.adjustment)).toBe(JSON.stringify(literal.adjustment));
+            expect(adjustment.value).toBe(literal.value);
+            expect(adjustment.value).toBe(16);
+        });
+
+        await it('steps by the increment the adjustment carries, whichever spelling set it', () => {
+            const row = mount<AdwSpinRow>('adw-spin-row');
+            row.adjustment = new GtkAdjustment({ ...FONT_SIZE, stepIncrement: 4 });
+
+            expect(row.adjustment.stepIncrement).toBe(4);
+            expect(row.value).toBe(16);
+        });
+    });
+};

package/src/index.ts

@@ -57,6 +57,14 @@ export type { ApplyAccentOptions } from './accent.js';
 export { AdwScrollShading } from './scroll-shading.js';
 export type { AdwUndershootEdges } from './scroll-shading.js';
 
+// The ADR 0051 tree instantiation half — turns an `@gjsify/adwaita-core/conformance`
+// `SharedTreeNode` into real custom elements. Shipped (not test-only) so a consumer
+// 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 { MountedSharedTree } from './shared-tree-builder.js';
+
 // The stylesheet compiles a chosen SUBSET of `@gjsify/adwaita-icons` (the whole set is
 // ~1.07 MB of data-URI), so a name outside it draws the `image-missing` fallback. This is
 // the way in for an app that needs a glyph this package does not ship — see
@@ -87,6 +95,11 @@ export { isIconAvailable, registerIcon } from './icon-registry.js';
 export * as Adw from './namespace/adw.js';
 export * as Gtk from './namespace/gtk.js';
 
+// The THIRD namespace, and the one that defines no element: the GObject types an author
+// CONSTRUCTS while building a tree. `Gio.Menu` is what makes `menuModel: menu` the same
+// program here as on GJS — `./namespace/gio.ts` says what does not go in it.
+export * as Gio from './namespace/gio.js';
+
 // WHAT DID NOT MOVE INTO THE NAMESPACE, and the rule that decides it. A member exists
 // for an element whose GIR tag names a real widget; `WEB_ELEMENT_ALIGNMENT` declares the
 // rest `webOnly`, meaning no widget in the reference vocabulary stands behind it, so
@@ -127,7 +140,7 @@ export { AdwSidebarItem, AdwSidebarSection } from './elements/adw-sidebar.js';
 
 // Slot wrappers and a declarative response: on GTK these are `set_content()`,
 // `set_sheet()` and `add_response()` — calls, not widgets.
-export { AdwBottomSheetContent, AdwBottomSheetSheet } from './elements/adw-bottom-sheet.js';
+export { AdwBottomSheetBottomBar, AdwBottomSheetContent, AdwBottomSheetSheet } from './elements/adw-bottom-sheet.js';
 export { AdwAlertResponse } from './elements/adw-alert-dialog.js';
 
 // Supporting types — the option bags, enums and unions the widgets above take and

package/src/keyboard-operable.spec.ts

@@ -621,7 +621,8 @@ export const AdwKeyboardOperableTest = async () => {
             //
             // Prose cannot hold that: this line fails the commit that adds it.
             // `<adw-inline-view-switcher>` has the same gap (status/open-todos.md).
-            expect([...AdwToggleGroup.observedAttributes]).toStrictEqual(['active', 'flat', 'round']);
+            // `active-name` joined the list without touching the axis: it picks a toggle.
+            expect([...AdwToggleGroup.observedAttributes]).toStrictEqual(['active', 'active-name', 'flat', 'round']);
         });
 
         await it('adw-toggle has no state a roving walk would have to skip', async () => {

package/src/namespace/gio.ts

@@ -0,0 +1,19 @@
+// The GIO half of `@gjsify/adwaita-web`'s vocabulary — `Gio.Menu`, `Gio.MenuItem`.
+// `export * as Gio from './namespace/gio.js'` in `src/index.ts` makes it the namespace,
+// the same module shape `./adw.ts` and `./gtk.ts` take and for the same reason (one list
+// carrying the value AND the type meaning — see the header of `./adw.ts`).
+//
+// RE-EXPORTED, NOT DEFINED. This package used to carry its own copy of the classes and
+// said so; they hold no DOM, so they now live in `@gjsify/adwaita-core` beside the
+// portable model they build. This barrel is the port's DOOR onto them, and
+// `gio-menu.spec.ts` drives the whole suite through it.
+//
+// WHY THIS BARREL IS SHORT, AND WILL STAY SHORT. The other two hold ELEMENTS, and
+// `check-vocabulary-alignment.mjs` derives their members from the elements this package
+// defines. GIO defines none: what lands here is the handful of GObject types an Adwaita
+// author CONSTRUCTS while building a tree — today the menu a `menuModel` property takes.
+// `Gio.File`, `Gio.Settings`, `Gio.SimpleAction` and the rest of the library are NOT this
+// package's business; a namespace that grows past what the elements consume is a second,
+// unheld vocabulary.
+
+export { GioMenu as Menu, GioMenuItem as MenuItem } from '@gjsify/adwaita-core';

package/src/namespace/gtk.ts

@@ -10,13 +10,27 @@
 // declare. GTK4 has no radio type: a radio is a GtkCheckButton with its `group` set,
 // which is what `<adw-radio>`'s own `why` in the ledger says. So the plain form takes the
 // GIR name and the grouped one keeps its flat export in `src/index.ts`.
+//
+// TWO MEMBERS HERE ARE NOT WIDGETS — `Gtk.Adjustment` and `Gtk.StringList`, the values an
+// `adjustment` and a `model` property take. ADR 0034 § Amendment 19 is what lets a
+// clause-2 namespace carry them, `CONSTRUCTIBLE_VALUES` in `scripts/value-types.mjs` is
+// where each one is declared, and the GIR answers for both in gtk-host's committed
+// `generated/value-types.mts`. They are re-exported from `@gjsify/adwaita-core`, which is
+// where the portable list and adjustment already live: the class IS that value wearing the
+// GIR spelling, so `model: ['a','b']` and `model: new Gtk.StringList({ strings: ['a','b'] })`
+// are the same write and nothing in this package had to learn a second input shape.
 
+export { GtkAdjustment as Adjustment } from '@gjsify/adwaita-core';
+export { GtkActionBar as ActionBar } from '../elements/gtk-action-bar.js';
+export { GtkBox as Box } from '../elements/gtk-box.js';
 export { GtkButton as Button } from '../elements/gtk-button.js';
 export { GtkCheckButton as CheckButton } from '../elements/checks.js';
 export { GtkDropDown as DropDown } from '../elements/gtk-drop-down.js';
 export { GtkEntry as Entry } from '../elements/gtk-entry.js';
 export { GtkImage as Image } from '../elements/gtk-image.js';
+export { GtkLabel as Label } from '../elements/gtk-label.js';
 export { GtkMenuButton as MenuButton } from '../elements/gtk-menu-button.js';
 export { GtkPopover as Popover } from '../elements/gtk-popover.js';
 export { GtkProgressBar as ProgressBar } from '../elements/gtk-progress-bar.js';
+export { GtkStringList as StringList } from '@gjsify/adwaita-core';
 export { GtkSwitch as Switch } from '../elements/gtk-switch.js';

package/src/shared-tree-builder.ts

@@ -0,0 +1,268 @@
+// THE INSTANTIATION HALF OF ADR 0051, SHIPPED — the `adwaita-web` third of what #1726 did
+// for `gtk-host` and #1729 did for `adwaita-nativescript`. Turning an
+// `@gjsify/adwaita-core/conformance` `SharedTreeNode` into real `<adw-*>`/`<gtk-*>` custom
+// elements is this renderer's OWN translation, not test code, and it lived only inside
+// `shared-trees.spec.ts` — unreachable by a storybook fixture, a devtools probe replaying a
+// gallery block, or a second suite, all of which would have had to import a `.spec.ts` file
+// to reach it. `hostTagOf`/`attributeOf` moved to `@gjsify/adwaita-core/tags` for exactly
+// this: a builder shipping FROM a package, not a dev-only driver reading `scripts/`, can
+// depend on the two case rules without depending on `scripts/`, which cannot ship inside an
+// npm package at all.
+//
+// TWO FUNCTIONS, NOT ONE WITH A FLAG — the split neither sibling builder needed.
+// `gtk-host`'s `materialize`/`insert` and NativeScript's `_addChildFromBuilder` each fully
+// REALISE a widget at construction; nothing later changes what it is. A Custom Element is
+// not: most elements this package defines build their internals in `connectedCallback`
+// (`shared-trees.spec.ts`'s own note: "these elements build on connect"), which runs only
+// once the element is CONNECTED to a document. So `buildSharedTree` alone — `createElement`
+// + `setAttribute`, recursing into children — is precisely the builder that ships dead
+// nodes: it stays exported for a caller supplying its own attachment point (its result
+// becomes live the moment ANYTHING connects it, same as a bare `document.createElement`
+// always has), but the complete path most callers want is `mountSharedTree`: build, attach
+// under a fresh host `<div>` in `document.body`, hand back the realised root.
+//
+// `unmount` IS PART OF THE SAME LIFECYCLE, NOT A TEST HOOK. `shared-trees.spec.ts`'s own
+// `finally` block is test POLICY (never leave a red test's tree mounted for the next one to
+// trip over); the ability to detach what was attached is a plain fact about anything with a
+// `connectedCallback`, so `mountSharedTree` hands it back rather than making a caller reach
+// into a host `<div>` it was never given.
+//
+// Placed flat under `src/`, at parity with this package's other single-purpose modules
+// (`accent.ts`, `breakpoints.ts`, `icon-registry.ts`) rather than a new `conformance/` or
+// `builder/` directory for one file: unlike `gtk-host`, this package has no existing
+// `conformance/` home to add to. Exported through the existing barrel, `src/index.ts` — the
+// package's `exports` map ships only `.`, and a new subpath would buy nothing for a module
+// this small, most of which (the `SharedTreeNode` type) is erased at build anyway.
+
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import { GTK_WIDGET_MARGIN_CSS, attributeOf, hostTagOf, propertyOf } from '@gjsify/adwaita-core/tags';
+
+import { slottedChildrenOf } from './slotted-children.js';
+
+/** One authored placement, kept so {@link mountSharedTree} can hold the renderer to it. */
+interface PlacedChild {
+    parent: HTMLElement;
+    child: HTMLElement;
+    slot: string;
+}
+
+/** One node that authored `extensions`, kept so {@link mountSharedTree} can hold it too. */
+interface ExtendedNode {
+    el: HTMLElement;
+    node: SharedTreeNode;
+}
+
+/** What one build collects for the checks that can only run once the tree is connected. */
+interface BuildRecord {
+    placed: PlacedChild[];
+    extended: ExtendedNode[];
+}
+
+/**
+ * Whether `member` can be assigned on `el`: the nearest descriptor up the prototype chain is
+ * a writable data property or an accessor WITH a setter. `in` alone answers true for a
+ * getter-only accessor, whose assignment throws in strict code.
+ */
+function isWritable(el: object, member: string): boolean {
+    for (let at: object | null = el; at !== null; at = Object.getPrototypeOf(at) as object | null) {
+        const descriptor = Object.getOwnPropertyDescriptor(at, member);
+        if (descriptor === undefined) continue;
+        return descriptor.set !== undefined || descriptor.writable === true;
+    }
+    return false;
+}
+
+/**
+ * A `SharedTreeNode`, realised as a DETACHED element tree: a tag, its authored properties as
+ * attributes, its style classes as classes, its extensions (ADR 0072) as the markup the element
+ * reads, its placement as `slot=`, its children, in that order — recursive and total,
+ * no tag list, no per-block case. A boolean authored property is the ATTRIBUTE'S PRESENCE
+ * (`toggleAttribute`), which is what every element in the corpus reads
+ * (`hasAttribute('revealed')`, `hasAttribute('expanded')`); spelling `"true"` would set a
+ * present attribute for `false` as well.
+ *
+ * EXCEPT AN AUTHORED `false` ON A PROPERTY THE ELEMENT DECLARES. Absence cannot say `false`
+ * where the GTK default is TRUE — `AdwNavigationPage:can-pop`, `GtkActionBar:revealed` —
+ * because those elements read an absent attribute as that default, so `can-pop: false`
+ * reached the page as `can-pop` unset and the page stayed poppable. The element's own
+ * property setter knows its attribute convention, so an authored `false` is written
+ * through it when the element (already upgraded: `createElement` of a defined tag
+ * constructs it) declares one; everything else keeps the presence rule. "Declares" means a
+ * member it can WRITE ({@link isWritable}): a getter-only accessor of the same name — the
+ * split button's and the menu button's read-only `active` — would throw a bare `TypeError`
+ * out of the assignment, so such a property falls back to the presence rule too.
+ *
+ * THE SLOT IS WRITTEN AS THE ATTRIBUTE THIS RENDERER ALREADY ROUTES ON, not translated:
+ * `src/slotted-children.ts` reads `slot=` off every light-DOM child and keeps the routing
+ * live. This builder read `tag`, `props` and `children` and dropped `slot` silently until a
+ * real `.blp` authored one — the `[top]` header bar landed in `adw-toolbar-view-content` and
+ * the window title was then discarded by `<adw-header-bar>`'s own build, at exit 0.
+ *
+ * NOT YET LIVE — see the file header. Nothing here has run `connectedCallback` until
+ * something connects it: {@link mountSharedTree} for the common case, or a caller's own
+ * container. A DETACHED build therefore cannot check a slot either: an element that has not
+ * upgraded has declared no slots yet, so the refusal below belongs to the mount.
+ */
+export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = { placed: [], extended: [] }): HTMLElement {
+    const el = document.createElement(hostTagOf(node.tag));
+    // The id is how the TypeScript beside a `.blp` reaches this element
+    // (`root.querySelector('#…')`), the counterpart of `InternalChildren` on GTK.
+    if (node.id !== undefined) el.id = node.id;
+    for (const [prop, value] of Object.entries(node.props ?? {})) {
+        const member = propertyOf(prop);
+        if (value === false && isWritable(el, member)) (el as unknown as Record<string, unknown>)[member] = false;
+        else if (typeof value === 'boolean') el.toggleAttribute(attributeOf(prop), value);
+        else el.setAttribute(attributeOf(prop), String(value));
+        // A margin is also inline style (`GTK_WIDGET_MARGIN_CSS` says why); the attribute
+        // stays, since it is what the tree authored and what a reader of the DOM looks for.
+        const margin = GTK_WIDGET_MARGIN_CSS[attributeOf(prop)];
+        if (margin !== undefined) el.style.setProperty(margin, `${Number(value)}px`);
+    }
+    // `styleClasses` is `GtkWidget:css-classes`, and this renderer's door for it is the
+    // `class` attribute — what `.title-1`, `.dimmed` and `.card` select on. Unread, a
+    // `.blp`'s `styles ["title-1"]` reached the tree and never the page.
+    if (node.styleClasses !== undefined && node.styleClasses.length > 0) el.classList.add(...node.styleClasses);
+    writeExtensions(el, node);
+    if (node.extensions !== undefined) record.extended.push({ el, node });
+    for (const child of node.children ?? []) {
+        const childEl = buildSharedTree(child, record);
+        if (child.slot !== undefined) {
+            childEl.setAttribute('slot', child.slot);
+            record.placed.push({ parent: el, child: childEl, slot: child.slot });
+        }
+        el.append(childEl);
+    }
+    return el;
+}
+
+/**
+ * ADR 0072's `extensions`, written in the markup this package already reads for each.
+ *
+ * `strings` is the `strings` attribute, a JSON array — `Gtk.StringList:strings` is a real
+ * property, and JSON is how `model` is written on the two elements that take the list (see
+ * `string-list-slot.ts`). `responses` are `<adw-alert-response>` children, the markup
+ * spelling of GtkBuilder's `<response>` that `<adw-alert-dialog>` consumes at connect. A
+ * translatable string is written as its source text: no renderer here translates, and the
+ * marking stays on the tree for whoever extracts it.
+ */
+function writeExtensions(el: HTMLElement, node: SharedTreeNode): void {
+    const strings = node.extensions?.strings;
+    if (strings !== undefined) el.setAttribute('strings', JSON.stringify(strings.map((string) => string.value)));
+    for (const response of node.extensions?.responses ?? []) {
+        const responseEl = document.createElement('adw-alert-response');
+        responseEl.id = response.id;
+        if (response.appearance !== undefined) responseEl.setAttribute('appearance', response.appearance);
+        if (response.enabled === false) responseEl.setAttribute('enabled', 'false');
+        responseEl.textContent = response.label;
+        el.append(responseEl);
+    }
+}
+
+/** 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;
+}
+
+/**
+ * An extension the realised element did not take is refused, after connect, like a slot.
+ *
+ * Both doors are markup the ELEMENT consumes, so writing them proves nothing: an element that
+ * has no `model` slot, or is not a dialog, leaves the list or the responses where the builder
+ * put them, and the widget renders empty at exit 0. So each is read back off the element. A
+ * string list must have been consumed (it is data and leaves the tree when taken); every
+ * response must be registered with the label, appearance and enabled state the tree authored.
+ */
+function refuseUnheldExtensions(extended: readonly ExtendedNode[]): void {
+    for (const { el, node } of extended) {
+        if (node.extensions?.strings !== undefined && el.isConnected) {
+            const parent = el.parentElement?.localName ?? 'nothing';
+            throw new Error(
+                `<${parent}> did not take the <${el.localName}> authored at "${el.getAttribute('slot') ?? ''}", so ` +
+                    `its ${node.extensions.strings.length} string(s) reach no list.`,
+            );
+        }
+        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);
+            if (!held) {
+                throw new Error(
+                    `<${el.localName}> did not register the response "${response.id}" as authored, so the ` +
+                        'dialog would show without it.',
+                );
+            }
+        }
+    }
+}
+
+/**
+ * A placement the element has no destination for is refused BY NAME, after connect.
+ *
+ * `bindSlottedChildren` copies the NATIVE assignment algorithm — an unmatched `slot=` name
+ * is assigned nowhere and the child visibly stays put — which is right for hand-written
+ * markup and is not a report. An authored tree is a claim about where a widget goes, so the
+ * builder that realises one has to say when the renderer could not honour it; a widget
+ * silently left beside its destination is the defect this whole path was measured on.
+ *
+ * The element's own `slots` declaration is the answer, never a list kept here: an element
+ * that binds a slot enrols itself in this refusal, and one that stops binding drops out of
+ * it visibly.
+ *
+ * AN ELEMENT THIS PACKAGE DOES NOT DEFINE IS NOT REFUSED, and that exemption is narrow on
+ * purpose. An undefined element has exactly ONE destination — itself — so a placement
+ * cannot land anywhere but where the tree authored it; what such a tree is really missing
+ * is the WIDGET, which is a wider gap than a slot and not this refusal's claim to make.
+ * (`AdwApplicationWindow` is the live case: a real `.blp` roots at one and this package has
+ * no element for it.) A DEFINED element that routes no named slot is refused like any
+ * other: it built a structure and chose not to route into it, so a name it does not have
+ * would leave the child beside that structure.
+ */
+function refuseUnknownSlots(placed: readonly PlacedChild[]): void {
+    for (const { parent, child, slot } of placed) {
+        if (customElements.get(parent.localName) === undefined) continue;
+        const binding = slottedChildrenOf(parent);
+        const known = (binding?.slots ?? []).map((declared) => declared.name).filter((name) => name !== undefined);
+        if (known.includes(slot)) continue;
+        throw new Error(
+            `<${parent.localName}> has no slot "${slot}", so the authored <${child.localName}> has nowhere ` +
+                `to go. Known slots: ${known.length > 0 ? known.join(', ') : 'none — it routes no named slot'}.`,
+        );
+    }
+}
+
+/** A tree {@link mountSharedTree} built and connected. */
+export interface MountedSharedTree {
+    /** The authored root — connected, so every custom element under it has upgraded and run. */
+    root: HTMLElement;
+    /** Disconnects and discards the mount point. */
+    unmount: () => void;
+}
+
+/**
+ * {@link buildSharedTree}, attached under a fresh host `<div>` in `document.body` so the tree
+ * — and every custom element in it — is REAL rather than merely constructed. This is the
+ * instantiation half a caller reading the corpus's elements normally wants; a bare
+ * `buildSharedTree` is for a caller that already has somewhere of its own to attach it.
+ */
+export function mountSharedTree(node: SharedTreeNode): MountedSharedTree {
+    const host = document.createElement('div');
+    const record: BuildRecord = { placed: [], extended: [] };
+    host.append(buildSharedTree(node, record));
+    document.body.append(host);
+    // After the append, because that is what upgrades the elements and runs the binds the
+    // refusal reads; before the return, because a caller handed a tree back has no way left
+    // to tell a placement that was honoured from one that was dropped.
+    try {
+        refuseUnknownSlots(record.placed);
+        refuseUnheldExtensions(record.extended);
+    } catch (error) {
+        host.remove();
+        throw error;
+    }
+    return { root: host.firstElementChild as HTMLElement, unmount: () => host.remove() };
+}