### Setup and build commands Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Clone the repository, install frontend dependencies with pnpm, start the development server (launches Tauri + Vite), and build for production. ```bash # Clone the repository git clone https://github.com/AnInsomniacy/rayburst.git cd rayburst # Install frontend dependencies pnpm install # Start development server (launches Tauri + Vite) pnpm tauri dev # Build for production pnpm tauri build ``` -------------------------------- ### Install dependencies and run development server Source: https://github.com/aninsomniacy/rayburst/blob/main/website/README.md Install dependencies with pnpm, then start the development server at http://localhost:5173. Use pnpm build for type checking and production build into dist/, and pnpm preview to serve the built output. ```bash pnpm install pnpm dev # http://localhost:5173 pnpm build # type check + production build into dist/ pnpm preview # serve dist/ ``` -------------------------------- ### Install dependencies and prepare environment Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/media/film/README.md Run from docs/media/film. Installs pnpm dependencies, runs the setup script (installs Chromium and downloads Noto fonts), creates a Python virtual environment, and installs the audio requirements. Requires Node.js 20+, Python 3.10+, and a system FFmpeg (or set FFMPEG to its path). ```sh pnpm install --frozen-lockfile pnpm run setup python3 -m venv .venv .venv/bin/python -m pip install -r audio/requirements.txt ``` -------------------------------- ### Clone and run dev server Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Clones the repository, installs dependencies with pnpm, and starts the Tauri + Vite dev server. Development mode does not register Native Messaging hosts or change URL protocol associations, so start the desktop manually when testing the extension API. ```bash git clone https://github.com/AnInsomniacy/rayburst.git cd rayrburst pnpm install pnpm tauri dev # Start dev server (Tauri + Vite) ``` -------------------------------- ### Install Debian/Ubuntu .deb package Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Install the Rayburst .deb package on Debian or Ubuntu using dpkg. Replace x.x.x with the actual version. ```bash sudo dpkg -i Rayburst_x.x.x_amd64.deb ``` -------------------------------- ### AI-Assisted-By commit trailer example Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Optional commit trailer for AI-assisted development, following the OpenInfra Foundation standard. Include the exact model name in the trailer. ```text feat: add speed limit control AI-Assisted-By: Claude ``` -------------------------------- ### GET /downloads/capabilities Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/DOWNLOADS.md Retrieves the product name and protocol version. Clients check this before each handoff to ensure compatibility. ```APIDOC ## [GET] /downloads/capabilities ### Description Retrieves the product name and protocol version. Clients check this before each handoff to ensure compatibility. ### Method GET ### Endpoint /downloads/capabilities ### Response #### Success Response (200) - **product** (string) - The product name. - **protocolVersion** (integer) - The protocol version. #### Response Example ```json { "product": "rayburst", "protocolVersion": 3 } ``` ``` -------------------------------- ### Install Fedora/RHEL .rpm package Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Install the Rayburst .rpm package on Fedora or RHEL using rpm. Replace x.x.x with the actual version. ```bash sudo rpm -i Rayburst-x.x.x-1.x86_64.rpm ``` -------------------------------- ### Install Rayburst via Flatpak from FlatPark Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Add the FlatPark repository and install the Rayburst Flatpak package. The in-app updater cannot update this package; use flatpak update instead. ```bash flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo flatpak install flatpark dev.aninsomniacy.rayburst ``` -------------------------------- ### Conventional Commits examples Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Commit messages must follow the Conventional Commits specification. Examples cover feat, fix, refactor, test, and docs types. ```text feat: add torrent file selection fix: handle empty bitfield in peer parser refactor: extract TorrentUpload sub-component test: add rename utility tests docs: update CONTRIBUTING guidelines ``` -------------------------------- ### PR title examples following Conventional Commits Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Pull request titles must follow the Conventional Commits format. Examples include scope and type variations. ```text feat(macos): add native traffic light toggle fix: handle null errorCode in task notification refactor: extract tracker sync into composable docs: update i18n translation guide ``` -------------------------------- ### Verify UI strings sync Source: https://github.com/aninsomniacy/rayburst/blob/main/website/README.md Run the maintenance script to refresh interface strings from the apps' locales. Use --check to verify without making changes. ```bash python3 tools/sync-ui-strings.py --check ``` -------------------------------- ### Project directory layout Source: https://github.com/aninsomniacy/rayburst/blob/main/website/README.md Shows the source tree structure: entry files, src/ directories for main app, i18n, motion, art, sim, composables, components, styles, and data, plus tools/ for maintenance scripts. ```text index.html, 404.html entries (theme is set before first paint) src/ main.ts, App.vue the page; not-found.ts, NotFound.vue for 404 i18n.ts locale detection, lazy loading, right-to-left locales/*.json 27 languages motion/ GSAP setup, the scene clock, canvas sizing, directives art/ the promo artwork's ripples, aria and palettes, drawn live sim/ the demo tasks as pure functions of time composables/ theme, language, GitHub releases and statistics components/ one folder per section; mock/ rebuilds the app window; art/ holds the mark's ring and the section backdrops styles/ tokens, base, shared controls, the window mock data/schemes.ts the ten color schemes, generated like colorScheme.ts tools/ maintenance scripts ``` -------------------------------- ### GET /tasks Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/DOWNLOADS.md Lists unfinished tasks in queue order and the ten latest finished ones with global statistics. Serves the extension popup. ```APIDOC ## [GET] /tasks ### Description Lists unfinished tasks in queue order and the ten latest finished ones with global statistics. Serves the extension popup. ### Method GET ### Endpoint /tasks ### Response #### Success Response (200) - **unfinished** (array) - Unfinished tasks in queue order. - **finished** (array) - The ten latest finished tasks. - **statistics** (object) - Global statistics. ``` -------------------------------- ### Required checks before pushing Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Run these checks before pushing. Required CI must pass. Includes linting, formatting, type checking, tests, build, and Rust checks. ```bash pnpm lint pnpm format:check npx vue-tsc --noEmit pnpm test npx vite build cd src-tauri && cargo fmt --all -- --check cd src-tauri && cargo clippy --workspace --all-targets -- -D warnings cd src-tauri && cargo test --workspace --all-targets ``` -------------------------------- ### Rust backend standalone checks Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Builds the native launcher and runs cargo check and tests for the Rust workspace. Use this when working on the Rust backend independently. ```bash pnpm build:native-launcher cd src-tauri cargo check --workspace --all-targets cargo test --workspace --all-targets ``` -------------------------------- ### Run all code quality checks Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/CONTRIBUTING.md Runs the full set of CI checks locally: linting, formatting, tests, repo structure validation, build, and Rust checks. Pre-commit hooks auto-run eslint --fix and prettier --write on staged files. ```bash pnpm lint # ESLint pnpm format:check # Prettier formatting pnpm test # Vitest pnpm check:repo # Locale structure and placeholders pnpm build # TypeScript check and frontend bundle cd src-tauri && cargo fmt --all -- --check # Rust formatting cd src-tauri && cargo clippy --workspace --all-targets -- -D warnings cd src-tauri && cargo test --workspace --all-targets ``` -------------------------------- ### Run Rayburst AppImage Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Make the AppImage executable and run it on other Linux distributions. Replace x.x.x with the actual version. ```bash chmod +x Rayburst_x.x.x_amd64.AppImage ./Rayburst_x.x.x_amd64.AppImage ``` -------------------------------- ### Bump version for stable or beta release Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Run before releasing. Updates Cargo.toml and package.json. Do not modify code after this step. ```bash # Stable ./scripts/bump-version.sh 1.4.0 # Beta ./scripts/bump-version.sh 1.4.0-beta.1 ``` -------------------------------- ### Release script Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Formats code, commits all changes, creates annotated tag v{VERSION}, and pushes to origin. Outputs color-coded channel indicator (yellow = pre-release, green = stable). ```bash ./scripts/release.sh ``` -------------------------------- ### Version Bump Command Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Use this script when bumping the version. Replace `` with the target version string. ```bash ./scripts/bump-version.sh ``` -------------------------------- ### Backend Verification Commands Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Run these checks for backend changes. `pnpm build:native-launcher` builds the target-specific Native Messaging sidecar. `cargo check` and `cargo test` operate on the workspace with all targets. ```bash pnpm build:native-launcher # Build the target-specific Native Messaging sidecar cargo check --workspace --all-targets # Fast compilation check cargo test --workspace --all-targets # Rust unit tests ``` -------------------------------- ### POST /add Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/DOWNLOADS.md Adds a download to the engine. The browser keeps holding the download until the answer decides who owns it. ```APIDOC ## [POST] /add ### Description Adds a download to the engine. The browser keeps holding the download until the answer decides who owns it. ### Method POST ### Endpoint /add ### Parameters #### Request Body - **url** (string) - Required - The download URL. - **filename** (string) - Optional - The suggested filename. - **filenameSource** (string) - Optional - Either `browser` or `suggested` (default `suggested`). - **requestHeaders** (array) - Optional - Array of `{name,value}` pairs. - **verify** (boolean) - Optional - Whether to verify the download. - **mime** (string) - Optional - The MIME type. - **size** (integer) - Optional - The size in bytes. - **finalUrl** (string) - Optional - The final URL. - **referer** (string) - Optional - The referer. - **cookie** (string) - Optional - The cookie. - **userAgent** (string) - Optional - The user agent. - **ack** (string) - Optional - Either `final` (default) or `early`. ### Response #### Success Response (200) - **action** (string) - One of `added`, `accepted`, `cancelled`, or `fallback`. - **gid** (string) - Present when action is `added`. - **reason** (string) - Present when action is `fallback`. #### Request Example ```json { "url": "https://example.com/download", "filename": "report%20.pdf", "filenameSource": "browser", "requestHeaders": [], "verify": true, "mime": "application/pdf", "size": 1048576 } ``` #### Response Example ```json { "action": "added", "gid": "…" } ``` ``` -------------------------------- ### List of 27 Locale Directories Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md The 27 locale directories used in the project. English (en-US) is the schema and fallback. ```text ar bg ca de el en-US es fa fr hi hu id it ja ko nb nl pl pt-BR ro ru th tr uk vi zh-CN zh-TW ``` -------------------------------- ### Verify Tauri updater signature with minisign Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Decode the base64 public key from tauri.conf.json and verify a release .sig file. Replace Rayburst_x.x.x_ with the actual release file. Expected output: 'Signature and comment signature verified' or 'Signature verification failed' if the artifact was changed. ```bash python3 -c 'import base64,sys; sys.stdout.write(base64.b64decode(sys.stdin.read()).decode())' \ < Rayburst_x.x.x_.sig \ > Rayburst_x.x.x_.minisig minisign -V \ -m Rayburst_x.x.x_ \ -x Rayburst_x.x.x_.minisig \ -p rayburst.pub ``` -------------------------------- ### Recover from failed release Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Steps to fix code, delete remote and local tags, delete failed GitHub Release, re-run bump-version.sh, and re-create Release. ```bash # 1. Fix the code, commit and push git add -A && git commit -m "fix: resolve build issue" && git push # 2. Delete the remote tag git push origin --delete v2.1.1 # 3. Delete the local tag git tag -d v2.1.1 # 4. Delete the failed Release on GitHub (Releases → click → Delete this release) # 5. Re-run bump-version.sh with the same version to re-create the tag ./scripts/bump-version.sh 2.1.1 git push && git push --tags # 6. Re-create the Release in the GitHub UI selecting the tag ``` -------------------------------- ### Bump version with ./scripts/bump-version.sh Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Use this script to atomically update both Cargo.toml and package.json. Never manually edit version strings. ```bash ./scripts/bump-version.sh 1.4.0 ``` -------------------------------- ### Run WebKit repaint probe with software rendering Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/LINUX.md Runs the native regression probe from scripts/diagnostics/webkit-transparent-repaint.c with Rayburst's default environment. The environment variables force CPU rendering and shared memory; leave out the last two variables to test the GPU path. Optionally run under xvfb-run -a for an isolated display. ```bash WEBKIT_FORCE_DMABUF_RENDERER=1 WEBKIT_DMABUF_RENDERER_FORCE_SHM=1 WEBKIT_SKIA_ENABLE_CPU_RENDERING=1 LIBGL_ALWAYS_SOFTWARE=1 /tmp/rayburst-webkit-repaint ``` -------------------------------- ### Project structure tree Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Directory layout of the Rayburst project, showing frontend (Vue 3 + TypeScript) and backend (Rust + Tauri 2) components. ```text rayburst/ ├── src/ # Frontend (Vue 3 + TypeScript) │ ├── api/ # aria2-compatible JSON-RPC client │ ├── components/ # Vue components │ │ ├── about/ # About panel │ │ ├── common/ # Shared UI primitives │ │ ├── layout/ # Sidebar, speedometer, navigation │ │ ├── preference/ # Settings pages, update dialog │ │ └── task/ # Task list, detail, add task │ ├── composables/ # Reusable composition functions │ ├── router/ # Vue Router configuration │ ├── shared/ # Shared utilities & config │ │ ├── locales/ # 27 language packs │ │ ├── utils/ # Pure utility functions (with tests) │ │ ├── types.ts # TypeScript interfaces │ │ ├── constants.ts # App constants & defaults │ │ └── configKeys.ts # Persisted config key registry │ ├── stores/ # Pinia state management (with tests) │ ├── styles/ # Global CSS custom properties │ └── views/ # Page-level route views ├── src-tauri/ # Backend (Rust + Tauri 2) │ ├── src/ │ │ ├── aria2/ # Native Rust aria2 JSON-RPC client │ │ ├── commands/ # Tauri invoke handlers (config, engine, fs, etc.) │ │ ├── database/ # SQLite owner: history, credentials, receipts │ │ ├── engine/ # Aria2 Next sidecar lifecycle, runtime config, state, cleanup │ │ ├── services/ # Runtime services (stat, speed, monitor, HTTP API, deep links) │ │ ├── error.rs # AppError enum │ │ ├── menu.rs # Native menu builder │ │ ├── tray.rs # System tray setup │ │ ├── upnp.rs # UPnP/IGD port mapping │ │ ├── webkit.rs # Linux WebKitGTK rendering setup │ │ └── lib.rs # Tauri builder & plugin registration │ ├── native-messaging/ # Browser Native Messaging launcher │ └── binaries/ # Aria2 Next sidecar binaries (6 platforms) ├── scripts/ # bump-version.sh, release.sh ├── .github/workflows/ # CI (ci.yml) + Release (release.yml) └── website/ # Website (Vue 3, TypeScript, Vite, GSAP) ``` -------------------------------- ### Frontend Verification Commands Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Run these checks for frontend changes. `pnpm format:check` must pass for every commit; `pnpm format` auto-formats source files. `pnpm check:repo` checks locale parity and i18n literal-key usage. `npx vue-tsc --noEmit` performs TypeScript type checking. ```bash pnpm format # Auto-format all source files with Prettier pnpm lint # ESLint check pnpm format:check # Verify formatting (CI runs this) pnpm test # Vitest unit tests pnpm check:repo # Locale parity + i18n literal-key usage (CI runs this) npx vue-tsc --noEmit # TypeScript type checking ``` -------------------------------- ### Expected output of minisign verification Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md The expected output when the signature is valid. ```text Signature and comment signature verified ``` -------------------------------- ### Python Batch Script to Update Locale Files Source: https://github.com/aninsomniacy/rayburst/blob/main/AGENTS.md Batch-update locale files with native translations. Reads each locale's messages.json, sets a new key under preferences, and writes back with UTF-8 encoding and indentation. After running, verify with pnpm lint, pnpm check:repo, npx vue-tsc --noEmit, and npx vite build. ```python #!/usr/bin/env python3 """Batch-update locale files with native translations.""" import json from pathlib import Path LOCALES_DIR = Path("src/shared/locales") TRANSLATIONS = { "ar": ("Arabic text",), "bg": ("Bulgarian text",), # ... all 27 locales with native translations ... "en-US": ("English text",), "zh-CN": ("Chinese Simplified text",), "zh-TW": ("Chinese Traditional text",), } def update_locale(locale_dir, values): filepath = LOCALES_DIR / locale_dir / "messages.json" messages = json.loads(filepath.read_text(encoding="utf-8")) messages["preferences"]["new-key"] = values[0] filepath.write_text(json.dumps(messages, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") for locale, vals in sorted(TRANSLATIONS.items()): update_locale(locale, vals) ``` -------------------------------- ### POST /tasks/{gid}/pause Source: https://github.com/aninsomniacy/rayburst/blob/main/docs/DOWNLOADS.md Pauses a specific task. Controls one task from the extension popup. ```APIDOC ## [POST] /tasks/{gid}/pause ### Description Pauses a specific task. Controls one task from the extension popup. ### Method POST ### Endpoint /tasks/{gid}/pause ### Parameters #### Path Parameters - **gid** (string) - Required - The task identifier. ``` -------------------------------- ### Output when artifact was changed Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md The output when the artifact was modified, indicating verification failure. ```text Signature verification failed ``` -------------------------------- ### Remove macOS quarantine attribute from Rayburst.app Source: https://github.com/aninsomniacy/rayburst/blob/main/README.md Run this command in Terminal when macOS reports the app is 'damaged and can't be opened'. It removes only the Gatekeeper quarantine attribute and must be run again after each upgrade. ```bash xattr -dr com.apple.quarantine /Applications/Rayburst.app ```