@gjsify/adwaita-web 0.62.0 → 0.63.0

package/README.md

@@ -130,6 +130,37 @@ auto-dismiss runs on the browser's timers by default; assign
 defines) to drive toast lifetimes from your own clock — that is how the
 package's own regression tests advance time without real timers.
 
+## Pango markup (`use-markup`)
+
+`<adw-banner>`'s `title`, `<adw-alert-dialog>`'s `heading` and `body` and
+`<gtk-label>` / `<gtk-inscription>`'s `markup` read Pango markup — GTK's eleven
+tags (`b`, `i`, `u`, `s`, `tt`, `big`, `small`, `sub`, `sup`, `span`,
+`markup`), `<span>` attributes, and `&amp;`/`&lt;`/`&gt;`/`&quot;`/`&apos;`
+plus numeric character references.
+
+Pango markup is **not** HTML, and nothing here is handed to `innerHTML`:
+`renderPangoMarkup` (in `src/pango-markup.ts`) builds elements and text nodes
+from the tree `parsePangoMarkup` (`@gjsify/adwaita-core`) returns. The banner
+and the alert dialog therefore DRAW the runs:
+
+```html
+<adw-banner title="<b>Metered</b> connection" use-markup revealed></adw-banner>
+```
+
+Anything pango cannot parse comes back as **text**, exactly as
+`gtk_label_set_markup` keeps an unparseable string: a bare `&`, a `<` in prose,
+a mismatched tag — and, importantly, every tag outside pango's set. An
+`<img src=x onerror=…>` in a banner title is shown, not run; there is no code
+path that creates an element for a name the parser did not recognise, and a
+`<span>` attribute becomes a CSS declaration (or is dropped), never a DOM
+attribute.
+
+Without `use-markup` every one of these strings is literal text — that is
+`Adw.Banner:use-markup`'s deliberate departure from the libadwaita default of
+`TRUE`, documented in `src/elements/adw-banner.ts`.
+`scripts/check-adwaita-no-markup-sinks.mjs` holds the no-`innerHTML` rule for
+the package's shipping sources.
+
 ## Theming a page without `<adw-window>`
 
 The components read their colours from the `--window-*` CSS custom properties,

package/lib/types/elements/gtk-window.d.ts

@@ -13,6 +13,12 @@ export declare class GtkWindow extends HTMLElement {
     private _titleLabel;
     /** Watches the strip for an author's titlebar arriving after the build. */
     private _titlebarObserver;
+    /** `is-active` and `focus-widget`; `maximized` stays the attribute above. */
+    private readonly _members;
+    private readonly _closing;
+    private readonly _syncActive;
+    private readonly _onFocusIn;
+    private readonly _onFocusOut;
     static get observedAttributes(): string[];
     /**
      * `Gtk.Window:title` — the window's title.
@@ -54,6 +60,9 @@ export declare class GtkWindow extends HTMLElement {
     private _offByDefault;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private _watchActivity;
+    private _documentIsActive;
+    private _notifyMember;
     /**
      * A `slot="titlebar"` child adopted AFTER the build has to take the strip over from the
      * server-side decoration, and `_render` is the one that notices — nothing else here runs
@@ -90,8 +99,32 @@ export declare class GtkWindow extends HTMLElement {
      * it, hide the window when `hide-on-close` is set and DESTROY it otherwise. "Destroy" is
      * the one word this port cannot mean — a page has no unref — so the default detaches the
      * frame, which is the same observable outcome for everything above it.
+     *
+     * A frame that is not in the page is not realized, so there is nothing to close; a listener
+     * that calls `close()` again is ignored, as GTK ignores it. Answers whether the window went
+     * away (hidden or detached), `false` when a listener took the request over or it was ignored.
      */
     close(): boolean;
+    /**
+     * `gtk_window_present`: show the frame. GTK also raises and focuses the toplevel, which is
+     * the window manager's to grant; a page owns no such surface, so this is only the first half.
+     */
+    present(): void;
+    /** `Gtk.Window:is-active` — see the header: the document's focus, while this frame is shown. */
+    get isActive(): boolean;
+    /** `gtk_window_is_active`. */
+    is_active(): boolean;
+    /** `Gtk.Window:focus-widget`, read live from the document. */
+    get focusWidget(): Element | null;
+    /** `gtk_window_get_focus`: the element inside the frame that has focus, or `null`. */
+    get_focus(): Element | null;
+    /**
+     * `gtk_window_set_focus`. `null` clears the focus. An element outside the frame is refused:
+     * GTK's window only focuses its own descendants.
+     */
+    set_focus(widget: Element | null): void;
+    /** `gtk_window_is_maximized`: the FRAME's state, not the browser window's. */
+    is_maximized(): boolean;
     /**
      * `gtk_window_maximize`. ASYNCHRONOUS in GTK — the GIR says so at gtkwindow.c:1044 — so
      * the property is the thing a caller watches, and this writes it directly rather than

package/lib/types/pango-markup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Render Pango markup into `target`, replacing its content — the one door every
+ * `use-markup` surface in this package goes through.
+ *
+ * The `null` branch is the C fallback and is the SECURITY property: markup that does not
+ * parse is written as TEXT, so an unrecognised tag can never become an element. Callers
+ * that want markup only when a caller has asked for it read that from their own flag and
+ * pass plain text here — this function never decides whether markup is meant.
+ */
+export declare function renderPangoMarkup(target: HTMLElement, markup: string): void;

package/lib/types/pango-markup.spec.d.ts

@@ -0,0 +1 @@
+export declare const PangoMarkupTest: () => Promise<void>;

package/lib/types/source-view/copy-glyph.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A recognisable copy glyph rendered inline so the opt-in `source-view` subpath needs no
+ * icon CSS. `doc` is a parameter so a caller outside the main document (a shadow root in
+ * another frame) gets nodes its own tree can adopt.
+ */
+export declare function createCopyGlyph(doc?: Document): SVGSVGElement;

package/lib/types/source-view/copy-glyph.spec.d.ts

@@ -0,0 +1 @@
+export declare const CopyGlyphTest: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-web",
-    "version": "0.62.0",
+    "version": "0.63.0",
     "description": "Adwaita/Libadwaita web components for browser targets",
     "type": "module",
     "main": "./src/index.ts",
@@ -58,14 +58,14 @@
         "@codemirror/language": "^6.12.4",
         "@codemirror/state": "^6.7.0",
         "@codemirror/view": "^6.43.4",
-        "@gjsify/adwaita-core": "^0.62.0",
-        "@gjsify/adwaita-fonts": "^0.62.0",
-        "@gjsify/adwaita-icons": "^0.62.0",
-        "@gjsify/gtksource-core": "^0.62.0",
+        "@gjsify/adwaita-core": "^0.63.0",
+        "@gjsify/adwaita-fonts": "^0.63.0",
+        "@gjsify/adwaita-icons": "^0.63.0",
+        "@gjsify/gtksource-core": "^0.63.0",
         "@lezer/highlight": "^1.2.3"
     },
     "peerDependencies": {
-        "@gjsify/app-settings": "^0.62.0"
+        "@gjsify/app-settings": "^0.63.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/app-settings": {
@@ -73,11 +73,11 @@
         }
     },
     "devDependencies": {
-        "@gjsify/app-settings": "^0.62.0",
-        "@gjsify/blueprint": "^0.62.0",
-        "@gjsify/cli": "^0.62.0",
-        "@gjsify/unit": "^0.62.0",
-        "@gjsify/vite-plugin-blueprint": "^0.62.0",
+        "@gjsify/app-settings": "^0.63.0",
+        "@gjsify/blueprint": "^0.63.0",
+        "@gjsify/cli": "^0.63.0",
+        "@gjsify/unit": "^0.63.0",
+        "@gjsify/vite-plugin-blueprint": "^0.63.0",
         "sass": "^1.101.0",
         "typescript": "^6.0.3"
     },

package/src/application.spec.ts

@@ -63,6 +63,39 @@ export const ApplicationTest = async () => {
         await it('Adw.Application is a Gtk.Application', () => {
             expect(Adw.Application.prototype instanceof Gtk.Application).toBe(true);
         });
+        await it('a keydown in the window runs the accelerator, with its target', () => {
+            const app = new Adw.Application({ application_id: 'org.gjsify.vec.WebAccel' });
+            const window = scene.window(app as never) as Element;
+            const hits: unknown[] = [];
+            for (const [owner, name] of [
+                [app, 'save'],
+                [window, 'open'],
+                [app, 'view'],
+            ] as const) {
+                const action = new Gio.SimpleAction({ name });
+                action.connect('activate', (_a: unknown, parameter: unknown) => hits.push([name, parameter ?? null]));
+                (owner as unknown as { add_action(a: object): void }).add_action(action);
+            }
+            app.set_accels_for_action('app.save', ['<Primary>s']);
+            app.set_accels_for_action('win.open', ['<Primary><Shift>o']);
+            app.set_accels_for_action('app.view::list', ['<Primary>l']);
+            const press = (init: KeyboardEventInit): boolean => {
+                const event = new KeyboardEvent('keydown', { bubbles: true, cancelable: true, ...init });
+                window.dispatchEvent(event);
+                return event.defaultPrevented;
+            };
+            expect(press({ key: 's', ctrlKey: true })).toBe(true);
+            expect(press({ key: 'O', ctrlKey: true, shiftKey: true })).toBe(true);
+            expect(press({ key: 'l', ctrlKey: true })).toBe(true);
+            expect(press({ key: 's' })).toBe(false);
+            expect(hits).toStrictEqual([
+                ['save', null],
+                ['open', null],
+                ['view', 'list'],
+            ]);
+            (window as unknown as { application: object | null }).application = null;
+            expect(press({ key: 's', ctrlKey: true })).toBe(false);
+        });
         await it('quit() takes the windows it added off the page', async () => {
             const app = new Adw.Application({ application_id: 'org.gjsify.vec.WebQuit' });
             const window = scene.window(app as never) as Element;

package/src/application.ts

@@ -11,6 +11,7 @@ import {
     activateWidgetAction as activateIn,
     activateMenuItem,
     applicationOfWindow,
+    dispatchAccelerator,
     menuActionsFor,
     installActionMap,
     type AdwMenuItem,
@@ -18,6 +19,7 @@ import {
     type AdwMenuModel,
     type ApplicationHost,
 } from '@gjsify/adwaita-core';
+import { webPlatformHost } from './platform-host.js';
 
 export const webHost: ApplicationHost = {
     name: 'adwaita-web',
@@ -70,6 +72,19 @@ export class AdwApplication extends GtkApplication {}
 
 type WindowApplication = { add_window(window: object): void; remove_window(window: object): void };
 
+const ACCEL_LISTENERS = new WeakMap<object, () => void>();
+
+/** Key presses in a window of an application run its accelerators; keydown of descendants bubbles here. */
+function followAccelerators(window: object, application: WindowApplication | null): void {
+    ACCEL_LISTENERS.get(window)?.();
+    ACCEL_LISTENERS.delete(window);
+    if (application === null) return;
+    ACCEL_LISTENERS.set(
+        window,
+        webPlatformHost.listenKeys(window, (event) => dispatchAccelerator(window, event, parentOfElement)),
+    );
+}
+
 /**
  * `Gtk.Window:application` and the window's `Gio.ActionMap` (`win.` actions) on an element class.
  * Setting the property is `add_window`, as on GTK; setting it to `null` is `remove_window`.
@@ -87,6 +102,7 @@ export function defineWindowApplication(proto: object): void {
             if (current === value) return;
             current?.remove_window(this);
             value?.add_window(this);
+            followAccelerators(this, value);
         },
     });
 }

package/src/elements/adw-alert-dialog.ts

@@ -25,9 +25,11 @@
 // `Adw.AlertDialog:heading-use-markup` and `:body-use-markup` both default to FALSE
 // (`Adw.Banner:use-markup` is the one that defaults to TRUE, which is why
 // `adw-banner.ts` documents a deliberate departure and this file does not need to).
-// Opting in renders through `innerHTML`, which is the author asserting the string is
-// trusted — Pango markup has a fixed tag set and no scripting, HTML has neither
-// property.
+// Opting in renders PANGO MARKUP through `renderPangoMarkup`: the string is PARSED by
+// `@gjsify/adwaita-core` and turned into nodes one at a time, never handed to
+// `innerHTML`. So opting in is no longer an assertion that the string is trusted —
+// `<b>` is drawn bold whether or not the author vouched for it, and a tag pango does
+// not know comes back as text.
 //
 // Buttons are stacked vertically by default (the Adw.AlertDialog default at medium
 // sizes) and laid out horizontally when prefer-wide-layout is set and there are no more
@@ -56,6 +58,7 @@
 import { AdwAlertResponses } from '@gjsify/adwaita-core';
 import type { AdwResponseAppearance } from '@gjsify/adwaita-core';
 
+import { renderPangoMarkup } from '../pango-markup.js';
 import { bindEmptySections } from '../empty-sections.js';
 import { bindSlottedChildren } from '../slotted-children.js';
 import { AdwModalSurface } from './modal-surface.js';
@@ -463,12 +466,12 @@ export class AdwAlertDialog extends HTMLElement {
         this.classList.toggle('open', this.open);
 
         const heading = this.heading;
-        if (this.headingUseMarkup) this._headingEl.innerHTML = heading;
+        if (this.headingUseMarkup) renderPangoMarkup(this._headingEl, heading);
         else this._headingEl.textContent = heading;
         this._headingEl.hidden = heading.length === 0;
 
         const body = this.body;
-        if (this.bodyUseMarkup) this._bodyEl.innerHTML = body;
+        if (this.bodyUseMarkup) renderPangoMarkup(this._bodyEl, body);
         else this._bodyEl.textContent = body;
         this._bodyEl.hidden = body.length === 0;
 

package/src/elements/adw-banner.ts

@@ -20,6 +20,8 @@ import {
     parseBannerButtonStyle,
 } from '@gjsify/adwaita-core';
 
+import { renderPangoMarkup } from '../pango-markup.js';
+
 export class AdwBanner extends HTMLElement {
     private _titleEl!: HTMLSpanElement;
     private _button!: HTMLButtonElement;
@@ -52,17 +54,20 @@ export class AdwBanner extends HTMLElement {
 
     private _render() {
         const title = this.getAttribute('title') ?? '';
-        // DELIBERATE DEPARTURE FROM THE C DEFAULT. `Adw.Banner:use-markup`
-        // defaults to TRUE and `@gjsify/adwaita-core`
-        // carries that as the spec value — but Pango markup is not HTML. Pango
-        // has a fixed tag set and no scripting; `innerHTML` will run an
-        // `onerror` handler. Adopting the C default here would turn every
-        // `title` attribute into an injection sink for a widget that is not one
-        // in GTK, so on this renderer markup is OPT-IN and the default is text.
-        // The opt-in is the developer asserting the title is trusted.
+        // DELIBERATE DEPARTURE FROM THE C DEFAULT, and the departure is now about
+        // SAFETY rather than about how markup is spelt. `Adw.Banner:use-markup`
+        // defaults to TRUE and `@gjsify/adwaita-core` carries that as the spec
+        // value — but a `title` attribute is an ATTRIBUTE, and a renderer that
+        // parsed it as markup would be one an author (or an injected value) could
+        // drive. Adopting the C default here would make every banner title markup
+        // by default for a widget that is not one in GTK, so on this renderer
+        // markup is OPT-IN and the default is text.
+        // Opting in renders PANGO markup — parsed by `renderPangoMarkup`, never
+        // handed to `innerHTML`, so nothing the title carries can become a node
+        // beyond the eleven tags pango itself knows.
         // The title label carries `use-underline=False` in the template
         //, so its underscores are literal — no stripping here.
-        if (this.hasAttribute('use-markup')) this._titleEl.innerHTML = title;
+        if (this.hasAttribute('use-markup')) renderPangoMarkup(this._titleEl, title);
         else this._titleEl.textContent = title;
 
         // `label && label[0]` — a first-character test, so a label of

package/src/elements/gtk-window.ts

@@ -47,7 +47,7 @@
 // difference a reader of the DOM can see.
 //
 // NOT PORTED, and why — these are the KNOWN_GAPS of this element:
-//   `application`, `child`, `default-widget`, `display`, `focus-widget` — WIDGET- or
+//   `application`, `child`, `default-widget`, `display` — WIDGET- or
 //     DISPLAY-typed, so a slot or an id here rather than an attribute; `child` and
 //     `titlebar` ARE slots and `transient-for` only has to be PRESENT.
 //   `destroy-with-parent` — a DOM node has no destroy, and a page has no parent to destroy.
@@ -59,15 +59,32 @@
 //     business and needs the `Gio.MenuModel` it is built from (:1150).
 //   `startup-id` — write-only, and written by the launcher that started the application (:883).
 //
+// THE STATE MEMBERS, and what each is in a page (the shared rules — notify only on change, the
+// close sequence — live in `@gjsify/adwaita-core`'s `window-members.ts`):
+//   `is-active`    — the DOCUMENT has focus and this frame is connected and shown. A page has one
+//                    focus for all its windows, so every shown frame is active together; that is
+//                    the honest limit of a frame (`document.hasFocus()`, window focus/blur and
+//                    `visibilitychange` feed it). Read-only, as in GTK.
+//   `focus-widget` — the element inside the frame that holds `document.activeElement`, live.
+//                    `set_focus(el)` calls `el.focus()` and refuses an element outside the frame;
+//                    `set_focus(null)` blurs. `focusin`/`focusout` notify; focus that merely
+//                    leaves with the window (blur) keeps its widget, as GTK keeps it.
+//   `maximized`    — the FRAME's state (square corners), not the browser window's: a page cannot
+//                    maximize its browser window. `is_maximized()` reads it.
+//   `present()`    — un-hides the frame; a page cannot raise or focus a window it does not own.
+//
 // Events: `notify::<prop>` (CustomEvent, bubbles, detail `{ <prop>: value }`) on every real
-// change, and `close-request` (CustomEvent, bubbles, CANCELLED, no detail), which is
-// `Gtk.Window::close-request`.
+// change, and `close-request` (CustomEvent, bubbles, CANCELLABLE, no detail), which is
+// `Gtk.Window::close-request`: a listener that calls `preventDefault()` is a GTK handler that
+// returns true. `window.close()` runs it through `CloseRequestState`.
 //
 // Reference: refs/gtk/gtk/gtkwindow.c
 // Reference: refs/libadwaita/src/stylesheet/widgets/_window.scss (GtkWindow)
 // Copyright (c) The GTK Team. LGPLv2.1+.
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
+import { CloseRequestState, WindowMemberState, type WindowMemberProperty } from '@gjsify/adwaita-core';
+
 import { bindSlottedChildren, type AdwSlot } from '../slotted-children.js';
 
 // Registers <gtk-window-controls>: a frame with no titlebar of its own draws the two of them
@@ -88,6 +105,20 @@ export class GtkWindow extends HTMLElement {
     private _titleLabel: HTMLElement | null = null;
     /** Watches the strip for an author's titlebar arriving after the build. */
     private _titlebarObserver: MutationObserver | null = null;
+    /** `is-active` and `focus-widget`; `maximized` stays the attribute above. */
+    private readonly _members = new WindowMemberState<Element>((property) => this._notifyMember(property));
+    private readonly _closing = new CloseRequestState();
+    private readonly _syncActive = (): void => void this._members.reportActive(this._documentIsActive());
+    private readonly _onFocusIn = (event: FocusEvent): void => {
+        if (event.target instanceof Element) this._members.reportFocus(event.target);
+    };
+    private readonly _onFocusOut = (event: FocusEvent): void => {
+        const next = event.relatedTarget;
+        if (next instanceof Node && this.contains(next)) return;
+        // Focus leaving WITH the window (tab switch, another app) keeps the widget; GTK does too.
+        if (next === null && !document.hasFocus()) return;
+        this._members.reportFocus(null);
+    };
 
     static get observedAttributes() {
         return [
@@ -103,6 +134,8 @@ export class GtkWindow extends HTMLElement {
             'resizable',
             'title',
             'transient-for',
+            // Not a window property: `is-active` depends on it, so it is watched but never notified.
+            'hidden',
         ];
     }
 
@@ -186,11 +219,13 @@ export class GtkWindow extends HTMLElement {
 
     connectedCallback() {
         if (this._initialized) {
+            this._watchActivity();
             this._watchTitlebar();
             this._render();
             return;
         }
         this._initialized = true;
+        this._watchActivity();
 
         this._titlebar = document.createElement('div');
         this._titlebar.className = 'adw-gtk-window-titlebar';
@@ -216,6 +251,37 @@ export class GtkWindow extends HTMLElement {
     disconnectedCallback() {
         this._titlebarObserver?.disconnect();
         this._titlebarObserver = null;
+        window.removeEventListener('focus', this._syncActive);
+        window.removeEventListener('blur', this._syncActive);
+        document.removeEventListener('visibilitychange', this._syncActive);
+        this.removeEventListener('focusin', this._onFocusIn);
+        this.removeEventListener('focusout', this._onFocusOut);
+        // An unmapped window is neither active nor holding focus.
+        this._members.reportActive(false);
+        this._members.reportFocus(null);
+    }
+
+    private _watchActivity(): void {
+        window.addEventListener('focus', this._syncActive);
+        window.addEventListener('blur', this._syncActive);
+        document.addEventListener('visibilitychange', this._syncActive);
+        this.addEventListener('focusin', this._onFocusIn);
+        this.addEventListener('focusout', this._onFocusOut);
+        this._syncActive();
+    }
+
+    private _documentIsActive(): boolean {
+        return this.isConnected && !this.hidden && document.visibilityState !== 'hidden' && document.hasFocus();
+    }
+
+    private _notifyMember(property: WindowMemberProperty): void {
+        const detail =
+            property === 'is-active'
+                ? this._members.active
+                : property === 'focus-widget'
+                  ? this._members.focus
+                  : this.maximized;
+        this.dispatchEvent(new CustomEvent(`notify::${property}`, { bubbles: true, detail: { [property]: detail } }));
     }
 
     /**
@@ -248,8 +314,13 @@ export class GtkWindow extends HTMLElement {
     }
 
     attributeChangedCallback(name: string) {
-        if (!this._initialized) return;
-        this._render();
+        if (name === 'hidden') {
+            this._syncActive();
+            return;
+        }
+        // Before the first connect there is nothing to draw, but the property still moved: GTK
+        // notifies a window that was never mapped, and a listener on a detached frame hears it.
+        if (this._initialized) this._render();
         this.dispatchEvent(
             new CustomEvent(`notify::${name}`, { bubbles: true, detail: { [name]: this._property(name) } }),
         );
@@ -344,14 +415,78 @@ export class GtkWindow extends HTMLElement {
      * it, hide the window when `hide-on-close` is set and DESTROY it otherwise. "Destroy" is
      * the one word this port cannot mean — a page has no unref — so the default detaches the
      * frame, which is the same observable outcome for everything above it.
+     *
+     * A frame that is not in the page is not realized, so there is nothing to close; a listener
+     * that calls `close()` again is ignored, as GTK ignores it. Answers whether the window went
+     * away (hidden or detached), `false` when a listener took the request over or it was ignored.
      */
     close(): boolean {
-        const request = new CustomEvent('close-request', { bubbles: true, cancelable: true });
-        this.dispatchEvent(request);
-        if (request.defaultPrevented) return false;
-        if (this._offByDefault('hide-on-close')) this.hidden = true;
-        else this.remove();
-        return true;
+        const outcome = this._closing.close({
+            realized: this.isConnected,
+            hideOnClose: this._offByDefault('hide-on-close'),
+            emit: () => {
+                const request = new CustomEvent('close-request', { bubbles: true, cancelable: true });
+                this.dispatchEvent(request);
+                return request.defaultPrevented;
+            },
+            hide: () => void (this.hidden = true),
+            destroy: () => this.remove(),
+        });
+        return outcome === 'hidden' || outcome === 'destroyed';
+    }
+
+    /**
+     * `gtk_window_present`: show the frame. GTK also raises and focuses the toplevel, which is
+     * the window manager's to grant; a page owns no such surface, so this is only the first half.
+     */
+    present(): void {
+        this.hidden = false;
+    }
+
+    /** `Gtk.Window:is-active` — see the header: the document's focus, while this frame is shown. */
+    get isActive(): boolean {
+        return this._members.active;
+    }
+
+    /** `gtk_window_is_active`. */
+    is_active(): boolean {
+        return this._members.active;
+    }
+
+    /** `Gtk.Window:focus-widget`, read live from the document. */
+    get focusWidget(): Element | null {
+        return this.get_focus();
+    }
+
+    /** `gtk_window_get_focus`: the element inside the frame that has focus, or `null`. */
+    get_focus(): Element | null {
+        const active = document.activeElement;
+        return active !== null && active !== this && this.contains(active) ? active : null;
+    }
+
+    /**
+     * `gtk_window_set_focus`. `null` clears the focus. An element outside the frame is refused:
+     * GTK's window only focuses its own descendants.
+     */
+    set_focus(widget: Element | null): void {
+        if (widget === null) {
+            const current = this.get_focus();
+            if (current instanceof HTMLElement || current instanceof SVGElement) current.blur();
+            this._members.reportFocus(null);
+            return;
+        }
+        if (widget === this || !this.contains(widget)) {
+            throw new Error('<gtk-window>.set_focus: the widget is not inside this window');
+        }
+        if (widget instanceof HTMLElement || widget instanceof SVGElement) widget.focus();
+        // `focus()` fires no focusin while the document itself is unfocused, so report what the
+        // document now says; an equal write is dropped by the state.
+        this._members.reportFocus(this.get_focus());
+    }
+
+    /** `gtk_window_is_maximized`: the FRAME's state, not the browser window's. */
+    is_maximized(): boolean {
+        return this.maximized;
     }
 
     /**