@gtkx/cli 0.17.3 → 0.18.1

package/dist/builder.d.ts

@@ -0,0 +1,55 @@
+import { type InlineConfig } from "vite";
+/**
+ * Options for building a GTKX application for production.
+ */
+export type BuildOptions = {
+    /** Path to the entry file (e.g., "src/index.tsx") */
+    entry: string;
+    /**
+     * Base path for resolving asset imports at runtime, relative to the
+     * executable directory.
+     *
+     * When set, asset imports resolve to
+     * `path.join(path.dirname(process.execPath), assetBase, filename)`.
+     * This is useful for FHS-compliant packaging where assets live under
+     * a `share/` directory rather than next to the binary.
+     *
+     * When omitted, assets resolve relative to the bundle via
+     * `import.meta.url`, which works when assets are co-located with
+     * the executable (e.g., in `bin/assets/`).
+     *
+     * @example
+     * ```ts
+     * await build({
+     *     entry: "./src/index.tsx",
+     *     assetBase: "../share/my-app",
+     * });
+     * ```
+     */
+    assetBase?: string;
+    /** Additional Vite configuration */
+    vite?: InlineConfig;
+};
+/**
+ * Builds a GTKX application for production using Vite's SSR build mode.
+ *
+ * Produces a single minified ESM bundle at `dist/bundle.js` with all
+ * dependencies inlined. The native `.node` binary is copied into the
+ * output directory as `gtkx.node`, making the bundle fully self-contained
+ * with no `node_modules` dependency at runtime.
+ *
+ * @param options - Build configuration including entry point and Vite options
+ *
+ * @example
+ * ```ts
+ * import { build } from "@gtkx/cli";
+ *
+ * await build({
+ *     entry: "./src/index.tsx",
+ *     vite: { root: process.cwd() },
+ * });
+ * ```
+ *
+ * @see {@link BuildOptions} for configuration options
+ */
+export declare const build: (options: BuildOptions) => Promise<void>;

package/dist/builder.js

@@ -0,0 +1,60 @@
+import { build as viteBuild } from "vite";
+import { gtkxAssets } from "./vite-plugin-gtkx-assets.js";
+import { gtkxBuiltUrl } from "./vite-plugin-gtkx-built-url.js";
+import { gtkxNative } from "./vite-plugin-gtkx-native.js";
+/**
+ * Builds a GTKX application for production using Vite's SSR build mode.
+ *
+ * Produces a single minified ESM bundle at `dist/bundle.js` with all
+ * dependencies inlined. The native `.node` binary is copied into the
+ * output directory as `gtkx.node`, making the bundle fully self-contained
+ * with no `node_modules` dependency at runtime.
+ *
+ * @param options - Build configuration including entry point and Vite options
+ *
+ * @example
+ * ```ts
+ * import { build } from "@gtkx/cli";
+ *
+ * await build({
+ *     entry: "./src/index.tsx",
+ *     vite: { root: process.cwd() },
+ * });
+ * ```
+ *
+ * @see {@link BuildOptions} for configuration options
+ */
+export const build = async (options) => {
+    const { entry, assetBase, vite: viteConfig } = options;
+    const root = viteConfig?.root ?? process.cwd();
+    await viteBuild({
+        ...viteConfig,
+        plugins: [...(viteConfig?.plugins ?? []), gtkxAssets(), gtkxBuiltUrl(assetBase), gtkxNative(root)],
+        build: {
+            ...viteConfig?.build,
+            ssr: entry,
+            ssrEmitAssets: true,
+            assetsInlineLimit: 0,
+            outDir: viteConfig?.build?.outDir ?? "dist",
+            minify: true,
+            rollupOptions: {
+                ...viteConfig?.build?.rollupOptions,
+                output: {
+                    ...(viteConfig?.build?.rollupOptions?.output ?? {}),
+                    entryFileNames: "bundle.js",
+                },
+            },
+        },
+        define: {
+            ...viteConfig?.define,
+            "process.env.NODE_ENV": JSON.stringify("production"),
+        },
+        ssr: {
+            ...viteConfig?.ssr,
+            noExternal: true,
+        },
+        experimental: {
+            ...viteConfig?.experimental,
+        },
+    });
+};

package/dist/cli.js

@@ -6,6 +6,7 @@ import { resolve } from "node:path";
 import { events } from "@gtkx/ffi";
 import { render } from "@gtkx/react";
 import { defineCommand, runMain } from "citty";
+import { build } from "./builder.js";
 import { createApp } from "./create.js";
 import { createDevServer } from "./dev-server.js";
 import { startMcpClient, stopMcpClient } from "./mcp-client.js";
@@ -49,6 +50,35 @@ const dev = defineCommand({
         console.log("[gtkx] HMR enabled - watching for changes...");
     },
 });
+const buildCmd = defineCommand({
+    meta: {
+        name: "build",
+        description: "Build application for production",
+    },
+    args: {
+        entry: {
+            type: "positional",
+            description: "Entry file (default: src/index.tsx)",
+            required: false,
+        },
+        "asset-base": {
+            type: "string",
+            description: "Asset base path relative to executable directory (e.g., ../share/my-app)",
+        },
+    },
+    async run({ args }) {
+        const entry = resolve(process.cwd(), args.entry ?? "src/index.tsx");
+        console.log(`[gtkx] Building ${entry}`);
+        await build({
+            entry,
+            assetBase: args["asset-base"],
+            vite: {
+                root: process.cwd(),
+            },
+        });
+        console.log("[gtkx] Build complete: dist/bundle.js");
+    },
+});
 const create = defineCommand({
     meta: {
         name: "create",
@@ -95,6 +125,7 @@ const main = defineCommand({
     },
     subCommands: {
         dev,
+        build: buildCmd,
         create,
     },
 });

package/dist/create.js

@@ -4,7 +4,7 @@ import { join, resolve } from "node:path";
 import * as p from "@clack/prompts";
 import { renderFile } from "./templates.js";
 const DEPENDENCIES = ["@gtkx/css", "@gtkx/ffi", "@gtkx/react", "react"];
-const DEV_DEPENDENCIES = ["@gtkx/cli", "@types/react", "typescript"];
+const DEV_DEPENDENCIES = ["@gtkx/cli", "@types/react", "typescript", "vite"];
 const TESTING_DEV_DEPENDENCIES = ["@gtkx/testing", "@gtkx/vitest", "vitest"];
 const createTemplateContext = (name, appId, testing) => {
     const title = name
@@ -126,6 +126,7 @@ const scaffoldProject = (projectPath, resolved) => {
     writeFileSync(join(projectPath, "src", "app.tsx"), renderFile("src/app.tsx.ejs", context));
     writeFileSync(join(projectPath, "src", "dev.tsx"), renderFile("src/dev.tsx.ejs", context));
     writeFileSync(join(projectPath, "src", "index.tsx"), renderFile("src/index.tsx.ejs", context));
+    writeFileSync(join(projectPath, "src", "vite-env.d.ts"), renderFile("src/vite-env.d.ts.ejs", context));
     writeFileSync(join(projectPath, ".gitignore"), renderFile("gitignore.ejs", context));
     if (claudeSkills) {
         const skillsDir = join(projectPath, ".claude", "skills", "developing-gtkx-apps");

package/dist/dev-server.js

@@ -3,6 +3,7 @@ import { events } from "@gtkx/ffi";
 import { setHotReloading, update } from "@gtkx/react";
 import { createServer } from "vite";
 import { isReactRefreshBoundary, performRefresh } from "./refresh-runtime.js";
+import { gtkxAssets } from "./vite-plugin-gtkx-assets.js";
 import { gtkxRefresh } from "./vite-plugin-gtkx-refresh.js";
 import { swcSsrRefresh } from "./vite-plugin-swc-ssr-refresh.js";
 /**
@@ -37,6 +38,7 @@ export const createDevServer = async (options) => {
         ...viteConfig,
         appType: "custom",
         plugins: [
+            gtkxAssets(),
             swcSsrRefresh(),
             gtkxRefresh(),
             {

package/dist/index.d.ts

@@ -1,2 +1,3 @@
+export { type BuildOptions, build } from "./builder.js";
 export { createApp } from "./create.js";
 export { createDevServer, type DevServerOptions } from "./dev-server.js";

package/dist/index.js

@@ -1,2 +1,3 @@
+export { build } from "./builder.js";
 export { createApp } from "./create.js";
 export { createDevServer } from "./dev-server.js";

package/dist/mcp-client.js

@@ -1,9 +1,19 @@
 import * as net from "node:net";
-import { getNativeId, getNativeInterface } from "@gtkx/ffi";
+import { getNativeInterface } from "@gtkx/ffi";
+import * as Gio from "@gtkx/ffi/gio";
 import { Value } from "@gtkx/ffi/gobject";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { DEFAULT_SOCKET_PATH, IpcRequestSchema, IpcResponseSchema, McpError, McpErrorCode, methodNotFoundError, widgetNotFoundError, } from "@gtkx/mcp";
-import { getApplication } from "@gtkx/react";
+const widgetIdMap = new WeakMap();
+let nextWidgetId = 0;
+const getWidgetId = (widget) => {
+    let id = widgetIdMap.get(widget);
+    if (!id) {
+        id = String(nextWidgetId++);
+        widgetIdMap.set(widget, id);
+    }
+    return id;
+};
 let testingModule = null;
 let testingLoadError = null;
 const loadTestingModule = async () => {
@@ -28,34 +38,16 @@ const formatRole = (role) => {
     return Gtk.AccessibleRole[role] ?? String(role);
 };
 const getWidgetText = (widget) => {
-    const role = widget.getAccessibleRole();
-    if (role === undefined)
-        return null;
-    switch (role) {
-        case Gtk.AccessibleRole.BUTTON:
-        case Gtk.AccessibleRole.LINK:
-        case Gtk.AccessibleRole.TAB:
-            return widget.getLabel?.() ?? widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.TOGGLE_BUTTON:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.CHECKBOX:
-        case Gtk.AccessibleRole.RADIO:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.LABEL:
-            return widget.getLabel?.() ?? widget.getText?.() ?? null;
-        case Gtk.AccessibleRole.TEXT_BOX:
-        case Gtk.AccessibleRole.SEARCH_BOX:
-        case Gtk.AccessibleRole.SPIN_BUTTON:
-            return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
-        case Gtk.AccessibleRole.GROUP:
-            return widget.getLabel?.() ?? null;
-        case Gtk.AccessibleRole.WINDOW:
-        case Gtk.AccessibleRole.DIALOG:
-        case Gtk.AccessibleRole.ALERT_DIALOG:
-            return widget.getTitle() ?? null;
-        default:
-            return null;
+    if ("getLabel" in widget && typeof widget.getLabel === "function") {
+        return widget.getLabel() ?? null;
+    }
+    if ("getText" in widget && typeof widget.getText === "function") {
+        return widget.getText() ?? null;
+    }
+    if ("getTitle" in widget && typeof widget.getTitle === "function") {
+        return widget.getTitle() ?? null;
     }
+    return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
 };
 const serializeWidget = (widget) => {
     const children = [];
@@ -66,7 +58,7 @@ const serializeWidget = (widget) => {
     }
     const text = getWidgetText(widget);
     return {
-        id: String(getNativeId(widget.handle)),
+        id: getWidgetId(widget),
         type: widget.constructor.name,
         role: formatRole(widget.getAccessibleRole()),
         name: widget.getName() || null,
@@ -80,7 +72,7 @@ const serializeWidget = (widget) => {
 };
 const widgetRegistry = new Map();
 const registerWidgets = (widget) => {
-    const idStr = String(getNativeId(widget.handle));
+    const idStr = getWidgetId(widget);
     widgetRegistry.set(idStr, widget);
     let child = widget.getFirstChild();
     while (child) {
@@ -282,7 +274,7 @@ class McpClient {
         }
     }
     async executeMethod(method, params) {
-        const app = getApplication();
+        const app = Gio.Application.getDefault();
         if (!app) {
             throw new Error("Application not initialized");
         }
@@ -292,7 +284,7 @@ class McpClient {
                 const windows = Gtk.Window.listToplevels();
                 return {
                     windows: windows.map((w) => ({
-                        id: String(getNativeId(w.handle)),
+                        id: getWidgetId(w),
                         title: w.getTitle?.() ?? null,
                     })),
                 };

package/dist/vite-plugin-gtkx-assets.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that resolves static asset imports to filesystem paths.
+ *
+ * In dev mode, asset imports resolve to the absolute source file path.
+ * In build mode, Vite's built-in asset pipeline handles emission and
+ * hashing; the `renderBuiltUrl` config in the builder converts the
+ * URL to a filesystem path via `import.meta.url`.
+ */
+export declare function gtkxAssets(): Plugin;

package/dist/vite-plugin-gtkx-assets.js

@@ -0,0 +1,25 @@
+const ASSET_RE = /\.(png|jpe?g|gif|svg|webp|webm|mp4|ogg|mp3|wav|flac|aac|woff2?|eot|ttf|otf|ico|avif)$/i;
+/**
+ * Vite plugin that resolves static asset imports to filesystem paths.
+ *
+ * In dev mode, asset imports resolve to the absolute source file path.
+ * In build mode, Vite's built-in asset pipeline handles emission and
+ * hashing; the `renderBuiltUrl` config in the builder converts the
+ * URL to a filesystem path via `import.meta.url`.
+ */
+export function gtkxAssets() {
+    let isBuild = false;
+    return {
+        name: "gtkx:assets",
+        enforce: "pre",
+        configResolved(config) {
+            isBuild = config.command === "build";
+        },
+        load(id) {
+            if (isBuild || !ASSET_RE.test(id)) {
+                return;
+            }
+            return `export default ${JSON.stringify(id)};`;
+        },
+    };
+}

package/dist/vite-plugin-gtkx-built-url.d.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that configures `renderBuiltUrl` for resolving asset imports
+ * to filesystem paths at runtime.
+ *
+ * When `assetBase` is provided, assets resolve relative to the executable
+ * directory using `path.join(path.dirname(process.execPath), assetBase, filename)`.
+ * This supports FHS-compliant layouts where assets live in `../share/<app>/`.
+ *
+ * When `assetBase` is omitted, assets resolve relative to the bundle file
+ * via `import.meta.url`, which works when assets are co-located with the
+ * executable.
+ *
+ * Only applies when the user has not already configured
+ * `experimental.renderBuiltUrl` in their Vite config.
+ */
+export declare function gtkxBuiltUrl(assetBase?: string): Plugin;

package/dist/vite-plugin-gtkx-built-url.js

@@ -0,0 +1,42 @@
+/**
+ * Vite plugin that configures `renderBuiltUrl` for resolving asset imports
+ * to filesystem paths at runtime.
+ *
+ * When `assetBase` is provided, assets resolve relative to the executable
+ * directory using `path.join(path.dirname(process.execPath), assetBase, filename)`.
+ * This supports FHS-compliant layouts where assets live in `../share/<app>/`.
+ *
+ * When `assetBase` is omitted, assets resolve relative to the bundle file
+ * via `import.meta.url`, which works when assets are co-located with the
+ * executable.
+ *
+ * Only applies when the user has not already configured
+ * `experimental.renderBuiltUrl` in their Vite config.
+ */
+export function gtkxBuiltUrl(assetBase) {
+    return {
+        name: "gtkx:built-url",
+        config(userConfig) {
+            if (userConfig.experimental?.renderBuiltUrl) {
+                return;
+            }
+            return {
+                experimental: {
+                    renderBuiltUrl(filename, { type }) {
+                        if (type !== "asset") {
+                            return;
+                        }
+                        if (assetBase) {
+                            return {
+                                runtime: `require("path").join(require("path").dirname(process.execPath),${JSON.stringify(assetBase)},${JSON.stringify(filename)})`,
+                            };
+                        }
+                        return {
+                            runtime: `new URL(${JSON.stringify(`./${filename}`)}, import.meta.url).pathname`,
+                        };
+                    },
+                },
+            };
+        },
+    };
+}

package/dist/vite-plugin-gtkx-native.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "vite";
+/**
+ * Vite plugin that embeds the native `.node` binary into the build output.
+ *
+ * During production builds, resolves the platform-specific `.node` binary,
+ * copies it into the output directory as `gtkx.node`, and transforms the
+ * `loadNativeBinding` function in `@gtkx/native` to load `./gtkx.node`
+ * directly. This makes the bundle self-contained with no `node_modules`
+ * dependency at runtime.
+ *
+ * @param root - Project root directory used to resolve native packages
+ */
+export declare function gtkxNative(root: string): Plugin;

package/dist/vite-plugin-gtkx-native.js

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { arch, platform } from "node:os";
+import { join } from "node:path";
+const LOAD_NATIVE_BINDING_RE = /function loadNativeBinding\(\) \{[\s\S]*?\n\}/;
+const NODE_OS_IMPORT_RE = /import\s*\{[^}]*\}\s*from\s*["']node:os["'];?\n?/;
+/**
+ * Vite plugin that embeds the native `.node` binary into the build output.
+ *
+ * During production builds, resolves the platform-specific `.node` binary,
+ * copies it into the output directory as `gtkx.node`, and transforms the
+ * `loadNativeBinding` function in `@gtkx/native` to load `./gtkx.node`
+ * directly. This makes the bundle self-contained with no `node_modules`
+ * dependency at runtime.
+ *
+ * @param root - Project root directory used to resolve native packages
+ */
+export function gtkxNative(root) {
+    const projectRequire = createRequire(join(root, "package.json"));
+    let nativeIndexPath;
+    return {
+        name: "gtkx:native",
+        enforce: "pre",
+        buildStart() {
+            const currentPlatform = platform();
+            const currentArch = arch();
+            const packageName = `@gtkx/native-linux-${currentArch}`;
+            if (currentPlatform !== "linux") {
+                throw new Error(`Unsupported build platform: ${currentPlatform}. Only Linux is supported.`);
+            }
+            if (currentArch !== "x64" && currentArch !== "arm64") {
+                throw new Error(`Unsupported build architecture: ${currentArch}. Only x64 and arm64 are supported.`);
+            }
+            nativeIndexPath = projectRequire.resolve("@gtkx/native");
+            const nodePath = projectRequire.resolve(`${packageName}/index.node`);
+            const source = readFileSync(nodePath);
+            this.emitFile({
+                type: "asset",
+                fileName: "gtkx.node",
+                source,
+            });
+        },
+        transform(code, id) {
+            if (id !== nativeIndexPath) {
+                return;
+            }
+            return code
+                .replace(NODE_OS_IMPORT_RE, "")
+                .replace(LOAD_NATIVE_BINDING_RE, 'function loadNativeBinding() { return require("./gtkx.node"); }');
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/cli",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "description": "CLI for GTKX - create and develop GTK4 React applications",
   "keywords": [
     "gtkx",
@@ -34,6 +34,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./builder": {
+      "types": "./dist/builder.d.ts",
+      "default": "./dist/builder.js"
+    },
     "./dev-server": {
       "types": "./dist/dev-server.d.ts",
       "default": "./dist/dev-server.js"
@@ -52,25 +56,25 @@
     "templates"
   ],
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
-    "@swc/core": "^1.15.10",
+    "@clack/prompts": "^1.0.0",
+    "@swc/core": "^1.15.11",
     "citty": "^0.2.0",
     "ejs": "^4.0.1",
     "react-refresh": "^0.18.0",
     "vite": "^7.3.1",
-    "@gtkx/ffi": "0.17.3",
-    "@gtkx/mcp": "0.17.3",
-    "@gtkx/react": "0.17.3"
+    "@gtkx/ffi": "0.18.1",
+    "@gtkx/mcp": "0.18.1",
+    "@gtkx/react": "0.18.1"
   },
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/react-refresh": "^0.14.7",
     "memfs": "^4.56.10",
-    "@gtkx/testing": "0.17.3"
+    "@gtkx/testing": "0.18.1"
   },
   "peerDependencies": {
     "react": "^19",
-    "@gtkx/testing": "0.17.3"
+    "@gtkx/testing": "0.18.1"
   },
   "peerDependenciesMeta": {
     "@gtkx/testing": {

package/templates/claude/EXAMPLES.md.ejs

@@ -34,13 +34,13 @@ import {
 export const App = () => (
     <AdwApplicationWindow title="My App" defaultWidth={800} defaultHeight={600} onClose={quit}>
         <AdwToolbarView>
-            <x.ToolbarTop>
+            <x.ContainerSlot for={AdwToolbarView} id="addTopBar">
                 <AdwHeaderBar>
                     <x.Slot for={AdwHeaderBar} id="titleWidget">
                         <AdwWindowTitle title="My App" subtitle="Welcome" />
                     </x.Slot>
                 </AdwHeaderBar>
-            </x.ToolbarTop>
+            </x.ContainerSlot>
             <AdwStatusPage
                 iconName="applications-system-symbolic"
                 title="Welcome"
@@ -132,7 +132,7 @@ const TodoList = () => {
                 <GtkButton label="Add" onClicked={addTodo} cssClasses={["suggested-action"]} />
             </GtkBox>
             <GtkScrolledWindow vexpand cssClasses={["card"]}>
-                <x.ListView<Todo>
+                <GtkListView
                     renderItem={(todo) => (
                         <GtkBox spacing={8} marginStart={12} marginEnd={12} marginTop={8} marginBottom={8}>
                             <GtkLabel label={todo?.text ?? ""} hexpand halign={Gtk.Align.START} />
@@ -143,7 +143,7 @@ const TodoList = () => {
                     {todos.map((todo) => (
                         <x.ListItem key={todo.id} id={todo.id} value={todo} />
                     ))}
-                </x.ListView>
+                </GtkListView>
             </GtkScrolledWindow>
         </GtkBox>
     );
@@ -179,7 +179,7 @@ const SidebarNav = () => {
         <GtkPaned position={200}>
             <x.Slot for={GtkPaned} id="startChild">
                 <GtkScrolledWindow cssClasses={["sidebar"]}>
-                    <x.ListView<Page>
+                    <GtkListView
                         selected={[currentPage]}
                         selectionMode={Gtk.SelectionMode.SINGLE}
                         onSelectionChanged={(ids) => setCurrentPage(ids[0])}
@@ -190,7 +190,7 @@ const SidebarNav = () => {
                         {pages.map((page) => (
                             <x.ListItem key={page.id} id={page.id} value={page} />
                         ))}
-                    </x.ListView>
+                    </GtkListView>
                 </GtkScrolledWindow>
             </x.Slot>
             <x.Slot for={GtkPaned} id="endChild">
@@ -219,9 +219,9 @@ const AppWithNavigation = () => {
         <GtkApplicationWindow title="App" defaultWidth={600} defaultHeight={400} onClose={quit}>
             <x.Slot for={GtkWindow} id="titlebar">
                 <GtkHeaderBar>
-                    <x.PackStart>
+                    <x.ContainerSlot for={GtkHeaderBar} id="packStart">
                         {page !== "home" && <GtkButton iconName="go-previous-symbolic" onClicked={() => setPage("home")} />}
-                    </x.PackStart>
+                    </x.ContainerSlot>
                     <x.Slot for={GtkHeaderBar} id="titleWidget">
                         <GtkLabel label={page === "home" ? "Home" : "Details"} cssClasses={["title"]} />
                     </x.Slot>
@@ -441,7 +441,7 @@ const AsyncList = () => {
 
     return (
         <GtkScrolledWindow vexpand>
-            <x.ListView<User>
+            <GtkListView
                 renderItem={(user) => (
                     <GtkBox orientation={Gtk.Orientation.VERTICAL} marginStart={12} marginTop={8} marginBottom={8}>
                         <GtkLabel label={user?.name ?? ""} halign={Gtk.Align.START} cssClasses={["heading"]} />
@@ -452,7 +452,7 @@ const AsyncList = () => {
                 {users.map((user) => (
                     <x.ListItem key={user.id} id={user.id} value={user} />
                 ))}
-            </x.ListView>
+            </GtkListView>
         </GtkScrolledWindow>
     );
 };
@@ -528,7 +528,7 @@ const NavigationDemo = () => {
             <AdwNavigationView history={history} onHistoryChanged={setHistory}>
                 <x.NavigationPage for={AdwNavigationView} id="home" title="Home">
                     <AdwToolbarView>
-                        <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
+                        <x.ContainerSlot for={AdwToolbarView} id="addTopBar"><AdwHeaderBar /></x.ContainerSlot>
                         <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER}>
                             <GtkLabel label="Welcome!" cssClasses={["title-1"]} />
                             <GtkButton label="Go to Settings" onClicked={() => push("settings")} cssClasses={["suggested-action"]} />
@@ -537,7 +537,7 @@ const NavigationDemo = () => {
                 </x.NavigationPage>
                 <x.NavigationPage for={AdwNavigationView} id="settings" title="Settings" canPop>
                     <AdwToolbarView>
-                        <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
+                        <x.ContainerSlot for={AdwToolbarView} id="addTopBar"><AdwHeaderBar /></x.ContainerSlot>
                         <GtkLabel label="Settings page content" vexpand />
                     </AdwToolbarView>
                 </x.NavigationPage>
@@ -589,7 +589,7 @@ const SplitViewDemo = () => {
             <AdwNavigationSplitView sidebarWidthFraction={0.33} minSidebarWidth={200} maxSidebarWidth={300}>
                 <x.NavigationPage for={AdwNavigationSplitView} id="sidebar" title="Mail">
                     <AdwToolbarView>
-                        <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
+                        <x.ContainerSlot for={AdwToolbarView} id="addTopBar"><AdwHeaderBar /></x.ContainerSlot>
                         <GtkScrolledWindow vexpand>
                             <GtkListBox
                                 cssClasses={["navigation-sidebar"]}
@@ -601,9 +601,9 @@ const SplitViewDemo = () => {
                             >
                                 {items.map((item) => (
                                     <AdwActionRow key={item.id} title={item.title}>
-                                        <x.ActionRowPrefix>
+                                        <x.ContainerSlot for={AdwActionRow} id="addPrefix">
                                             <GtkImage iconName={item.icon} />
-                                        </x.ActionRowPrefix>
+                                        </x.ContainerSlot>
                                     </AdwActionRow>
                                 ))}
                             </GtkListBox>
@@ -613,7 +613,7 @@ const SplitViewDemo = () => {
 
                 <x.NavigationPage for={AdwNavigationSplitView} id="content" title={selected?.title ?? ""}>
                     <AdwToolbarView>
-                        <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
+                        <x.ContainerSlot for={AdwToolbarView} id="addTopBar"><AdwHeaderBar /></x.ContainerSlot>
                         <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER} vexpand>
                             <GtkImage iconName={selected?.icon ?? ""} iconSize={Gtk.IconSize.LARGE} />
                             <GtkLabel label={selected?.title ?? ""} cssClasses={["title-2"]} />
@@ -628,11 +628,11 @@ const SplitViewDemo = () => {
 
 ---
 
-## File Browser with TreeListView
+## File Browser with GtkListView (tree)
 
 ```tsx
 import * as Gtk from "@gtkx/ffi/gtk";
-import { GtkBox, GtkImage, GtkLabel, GtkScrolledWindow, x } from "@gtkx/react";
+import { GtkBox, GtkImage, GtkLabel, GtkListView, GtkScrolledWindow, x } from "@gtkx/react";
 import { useState } from "react";
 
 interface FileNode {
@@ -660,7 +660,7 @@ const FileBrowser = () => {
 
     return (
         <GtkScrolledWindow vexpand cssClasses={["card"]}>
-            <x.TreeListView<FileNode>
+            <GtkListView
                 estimatedItemHeight={36}
                 vexpand
                 autoexpand={false}
@@ -675,13 +675,13 @@ const FileBrowser = () => {
                 )}
             >
                 {files.map((file) => (
-                    <x.TreeListItem key={file.id} id={file.id} value={file}>
+                    <x.ListItem key={file.id} id={file.id} value={file}>
                         {file.children?.map((child) => (
-                            <x.TreeListItem key={child.id} id={child.id} value={child} />
+                            <x.ListItem key={child.id} id={child.id} value={child} />
                         ))}
-                    </x.TreeListItem>
+                    </x.ListItem>
                 ))}
-            </x.TreeListView>
+            </GtkListView>
         </GtkScrolledWindow>
     );
 };
@@ -735,11 +735,10 @@ const AnimatedCard = () => {
             <GtkButton label={visible ? "Hide Card" : "Show Card"} onClicked={() => setVisible(!visible)} halign={Gtk.Align.START} />
             {visible && (
                 <x.Animation
-                    mode="spring"
                     initial={{ opacity: 0, scale: 0.8, translateY: -20 }}
                     animate={{ opacity: 1, scale: 1, translateY: 0 }}
                     exit={{ opacity: 0, scale: 0.8, translateY: 20 }}
-                    transition={{ damping: 0.7, stiffness: 200 }}
+                    transition={{ mode: "spring", damping: 0.7, stiffness: 200 }}
                     animateOnMount
                 >
                     <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={8} cssClasses={["card"]} marginStart={12} marginEnd={12} marginTop={8} marginBottom={8}>

package/templates/claude/SKILL.md.ejs

@@ -58,12 +58,12 @@ Some widgets require children in specific slots:
 </GtkPaned>
 ```
 
-### Packing (HeaderBar, ActionBar)
+### Container Slots (HeaderBar, ActionBar, ToolbarView, ActionRow, ExpanderRow)
 
 ```tsx
 <GtkHeaderBar>
-    <x.PackStart><GtkButton iconName="go-previous-symbolic" /></x.PackStart>
-    <x.PackEnd><GtkMenuButton iconName="open-menu-symbolic" /></x.PackEnd>
+    <x.ContainerSlot for={GtkHeaderBar} id="packStart"><GtkButton iconName="go-previous-symbolic" /></x.ContainerSlot>
+    <x.ContainerSlot for={GtkHeaderBar} id="packEnd"><GtkMenuButton iconName="open-menu-symbolic" /></x.ContainerSlot>
 </GtkHeaderBar>
 ```
 
@@ -71,10 +71,9 @@ Some widgets require children in specific slots:
 
 ```tsx
 <x.Animation
-    mode="spring"
     initial={{ opacity: 0, scale: 0.8 }}
     animate={{ opacity: 1, scale: 1 }}
-    transition={{ damping: 0.8, stiffness: 200 }}
+    transition={{ mode: "spring", damping: 0.8, stiffness: 200 }}
     animateOnMount
 >
     <GtkLabel label="Animated!" />

package/templates/claude/WIDGETS.md.ejs

@@ -132,11 +132,11 @@ Scrollable container.
 
 All virtual list widgets use `ListItem` children and a `renderItem` function.
 
-### ListView
+### GtkListView
 High-performance scrollable list with selection.
 
 ```tsx
-<x.ListView<Item>
+<GtkListView
     estimatedItemHeight={48}
     vexpand
     selected={selectedId ? [selectedId] : []}
@@ -145,14 +145,14 @@ High-performance scrollable list with selection.
     renderItem={(item) => <GtkLabel label={item?.name ?? ""} />}
 >
     {items.map(item => <x.ListItem key={item.id} id={item.id} value={item} />)}
-</x.ListView>
+</GtkListView>
 ```
 
-### GridView
+### GtkGridView
 Grid-based virtual scrolling.
 
 ```tsx
-<x.GridView<Item>
+<GtkGridView
     estimatedItemHeight={100}
     minColumns={2}
     maxColumns={4}
@@ -164,7 +164,7 @@ Grid-based virtual scrolling.
     )}
 >
     {items.map(item => <x.ListItem key={item.id} id={item.id} value={item} />)}
-</x.GridView>
+</GtkGridView>
 ```
 
 ### GtkColumnView
@@ -195,15 +195,15 @@ Selection dropdown.
 
 ```tsx
 <GtkDropDown selectedId={selectedId} onSelectionChanged={setSelectedId}>
-    {options.map(opt => <x.SimpleListItem key={opt.id} id={opt.id} value={opt.label} />)}
+    {options.map(opt => <x.ListItem key={opt.id} id={opt.id} value={opt.label} />)}
 </GtkDropDown>
 ```
 
-### TreeListView
-Hierarchical tree with expand/collapse.
+### GtkListView (tree mode)
+Hierarchical tree with expand/collapse. Nesting `x.ListItem` children triggers tree behavior.
 
 ```tsx
-<x.TreeListView<FileNode>
+<GtkListView
     estimatedItemHeight={48}
     vexpand
     autoexpand={false}
@@ -218,16 +218,16 @@ Hierarchical tree with expand/collapse.
     )}
 >
     {files.map(file => (
-        <x.TreeListItem key={file.id} id={file.id} value={file}>
+        <x.ListItem key={file.id} id={file.id} value={file}>
             {file.children?.map(child => (
-                <x.TreeListItem key={child.id} id={child.id} value={child} />
+                <x.ListItem key={child.id} id={child.id} value={child} />
             ))}
-        </x.TreeListItem>
+        </x.ListItem>
     ))}
-</x.TreeListView>
+</GtkListView>
 ```
 
-**TreeListItem props:** `id`, `value`, `indentForDepth`, `indentForIcon`, `hideExpander`, nested `children`
+**ListItem tree props:** `id`, `value`, `indentForDepth`, `indentForIcon`, `hideExpander`, nested `children`
 
 ---
 
@@ -348,15 +348,15 @@ Progress/level indicator with customizable thresholds.
 ## Header & Action Bars
 
 ### GtkHeaderBar
-Title bar with packed widgets. Use `Pack.Start`, `Pack.End`, and `Slot` for titleWidget.
+Title bar with packed widgets. Use `x.ContainerSlot` for packing and `x.Slot` for titleWidget.
 
 ```tsx
 <GtkHeaderBar>
-    <x.PackStart><GtkButton iconName="go-previous-symbolic" /></x.PackStart>
+    <x.ContainerSlot for={GtkHeaderBar} id="packStart"><GtkButton iconName="go-previous-symbolic" /></x.ContainerSlot>
     <x.Slot for={GtkHeaderBar} id="titleWidget">
         <GtkLabel label="Title" cssClasses={["title"]} />
     </x.Slot>
-    <x.PackEnd><GtkMenuButton iconName="open-menu-symbolic" /></x.PackEnd>
+    <x.ContainerSlot for={GtkHeaderBar} id="packEnd"><GtkMenuButton iconName="open-menu-symbolic" /></x.ContainerSlot>
 </GtkHeaderBar>
 ```
 
@@ -365,8 +365,8 @@ Bottom action bar.
 
 ```tsx
 <GtkActionBar>
-    <x.PackStart><GtkButton label="Cancel" /></x.PackStart>
-    <x.PackEnd><GtkButton label="Save" cssClasses={["suggested-action"]} /></x.PackEnd>
+    <x.ContainerSlot for={GtkActionBar} id="packStart"><GtkButton label="Cancel" /></x.ContainerSlot>
+    <x.ContainerSlot for={GtkActionBar} id="packEnd"><GtkButton label="Save" cssClasses={["suggested-action"]} /></x.ContainerSlot>
 </GtkActionBar>
 ```
 
@@ -439,17 +439,17 @@ Modern app structure.
 ```tsx
 <AdwApplicationWindow title="App" defaultWidth={800} defaultHeight={600} onClose={quit}>
     <AdwToolbarView>
-        <x.ToolbarTop>
+        <x.ContainerSlot for={AdwToolbarView} id="addTopBar">
             <AdwHeaderBar>
                 <x.Slot for={AdwHeaderBar} id="titleWidget">
                     <AdwWindowTitle title="App" subtitle="Description" />
                 </x.Slot>
             </AdwHeaderBar>
-        </x.ToolbarTop>
+        </x.ContainerSlot>
         <MainContent />
-        <x.ToolbarBottom>
+        <x.ContainerSlot for={AdwToolbarView} id="addBottomBar">
             <GtkActionBar />
-        </x.ToolbarBottom>
+        </x.ContainerSlot>
     </AdwToolbarView>
 </AdwApplicationWindow>
 ```
@@ -478,35 +478,35 @@ Settings UI.
     <AdwPreferencesGroup title="Appearance" description="Customize look">
         <AdwSwitchRow title="Dark Mode" active={dark} onActivated={() => setDark(!dark)} />
         <AdwActionRow title="Theme" subtitle="Select color">
-            <x.ActionRowPrefix>
+            <x.ContainerSlot for={AdwActionRow} id="addPrefix">
                 <GtkImage iconName="preferences-color-symbolic" />
-            </x.ActionRowPrefix>
-            <x.ActionRowSuffix>
+            </x.ContainerSlot>
+            <x.ContainerSlot for={AdwActionRow} id="addSuffix">
                 <GtkImage iconName="go-next-symbolic" valign={Gtk.Align.CENTER} />
-            </x.ActionRowSuffix>
+            </x.ContainerSlot>
         </AdwActionRow>
     </AdwPreferencesGroup>
 </AdwPreferencesPage>
 ```
 
-**ActionRow children:** Use `x.ActionRowPrefix` for left widgets, `x.ActionRowSuffix` for right widgets, or `x.Slot for={AdwActionRow} id="activatableWidget"` for clickable suffix.
+**ActionRow children:** Use `x.ContainerSlot for={AdwActionRow} id="addPrefix"` for left widgets, `x.ContainerSlot for={AdwActionRow} id="addSuffix"` for right widgets, or `x.Slot for={AdwActionRow} id="activatableWidget"` for clickable suffix.
 
 ### AdwExpanderRow
 Expandable settings row with optional action widget.
 
 ```tsx
 <AdwExpanderRow title="Advanced" subtitle="More options">
-    <x.ExpanderRowAction>
+    <x.ContainerSlot for={AdwExpanderRow} id="addAction">
         <GtkButton iconName="emblem-system-symbolic" cssClasses={["flat"]} />
-    </x.ExpanderRowAction>
-    <x.ExpanderRowRow>
+    </x.ContainerSlot>
+    <x.ContainerSlot for={AdwExpanderRow} id="addRow">
         <AdwSwitchRow title="Option 1" active />
         <AdwSwitchRow title="Option 2" />
-    </x.ExpanderRowRow>
+    </x.ContainerSlot>
 </AdwExpanderRow>
 ```
 
-**ExpanderRow slots:** `x.ExpanderRowRow` for nested rows, `x.ExpanderRowAction` for header action widget. Direct children also work for simple cases.
+**ExpanderRow slots:** `x.ContainerSlot for={AdwExpanderRow} id="addRow"` for nested rows, `x.ContainerSlot for={AdwExpanderRow} id="addAction"` for header action widget. Direct children also work for simple cases.
 
 ### AdwEntryRow / AdwPasswordEntryRow
 Input in list row.
@@ -560,7 +560,7 @@ const [selected, setSelected] = useState(items[0]);
 <AdwNavigationSplitView sidebarWidthFraction={0.33} minSidebarWidth={200} maxSidebarWidth={300}>
     <x.NavigationPage for={AdwNavigationSplitView} id="sidebar" title="Sidebar">
         <AdwToolbarView>
-            <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
+            <x.ContainerSlot for={AdwToolbarView} id="addTopBar"><AdwHeaderBar /></x.ContainerSlot>
             <GtkListBox cssClasses={["navigation-sidebar"]} onRowSelected={(row) => {
                     if (!row) return;
                     const item = items[row.getIndex()];
@@ -573,7 +573,7 @@ const [selected, setSelected] = useState(items[0]);
 
     <x.NavigationPage for={AdwNavigationSplitView} id="content" title={selected?.title ?? ""}>
         <AdwToolbarView>
-            <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
+            <x.ContainerSlot for={AdwToolbarView} id="addTopBar"><AdwHeaderBar /></x.ContainerSlot>
             <GtkLabel label={selected?.title ?? ""} />
         </AdwToolbarView>
     </x.NavigationPage>
@@ -633,10 +633,9 @@ Wrap widgets in `x.Animation` for declarative animations with spring or timed tr
 
 ```tsx
 <x.Animation
-    mode="spring"
     initial={{ opacity: 0, scale: 0.8 }}
     animate={{ opacity: 1, scale: 1 }}
-    transition={{ damping: 0.8, stiffness: 200, mass: 1 }}
+    transition={{ mode: "spring", damping: 0.8, stiffness: 200, mass: 1 }}
     animateOnMount
     onAnimationComplete={() => console.log("done")}
 >
@@ -644,11 +643,11 @@ Wrap widgets in `x.Animation` for declarative animations with spring or timed tr
 </x.Animation>
 ```
 
-**Props:** `mode` (`"spring"` | `"timed"`), `initial`, `animate`, `exit`, `transition`, `animateOnMount`, `onAnimationStart`, `onAnimationComplete`
+**Props:** `initial`, `animate`, `exit`, `transition` (`AnimationTransition` discriminated union), `animateOnMount`, `onAnimationStart`, `onAnimationComplete`
 
-**Spring transition:** `damping`, `stiffness`, `mass`, `initialVelocity`, `clamp`, `delay`
+**Spring transition:** `{ mode: "spring", damping, stiffness, mass, initialVelocity, clamp, delay }`
 
-**Timed transition:** `duration`, `easing` (from `Adw.Easing`), `delay`, `repeat`, `reverse`, `alternate`
+**Timed transition:** `{ mode: "timed", duration, easing (from Adw.Easing), delay, repeat, reverse, alternate }`
 
 ---
 

package/templates/package.json.ejs

@@ -5,8 +5,8 @@
     "type": "module",
     "scripts": {
         "dev": "gtkx dev src/dev.tsx",
-        "build": "tsc -b",
-        "start": "node dist/index.js"<% if (testing === 'vitest') { %>,
+        "build": "gtkx build",
+        "start": "node dist/bundle.js"<% if (testing === 'vitest') { %>,
         "test": "vitest"<% } %>
     },
     "gtkx": {

package/templates/src/vite-env.d.ts.ejs

@@ -0,0 +1 @@
+/// <reference types="vite/client" />