Skip to main content

index

A mockup tool for Adwaita app UIs that obeys the GNOME HIG.

Uses real @gjsify/adwaita-web web components so mockups look and behave like real Adwaita — not pixel replicas.

Live: https://tuna-os.github.io/protota/

Contribute compute — no code needed​

Donate time with your AI CLI.

Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.

The guide covers prerequisites, verified just setup, credentials, provider costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply. Never post account credentials or API keys in issues or pull requests.

Development​

npm install
npm run dev # Vite dev server
npx tsc -b # TypeScript typecheck — CI runs this on every PR
npm run lint # oxlint
npm run build # Production build → dist/
npm run test:unit # Blueprint/renderer conformance tests
npm test # Playwright tests

just check runs lint, unit tests, and build together.

Rendering and conformance​

Protota renders GTK4/Libadwaita from a typed widget tree. The renderer is generic: presets must not add branches for one app. An import of Blueprint or GtkBuilder keeps the tree structure and the properties that Protota supports. The import reports unknown visual widgets, so that a contributor can add support for them on purpose.

Editing an app UI file​

Import a work-in-progress .blp (Blueprint) or .ui (GtkBuilder) file using File → Import. Protota turns it into an editable MockupDocument. When you finish your changes, use File → Export Blueprint. Then replace the related UI file in your checkout and build the app again. The browser downloads the result on purpose; it does not write into a local source tree. An import of an unsupported GTK/Libadwaita widget fails with an error, so the output UI is never a plausible-but-wrong substitute.

Building presets and flows​

docs/components.md lists every component Protota can build with — the GTK class it exports as, its named slots, editable properties, and legal children. A script makes it from the code, so it cannot drift. To regenerate it after you change component definitions, run npx tsx scripts/generate-component-reference.mjs. The script imports .ts sources, so plain node fails with ERR_MODULE_NOT_FOUND; npx tsx is required.

A script makes each preset from the official app source. A person then completes it with override files that others can review. See docs/preset-workflow.md for the full toolchain (scripts/import-gnome-app.mjs, scripts/capture-preset.mjs, presets-src/*.finishing.json) and for the MockupBuilder agent API that exposes the same capabilities (source import, multi-screen flows, override files) programmatically.

The tests/fixtures/gnome-app-catalog.json catalog connects a GNOME app, its source (repository + pinned tag), its preset, and a canonical viewport. The manual Broadway Reference Capture GitHub workflow runs the native app under GTK Broadway and uploads its capture alongside the matching Protota preset. This provides an external visual oracle while the structural tests keep the renderer honest. Each run also creates a pixel-diff image and JSON metric. It reports the metric when you tune a baseline. If you supply a maximum difference ratio, the same comparison becomes a CI gate for a calibrated preset.

To list the suite that you can run now on your computer, use node scripts/broadway-app.mjs --list. To add an app, add its catalogue entry and its preset together. The conformance test rejects an untracked preset. It also rejects an incomplete native-reference target. Core and Circle use the same catalogue fields and renderer path.

See visual conformance of GNOME apps for the current validation state. "Passed" always means that a person looked at the paired screenshots and their diff, not only that a capture command exited. See the source-import loop for GNOME Core for the official-source UI inputs and explicit custom-widget boundaries. See GNOME GUI Specification & Audits for UI layout patterns, intent mappings, and per-app source audits — a vendored read-only snapshot of gnome-gui-spec, not a build input.

Pull requests​

Do not stop a required check; let it complete. If the repository has no merge queue and a maintainer explicitly authorizes a protected-branch merge, use the merge path that maintainers approve. See AGENTS.md for the exact procedure and resource-use guidance.

License​

Apache-2.0 — see LICENSE.