@gjsify/adwaita-web 0.54.0 → 0.56.0

package/src/shared-tree-builder.ts

@@ -34,10 +34,23 @@
 // 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 { createBreakpointDriver, parseBreakpointCondition, type BreakpointSize } from '@gjsify/adwaita-core';
+import { assertTreeConstructs, type SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+import {
+    GTK_WIDGET_EXPAND,
+    attributeOf,
+    hostTagOf,
+    isValueBasedBooleanAttr,
+    propertyOf,
+    widgetLengthStyle,
+} from '@gjsify/adwaita-core/tags';
 
+import { observeAdaptiveSize } from './breakpoints.js';
+import { capabilities } from './capabilities.mjs';
+import { dispatchedSignalsOf } from './signals.js';
 import { slottedChildrenOf } from './slotted-children.js';
+import { templateTagFor } from './template-classes.js';
+import { writeBooleanAttribute } from './attributes.js';
 
 /** One authored placement, kept so {@link mountSharedTree} can hold the renderer to it. */
 interface PlacedChild {
@@ -56,6 +69,29 @@ interface ExtendedNode {
 interface BuildRecord {
     placed: PlacedChild[];
     extended: ExtendedNode[];
+    /** Every authored id and the element it built, which a `bind` source is looked up in. */
+    ids: Map<string, HTMLElement>;
+    /** The `bindings` of every node, resolved once every id exists (a source may be built after its target). */
+    binds: PendingBind[];
+    /** The nodes that carry `breakpoints`, wired once every id exists (a setter may name a later sibling). */
+    breakpointHosts: { el: HTMLElement; node: SharedTreeNode }[];
+    /** Undoes what the build wired to the outside (the size observers); {@link mountSharedTree}'s `unmount` runs it. */
+    disposers: (() => void)[];
+    /** The size source a `breakpoints` node is driven from; a `ResizeObserver` unless the caller supplies one. */
+    observeSize?: SizeSource;
+    /** The object a signal handler's NAME is resolved against (ADR 0093 § 3), as `Gtk.BuilderScope` does. */
+    scope?: Readonly<Record<string, unknown>>;
+}
+
+/** Calls `onSize` with the host's measured size, now and on every change; returns its disposer. */
+export type SizeSource = (element: Element, onSize: (size: BreakpointSize) => void) => () => void;
+
+interface PendingBind {
+    el: HTMLElement;
+    property: string;
+    source: string;
+    sourceProperty: string;
+    flags: readonly string[];
 }
 
 /**
@@ -76,21 +112,22 @@ function isWritable(el: object, member: string): boolean {
  * 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.
+ * no tag list, no per-block case.
+ *
+ * BOOLEAN ATTRIBUTES are written per (widget, property), not per attribute name. The same
+ * attribute name (e.g. `revealed`) can be VALUE-BASED for one widget (`gtk-action-bar`,
+ * default TRUE) and PRESENCE-BASED for another (`adw-banner`, default FALSE). The
+ * per-widget map in `@gjsify/adwaita-core/tags` ({@link isValueBasedBooleanAttr}) records this.
  *
- * 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.
+ * - VALUE-BASED: `attr="false"` means false, absent means true (the GTK default).
+ *   The builder writes `attr="true"|"false"` directly via {@link writeBooleanAttribute}.
+ * - PRESENCE-BASED (style classes like `flat`, `round`, `compact`): `toggleAttribute`
+ *   writes the bare attribute for `true`, removes it for `false`.
+ *
+ * EXCEPT an authored `false` on a NON-value-based, WRITABLE property: the property is set
+ * directly (bypassing the attribute) because the element's setter will reflect it correctly.
+ * A getter-only property of the same name (e.g. `AdwSplitButton.active`) falls back to the
+ * presence rule since assignment would throw.
  *
  * 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
@@ -103,29 +140,206 @@ function isWritable(el: object, member: string): boolean {
  * 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));
+export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = newRecord()): HTMLElement {
+    // 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);
+    const root = buildNode(node, record);
+    for (const bind of record.binds) bindProperty(bind, record);
+    for (const host of record.breakpointHosts) bindBreakpoints(host.el, host.node, record);
+    return root;
+}
+
+/** A fresh record, with the scope when the caller has one. */
+function newRecord(scope?: Readonly<Record<string, unknown>>, observeSize?: SizeSource): BuildRecord {
+    return {
+        placed: [],
+        extended: [],
+        ids: new Map(),
+        binds: [],
+        breakpointHosts: [],
+        disposers: [],
+        ...(scope === undefined ? {} : { scope }),
+        ...(observeSize === undefined ? {} : { observeSize }),
+    };
+}
+
+/** What a setter's target held before any breakpoint wrote it: the member's value or the attribute's. */
+type Original = { member: unknown } | { attribute: string | null };
+
+/**
+ * ADR 0093's `breakpoints`: each setter's `object` resolves to the element built for that id and
+ * the write is the one an authored prop takes. The parent's own box is the size source (a
+ * `ResizeObserver`; an Adwaita condition is written against the window, which a page rarely is),
+ * and `adwaita-core` picks the breakpoint and the restores.
+ *
+ * Refused by name, never dropped: a setter whose object is not an id of this tree (`template`
+ * included) and a condition the grammar cannot read, which libadwaita would drop silently.
+ */
+function bindBreakpoints(el: HTMLElement, node: SharedTreeNode, record: BuildRecord): void {
+    const definitions = (node.breakpoints ?? []).map((breakpoint) => {
+        if (parseBreakpointCondition(breakpoint.condition) === null) {
+            throw new Error(
+                `<${el.localName}> \`condition ("${breakpoint.condition}")\` is not an Adwaita breakpoint condition.`,
+            );
+        }
+        return {
+            condition: breakpoint.condition,
+            setters: breakpoint.setters.map((setter) => {
+                const object = record.ids.get(setter.object);
+                if (object === undefined) {
+                    throw new Error(
+                        `<${el.localName}> breakpoint setter \`${setter.object}.${setter.property}\` names no object: ` +
+                            `nothing in this tree has the id '${setter.object}'.`,
+                    );
+                }
+                return { object, property: setter.property, value: setter.value };
+            }),
+        };
+    });
+    const driver = createBreakpointDriver<HTMLElement>(definitions, {
+        read(target, property) {
+            const member = propertyOf(property);
+            const current = (target as unknown as Record<string, unknown>)[member];
+            if (typeof current === 'boolean' && isWritable(target, member))
+                return { member: current } satisfies Original;
+            return { attribute: target.getAttribute(attributeOf(property)) } satisfies Original;
+        },
+        write(target, property, value) {
+            const member = propertyOf(property);
+            if (typeof value === 'object' && value !== null && 'member' in value) {
+                (target as unknown as Record<string, unknown>)[member] = (value as { member: unknown }).member;
+            } else if (typeof value === 'object' && value !== null && 'attribute' in value) {
+                const attribute = (value as { attribute: string | null }).attribute;
+                if (attribute === null) target.removeAttribute(attributeOf(property));
+                else target.setAttribute(attributeOf(property), attribute);
+            } else if (typeof value === 'boolean' && isWritable(target, member)) {
+                (target as unknown as Record<string, unknown>)[member] = value;
+            } else writeProp(target, property, value as string | number | boolean);
+        },
+    });
+    record.disposers.push((record.observeSize ?? observeAdaptiveSize)(el, (size) => driver.evaluate(size)));
+}
+
+/**
+ * ADR 0093's `bindings`, the simple form: the target property takes the source's value now and
+ * again on every `notify::<property>` the source dispatches (`G_BINDING_SYNC_CREATE`, which is
+ * what GtkBuilder's `bind-flags` default means).
+ *
+ * Refused by name, never dropped: a source that is not an id of this tree (`template` included),
+ * a source element that does not dispatch `notify::<property>`, a target without a writable
+ * property, and any flag, which this first slice has not verified. An element dispatches
+ * `notify::…` only while connected, so a tree built but never attached follows once, at build.
+ */
+function bindProperty(bind: PendingBind, record: BuildRecord): void {
+    const { el, property, source, sourceProperty, flags } = bind;
+    const where = `<${el.localName}> \`${property}: bind ${source}.${sourceProperty}\``;
+    const from = record.ids.get(source);
+    if (from === undefined) {
+        throw new Error(`${where} names no object: nothing in this tree has the id '${source}'.`);
+    }
+    if (flags.length > 0) {
+        throw new Error(
+            `${where} carries ${flags.join(', ')}: adwaita-web binds the plain form only until each flag is ` +
+                'verified against GObject.',
+        );
+    }
+    const notification = `notify::${sourceProperty}`;
+    const declared = dispatchedSignalsOf(from);
+    const event = declared[notification];
+    if (event === undefined) {
+        throw new Error(
+            `${where}: <${from.localName}> dispatches no '${notification}', so the target would follow the source ` +
+                `once and never again. It dispatches: ${Object.keys(declared).join(', ') || 'none'}.`,
+        );
+    }
+    const targetMember = propertyOf(property);
+    const sourceMember = propertyOf(sourceProperty);
+    if (!isWritable(el, targetMember)) {
+        throw new Error(`${where}: <${el.localName}> has no writable property '${targetMember}'.`);
+    }
+    const follow = () => {
+        (el as unknown as Record<string, unknown>)[targetMember] = (from as unknown as Record<string, unknown>)[
+            sourceMember
+        ];
+    };
+    follow();
+    from.addEventListener(event, follow);
+}
+
+/**
+ * One authored property, written as the element reads it; a breakpoint setter takes the same door.
+ *
+ * BOOLEAN ATTRIBUTES are written per (widget, property), not per attribute name. The same
+ * attribute name (e.g. `revealed`) can be VALUE-BASED for one widget (`gtk-action-bar`,
+ * default TRUE) and PRESENCE-BASED for another (`adw-banner`, default FALSE). The
+ * per-widget map in `@gjsify/adwaita-core/tags` ({@link isValueBasedBooleanAttr}) records this.
+ *
+ * - VALUE-BASED: `attr="false"` means false, absent means true (the GTK default).
+ *   The builder writes `attr="true"|"false"` directly via {@link writeBooleanAttribute}.
+ * - PRESENCE-BASED (style classes like `flat`, `round`, `compact`): `toggleAttribute`
+ *   writes the bare attribute for `true`, removes it for `false`.
+ *
+ * EXCEPT an authored `false` on a NON-value-based, WRITABLE property: the property is set
+ * directly (bypassing the attribute) because the element's setter will reflect it correctly.
+ * A getter-only property of the same name (e.g. `AdwSplitButton.active`) falls back to the
+ * presence rule since assignment would throw. `hexpand` / `vexpand` keep an authored `false`
+ * as the attribute `"false"` and a later `true` rewrites it — `GTK_WIDGET_EXPAND` says why.
+ */
+export function writeProp(el: HTMLElement, prop: string, value: string | number | boolean): void {
+    const attr = attributeOf(prop);
+    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 (typeof value === 'boolean' && isValueBasedBooleanAttr(el.localName, attr)) {
+        writeBooleanAttribute(el, attr, value);
+    } else if (value === false && isWritable(el, member)) {
+        // Non-value-based, writable property: set the property directly (bypasses attribute).
+        (el as unknown as Record<string, unknown>)[member] = false;
+    } else if (typeof value === 'boolean') {
+        // Presence-based (style classes) or true for non-value-based: use toggleAttribute.
+        el.toggleAttribute(attr, value);
+    } else {
+        el.setAttribute(attr, String(value));
+    }
+    // A margin or a size request 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 length = widgetLengthStyle(attr, value);
+    if (length === undefined) return;
+    if (length[1] === null) el.style.removeProperty(length[0]);
+    else el.style.setProperty(length[0], length[1]);
+}
+
+function buildNode(node: SharedTreeNode, record: BuildRecord): HTMLElement {
+    // An `extern` node is built by the class the application registered under its name (ADR 0093).
+    const el = document.createElement(node.extern === true ? templateTagFor(node.tag) : 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`);
+    if (node.id !== undefined) {
+        el.id = node.id;
+        record.ids.set(node.id, el);
+    }
+    for (const [property, binding] of Object.entries(node.bindings ?? {})) {
+        record.binds.push({
+            el,
+            property,
+            source: binding.source,
+            sourceProperty: binding.property,
+            flags: binding.flags ?? [],
+        });
     }
+    for (const [prop, value] of Object.entries(node.props ?? {})) writeProp(el, prop, value);
+    if (node.breakpoints !== undefined) record.breakpointHosts.push({ el, node });
     // `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);
+    bindSignals(el, node, record);
     if (node.extensions !== undefined) record.extended.push({ el, node });
     for (const child of node.children ?? []) {
-        const childEl = buildSharedTree(child, record);
+        const childEl = buildNode(child, record);
+        if (child.page !== undefined) writePage(el, childEl, child);
         if (child.slot !== undefined) {
             childEl.setAttribute('slot', child.slot);
             record.placed.push({ parent: el, child: childEl, slot: child.slot });
@@ -135,6 +349,43 @@ export function buildSharedTree(node: SharedTreeNode, record: BuildRecord = { pl
     return el;
 }
 
+/**
+ * ADR 0093's `signals`: each handler NAME is looked up on the scope the builder was handed and
+ * listened for as the DOM event the element declares for that GTK signal.
+ *
+ * Refused by name, never dropped: a missing scope or handler (as `Gtk.Builder` refuses one), a
+ * signal the element does not declare, and the `swapped`, `after` and `object` forms, which this
+ * first slice has not verified against GTK's argument order and emission phase.
+ */
+function bindSignals(el: HTMLElement, node: SharedTreeNode, record: BuildRecord): void {
+    const declared = dispatchedSignalsOf(el);
+    for (const signal of node.signals ?? []) {
+        const name = signal.detail === undefined ? signal.name : `${signal.name}::${signal.detail}`;
+        const event = declared[name];
+        if (event === undefined) {
+            throw new Error(
+                `<${el.localName}> declares no signal '${name}', so the handler '${signal.handler}' would never ` +
+                    `run. It dispatches: ${Object.keys(declared).join(', ') || 'none'}.`,
+            );
+        }
+        if (signal.object !== undefined || (signal.flags?.length ?? 0) > 0) {
+            throw new Error(
+                `the handler '${signal.handler}' for '${name}' uses ${signal.object === undefined ? '' : 'an object '}` +
+                    `${(signal.flags ?? []).join(', ')}: adwaita-web binds plain handlers only until each of those ` +
+                    'is verified against GTK.',
+            );
+        }
+        const handler = record.scope?.[signal.handler];
+        if (typeof handler !== 'function') {
+            throw new Error(
+                `the tree binds the handler '${signal.handler}' for '${name}', and the scope ` +
+                    `${record.scope === undefined ? 'was not given (pass `scope`)' : 'has no such function'}.`,
+            );
+        }
+        el.addEventListener(event, (domEvent) => handler.call(record.scope, domEvent));
+    }
+}
+
 /**
  * ADR 0072's `extensions`, written in the markup this package already reads for each.
  *
@@ -217,10 +468,12 @@ function refuseUnheldExtensions(extended: readonly ExtendedNode[]): void {
  * 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.
+ * (It was `AdwApplicationWindow`, which `showcases/gtk/effect-adw-services/src/window.blp`
+ * roots at while this package had no element for it. That element now exists, so the live
+ * case is the opposite one: `<adw-window>` and `<adw-application-window>` both declare
+ * `content`, which is what that file's `content:` becomes.) 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) {
@@ -239,21 +492,37 @@ function refuseUnknownSlots(placed: readonly PlacedChild[]): void {
 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. */
+    /** Disconnects the tree, and discards the mount point when this call made one. */
     unmount: () => void;
 }
 
+/** What {@link mountSharedTree} takes beside the tree. */
+export interface MountOptions {
+    /** 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;
+    /**
+     * Where the root is appended — a showcase's own container, which then lays the window out.
+     * Without it the tree gets a fresh host `<div>` in `document.body`, discarded on `unmount`.
+     */
+    into?: HTMLElement;
+}
+
 /**
  * {@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);
+export function mountSharedTree(node: SharedTreeNode, options: MountOptions = {}): MountedSharedTree {
+    const { into } = options;
+    const host = into ?? document.createElement('div');
+    const record = newRecord(options.scope, options.observeSize);
+    const root = buildSharedTree(node, record);
+    host.append(root);
+    if (into === undefined) document.body.append(host);
+    const discard = () => (into === undefined ? host : root).remove();
     // 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.
@@ -261,8 +530,34 @@ export function mountSharedTree(node: SharedTreeNode): MountedSharedTree {
         refuseUnknownSlots(record.placed);
         refuseUnheldExtensions(record.extended);
     } catch (error) {
-        host.remove();
+        for (const dispose of record.disposers) dispose();
+        discard();
         throw error;
     }
-    return { root: host.firstElementChild as HTMLElement, unmount: () => host.remove() };
+    return {
+        root,
+        unmount: () => {
+            for (const dispose of record.disposers) dispose();
+            discard();
+        },
+    };
+}
+
+/**
+ * A `page` as the attributes `<gtk-notebook>` (`tab-label`) and `<gtk-stack>` (`name`, `title`)
+ * read off their children. Any other parent is refused by name: the attributes would be written
+ * and read by nobody.
+ */
+function writePage(parent: HTMLElement, child: HTMLElement, node: SharedTreeNode): void {
+    const { page } = node;
+    if (parent.localName === 'gtk-notebook') {
+        if (page?.label !== undefined) child.setAttribute('tab-label', page.label);
+    } else if (parent.localName === 'gtk-stack') {
+        if (page?.name !== undefined) child.setAttribute('name', page.name);
+        if (page?.label !== undefined) child.setAttribute('title', page.label);
+    } else {
+        throw new Error(
+            `adwaita-web's shared-tree builder: <${node.tag}> has a page, and <${parent.localName}> has no pages.`,
+        );
+    }
 }

package/src/shared-tree-mount.spec.ts

@@ -0,0 +1,130 @@
+// A showcase window mounted from its tree (ADR 0093): the shape every showcase `.blp` writes — a
+// toggle button and a split view that bind to each other, two breakpoints that collapse the split
+// view, and a window sized by `default-width`. What is held here is the exact cycle the showcases
+// rely on, and `into`, the container a showcase mounts its window in.
+import { describe, expect, it } from '@gjsify/unit';
+import type { SharedTreeNode } from '@gjsify/adwaita-core/conformance';
+
+import { mountSharedTree } from './shared-tree-builder.js';
+
+/** Wait for a ResizeObserver delivery (it runs after layout, before paint). */
+function settle(): Promise<void> {
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+}
+
+/** The showcase window, sized by `default-width` and adapting at 800sp. */
+const tree = (width: number): SharedTreeNode => ({
+    tag: 'AdwApplicationWindow',
+    props: { 'default-width': width, 'default-height': 400 },
+    breakpoints: [
+        {
+            condition: 'max-width: 799sp',
+            setters: [
+                { object: 'splitView', property: 'collapsed', value: true },
+                { object: 'splitView', property: 'show-sidebar', value: false },
+            ],
+        },
+        {
+            condition: 'min-width: 800sp',
+            setters: [
+                { object: 'splitView', property: 'collapsed', value: false },
+                { object: 'splitView', property: 'show-sidebar', value: true },
+            ],
+        },
+    ],
+    children: [
+        {
+            tag: 'GtkBox',
+            slot: 'content',
+            children: [
+                {
+                    tag: 'GtkToggleButton',
+                    id: 'sidebarToggleButton',
+                    bindings: { active: { source: 'splitView', property: 'show-sidebar' } },
+                },
+                {
+                    tag: 'AdwOverlaySplitView',
+                    id: 'splitView',
+                    bindings: { 'show-sidebar': { source: 'sidebarToggleButton', property: 'active' } },
+                    children: [
+                        { tag: 'GtkBox', slot: 'sidebar' },
+                        { tag: 'GtkBox', slot: 'content' },
+                    ],
+                },
+            ],
+        },
+    ],
+});
+
+type SplitView = HTMLElement & { showSidebar: boolean; collapsed: boolean };
+type Toggle = HTMLElement & { active: boolean };
+
+export const AdwSharedTreeMountTest = async () => {
+    await describe('adwaita-web: a showcase window mounted from its tree', async () => {
+        await it('<adw-overlay-split-view> raises notify::show-sidebar once per real change', () => {
+            const view = document.createElement('adw-overlay-split-view') as SplitView;
+            document.body.append(view);
+            const seen: boolean[] = [];
+            view.addEventListener('notify::show-sidebar', (event) => {
+                seen.push((event as CustomEvent<{ showSidebar: boolean }>).detail.showSidebar);
+            });
+            view.showSidebar = true;
+            view.showSidebar = false;
+            view.showSidebar = false;
+            view.showSidebar = true;
+            view.remove();
+            expect(seen).toStrictEqual([false, true]);
+        });
+
+        await it('a wide window keeps the sidebar and the toggle follows the split view', async () => {
+            const { root, unmount } = mountSharedTree(tree(1100));
+            await settle();
+            const split = root.querySelector('#splitView') as SplitView;
+            expect(root.getBoundingClientRect().width).toBe(1100);
+            expect(split.collapsed).toBe(false);
+            expect(split.showSidebar).toBe(true);
+            expect((root.querySelector('#sidebarToggleButton') as Toggle).active).toBe(true);
+            unmount();
+        });
+
+        await it('a narrow window collapses the split view and the toggle follows it', async () => {
+            const { root, unmount } = mountSharedTree(tree(500));
+            await settle();
+            const split = root.querySelector('#splitView') as SplitView;
+            expect(split.collapsed).toBe(true);
+            expect(split.showSidebar).toBe(false);
+            expect((root.querySelector('#sidebarToggleButton') as Toggle).active).toBe(false);
+            unmount();
+        });
+
+        await it('the toggle drives the split view back, and the cycle settles', async () => {
+            const { root, unmount } = mountSharedTree(tree(1100));
+            await settle();
+            const toggle = root.querySelector('#sidebarToggleButton') as Toggle;
+            const split = root.querySelector('#splitView') as SplitView;
+            toggle.active = false;
+            expect(split.showSidebar).toBe(false);
+            split.showSidebar = true;
+            expect(toggle.active).toBe(true);
+            toggle.active = false;
+            toggle.active = true;
+            expect(split.showSidebar).toBe(true);
+            expect(split.getAttribute('show-sidebar')).toBe('');
+            unmount();
+        });
+
+        await it('a tree mounted into a container lives in it, and unmount takes only the tree', () => {
+            const container = document.createElement('div');
+            document.body.append(container);
+            const { root, unmount } = mountSharedTree(tree(1100), { into: container });
+            expect(root.parentElement).toBe(container);
+            expect(container.querySelector('adw-application-window')).toBe(root);
+            unmount();
+            expect(container.childElementCount).toBe(0);
+            expect(container.isConnected).toBe(true);
+            container.remove();
+        });
+    });
+};

package/src/shared-trees.spec.ts

@@ -295,6 +295,21 @@ export const AdwSharedTreesTest = async () => {
             });
         });
 
+        await it('Adw.Banner with revealed: false stays closed — attribute must be absent, not "false"', () => {
+            const tree = blueprintTree(`Adw.Banner {
+                title: "Test";
+                revealed: false;
+            }`);
+            mounted(tree, (root) => {
+                const banner = root as HTMLElement;
+                // The banner reads 'revealed' by PRESENCE (hasAttribute), so the attribute must be absent.
+                // Currently the builder writes revealed="false", which makes hasAttribute return true.
+                expect(banner.hasAttribute('revealed')).toBe(false);
+                expect(banner.classList.contains('revealed')).toBe(false);
+                expect(getComputedStyle(banner).display).toBe('none');
+            });
+        });
+
         await it('an authored false on a getter-only property keeps the presence rule instead of throwing', () => {
             // `<adw-split-button>` exposes `active` as a read-only getter; assigning through it
             // threw a bare TypeError out of the builder before the writability check.

package/src/signals.ts

@@ -0,0 +1,15 @@
+// The GTK signals an element dispatches, and the DOM event each one arrives as (ADR 0093 § 3).
+//
+// A GTK signal name is not a DOM event name — `clicked` is a native `click` here, `notify::active`
+// is a `CustomEvent` of that very name — so a `.blp`'s `clicked => $onClicked()` cannot be wired by
+// the name alone, and an element that dispatches nothing under it must not be wired silently. Each
+// element declares its signals in a `static signals` the way it declares its `slots`, and the
+// builder refuses a signal the element does not declare.
+
+/** GTK signal name → the DOM event type the element dispatches it as. */
+export type DispatchedSignals = Readonly<Record<string, string>>;
+
+/** The signals `el`'s class declares, or none. */
+export function dispatchedSignalsOf(el: Element): DispatchedSignals {
+    return (el.constructor as { signals?: DispatchedSignals }).signals ?? {};
+}

package/src/style-classes.spec.ts

@@ -45,8 +45,10 @@ const SHIPPED = { shipped: true } as const;
 const deprecated = (replacement: string) =>
     ({ shipped: false, reason: `deprecated upstream — use ${replacement}` }) as const;
 
-/** No counterpart in this renderer (yet), with the reason. */
-const unported = (reason: string) => ({ shipped: false, reason }) as const;
+// There is no "no counterpart in this renderer YET" form any more: every class this ledger
+// documents either ships a rule or is deprecated upstream, the last of the unported ones
+// (`.inline`) becoming a rule with `<gtk-text-view>` and `<gtk-search-bar>`. An entry that
+// does need one gets its own form back, with the reason it has no rule.
 
 /**
  * Every class `style-classes.md` documents, and what this package does about it.
@@ -117,12 +119,11 @@ export const DOCUMENTED_STYLE_CLASSES: Record<string, { shipped: boolean; reason
     // Development window
     devel: SHIPPED,
     // Inline
-    inline: unported(
-        'applies to GtkSearchBar, AdwTabBar and GtkTextView. This renderer ports none of ' +
-            'the three — <adw-tab-view> is the tab CONTENT, not AdwTabBar — and upstream ' +
-            'excludes GtkSourceView, which is the one text widget here (<adw-source-view>). ' +
-            'The class ships with the first of those three widgets, not before.',
-    ),
+    // SHIPPED since `<gtk-text-view>` and `<gtk-search-bar>` arrived: upstream applies
+    // `.inline` to GtkTextView (`_views.scss:31-36`) and to GtkSearchBar
+    // (`_toolbars.scss:156-158`), and both elements carry the rule in `scss/_text.scss` and
+    // `scss/_search_bar.scss`. AdwTabBar and GtkSourceView still have no counterpart here.
+    inline: SHIPPED,
     // Undershoot indicators
     'undershoot-top': SHIPPED,
     'undershoot-bottom': SHIPPED,