@gtkx/cli 0.14.0 → 0.16.0

package/dist/mcp-client.js

@@ -1,5 +1,6 @@
 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";
 import { getApplication } from "@gtkx/react";
@@ -45,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:
@@ -92,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);
     }
@@ -290,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 }) };
@@ -299,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;
@@ -354,7 +365,32 @@ class McpClient {
                 if (!widget) {
                     throw widgetNotFoundError(p.widgetId);
                 }
-                const signalArgs = (p.args ?? []);
+                const signalArgs = (p.args ?? []).map((arg) => {
+                    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(argValue);
+                        case "int":
+                            return Value.newFromInt(argValue);
+                        case "uint":
+                            return Value.newFromUint(argValue);
+                        case "int64":
+                            return Value.newFromInt64(argValue);
+                        case "uint64":
+                            return Value.newFromUint64(argValue);
+                        case "float":
+                            return Value.newFromFloat(argValue);
+                        case "double":
+                        case "number":
+                            return Value.newFromDouble(argValue);
+                        case "string":
+                            return Value.newFromString(argValue);
+                        default:
+                            throw new McpError(McpErrorCode.INVALID_REQUEST, `Unknown argument type: ${argType}`);
+                    }
+                });
                 await testing.fireEvent(widget, p.signal, ...signalArgs);
                 return { success: true };
             }

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.14.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/ffi": "0.14.0",
-    "@gtkx/mcp": "0.14.0",
-    "@gtkx/react": "0.14.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.14.0"
+    "memfs": "^4.56.9",
+    "@gtkx/testing": "0.16.0"
   },
   "peerDependencies": {
     "react": "^19",
-    "@gtkx/testing": "0.14.0"
+    "@gtkx/testing": "0.16.0"
   },
   "peerDependenciesMeta": {
     "@gtkx/testing": {

package/templates/claude/EXAMPLES.md.ejs

@@ -339,7 +339,7 @@ const FileTable = () => {
 
     return (
         <GtkScrolledWindow vexpand cssClasses={["card"]}>
-            <GtkColumnView estimatedRowHeight={48} sortColumn={sortColumn} sortOrder={sortOrder} onSortChange={handleSort}>
+            <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 ?? ""} />} />
@@ -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,28 +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 active={view} onToggled={setView} 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.
@@ -169,7 +171,7 @@ Grid-based virtual scrolling.
 Table with sortable columns.
 
 ```tsx
-<GtkColumnView estimatedRowHeight={48} sortColumn="name" sortOrder={Gtk.SortType.ASCENDING} onSortChange={handleSort}>
+<GtkColumnView estimatedRowHeight={48} sortColumn="name" sortOrder={Gtk.SortType.ASCENDING} onSortChanged={handleSort}>
     <x.ColumnViewColumn<Item>
         title="Name"
         id="name"
@@ -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,13 +520,17 @@ Input in list row.
 Segmented button group for mutually exclusive options.
 
 ```tsx
-<AdwToggleGroup active={viewMode} onToggled={setViewMode}>
+const [mode, setMode] = useState("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
@@ -516,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.
@@ -534,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 ?? ""} />
@@ -557,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 |
@@ -572,44 +627,188 @@ 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.
 
 ```tsx
 import * as Gdk from "@gtkx/ffi/gdk";
-import * as GObject from "@gtkx/ffi/gobject";
-import { typeFromName } from "@gtkx/ffi/gobject";
-import { GtkButton, GtkBox, GtkLabel } from "@gtkx/react";
-import { useState } from "react";
-
-const DraggableButton = ({ label }: { label: string }) => {
-    const stringType = typeFromName("gchararray");
-    const value = new GObject.Value();
-    value.init(stringType);
-    value.setString(label);
-
-    return (
-        <GtkButton
-            label={label}
-            onDragPrepare={() => Gdk.ContentProvider.newForValue(value)}
-        />
-    );
-};
+import { Type, Value } from "@gtkx/ffi/gobject";
+
+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);
-    const stringType = typeFromName("gchararray");
-
     return (
         <GtkBox
-            dropTypes={[stringType]}
-            onDrop={(value: GObject.Value) => {
-                setDropped(value.getString());
-                return true;
-            }}
+            dropTypes={[Type.STRING]}
+            onDrop={(value: Value) => { setDropped(value.getString()); return true; }}
         >
             <GtkLabel label={dropped ?? "Drop here"} />
         </GtkBox>
     );
 };
+```
+
+**Drag source props:** `dragIcon`, `dragIconHotX`, `dragIconHotY`
+
+## GValue Factories
+
+Create typed values for drag-and-drop and signal emission:
+
+| Factory                        | Description                   |
+| ------------------------------ | ----------------------------- |
+| `Value.newFromString(str)`     | String values                 |
+| `Value.newFromDouble(num)`     | 64-bit floating point         |
+| `Value.newFromInt(num)`        | 32-bit signed integer         |
+| `Value.newFromBoolean(bool)`   | Boolean values                |
+| `Value.newFromObject(obj)`     | GObject instances             |
+| `Value.newFromBoxed(boxed)`    | Boxed types (Gdk.RGBA, etc.)  |
+| `Value.newFromEnum(gtype, n)`  | Enum values (requires GType)  |
+| `Value.newFromFlags(gtype, n)` | Flags values (requires GType) |
+
+Type constants for `dropTypes`: `Type.STRING`, `Type.INT`, `Type.DOUBLE`, `Type.BOOLEAN`, `Type.OBJECT`.
+
+## Custom Drawing
+
+Render custom graphics with `GtkDrawingArea` using the `onDraw` callback:
+
+```tsx
+import type { Context } from "@gtkx/ffi/cairo";
+
+const Canvas = () => {
+    const handleDraw = (self: Gtk.DrawingArea, cr: Context, width: number, height: number) => {
+        cr.setSourceRgb(0.2, 0.4, 0.8);
+        cr.rectangle(10, 10, width - 20, height - 20);
+        cr.fill();
+    };
+
+    return <GtkDrawingArea contentWidth={400} contentHeight={300} onDraw={handleDraw} />;
+};
+```
+
+Add a `GtkGestureDrag` child for interactive drawing. Call `widget.queueDraw()` to trigger redraws.
+
+## Event Controllers
+
+Event controllers are added as children to any widget. They are auto-generated from GTK's introspection data.
+
+```tsx
+<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>
+```
+
+**Input controllers:** `GtkEventControllerMotion`, `GtkEventControllerKey`, `GtkEventControllerScroll`, `GtkEventControllerFocus`
+
+**Gesture controllers:** `GtkGestureClick`, `GtkGestureDrag`, `GtkGestureLongPress`, `GtkGestureZoom`, `GtkGestureRotate`, `GtkGestureSwipe`, `GtkGestureStylus`, `GtkGesturePan`
+
+**Drag-and-drop:** `GtkDragSource`, `GtkDropTarget`, `GtkDropControllerMotion`
+
+## SearchBar
+
+```tsx
+const [searchActive, setSearchActive] = useState(false);
+
+<GtkSearchBar searchModeEnabled={searchActive} onSearchModeChanged={setSearchActive}>
+    <GtkSearchEntry text={query} onSearchChanged={(entry) => setQuery(entry.getText())} />
+</GtkSearchBar>
+```
+
+The `onSearchModeChanged` callback fires when search mode changes (e.g., user presses Escape).
+
+## TextView / SourceView
+
+Text content is provided as direct children. Use `x.TextTag` for formatting and `x.TextAnchor` for embedded widgets.
+
+```tsx
+<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>
+```
+
+**TextView props:** `enableUndo`, `onBufferChanged`, `onTextInserted`, `onTextDeleted`, `onCanUndoChanged`, `onCanRedoChanged`
+
+**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>
+```
+
+**SourceView additional props:** `language`, `styleScheme`, `highlightSyntax`, `highlightMatchingBrackets`, `implicitTrailingNewline`, `onCursorMoved`, `onHighlightUpdated`
+
+## Keyboard Shortcuts
+
+Attach shortcuts with `x.ShortcutController` and `x.Shortcut`:
+
+```tsx
+<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)
+
+**Trigger syntax:** `<Control>s`, `<Control><Shift>s`, `<Alt>F4`, `<Primary>q`, `F5`
+
+**Multiple triggers:** `trigger={["F5", "<Control>r"]}`