react-native-gtkx 0.2.0-alpha.1 → 0.3.0-alpha.1

package/dist/mcp/server.js

@@ -98,7 +98,7 @@ const searchDocsTool = () => defineTool({
     name: "rn_gtkx_search_docs",
     title: "Search react-native-gtkx docs",
     description: "Free-text search over the docs (getting-started, the platform layer, " +
-        "gtkx rc.2 workarounds/quirks, navigation). The fallback tool: use it " +
+        "gtkx rc.3 workarounds/quirks, navigation). The fallback tool: use it " +
         "for symptoms and known-issue questions that rn_gtkx_describe_component " +
         "cannot answer by name (workarounds are keyed by mechanism, not by " +
         "component).",

package/dist/mcp/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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","sourcesContent":["// The MCP server itself: three tools over stdio, backed entirely by the\n// generated data in ./data/generated.ts — no @gtkx/* import anywhere in\n// this module or its dependents, so this runs on any OS without GTK\n// installed (an agent reading a react-native-gtkx project on a Mac, for\n// instance). See docs/getting-started.md for how a consumer registers it.\nimport { createRequire } from \"node:module\"\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"\nimport { z } from \"zod\"\nimport { listSurface, SURFACE_AREAS } from \"./list.js\"\nimport { formatEntity, resolveComponent } from \"./resolve.js\"\nimport { searchDocs } from \"./search.js\"\nimport {\n  defineTool,\n  registerTool,\n  textContent,\n  textError,\n  type Tool,\n} from \"./tool.js\"\n\nconst require = createRequire(import.meta.url)\n// Package root is two levels up from dist/mcp/server.js (dist/mcp -> dist\n// -> package root). package.json ships in every npm tarball regardless of\n// the \"files\" allowlist, so this needs no extra packaging step.\nconst { version } = require(\"../../package.json\") as { version: string }\n\nconst SERVER_NAME = \"react-native-gtkx-mcp\"\nconst DEFAULT_SEARCH_LIMIT = 10\nconst MAX_SEARCH_LIMIT = 20\n\nconst listSurfaceShape = {\n  area: z\n    .enum(SURFACE_AREAS)\n    .optional()\n    .describe(\n      \"Area to list. Omit for an overview with counts across all areas: \" +\n        SURFACE_AREAS.join(\", \") +\n        \".\",\n    ),\n}\n\nconst describeComponentShape = {\n  name: z\n    .string()\n    .describe(\n      \"A component/API/widget name: a portable react-native export (e.g. \" +\n        '\"FlatList\"), a react-native-gtkx/gtk or /adw widget with or ' +\n        'without its Gtk/Adw prefix (e.g. \"Popover\" resolves to ' +\n        '\"GtkPopover\"), or a react-native-gtkx/common export (e.g. ' +\n        '\"NavigationStack\"). Case-insensitive.',\n    ),\n}\n\nconst searchDocsShape = {\n  query: z\n    .string()\n    .describe(\n      \"Free-text query — a symptom, a GTK term, an option name. Use this \" +\n        \"when rn_gtkx_describe_component does not have a name to look up, \" +\n        'e.g. \"known issues\", \"chrome content\", \"windowSize\".',\n    ),\n  limit: z\n    .number()\n    .int()\n    .min(1)\n    .max(MAX_SEARCH_LIMIT)\n    .optional()\n    .describe(\n      `Maximum number of results (default ${DEFAULT_SEARCH_LIMIT}, max ${MAX_SEARCH_LIMIT}).`,\n    ),\n}\n\nconst listSurfaceTool = (): Tool =>\n  defineTool({\n    name: \"rn_gtkx_list_surface\",\n    title: \"List the react-native-gtkx surface\",\n    description:\n      \"Browse the react-native-gtkx surface without knowing an exact name first: \" +\n      \"portable react-native components/APIs, the react-native-gtkx/gtk and \" +\n      \"/adw widget lists (wrapped vs. raw), and react-native-gtkx/common. \" +\n      \"Without `area`, returns counts and where to look next.\",\n    inputSchema: listSurfaceShape,\n    handler: ({ area }) => textContent(listSurface(area)),\n  })\n\nconst describeComponentTool = (): Tool =>\n  defineTool({\n    name: \"rn_gtkx_describe_component\",\n    title: \"Describe a react-native-gtkx component\",\n    description:\n      \"Look up one component/widget/API by name: does it exist, which \" +\n      \"subpath it is exported from, what GTK widget backs it (for \" +\n      \"portable components), what differs from React Native, and whether \" +\n      \"a gtk/adw widget is wrapped (takes `style`/`onLayout`) or raw. The \" +\n      \"single most useful tool here — start with this before \" +\n      \"rn_gtkx_search_docs.\",\n    inputSchema: describeComponentShape,\n    handler: ({ name }) => {\n      const result = resolveComponent(name)\n      if (result.status === \"resolved\") {\n        const body = {\n          matchedBy: result.matchedBy,\n          ...formatEntity(result.entity),\n        }\n        return textContent(JSON.stringify(body, null, 2))\n      }\n      if (result.status === \"ambiguous\") {\n        const lines = result.candidates\n          .map((c) => `- ${c.name} (${c.subpath}, ${c.kind})`)\n          .join(\"\\n\")\n        return textError(\n          `\"${result.query}\" matches ${result.candidates.length} names — call again with one of:\\n${lines}`,\n        )\n      }\n      const lines = result.suggestions\n        .map((c) => `- ${c.name} (${c.subpath}, ${c.kind})`)\n        .join(\"\\n\")\n      return textError(\n        `No component named \"${result.query}\".` +\n          (lines.length > 0\n            ? ` Closest known names:\\n${lines}`\n            : \" rn_gtkx_list_surface has the full index.\"),\n      )\n    },\n  })\n\nconst searchDocsTool = (): Tool =>\n  defineTool({\n    name: \"rn_gtkx_search_docs\",\n    title: \"Search react-native-gtkx docs\",\n    description:\n      \"Free-text search over the docs (getting-started, the platform layer, \" +\n      \"gtkx rc.2 workarounds/quirks, navigation). The fallback tool: use it \" +\n      \"for symptoms and known-issue questions that rn_gtkx_describe_component \" +\n      \"cannot answer by name (workarounds are keyed by mechanism, not by \" +\n      \"component).\",\n    inputSchema: searchDocsShape,\n    handler: ({ query, limit }) => {\n      const results = searchDocs(query, limit ?? DEFAULT_SEARCH_LIMIT)\n      if (results.length === 0) {\n        return textContent(\n          `No matches for \"${query}\". Try rn_gtkx_list_surface or rn_gtkx_describe_component instead.`,\n        )\n      }\n      const body = results\n        .map((r) => `## ${r.doc} — ${r.heading}\\n\\n${r.text}`)\n        .join(\"\\n\\n---\\n\\n\")\n      return textContent(body)\n    },\n  })\n\nconst buildTools = (): Tool[] => [\n  listSurfaceTool(),\n  describeComponentTool(),\n  searchDocsTool(),\n]\n\nconst createMcpServer = (): McpServer => {\n  const server = new McpServer({ name: SERVER_NAME, version })\n  for (const tool of buildTools()) {\n    registerTool(server, tool)\n  }\n  return server\n}\n\nconst main = async (): Promise<void> => {\n  const server = createMcpServer()\n  const transport = new StdioServerTransport()\n  await server.connect(transport)\n}\n\nexport { buildTools, createMcpServer, main, SERVER_NAME }\n"]}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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","sourcesContent":["// The MCP server itself: three tools over stdio, backed entirely by the\n// generated data in ./data/generated.ts — no @gtkx/* import anywhere in\n// this module or its dependents, so this runs on any OS without GTK\n// installed (an agent reading a react-native-gtkx project on a Mac, for\n// instance). See docs/getting-started.md for how a consumer registers it.\nimport { createRequire } from \"node:module\"\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\"\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\"\nimport { z } from \"zod\"\nimport { listSurface, SURFACE_AREAS } from \"./list.js\"\nimport { formatEntity, resolveComponent } from \"./resolve.js\"\nimport { searchDocs } from \"./search.js\"\nimport {\n  defineTool,\n  registerTool,\n  textContent,\n  textError,\n  type Tool,\n} from \"./tool.js\"\n\nconst require = createRequire(import.meta.url)\n// Package root is two levels up from dist/mcp/server.js (dist/mcp -> dist\n// -> package root). package.json ships in every npm tarball regardless of\n// the \"files\" allowlist, so this needs no extra packaging step.\nconst { version } = require(\"../../package.json\") as { version: string }\n\nconst SERVER_NAME = \"react-native-gtkx-mcp\"\nconst DEFAULT_SEARCH_LIMIT = 10\nconst MAX_SEARCH_LIMIT = 20\n\nconst listSurfaceShape = {\n  area: z\n    .enum(SURFACE_AREAS)\n    .optional()\n    .describe(\n      \"Area to list. Omit for an overview with counts across all areas: \" +\n        SURFACE_AREAS.join(\", \") +\n        \".\",\n    ),\n}\n\nconst describeComponentShape = {\n  name: z\n    .string()\n    .describe(\n      \"A component/API/widget name: a portable react-native export (e.g. \" +\n        '\"FlatList\"), a react-native-gtkx/gtk or /adw widget with or ' +\n        'without its Gtk/Adw prefix (e.g. \"Popover\" resolves to ' +\n        '\"GtkPopover\"), or a react-native-gtkx/common export (e.g. ' +\n        '\"NavigationStack\"). Case-insensitive.',\n    ),\n}\n\nconst searchDocsShape = {\n  query: z\n    .string()\n    .describe(\n      \"Free-text query — a symptom, a GTK term, an option name. Use this \" +\n        \"when rn_gtkx_describe_component does not have a name to look up, \" +\n        'e.g. \"known issues\", \"chrome content\", \"windowSize\".',\n    ),\n  limit: z\n    .number()\n    .int()\n    .min(1)\n    .max(MAX_SEARCH_LIMIT)\n    .optional()\n    .describe(\n      `Maximum number of results (default ${DEFAULT_SEARCH_LIMIT}, max ${MAX_SEARCH_LIMIT}).`,\n    ),\n}\n\nconst listSurfaceTool = (): Tool =>\n  defineTool({\n    name: \"rn_gtkx_list_surface\",\n    title: \"List the react-native-gtkx surface\",\n    description:\n      \"Browse the react-native-gtkx surface without knowing an exact name first: \" +\n      \"portable react-native components/APIs, the react-native-gtkx/gtk and \" +\n      \"/adw widget lists (wrapped vs. raw), and react-native-gtkx/common. \" +\n      \"Without `area`, returns counts and where to look next.\",\n    inputSchema: listSurfaceShape,\n    handler: ({ area }) => textContent(listSurface(area)),\n  })\n\nconst describeComponentTool = (): Tool =>\n  defineTool({\n    name: \"rn_gtkx_describe_component\",\n    title: \"Describe a react-native-gtkx component\",\n    description:\n      \"Look up one component/widget/API by name: does it exist, which \" +\n      \"subpath it is exported from, what GTK widget backs it (for \" +\n      \"portable components), what differs from React Native, and whether \" +\n      \"a gtk/adw widget is wrapped (takes `style`/`onLayout`) or raw. The \" +\n      \"single most useful tool here — start with this before \" +\n      \"rn_gtkx_search_docs.\",\n    inputSchema: describeComponentShape,\n    handler: ({ name }) => {\n      const result = resolveComponent(name)\n      if (result.status === \"resolved\") {\n        const body = {\n          matchedBy: result.matchedBy,\n          ...formatEntity(result.entity),\n        }\n        return textContent(JSON.stringify(body, null, 2))\n      }\n      if (result.status === \"ambiguous\") {\n        const lines = result.candidates\n          .map((c) => `- ${c.name} (${c.subpath}, ${c.kind})`)\n          .join(\"\\n\")\n        return textError(\n          `\"${result.query}\" matches ${result.candidates.length} names — call again with one of:\\n${lines}`,\n        )\n      }\n      const lines = result.suggestions\n        .map((c) => `- ${c.name} (${c.subpath}, ${c.kind})`)\n        .join(\"\\n\")\n      return textError(\n        `No component named \"${result.query}\".` +\n          (lines.length > 0\n            ? ` Closest known names:\\n${lines}`\n            : \" rn_gtkx_list_surface has the full index.\"),\n      )\n    },\n  })\n\nconst searchDocsTool = (): Tool =>\n  defineTool({\n    name: \"rn_gtkx_search_docs\",\n    title: \"Search react-native-gtkx docs\",\n    description:\n      \"Free-text search over the docs (getting-started, the platform layer, \" +\n      \"gtkx rc.3 workarounds/quirks, navigation). The fallback tool: use it \" +\n      \"for symptoms and known-issue questions that rn_gtkx_describe_component \" +\n      \"cannot answer by name (workarounds are keyed by mechanism, not by \" +\n      \"component).\",\n    inputSchema: searchDocsShape,\n    handler: ({ query, limit }) => {\n      const results = searchDocs(query, limit ?? DEFAULT_SEARCH_LIMIT)\n      if (results.length === 0) {\n        return textContent(\n          `No matches for \"${query}\". Try rn_gtkx_list_surface or rn_gtkx_describe_component instead.`,\n        )\n      }\n      const body = results\n        .map((r) => `## ${r.doc} — ${r.heading}\\n\\n${r.text}`)\n        .join(\"\\n\\n---\\n\\n\")\n      return textContent(body)\n    },\n  })\n\nconst buildTools = (): Tool[] => [\n  listSurfaceTool(),\n  describeComponentTool(),\n  searchDocsTool(),\n]\n\nconst createMcpServer = (): McpServer => {\n  const server = new McpServer({ name: SERVER_NAME, version })\n  for (const tool of buildTools()) {\n    registerTool(server, tool)\n  }\n  return server\n}\n\nconst main = async (): Promise<void> => {\n  const server = createMcpServer()\n  const transport = new StdioServerTransport()\n  await server.connect(transport)\n}\n\nexport { buildTools, createMcpServer, main, SERVER_NAME }\n"]}

package/dist/metro/index.d.ts

@@ -1,3 +1,6 @@
+import { type AliasOverrides } from "../aliases/index.js";
+export { CONFIGURABLE_ALIASES, DEFAULT_ALIASES, PLATFORM_ALIAS, } from "../aliases/index.js";
+export type { AliasOverride, AliasOverrides, AliasPattern, AliasTable, CompiledAlias, } from "../aliases/index.js";
 /** Modules the run-linux host provides to the bundle at runtime. */
 export declare const HOST_MODULE_EXTERNALS: string[];
 export declare const LINUX_PLATFORM = "linux";
@@ -24,6 +27,13 @@ export type LinuxPlatformOptions = {
     externals?: readonly string[];
     /** Proxy directory override (default: node_modules/.react-native-gtkx). */
     proxyDir?: string;
+    /**
+     * Deltas over the preset's package aliases, keyed by package name — a
+     * string target, a `{ pattern, replace }` rule, or `false` to drop one of
+     * ours so the real package loads. See ../aliases/index.ts and docs/api.md.
+     * Invalid entries throw here, while the config is being read.
+     */
+    aliases?: AliasOverrides;
 };
 export type LinuxPlatformConfig<T extends MetroLikeConfig> = T & {
     resolver: {

package/dist/metro/index.js

@@ -8,7 +8,9 @@
 //    Platform.OS come along with it).
 // 2. Redirects `react-native` (and subpaths) to `react-native-gtkx` — the
 //    out-of-tree npmPackageName declaration alone does not alias imports
-//    for `bundle`, the resolver has to.
+//    for `bundle`, the resolver has to — plus five package substitutions
+//    for libraries whose real implementation cannot run here. The rules
+//    are data, shared with the vite preset: see ../aliases/index.ts.
 // 3. EXTERNALIZES host-side singletons. Unlike react-native-windows, whose
 //    native side lives outside the JS bundle by construction, our "native"
 //    is Node modules with NAPI bindings (@gtkx/*) plus yoga-layout's WASM —
@@ -24,6 +26,11 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { builtinModules, isBuiltin } from "node:module";
 import { join } from "node:path";
+// Explicit .js: bare Node loads metro.config.ts and does not guess extensions.
+import { applyAliases, compileAliases, } from "../aliases/index.js";
+// Re-exported so an app configuring `aliases` never has to reach past the
+// preset subpath it already imports.
+export { CONFIGURABLE_ALIASES, DEFAULT_ALIASES, PLATFORM_ALIAS, } from "../aliases/index.js";
 /** Modules the run-linux host provides to the bundle at runtime. */
 export const HOST_MODULE_EXTERNALS = [
     "@gtkx/css",
@@ -80,6 +87,9 @@ export const withLinuxPlatform = (config, options = {}) => {
     const proxyDir = options.proxyDir ??
         join(config.projectRoot ?? process.cwd(), "node_modules", ".react-native-gtkx", "metro-externals");
     generateProxies(proxyDir, externals);
+    // Throws on an unknown key, an overlapping pattern or an attempt to remove
+    // the platform alias — at config load, naming what is valid.
+    const aliases = compileAliases(options.aliases);
     const previousResolve = config.resolver?.resolveRequest ?? null;
     const fallback = (context, moduleName, platform) => previousResolve
         ? previousResolve(context, moduleName, platform)
@@ -94,17 +104,16 @@ export const withLinuxPlatform = (config, options = {}) => {
                 filePath: join(proxyDir, sanitize(moduleName)),
             };
         }
-        if (moduleName === "react-native" ||
-            moduleName.startsWith("react-native/")) {
-            return fallback(context, moduleName.replace(/^react-native/, "react-native-gtkx"), platform);
-        }
-        // Same alias, same guard shape, for the SVG compat subpath (see
-        // src/svg-compat/index.ts and the vite preset's rewriteReactNativeImport
-        // — kept in sync deliberately rather than sharing code, Metro and vite
-        // resolvers have never shared an implementation in this package).
-        if (moduleName === "react-native-svg" ||
-            moduleName.startsWith("react-native-svg/")) {
-            return fallback(context, moduleName.replace(/^react-native-svg/, "react-native-gtkx/svg"), platform);
+        // The five package substitutions plus the platform alias, from the table
+        // both presets share (../aliases/index.ts). Each rule is anchored to its
+        // package name and matches the exact name or a slash-prefixed subpath,
+        // with the tail transplanted onto the target — the guard, not just the
+        // order, is what keeps `react-native-reanimated-dnd` out of the
+        // `react-native-reanimated` rule and the real, unrelated
+        // `react-native-worklets-core` out of the `react-native-worklets` one.
+        const aliased = applyAliases(aliases, moduleName);
+        if (aliased !== null) {
+            return fallback(context, aliased, platform);
         }
         return fallback(context, moduleName, platform);
     };

package/dist/metro/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metro/index.ts"],"names":[],"mappings":"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","sourcesContent":["// Metro preset for the linux out-of-tree platform: wrap the app's Metro\n// config with `withLinuxPlatform` and the standard RN toolchain bundles for\n// `--platform linux`.\n//\n// What it does on top of RN defaults (validated by spike/rn-platform):\n//\n// 1. Adds \"linux\" to resolver.platforms (`.linux.tsx` extensions and\n//    Platform.OS come along with it).\n// 2. Redirects `react-native` (and subpaths) to `react-native-gtkx` — the\n//    out-of-tree npmPackageName declaration alone does not alias imports\n//    for `bundle`, the resolver has to.\n// 3. EXTERNALIZES host-side singletons. Unlike react-native-windows, whose\n//    native side lives outside the JS bundle by construction, our \"native\"\n//    is Node modules with NAPI bindings (@gtkx/*) plus yoga-layout's WASM —\n//    Metro cannot bundle those. react (and its jsx runtimes) must also stay\n//    host-side: the reconciler inside @gtkx/react and the app have to share\n//    one React instance. Every external resolves to a generated proxy that\n//    reads the real module from global.__hostModules — the run-linux host\n//    injects them before executing the bundle.\n// 4. Proxies Node builtins through the host's require: apps on this\n//    platform may use the whole Node API, it is a platform feature.\n// 5. Drops InitializeCore (RN's mobile environment polyfills): the runtime\n//    environment IS Node, the host provides everything.\nimport { mkdirSync, writeFileSync } from \"node:fs\"\nimport { builtinModules, isBuiltin } from \"node:module\"\nimport { join } from \"node:path\"\n\n/** Modules the run-linux host provides to the bundle at runtime. */\nexport const HOST_MODULE_EXTERNALS = [\n  \"@gtkx/css\",\n  \"@gtkx/gi/adw\",\n  \"@gtkx/gi/gdk\",\n  \"@gtkx/gi/gio\",\n  \"@gtkx/gi/glib\",\n  \"@gtkx/gi/gobject\",\n  \"@gtkx/gi/graphene\",\n  \"@gtkx/gi/gsk\",\n  \"@gtkx/gi/gtk\",\n  \"@gtkx/gi/pango\",\n  \"@gtkx/jsx/adw\",\n  \"@gtkx/jsx/gio\",\n  \"@gtkx/jsx/gtk\",\n  \"@gtkx/react\",\n  \"@gtkx/react/internal\",\n  \"@gtkx/runtime\",\n  \"react\",\n  \"react/jsx-runtime\",\n  \"react/jsx-dev-runtime\",\n  \"yoga-layout\",\n]\n\nexport const LINUX_PLATFORM = \"linux\"\n\n// Structural slices of Metro's config/resolution types: Metro is the app's\n// dependency, not ours — depending on its types here would pin versions.\nexport type MetroResolutionContext = {\n  resolveRequest: MetroResolver\n}\nexport type MetroResolution = { type: string; filePath?: string }\nexport type MetroResolver = (\n  context: MetroResolutionContext,\n  moduleName: string,\n  platform: string | null,\n) => MetroResolution\n\nexport type MetroLikeConfig = {\n  projectRoot?: string\n  resolver?: {\n    platforms?: readonly string[]\n    resolveRequest?: MetroResolver | null\n  }\n  serializer?: {\n    getModulesRunBeforeMainModule?: (entryFilePath: string) => string[]\n  }\n}\n\nexport type LinuxPlatformOptions = {\n  /** Extra host-provided modules to keep out of the bundle. */\n  externals?: readonly string[]\n  /** Proxy directory override (default: node_modules/.react-native-gtkx). */\n  proxyDir?: string\n}\n\nconst sanitize = (name: string): string => name.replace(/[@/:]/g, \"_\") + \".js\"\n\nconst hostModuleProxy = (name: string): string =>\n  // The run-linux host guarantees __hostModules before executing the bundle.\n  `module.exports = global.__hostModules[${JSON.stringify(name)}]\\n`\n\nconst builtinProxy = (name: string): string =>\n  `module.exports = global.__hostRequire(${JSON.stringify(name)})\\n`\n\n// Every proxy is generated eagerly when the config loads: Metro crawls the\n// file map before transforming, and files that appear mid-build lose the\n// race (\"Failed to get the SHA-1\"). The builtin list is finite, so the\n// whole proxy set can exist up front.\nconst generateProxies = (dir: string, externals: Set<string>): void => {\n  mkdirSync(dir, { recursive: true })\n  for (const name of externals) {\n    writeFileSync(join(dir, sanitize(name)), hostModuleProxy(name))\n  }\n  for (const bare of builtinModules) {\n    writeFileSync(join(dir, sanitize(bare)), builtinProxy(bare))\n    writeFileSync(\n      join(dir, sanitize(`node:${bare}`)),\n      builtinProxy(`node:${bare}`),\n    )\n  }\n}\n\nexport type LinuxPlatformConfig<T extends MetroLikeConfig> = T & {\n  resolver: {\n    platforms: string[]\n    resolveRequest: MetroResolver\n  }\n  serializer: {\n    getModulesRunBeforeMainModule: (entryFilePath: string) => string[]\n  }\n}\n\n/**\n * Wraps a Metro config (RN's getDefaultConfig output) with everything the\n * linux platform needs. Composes with an existing custom resolveRequest —\n * non-linux platforms fall through to it untouched.\n */\nexport const withLinuxPlatform = <T extends MetroLikeConfig>(\n  config: T,\n  options: LinuxPlatformOptions = {},\n): LinuxPlatformConfig<T> => {\n  const externals = new Set([\n    ...HOST_MODULE_EXTERNALS,\n    ...(options.externals ?? []),\n  ])\n  const proxyDir =\n    options.proxyDir ??\n    join(\n      config.projectRoot ?? process.cwd(),\n      \"node_modules\",\n      \".react-native-gtkx\",\n      \"metro-externals\",\n    )\n  generateProxies(proxyDir, externals)\n  const previousResolve = config.resolver?.resolveRequest ?? null\n\n  const fallback: MetroResolver = (context, moduleName, platform) =>\n    previousResolve\n      ? previousResolve(context, moduleName, platform)\n      : context.resolveRequest(context, moduleName, platform)\n\n  const resolveRequest: MetroResolver = (context, moduleName, platform) => {\n    if (platform !== LINUX_PLATFORM) {\n      return fallback(context, moduleName, platform)\n    }\n    if (externals.has(moduleName) || isBuiltin(moduleName)) {\n      return {\n        type: \"sourceFile\",\n        filePath: join(proxyDir, sanitize(moduleName)),\n      }\n    }\n    if (\n      moduleName === \"react-native\" ||\n      moduleName.startsWith(\"react-native/\")\n    ) {\n      return fallback(\n        context,\n        moduleName.replace(/^react-native/, \"react-native-gtkx\"),\n        platform,\n      )\n    }\n    // Same alias, same guard shape, for the SVG compat subpath (see\n    // src/svg-compat/index.ts and the vite preset's rewriteReactNativeImport\n    // — kept in sync deliberately rather than sharing code, Metro and vite\n    // resolvers have never shared an implementation in this package).\n    if (\n      moduleName === \"react-native-svg\" ||\n      moduleName.startsWith(\"react-native-svg/\")\n    ) {\n      return fallback(\n        context,\n        moduleName.replace(/^react-native-svg/, \"react-native-gtkx/svg\"),\n        platform,\n      )\n    }\n    return fallback(context, moduleName, platform)\n  }\n\n  // The cast: T may carry narrower resolver/serializer types than the ones\n  // rebuilt here — the runtime shape is a strict superset of both.\n  return {\n    ...config,\n    resolver: {\n      ...config.resolver,\n      platforms: [\n        ...new Set([...(config.resolver?.platforms ?? []), LINUX_PLATFORM]),\n      ],\n      resolveRequest,\n    },\n    serializer: {\n      ...config.serializer,\n      // RN prepends InitializeCore (Hermes Promise, nativeLoggingHook\n      // console...). Our runtime environment IS Node — nothing to\n      // initialize inside the bundle.\n      getModulesRunBeforeMainModule: () => [],\n    },\n  } as LinuxPlatformConfig<T>\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/metro/index.ts"],"names":[],"mappings":"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","sourcesContent":["// Metro preset for the linux out-of-tree platform: wrap the app's Metro\n// config with `withLinuxPlatform` and the standard RN toolchain bundles for\n// `--platform linux`.\n//\n// What it does on top of RN defaults (validated by spike/rn-platform):\n//\n// 1. Adds \"linux\" to resolver.platforms (`.linux.tsx` extensions and\n//    Platform.OS come along with it).\n// 2. Redirects `react-native` (and subpaths) to `react-native-gtkx` — the\n//    out-of-tree npmPackageName declaration alone does not alias imports\n//    for `bundle`, the resolver has to — plus five package substitutions\n//    for libraries whose real implementation cannot run here. The rules\n//    are data, shared with the vite preset: see ../aliases/index.ts.\n// 3. EXTERNALIZES host-side singletons. Unlike react-native-windows, whose\n//    native side lives outside the JS bundle by construction, our \"native\"\n//    is Node modules with NAPI bindings (@gtkx/*) plus yoga-layout's WASM —\n//    Metro cannot bundle those. react (and its jsx runtimes) must also stay\n//    host-side: the reconciler inside @gtkx/react and the app have to share\n//    one React instance. Every external resolves to a generated proxy that\n//    reads the real module from global.__hostModules — the run-linux host\n//    injects them before executing the bundle.\n// 4. Proxies Node builtins through the host's require: apps on this\n//    platform may use the whole Node API, it is a platform feature.\n// 5. Drops InitializeCore (RN's mobile environment polyfills): the runtime\n//    environment IS Node, the host provides everything.\nimport { mkdirSync, writeFileSync } from \"node:fs\"\nimport { builtinModules, isBuiltin } from \"node:module\"\nimport { join } from \"node:path\"\n// Explicit .js: bare Node loads metro.config.ts and does not guess extensions.\nimport {\n  applyAliases,\n  compileAliases,\n  type AliasOverrides,\n} from \"../aliases/index.js\"\n\n// Re-exported so an app configuring `aliases` never has to reach past the\n// preset subpath it already imports.\nexport {\n  CONFIGURABLE_ALIASES,\n  DEFAULT_ALIASES,\n  PLATFORM_ALIAS,\n} from \"../aliases/index.js\"\nexport type {\n  AliasOverride,\n  AliasOverrides,\n  AliasPattern,\n  AliasTable,\n  CompiledAlias,\n} from \"../aliases/index.js\"\n\n/** Modules the run-linux host provides to the bundle at runtime. */\nexport const HOST_MODULE_EXTERNALS = [\n  \"@gtkx/css\",\n  \"@gtkx/gi/adw\",\n  \"@gtkx/gi/gdk\",\n  \"@gtkx/gi/gio\",\n  \"@gtkx/gi/glib\",\n  \"@gtkx/gi/gobject\",\n  \"@gtkx/gi/graphene\",\n  \"@gtkx/gi/gsk\",\n  \"@gtkx/gi/gtk\",\n  \"@gtkx/gi/pango\",\n  \"@gtkx/jsx/adw\",\n  \"@gtkx/jsx/gio\",\n  \"@gtkx/jsx/gtk\",\n  \"@gtkx/react\",\n  \"@gtkx/react/internal\",\n  \"@gtkx/runtime\",\n  \"react\",\n  \"react/jsx-runtime\",\n  \"react/jsx-dev-runtime\",\n  \"yoga-layout\",\n]\n\nexport const LINUX_PLATFORM = \"linux\"\n\n// Structural slices of Metro's config/resolution types: Metro is the app's\n// dependency, not ours — depending on its types here would pin versions.\nexport type MetroResolutionContext = {\n  resolveRequest: MetroResolver\n}\nexport type MetroResolution = { type: string; filePath?: string }\nexport type MetroResolver = (\n  context: MetroResolutionContext,\n  moduleName: string,\n  platform: string | null,\n) => MetroResolution\n\nexport type MetroLikeConfig = {\n  projectRoot?: string\n  resolver?: {\n    platforms?: readonly string[]\n    resolveRequest?: MetroResolver | null\n  }\n  serializer?: {\n    getModulesRunBeforeMainModule?: (entryFilePath: string) => string[]\n  }\n}\n\nexport type LinuxPlatformOptions = {\n  /** Extra host-provided modules to keep out of the bundle. */\n  externals?: readonly string[]\n  /** Proxy directory override (default: node_modules/.react-native-gtkx). */\n  proxyDir?: string\n  /**\n   * Deltas over the preset's package aliases, keyed by package name — a\n   * string target, a `{ pattern, replace }` rule, or `false` to drop one of\n   * ours so the real package loads. See ../aliases/index.ts and docs/api.md.\n   * Invalid entries throw here, while the config is being read.\n   */\n  aliases?: AliasOverrides\n}\n\nconst sanitize = (name: string): string => name.replace(/[@/:]/g, \"_\") + \".js\"\n\nconst hostModuleProxy = (name: string): string =>\n  // The run-linux host guarantees __hostModules before executing the bundle.\n  `module.exports = global.__hostModules[${JSON.stringify(name)}]\\n`\n\nconst builtinProxy = (name: string): string =>\n  `module.exports = global.__hostRequire(${JSON.stringify(name)})\\n`\n\n// Every proxy is generated eagerly when the config loads: Metro crawls the\n// file map before transforming, and files that appear mid-build lose the\n// race (\"Failed to get the SHA-1\"). The builtin list is finite, so the\n// whole proxy set can exist up front.\nconst generateProxies = (dir: string, externals: Set<string>): void => {\n  mkdirSync(dir, { recursive: true })\n  for (const name of externals) {\n    writeFileSync(join(dir, sanitize(name)), hostModuleProxy(name))\n  }\n  for (const bare of builtinModules) {\n    writeFileSync(join(dir, sanitize(bare)), builtinProxy(bare))\n    writeFileSync(\n      join(dir, sanitize(`node:${bare}`)),\n      builtinProxy(`node:${bare}`),\n    )\n  }\n}\n\nexport type LinuxPlatformConfig<T extends MetroLikeConfig> = T & {\n  resolver: {\n    platforms: string[]\n    resolveRequest: MetroResolver\n  }\n  serializer: {\n    getModulesRunBeforeMainModule: (entryFilePath: string) => string[]\n  }\n}\n\n/**\n * Wraps a Metro config (RN's getDefaultConfig output) with everything the\n * linux platform needs. Composes with an existing custom resolveRequest —\n * non-linux platforms fall through to it untouched.\n */\nexport const withLinuxPlatform = <T extends MetroLikeConfig>(\n  config: T,\n  options: LinuxPlatformOptions = {},\n): LinuxPlatformConfig<T> => {\n  const externals = new Set([\n    ...HOST_MODULE_EXTERNALS,\n    ...(options.externals ?? []),\n  ])\n  const proxyDir =\n    options.proxyDir ??\n    join(\n      config.projectRoot ?? process.cwd(),\n      \"node_modules\",\n      \".react-native-gtkx\",\n      \"metro-externals\",\n    )\n  generateProxies(proxyDir, externals)\n  // Throws on an unknown key, an overlapping pattern or an attempt to remove\n  // the platform alias — at config load, naming what is valid.\n  const aliases = compileAliases(options.aliases)\n  const previousResolve = config.resolver?.resolveRequest ?? null\n\n  const fallback: MetroResolver = (context, moduleName, platform) =>\n    previousResolve\n      ? previousResolve(context, moduleName, platform)\n      : context.resolveRequest(context, moduleName, platform)\n\n  const resolveRequest: MetroResolver = (context, moduleName, platform) => {\n    if (platform !== LINUX_PLATFORM) {\n      return fallback(context, moduleName, platform)\n    }\n    if (externals.has(moduleName) || isBuiltin(moduleName)) {\n      return {\n        type: \"sourceFile\",\n        filePath: join(proxyDir, sanitize(moduleName)),\n      }\n    }\n    // The five package substitutions plus the platform alias, from the table\n    // both presets share (../aliases/index.ts). Each rule is anchored to its\n    // package name and matches the exact name or a slash-prefixed subpath,\n    // with the tail transplanted onto the target — the guard, not just the\n    // order, is what keeps `react-native-reanimated-dnd` out of the\n    // `react-native-reanimated` rule and the real, unrelated\n    // `react-native-worklets-core` out of the `react-native-worklets` one.\n    const aliased = applyAliases(aliases, moduleName)\n    if (aliased !== null) {\n      return fallback(context, aliased, platform)\n    }\n    return fallback(context, moduleName, platform)\n  }\n\n  // The cast: T may carry narrower resolver/serializer types than the ones\n  // rebuilt here — the runtime shape is a strict superset of both.\n  return {\n    ...config,\n    resolver: {\n      ...config.resolver,\n      platforms: [\n        ...new Set([...(config.resolver?.platforms ?? []), LINUX_PLATFORM]),\n      ],\n      resolveRequest,\n    },\n    serializer: {\n      ...config.serializer,\n      // RN prepends InitializeCore (Hermes Promise, nativeLoggingHook\n      // console...). Our runtime environment IS Node — nothing to\n      // initialize inside the bundle.\n      getModulesRunBeforeMainModule: () => [],\n    },\n  } as LinuxPlatformConfig<T>\n}\n"]}

package/dist/navigation/sidebar.d.ts

@@ -68,6 +68,22 @@ export type SidebarNavigationOptions = {
      *  specifically (replaces it entirely when set, same as the stack
      *  navigator's per-screen option override). */
     headerButtons?: HeaderButton[];
+    /** Section this row belongs to. Consecutive screens sharing a `group`
+     *  get one Adwaita section header above the first of them.
+     *
+     *  The header is attached with `GtkListBox.set_header_func`, which is
+     *  what GNOME's own sidebars use: a header is a DECORATION owned by the
+     *  row below it, not a row of its own. That distinction is the whole
+     *  reason to do it this way — a header faked as a non-selectable
+     *  `GtkListBoxRow` still sits in the list's focus chain, so Tab and the
+     *  arrow keys stop on it and assistive technology announces a row that
+     *  cannot be activated. A real header is skipped by both, for free.
+     *
+     *  Grouping follows ROW ORDER, so screens in one group are declared
+     *  together; a group name reappearing after a gap starts a second
+     *  header rather than reordering anything. Leave it unset on every
+     *  screen (the default) and the list is flat, exactly as before. */
+    group?: string;
 };
 export type HeaderButton = {
     id: string;
@@ -124,6 +140,36 @@ type SidebarNavigatorProps = {
     screenOptions?: SidebarNavigationOptions;
     /** Title of the sidebar pane's AdwHeaderBar. */
     sidebarTitle?: string;
+    /**
+     * Content packed at the START of the SIDEBAR pane's AdwHeaderBar — the
+     * "new item" action a GNOME sidebar puts next to its title, a search
+     * toggle, anything the pane's chrome needs.
+     *
+     * The content header's `headerLeft`/`headerRight`/`headerTitle` are
+     * screen OPTIONS because that header changes with the focused screen.
+     * The sidebar's does not: one pane, shared by every screen, so its
+     * chrome belongs to the navigator — the same level `sidebarTitle` and
+     * `sidebarContent` already sit at. Hence the `sidebar` prefix on
+     * otherwise identical names.
+     *
+     * Mounted through the same `HeaderSlotContent` root the content header
+     * uses, so a slot of React Native content lays out as a horizontal,
+     * content-hugging cluster flush with natively packed buttons.
+     */
+    sidebarHeaderLeft?: () => ReactNode;
+    /** Content packed at the END of the sidebar AdwHeaderBar — a primary
+     *  menu, say. Same contract as {@link sidebarHeaderLeft}. */
+    sidebarHeaderRight?: () => ReactNode;
+    /**
+     * Replaces the sidebar AdwHeaderBar's title WIDGET — a search entry, a
+     * switcher, anything the plain `sidebarTitle` string cannot express.
+     *
+     * `sidebarTitle` sets the pane's `AdwNavigationPage` title, which the
+     * HeaderBar renders by default; this overrides what is drawn there,
+     * exactly as a screen's `headerTitle` overrides its page `title`. Left
+     * unset, `sidebarTitle` shows as before.
+     */
+    sidebarHeaderTitle?: () => ReactNode;
     /** Buttons packed at the end of the content AdwHeaderBar. */
     headerButtons?: HeaderButton[];
     /**
@@ -180,7 +226,7 @@ type SidebarNavigatorProps = {
     sidebarContent?: (props: SidebarContentProps) => ReactNode;
     children: ReactNode;
 };
-declare const SidebarNavigator: ({ initialRouteName, screenOptions, sidebarTitle, headerButtons, collapseWidth, minWidth, minHeight, sidebarContent, children, }: SidebarNavigatorProps) => React.JSX.Element;
+declare const SidebarNavigator: ({ initialRouteName, screenOptions, sidebarTitle, sidebarHeaderLeft, sidebarHeaderRight, sidebarHeaderTitle, headerButtons, collapseWidth, minWidth, minHeight, sidebarContent, children, }: SidebarNavigatorProps) => React.JSX.Element;
 export type SidebarNavigationHelpers<ParamList extends ParamListBase = ParamListBase, RouteName extends keyof ParamList = keyof ParamList> = NavigationProp<ParamList, RouteName, TabNavigationState<ParamList>, SidebarNavigationOptions, SidebarNavigationEventMap>;
 export type SidebarScreenProps<ParamList extends ParamListBase = ParamListBase, RouteName extends keyof ParamList = keyof ParamList> = {
     route: RouteProp<ParamList, RouteName>;

package/dist/navigation/sidebar.js

@@ -56,6 +56,7 @@ const SIDEBAR_OPTION_KEYS = new Set([
     "headerButtons",
     "contentLayout",
     "sidebarRow",
+    "group",
 ]);
 // A one-off CSS class for a colored dot prefix — the same mechanism
 // tasks-app's own sidebar used (react-native-gtkx/gtk's `css` tag, kept
@@ -72,7 +73,7 @@ const listDot = (color) => css `
 // minimum at all" (Adwaita's own, which clips) is never the behavior.
 const DEFAULT_MIN_WIDTH = 360;
 const DEFAULT_MIN_HEIGHT = 294;
-const SidebarNavigator = ({ initialRouteName, screenOptions, sidebarTitle = "Sidebar", headerButtons, collapseWidth, minWidth = DEFAULT_MIN_WIDTH, minHeight = DEFAULT_MIN_HEIGHT, sidebarContent, children, }) => {
+const SidebarNavigator = ({ initialRouteName, screenOptions, sidebarTitle = "Sidebar", sidebarHeaderLeft, sidebarHeaderRight, sidebarHeaderTitle, headerButtons, collapseWidth, minWidth = DEFAULT_MIN_WIDTH, minHeight = DEFAULT_MIN_HEIGHT, sidebarContent, children, }) => {
     const { state, descriptors, navigation, NavigationContent } = useNavigationBuilder(TabRouter, {
         initialRouteName,
         screenOptions,
@@ -166,6 +167,69 @@ const SidebarNavigator = ({ initialRouteName, screenOptions, sidebarTitle = "Sid
     const activeDescriptor = descriptors[active.key];
     const optionsOf = (routeKey) => descriptors[routeKey]?.options ?? {};
     const titleOf = (routeKey, fallback) => optionsOf(routeKey).title ?? fallback;
+    // Group headers, through GtkListBox's own `set_header_func` — the
+    // mechanism GNOME's sidebars use, and the reason this is not a row: a
+    // header attached to a row is a decoration, outside the list's selection
+    // model and outside its focus chain, so arrow keys and Tab walk straight
+    // past it and assistive technology never announces an unactivatable row.
+    //
+    // The effect re-runs only when the group LIST changes (joined below with a
+    // separator that cannot occur in a group name), not on every render: the
+    // callback closes over `groups`, so a stale one would label rows with the
+    // previous grouping.
+    const groups = state.routes.map((route) => optionsOf(route.key).group);
+    const groupsKey = groups.map((group) => group ?? "
").join("");
+    useEffect(() => {
+        const list = listRef.current;
+        if (!list) {
+            return;
+        }
+        if (groups.every((group) => group === undefined)) {
+            // Ungrouped is the default and must stay byte-identical to what this
+            // navigator did before groups existed — including after a navigator
+            // that HAD groups re-rendered without them.
+            list.setHeaderFunc(null);
+            list.invalidateHeaders();
+            return;
+        }
+        list.setHeaderFunc((row, before) => {
+            const group = groups[row.getIndex()];
+            // `before` is null for the first row, which is where a header is most
+            // wanted; a row whose predecessor carries the same group gets none.
+            if (group === undefined ||
+                (before !== null && groups[before.getIndex()] === group)) {
+                row.setHeader(null);
+                return;
+            }
+            // The structure Adwaita's own stylesheet styles, rather than margins
+            // picked by eye. From libadwaita's compiled CSS:
+            //
+            //   .navigation-sidebar > .header > .heading      { margin: 12px }
+            //   .navigation-sidebar > .header.first > .heading { margin-top: 0 }
+            //   .navigation-sidebar > row  { min-height: 36px; padding: 0 8px;
+            //                                margin: 0 6px 2px }
+            //
+            // so a `.header` box holding a `.heading` label lands its text 12px
+            // from the list edge against a row label's 6 + 8 = 14px, and gets
+            // 12px of air above and below — which is the alignment and the rhythm
+            // GNOME ships, arrived at by matching the selectors rather than the
+            // pixels. `.first` is libadwaita's own class for the header that needs
+            // no top margin; its CSS carries the comment "No top margin on the
+            // first header".
+            const header = Gtk.Box.new(Gtk.Orientation.HORIZONTAL, 0);
+            header.addCssClass("header");
+            if (before === null) {
+                header.addCssClass("first");
+            }
+            const label = Gtk.Label.new(group);
+            label.setXalign(0);
+            label.addCssClass("heading");
+            header.append(label);
+            row.setHeader(header);
+        });
+        list.invalidateHeaders();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [groupsKey]);
     // The content HeaderBar's own shape — the thing tasks-app's README named
     // as a structural-sounding complaint ("one content header shared by the
     // whole navigator") and the PRD allowed finding a real gap. It is not
@@ -225,7 +289,17 @@ const SidebarNavigator = ({ initialRouteName, screenOptions, sidebarTitle = "Sid
         // Adwaita's own defaults for a sidebar of rows. Set explicitly
         // because they are what keeps the sidebar's width off the window's
         // minimum now that the scrolled window no longer propagates it.
-        minSidebarWidth: 180, maxSidebarWidth: 280, onNotifyShowContent: handleShowContentChanged, sidebar: _jsx(AdwNavigationPage, { title: sidebarTitle, tag: "sidebar", children: _jsx(AdwToolbarView, { topBar: _jsx(AdwHeaderBar, {}), children: sidebarContent ? (
+        minSidebarWidth: 180, maxSidebarWidth: 280, onNotifyShowContent: handleShowContentChanged, sidebar: _jsx(AdwNavigationPage, { title: sidebarTitle, tag: "sidebar", children: _jsx(AdwToolbarView, { topBar: 
+                // The sidebar pane's own chrome, mounted exactly the way the
+                // content HeaderBar below mounts its slots. It used to be a
+                // bare `<AdwHeaderBar />` with nothing an app could reach:
+                // `examples/tasks-nav` wanted its "New List" button here
+                // (where GNOME — and the gtkx tutorial this app family is
+                // modelled on — puts a sidebar's add action) and had to move
+                // it onto the CONTENT header instead, next to that header's
+                // own "New Task" +, leaving the user with two identical plus
+                // buttons and no way to tell them apart.
+                _jsx(AdwHeaderBar, { titleWidget: sidebarHeaderTitle ? (_jsx(HeaderSlotContent, { children: sidebarHeaderTitle() })) : undefined, start: sidebarHeaderLeft ? (_jsx(HeaderSlotContent, { children: sidebarHeaderLeft() })) : undefined, end: sidebarHeaderRight ? (_jsx(HeaderSlotContent, { children: sidebarHeaderRight() })) : undefined }), children: sidebarContent ? (
                 // The whole pane is the app's, mounted the way a page body
                 // is: a layout root that FILLS the pane, so React Native
                 // content — the common case — behaves as it does anywhere
@@ -286,7 +360,7 @@ const SidebarNavigator = ({ initialRouteName, screenOptions, sidebarTitle = "Sid
                                 // examples/gallery passes only titles and had been
                                 // paying it since.
                                 if (!options.icon && !options.color && !options.count) {
-                                    return (_jsx(GtkListBoxRow, { activatable: true, children: _jsx(GtkLabel, { label: titleOf(route.key, route.name), xalign: 0, marginTop: 8, marginBottom: 8, marginStart: 6, marginEnd: 6 }) }, route.key));
+                                    return (_jsx(GtkListBoxRow, { activatable: true, children: _jsx(GtkLabel, { label: titleOf(route.key, route.name), xalign: 0, marginTop: 8, marginBottom: 8 }) }, route.key));
                                 }
                                 return (_jsx(AdwActionRow, { title: titleOf(route.key, route.name), 
                                     // AdwActionRow defaults GtkListBoxRow:activatable