# gigit

A desktop git GUI client. Tauri 2 + Solid, with a colourful commit graph whose layout is
computed in Rust and streamed to the frontend.

## Stack

| Layer         | Choice                                                              |
| ------------- | ------------------------------------------------------------------- |
| Shell         | Tauri 2                                                             |
| Frontend      | Solid 2 (beta), TypeScript 7, Vite                                  |
| Styling       | Tailwind CSS v4 (CSS-first config) + `@claas.dev/material-tailwind` |
| Lint / format | Oxc — `oxlint` and `oxfmt`. **Not** ESLint or Prettier.             |
| Git access    | `gix` (gitoxide), reads only for now                                |
| Async         | tokio                                                               |

`crates/gigit-git` holds git access and the graph layout engine and knows nothing about
Tauri, so it can be tested and benchmarked with plain `cargo test`. `src-tauri` holds the
actors, commands and channels.

## Architecture rules

- **Logic goes in Rust.** The frontend renders and handles input; it does not compute.
- **Actors, not mutexes.** Shared state gets an owning actor — a handle plus
  `tokio::sync::mpsc` and `oneshot`, per <https://ryhl.io/blog/actors-with-tokio/>. No
  `Mutex`/`RwLock` without a stated reason the actor pattern doesn't fit. A `gix::Repository`
  is blocking and thread-affine, so its actor runs on a dedicated `std::thread` draining its
  receiver with `blocking_recv()`.
- **Stream anything large.** List-shaped data crosses IPC as pull-based chunks over
  `tauri::ipc::Channel`, driven by the frontend asking for more — never one big response.
- **Rule of least power** (<https://www.w3.org/2001/tag/doc/leastPower.html>): semantic HTML
  first, then CSS, then JavaScript. A CSS solution beats a JS one.
- **Accessibility is a requirement.** Keyboard operability and correct AT semantics are part
  of the work, not a follow-up. Decorative graphics are `aria-hidden` over content that
  already reads correctly without them.

## Browser support policy

The only targets are Tauri's webviews: WKWebView (Safari) on macOS, WebView2 (Chromium) on
Windows, WebKitGTK on Linux. Baseline Newly available features are fine where they degrade
gracefully. No polyfills. Hand-written fallbacks only when under ~20 lines and dependency-free.

Use the `modern-web-guidance` skill before starting frontend work.

## Dependencies

**Ask before adding any npm or cargo dependency**, and list notable transitive ones. Prefer a
platform feature over a library.

## Licence and attribution

gigit is MIT. Adapted or copied code must carry attribution including its licence, in
`NOTICE.md`.

Specifically: the commit graph is implemented from the algorithm _described_ in
<https://pvigier.github.io/2019/05/06/commit-graph-drawing-algorithms.html>. Its reference
implementation, [gitamine](https://github.com/pvigier/gitamine), is **GPL-3.0** — do not read
or port its source.

## Testing the UI

The frontend is an ordinary web page, so it is tested in real browsers with the IPC
boundary mocked — no native build, no app window, and no system permissions. Rendering,
keyboard behaviour and accessibility are all checked this way rather than by looking at
screenshots.

- `tests/unit` — Vitest with `@solidjs/testing-library`, for components and stores.
- `tests/e2e` — Playwright against **WebKit and Chromium**. WebKit is the important one:
  it is what WKWebView on macOS actually is, so it is the only way to find out whether
  something works in the shipped app. It has already caught two behaviours Chromium does
  not have.
- `tests/e2e/tauri.ts` is the only file that knows about `window.__TAURI_INTERNALS__`, so
  a Tauri upgrade that moves it breaks in one place.
- `tests/fixtures/rows.ts` builds graph rows typed as the real `GraphRow`, so a change to
  the Rust types stops the tests compiling instead of letting them drift.

No screenshot baselines: they differ by operating system and font rendering, so they fail
for reasons unrelated to the change. Assert computed styles and the accessibility tree.

## Commands

```
pnpm tauri dev        # run the app
pnpm typecheck        # tsc --noEmit
pnpm lint             # oxlint
pnpm format           # oxfmt .
pnpm format:check     # oxfmt --check .
pnpm test             # vitest run
pnpm test:e2e         # playwright test (webkit + chromium)
cargo test --workspace
cargo clippy --workspace
```

Playwright needs its browsers once: `pnpm exec playwright install webkit chromium`.

## Workflow

Work ships as stacked PRs using the `gh-stack` skill — small, reviewable layers where
foundational changes sit below dependent ones.