@gtkx/gl 0.21.0 → 1.0.0-rc.1

package/README.md

@@ -1,118 +1,173 @@
 <p align="center">
-  <img src="logo.svg" alt="gtkx" width="180" />
+  <img src="https://raw.githubusercontent.com/gtkx-org/gtkx/main/logo.svg" alt="GTKX" width="100" />
 </p>
 
-# gtkx
+<h1 align="center">GTKX</h1>
 
-gtkx is a framework for building native GTK4/libadwaita desktop applications with React, TypeScript, and JSX. You write declarative JSX whose element types are GTK widget names; a custom react-reconciler maps that tree to live GObject instances, while a Rust napi addon owns the single GLib main-loop thread and performs every call into GTK. A build-time generator turns GObject-Introspection (GIR) XML into typed bindings, JSX element types, and reconciler metadata, and a Vite-based CLI provides scaffolding, a hot-reloading dev server, single-file production bundling, and GTK-asset integration.
-
-Homepage: [gtkx.dev](https://gtkx.dev)
+<p align="center">
+  The React framework for Linux.<br />
+  Build GTK4 and Adwaita apps in TypeScript, with React components and hooks driving GNOME's own widgets. What you ship is a GNOME app.
+</p>
 
-![gtkx demo](demo.gif)
+<p align="center">
+  <a href="https://www.npmjs.com/package/create-gtkx"><img src="https://img.shields.io/npm/v/create-gtkx?color=cb3837&logo=npm&label=create-gtkx" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/create-gtkx"><img src="https://img.shields.io/npm/dm/create-gtkx?color=cb3837&logo=npm&label=downloads" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A524-339933?logo=node.js&logoColor=white" alt="Node >= 24" />
+  <a href="https://github.com/gtkx-org/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License: MPL-2.0" /></a>
+  <a href="https://github.com/gtkx-org/gtkx/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/gtkx-org/gtkx/ci.yml?branch=main&logo=github&label=CI" alt="CI status" /></a>
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
 
-## Prerequisites
+<p align="center">
+  <a href="https://gtkx.dev">Homepage</a> &middot;
+  <a href="https://gtkx.dev/guide/why-gtkx">Documentation</a> &middot;
+  <a href="https://github.com/gtkx-org/gtkx/tree/main/examples">Examples</a> &middot;
+  <a href="https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md">Contributing</a>
+</p>
 
-This is a Linux desktop framework, not a browser/DOM renderer. You need:
+---
 
-- **Node.js** — the engines floor is Node `>=24`.
-- **pnpm** — the workspace package manager, provisioned via Corepack from the `packageManager` field.
-- **Rust toolchain** — 2024 edition with a C linker, plus the napi-rs CLI and Node N-API headers, to compile the native addon. A nightly toolchain is additionally required for the coverage, asan, and miri paths.
-- **libffi** — for dynamic CIF construction and closures in the native addon.
-- **GTK4 and libadwaita** development libraries, plus the broader GNOME library set the examples use (GtkSourceView, WebKitGTK, VTE, GStreamer, etc.), with `pkg-config`.
-- **GLib/GObject** shared libraries present at build and run time; gtkx resolves GTK symbols dynamically by name.
-- **GObject-Introspection** development data and system GIR files (read by codegen), plus `glib-compile-resources` and `glib-compile-schemas` for asset compilation.
-- **A headless Wayland compositor** (Weston, or Sway when `GTKX_COMPOSITOR=sway`) and software GL/Vulkan rasterization to run GTK tests and benches without a GPU.
-- **git**, for repository initialization during scaffolding.
+GTKX generates fully typed bindings for the entire GTK4 and Adwaita surface directly from GObject-Introspection. On top of those bindings you get the React programming model: components and hooks driving GObject instances, with Fast Refresh while you develop.
 
-For the containerized CI path you additionally need Docker; the CI image pins the full GTK/Rust/Node toolchain.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gtkx-org/gtkx/main/examples/tutorial/assets/screenshot.png" alt="The Tasks app: an Adwaita window with a sidebar of smart views and colored lists on the left, and a boxed task list on the right." />
+</p>
 
-## Getting started
+<p align="center">
+  <em>The Tasks app you build in the <a href="https://gtkx.dev/tutorial/">tutorial</a>.</em>
+</p>
 
-```sh
-git clone https://github.com/gtkx-org/gtkx.git
-cd gtkx
-corepack enable
-pnpm install
-pnpm build
+## Demo
+
+The intrinsic elements in this snippet render GTK4 widgets, and ordinary React hooks and events drive them:
+
+```tsx
+import * as Gtk from "@gtkx/gi/gtk";
+import { GtkApplication, GtkApplicationWindow, GtkBox, GtkButton, GtkLabel } from "@gtkx/jsx/gtk";
+import { createRoot, quit } from "@gtkx/react";
+import { useState } from "react";
+
+const Counter = () => {
+  const [count, setCount] = useState(0);
+
+  return (
+    <GtkApplicationWindow
+      title="Hello GTKX"
+      defaultWidth={400}
+      defaultHeight={300}
+      onCloseRequest={quit}
+    >
+      <GtkBox
+        orientation={Gtk.Orientation.VERTICAL}
+        spacing={20}
+        marginTop={40}
+        marginBottom={40}
+        marginStart={40}
+        marginEnd={40}
+        valign={Gtk.Align.CENTER}
+        halign={Gtk.Align.CENTER}
+      >
+        <GtkLabel cssClasses={["title-1"]}>Welcome to GTKX!</GtkLabel>
+        <GtkLabel cssClasses={["title-2"]}>{`Count: ${count}`}</GtkLabel>
+        <GtkButton
+          label="Increment"
+          onClicked={() => setCount((c) => c + 1)}
+          cssClasses={["suggested-action", "pill"]}
+        />
+      </GtkBox>
+    </GtkApplicationWindow>
+  );
+};
+
+const App = () => (
+  <GtkApplication>
+    <Counter />
+  </GtkApplication>
+);
+
+createRoot().render(<App />);
 ```
 
-`pnpm build` runs the Rust `native-build` and `@gtkx/cli#codegen` first (hard Turbo upstreams), so the first build compiles the addon and generates the `@gtkx/gi`/`@gtkx/jsx` binding stores before any TypeScript package builds.
+This is the [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world) example, with `app.tsx` and `index.tsx` combined into a single snippet. `@gtkx/gi` and `@gtkx/jsx` are per-project bindings generated by the CLI, not packages you install from npm.
 
-## Common commands
+## Why GTKX
 
-All root scripts run through Turbo over the workspace (the root meta-package is excluded with `--filter=!gtkx`).
+### A declarative layer for the GNOME stack
 
-| Command | Description |
-| --- | --- |
-| `pnpm build` | Build all workspace packages (runs codegen + native-build first). |
-| `pnpm --filter <pkg> dev` | Start a package/example dev server (hot-reloading `gtkx dev`); see [Running the examples](#running-the-examples). There is no root `dev` script. |
-| `pnpm test` | Run the Vitest workspace plus per-package test scripts. |
-| `pnpm typecheck` | Type-check every package via `tsc -b --emitDeclarationOnly` across the reference graph. |
-| `pnpm lint` | Full quality gate: ts-reference drift check, biome, knip (default + production), dependency-cruiser, plus per-package lint (Rust fmt/clippy on native). |
-| `pnpm codegen` | Generate/refresh the `.gtkx` GIR and JSX binding stores consumed by other packages. |
-| `pnpm coverage` | Aggregated v8 lcov coverage (TS) plus native Rust coverage. |
-| `pnpm sync:ts-refs` | Rewrite TypeScript project references from `package.json` deps and format them (add `--check` to fail on drift). |
-| `pnpm asan` / `pnpm miri` / `pnpm bench` | Native AddressSanitizer suite, Miri marshalling subset, and CodSpeed benchmarks under the headless compositor. |
-| `pnpm release` | Build, inject README into published packages, stage native artifacts, and publish to npm. |
-| `pnpm publish-test` | Publish to an ephemeral Verdaccio registry, then scaffold, build, typecheck, and test a consumer app end-to-end. |
+GTK4 is mature, and GtkBuilder XML can lay out a static interface, but nothing re-renders that interface when your application state changes, and nothing hot-reloads it as you work. GTKX adds that missing layer, and the tooling around it, on top of the stack you already know:
 
-To run tests for a single package, filter through Turbo or pnpm, for example:
+- a React reconciler that exposes every GObject as a JSX element,
+- a CLI for scaffolding, development, and production builds,
+- a dev server with Fast Refresh that patches your running UI in place,
+- CSS-in-JS styling and high-level list, grid, and dialog components,
+- a Testing Library-style API for querying and driving your widgets in tests,
+- and a Model Context Protocol (MCP) server that exposes your live app to AI agents.
 
-```sh
-pnpm --filter @gtkx/ffi test
-pnpm --filter @gtkx/react test
-pnpm --filter @gtkx/cli build
-```
+### The full GNOME API surface
 
-## Running the examples
+React Native and similar frameworks hide the native toolkit so one API can run everywhere. GTKX exposes it: GTK4, Adwaita, and any other GObject-Introspection library on your system. Linux-only by design.
 
-Each example exposes the standard `dev`, `build`, and `start` scripts that wrap the CLI (`gtkx dev` / `gtkx build` / `node dist/bundle.js`).
+### Why Node.js, and why generated bindings
 
-```sh
-# Counter app demonstrating the basics
-pnpm --filter hello-world dev
+GTKX runs on Node.js, which puts native modules, the npm ecosystem, and the tooling built for Node.js APIs within reach. GJS is GNOME's own runtime, built on SpiderMonkey rather than V8; node-gtk runs on Node.js but is lightly maintained, on the older nan/V8 ABI rather than N-API, and still centered on GTK3. The [why-gtkx guide](https://gtkx.dev/guide/why-gtkx) covers the comparison in full.
 
-# Notes app from the tutorial (uses @gtkx/css and @gtkx/animate, GSettings via #data)
-pnpm --filter tutorial dev
+GTKX generates the TypeScript types and the native FFI calls from the same GObject-Introspection data, so the types cannot drift from the calls they back. Codegen covers the whole GTK4 and Adwaita surface.
 
-# GTK4 widget showcase (the React port of the official gtk-demo; the only example with tests)
-pnpm --filter gtk-demo dev
-pnpm --filter gtk-demo coverage
+At runtime, the native Rust core calls straight into the system GTK4, Adwaita, and GLib libraries through libffi, without loading libgirepository at all.
 
-# Simple browser using WebKitWebView
-pnpm --filter browser dev
-```
+## Quick start
 
-Build and run any example's production bundle:
+GTKX is Linux-only and needs Node.js 24 or later. See [Requirements](#requirements).
+
+Scaffold a new app with the `create-gtkx` initializer:
 
 ```sh
-pnpm --filter hello-world build
-pnpm --filter hello-world start
+npm create gtkx@rc
 ```
 
-The tutorial additionally packages as a single executable (`pnpm --filter tutorial build:sea`) and as a Flatpak (`pnpm --filter tutorial build:flatpak`); these need esbuild, postject, and a Flatpak toolchain.
+The same command works with other package managers: `pnpm create gtkx@rc` or `yarn create gtkx@rc`.
+
+Then run your new app:
 
-## Gotchas
+```sh
+cd my-app
+npm run dev
+```
 
-- **codegen and native-build come first.** A clean checkout cannot type-check or build any TypeScript package until the Rust addon is compiled and codegen has produced `.gtkx`; both are hard Turbo upstreams. `pnpm lint` first creates the `.gtkx` symlink that knip and dependency-cruiser resolve against.
-- **Generated packages are not hand-edited.** `@gtkx/gi`, `@gtkx/jsx`, and the generated `@gtkx/gl` sources come from `@gtkx/codegen`. Change the emitters or `gtkx.config.ts` and regenerate (`pnpm codegen`); the store swap is atomic, so partial writes never appear.
-- **GTK tests/benches need a headless display.** Running native `test`/`coverage`/`asan` or the GTK suites outside the headless wrapper fails to initialize a display; the harness provisions a Wayland compositor with software rendering. Native tests run single-threaded because GTK requires a single owning thread.
-- **The native runtime is single-use.** All GObject/GTK mutation runs only on the single `gtkx-glib` thread; native init is one-shot and quit is terminal, so a process cannot restart the runtime. Importing `@gtkx/ffi` starts the GLib main loop and registers a process exit handler.
-- **Project references track deps.** TypeScript references are generated from `package.json` dependency fields by `sync-ts-references`; hand-editing them is reported as drift by the `--check` run in lint. Change deps, then run `pnpm sync:ts-refs`.
-- **`@gtkx/testing` cleanup is not automatic.** Consumers must register `cleanup()` (the e2e setup wires it into `afterEach`/`afterAll`), or leaked windows persist across tests.
-- **The dev loop restarts via exit code 75.** The dev supervisor and runner signal restart intent purely through process exit code 75; Fast Refresh applies only to SSR-transformed project files where every export looks like a React component, otherwise the whole process restarts.
+To go further, follow the [tutorial](https://gtkx.dev/tutorial/).
 
 ## Documentation
 
-Architecture and subsystem docs live under `docs/`:
+The documentation at **[gtkx.dev](https://gtkx.dev)** includes a step-by-step tutorial that builds a complete GNOME app, from scaffolding to packaging and shipping, plus guides and a full API reference.
+
+**[Read the docs &rarr;](https://gtkx.dev/guide/why-gtkx)**
+
+## Requirements
+
+GTKX is Linux-only. You need:
+
+- Linux with the GTK4 (4.20 or later), Adwaita (1.8 or later), and GLib development libraries
+- Node.js 24 or later
+
+The `@gtkx/native` addon ships prebuilt for x64 and arm64 glibc Linux; other targets need to build it from the GTKX repository, which requires a Rust toolchain.
+
+## Examples
+
+Explore the [example apps](https://github.com/gtkx-org/gtkx/tree/main/examples):
+
+- [`hello-world`](https://github.com/gtkx-org/gtkx/tree/main/examples/hello-world): the counter above.
+- [`gtk-demo`](https://github.com/gtkx-org/gtkx/tree/main/examples/gtk-demo): a React port of the official GTK4 widget showcase, covering lists, dialogs, gestures, CSS, and OpenGL.
+- [`browser`](https://github.com/gtkx-org/gtkx/tree/main/examples/browser): a WebKitWebView-based web browser.
+- [`tutorial`](https://github.com/gtkx-org/gtkx/tree/main/examples/tutorial): the Tasks app the documentation builds.
+
+## Status
+
+GTKX 1.0 is at the release candidate stage.
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](https://github.com/gtkx-org/gtkx/blob/main/CONTRIBUTING.md), the [Code of Conduct](https://github.com/gtkx-org/gtkx/blob/main/CODE_OF_CONDUCT.md), and the [security policy](https://github.com/gtkx-org/gtkx/blob/main/SECURITY.md). Building the repo needs Node.js 24 or later, pnpm, and a Rust toolchain.
 
-- [`docs/architecture.md`](docs/architecture.md) — architecture overview and layer stack.
-- [`docs/rendering.md`](docs/rendering.md) — the render and event pipeline.
-- [`docs/codegen.md`](docs/codegen.md) — the GIR/Khronos code generator and the runtime contract.
-- [`docs/cli.md`](docs/cli.md) — the CLI and project workflow.
-- [`docs/styling.md`](docs/styling.md) — styling, animation, and GL.
-- [`docs/mcp.md`](docs/mcp.md) — the MCP server.
-- [`docs/testing.md`](docs/testing.md) — the testing architecture.
-- [`docs/build-system.md`](docs/build-system.md) — the build system and quality tooling.
+## License
 
-For an agent-oriented index of packages and the hard build rules, see [`CLAUDE.md`](CLAUDE.md).
+GTKX is licensed under [MPL-2.0](https://github.com/gtkx-org/gtkx/blob/main/LICENSE).