@multiplatform.one/cli 6.4.3 → 6.6.0

package/src/commands/updateApp.ts

@@ -15,12 +15,12 @@
  * pins matching paths to your HEAD version, exactly like the old script.
  */
 
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import spawn from "nano-spawn";
 import { generateVscodeConfig } from "../generateVscode";
-import { cliVersion, initApp, readProvenance, writeProvenance } from "./initApp";
+import { cliVersion, initApp, readProvenance, writeProvenance, type InitAppPiece } from "./initApp";
 
 export interface UpdateAppOptions {
   /** Skip pnpm install after the merge. */
@@ -69,6 +69,7 @@ async function scaffoldBaseline(
   name: string,
   template: "universal" | "app",
   mpoVersion: string,
+  pieces: InitAppPiece[],
 ): Promise<{ dir: string; cleanup: () => void }> {
   const parent = mkdtempSync(join(tmpdir(), "mpo-update-"));
   const cleanup = () => rmSync(parent, { recursive: true, force: true });
@@ -79,6 +80,19 @@ async function scaffoldBaseline(
   // scaffold baseline.
   const [major = 0, minor = 0] = version.split(".").map(Number);
   const scaffoldCapable = major > 6 || (major === 6 && minor >= 3);
+  // Composable pieces (--frappe/--keycloak/--tauri/--vscode/--webext)
+  // shipped in 6.5.0 — older published CLIs reject the flags. A 6.3/6.4
+  // baseline is scaffolded WITHOUT pieces: piece files then appear as
+  // ours-only additions relative to that base, which three-way merge keeps
+  // cleanly (they can't have come from those CLIs in the first place).
+  const piecesCapable = major > 6 || (major === 6 && minor >= 5);
+  const pieceFlags = piecesCapable ? pieces.map((piece) => `--${piece}`) : [];
+  if (pieces.length && scaffoldCapable && !piecesCapable && version !== current) {
+    console.warn(
+      `⚠️  @multiplatform.one/cli@${version} predates composable pieces (6.5.0); ` +
+        "the merge base is scaffolded without them.",
+    );
+  }
   if (!scaffoldCapable) {
     console.warn(
       `⚠️  @multiplatform.one/cli@${version} predates the consumer scaffolder (6.3.0); ` +
@@ -104,6 +118,7 @@ async function scaffoldBaseline(
             "--mpo-version",
             mpoVersion,
             ...templateFlag,
+            ...pieceFlags,
           ],
           { cwd: parent, stdio: "inherit" },
         );
@@ -131,6 +146,7 @@ async function scaffoldBaseline(
       yes: true,
       template,
       version: mpoVersion,
+      pieces,
     });
   } finally {
     process.chdir(previousCwd);
@@ -180,6 +196,167 @@ async function pinPathsToHead(
   return pinned;
 }
 
+// ── package.json conflict auto-resolution ─────────────────────────
+//
+// The dominant conflict class in real updates is dependency-range drift:
+// the project bumped a range between updates (ours ^6.4.2) while the new
+// template carries its own (theirs ^6.4.3). Both sides changed the same
+// JSON entry, so textual merge punts — but the resolution is mechanical:
+// take the newer minimum version. A structural three-way merge handles it.
+
+const UNRESOLVED = Symbol("unresolved");
+/** Deleted-on-one-side sentinel (distinct from a key that never existed). */
+const ABSENT = Symbol("absent");
+
+const DEP_MAP_KEYS = new Set([
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "overrides",
+  "resolutions",
+]);
+
+/** Minimum concrete version of a simple range (`^x.y.z`, `~x.y.z`,
+ *  `x.y.z`, optional prerelease). Anything fancier is not auto-resolved. */
+function rangeMinimum(range: unknown): [number, number, number] | undefined {
+  if (typeof range !== "string") return undefined;
+  const match = range.match(/^[\^~]?(\d+)\.(\d+)\.(\d+)(?:-[\w.]+)?$/);
+  if (!match) return undefined;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function jsonEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function mergeNode(
+  base: unknown,
+  ours: unknown,
+  theirs: unknown,
+  inDepMap: boolean,
+): unknown | typeof UNRESOLVED | typeof ABSENT {
+  if (jsonEqual(ours, theirs)) return ours === undefined ? ABSENT : ours;
+  // Only one side diverged from base → that side wins (undefined = deletion).
+  if (jsonEqual(theirs, base)) return ours === undefined ? ABSENT : ours;
+  if (jsonEqual(ours, base)) return theirs === undefined ? ABSENT : theirs;
+  // Both diverged. Objects merge key-by-key; dep ranges take the newer
+  // minimum; everything else is a genuine conflict.
+  if (isPlainObject(ours) && isPlainObject(theirs)) {
+    const baseObject = isPlainObject(base) ? base : {};
+    const merged: Record<string, unknown> = {};
+    const keys = [...Object.keys(ours), ...Object.keys(theirs).filter((key) => !(key in ours))];
+    for (const key of keys) {
+      const child = mergeNode(
+        baseObject[key],
+        ours[key],
+        theirs[key],
+        inDepMap || DEP_MAP_KEYS.has(key),
+      );
+      if (child === UNRESOLVED) return UNRESOLVED;
+      if (child !== ABSENT) merged[key] = child;
+    }
+    return merged;
+  }
+  if (inDepMap) {
+    const oursMin = rangeMinimum(ours);
+    const theirsMin = rangeMinimum(theirs);
+    if (oursMin && theirsMin) {
+      for (let i = 0; i < 3; i++) {
+        if (oursMin[i]! > theirsMin[i]!) return ours;
+        if (oursMin[i]! < theirsMin[i]!) return theirs;
+      }
+      return theirs; // equal minimums, different spelling — template wins
+    }
+  }
+  return UNRESOLVED;
+}
+
+/** Structural three-way merge of package.json content. Returns the merged
+ *  object, or undefined when a divergence can't be auto-resolved (the file
+ *  then keeps its textual conflict markers for manual resolution). */
+export function threeWayMergePackageJson(
+  base: string | undefined,
+  ours: string,
+  theirs: string,
+): Record<string, unknown> | undefined {
+  let baseJson: unknown;
+  let oursJson: unknown;
+  let theirsJson: unknown;
+  try {
+    baseJson = base === undefined ? {} : JSON.parse(base);
+    oursJson = JSON.parse(ours);
+    theirsJson = JSON.parse(theirs);
+  } catch {
+    return undefined;
+  }
+  if (!isPlainObject(oursJson) || !isPlainObject(theirsJson)) return undefined;
+  const merged = mergeNode(baseJson, oursJson, theirsJson, false);
+  if (merged === UNRESOLVED || merged === ABSENT || !isPlainObject(merged)) return undefined;
+  return merged;
+}
+
+/** Replace auto-resolvable conflicted package.json files in `mergedTree`
+ *  with their structural merge. Pure index plumbing, worktree untouched. */
+async function autoResolveDependencyConflicts(
+  projectDir: string,
+  mergedTree: string,
+  conflicts: string[],
+  baseCommit: string,
+  headCommit: string,
+  nextCommit: string,
+): Promise<{ tree: string; conflicts: string[]; resolved: string[] }> {
+  const candidates = conflicts.filter((file) => basename(file) === "package.json");
+  if (!candidates.length) return { tree: mergedTree, conflicts, resolved: [] };
+
+  const scratch = mkdtempSync(join(tmpdir(), "mpo-resolve-"));
+  const resolved: { path: string; oid: string }[] = [];
+  try {
+    for (const file of candidates) {
+      const show = (commit: string) =>
+        gitOut(projectDir, ["show", `${commit}:${file}`]).catch(() => undefined);
+      const [base, ours, theirs] = await Promise.all([
+        show(baseCommit),
+        show(headCommit),
+        show(nextCommit),
+      ]);
+      // Add/delete conflicts stay manual — only both-sides-present merges.
+      if (ours === undefined || theirs === undefined) continue;
+      const merged = threeWayMergePackageJson(base, ours, theirs);
+      if (!merged) continue;
+      const blobFile = join(scratch, "blob.json");
+      writeFileSync(blobFile, `${JSON.stringify(merged, null, 2)}\n`);
+      const oid = await gitOut(projectDir, ["hash-object", "-w", "--", blobFile]);
+      resolved.push({ path: file, oid });
+    }
+    if (!resolved.length) return { tree: mergedTree, conflicts, resolved: [] };
+
+    const indexFile = join(scratch, "index");
+    const env = { GIT_INDEX_FILE: indexFile };
+    await git(projectDir, ["read-tree", mergedTree], env);
+    for (const entry of resolved) {
+      await git(
+        projectDir,
+        ["update-index", "--add", "--cacheinfo", `100644,${entry.oid},${entry.path}`],
+        env,
+      );
+    }
+    const tree = await gitOut(projectDir, ["write-tree"], env);
+    const resolvedPaths = new Set(resolved.map((entry) => entry.path));
+    return {
+      tree,
+      conflicts: conflicts.filter((file) => !resolvedPaths.has(file)),
+      resolved: [...resolvedPaths],
+    };
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
 export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
   const projectDir = await gitOut(process.cwd(), ["rev-parse", "--show-toplevel"]).catch(() => {
     throw new Error("mpo update must run inside a git repository");
@@ -212,15 +389,19 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
 
   console.log(`\nmpo update: ${provenance.cliVersion} → ${currentVersion}`);
   console.log(`  template: ${provenance.template}`);
+  if (provenance.pieces.length) console.log(`  pieces:   ${provenance.pieces.join(", ")}`);
   console.log(`  project:  ${provenance.name}\n`);
 
-  // 1. Regenerate the ORIGINAL scaffold (merge base).
+  // 1. Regenerate the ORIGINAL scaffold (merge base). Pieces recorded in
+  // provenance are reproduced in BOTH baselines so piece files merge as
+  // template content, not as phantom diffs.
   console.log(`Scaffolding merge base (cli@${provenance.cliVersion})...`);
   const base = await scaffoldBaseline(
     provenance.cliVersion,
     provenance.name,
     provenance.template,
     provenance.mpoVersion,
+    provenance.pieces,
   );
 
   // 2. Generate the CURRENT scaffold (theirs).
@@ -230,6 +411,7 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
     provenance.name,
     provenance.template,
     targetMpoRange,
+    provenance.pieces,
   );
 
   // .mpo.json is TOOL-owned, never merged: pre-provenance CLIs (≤6.3.0)
@@ -289,6 +471,7 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
       cliVersion: currentVersion,
       name: provenance.name,
       mpoVersion: targetMpoRange,
+      pieces: provenance.pieces,
     };
 
     // .updateignore pathspecs (+ pnpm-lock.yaml) pin to the pre-update HEAD.
@@ -309,6 +492,22 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
       (file) => !pins.some((pin) => file === pin || file.startsWith(`${pin}/`)),
     );
 
+    // Dependency-range drift in package.json files resolves mechanically
+    // (newer minimum version wins) — don't punt those to the user.
+    const autoResolved = await autoResolveDependencyConflicts(
+      projectDir,
+      mergedTree,
+      conflicts,
+      baseCommit,
+      head,
+      nextCommit,
+    );
+    mergedTree = autoResolved.tree;
+    conflicts = autoResolved.conflicts;
+    for (const file of autoResolved.resolved) {
+      console.log(`   auto-resolved: ${file} (dependency ranges)`);
+    }
+
     // No-op detection: identical trees mean the project already carries the
     // current template — don't stack empty merge commits.
     const headTree = await gitOut(projectDir, ["rev-parse", `${head}^{tree}`]);
@@ -332,6 +531,7 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
       return;
     }
 
+    let cleanMergeMessage: string | undefined;
     if (!conflicts.length) {
       const message = `chore: mpo update ${provenance.cliVersion} → ${currentVersion}`;
       const mergeCommit = await gitOut(projectDir, [
@@ -356,8 +556,7 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
       }
       await git(projectDir, ["add", "--", ".mpo.json", ".vscode"]);
       await git(projectDir, ["commit", "--amend", "--no-edit", "--quiet"]);
-      const amended = await gitOut(projectDir, ["rev-parse", "--short", "HEAD"]);
-      console.log(`\n✅ merged cleanly → ${amended} ("${message}")`);
+      cleanMergeMessage = message;
     } else {
       // Land the merged tree (with conflict markers) in index + worktree for
       // manual resolution; pins are already part of the tree.
@@ -389,6 +588,13 @@ export async function updateApp(options: UpdateAppOptions = {}): Promise<void> {
         }
       }
     }
+
+    // Reported last — the lockfile amend above rewrites the commit, so an
+    // earlier print would show a hash that no longer exists.
+    if (cleanMergeMessage) {
+      const finalHash = await gitOut(projectDir, ["rev-parse", "--short", "HEAD"]);
+      console.log(`\n✅ merged cleanly → ${finalHash} ("${cleanMergeMessage}")`);
+    }
   } finally {
     base.cleanup();
     next.cleanup();

package/templates/pieces/frappe/universal/README.md.partial

@@ -0,0 +1,32 @@
+## Frappe backend (`mpo init --frappe`)
+
+`apps/__NAME__/src/app.ts` wires `createApp({ frappe: … })`: the
+`FrappeProvider` mounts when `FRAPPE_ENABLED=1` and talks to `FRAPPE_URL`
+(both are `public` env keys in `packages/config/config.json`, loaded from
+`.env` — start from `.env.example`).
+
+Run a dev bench with docker:
+
+```bash
+docker compose -f docker/compose.frappe.yaml up -d
+docker compose -f docker/compose.frappe.yaml exec bench bash
+
+# inside the container (first time only)
+bench init --skip-redis-config-generation frappe-bench
+cd frappe-bench
+bench set-config -g db_host mariadb
+bench set-config -g redis_cache redis://redis-cache:6379
+bench set-config -g redis_queue redis://redis-queue:6379
+bench set-config -g redis_socketio redis://redis-queue:6379
+bench new-site __NAME__.localhost \
+  --mariadb-user-host-login-scope=% \
+  --db-root-password frappe --admin-password admin
+bench --site __NAME__.localhost set-config developer_mode 1
+
+# every dev session
+bench start
+```
+
+Then set `FRAPPE_URL=http://__NAME__.localhost:8000` (or keep
+`http://localhost:8000` and make the site the default with
+`bench use __NAME__.localhost`) and restart `pnpm dev`.

package/templates/pieces/frappe/universal/docker/compose.frappe.yaml

@@ -0,0 +1,52 @@
+# Dev Frappe bench for __NAME__ (mpo init --frappe).
+#
+#   docker compose -f docker/compose.frappe.yaml up -d
+#   docker compose -f docker/compose.frappe.yaml exec bench bash
+#
+# The frappe/bench image is a development sandbox (frappe user + bench
+# tooling); the bench itself is created ONCE inside the container — see the
+# "Frappe backend" section of the README for the init commands. State
+# persists in the named volumes.
+services:
+  bench:
+    image: frappe/bench:latest
+    command: sleep infinity
+    working_dir: /home/frappe
+    environment:
+      SHELL: /bin/bash
+    volumes:
+      - bench:/home/frappe
+    ports:
+      - "8000:8000" # bench serve (FRAPPE_URL)
+      - "9000:9000" # socket.io realtime
+    depends_on:
+      - mariadb
+      - redis-cache
+      - redis-queue
+
+  mariadb:
+    image: mariadb:10.6
+    command:
+      - --character-set-server=utf8mb4
+      - --collation-server=utf8mb4_unicode_ci
+      - --skip-character-set-client-handshake
+      - --skip-innodb-read-only-compressed
+    environment:
+      MARIADB_ROOT_PASSWORD: frappe
+    volumes:
+      - mariadb:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mariadb-admin", "ping", "-h", "127.0.0.1", "-uroot", "-pfrappe"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis-cache:
+    image: redis:alpine
+
+  redis-queue:
+    image: redis:alpine
+
+volumes:
+  bench: {}
+  mariadb: {}

package/templates/pieces/frappe/universal/env.example.partial

@@ -0,0 +1,8 @@
+# Frappe backend (mpo init --frappe) — copy to .env. Keys listed as `public`
+# in packages/config/config.json are baked into the client bundle at build
+# time (VITE_MP_CONFIG); FRAPPE_ENABLED=1 mounts the FrappeProvider wired in
+# apps/__NAME__/src/app.ts.
+FRAPPE_ENABLED=1
+# Bench URL the client talks to (docker/compose.frappe.yaml serves :8000).
+# Falls back to BASE_URL, then http://localhost:8000.
+FRAPPE_URL=http://localhost:8000

package/templates/pieces/frappe/universal/packages/config/config.json.partial

@@ -0,0 +1,3 @@
+{
+  "public": ["FRAPPE_ENABLED", "FRAPPE_URL"]
+}

package/templates/pieces/gnome/universal/README.md.partial

@@ -0,0 +1,68 @@
+## GNOME desktop (GTK4 / GJS)
+
+`mpo init --gnome` added a native GNOME target. Unlike the Tauri target,
+which ships the web build inside a system webview, this renders **real
+GTK4 widgets** through [react-gnome](https://github.com/react-gjs) — your
+Tamagui components become `Gtk.Widget`s laid out by Yoga, with no DOM
+anywhere in the process.
+
+### Prerequisites
+
+GJS and the GTK stack are system packages, not npm ones:
+
+```bash
+# Fedora / RHEL
+sudo dnf install gjs gtk4-devel libadwaita-devel gobject-introspection-devel
+
+# Debian / Ubuntu
+sudo apt install gjs libgtk-4-dev libadwaita-1-dev libgirepository1.0-dev
+
+# macOS (development only — GTK apps ship on Linux)
+brew install gjs gtk4 libadwaita gobject-introspection
+```
+
+On macOS, `gjs` needs the Homebrew libraries on its loader path:
+
+```bash
+export DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix gjs)/lib:$(brew --prefix)/lib"
+```
+
+### Run it
+
+```bash
+pnpm gnome            # build and open an interactive Adw.ApplicationWindow
+pnpm gnome:capture    # build, render, save a PNG, quit — works headless
+```
+
+`gnome:capture` writes `/tmp/__NAME__-gnome.png`. It polls for a render
+node across frames rather than waiting a fixed delay, because offscreen
+surfaces return null transiently after an invalidation — which is how you
+get a blank screenshot that looks like a broken app.
+
+### How it is wired
+
+| Path | Role |
+| --- | --- |
+| `apps/__NAME__/gnome/main.tsx` | Entry — Gtk init, Yoga, providers, window |
+| `apps/__NAME__/gnome/polyfills.ts` | Browser-API globals. **Must be the first import** |
+| `apps/__NAME__/gnome/tamagui-barrel.ts` | The granular `@tamagui/*` set this app reaches |
+| `apps/__NAME__/gnome/shims/` | Barrels narrowed to their GJS-safe subgraph |
+| `apps/__NAME__/vite.config.gnome.ts` | Separate library build → `dist/gnome/main.js` |
+
+Two things surprise people:
+
+**One's router is not mounted.** Its native path needs the React Native
+fabric renderer, which does not exist here. `gnome/shims/one.ts` backs
+`useRouter`, `usePathname` and `Link` with the framework's navigator seam
+instead. With no `Adw.NavigationView` attached it degrades — pushes are
+ignored, `Link` renders its children. Attach a navigation host and the
+same calls become real push/pop with the back button, Escape and
+swipe-back. Your screens do not change.
+
+**Barrels are aliased to shims.** The full `@multiplatform.one/components`
+barrel pulls expo-asset, flash-list and phosphor; `theme` pulls
+react-dom/server and node:fs. Those fail at module init, before a widget
+exists. The shims re-export only the GJS-safe subgraph, so adding a
+component is usually one line in a shim plus one granular `@tamagui/*`
+export in the barrel. A missing export is a build error naming the
+symbol.

package/templates/pieces/gnome/universal/apps/__NAME__/gnome/main.tsx

@@ -0,0 +1,165 @@
+// GNOME (GTK4 / GJS / libadwaita) entry for __NAME__.
+//
+// Renders the home screen inside a real Adw.ApplicationWindow via
+// react-gnome. Every box you see is an actual GTK widget laid out by Yoga
+// — there is no webview and no DOM.
+//
+//   pnpm gnome           interactive window
+//   pnpm gnome:capture   render, save a PNG, quit (works headless)
+//   gjs -m dist/gnome/main.js [outPath|interactive]
+//
+// ONE'S ROUTER IS NOT MOUNTED. Its native path goes through
+// react-native-screens, which needs the RN fabric renderer that does not
+// exist here. The index route's component is imported directly, and
+// gnome/shims/one.ts backs the router API the screens call. Give this
+// entry an Adw.NavigationView host when you want real push/pop.
+//
+// PROVIDERS. Only what the home screen consumes: Tamagui with the app's
+// real config, and i18next with the app's real resources. Add others as
+// screens need them — a provider whose graph reaches the DOM will fail at
+// module init, not at render.
+
+// Browser-API polyfills FIRST. Tamagui and RN-shaped dependencies probe
+// window/document/matchMedia at module-init time, and imports are hoisted
+// — first-import order is what guarantees the globals exist by then.
+import "./polyfills";
+
+import "gi://Gtk?version=4.0";
+import "gi://Adw?version=1";
+import Adw from "gi://Adw";
+import GLib from "gi://GLib";
+import Graphene from "gi://Graphene";
+import Gtk from "gi://Gtk";
+import {
+  AdwApplicationWindowElement,
+  AdwHeaderBar,
+  ToolbarView,
+  loadYogaForGjs,
+  render,
+  setYoga,
+} from "@react-gnome/renderer";
+import { HomeScreen } from "@features/__NAME__";
+import { resources } from "@package/i18n/resources";
+import i18n from "i18next";
+import React from "react";
+import { initReactI18next } from "react-i18next";
+import { config } from "../config/tamagui.config";
+import { TamaguiProvider } from "./tamagui-barrel";
+
+declare const ARGV: string[];
+declare const imports: { system: { exit(code: number): void } };
+
+// initImmediate:false makes init synchronous — resources are bundled, so
+// useTranslation must not suspend on first render.
+i18n.use(initReactI18next).init({
+  compatibilityJSON: "v4",
+  defaultNS: "common",
+  ns: ["common"],
+  fallbackLng: "en",
+  lng: "en",
+  resources,
+  interpolation: { escapeValue: false },
+  initImmediate: false,
+});
+
+const arg0 = typeof ARGV !== "undefined" ? ARGV[0] : undefined;
+const interactive = arg0 === "interactive" || arg0 === "i";
+const outPath = !interactive && arg0 ? arg0 : "/tmp/__NAME__-gnome.png";
+
+Gtk.init();
+setYoga(await loadYogaForGjs());
+
+function GnomeApp(): React.ReactElement {
+  return (
+    <TamaguiProvider config={config} defaultTheme="light">
+      <React.Suspense fallback={null}>
+        <HomeScreen />
+      </React.Suspense>
+    </TamaguiProvider>
+  );
+}
+
+const app = new Adw.Application({ applicationId: "one.multiplatform.__NAME_APPID__", flags: 0 });
+
+app.connect("activate", () => {
+  const window = new AdwApplicationWindowElement({
+    title: "__NAME_PASCAL__",
+    application: app,
+    defaultWidth: 900,
+    defaultHeight: 640,
+  });
+
+  render(
+    <ToolbarView>
+      <AdwHeaderBar toolbarSlot="top" />
+      <GnomeApp />
+    </ToolbarView>,
+    window,
+  );
+  window.widget.present();
+
+  if (interactive) return;
+
+  // Headless capture. A render node is transiently null on offscreen
+  // surfaces right after an invalidation, so poll across frames rather
+  // than trusting one fixed delay — a single timeout yields a blank PNG
+  // often enough to be useless as evidence.
+  const dir = outPath.substring(0, outPath.lastIndexOf("/")) || ".";
+  GLib.mkdir_with_parents(dir, 0o755);
+  const wait = Number.parseInt(GLib.getenv("RGN_WAIT") ?? "800", 10);
+  GLib.timeout_add(GLib.PRIORITY_DEFAULT, wait, () => {
+    const widget = window.widget as Gtk.Widget & {
+      get_width(): number;
+      get_height(): number;
+      get_native(): Gtk.Native | null;
+      queue_draw(): void;
+    };
+    const WidgetPaintable = (
+      Gtk as unknown as { WidgetPaintable: { new: (w: Gtk.Widget) => unknown } }
+    ).WidgetPaintable;
+    let tries = 0;
+    const poll = (): boolean => {
+      try {
+        const width = widget.get_width();
+        const height = widget.get_height();
+        if (width > 0 && height > 0) {
+          const paintable = WidgetPaintable.new(widget) as {
+            snapshot(s: Gtk.Snapshot, w: number, h: number): void;
+          };
+          const snapshot = new Gtk.Snapshot();
+          paintable.snapshot(snapshot, width, height);
+          const node = snapshot.to_node();
+          if (node) {
+            const renderer = widget.get_native()?.get_renderer();
+            if (!renderer) throw new Error("no Gsk.Renderer attached to the window");
+            const viewport = new Graphene.Rect();
+            viewport.init(0, 0, width, height);
+            renderer.render_texture(node, viewport).save_to_png(outPath);
+            console.log(`captured ${width}x${height} -> ${outPath}`);
+            app.quit();
+            return GLib.SOURCE_REMOVE;
+          }
+        }
+        if (++tries >= 80) {
+          console.error(`snapshot produced no render node after ${tries} frames`);
+          app.quit();
+          imports.system.exit(4);
+          return GLib.SOURCE_REMOVE;
+        }
+        widget.queue_draw();
+        return GLib.SOURCE_CONTINUE;
+      } catch (e) {
+        console.error(`snapshot failed: ${String(e)}`);
+        app.quit();
+        imports.system.exit(5);
+        return GLib.SOURCE_REMOVE;
+      }
+    };
+    if (poll() !== GLib.SOURCE_REMOVE) {
+      GLib.timeout_add(GLib.PRIORITY_DEFAULT, 100, poll);
+    }
+    return GLib.SOURCE_REMOVE;
+  });
+});
+
+app.run([]);

package/templates/pieces/gnome/universal/apps/__NAME__/gnome/polyfills.ts

@@ -0,0 +1,10 @@
+// Browser-API polyfills for the GNOME target. MUST be the first import of
+// gnome/main.tsx: JS imports are hoisted, so first-import order is what
+// guarantees window/document/matchMedia/URL exist before Tamagui and the
+// RN-shaped dependencies probe for them at module-init time.
+//
+// The implementation is packaged — @react-gnome/react-native/polyfills
+// installs each global conditionally, so anything you define before this
+// import wins. Keep this file as the app's stable local import point.
+
+import "@react-gnome/react-native/polyfills";