@gjsify/adwaita-app 0.16.5

package/README.md

@@ -0,0 +1,106 @@
+# @gjsify/adwaita-app
+
+Native Adwaita application shell for GJS/GTK apps. It wires the boilerplate every
+native Adwaita app repeats — the `runAsync` lifecycle, the opt-in
+[`@gjsify/devtools`](../devtools) control plane, a startup CSS bootstrap, standard
+`app.quit`/`app.about` actions, a data-driven `Adw.NavigationSplitView` nav shell,
+an async-view mounter, and promise-based dialog/toast/file helpers.
+
+It is **composition-first**: opt-in wiring for the parts that are pure
+boilerplate, never a wrapper that hides `Adw`/`Gtk`. You still write your views as
+plain `Gtk.Widget`s.
+
+> GJS-only (`runtimes.gjs = polyfill`, everything else `none`). Tier 2.
+
+## Install
+
+```bash
+gjsify install @gjsify/adwaita-app
+```
+
+## Quick start
+
+```ts
+import Adw from '@girs/adw-1';
+import { runAdwaitaApp, createNavShell, type NavItem } from '@gjsify/adwaita-app';
+
+const NAV: NavItem[] = [
+    { id: 'overview', label: 'Overview', icon: 'go-home-symbolic' },
+    { id: 'reports', label: 'Reports', icon: 'x-office-spreadsheet-symbolic' },
+];
+
+class MainWindow extends Adw.ApplicationWindow {
+    static { imports.gi.GObject.registerClass({ GTypeName: 'MyMainWindow' }, MainWindow); }
+    constructor(app: Adw.Application) {
+        super({ application: app, defaultWidth: 1000, defaultHeight: 700 });
+        const shell = createNavShell(this, {
+            items: NAV,
+            sidebarTitle: 'My App',
+            onSelect: (item) => shell.stack.set_visible_child_name(item.id),
+        });
+        shell.stack.add_named(buildOverview(), 'overview');
+        shell.stack.add_named(buildReports(), 'reports');
+        this.set_content(shell.widget);
+        shell.selectById('overview');
+    }
+}
+
+await runAdwaitaApp({
+    applicationId: 'org.example.App',
+    createWindow: (app) => new MainWindow(app),
+    css: '/* optional app CSS, loaded display-wide on startup */',
+    about: { applicationName: 'My App', version: '1.0.0', developerName: 'Me' },
+    // devtools omitted → gated on the GJSIFY_DEVTOOLS env var (safe in prod).
+});
+```
+
+`runAdwaitaApp` uses `Adw.Application.runAsync()` — **not** sync `run()` — so a
+synchronous view load does not hang its spinner (GJS does not flush the
+promise-job queue under `run()`).
+
+## API
+
+### Application
+
+- `runAdwaitaApp(options): Promise<number>` — construct + run, resolve with the
+  exit code. `AdwaitaAppOptions`: `applicationId`, `createWindow`, optional
+  `flags`, `css`, `about` (`AboutInfo`), `quitAction` (default on, `<primary>q`),
+  `devtools` (`true` | `InstallDevtoolsOptions` | omitted = env-gated),
+  `onStartup`.
+- `AdwaitaApp` — the configured `Adw.Application` subclass, if you need the
+  instance instead of `runAdwaitaApp`.
+
+### Navigation shell
+
+- `createNavShell(window, options): NavShell` — builds the
+  `Adw.NavigationSplitView` (sidebar `Gtk.ListBox` + content `Gtk.Stack`) into
+  `window` (which owns the responsive `Adw.Breakpoint`, default `max-width: 720px`).
+  Returns `{ widget, stack, contentHeader, selectById, selectByIndex }`.
+- `resolveInitialNavIndex(items, wantedId?)`, `findNavItem(items, id)` — pure
+  helpers (e.g. to turn a `${PREFIX}_VIEW` dev hook into a start index).
+
+### Async view mounting
+
+- `LoadToken` + `loadIntoStack({ stack, token, load, fill, onError? })` — show a
+  loading page, run `load` (sync or async), then `fill` + show content — dropping
+  a result a newer reload superseded, and showing the error page on failure.
+
+### Interaction helpers
+
+- `confirmDialog(parent, { heading, body?, confirmLabel?, cancelLabel?, destructive? }): Promise<boolean>`
+- `errorDialog(parent, heading, body?): Promise<void>`
+- `registerToastOverlay(overlay)` + `showToast(title, timeout?)`
+- `pickFile(parent, { title?, filters? }): Promise<string | null>` /
+  `saveFile(parent, { title?, filters?, initialName? }): Promise<string | null>`
+
+### Dev hooks
+
+- `readAppDevHooks({ prefix, env? }): { view?, file?, debug }` — the
+  `${PREFIX}_VIEW` / `${PREFIX}_FILE` / `${PREFIX}_DEBUG` env pattern (e.g.
+  `MYAPP_VIEW=reports myapp` to open straight to a view in dev).
+
+## See also
+
+- [`@gjsify/devtools`](../devtools) — the DBus control plane wired in on startup.
+- [`@gjsify/storybook`](../storybook) — the component browser this shell was
+  generalized from ([ADR 0009](../../../docs/adr/0009-native-adwaita-app-shell.md)).

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/application.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gdk-4.0";import n from"@girs/gio-2.0";import r from"@girs/gobject-2.0";import i from"@girs/gtk-4.0";import{installDevtools as a}from"@gjsify/devtools";var o=class AdwaitaApp extends e.Application{static{r.registerClass({GTypeName:`GjsifyAdwaitaApp`},AdwaitaApp)}constructor(e){super({application_id:e.applicationId,flags:e.flags??n.ApplicationFlags.DEFAULT_FLAGS}),this._window=null,this._options=e,this._initActions(),this.connect(`startup`,()=>this._onStartup()),this.connect(`activate`,()=>this._onActivate())}_initActions(){if(this._options.quitAction!==!1){let e=new n.SimpleAction({name:`quit`});e.connect(`activate`,()=>this.quit()),this.add_action(e),this.set_accels_for_action(`app.quit`,[`<primary>q`])}if(this._options.about){let e=new n.SimpleAction({name:`about`});e.connect(`activate`,()=>this._showAbout()),this.add_action(e)}}_onStartup(){this._options.css&&this._loadCss(this._options.css),this._installDevtools(),this._options.onStartup?.(this)}_loadCss(e){let n=t.Display.get_default();if(!n){console.error(`@gjsify/adwaita-app: no default display; CSS not applied`);return}let r=new i.CssProvider;r.load_from_string(e),i.StyleContext.add_provider_for_display(n,r,i.STYLE_PROVIDER_PRIORITY_APPLICATION)}_installDevtools(){let e=this._options.devtools;if(e===!1)return;let t=typeof e==`object`?e:{enabled:e||void 0};a(this,t)}_onActivate(){this._window||=this._options.createWindow(this),this._window.present()}_showAbout(){let t=this._options.about;if(!t)return;let n=new e.AboutDialog({application_name:t.applicationName,application_icon:t.applicationIcon??this._options.applicationId});t.version&&(n.version=t.version),t.developerName&&(n.developer_name=t.developerName),t.website&&(n.website=t.website),t.issueUrl&&(n.issue_url=t.issueUrl),t.license&&(n.license=t.license),t.comments&&(n.comments=t.comments),t.copyright&&(n.copyright=t.copyright),t.developers?.length&&n.set_developers(t.developers),n.present(this.get_active_window())}};async function runAdwaitaApp(e){return new o(e).runAsync([imports.system.programInvocationName,...ARGV])}r.type_ensure(o.$gtype);export{o as AdwaitaApp,runAdwaitaApp};

package/lib/esm/dev-hooks.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function isTruthy(e){if(e==null||e===``)return!1;let t=e.toLowerCase();return t!==`0`&&t!==`false`&&t!==`no`}function readAppDevHooks(e){let t=e.env??globalThis.process?.env??{},n=e.prefix;return{view:t[`${n}_VIEW`]||void 0,file:t[`${n}_FILE`]||void 0,debug:isTruthy(t[`${n}_DEBUG`])}}export{readAppDevHooks};

package/lib/esm/dialogs.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";function confirmDialog(t,n){return new Promise(r=>{let i=new e.AlertDialog({heading:n.heading,body:n.body??``});i.add_response(`cancel`,n.cancelLabel??`Cancel`),i.add_response(`confirm`,n.confirmLabel??`OK`),i.set_response_appearance(`confirm`,n.destructive?e.ResponseAppearance.DESTRUCTIVE:e.ResponseAppearance.SUGGESTED),i.set_default_response(`confirm`),i.set_close_response(`cancel`),i.connect(`response`,(e,t)=>r(t===`confirm`)),i.present(t)})}function errorDialog(t,n,r){return new Promise(i=>{let a=new e.AlertDialog({heading:n,body:r??``});a.add_response(`ok`,`OK`),a.set_default_response(`ok`),a.set_close_response(`ok`),a.connect(`response`,()=>i()),a.present(t)})}export{confirmDialog,errorDialog};

package/lib/esm/file-dialog.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/gio-2.0";import t from"@girs/gtk-4.0";function buildFilters(n){if(!n?.length)return;let r=new e.ListStore({itemType:t.FileFilter.$gtype});for(let e of n){let n=new t.FileFilter;n.set_name(e.name);for(let t of e.patterns??[])n.add_pattern(t);for(let t of e.mimeTypes??[])n.add_mime_type(t);r.append(n)}return r}function pickFile(e,n={}){return new Promise(r=>{let i=new t.FileDialog({title:n.title??`Open File`}),a=buildFilters(n.filters);a&&i.set_filters(a),i.open(e,null,(e,t)=>{try{r(i.open_finish(t)?.get_path()??null)}catch{r(null)}})})}function saveFile(e,n={}){return new Promise(r=>{let i=new t.FileDialog({title:n.title??`Save File`});n.initialName&&i.set_initial_name(n.initialName);let a=buildFilters(n.filters);a&&i.set_filters(a),i.save(e,null,(e,t)=>{try{r(i.save_finish(t)?.get_path()??null)}catch{r(null)}})})}export{pickFile,saveFile};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{AdwaitaApp as e,runAdwaitaApp as t}from"./application.js";import{readAppDevHooks as n}from"./dev-hooks.js";import{confirmDialog as r,errorDialog as i}from"./dialogs.js";import{pickFile as a,saveFile as o}from"./file-dialog.js";import{createNavShell as s}from"./nav-shell.js";import{LoadToken as c,loadIntoStack as l}from"./view-loader.js";import{LoadingStack as u}from"./loading-stack.js";import{registerToastOverlay as d,showToast as f}from"./toast.js";import{findNavItem as p,resolveInitialNavIndex as m}from"./nav-model.js";export{e as AdwaitaApp,c as LoadToken,u as LoadingStack,r as confirmDialog,s as createNavShell,i as errorDialog,p as findNavItem,l as loadIntoStack,a as pickFile,n as readAppDevHooks,d as registerToastOverlay,m as resolveInitialNavIndex,t as runAdwaitaApp,o as saveFile,f as showToast};

package/lib/esm/loading-stack.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gobject-2.0";import n from"@girs/gtk-4.0";var r=class LoadingStack extends n.Stack{static{t.registerClass({GTypeName:`GjsifyLoadingStack`},LoadingStack)}constructor(t={}){super(t);let r=new n.Box({orientation:n.Orientation.VERTICAL,halign:n.Align.CENTER,valign:n.Align.CENTER,hexpand:!0,vexpand:!0});r.append(new e.Spinner),this.add_named(r,`loading`),this._content=new e.Bin({hexpand:!0,vexpand:!0}),this.add_named(this._content,`content`),this._error=new e.StatusPage({iconName:`dialog-error-symbolic`,title:`Something went wrong`}),this.add_named(this._error,`error`),this.set_visible_child_name(`loading`)}setContent(e){this._content.set_child(e)}setError(e,t){this._error.set_title(e),this._error.set_description(t??``)}showLoading(){this.set_visible_child_name(`loading`)}showContent(){this.set_visible_child_name(`content`)}showError(){this.set_visible_child_name(`error`)}};t.type_ensure(r.$gtype);export{r as LoadingStack};

package/lib/esm/nav-model.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function resolveInitialNavIndex(e,t){if(e.length===0)return-1;if(!t)return 0;let n=e.findIndex(e=>e.id===t);return n>=0?n:0}function findNavItem(e,t){return e.find(e=>e.id===t)}export{findNavItem,resolveInitialNavIndex};

package/lib/esm/nav-shell.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";import t from"@girs/gtk-4.0";function buildNavRow(e){let n=new t.ListBoxRow,r=new t.Box({orientation:t.Orientation.HORIZONTAL,spacing:12,marginTop:8,marginBottom:8,marginStart:12,marginEnd:12});e.icon&&r.append(new t.Image({iconName:e.icon}));let i=new t.Box({orientation:t.Orientation.VERTICAL,hexpand:!0});return i.append(new t.Label({label:e.label,xalign:0})),e.subtitle&&i.append(new t.Label({label:e.subtitle,xalign:0,cssClasses:[`dim-label`,`caption`]})),r.append(i),n.set_child(r),n}function createNavShell(n,r){let i=new e.NavigationSplitView,a=new t.Stack({transitionType:t.StackTransitionType.CROSSFADE,hexpand:!0,vexpand:!0}),o=new t.ListBox({cssClasses:[`navigation-sidebar`]}),s=new e.HeaderBar,c=new e.HeaderBar;r.sidebarTitle&&c.set_title_widget(new e.WindowTitle({title:r.sidebarTitle,subtitle:``})),r.sidebarHeaderStart&&c.pack_start(r.sidebarHeaderStart),r.sidebarHeaderEnd&&c.pack_end(r.sidebarHeaderEnd);let l=new e.ToolbarView;l.add_top_bar(c),l.set_content(o),i.set_sidebar(new e.NavigationPage({title:r.sidebarTitle??`Menu`,child:l}));let u=new e.ToolbarView;u.add_top_bar(s),u.set_content(a),i.set_content(new e.NavigationPage({title:r.sidebarTitle??``,child:u}));for(let e of r.items)o.append(buildNavRow(e));o.connect(`row-selected`,(e,t)=>{if(!t)return;let n=t.get_index(),a=r.items[n];a&&(r.onSelect(a,n),i.get_collapsed()&&i.set_show_content(!0))});let d=r.collapseWidth??720,f=e.BreakpointCondition.parse(`max-width: ${d}px`);if(f){let t=new e.Breakpoint({condition:f});t.add_setter(i,`collapsed`,!0),n.add_breakpoint(t)}let selectByIndex=e=>{let t=o.get_row_at_index(e);t&&o.select_row(t)};return{widget:i,stack:a,contentHeader:s,selectByIndex,selectById(e){let t=r.items.findIndex(t=>t.id===e);selectByIndex(t>=0?t:0)}}}export{createNavShell};

package/lib/esm/toast.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/adw-1";let t=null;function registerToastOverlay(e){t=e}function showToast(n,r=3){if(!t){console.warn(`@gjsify/adwaita-app: showToast() before registerToastOverlay()`);return}t.add_toast(new e.Toast({title:n,timeout:r}))}export{registerToastOverlay,showToast};

package/lib/esm/view-loader.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";var LoadToken=class{constructor(){this._current=0}next(){return++this._current}get current(){return this._current}};function loadIntoStack(e){let t=e.loadingName??`loading`,n=e.contentName??`content`,r=e.errorName??`error`;e.stack.set_visible_child_name(t);let i=e.token.next();Promise.resolve().then(e.load).then(t=>{i===e.token.current&&(e.fill(t),e.stack.set_visible_child_name(n))}).catch(t=>{i===e.token.current&&(e.onError?.(t),e.stack.set_visible_child_name(r))})}export{LoadToken,loadIntoStack};

package/lib/types/application.d.ts

@@ -0,0 +1,56 @@
+import Adw from '@girs/adw-1';
+import Gio from '@girs/gio-2.0';
+import Gtk from '@girs/gtk-4.0';
+import { type InstallDevtoolsOptions } from '@gjsify/devtools';
+import type { AboutInfo } from './types.js';
+/** Options for {@link AdwaitaApp} / {@link runAdwaitaApp}. */
+export interface AdwaitaAppOptions {
+    /** GApplication id, e.g. `org.example.App`. */
+    applicationId: string;
+    /** GApplication flags. Default `Gio.ApplicationFlags.DEFAULT_FLAGS`. */
+    flags?: Gio.ApplicationFlags;
+    /** Build the main window on first `activate`. Called once. */
+    createWindow: (app: Adw.Application) => Gtk.Window;
+    /** CSS string applied display-wide on `startup` (via `Gtk.CssProvider`). */
+    css?: string;
+    /** When set, wires an `app.about` action opening an `Adw.AboutDialog`. */
+    about?: AboutInfo;
+    /** Wire `app.quit` (`<primary>q`). Default `true`. */
+    quitAction?: boolean;
+    /**
+     * Devtools control plane: `true` force-enables, an object passes
+     * {@link InstallDevtoolsOptions} through, omitted leaves it gated on the
+     * `GJSIFY_DEVTOOLS` env var (safe in production either way).
+     */
+    devtools?: boolean | InstallDevtoolsOptions;
+    /** Extra work on `startup`, after CSS + devtools are wired. */
+    onStartup?: (app: Adw.Application) => void;
+}
+/**
+ * A ready-to-run `Adw.Application` configured from {@link AdwaitaAppOptions}.
+ * Prefer {@link runAdwaitaApp} unless you need the instance.
+ */
+export declare class AdwaitaApp extends Adw.Application {
+    private readonly _options;
+    private _window;
+    constructor(options: AdwaitaAppOptions);
+    private _initActions;
+    private _onStartup;
+    private _loadCss;
+    private _installDevtools;
+    private _onActivate;
+    private _showAbout;
+}
+/**
+ * Construct and run an {@link AdwaitaApp}, resolving with its exit code when the
+ * last window closes. The whole per-project launcher collapses to:
+ *
+ * ```ts
+ * import { runAdwaitaApp } from '@gjsify/adwaita-app';
+ * await runAdwaitaApp({
+ *     applicationId: 'org.example.App',
+ *     createWindow: (app) => new MyWindow(app),
+ * });
+ * ```
+ */
+export declare function runAdwaitaApp(options: AdwaitaAppOptions): Promise<number>;

package/lib/types/dev-hooks.d.ts

@@ -0,0 +1,21 @@
+/** Resolved dev-hook values. */
+export interface AppDevHooks {
+    /** `${PREFIX}_VIEW` — open straight to this view id on startup. */
+    view?: string;
+    /** `${PREFIX}_FILE` — auto-load this file/document on startup. */
+    file?: string;
+    /** `${PREFIX}_DEBUG` — emit verbose load logging. */
+    debug: boolean;
+}
+/** Options for {@link readAppDevHooks}. */
+export interface ReadAppDevHooksOptions {
+    /** Env-var prefix without a trailing underscore, e.g. `BH_APP` or `ER_APP`. */
+    prefix: string;
+    /** Env map to read from. Defaults to `globalThis.process?.env`. */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Read the `${prefix}_VIEW` / `${prefix}_FILE` / `${prefix}_DEBUG` dev hooks.
+ * Empty-string values are treated as unset.
+ */
+export declare function readAppDevHooks(options: ReadAppDevHooksOptions): AppDevHooks;

package/lib/types/dev-hooks.spec.d.ts

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

package/lib/types/dialogs.d.ts

@@ -0,0 +1,21 @@
+import type Gtk from '@girs/gtk-4.0';
+/** Options for {@link confirmDialog}. */
+export interface ConfirmOptions {
+    /** Dialog heading. */
+    heading: string;
+    /** Body text under the heading. */
+    body?: string;
+    /** Confirm-button label. Default `OK`. */
+    confirmLabel?: string;
+    /** Cancel-button label. Default `Cancel`. */
+    cancelLabel?: string;
+    /** Style the confirm button as destructive (red) instead of suggested. */
+    destructive?: boolean;
+}
+/**
+ * Present a confirm/cancel `Adw.AlertDialog`; resolves `true` on confirm, `false`
+ * on cancel/dismiss. `parent` anchors the dialog (typically the window).
+ */
+export declare function confirmDialog(parent: Gtk.Widget, options: ConfirmOptions): Promise<boolean>;
+/** Present a single-button error `Adw.AlertDialog`; resolves when dismissed. */
+export declare function errorDialog(parent: Gtk.Widget, heading: string, body?: string): Promise<void>;

package/lib/types/file-dialog.d.ts

@@ -0,0 +1,23 @@
+import Gtk from '@girs/gtk-4.0';
+/** A named file filter (glob patterns and/or MIME types). */
+export interface FileFilterSpec {
+    /** Human-readable filter name. */
+    name: string;
+    /** Glob patterns, e.g. `*.json`. */
+    patterns?: string[];
+    /** MIME types, e.g. `application/pdf`. */
+    mimeTypes?: string[];
+}
+/** Options for {@link pickFile} / {@link saveFile}. */
+export interface PickFileOptions {
+    /** Dialog title. */
+    title?: string;
+    /** File filters offered in the dialog. */
+    filters?: FileFilterSpec[];
+    /** Pre-filled file name (save dialogs). */
+    initialName?: string;
+}
+/** Open-file dialog; resolves the chosen path, or `null` if cancelled. */
+export declare function pickFile(parent: Gtk.Window, options?: PickFileOptions): Promise<string | null>;
+/** Save-file dialog; resolves the chosen path, or `null` if cancelled. */
+export declare function saveFile(parent: Gtk.Window, options?: PickFileOptions): Promise<string | null>;

package/lib/types/index.d.ts

@@ -0,0 +1,16 @@
+export { AdwaitaApp, runAdwaitaApp } from './application.js';
+export type { AdwaitaAppOptions } from './application.js';
+export { createNavShell } from './nav-shell.js';
+export type { NavShell, NavShellOptions } from './nav-shell.js';
+export { LoadToken, loadIntoStack } from './view-loader.js';
+export type { LoadIntoStackOptions } from './view-loader.js';
+export { LoadingStack } from './loading-stack.js';
+export { confirmDialog, errorDialog } from './dialogs.js';
+export type { ConfirmOptions } from './dialogs.js';
+export { registerToastOverlay, showToast } from './toast.js';
+export { pickFile, saveFile } from './file-dialog.js';
+export type { FileFilterSpec, PickFileOptions } from './file-dialog.js';
+export { readAppDevHooks } from './dev-hooks.js';
+export type { AppDevHooks, ReadAppDevHooksOptions } from './dev-hooks.js';
+export { findNavItem, resolveInitialNavIndex } from './nav-model.js';
+export type { AboutInfo, NavItem } from './types.js';

package/lib/types/loading-stack.d.ts

@@ -0,0 +1,21 @@
+import Gtk from '@girs/gtk-4.0';
+/**
+ * A `Gtk.Stack` pre-wired with the three named pages {@link loadIntoStack}
+ * switches between: `loading` (a centered `Adw.Spinner`), `content` (a settable
+ * child), and `error` (an `Adw.StatusPage`). Starts on `loading`.
+ */
+export declare class LoadingStack extends Gtk.Stack {
+    private readonly _content;
+    private readonly _error;
+    constructor(params?: Partial<Gtk.Stack.ConstructorProps>);
+    /** Set the widget shown on the `content` page. */
+    setContent(widget: Gtk.Widget): void;
+    /** Customize the `error` page's title (and optional description). */
+    setError(title: string, description?: string): void;
+    /** Show the loading spinner. */
+    showLoading(): void;
+    /** Show the content page. */
+    showContent(): void;
+    /** Show the error page (optionally setting its text first via {@link setError}). */
+    showError(): void;
+}

package/lib/types/nav-model.d.ts

@@ -0,0 +1,10 @@
+import type { NavItem } from './types.js';
+/**
+ * Resolve the sidebar row index to select on startup.
+ *
+ * @returns the index of the item whose id matches `wantedId`; `0` when there is
+ *   no match or no `wantedId` but the list is non-empty; `-1` for an empty list.
+ */
+export declare function resolveInitialNavIndex(items: readonly NavItem[], wantedId?: string): number;
+/** Find a nav item by id, or `undefined`. */
+export declare function findNavItem(items: readonly NavItem[], id: string): NavItem | undefined;

package/lib/types/nav-model.spec.d.ts

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

package/lib/types/nav-shell.d.ts

@@ -0,0 +1,38 @@
+import Adw from '@girs/adw-1';
+import Gtk from '@girs/gtk-4.0';
+import type { NavItem } from './types.js';
+/** Options for {@link createNavShell}. */
+export interface NavShellOptions {
+    /** Sidebar rows + stack child ids, in order. */
+    items: readonly NavItem[];
+    /** Fired when the selected item changes (row-selected). */
+    onSelect: (item: NavItem, index: number) => void;
+    /** Sidebar header title. */
+    sidebarTitle?: string;
+    /** Widget packed at the start of the sidebar header (e.g. an open button). */
+    sidebarHeaderStart?: Gtk.Widget;
+    /** Widget packed at the end of the sidebar header (e.g. a menu button). */
+    sidebarHeaderEnd?: Gtk.Widget;
+    /** Collapse the split view below this width (px). Default `720`. */
+    collapseWidth?: number;
+}
+/** The pieces a consumer wires into its window + views. */
+export interface NavShell {
+    /** Top-level widget — set as the window content. */
+    widget: Adw.NavigationSplitView;
+    /** Content stack — add view widgets via `add_named(view, item.id)`. */
+    stack: Gtk.Stack;
+    /** Content header bar — add title widgets / buttons. */
+    contentHeader: Adw.HeaderBar;
+    /** Select a nav item by its id (falls back to the first item). */
+    selectById(id: string): void;
+    /** Select a nav item by index. */
+    selectByIndex(index: number): void;
+}
+/**
+ * Build the nav shell into `window` (which owns the responsive breakpoint).
+ * Returns the split view to set as content plus the stack + content header to
+ * fill. Row selection drives `onSelect`; a collapsed shell reveals the content
+ * pane on selection.
+ */
+export declare function createNavShell(window: Adw.ApplicationWindow, options: NavShellOptions): NavShell;

package/lib/types/toast.d.ts

@@ -0,0 +1,10 @@
+import Adw from '@girs/adw-1';
+/** Register the active window's toast overlay. Call once, at window build. */
+export declare function registerToastOverlay(toastOverlay: Adw.ToastOverlay): void;
+/**
+ * Show a toast on the registered overlay. No-ops with a warning if
+ * {@link registerToastOverlay} has not been called yet.
+ *
+ * @param timeout auto-dismiss seconds; `0` = sticky. Default `3`.
+ */
+export declare function showToast(title: string, timeout?: number): void;

package/lib/types/types.d.ts

@@ -0,0 +1,37 @@
+/** A single entry in the navigation sidebar / view stack. */
+export interface NavItem {
+    /** Stable id used as the `Gtk.Stack` child name and for `selectById`. */
+    id: string;
+    /** Sidebar row label. */
+    label: string;
+    /** Optional symbolic icon name for the sidebar row. */
+    icon?: string;
+    /** Optional dim caption under the label. */
+    subtitle?: string;
+}
+/**
+ * Fields for the standard `app.about` dialog. All optional except the name;
+ * omitted fields are simply not set on the `Adw.AboutDialog`.
+ */
+export interface AboutInfo {
+    /** Application name shown at the top of the dialog. */
+    applicationName: string;
+    /** Version string (e.g. `1.2.0`). */
+    version?: string;
+    /** "Developer" / vendor line. */
+    developerName?: string;
+    /** Icon name; defaults to the application id. */
+    applicationIcon?: string;
+    /** Homepage URL. */
+    website?: string;
+    /** Issue-tracker URL. */
+    issueUrl?: string;
+    /** License text or SPDX id (free-form, shown verbatim). */
+    license?: string;
+    /** Developer credit lines. */
+    developers?: string[];
+    /** Copyright line. */
+    copyright?: string;
+    /** Extra description shown under the header. */
+    comments?: string;
+}

package/lib/types/view-loader.d.ts

@@ -0,0 +1,37 @@
+import type Gtk from '@girs/gtk-4.0';
+/**
+ * Monotonic counter guarding against stale async reloads: each load takes a
+ * `next()` ticket and only applies its result while it is still `current`.
+ */
+export declare class LoadToken {
+    private _current;
+    /** Begin a new load; returns its ticket. */
+    next(): number;
+    /** The most recently issued ticket. */
+    get current(): number;
+}
+/** Options for {@link loadIntoStack}. */
+export interface LoadIntoStackOptions<T> {
+    /** The `Gtk.Stack` whose visible child is swapped between the three pages. */
+    stack: Gtk.Stack;
+    /** Shared token so a later reload supersedes an in-flight one. */
+    token: LoadToken;
+    /** Produce the view data (sync or async). */
+    load: () => T | Promise<T>;
+    /** Populate the content page from the loaded data. */
+    fill: (data: T) => void;
+    /** Stack child name shown while loading. Default `loading`. */
+    loadingName?: string;
+    /** Stack child name shown on success. Default `content`. */
+    contentName?: string;
+    /** Stack child name shown on failure. Default `error`. */
+    errorName?: string;
+    /** Called with the error before the error page is shown. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Run `load`, then `fill` + show the content page — unless a newer reload has
+ * started (result dropped) or `load` throws (error page shown). Always shows the
+ * loading page first. Never rejects.
+ */
+export declare function loadIntoStack<T>(options: LoadIntoStackOptions<T>): void;

package/lib/types/view-loader.spec.d.ts

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

package/package.json

@@ -0,0 +1,83 @@
+{
+    "name": "@gjsify/adwaita-app",
+    "version": "0.16.5",
+    "description": "Native Adwaita application shell for GJS/GTK apps — Adw.Application lifecycle (runAsync + devtools + CSS), a data-driven NavigationSplitView nav shell, an async-view mounter, and promise dialog/toast/file helpers",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "rm -rf lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs || exit 0",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "test:node": "node test.node.mjs",
+        "storybook": "gjsify storybook",
+        "storybook:build": "gjsify storybook --build-only --out dist/storybook.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "gtk",
+        "adwaita",
+        "application",
+        "shell",
+        "navigation",
+        "framework"
+    ],
+    "dependencies": {
+        "@girs/adw-1": "^4.1.0",
+        "@girs/gdk-4.0": "^4.1.0",
+        "@girs/gio-2.0": "^4.1.0",
+        "@girs/gjs": "^4.1.0",
+        "@girs/glib-2.0": "^4.1.0",
+        "@girs/gobject-2.0": "^4.1.0",
+        "@girs/gtk-4.0": "^4.1.0",
+        "@gjsify/devtools": "^0.16.5"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.16.5",
+        "@gjsify/storybook": "^0.16.5",
+        "@gjsify/unit": "^0.16.5",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "tier": 2,
+        "storybook": {
+            "applicationId": "org.gjsify.AdwaitaAppStorybook",
+            "title": "Adwaita App",
+            "stories": "stories",
+            "globals": "auto"
+        }
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/adwaita-app"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/adwaita-app#readme"
+}