@gtkx/cli 0.18.9 → 0.20.0

package/dist/create.js

@@ -126,7 +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, "src", "gtkx-env.d.ts"), renderFile("src/gtkx-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/vite-plugin-gtkx-assets.d.ts

@@ -1,11 +1,20 @@
 import type { Plugin } from "vite";
 /**
- * Vite plugin that resolves static asset imports to filesystem paths.
+ * Vite plugin that resolves static asset imports to filesystem paths
+ * and handles CSS imports for GTK applications.
  *
- * 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`.
+ * **Non-CSS assets:** 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`.
+ *
+ * **CSS imports (`import "./style.css"`):** Transformed into a module that
+ * calls `injectGlobal` from `@gtkx/css` with the file's contents, injecting
+ * the styles into the GTK CSS provider at runtime.
+ *
+ * **CSS URL imports (`import path from "./style.css?url"`):** Handled by
+ * Vite's built-in `?url` mechanism, which emits the file as an asset and
+ * resolves it to a filesystem path via `renderBuiltUrl`.
  */
 export declare function gtkxAssets(): Plugin;
 //# sourceMappingURL=vite-plugin-gtkx-assets.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin-gtkx-assets.d.ts","sourceRoot":"","sources":["../src/vite-plugin-gtkx-assets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAmBnC"}
+{"version":3,"file":"vite-plugin-gtkx-assets.d.ts","sourceRoot":"","sources":["../src/vite-plugin-gtkx-assets.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAMnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,IAAI,MAAM,CA4CnC"}

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

@@ -1,21 +1,52 @@
-const ASSET_RE = /\.(png|jpe?g|gif|svg|webp|webm|mp4|ogg|mp3|wav|flac|aac|woff2?|eot|ttf|otf|ico|avif)$/i;
+import { readFileSync } from "node:fs";
+const ASSET_RE = /\.(png|jpe?g|gif|svg|webp|webm|mp4|ogg|mp3|wav|flac|aac|woff2?|eot|ttf|otf|ico|avif|data)$/i;
+const CSS_RE = /\.css$/i;
+const VIRTUAL_PREFIX = "\0gtkx:";
 /**
- * Vite plugin that resolves static asset imports to filesystem paths.
+ * Vite plugin that resolves static asset imports to filesystem paths
+ * and handles CSS imports for GTK applications.
  *
- * 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`.
+ * **Non-CSS assets:** 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`.
+ *
+ * **CSS imports (`import "./style.css"`):** Transformed into a module that
+ * calls `injectGlobal` from `@gtkx/css` with the file's contents, injecting
+ * the styles into the GTK CSS provider at runtime.
+ *
+ * **CSS URL imports (`import path from "./style.css?url"`):** Handled by
+ * Vite's built-in `?url` mechanism, which emits the file as an asset and
+ * resolves it to a filesystem path via `renderBuiltUrl`.
  */
 export function gtkxAssets() {
     let isBuild = false;
     return {
         name: "gtkx:assets",
         enforce: "pre",
+        config() {
+            return {
+                assetsInclude: [ASSET_RE],
+            };
+        },
         configResolved(config) {
             isBuild = config.command === "build";
         },
+        async resolveId(source, importer, options) {
+            if (!CSS_RE.test(source)) {
+                return;
+            }
+            const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
+            if (!resolved || resolved.external)
+                return;
+            return `${VIRTUAL_PREFIX + resolved.id}?inject`;
+        },
         load(id) {
+            if (id.startsWith(VIRTUAL_PREFIX) && id.endsWith("?inject")) {
+                const filePath = id.slice(VIRTUAL_PREFIX.length, -"?inject".length);
+                const content = readFileSync(filePath, "utf-8");
+                return [`import { injectGlobal } from "@gtkx/css";`, `injectGlobal(${JSON.stringify(content)});`].join("\n");
+            }
             if (isBuild || !ASSET_RE.test(id)) {
                 return;
             }

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

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin-gtkx-assets.js","sourceRoot":"","sources":["../src/vite-plugin-gtkx-assets.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG,wFAAwF,CAAC;AAE1G;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU;IACtB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACH,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK;QAEd,cAAc,CAAC,MAAM;YACjB,OAAO,GAAG,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC;QACzC,CAAC;QAED,IAAI,CAAC,EAAE;YACH,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChC,OAAO;YACX,CAAC;YAED,OAAO,kBAAkB,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC;QACnD,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"vite-plugin-gtkx-assets.js","sourceRoot":"","sources":["../src/vite-plugin-gtkx-assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,MAAM,QAAQ,GAAG,6FAA6F,CAAC;AAC/G,MAAM,MAAM,GAAG,SAAS,CAAC;AACzB,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU;IACtB,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACH,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,KAAK;QAEd,MAAM;YACF,OAAO;gBACH,aAAa,EAAE,CAAC,QAAQ,CAAC;aAC5B,CAAC;QACN,CAAC;QAED,cAAc,CAAC,MAAM;YACjB,OAAO,GAAG,MAAM,CAAC,OAAO,KAAK,OAAO,CAAC;QACzC,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO;YACrC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,OAAO;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACtF,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ;gBAAE,OAAO;YAE3C,OAAO,GAAG,cAAc,GAAG,QAAQ,CAAC,EAAE,SAAS,CAAC;QACpD,CAAC;QAED,IAAI,CAAC,EAAE;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC1D,MAAM,QAAQ,GAAG,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;gBACpE,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAChD,OAAO,CAAC,2CAA2C,EAAE,gBAAgB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAClG,IAAI,CACP,CAAC;YACN,CAAC;YAED,IAAI,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChC,OAAO;YACX,CAAC;YAED,OAAO,kBAAkB,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC;QACnD,CAAC;KACJ,CAAC;AACN,CAAC"}

package/env.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+
+declare module "*.css?url" {
+    const path: string;
+    export default path;
+}
+
+declare module "*.data" {
+    const path: string;
+    export default path;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/cli",
-  "version": "0.18.9",
+  "version": "0.20.0",
   "description": "CLI for GTKX - create and develop GTK4 React applications",
   "keywords": [
     "gtkx",
@@ -45,7 +45,8 @@
     "./refresh-runtime": {
       "types": "./dist/refresh-runtime.d.ts",
       "default": "./dist/refresh-runtime.js"
-    }
+    },
+    "./env": "./env.d.ts"
   },
   "bin": {
     "gtkx": "bin/gtkx.js"
@@ -54,29 +55,30 @@
   "files": [
     "bin",
     "dist",
+    "env.d.ts",
     "src",
     "templates"
   ],
   "dependencies": {
-    "@clack/prompts": "^1.0.0",
+    "@clack/prompts": "^1.0.1",
     "@swc/core": "^1.15.11",
-    "citty": "^0.2.0",
+    "citty": "^0.2.1",
     "ejs": "^4.0.1",
     "react-refresh": "^0.18.0",
     "vite": "^7.3.1",
-    "@gtkx/ffi": "0.18.9",
-    "@gtkx/mcp": "0.18.9",
-    "@gtkx/react": "0.18.9"
+    "@gtkx/ffi": "0.20.0",
+    "@gtkx/mcp": "0.20.0",
+    "@gtkx/react": "0.20.0"
   },
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/react-refresh": "^0.14.7",
     "memfs": "^4.56.10",
-    "@gtkx/testing": "0.18.9"
+    "@gtkx/testing": "0.20.0"
   },
   "peerDependencies": {
     "react": "^19",
-    "@gtkx/testing": "0.18.9"
+    "@gtkx/testing": "0.20.0"
   },
   "peerDependenciesMeta": {
     "@gtkx/testing": {
@@ -85,6 +87,7 @@
   },
   "scripts": {
     "build": "tsc -b",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc -b --emitDeclarationOnly"
   }
 }

package/src/create.ts

@@ -196,7 +196,7 @@ const scaffoldProject = (projectPath: string, resolved: ResolvedOptions): void =
     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, "src", "gtkx-env.d.ts"), renderFile("src/gtkx-env.d.ts.ejs", context));
     writeFileSync(join(projectPath, ".gitignore"), renderFile("gitignore.ejs", context));
 
     if (claudeSkills) {

package/src/vite-plugin-gtkx-assets.ts

@@ -1,14 +1,26 @@
+import { readFileSync } from "node:fs";
 import type { Plugin } from "vite";
 
-const ASSET_RE = /\.(png|jpe?g|gif|svg|webp|webm|mp4|ogg|mp3|wav|flac|aac|woff2?|eot|ttf|otf|ico|avif)$/i;
+const ASSET_RE = /\.(png|jpe?g|gif|svg|webp|webm|mp4|ogg|mp3|wav|flac|aac|woff2?|eot|ttf|otf|ico|avif|data)$/i;
+const CSS_RE = /\.css$/i;
+const VIRTUAL_PREFIX = "\0gtkx:";
 
 /**
- * Vite plugin that resolves static asset imports to filesystem paths.
+ * Vite plugin that resolves static asset imports to filesystem paths
+ * and handles CSS imports for GTK applications.
  *
- * 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`.
+ * **Non-CSS assets:** 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`.
+ *
+ * **CSS imports (`import "./style.css"`):** Transformed into a module that
+ * calls `injectGlobal` from `@gtkx/css` with the file's contents, injecting
+ * the styles into the GTK CSS provider at runtime.
+ *
+ * **CSS URL imports (`import path from "./style.css?url"`):** Handled by
+ * Vite's built-in `?url` mechanism, which emits the file as an asset and
+ * resolves it to a filesystem path via `renderBuiltUrl`.
  */
 export function gtkxAssets(): Plugin {
     let isBuild = false;
@@ -17,11 +29,36 @@ export function gtkxAssets(): Plugin {
         name: "gtkx:assets",
         enforce: "pre",
 
+        config() {
+            return {
+                assetsInclude: [ASSET_RE],
+            };
+        },
+
         configResolved(config) {
             isBuild = config.command === "build";
         },
 
+        async resolveId(source, importer, options) {
+            if (!CSS_RE.test(source)) {
+                return;
+            }
+
+            const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
+            if (!resolved || resolved.external) return;
+
+            return `${VIRTUAL_PREFIX + resolved.id}?inject`;
+        },
+
         load(id) {
+            if (id.startsWith(VIRTUAL_PREFIX) && id.endsWith("?inject")) {
+                const filePath = id.slice(VIRTUAL_PREFIX.length, -"?inject".length);
+                const content = readFileSync(filePath, "utf-8");
+                return [`import { injectGlobal } from "@gtkx/css";`, `injectGlobal(${JSON.stringify(content)});`].join(
+                    "\n",
+                );
+            }
+
             if (isBuild || !ASSET_RE.test(id)) {
                 return;
             }

package/templates/claude/EXAMPLES.md.ejs

@@ -101,7 +101,7 @@ const LoginForm = () => {
 
 ```tsx
 import * as Gtk from "@gtkx/ffi/gtk";
-import { GtkBox, GtkButton, GtkEntry, GtkLabel, GtkScrolledWindow, x } from "@gtkx/react";
+import { GtkBox, GtkButton, GtkEntry, GtkLabel, GtkScrolledWindow } from "@gtkx/react";
 import { useCallback, useState } from "react";
 
 interface Todo {
@@ -133,17 +133,14 @@ const TodoList = () => {
             </GtkBox>
             <GtkScrolledWindow vexpand cssClasses={["card"]}>
                 <GtkListView
-                    renderItem={(todo) => (
+                    items={todos.map((todo) => ({ id: todo.id, value: todo }))}
+                    renderItem={(todo: Todo) => (
                         <GtkBox spacing={8} marginStart={12} marginEnd={12} marginTop={8} marginBottom={8}>
-                            <GtkLabel label={todo?.text ?? ""} hexpand halign={Gtk.Align.START} />
-                            <GtkButton iconName="edit-delete-symbolic" cssClasses={["flat"]} onClicked={() => todo && deleteTodo(todo.id)} />
+                            <GtkLabel label={todo.text} hexpand halign={Gtk.Align.START} />
+                            <GtkButton iconName="edit-delete-symbolic" cssClasses={["flat"]} onClicked={() => deleteTodo(todo.id)} />
                         </GtkBox>
                     )}
-                >
-                    {todos.map((todo) => (
-                        <x.ListItem key={todo.id} id={todo.id} value={todo} />
-                    ))}
-                </GtkListView>
+                />
             </GtkScrolledWindow>
         </GtkBox>
     );
@@ -158,7 +155,7 @@ const TodoList = () => {
 
 ```tsx
 import * as Gtk from "@gtkx/ffi/gtk";
-import { GtkBox, GtkLabel, GtkPaned, GtkScrolledWindow, GtkStack, x } from "@gtkx/react";
+import { GtkBox, GtkLabel, GtkListView, GtkPaned, GtkScrolledWindow, GtkStack, x } from "@gtkx/react";
 import { useState } from "react";
 
 interface Page {
@@ -183,14 +180,11 @@ const SidebarNav = () => {
                         selected={[currentPage]}
                         selectionMode={Gtk.SelectionMode.SINGLE}
                         onSelectionChanged={(ids) => setCurrentPage(ids[0])}
-                        renderItem={(page) => (
-                            <GtkLabel label={page?.name ?? ""} halign={Gtk.Align.START} marginStart={12} marginTop={8} marginBottom={8} />
+                        items={pages.map((page) => ({ id: page.id, value: page }))}
+                        renderItem={(page: Page) => (
+                            <GtkLabel label={page.name} halign={Gtk.Align.START} marginStart={12} marginTop={8} marginBottom={8} />
                         )}
-                    >
-                        {pages.map((page) => (
-                            <x.ListItem key={page.id} id={page.id} value={page} />
-                        ))}
-                    </GtkListView>
+                    />
                 </GtkScrolledWindow>
             </x.Slot>
             <x.Slot for={GtkPaned} id="endChild">
@@ -339,13 +333,16 @@ const FileTable = () => {
 
     return (
         <GtkScrolledWindow vexpand cssClasses={["card"]}>
-            <GtkColumnView estimatedRowHeight={48} sortColumn={sortColumn} sortOrder={sortOrder} onSortChanged={handleSort}>
-                <x.ColumnViewColumn<FileItem> title="Name" id="name" expand sortable renderCell={(f) => <GtkLabel label={f?.name ?? ""} />} />
-                <x.ColumnViewColumn<FileItem> title="Size" id="size" fixedWidth={100} sortable renderCell={(f) => <GtkLabel label={`${f?.size ?? 0} KB`} />} />
-                <x.ColumnViewColumn<FileItem> title="Modified" id="modified" fixedWidth={120} sortable renderCell={(f) => <GtkLabel label={f?.modified ?? ""} />} />
-                {sortedFiles.map((file) => (
-                    <x.ListItem key={file.id} id={file.id} value={file} />
-                ))}
+            <GtkColumnView
+                estimatedRowHeight={48}
+                sortColumn={sortColumn}
+                sortOrder={sortOrder}
+                onSortChanged={handleSort}
+                items={sortedFiles.map((file) => ({ id: file.id, value: file }))}
+            >
+                <x.ColumnViewColumn title="Name" id="name" expand sortable renderCell={(f: FileItem) => <GtkLabel label={f.name} />} />
+                <x.ColumnViewColumn title="Size" id="size" fixedWidth={100} sortable renderCell={(f: FileItem) => <GtkLabel label={`${f.size} KB`} />} />
+                <x.ColumnViewColumn title="Modified" id="modified" fixedWidth={120} sortable renderCell={(f: FileItem) => <GtkLabel label={f.modified} />} />
             </GtkColumnView>
         </GtkScrolledWindow>
     );
@@ -398,7 +395,7 @@ const MenuDemo = () => {
 
 ```tsx
 import * as Gtk from "@gtkx/ffi/gtk";
-import { AdwSpinner, GtkBox, GtkLabel, GtkScrolledWindow, x } from "@gtkx/react";
+import { AdwSpinner, GtkBox, GtkLabel, GtkListView, GtkScrolledWindow } from "@gtkx/react";
 import { useEffect, useState } from "react";
 
 interface User {
@@ -442,17 +439,14 @@ const AsyncList = () => {
     return (
         <GtkScrolledWindow vexpand>
             <GtkListView
-                renderItem={(user) => (
+                items={users.map((user) => ({ id: user.id, value: user }))}
+                renderItem={(user: User) => (
                     <GtkBox orientation={Gtk.Orientation.VERTICAL} marginStart={12} marginTop={8} marginBottom={8}>
-                        <GtkLabel label={user?.name ?? ""} halign={Gtk.Align.START} cssClasses={["heading"]} />
-                        <GtkLabel label={user?.email ?? ""} halign={Gtk.Align.START} cssClasses={["dim-label"]} />
+                        <GtkLabel label={user.name} halign={Gtk.Align.START} cssClasses={["heading"]} />
+                        <GtkLabel label={user.email} halign={Gtk.Align.START} cssClasses={["dim-label"]} />
                     </GtkBox>
                 )}
-            >
-                {users.map((user) => (
-                    <x.ListItem key={user.id} id={user.id} value={user} />
-                ))}
-            </GtkListView>
+            />
         </GtkScrolledWindow>
     );
 };
@@ -632,7 +626,7 @@ const SplitViewDemo = () => {
 
 ```tsx
 import * as Gtk from "@gtkx/ffi/gtk";
-import { GtkBox, GtkImage, GtkLabel, GtkListView, GtkScrolledWindow, x } from "@gtkx/react";
+import { GtkBox, GtkImage, GtkLabel, GtkListView, GtkScrolledWindow } from "@gtkx/react";
 import { useState } from "react";
 
 interface FileNode {
@@ -667,21 +661,18 @@ const FileBrowser = () => {
                 selectionMode={Gtk.SelectionMode.SINGLE}
                 selected={selected ? [selected] : []}
                 onSelectionChanged={(ids) => setSelected(ids[0] ?? null)}
-                renderItem={(item) => (
+                items={files.map((file) => ({
+                    id: file.id,
+                    value: file,
+                    children: file.children?.map((child) => ({ id: child.id, value: child })),
+                }))}
+                renderItem={(item: FileNode) => (
                     <GtkBox spacing={8}>
-                        <GtkImage iconName={item?.isDirectory ? "folder-symbolic" : "text-x-generic-symbolic"} />
-                        <GtkLabel label={item?.name ?? ""} halign={Gtk.Align.START} />
+                        <GtkImage iconName={item.isDirectory ? "folder-symbolic" : "text-x-generic-symbolic"} />
+                        <GtkLabel label={item.name} halign={Gtk.Align.START} />
                     </GtkBox>
                 )}
-            >
-                {files.map((file) => (
-                    <x.ListItem key={file.id} id={file.id} value={file}>
-                        {file.children?.map((child) => (
-                            <x.ListItem key={child.id} id={child.id} value={child} />
-                        ))}
-                    </x.ListItem>
-                ))}
-            </GtkListView>
+            />
         </GtkScrolledWindow>
     );
 };

package/templates/claude/WIDGETS.md.ejs

@@ -130,7 +130,7 @@ Scrollable container.
 
 ## Virtual Lists
 
-All virtual list widgets use `ListItem` children and a `renderItem` function.
+All virtual list widgets use an `items` data prop and a `renderItem` function. Items are `{ id: string, value: T }` objects.
 
 ### GtkListView
 High-performance scrollable list with selection.
@@ -142,10 +142,9 @@ High-performance scrollable list with selection.
     selected={selectedId ? [selectedId] : []}
     selectionMode={Gtk.SelectionMode.SINGLE}
     onSelectionChanged={(ids) => setSelectedId(ids[0])}
-    renderItem={(item) => <GtkLabel label={item?.name ?? ""} />}
->
-    {items.map(item => <x.ListItem key={item.id} id={item.id} value={item} />)}
-</GtkListView>
+    items={items.map(item => ({ id: item.id, value: item }))}
+    renderItem={(item: Item) => <GtkLabel label={item.name} />}
+/>
 ```
 
 ### GtkGridView
@@ -156,37 +155,41 @@ Grid-based virtual scrolling.
     estimatedItemHeight={100}
     minColumns={2}
     maxColumns={4}
-    renderItem={(item) => (
+    items={items.map(item => ({ id: item.id, value: item }))}
+    renderItem={(item: Item) => (
         <GtkBox orientation={Gtk.Orientation.VERTICAL}>
-            <GtkImage iconName={item?.icon ?? "image-missing"} />
-            <GtkLabel label={item?.name ?? ""} />
+            <GtkImage iconName={item.icon} />
+            <GtkLabel label={item.name} />
         </GtkBox>
     )}
->
-    {items.map(item => <x.ListItem key={item.id} id={item.id} value={item} />)}
-</GtkGridView>
+/>
 ```
 
 ### GtkColumnView
 Table with sortable columns.
 
 ```tsx
-<GtkColumnView estimatedRowHeight={48} sortColumn="name" sortOrder={Gtk.SortType.ASCENDING} onSortChanged={handleSort}>
-    <x.ColumnViewColumn<Item>
+<GtkColumnView
+    estimatedRowHeight={48}
+    sortColumn="name"
+    sortOrder={Gtk.SortType.ASCENDING}
+    onSortChanged={handleSort}
+    items={items.map(item => ({ id: item.id, value: item }))}
+>
+    <x.ColumnViewColumn
         title="Name"
         id="name"
         expand
         resizable
         sortable
-        renderCell={(item) => <GtkLabel label={item?.name ?? ""} />}
+        renderCell={(item: Item) => <GtkLabel label={item.name} />}
     />
-    <x.ColumnViewColumn<Item>
+    <x.ColumnViewColumn
         title="Size"
         id="size"
         fixedWidth={100}
-        renderCell={(item) => <GtkLabel label={`${item?.size ?? 0} KB`} />}
+        renderCell={(item: Item) => <GtkLabel label={`${item.size} KB`} />}
     />
-    {items.map(item => <x.ListItem key={item.id} id={item.id} value={item} />)}
 </GtkColumnView>
 ```
 
@@ -194,13 +197,15 @@ Table with sortable columns.
 Selection dropdown.
 
 ```tsx
-<GtkDropDown selectedId={selectedId} onSelectionChanged={setSelectedId}>
-    {options.map(opt => <x.ListItem key={opt.id} id={opt.id} value={opt.label} />)}
-</GtkDropDown>
+<GtkDropDown
+    selectedId={selectedId}
+    onSelectionChanged={setSelectedId}
+    items={options.map(opt => ({ id: opt.id, value: opt.label }))}
+/>
 ```
 
 ### GtkListView (tree mode)
-Hierarchical tree with expand/collapse. Nesting `x.ListItem` children triggers tree behavior.
+Hierarchical tree with expand/collapse. Items with nested `children` arrays trigger tree behavior.
 
 ```tsx
 <GtkListView
@@ -210,24 +215,21 @@ Hierarchical tree with expand/collapse. Nesting `x.ListItem` children triggers t
     selectionMode={Gtk.SelectionMode.SINGLE}
     selected={selectedId ? [selectedId] : []}
     onSelectionChanged={(ids) => setSelectedId(ids[0])}
-    renderItem={(item, row) => (
+    items={files.map(file => ({
+        id: file.id,
+        value: file,
+        children: file.children?.map(child => ({ id: child.id, value: child })),
+    }))}
+    renderItem={(item: FileNode, row) => (
         <GtkBox spacing={8}>
-            <GtkImage iconName={item?.isDirectory ? "folder-symbolic" : "text-x-generic-symbolic"} />
-            <GtkLabel label={item?.name ?? ""} />
+            <GtkImage iconName={item.isDirectory ? "folder-symbolic" : "text-x-generic-symbolic"} />
+            <GtkLabel label={item.name} />
         </GtkBox>
     )}
->
-    {files.map(file => (
-        <x.ListItem key={file.id} id={file.id} value={file}>
-            {file.children?.map(child => (
-                <x.ListItem key={child.id} id={child.id} value={child} />
-            ))}
-        </x.ListItem>
-    ))}
-</GtkListView>
+/>
 ```
 
-**ListItem tree props:** `id`, `value`, `indentForDepth`, `indentForIcon`, `hideExpander`, nested `children`
+**ListItem data props:** `id`, `value`, `children` (nested items for tree mode), `hideExpander`, `indentForDepth`, `indentForIcon`, `section` (for sectioned lists)
 
 ---
 
@@ -799,14 +801,14 @@ Text content is provided as direct children. Use `x.TextTag` for formatting and
 
 ## Keyboard Shortcuts
 
-Attach shortcuts with `x.ShortcutController` and `x.Shortcut`:
+Attach shortcuts with `<GtkShortcutController>` and `x.Shortcut`:
 
 ```tsx
 <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} focusable>
-    <x.ShortcutController scope={Gtk.ShortcutScope.LOCAL}>
+    <GtkShortcutController scope={Gtk.ShortcutScope.LOCAL}>
         <x.Shortcut trigger="<Control>equal" onActivate={() => setCount((c) => c + 1)} />
         <x.Shortcut trigger="<Control>minus" onActivate={() => setCount((c) => c - 1)} />
-    </x.ShortcutController>
+    </GtkShortcutController>
     <GtkLabel label={`Count: ${count}`} />
 </GtkBox>
 ```

package/templates/package.json.ejs

@@ -6,6 +6,7 @@
     "scripts": {
         "dev": "gtkx dev src/dev.tsx",
         "build": "gtkx build",
+        "typecheck": "tsc --noEmit",
         "start": "node dist/bundle.js"<% if (testing === 'vitest') { %>,
         "test": "vitest"<% } %>
     },

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

@@ -0,0 +1 @@
+/// <reference types="@gtkx/cli/env" />

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

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