react-native-gtkx 0.3.0-alpha.1 → 0.4.0-alpha.2

package/dist/globals/index.js

@@ -0,0 +1,181 @@
+// The global-environment parity seam: values react-native installs at
+// startup (Libraries/Core/setUp*.js, plus @react-native/js-polyfills, which
+// every Metro RN bundle carries unconditionally) that this platform's own
+// runtime — Node — does not provide natively. Both toolchains resolve
+// `react-native` to this package (see ../aliases/index.ts), and ./install.ts
+// calls every installer below once from the top of ../index.ts, so they run
+// before any app code on the vite dev path AND the Metro/run-linux host
+// alike — the one place both toolchains share. A later
+// requestAnimationFrame/cancelAnimationFrame install belongs in this same
+// file, next to these, not in a second module.
+//
+// Each install is idempotent and guards on the global already existing —
+// exactly RN's own polyfillGlobal discipline
+// (Libraries/Utilities/PolyfillFunctions.js) — so calling an installer
+// twice, or a global already supplied by the toolchain (Metro's
+// error-guard.js beats us to ErrorUtils), is a no-op rather than a clobber.
+//
+// What is deliberately NOT installed here — XMLHttpRequest, FileReader,
+// RN-shaped FormData file entries — is documented in docs/api.md; Node
+// already provides fetch/Blob/File/FormData/URL/AbortController/
+// structuredClone/TextEncoder/atob-btoa/performance/crypto natively, with
+// RN-equivalent behaviour for the pure-JS surface these APIs expose.
+//
+// No import from ../apis/index (the gtkx bridge) on purpose: unit tests
+// import these installers directly, the same way ../apis/*'s create*
+// factories are tested with a mock host instead of the wired singletons.
+// The one installer that needs a real dependency (installAlertGlobal needs
+// Alert.alert) takes it as a parameter instead — ./install.ts supplies the
+// real one.
+const hasGlobal = (name) => typeof globalThis[name] !== "undefined";
+const setGlobal = (name, value) => {
+    ;
+    globalThis[name] = value;
+};
+/**
+ * The very first thing react-native's own setup chain does
+ * (Libraries/Core/setUpGlobals.js, run before anything else in
+ * InitializeCore): `global.window = global` and `global.self = global`.
+ * Node has neither. This exists for the same reason RN sets it on a
+ * platform with no DOM either — an isomorphic library's
+ * `typeof window !== "undefined"` check (often used to mean "not a
+ * server/SSR context, safe to run browser-shaped init") should read the
+ * same way here as on any other RN platform.
+ */
+export const installWindowAndSelfGlobals = () => {
+    if (!hasGlobal("window")) {
+        setGlobal("window", globalThis);
+    }
+    if (!hasGlobal("self")) {
+        setGlobal("self", globalThis);
+    }
+};
+/**
+ * `navigator.product === "ReactNative"` is the ecosystem's standard
+ * environment-detection idiom (react-native's own
+ * Libraries/Core/setUpNavigator.js). Node >= 21 already ships a minimal
+ * `navigator` (userAgent only, no `product`), so this mirrors RN's own
+ * fallback exactly rather than assuming a bare object needs creating.
+ */
+export const installNavigatorProductGlobal = () => {
+    const nav = globalThis.navigator;
+    if (nav === undefined) {
+        setGlobal("navigator", { product: "ReactNative" });
+        return;
+    }
+    if (nav.product !== "ReactNative") {
+        Object.defineProperty(nav, "product", {
+            value: "ReactNative",
+            writable: true,
+            configurable: true,
+            enumerable: true,
+        });
+    }
+};
+/**
+ * RN's real requestIdleCallback (Libraries/Core/setUpTimers.js) is a
+ * TurboModule with true native idle scheduling. Node has none — this is
+ * the standard web-fallback shape (the shape every "requestidlecallback
+ * polyfill" package on npm uses): fire on the next macrotask, report a
+ * fixed 50ms budget, never report a timeout. Good enough for "runs off
+ * this tick, eventually" — not a scheduling primitive. See docs/api.md.
+ */
+export const installIdleCallbackGlobals = () => {
+    if (!hasGlobal("requestIdleCallback")) {
+        setGlobal("requestIdleCallback", (callback, options) => {
+            const start = Date.now();
+            return setTimeout(() => {
+                callback({
+                    didTimeout: false,
+                    timeRemaining: () => Math.max(0, 50 - (Date.now() - start)),
+                });
+            }, options?.timeout ?? 1);
+        });
+    }
+    if (!hasGlobal("cancelIdleCallback")) {
+        setGlobal("cancelIdleCallback", (handle) => {
+            clearTimeout(handle);
+        });
+    }
+};
+/**
+ * RN's global.alert (Libraries/Core/setUpAlert.js) forwards to
+ * Alert.alert('Alert', text). Dependency-injected so unit tests exercise it
+ * without pulling in the gtkx bridge (see ../apis/index.ts) — installGlobals
+ * below does the real wiring.
+ */
+export const installAlertGlobal = (alert) => {
+    if (hasGlobal("alert")) {
+        return;
+    }
+    setGlobal("alert", (text) => {
+        alert("Alert", String(text));
+    });
+};
+/**
+ * RN's own setUpErrorHandling.js requires `global.ErrorUtils` to already
+ * exist — on a real RN app it does, installed by @react-native/js-polyfills'
+ * error-guard.js, which @react-native/metro-config's getDefaultConfig
+ * prepends to EVERY Metro bundle unconditionally (independent of, and not
+ * disabled by, this platform's own `getModulesRunBeforeMainModule: () =>
+ * []`). Confirmed empirically (rn-globals-audit): the Metro/run-linux host
+ * already has ErrorUtils, the vite path does not — this closes that gap so
+ * both toolchains agree. A faithful port of the real polyfill: a default
+ * handler that rethrows, exactly react-native's un-hooked behaviour.
+ */
+export const installErrorUtilsGlobal = () => {
+    if (hasGlobal("ErrorUtils")) {
+        return;
+    }
+    let inGuard = 0;
+    let globalHandler = (error) => {
+        throw error;
+    };
+    const ErrorUtils = {
+        setGlobalHandler(handler) {
+            globalHandler = handler;
+        },
+        getGlobalHandler() {
+            return globalHandler;
+        },
+        reportError(error) {
+            globalHandler(error, false);
+        },
+        reportFatalError(error) {
+            globalHandler(error, true);
+        },
+        applyWithGuard(fn, context, args) {
+            try {
+                inGuard += 1;
+                return fn.apply(context, args ?? []);
+            }
+            catch (error) {
+                ErrorUtils.reportError(error);
+                return null;
+            }
+            finally {
+                inGuard -= 1;
+            }
+        },
+        applyWithGuardIfNeeded(fn, context, args) {
+            if (ErrorUtils.inGuard()) {
+                return fn.apply(context, args ?? []);
+            }
+            return ErrorUtils.applyWithGuard(fn, context, args);
+        },
+        inGuard() {
+            return inGuard > 0;
+        },
+        // react-native's real `guard` also takes a debugging `name` label; this
+        // port has no crash reporter to hand it to, so it is dropped rather than
+        // kept and ignored.
+        guard(fn) {
+            if (typeof fn !== "function") {
+                return null;
+            }
+            return (...args) => ErrorUtils.applyWithGuard(fn, undefined, args);
+        },
+    };
+    setGlobal("ErrorUtils", ErrorUtils);
+};
+//# sourceMappingURL=index.js.map

package/dist/globals/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/globals/index.ts"],"names":[],"mappings":"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","sourcesContent":["// The global-environment parity seam: values react-native installs at\n// startup (Libraries/Core/setUp*.js, plus @react-native/js-polyfills, which\n// every Metro RN bundle carries unconditionally) that this platform's own\n// runtime — Node — does not provide natively. Both toolchains resolve\n// `react-native` to this package (see ../aliases/index.ts), and ./install.ts\n// calls every installer below once from the top of ../index.ts, so they run\n// before any app code on the vite dev path AND the Metro/run-linux host\n// alike — the one place both toolchains share. A later\n// requestAnimationFrame/cancelAnimationFrame install belongs in this same\n// file, next to these, not in a second module.\n//\n// Each install is idempotent and guards on the global already existing —\n// exactly RN's own polyfillGlobal discipline\n// (Libraries/Utilities/PolyfillFunctions.js) — so calling an installer\n// twice, or a global already supplied by the toolchain (Metro's\n// error-guard.js beats us to ErrorUtils), is a no-op rather than a clobber.\n//\n// What is deliberately NOT installed here — XMLHttpRequest, FileReader,\n// RN-shaped FormData file entries — is documented in docs/api.md; Node\n// already provides fetch/Blob/File/FormData/URL/AbortController/\n// structuredClone/TextEncoder/atob-btoa/performance/crypto natively, with\n// RN-equivalent behaviour for the pure-JS surface these APIs expose.\n//\n// No import from ../apis/index (the gtkx bridge) on purpose: unit tests\n// import these installers directly, the same way ../apis/*'s create*\n// factories are tested with a mock host instead of the wired singletons.\n// The one installer that needs a real dependency (installAlertGlobal needs\n// Alert.alert) takes it as a parameter instead — ./install.ts supplies the\n// real one.\n\ntype IdleDeadline = { didTimeout: boolean; timeRemaining: () => number }\ntype RequestIdleCallbackOptions = { timeout?: number }\ntype IdleCallbackHandle = ReturnType<typeof setTimeout>\ntype ErrorHandler = (error: unknown, isFatal: boolean) => void\n\nconst hasGlobal = (name: string): boolean =>\n  typeof (globalThis as Record<string, unknown>)[name] !== \"undefined\"\n\nconst setGlobal = (name: string, value: unknown): void => {\n  ;(globalThis as Record<string, unknown>)[name] = value\n}\n\n/**\n * The very first thing react-native's own setup chain does\n * (Libraries/Core/setUpGlobals.js, run before anything else in\n * InitializeCore): `global.window = global` and `global.self = global`.\n * Node has neither. This exists for the same reason RN sets it on a\n * platform with no DOM either — an isomorphic library's\n * `typeof window !== \"undefined\"` check (often used to mean \"not a\n * server/SSR context, safe to run browser-shaped init\") should read the\n * same way here as on any other RN platform.\n */\nexport const installWindowAndSelfGlobals = (): void => {\n  if (!hasGlobal(\"window\")) {\n    setGlobal(\"window\", globalThis)\n  }\n  if (!hasGlobal(\"self\")) {\n    setGlobal(\"self\", globalThis)\n  }\n}\n\n/**\n * `navigator.product === \"ReactNative\"` is the ecosystem's standard\n * environment-detection idiom (react-native's own\n * Libraries/Core/setUpNavigator.js). Node >= 21 already ships a minimal\n * `navigator` (userAgent only, no `product`), so this mirrors RN's own\n * fallback exactly rather than assuming a bare object needs creating.\n */\nexport const installNavigatorProductGlobal = (): void => {\n  const nav = (globalThis as Record<string, unknown>).navigator as\n    Record<string, unknown> | undefined\n  if (nav === undefined) {\n    setGlobal(\"navigator\", { product: \"ReactNative\" })\n    return\n  }\n  if (nav.product !== \"ReactNative\") {\n    Object.defineProperty(nav, \"product\", {\n      value: \"ReactNative\",\n      writable: true,\n      configurable: true,\n      enumerable: true,\n    })\n  }\n}\n\n/**\n * RN's real requestIdleCallback (Libraries/Core/setUpTimers.js) is a\n * TurboModule with true native idle scheduling. Node has none — this is\n * the standard web-fallback shape (the shape every \"requestidlecallback\n * polyfill\" package on npm uses): fire on the next macrotask, report a\n * fixed 50ms budget, never report a timeout. Good enough for \"runs off\n * this tick, eventually\" — not a scheduling primitive. See docs/api.md.\n */\nexport const installIdleCallbackGlobals = (): void => {\n  if (!hasGlobal(\"requestIdleCallback\")) {\n    setGlobal(\n      \"requestIdleCallback\",\n      (\n        callback: (deadline: IdleDeadline) => void,\n        options?: RequestIdleCallbackOptions,\n      ): IdleCallbackHandle => {\n        const start = Date.now()\n        return setTimeout(() => {\n          callback({\n            didTimeout: false,\n            timeRemaining: () => Math.max(0, 50 - (Date.now() - start)),\n          })\n        }, options?.timeout ?? 1)\n      },\n    )\n  }\n  if (!hasGlobal(\"cancelIdleCallback\")) {\n    setGlobal(\"cancelIdleCallback\", (handle: IdleCallbackHandle): void => {\n      clearTimeout(handle)\n    })\n  }\n}\n\n/**\n * RN's global.alert (Libraries/Core/setUpAlert.js) forwards to\n * Alert.alert('Alert', text). Dependency-injected so unit tests exercise it\n * without pulling in the gtkx bridge (see ../apis/index.ts) — installGlobals\n * below does the real wiring.\n */\nexport const installAlertGlobal = (\n  alert: (title: string, message?: string) => void,\n): void => {\n  if (hasGlobal(\"alert\")) {\n    return\n  }\n  setGlobal(\"alert\", (text: unknown): void => {\n    alert(\"Alert\", String(text))\n  })\n}\n\n/**\n * RN's own setUpErrorHandling.js requires `global.ErrorUtils` to already\n * exist — on a real RN app it does, installed by @react-native/js-polyfills'\n * error-guard.js, which @react-native/metro-config's getDefaultConfig\n * prepends to EVERY Metro bundle unconditionally (independent of, and not\n * disabled by, this platform's own `getModulesRunBeforeMainModule: () =>\n * []`). Confirmed empirically (rn-globals-audit): the Metro/run-linux host\n * already has ErrorUtils, the vite path does not — this closes that gap so\n * both toolchains agree. A faithful port of the real polyfill: a default\n * handler that rethrows, exactly react-native's un-hooked behaviour.\n */\nexport const installErrorUtilsGlobal = (): void => {\n  if (hasGlobal(\"ErrorUtils\")) {\n    return\n  }\n  let inGuard = 0\n  let globalHandler: ErrorHandler = (error) => {\n    throw error\n  }\n  // Mirrors react-native's own loose `Fn<Args, Return> = (...Args) => Return`\n  // (Libraries/vendor/core/ErrorUtils.js): a guard wraps ANY function.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  type AnyFn = (...args: any[]) => unknown\n  const ErrorUtils = {\n    setGlobalHandler(handler: ErrorHandler): void {\n      globalHandler = handler\n    },\n    getGlobalHandler(): ErrorHandler {\n      return globalHandler\n    },\n    reportError(error: unknown): void {\n      globalHandler(error, false)\n    },\n    reportFatalError(error: unknown): void {\n      globalHandler(error, true)\n    },\n    applyWithGuard<TFn extends AnyFn>(\n      fn: TFn,\n      context?: unknown,\n      args?: Parameters<TFn>,\n    ): ReturnType<TFn> | null {\n      try {\n        inGuard += 1\n        return fn.apply(context, args ?? []) as ReturnType<TFn>\n      } catch (error) {\n        ErrorUtils.reportError(error)\n        return null\n      } finally {\n        inGuard -= 1\n      }\n    },\n    applyWithGuardIfNeeded<TFn extends AnyFn>(\n      fn: TFn,\n      context?: unknown,\n      args?: Parameters<TFn>,\n    ): ReturnType<TFn> | null {\n      if (ErrorUtils.inGuard()) {\n        return fn.apply(context, args ?? []) as ReturnType<TFn>\n      }\n      return ErrorUtils.applyWithGuard(fn, context, args)\n    },\n    inGuard(): boolean {\n      return inGuard > 0\n    },\n    // react-native's real `guard` also takes a debugging `name` label; this\n    // port has no crash reporter to hand it to, so it is dropped rather than\n    // kept and ignored.\n    guard<TFn extends AnyFn>(\n      fn: TFn,\n    ): ((...args: Parameters<TFn>) => ReturnType<TFn> | null) | null {\n      if (typeof fn !== \"function\") {\n        return null\n      }\n      return (...args: Parameters<TFn>): ReturnType<TFn> | null =>\n        ErrorUtils.applyWithGuard(fn, undefined, args)\n    },\n  }\n  setGlobal(\"ErrorUtils\", ErrorUtils)\n}\n"]}

package/dist/globals/install.d.ts

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

package/dist/globals/install.js

@@ -0,0 +1,14 @@
+// The real wiring for ./index.ts's installers: pulled in only from the top
+// of ../index.ts, never from a unit test, exactly the split ../apis/index.ts
+// draws between its create* factories (mock-host-testable) and itself (the
+// file that binds them to gtkxHost, "it pulls in the gtkx bridge").
+import { Alert } from "../apis/index";
+import { installAlertGlobal, installErrorUtilsGlobal, installIdleCallbackGlobals, installNavigatorProductGlobal, installWindowAndSelfGlobals, } from "./index";
+export const installGlobals = () => {
+    installWindowAndSelfGlobals();
+    installNavigatorProductGlobal();
+    installIdleCallbackGlobals();
+    installErrorUtilsGlobal();
+    installAlertGlobal(Alert.alert);
+};
+//# sourceMappingURL=install.js.map

package/dist/globals/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/globals/install.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,6EAA6E;AAC7E,2EAA2E;AAC3E,oEAAoE;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAA;AACrC,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,SAAS,CAAA;AAEhB,MAAM,CAAC,MAAM,cAAc,GAAG,GAAS,EAAE;IACvC,2BAA2B,EAAE,CAAA;IAC7B,6BAA6B,EAAE,CAAA;IAC/B,0BAA0B,EAAE,CAAA;IAC5B,uBAAuB,EAAE,CAAA;IACzB,kBAAkB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;AACjC,CAAC,CAAA","sourcesContent":["// The real wiring for ./index.ts's installers: pulled in only from the top\n// of ../index.ts, never from a unit test, exactly the split ../apis/index.ts\n// draws between its create* factories (mock-host-testable) and itself (the\n// file that binds them to gtkxHost, \"it pulls in the gtkx bridge\").\nimport { Alert } from \"../apis/index\"\nimport {\n  installAlertGlobal,\n  installErrorUtilsGlobal,\n  installIdleCallbackGlobals,\n  installNavigatorProductGlobal,\n  installWindowAndSelfGlobals,\n} from \"./index\"\n\nexport const installGlobals = (): void => {\n  installWindowAndSelfGlobals()\n  installNavigatorProductGlobal()\n  installIdleCallbackGlobals()\n  installErrorUtilsGlobal()\n  installAlertGlobal(Alert.alert)\n}\n"]}

package/dist/gtkx/bridge/adw-namespace.d.ts

@@ -0,0 +1,2 @@
+import * as Adw from "@gtkx/gi/adw";
+export { Adw };

package/dist/gtkx/bridge/adw-namespace.js

@@ -0,0 +1,26 @@
+// A plain, EAGER, static re-export of the real `@gtkx/gi/adw` namespace —
+// deliberately NOT behind adw.ts's probe.
+//
+// Why this needs to exist separately from adw.ts: react-native-gtkx/adw's
+// public `Adw` export (toast.tsx, window.tsx and adwaita-stack.tsx in the
+// examples all import it as a plain named value off that one subpath, then
+// use it BOTH as a value — `Adw.Toast.new(title)` — and as a namespace in
+// type position — `Ref<Adw.ToastOverlay | null>`) needs that same duality
+// gtkx's own `import * as Adw from "@gtkx/gi/adw"` gives for free. That
+// duality is a property of the IMPORT STATEMENT itself: TypeScript only
+// treats an identifier as usable in both spaces when it traces back to an
+// actual namespace import, forwarded by a bare re-export (`export { X }
+// from` a specifier) — introduce a local binding anywhere in the chain (an
+// `import type` alongside a `const`, or a value synthesized by calling a
+// function) and the type half is lost, which is exactly what broke when
+// adw/index.ts first tried to build `Adw` from adw.ts's requireAdwGi().
+//
+// So this file exists purely to be the START of that re-export chain, and
+// nothing imports it except adw/index.ts (and only for this one name) —
+// never gtkx/bridge/core.ts, app-registry.tsx or host.gtkx.ts, which is
+// exactly what keeps the plain-GTK profile buildable: those three reach for
+// adw.ts's LAZY probe instead, and this file's static import never enters
+// their module graph.
+import * as Adw from "@gtkx/gi/adw";
+export { Adw };
+//# sourceMappingURL=adw-namespace.js.map

package/dist/gtkx/bridge/adw-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adw-namespace.js","sourceRoot":"","sources":["../../../src/gtkx/bridge/adw-namespace.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0CAA0C;AAC1C,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,wEAAwE;AACxE,0EAA0E;AAC1E,wEAAwE;AACxE,2EAA2E;AAC3E,yEAAyE;AACzE,wEAAwE;AACxE,wEAAwE;AACxE,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,wEAAwE;AACxE,4EAA4E;AAC5E,0EAA0E;AAC1E,sBAAsB;AACtB,OAAO,KAAK,GAAG,MAAM,cAAc,CAAA;AAEnC,OAAO,EAAE,GAAG,EAAE,CAAA","sourcesContent":["// A plain, EAGER, static re-export of the real `@gtkx/gi/adw` namespace —\n// deliberately NOT behind adw.ts's probe.\n//\n// Why this needs to exist separately from adw.ts: react-native-gtkx/adw's\n// public `Adw` export (toast.tsx, window.tsx and adwaita-stack.tsx in the\n// examples all import it as a plain named value off that one subpath, then\n// use it BOTH as a value — `Adw.Toast.new(title)` — and as a namespace in\n// type position — `Ref<Adw.ToastOverlay | null>`) needs that same duality\n// gtkx's own `import * as Adw from \"@gtkx/gi/adw\"` gives for free. That\n// duality is a property of the IMPORT STATEMENT itself: TypeScript only\n// treats an identifier as usable in both spaces when it traces back to an\n// actual namespace import, forwarded by a bare re-export (`export { X }\n// from` a specifier) — introduce a local binding anywhere in the chain (an\n// `import type` alongside a `const`, or a value synthesized by calling a\n// function) and the type half is lost, which is exactly what broke when\n// adw/index.ts first tried to build `Adw` from adw.ts's requireAdwGi().\n//\n// So this file exists purely to be the START of that re-export chain, and\n// nothing imports it except adw/index.ts (and only for this one name) —\n// never gtkx/bridge/core.ts, app-registry.tsx or host.gtkx.ts, which is\n// exactly what keeps the plain-GTK profile buildable: those three reach for\n// adw.ts's LAZY probe instead, and this file's static import never enters\n// their module graph.\nimport * as Adw from \"@gtkx/gi/adw\"\n\nexport { Adw }\n"]}

package/dist/gtkx/bridge/adw.d.ts

@@ -0,0 +1,23 @@
+import type * as AdwGi from "@gtkx/gi/adw";
+import type * as AdwJsx from "@gtkx/jsx/adw";
+/**
+ * True when this app's codegen store actually generated Adwaita bindings —
+ * i.e. `"Adw-1"` is in this app's gtkx.config.ts `libraries`. Synchronous
+ * from every caller's point of view on the Metro/SEA host and the
+ * plain-GTK profile (both resolved above with nothing to await); on vite
+ * build/dev and vitest this reads whatever the fire-and-forget probe above
+ * has settled to by the time it is called — see the module doc for why
+ * that is reliably "already settled" for every real call site in this
+ * package, not a formal guarantee.
+ */
+export declare const adwAvailable: () => boolean;
+/** The real `@gtkx/gi/adw` namespace (enums, GObject classes — `Adw.StyleManager`,
+ *  `Adw.ColorScheme`, `Adw.ResponseAppearance`, ...), or the loud throw above. */
+export declare const requireAdwGi: (feature: string) => typeof AdwGi;
+/** The real `@gtkx/jsx/adw` namespace (raw JSX elements — `AdwApplicationWindow`,
+ *  `AdwNavigationView`, `AdwNavigationPage`, ...), or the loud throw above. */
+export declare const requireAdwJsx: (feature: string) => typeof AdwJsx;
+export type { AdwGi as Adw };
+export type ColorScheme = "light" | "dark";
+export declare const styleManager: () => AdwGi.StyleManager;
+export declare const colorScheme: () => ColorScheme;

package/dist/gtkx/bridge/adw.js

@@ -0,0 +1,93 @@
+// Assembled rather than written as one literal: used only as a lookup key
+// into global.__hostModules (an object property read, not an import), which
+// the run-linux host populates keyed by these exact strings
+// (HOST_MODULE_EXTERNALS in src/metro/index.ts). Kept opaque to a plain text
+// search for consistency with the rest of this file, not because anything
+// would fail resolving it — fromHostModules never imports.
+const GI_ADW = ["@gtkx", "gi", "adw"].join("/");
+const JSX_ADW = ["@gtkx", "jsx", "adw"].join("/");
+// The run-linux (Metro) host already resolved every external — including
+// these two, when the app declared "Adw-1" — into global.__hostModules
+// BEFORE the bundle ever runs (see src/runner/host.ts) — synchronously, as
+// far as this module is concerned, and the authoritative answer on that
+// toolchain: reading it directly is both correct and avoids a second,
+// redundant resolution attempt Metro's bundler cannot serve anyway (no
+// "virtual:gtkx-config" loader hook outside Vite's own pipeline or the
+// host's own module.registerHooks).
+// Returns undefined (not false) when there is no host indirection in play
+// at all — the vite dev/build toolchain, where every spike and example in
+// this repo runs — so the caller knows to fall through to the real probe.
+const fromHostModules = () => {
+    const hostModules = globalThis.__hostModules;
+    if (!hostModules) {
+        return undefined;
+    }
+    const gi = hostModules[GI_ADW];
+    const jsx = hostModules[JSX_ADW];
+    return gi && jsx
+        ? { gi: gi, jsx: jsx }
+        : null;
+};
+const hostModulesResult = fromHostModules();
+let cached;
+if (hostModulesResult !== undefined) {
+    cached = hostModulesResult;
+}
+else if (typeof __GTKX_ADW_AVAILABLE__ !== "undefined" &&
+    !__GTKX_ADW_AVAILABLE__) {
+    cached = null;
+}
+else {
+    // Fire-and-forget — see the module doc above for why this can no longer
+    // be a module-scope `await` and why starting it here, unconditionally,
+    // still settles in time for every real caller.
+    Promise.all([import("@gtkx/gi/adw"), import("@gtkx/jsx/adw")])
+        .then(([gi, jsx]) => {
+        cached = { gi: gi, jsx: jsx };
+    })
+        .catch(() => {
+        cached = null;
+    });
+}
+/**
+ * True when this app's codegen store actually generated Adwaita bindings —
+ * i.e. `"Adw-1"` is in this app's gtkx.config.ts `libraries`. Synchronous
+ * from every caller's point of view on the Metro/SEA host and the
+ * plain-GTK profile (both resolved above with nothing to await); on vite
+ * build/dev and vitest this reads whatever the fire-and-forget probe above
+ * has settled to by the time it is called — see the module doc for why
+ * that is reliably "already settled" for every real call site in this
+ * package, not a formal guarantee.
+ */
+export const adwAvailable = () => cached !== null && cached !== undefined;
+const NOT_AVAILABLE = ' requires "Adw-1" in this app\'s gtkx.config.ts `libraries` — see ' +
+    "docs/api.md (the plain-GTK profile) for what needs Adw unconditionally " +
+    "and what falls back without it.";
+/** The repo's loud named throw for a feature that reached for Adw and found
+ *  none. Every Adw-dependent call site in the seam funnels through this, but
+ *  most no longer reach it in practice: Alert, Appearance and chrome:
+ *  "content" all check `adwAvailable()` themselves first and take a
+ *  plain-GTK fallback instead (see .claude/epics/adw-optional/002.md,
+ *  003.md, 004.md) — this throw is what is left for the features with no
+ *  fallback at all (NavigationStack, react-native-gtkx/adw's own
+ *  AdwBreakpoint family). */
+const requireAdw = (feature) => {
+    if (!cached) {
+        throw new Error(`[react-native-gtkx] ${feature}${NOT_AVAILABLE}`);
+    }
+    return cached;
+};
+/** The real `@gtkx/gi/adw` namespace (enums, GObject classes — `Adw.StyleManager`,
+ *  `Adw.ColorScheme`, `Adw.ResponseAppearance`, ...), or the loud throw above. */
+export const requireAdwGi = (feature) => requireAdw(feature).gi;
+/** The real `@gtkx/jsx/adw` namespace (raw JSX elements — `AdwApplicationWindow`,
+ *  `AdwNavigationView`, `AdwNavigationPage`, ...), or the loud throw above. */
+export const requireAdwJsx = (feature) => requireAdw(feature).jsx;
+// Folded in from the pre-seam ./theme.ts: both are pure Adw, both were only
+// ever called from apis/host.gtkx.ts, and keeping them as their own
+// (formerly eagerly-imported) file would just move the eager `import * as
+// Adw` problem one hop over instead of removing it.
+export const styleManager = () => requireAdwGi("Appearance").StyleManager.getDefault();
+// The Appearance API subscribes to notify::dark on the style manager.
+export const colorScheme = () => styleManager().getDark() ? "dark" : "light";
+//# sourceMappingURL=adw.js.map

package/dist/gtkx/bridge/adw.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adw.js","sourceRoot":"","sources":["../../../src/gtkx/bridge/adw.ts"],"names":[],"mappings":"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","sourcesContent":["// The ONLY module allowed to import @gtkx/gi/adw and @gtkx/jsx/adw — see\n// .claude/epics/adw-optional/001.md. Everything the RN core needs lives in\n// ./core instead, with zero Adw imports, so an app whose gtkx.config.ts\n// declares `libraries: [\"Gtk-4.0\"]` alone (no \"Adw-1\") never reaches either\n// specifier: a codegen store generated that way has no \"./adw\" entry in\n// either package's `exports` map AT ALL (empirically verified: neither\n// directory even exists on disk), so a STATIC import of either one fails\n// the whole build — `gtkx build`'s own \"gtkx:undeclared-library\" vite\n// plugin throws while resolving it, unconditionally, whether or not the\n// import is ever reached at runtime.\n//\n// __GTKX_ADW_AVAILABLE__ (declared ambient just below) is a build-time\n// constant the vite preset injects (src/vite/index.ts, see its own doc for\n// the full story — .claude/epics/adw-optional/006.md is the regression this\n// exists to fix): true only when THIS app's codegen store actually has an\n// \"adw\" entry. The probe below guards on it and, only inside that guard,\n// imports @gtkx/gi/adw and @gtkx/jsx/adw as LITERAL specifiers —\n// deliberately, unlike a runtime-assembled string. A hidden specifier is\n// invisible to Rollup's build graph, which sounds like the safer choice,\n// but it is ALSO invisible to everything that graph gives every OTHER gtkx\n// import for free: `resolve.dedupe` (RC4-WORKAROUND(runtime-dedupe) in\n// docs/gtkx-rc4-notes.md) and `gtkx build`'s own asset pipeline for the\n// native addon (`@gtkx/cli`'s `gtkx:native` plugin, which rewrites every\n// STATICALLY reachable `@gtkx/native` import onto the single `dist/gtkx.node`\n// it emits) — a hidden specifier resolves a SECOND, independent copy from\n// node_modules at runtime instead, and two distinct native addons\n// double-initialize the gtkx runtime and abort the process\n// (`g_log_set_writer_func() called multiple times`, proven with a core dump\n// showing both `.node` files mapped into one process). A literal specifier\n// gets the exact same static treatment as every other gtkx import; when the\n// build-time constant folds to `false` instead, dead-code elimination\n// removes the whole guarded body — literal specifiers included — before\n// Rollup's graph walk ever starts, so `gtkx:undeclared-library` never\n// throws on the plain-GTK profile either.\n//\n// No module-scope await, anywhere — the one thing that actually changed\n// here (.claude/epics/adw-optional/007-sea-tla.md): this file used to\n// resolve Adw with a TOP-LEVEL AWAIT (both the #132 guarded literal imports\n// and the fallback probe), so every call site below could stay synchronous\n// without an explicit wait of its own. That broke `react-native\n// build-linux` outright — reproduced empirically in the VM, WITH OR\n// WITHOUT --sea/--standalone (all three share the same Metro `bundle()`\n// call, `--dev false`): Metro's own minifier (metro-minify-terser, i.e.\n// terser) parses each module's compiled factory as a plain SCRIPT, not an\n// ES module — `await` is just an ordinary identifier there, not a keyword,\n// so \"await probeViaDynamicImport()\" is a hard syntax error (\"Unexpected\n// token: name (probeViaDynamicImport)\"), independent of the SEA/rolldown\n// CJS-format restriction the task file also names (CJS has no TLA either —\n// the same file would have failed a second time even past Metro).\n//\n// Tried and reverted: resolving gi through a synchronous `require()` (via\n// `createRequire(import.meta.url)`) instead of a dynamic import — it does\n// answer synchronously under vite build/dev and vitest, but\n// `import.meta.url` is ITSELF ESM-only syntax, exactly like top-level\n// await: Metro's minifier happened not to reject it at minify time (unlike\n// `await`), but Node's own parser does, the moment the Metro/SEA host\n// actually executes the bundle via `vm.runInThisContext` (which runs the\n// whole bundle as a plain SCRIPT, not a module) — \"SyntaxError: Cannot use\n// 'import.meta' outside a module\", reproduced building and running\n// examples/hn-app's SEA artifact. Same class of bug as the TLA one this\n// file exists to fix, so back to a dynamic import for both gi and jsx —\n// their own literal specifiers, unlike ours, are genuinely fine either way\n// since Metro/the SEA host never reach this branch at all (see\n// fromHostModules below) and every other toolchain is real ESM.\n//\n// So: a single, ordinary (non-async, non-top-level-await) function starts\n// BOTH imports together — Promise.all, exactly like the old probe — the\n// moment this module itself finishes evaluating, fire-and-forget (no\n// module-scope await to block on this time). No formal ordering guarantee\n// versus the old TLA probe's, but starting it as early as this module can\n// (not lazily, on the first actual `requireAdwJsx()`/`requireAdwGi()` call)\n// gives it a real, if informal, chance to have already settled — verified\n// against this package's own gtk test suite, including the one caller with\n// the least slack of all: react-native-gtkx/adw's own `adw/index.ts` calls\n// `requireAdwJsx()` eagerly, at ITS OWN module scope, the moment it is\n// imported (immediately after this file). Under Vite's SSR module runner\n// (dev and vitest both), every static import a transformed module has is\n// itself an awaited call in that runner, cached or not — so `adw/index.ts`\n// evaluating is always at least one module-boundary await after this\n// file's own module body, including the Promise.all it starts, finished\n// running. tests/gtk/bridge/auxiliary-elements.gtk.test.tsx (imports\n// react-native-gtkx/adw) and tests/gtk/adw/* are all green under this.\n//\n// The Metro/SEA host fast path (fromHostModules, below) takes priority over\n// all of this and never touches import() at all: `global.__hostModules` is\n// already populated — both gi and jsx together, when present — before the\n// run-linux host or the SEA entry's own async wrapper (src/sea/bundle.ts's\n// `buildEntrySource`, itself already just an ordinary async FUNCTION, never\n// a module-scope await) ever executes the bundle that reaches this file.\nimport type * as AdwGi from \"@gtkx/gi/adw\"\nimport type * as AdwJsx from \"@gtkx/jsx/adw\"\n\n// Assembled rather than written as one literal: used only as a lookup key\n// into global.__hostModules (an object property read, not an import), which\n// the run-linux host populates keyed by these exact strings\n// (HOST_MODULE_EXTERNALS in src/metro/index.ts). Kept opaque to a plain text\n// search for consistency with the rest of this file, not because anything\n// would fail resolving it — fromHostModules never imports.\nconst GI_ADW = [\"@gtkx\", \"gi\", \"adw\"].join(\"/\")\nconst JSX_ADW = [\"@gtkx\", \"jsx\", \"adw\"].join(\"/\")\n\ntype AdwModules = {\n  gi: typeof AdwGi\n  jsx: typeof AdwJsx\n}\n\ntype HostModulesGlobal = typeof globalThis & {\n  __hostModules?: Record<string, unknown>\n}\n\n// The run-linux (Metro) host already resolved every external — including\n// these two, when the app declared \"Adw-1\" — into global.__hostModules\n// BEFORE the bundle ever runs (see src/runner/host.ts) — synchronously, as\n// far as this module is concerned, and the authoritative answer on that\n// toolchain: reading it directly is both correct and avoids a second,\n// redundant resolution attempt Metro's bundler cannot serve anyway (no\n// \"virtual:gtkx-config\" loader hook outside Vite's own pipeline or the\n// host's own module.registerHooks).\n// Returns undefined (not false) when there is no host indirection in play\n// at all — the vite dev/build toolchain, where every spike and example in\n// this repo runs — so the caller knows to fall through to the real probe.\nconst fromHostModules = (): AdwModules | null | undefined => {\n  const hostModules = (globalThis as HostModulesGlobal).__hostModules\n  if (!hostModules) {\n    return undefined\n  }\n  const gi = hostModules[GI_ADW]\n  const jsx = hostModules[JSX_ADW]\n  return gi && jsx\n    ? { gi: gi as typeof AdwGi, jsx: jsx as typeof AdwJsx }\n    : null\n}\n\nconst hostModulesResult = fromHostModules()\n\n// Skips the probe outright when the vite preset has POSITIVELY told us Adw\n// is not in this app's codegen store (see the module doc above for why a\n// literal specifier below needs this guard to exist at all). `typeof`, not\n// a direct reference: safe on any toolchain that never defines the constant\n// (a bare `vitest` \"unit\" project, or a consumer not using our preset) —\n// reads as \"undefined\", so the guard is skipped and the probe runs for\n// real. Only an explicit `false` short-circuits.\ndeclare const __GTKX_ADW_AVAILABLE__: boolean | undefined\n\nlet cached: AdwModules | null | undefined\n\nif (hostModulesResult !== undefined) {\n  cached = hostModulesResult\n} else if (\n  typeof __GTKX_ADW_AVAILABLE__ !== \"undefined\" &&\n  !__GTKX_ADW_AVAILABLE__\n) {\n  cached = null\n} else {\n  // Fire-and-forget — see the module doc above for why this can no longer\n  // be a module-scope `await` and why starting it here, unconditionally,\n  // still settles in time for every real caller.\n  Promise.all([import(\"@gtkx/gi/adw\"), import(\"@gtkx/jsx/adw\")])\n    .then(([gi, jsx]) => {\n      cached = { gi: gi as typeof AdwGi, jsx: jsx as typeof AdwJsx }\n    })\n    .catch(() => {\n      cached = null\n    })\n}\n\n/**\n * True when this app's codegen store actually generated Adwaita bindings —\n * i.e. `\"Adw-1\"` is in this app's gtkx.config.ts `libraries`. Synchronous\n * from every caller's point of view on the Metro/SEA host and the\n * plain-GTK profile (both resolved above with nothing to await); on vite\n * build/dev and vitest this reads whatever the fire-and-forget probe above\n * has settled to by the time it is called — see the module doc for why\n * that is reliably \"already settled\" for every real call site in this\n * package, not a formal guarantee.\n */\nexport const adwAvailable = (): boolean =>\n  cached !== null && cached !== undefined\n\nconst NOT_AVAILABLE =\n  ' requires \"Adw-1\" in this app\\'s gtkx.config.ts `libraries` — see ' +\n  \"docs/api.md (the plain-GTK profile) for what needs Adw unconditionally \" +\n  \"and what falls back without it.\"\n\n/** The repo's loud named throw for a feature that reached for Adw and found\n *  none. Every Adw-dependent call site in the seam funnels through this, but\n *  most no longer reach it in practice: Alert, Appearance and chrome:\n *  \"content\" all check `adwAvailable()` themselves first and take a\n *  plain-GTK fallback instead (see .claude/epics/adw-optional/002.md,\n *  003.md, 004.md) — this throw is what is left for the features with no\n *  fallback at all (NavigationStack, react-native-gtkx/adw's own\n *  AdwBreakpoint family). */\nconst requireAdw = (feature: string): AdwModules => {\n  if (!cached) {\n    throw new Error(`[react-native-gtkx] ${feature}${NOT_AVAILABLE}`)\n  }\n  return cached\n}\n\n/** The real `@gtkx/gi/adw` namespace (enums, GObject classes — `Adw.StyleManager`,\n *  `Adw.ColorScheme`, `Adw.ResponseAppearance`, ...), or the loud throw above. */\nexport const requireAdwGi = (feature: string): typeof AdwGi =>\n  requireAdw(feature).gi\n\n/** The real `@gtkx/jsx/adw` namespace (raw JSX elements — `AdwApplicationWindow`,\n *  `AdwNavigationView`, `AdwNavigationPage`, ...), or the loud throw above. */\nexport const requireAdwJsx = (feature: string): typeof AdwJsx =>\n  requireAdw(feature).jsx\n\n// Type-only (erased at build — no runtime import, so this costs nothing on\n// the plain profile): re-exported so a consumer like common/navigation-stack.tsx\n// can spell `Ref<Adw.NavigationView | null>` without importing @gtkx/gi/adw\n// itself, which the eslint fence (no @gtkx/* outside src/gtkx/bridge/**)\n// would refuse anyway.\nexport type { AdwGi as Adw }\n\nexport type ColorScheme = \"light\" | \"dark\"\n\n// Folded in from the pre-seam ./theme.ts: both are pure Adw, both were only\n// ever called from apis/host.gtkx.ts, and keeping them as their own\n// (formerly eagerly-imported) file would just move the eager `import * as\n// Adw` problem one hop over instead of removing it.\nexport const styleManager = (): AdwGi.StyleManager =>\n  requireAdwGi(\"Appearance\").StyleManager.getDefault()\n\n// The Appearance API subscribes to notify::dark on the style manager.\nexport const colorScheme = (): ColorScheme =>\n  styleManager().getDark() ? \"dark\" : \"light\"\n"]}

package/dist/gtkx/bridge/color-scheme-parse.d.ts

@@ -0,0 +1,11 @@
+export type ColorScheme = "light" | "dark";
+export type VariantLike = {
+    getTypeString(): string;
+    getVariant(): VariantLike;
+    getUint32(): number;
+    getString(): [string, number];
+};
+export declare const unwrapVariant: (variant: VariantLike) => VariantLike;
+export declare const parseColorSchemeValue: (raw: number) => ColorScheme;
+export declare const parsePortalReadReply: (reply: VariantLike) => ColorScheme;
+export declare const parseSettingChangedValue: (value: VariantLike) => ColorScheme;

package/dist/gtkx/bridge/color-scheme-parse.js

@@ -0,0 +1,42 @@
+// The pure, GTK-free half of color-scheme-portal.ts: parsing a
+// org.freedesktop.portal.Settings reply/signal payload into "light" | "dark".
+// Deliberately has NO @gtkx/gi imports (not even type-only ones — see
+// VariantLike below) so it is importable from tests/unit (cross-platform,
+// no GTK, no codegen store) — see
+// tests/unit/gtkx/color-scheme-parse.test.ts and
+// .claude/epics/adw-optional/004.md's note on why the real D-Bus round trip
+// itself cannot be integration-tested in this repo's headless session.
+// org.freedesktop.portal.Settings.Read's "value" out-arg is declared as
+// variant ("v"); a long-standing, widely reported implementation quirk
+// (flatpak/xdg-desktop-portal#789) double-boxes it, so a real reply is
+// Variant[Variant[uint32]] as often as it is Variant[uint32] depending on
+// the backend (xdg-desktop-portal-gnome, -kde, ...) and version. Peeling
+// while the type is still "v" handles both without having to guess which
+// one a given portal implementation does.
+export const unwrapVariant = (variant) => {
+    let current = variant;
+    // A defensive bound, not a real limit — no correct implementation nests
+    // more than one extra layer; this only stops a corrupt/adversarial reply
+    // from looping forever.
+    for (let guard = 0; guard < 8 && current.getTypeString() === "v"; guard += 1) {
+        current = current.getVariant();
+    }
+    return current;
+};
+// The portal's own enum for org.freedesktop.appearance's color-scheme key:
+// 0 = no preference, 1 = prefer dark, 2 = prefer light. The spec requires
+// unknown values to be treated the same as 0 — mapped to "light" here,
+// matching Gtk.Settings' own gtk-application-prefer-dark-theme default.
+export const parseColorSchemeValue = (raw) => raw === 1 ? "dark" : "light";
+// reply is "(v)" — Settings.Read's single out-arg, boxed once more by the
+// tuple every D-Bus method reply is wrapped in; the caller passes
+// reply.getChildValue(0) (a real GLib.Variant call, not part of VariantLike
+// — trivial enough it does not need its own seam), everything after that
+// goes through the parser above.
+export const parsePortalReadReply = (reply) => parseColorSchemeValue(unwrapVariant(reply).getUint32());
+// SettingChanged's payload is (namespace: s, key: s, value: v) — value goes
+// through the same unwrap-then-read path as a Read reply. The caller passes
+// just the value child (parameters.getChildValue(2)); namespace/key
+// filtering happens in the caller with the real Variant's getString().
+export const parseSettingChangedValue = (value) => parseColorSchemeValue(unwrapVariant(value).getUint32());
+//# sourceMappingURL=color-scheme-parse.js.map

package/dist/gtkx/bridge/color-scheme-parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-scheme-parse.js","sourceRoot":"","sources":["../../../src/gtkx/bridge/color-scheme-parse.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,8EAA8E;AAC9E,sEAAsE;AACtE,0EAA0E;AAC1E,kCAAkC;AAClC,iDAAiD;AACjD,4EAA4E;AAC5E,uEAAuE;AAcvE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,0EAA0E;AAC1E,yEAAyE;AACzE,yEAAyE;AACzE,0CAA0C;AAC1C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,OAAoB,EAAe,EAAE;IACjE,IAAI,OAAO,GAAG,OAAO,CAAA;IACrB,wEAAwE;IACxE,yEAAyE;IACzE,wBAAwB;IACxB,KACE,IAAI,KAAK,GAAG,CAAC,EACb,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,aAAa,EAAE,KAAK,GAAG,EAC5C,KAAK,IAAI,CAAC,EACV,CAAC;QACD,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAA;IAChC,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA;AAED,2EAA2E;AAC3E,0EAA0E;AAC1E,uEAAuE;AACvE,wEAAwE;AACxE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAW,EAAe,EAAE,CAChE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAA;AAE9B,0EAA0E;AAC1E,kEAAkE;AAClE,4EAA4E;AAC5E,yEAAyE;AACzE,iCAAiC;AACjC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,KAAkB,EAAe,EAAE,CACtE,qBAAqB,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,CAAA;AAEzD,4EAA4E;AAC5E,4EAA4E;AAC5E,oEAAoE;AACpE,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAkB,EAAe,EAAE,CAC1E,qBAAqB,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,CAAA","sourcesContent":["// The pure, GTK-free half of color-scheme-portal.ts: parsing a\n// org.freedesktop.portal.Settings reply/signal payload into \"light\" | \"dark\".\n// Deliberately has NO @gtkx/gi imports (not even type-only ones — see\n// VariantLike below) so it is importable from tests/unit (cross-platform,\n// no GTK, no codegen store) — see\n// tests/unit/gtkx/color-scheme-parse.test.ts and\n// .claude/epics/adw-optional/004.md's note on why the real D-Bus round trip\n// itself cannot be integration-tested in this repo's headless session.\n\nexport type ColorScheme = \"light\" | \"dark\"\n\n// A structural (not nominal) slice of GLib.Variant — just enough of it to\n// parse a Settings.Read reply or a SettingChanged payload, so this file can\n// be unit-tested with a plain object instead of a real GLib.Variant.\nexport type VariantLike = {\n  getTypeString(): string\n  getVariant(): VariantLike\n  getUint32(): number\n  getString(): [string, number]\n}\n\n// org.freedesktop.portal.Settings.Read's \"value\" out-arg is declared as\n// variant (\"v\"); a long-standing, widely reported implementation quirk\n// (flatpak/xdg-desktop-portal#789) double-boxes it, so a real reply is\n// Variant[Variant[uint32]] as often as it is Variant[uint32] depending on\n// the backend (xdg-desktop-portal-gnome, -kde, ...) and version. Peeling\n// while the type is still \"v\" handles both without having to guess which\n// one a given portal implementation does.\nexport const unwrapVariant = (variant: VariantLike): VariantLike => {\n  let current = variant\n  // A defensive bound, not a real limit — no correct implementation nests\n  // more than one extra layer; this only stops a corrupt/adversarial reply\n  // from looping forever.\n  for (\n    let guard = 0;\n    guard < 8 && current.getTypeString() === \"v\";\n    guard += 1\n  ) {\n    current = current.getVariant()\n  }\n  return current\n}\n\n// The portal's own enum for org.freedesktop.appearance's color-scheme key:\n// 0 = no preference, 1 = prefer dark, 2 = prefer light. The spec requires\n// unknown values to be treated the same as 0 — mapped to \"light\" here,\n// matching Gtk.Settings' own gtk-application-prefer-dark-theme default.\nexport const parseColorSchemeValue = (raw: number): ColorScheme =>\n  raw === 1 ? \"dark\" : \"light\"\n\n// reply is \"(v)\" — Settings.Read's single out-arg, boxed once more by the\n// tuple every D-Bus method reply is wrapped in; the caller passes\n// reply.getChildValue(0) (a real GLib.Variant call, not part of VariantLike\n// — trivial enough it does not need its own seam), everything after that\n// goes through the parser above.\nexport const parsePortalReadReply = (reply: VariantLike): ColorScheme =>\n  parseColorSchemeValue(unwrapVariant(reply).getUint32())\n\n// SettingChanged's payload is (namespace: s, key: s, value: v) — value goes\n// through the same unwrap-then-read path as a Read reply. The caller passes\n// just the value child (parameters.getChildValue(2)); namespace/key\n// filtering happens in the caller with the real Variant's getString().\nexport const parseSettingChangedValue = (value: VariantLike): ColorScheme =>\n  parseColorSchemeValue(unwrapVariant(value).getUint32())\n"]}

package/dist/gtkx/bridge/color-scheme-portal.d.ts

@@ -0,0 +1,24 @@
+import type { SubscriptionHandle } from "../../contracts";
+import { type ColorScheme } from "./color-scheme-parse";
+export type { ColorScheme };
+/** Always "light" | "dark" — see the module doc for how it is sourced. */
+export declare const getPlainColorScheme: () => ColorScheme;
+/**
+ * The plain profile's setColorScheme. What Adw's setColorScheme forces is
+ * already only ever an app-local override — AdwStyleManager is per-process,
+ * never a system-wide write — so writing Gtk.Settings'
+ * gtk-application-prefer-dark-theme here (also strictly app-local: it never
+ * reaches outside this process either) is not a lesser feature, just the
+ * plain-GTK lever that does the same job. There is no honest way to make
+ * this profile change the DESKTOP's own preference — no portal write API
+ * exists (the portal is read + notify only, by design) — so "local-only" is
+ * the whole story, not a fallback for a system-wide write that almost
+ * worked.
+ *
+ * null ("follow the system") re-applies the last value actually observed
+ * from the portal, if any. With no portal reachable at all there is no
+ * other system source to revert to, so it is a deliberate no-op — staying
+ * at whatever the toggle already reads rather than guessing a default.
+ */
+export declare const setPlainColorScheme: (scheme: ColorScheme | null) => void;
+export declare const onPlainColorSchemeChange: (notify: () => void) => SubscriptionHandle;