Add CUDA backend for Linux/NVIDIA (GB10-tested) and h3c studio web UI

.env.example

@@ -0,0 +1,39 @@
+# Copy to .env and adjust. Only H3_MODEL_DIR is required.
+
+# The MiniMax-H3 checkpoint directory, mounted read-only (about 465 GB).
+H3_MODEL_DIR=./MiniMax-H3
+
+# Where jobs, uploads and generated videos are written. Keep this separate
+# from the local development directory: the container writes as root.
+H3_DATA_DIR=./data
+
+# CUDA architecture the h3 binary is compiled for. sm_121 is the NVIDIA GB10.
+NVCC_ARCH=sm_121
+
+# Interface the UI is published on. 127.0.0.1 keeps it on this machine only.
+# To reach it from another machine, use a private-network address rather than
+# 0.0.0.0: accounts are required, but the service serves plain HTTP. With
+# Tailscale, `tailscale ip -4` prints the address to use, and only your
+# tailnet can then connect.
+H3_BIND=127.0.0.1
+
+# The administrator account. It is created once, on the first start of an
+# empty database; afterwards these values are ignored and the password is
+# managed from the People tab in the UI. Every other account is made with a
+# single-use invite from that tab. Change both before the first start.
+H3_ADMIN_USERNAME=admin
+H3_ADMIN_PASSWORD=change-me-before-first-start
+
+# Largest accepted upload, in bytes (512 MB).
+H3_MAX_UPLOAD_BYTES=536870912
+
+# Optional post-processing runtime. Left empty, the faceswap plugin stays
+# unavailable and nothing is downloaded. See docs/POSTPROCESSING.md.
+H3_FACESWAP_CMD=
+
+# Read only by scripts/faceswap-facefusion.sh, the adapter that install.sh
+# points H3_FACESWAP_CMD at: where FaceFusion is, and the image of the face to
+# put in. The second one is yours to choose, and the stage refuses to run
+# without it.
+H3_FACEFUSION_DIR=
+H3_FACESWAP_SOURCE=

.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+# CI without a GPU: everything that does not need CUDA or the 465 GB
+# checkpoint. The end-to-end render stays a local gate: no runner has the
+# hardware or the model.
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  backend:
+    name: Backend (lint + tests)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install FFmpeg
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
+      - name: Install dependencies
+        run: |
+          python -m venv webui/backend/.venv
+          webui/backend/.venv/bin/pip install --upgrade pip
+          webui/backend/.venv/bin/pip install \
+            "fastapi>=0.115" "uvicorn[standard]>=0.34" "pydantic-settings>=2.6" \
+            "argon2-cffi>=23.1" python-multipart pytest httpx ruff
+      - name: Lint
+        run: webui/backend/.venv/bin/ruff check webui
+      - name: Tests
+        run: webui/backend/.venv/bin/pytest webui/backend/tests -q
+
+  frontend:
+    name: Frontend (build + lint)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - name: Install repo tooling
+        run: npm install --no-audit --no-fund
+      - name: Install frontend dependencies
+        run: npm install --no-audit --no-fund
+        working-directory: webui/frontend
+      - name: Regenerate the options module and check it is committed
+        run: |
+          node scripts/generate-options.mjs
+          git diff --exit-code src/generated/options.ts
+        working-directory: webui/frontend
+      - name: Build
+        run: npm run build
+        working-directory: webui/frontend
+      - name: Lint
+        run: npx eslint .
+
+  compose:
+    name: Docker compose files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate compose configuration
+        env:
+          H3_MODEL_DIR: ./MiniMax-H3
+          # Compose requires it (`:?`); config validation only needs it to
+          # exist, so this placeholder never reaches a running container.
+          H3_ADMIN_PASSWORD: ci-placeholder-not-a-secret
+        run: |
+          docker compose config >/dev/null
+          H3_FACESWAP_CMD=/opt/faceswap/run H3_FACESWAP_DIR=/opt/faceswap \
+            docker compose -f docker-compose.yml -f docker-compose.faceswap.yml \
+            config >/dev/null

.gitignore

@@ -2,6 +2,7 @@
 misc/
 MiniMax-H3/
 outputs/
+logs/
 .ruff_cache/
 
 # Compiler and test outputs.
@@ -12,7 +13,7 @@ outputs/
 h3
 h3_*test
 h3_*tests
-h3_*bench
+h3_*bench*
 h3_dit_bench_864
 h3_tests
 h3_metal_tests
@@ -28,3 +29,32 @@ h3_real_video_vae_test
 h3_semantic_vae_test
 libh3.a
 .DS_Store
+._*
+
+# Node dev tooling and web UI build output.
+node_modules/
+webui/frontend/dist/
+webui/backend/.venv/
+webui/backend/data/
+data/
+__pycache__/
+.pytest_cache/
+
+# Local docker env
+.env
+
+# Agent method files: they guide work on this machine (R35, 2026-08-30) but
+# are not part of the public repository.
+PLAN.md
+PLAN.template.md
+PLAN_ARCHIVE.md
+AGENTS.md
+CLAUDE.md
+docs/AGENT_SOP.md
+scripts/agent_logging.py
+scripts/health_report.sh
+scripts/install_git_hook.sh
+
+# Python packaging artefacts from a local `pip install` of the backend.
+webui/backend/build/
+*.egg-info/

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for looking. This is a small project with a strict habit: **nothing is
+marked done until a command says so.**
+
+## Before you start
+
+If you are adding something substantial, open an issue first and say what you
+intend to change; a plan beats a surprise pull request.
+
+## The gate
+
+One command decides whether a change is acceptable:
+
+```sh
+./scripts/verify.sh all
+```
+
+Its last line is `VERIFY: PASS` or `VERIFY: FAIL`. It runs the C test suite,
+the CUDA primitive tests when `nvcc` is present, `ruff` and `pytest` over
+`webui/`, and ESLint over the repository. A pull request whose gate fails is
+not ready, and "it works on my machine" is not an exit code.
+
+The GPU end-to-end render is not in CI — no runner has a GB10 and the
+checkpoint is 465 GB. If your change can affect generation, run one yourself
+and say so in the pull request:
+
+```sh
+./h3 -d ./MiniMax-H3 -p "A bright red cube on a white background." \
+  --width 256 --height 256 --frames 22 --steps 2 -o outputs/smoke.mp4
+```
+
+## Working on the C engine
+
+- Keep the CLI and the public API in `h3.h` backward compatible. New behaviour
+  is an additive flag that changes nothing when it is absent.
+- Prove non-invasiveness where it matters. `--preview-dir` was accepted because
+  the SHA-256 of the generated mp4 is identical with and without the flag.
+- Both backends stay alive: Metal on Apple Silicon, CUDA on Linux. Selection
+  happens at build time in the `Makefile`, never with a runtime branch.
+
+## Working on the web UI
+
+- `webui/shared/options.schema.json` is the single source of truth for the
+  generation options. Add the flag to `main.c`, then to the schema; a test
+  reads `main.c` and fails if the two drift.
+- The frontend's `src/generated/options.ts` is generated by
+  `node scripts/generate-options.mjs`. Never edit it by hand, and commit the
+  regenerated file: CI checks that it is current.
+- Validation messages are copied verbatim from `h3.c`, so the browser and the
+  engine say the same thing.
+- Tests use a stand-in for the `h3` binary: a shell script that prints progress
+  lines and writes a file. No GPU, no checkpoint, no waiting.
+
+## Style
+
+Match the surrounding code. C follows the existing project conventions; Python
+is formatted for `ruff` with the settings in `webui/backend/pyproject.toml`;
+TypeScript follows the ESLint configuration at the repository root. Comments
+explain why, not what.
+
+Keep diffs surgical: a change that also reformats a neighbouring function is
+two changes, and reviewers can only review one of them.
+
+## Licensing
+
+By contributing you agree that your work is released under the MIT license in
+[`LICENSE`](LICENSE). Do not add model weights, checkpoints or download URLs to
+this repository, and do not add dependencies whose license is more restrictive
+than MIT without saying so explicitly in the pull request.