@gtkx/cli 0.15.0 → 0.16.0

package/dist/mcp-client.js

@@ -1,5 +1,5 @@
 import * as net from "node:net";
-import { getNativeId, getNativeObject } from "@gtkx/ffi";
+import { getNativeId, getNativeInterface } from "@gtkx/ffi";
 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";
@@ -46,7 +46,7 @@ const getWidgetText = (widget) => {
         case Gtk.AccessibleRole.TEXT_BOX:
         case Gtk.AccessibleRole.SEARCH_BOX:
         case Gtk.AccessibleRole.SPIN_BUTTON:
-            return getNativeObject(widget.handle, Gtk.Editable).getText() ?? null;
+            return getNativeInterface(widget, Gtk.Editable)?.getText() ?? null;
         case Gtk.AccessibleRole.GROUP:
             return widget.getLabel?.() ?? null;
         case Gtk.AccessibleRole.WINDOW:
@@ -93,10 +93,7 @@ const getWidgetById = (id) => {
 };
 const refreshWidgetRegistry = () => {
     widgetRegistry.clear();
-    const app = getApplication();
-    if (!app)
-        return;
-    const windows = app.getWindows();
+    const windows = Gtk.Window.listToplevels();
     for (const window of windows) {
         registerWidgets(window);
     }
@@ -291,6 +288,15 @@ class McpClient {
         }
         refreshWidgetRegistry();
         switch (method) {
+            case "app.getWindows": {
+                const windows = Gtk.Window.listToplevels();
+                return {
+                    windows: windows.map((w) => ({
+                        id: String(getNativeId(w.handle)),
+                        title: w.getTitle?.() ?? null,
+                    })),
+                };
+            }
             case "widget.getTree": {
                 const testing = await loadTestingModule();
                 return { tree: testing.prettyWidget(app, { includeIds: true, highlight: false }) };
@@ -300,9 +306,13 @@ class McpClient {
                 const p = params;
                 let widgets = [];
                 switch (p.queryType) {
-                    case "role":
-                        widgets = await testing.findAllByRole(app, p.value, p.options);
+                    case "role": {
+                        const roleValue = typeof p.value === "string"
+                            ? Gtk.AccessibleRole[p.value]
+                            : p.value;
+                        widgets = await testing.findAllByRole(app, roleValue, p.options);
                         break;
+                    }
                     case "text":
                         widgets = await testing.findAllByText(app, String(p.value), p.options);
                         break;
@@ -356,25 +366,29 @@ class McpClient {
                     throw widgetNotFoundError(p.widgetId);
                 }
                 const signalArgs = (p.args ?? []).map((arg) => {
-                    switch (arg.type) {
+                    const isTypedArg = typeof arg === "object" && arg !== null && "type" in arg && "value" in arg;
+                    const argType = isTypedArg ? arg.type : typeof arg;
+                    const argValue = isTypedArg ? arg.value : arg;
+                    switch (argType) {
                         case "boolean":
-                            return Value.newFromBoolean(arg.value);
+                            return Value.newFromBoolean(argValue);
                         case "int":
-                            return Value.newFromInt(arg.value);
+                            return Value.newFromInt(argValue);
                         case "uint":
-                            return Value.newFromUint(arg.value);
+                            return Value.newFromUint(argValue);
                         case "int64":
-                            return Value.newFromInt64(arg.value);
+                            return Value.newFromInt64(argValue);
                         case "uint64":
-                            return Value.newFromUint64(arg.value);
+                            return Value.newFromUint64(argValue);
                         case "float":
-                            return Value.newFromFloat(arg.value);
+                            return Value.newFromFloat(argValue);
                         case "double":
-                            return Value.newFromDouble(arg.value);
+                        case "number":
+                            return Value.newFromDouble(argValue);
                         case "string":
-                            return Value.newFromString(arg.value);
+                            return Value.newFromString(argValue);
                         default:
-                            throw new McpError(McpErrorCode.INVALID_REQUEST, `Unknown argument type: ${arg.type}`);
+                            throw new McpError(McpErrorCode.INVALID_REQUEST, `Unknown argument type: ${argType}`);
                     }
                 });
                 await testing.fireEvent(widget, p.signal, ...signalArgs);

package/dist/templates.d.ts

@@ -1,8 +1,8 @@
 import type { TestingOption } from "./create.js";
-export interface TemplateContext {
+export type TemplateContext = {
     name: string;
     appId: string;
     title: string;
     testing: TestingOption;
-}
+};
 export declare const renderFile: (templateName: string, context: TemplateContext) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "CLI for GTKX - create and develop GTK4 React applications",
   "keywords": [
     "gtkx",
@@ -53,24 +53,24 @@
   ],
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@swc/core": "^1.15.8",
-    "citty": "^0.1.6",
-    "ejs": "^3.1.10",
+    "@swc/core": "^1.15.10",
+    "citty": "^0.2.0",
+    "ejs": "^4.0.1",
     "react-refresh": "^0.18.0",
     "vite": "^7.3.1",
-    "@gtkx/mcp": "0.15.0",
-    "@gtkx/react": "0.15.0",
-    "@gtkx/ffi": "0.15.0"
+    "@gtkx/mcp": "0.16.0",
+    "@gtkx/ffi": "0.16.0",
+    "@gtkx/react": "0.16.0"
   },
   "devDependencies": {
     "@types/ejs": "^3.1.5",
     "@types/react-refresh": "^0.14.7",
-    "memfs": "^4.51.1",
-    "@gtkx/testing": "0.15.0"
+    "memfs": "^4.56.9",
+    "@gtkx/testing": "0.16.0"
   },
   "peerDependencies": {
     "react": "^19",
-    "@gtkx/testing": "0.15.0"
+    "@gtkx/testing": "0.16.0"
   },
   "peerDependenciesMeta": {
     "@gtkx/testing": {

package/templates/claude/EXAMPLES.md.ejs

@@ -526,7 +526,7 @@ const NavigationDemo = () => {
     return (
         <AdwApplicationWindow title="Navigation Demo" defaultWidth={600} defaultHeight={400} onClose={quit}>
             <AdwNavigationView history={history} onHistoryChanged={setHistory}>
-                <x.NavigationPage id="home" title="Home">
+                <x.NavigationPage for={AdwNavigationView} id="home" title="Home">
                     <AdwToolbarView>
                         <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
                         <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER}>
@@ -535,7 +535,7 @@ const NavigationDemo = () => {
                         </GtkBox>
                     </AdwToolbarView>
                 </x.NavigationPage>
-                <x.NavigationPage id="settings" title="Settings" canPop>
+                <x.NavigationPage for={AdwNavigationView} id="settings" title="Settings" canPop>
                     <AdwToolbarView>
                         <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
                         <GtkLabel label="Settings page content" vexpand />
@@ -587,13 +587,13 @@ const SplitViewDemo = () => {
     return (
         <AdwApplicationWindow title="Split View Demo" defaultWidth={800} defaultHeight={500} onClose={quit}>
             <AdwNavigationSplitView sidebarWidthFraction={0.33} minSidebarWidth={200} maxSidebarWidth={300}>
-                <x.NavigationPage id="sidebar" title="Mail">
+                <x.NavigationPage for={AdwNavigationSplitView} id="sidebar" title="Mail">
                     <AdwToolbarView>
                         <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
                         <GtkScrolledWindow vexpand>
                             <GtkListBox
                                 cssClasses={["navigation-sidebar"]}
-                                onRowSelected={(_, row) => {
+                                onRowSelected={(row) => {
                                     if (!row) return;
                                     const item = items[row.getIndex()];
                                     if (item) setSelected(item);
@@ -611,7 +611,7 @@ const SplitViewDemo = () => {
                     </AdwToolbarView>
                 </x.NavigationPage>
 
-                <x.NavigationPage id="content" title={selected?.title ?? ""}>
+                <x.NavigationPage for={AdwNavigationSplitView} id="content" title={selected?.title ?? ""}>
                     <AdwToolbarView>
                         <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
                         <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} halign={Gtk.Align.CENTER} valign={Gtk.Align.CENTER} vexpand>
@@ -689,36 +689,28 @@ const FileBrowser = () => {
 
 ---
 
-## Toggle Group View Switcher
+## Stack with Programmatic Navigation
 
 ```tsx
 import * as Gtk from "@gtkx/ffi/gtk";
-import { AdwToggleGroup, GtkBox, GtkLabel, GtkStack, x } from "@gtkx/react";
+import { GtkBox, GtkButton, GtkLabel, GtkStack, x } from "@gtkx/react";
 import { useState } from "react";
 
-const ViewSwitcher = () => {
-    const [view, setView] = useState("list");
+const StackNavigation = () => {
+    const [page, setPage] = useState("home");
 
     return (
         <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-            <AdwToggleGroup
-                activeName={view}
-                onNotify={(group, prop) => {
-                    if (prop === "active-name") {
-                        setView(group.getActiveName() ?? "list");
-                    }
-                }}
-                halign={Gtk.Align.CENTER}
-            >
-                <x.Toggle id="list" iconName="view-list-symbolic" tooltip="List view" />
-                <x.Toggle id="grid" iconName="view-grid-symbolic" tooltip="Grid view" />
-            </AdwToggleGroup>
-            <GtkStack page={view} vexpand>
-                <x.StackPage id="list">
-                    <GtkLabel label="List View Content" />
+            <GtkBox spacing={6} halign={Gtk.Align.CENTER}>
+                <GtkButton label="Home" onClicked={() => setPage("home")} />
+                <GtkButton label="Settings" onClicked={() => setPage("settings")} />
+            </GtkBox>
+            <GtkStack page={page} onPageChanged={setPage} vexpand>
+                <x.StackPage id="home">
+                    <GtkLabel label="Home Content" />
                 </x.StackPage>
-                <x.StackPage id="grid">
-                    <GtkLabel label="Grid View Content" />
+                <x.StackPage id="settings">
+                    <GtkLabel label="Settings Content" />
                 </x.StackPage>
             </GtkStack>
         </GtkBox>

package/templates/claude/WIDGETS.md.ejs

@@ -60,7 +60,7 @@ Tabbed container with visible tabs.
 ```tsx
 <GtkNotebook>
     <x.NotebookPage label="Tab 1"><Content1 /></x.NotebookPage>
-    <x.NotebookPage label="Tab 2"><Content2 /></x.NotebookPage>
+    <x.NotebookPage label="Tab 2" tabExpand tabFill><Content2 /></x.NotebookPage>
 </GtkNotebook>
 ```
 
@@ -77,6 +77,8 @@ Custom tab widget:
 </x.NotebookPage>
 ```
 
+**NotebookPage props:** `label`, `tabExpand`, `tabFill`
+
 ### GtkPaned
 Resizable split with draggable divider. **Requires Slot components.**
 
@@ -88,7 +90,7 @@ Resizable split with draggable divider. **Requires Slot components.**
 ```
 
 ### GtkOverlay
-Stack widgets on top of each other. First child is base layer, additional children need `OverlayChild` wrapper.
+Stack widgets on top of each other. First child is base layer, additional children need `OverlayChild` wrapper. Multiple children supported per overlay.
 
 ```tsx
 <GtkOverlay>
@@ -100,20 +102,20 @@ Stack widgets on top of each other. First child is base layer, additional childr
 ```
 
 ### GtkFixed
-Absolute positioning. Use `x.FixedChild` wrapper for children.
+Absolute positioning with optional 3D transforms. Use `x.FixedChild` wrapper for children.
 
 ```tsx
 <GtkFixed>
     <x.FixedChild x={20} y={30}>
         <GtkLabel label="Top Left" />
     </x.FixedChild>
-    <x.FixedChild x={200} y={100}>
-        <GtkLabel label="Middle" />
+    <x.FixedChild x={200} y={100} transform={someGskTransform}>
+        <GtkLabel label="Transformed" />
     </x.FixedChild>
 </GtkFixed>
 ```
 
-**FixedChild props:** `x`, `y` (pixel coordinates)
+**FixedChild props:** `x`, `y` (pixel coordinates), `transform` (optional `Gsk.Transform`)
 
 ### GtkScrolledWindow
 Scrollable container.
@@ -182,7 +184,7 @@ Table with sortable columns.
         title="Size"
         id="size"
         fixedWidth={100}
-        renderCell={(item) => <GtkLabel label={item?.size ?? ""} />}
+        renderCell={(item) => <GtkLabel label={`${item?.size ?? 0} KB`} />}
     />
     {items.map(item => <x.ListItem key={item.id} id={item.id} value={item} />)}
 </GtkColumnView>
@@ -261,49 +263,67 @@ On/off switch.
 ```
 
 ### GtkSpinButton
-Numeric input with increment/decrement.
+Numeric input with increment/decrement. Adjustment props are set directly.
 
 ```tsx
-<GtkSpinButton value={count} onValueChanged={(sb) => setCount(sb.getValue())} />
+<GtkSpinButton
+    value={count}
+    lower={0}
+    upper={100}
+    stepIncrement={1}
+    onValueChanged={setCount}
+/>
 ```
 
 ### GtkScale
-Slider with optional marks.
+Slider with adjustment props and optional marks.
 
 ```tsx
 <GtkScale
     drawValue
     valuePos={Gtk.PositionType.TOP}
->
-    <x.ScaleMark value={0} label="Min" />
-    <x.ScaleMark value={50} />
-    <x.ScaleMark value={100} label="Max" />
-</GtkScale>
-```
-
-**ScaleMark props:** `value` (required), `position`, `label`
+    value={volume}
+    lower={0}
+    upper={100}
+    stepIncrement={1}
+    onValueChanged={setVolume}
+    marks={[
+        { value: 0, label: "Min", position: Gtk.PositionType.BOTTOM },
+        { value: 50, position: Gtk.PositionType.BOTTOM },
+        { value: 100, label: "Max", position: Gtk.PositionType.BOTTOM },
+    ]}
+/>
+```
+
+**Adjustment props:** `value`, `lower`, `upper`, `stepIncrement`, `pageIncrement`, `pageSize`, `onValueChanged`
+**ScaleMark type:** `{ value: number, position?: Gtk.PositionType, label?: string }`
 
 ### GtkCalendar
 Date picker with markable days.
 
 ```tsx
-<GtkCalendar onDaySelected={(cal) => setDate(cal.getDate())}>
-    <x.CalendarMark day={15} />
-    <x.CalendarMark day={20} />
-</GtkCalendar>
+<GtkCalendar
+    onDaySelected={(cal) => setDate(cal.getDate())}
+    markedDays={[15, 20, 25]}
+/>
 ```
 
 ### GtkLevelBar
 Progress/level indicator with customizable thresholds.
 
 ```tsx
-<GtkLevelBar value={0.6}>
-    <x.LevelBarOffset id="low" value={0.25} />
-    <x.LevelBarOffset id="high" value={0.75} />
-    <x.LevelBarOffset id="full" value={1.0} />
-</GtkLevelBar>
+<GtkLevelBar
+    value={0.6}
+    offsets={[
+        { id: "low", value: 0.25 },
+        { id: "high", value: 0.75 },
+        { id: "full", value: 1.0 },
+    ]}
+/>
 ```
 
+**LevelBarOffset type:** `{ id: string, value: number }`
+
 ---
 
 ## Display
@@ -500,22 +520,17 @@ Input in list row.
 Segmented button group for mutually exclusive options.
 
 ```tsx
-const [viewMode, setViewMode] = useState("list");
+const [mode, setMode] = useState("list");
 
-<AdwToggleGroup
-    activeName={viewMode}
-    onNotify={(group, prop) => {
-        if (prop === "active-name") {
-            setViewMode(group.getActiveName() ?? "list");
-        }
-    }}
->
+<AdwToggleGroup activeName={mode} onActiveChanged={(_index, name) => setMode(name ?? "list")}>
     <x.Toggle id="list" iconName="view-list-symbolic" tooltip="List view" />
     <x.Toggle id="grid" iconName="view-grid-symbolic" tooltip="Grid view" />
     <x.Toggle id="flow" label="Flow" />
 </AdwToggleGroup>
 ```
 
+**ToggleGroup props:** `activeName`, `active` (index), `onActiveChanged` (callback with index and name)
+
 **Toggle props:** `id` (optional), `label`, `iconName`, `tooltip`, `enabled`
 
 ### AdwNavigationView
@@ -525,16 +540,16 @@ Stack-based navigation with history.
 const [history, setHistory] = useState(["home"]);
 
 <AdwNavigationView history={history} onHistoryChanged={setHistory}>
-    <x.NavigationPage id="home" title="Home">
+    <x.NavigationPage for={AdwNavigationView} id="home" title="Home">
         <GtkButton label="Go to Details" onClicked={() => setHistory([...history, "details"])} />
     </x.NavigationPage>
-    <x.NavigationPage id="details" title="Details" canPop>
+    <x.NavigationPage for={AdwNavigationView} id="details" title="Details" canPop>
         <GtkLabel label="Details content" />
     </x.NavigationPage>
 </AdwNavigationView>
 ```
 
-**NavigationPage props:** `id` (required), `title`, `canPop`. Control navigation via `history` array.
+**NavigationPage props:** `for` (required, parent widget type), `id` (required), `title`, `canPop`. Control navigation via `history` array.
 
 ### AdwNavigationSplitView
 Sidebar/content split layout for master-detail interfaces.
@@ -543,20 +558,20 @@ Sidebar/content split layout for master-detail interfaces.
 const [selected, setSelected] = useState(items[0]);
 
 <AdwNavigationSplitView sidebarWidthFraction={0.33} minSidebarWidth={200} maxSidebarWidth={300}>
-    <x.NavigationPage id="sidebar" title="Sidebar">
+    <x.NavigationPage for={AdwNavigationSplitView} id="sidebar" title="Sidebar">
         <AdwToolbarView>
             <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
-            <GtkListBox cssClasses={["navigation-sidebar"]} onRowSelected={(_, row) => {
-                if (!row) return;
-                const item = items[row.getIndex()];
-                if (item) setSelected(item);
-            }}>
+            <GtkListBox cssClasses={["navigation-sidebar"]} onRowSelected={(row) => {
+                    if (!row) return;
+                    const item = items[row.getIndex()];
+                    if (item) setSelected(item);
+                }}>
                 {items.map((item) => <AdwActionRow key={item.id} title={item.title} />)}
             </GtkListBox>
         </AdwToolbarView>
     </x.NavigationPage>
 
-    <x.NavigationPage id="content" title={selected?.title ?? ""}>
+    <x.NavigationPage for={AdwNavigationSplitView} id="content" title={selected?.title ?? ""}>
         <AdwToolbarView>
             <x.ToolbarTop><AdwHeaderBar /></x.ToolbarTop>
             <GtkLabel label={selected?.title ?? ""} />
@@ -566,9 +581,40 @@ const [selected, setSelected] = useState(items[0]);
 ```
 
 **Props:** `sidebarWidthFraction`, `minSidebarWidth`, `maxSidebarWidth`, `collapsed`, `showContent`.
-**NavigationPage slots:** Use `id="sidebar"` for left pane, `id="content"` for right pane.
+**NavigationPage:** Use `for={AdwNavigationSplitView}` with `id="sidebar"` for left pane, `id="content"` for right pane.
 **Selection:** Use `GtkListBox` with `onRowSelected` (single click) not `onRowActivated` (double click).
 
+### AdwAlertDialog
+Modern modal alert dialogs with response buttons.
+
+```tsx
+const [showDialog, setShowDialog] = useState(false);
+
+{showDialog && (
+    <AdwAlertDialog
+        heading="Delete File?"
+        body="This action cannot be undone."
+        onResponse={(id) => {
+            if (id === "delete") handleDelete();
+            setShowDialog(false);
+        }}
+    >
+        <x.AlertDialogResponse id="cancel" label="Cancel" />
+        <x.AlertDialogResponse id="delete" label="Delete" appearance={Adw.ResponseAppearance.DESTRUCTIVE} />
+    </AdwAlertDialog>
+)}
+```
+
+**AlertDialogResponse props:** `id`, `label`, `appearance` (SUGGESTED, DESTRUCTIVE), `enabled`
+
+### GtkColorDialogButton / GtkFontDialogButton
+Color and font picker dialogs.
+
+```tsx
+<GtkColorDialogButton rgba={color} onRgbaChanged={setColor} title="Select Color" modal withAlpha />
+<GtkFontDialogButton fontDesc={font} onFontDescChanged={setFont} title="Select Font" modal useFont useSize />
+```
+
 ### Other Adwaita Widgets
 
 | Widget | Description |
@@ -581,6 +627,26 @@ const [selected, setSelected] = useState(items[0]);
 
 ---
 
+## Animations
+
+Wrap widgets in `x.Animation` for declarative animations with spring or timed transitions:
+
+```tsx
+<x.Animation
+    initial={{ opacity: 0, scaleX: 0.8 }}
+    animate={{ opacity: 1, scaleX: 1 }}
+    transition={{ type: "spring", stiffness: 300, damping: 20 }}
+    onAnimationComplete={() => console.log("done")}
+>
+    <GtkBox>...</GtkBox>
+</x.Animation>
+```
+
+**Props:** `initial`, `animate`, `transition`, `onAnimationComplete`
+**Transition types:** `{ type: "spring", stiffness, damping }` or `{ type: "timed", duration, easing }`
+
+---
+
 ## Drag and Drop
 
 All widgets support drag-and-drop through props. Use `onDragPrepare`, `onDragBegin`, and `onDragEnd` to make a widget draggable, and `dropTypes`, `onDrop`, `onDropEnter`, and `onDropLeave` to accept drops.
@@ -588,28 +654,23 @@ All widgets support drag-and-drop through props. Use `onDragPrepare`, `onDragBeg
 ```tsx
 import * as Gdk from "@gtkx/ffi/gdk";
 import { Type, Value } from "@gtkx/ffi/gobject";
-import { GtkButton, GtkBox, GtkLabel } from "@gtkx/react";
-import { useState } from "react";
 
-const DraggableButton = ({ label }: { label: string }) => {
-    return (
-        <GtkButton
-            label={label}
-            onDragPrepare={() => Gdk.ContentProvider.newForValue(Value.newFromString(label))}
-        />
-    );
-};
+const DraggableButton = ({ label }: { label: string }) => (
+    <GtkButton
+        label={label}
+        onDragPrepare={() => Gdk.ContentProvider.newForValue(Value.newFromString(label))}
+        dragIcon={someTexture}
+        dragIconHotX={16}
+        dragIconHotY={16}
+    />
+);
 
 const DropZone = () => {
     const [dropped, setDropped] = useState<string | null>(null);
-
     return (
         <GtkBox
             dropTypes={[Type.STRING]}
-            onDrop={(value: Value) => {
-                setDropped(value.getString());
-                return true;
-            }}
+            onDrop={(value: Value) => { setDropped(value.getString()); return true; }}
         >
             <GtkLabel label={dropped ?? "Drop here"} />
         </GtkBox>
@@ -617,6 +678,8 @@ const DropZone = () => {
 };
 ```
 
+**Drag source props:** `dragIcon`, `dragIconHotX`, `dragIconHotY`
+
 ## GValue Factories
 
 Create typed values for drag-and-drop and signal emission:
@@ -639,9 +702,7 @@ Type constants for `dropTypes`: `Type.STRING`, `Type.INT`, `Type.DOUBLE`, `Type.
 Render custom graphics with `GtkDrawingArea` using the `onDraw` callback:
 
 ```tsx
-import { GtkDrawingArea } from "@gtkx/react";
 import type { Context } from "@gtkx/ffi/cairo";
-import * as Gtk from "@gtkx/ffi/gtk";
 
 const Canvas = () => {
     const handleDraw = (self: Gtk.DrawingArea, cr: Context, width: number, height: number) => {
@@ -654,112 +715,96 @@ const Canvas = () => {
 };
 ```
 
-Use `onGestureDragBegin`, `onGestureDragUpdate`, `onGestureDragEnd` for interactive drawing. Call `widget.queueDraw()` to trigger redraws.
+Add a `GtkGestureDrag` child for interactive drawing. Call `widget.queueDraw()` to trigger redraws.
 
-## Adjustment
+## Event Controllers
 
-Configure adjustable widgets declaratively with `x.Adjustment`:
+Event controllers are added as children to any widget. They are auto-generated from GTK's introspection data.
 
 ```tsx
-import { x, GtkScale, GtkBox, GtkLabel } from "@gtkx/react";
-import * as Gtk from "@gtkx/ffi/gtk";
-import { useState } from "react";
-
-const VolumeControl = () => {
-    const [volume, setVolume] = useState(50);
-
-    return (
-        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-            <GtkScale drawValue hexpand>
-                <x.Adjustment value={volume} lower={0} upper={100} stepIncrement={1} pageIncrement={10} onValueChanged={setVolume} />
-            </GtkScale>
-            <GtkLabel label={`Volume: ${Math.round(volume)}%`} />
-        </GtkBox>
-    );
-};
+<GtkBox focusable>
+    <GtkEventControllerMotion
+        onEnter={(x, y) => console.log("Entered at", x, y)}
+        onMotion={(x, y) => setPosition({ x, y })}
+        onLeave={() => console.log("Left")}
+    />
+    <GtkEventControllerKey
+        onKeyPressed={(keyval, keycode, state) => {
+            console.log("Key pressed:", keyval);
+            return false;
+        }}
+    />
+    <GtkGestureClick onPressed={(nPress, x, y) => console.log("Clicked")} />
+    <GtkLabel label="Hover or type here" />
+</GtkBox>
 ```
 
-Works with `GtkScale`, `GtkScrollbar`, `GtkScaleButton`, `GtkSpinButton`, `GtkListBox`.
+**Input controllers:** `GtkEventControllerMotion`, `GtkEventControllerKey`, `GtkEventControllerScroll`, `GtkEventControllerFocus`
 
-**Props:** `value`, `lower`, `upper`, `stepIncrement`, `pageIncrement`, `pageSize`, `onValueChanged`
+**Gesture controllers:** `GtkGestureClick`, `GtkGestureDrag`, `GtkGestureLongPress`, `GtkGestureZoom`, `GtkGestureRotate`, `GtkGestureSwipe`, `GtkGestureStylus`, `GtkGesturePan`
 
-## TextBuffer
+**Drag-and-drop:** `GtkDragSource`, `GtkDropTarget`, `GtkDropControllerMotion`
 
-Configure `GtkTextView` buffers declaratively with `x.TextBuffer`:
+## SearchBar
 
 ```tsx
-import { x, GtkTextView, GtkScrolledWindow } from "@gtkx/react";
-import * as Gtk from "@gtkx/ffi/gtk";
-import { useState } from "react";
+const [searchActive, setSearchActive] = useState(false);
 
-const TextEditor = () => {
-    const [text, setText] = useState("Hello, World!");
-
-    return (
-        <GtkScrolledWindow minContentHeight={200}>
-            <GtkTextView wrapMode={Gtk.WrapMode.WORD_CHAR}>
-                <x.TextBuffer text={text} enableUndo onTextChanged={setText} />
-            </GtkTextView>
-        </GtkScrolledWindow>
-    );
-};
+<GtkSearchBar searchModeEnabled={searchActive} onSearchModeChanged={setSearchActive}>
+    <GtkSearchEntry text={query} onSearchChanged={(entry) => setQuery(entry.getText())} />
+</GtkSearchBar>
 ```
 
-**Props:** `text`, `enableUndo`, `onTextChanged`, `onCanUndoChanged`, `onCanRedoChanged`
+The `onSearchModeChanged` callback fires when search mode changes (e.g., user presses Escape).
 
-## SourceBuffer
+## TextView / SourceView
 
-Configure `GtkSourceView` buffers with syntax highlighting using `x.SourceBuffer`:
+Text content is provided as direct children. Use `x.TextTag` for formatting and `x.TextAnchor` for embedded widgets.
 
 ```tsx
-import { x, GtkSourceView, GtkScrolledWindow } from "@gtkx/react";
-import { useState } from "react";
+<GtkTextView enableUndo onBufferChanged={(text) => console.log(text)}>
+    Normal text, <x.TextTag id="bold" weight={Pango.Weight.BOLD}>bold</x.TextTag>, and
+    <x.TextAnchor><GtkButton label="Click" /></x.TextAnchor> inline.
+</GtkTextView>
+```
 
-const CodeEditor = () => {
-    const [code, setCode] = useState('console.log("Hello!");');
+**TextView props:** `enableUndo`, `onBufferChanged`, `onTextInserted`, `onTextDeleted`, `onCanUndoChanged`, `onCanRedoChanged`
 
-    return (
-        <GtkScrolledWindow minContentHeight={300}>
-            <GtkSourceView showLineNumbers highlightCurrentLine tabWidth={4}>
-                <x.SourceBuffer
-                    text={code}
-                    language="typescript"
-                    styleScheme="Adwaita-dark"
-                    highlightSyntax
-                    highlightMatchingBrackets
-                    enableUndo
-                    onTextChanged={setCode}
-                />
-            </GtkSourceView>
-        </GtkScrolledWindow>
-    );
-};
+**TextTag props:** `id` (required), `priority`, `foreground`, `background`, `weight`, `style`, `underline`, `strikethrough`, `family`, `size`, `sizePoints`, `scale`, `justification`, `leftMargin`, `rightMargin`, `indent`, `editable`, `invisible`
+
+**TextAnchor:** Embeds widgets inline with `children`
+
+**TextPaintable:** Embeds images inline with `paintable` prop
+
+```tsx
+<GtkSourceView
+    showLineNumbers
+    highlightCurrentLine
+    language="typescript"
+    styleScheme="Adwaita-dark"
+    highlightSyntax
+    highlightMatchingBrackets
+    enableUndo
+    onBufferChanged={setCode}
+>
+    {code}
+</GtkSourceView>
 ```
 
-**Props:** `text`, `language`, `styleScheme`, `highlightSyntax`, `highlightMatchingBrackets`, `enableUndo`, `onTextChanged`, `onCanUndoChanged`, `onCanRedoChanged`, `onCursorMoved`
+**SourceView additional props:** `language`, `styleScheme`, `highlightSyntax`, `highlightMatchingBrackets`, `implicitTrailingNewline`, `onCursorMoved`, `onHighlightUpdated`
 
 ## Keyboard Shortcuts
 
 Attach shortcuts with `x.ShortcutController` and `x.Shortcut`:
 
 ```tsx
-import { x, GtkBox, GtkLabel } from "@gtkx/react";
-import * as Gtk from "@gtkx/ffi/gtk";
-import { useState } from "react";
-
-const App = () => {
-    const [count, setCount] = useState(0);
-
-    return (
-        <GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} focusable>
-            <x.ShortcutController 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>
-            <GtkLabel label={`Count: ${count}`} />
-        </GtkBox>
-    );
-};
+<GtkBox orientation={Gtk.Orientation.VERTICAL} spacing={12} focusable>
+    <x.ShortcutController 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>
+    <GtkLabel label={`Count: ${count}`} />
+</GtkBox>
 ```
 
 **Scopes:** `LOCAL` (widget focus), `MANAGED` (parent managed), `GLOBAL` (window-wide)