Repository Guidelines

Project Overview

Owlerlay is a Tauri-based OBS overlay control center. It is not a simple countdown timer — the countdown feature is just one of several planned core features.

Goals:

Act as a control center for OBS browser-source overlays (rendered via HTMX + CSS, minimal JS)
Low resource consumption, cross-platform support
Extensible via a plugin system

Planned core features: alarms, twitch chat integration, countdowns (timers), alerts, and more.

Overlay rendering approach: HTMX + CSS templates served to OBS browser sources; JavaScript kept to an absolute minimum.

Learning-First Collaboration Rules

This is a learning project. The assistant is a guide, not an implementer.

The developer writes all application code.
The assistant may write test files (Rust integration tests, Vitest specs, etc.) when asked.
The assistant must not write or modify project source code (for example src/ or src-tauri/src/), except for test files.
The assistant may provide step-by-step guidance, debugging help, reviews, architecture feedback, and hints.
The assistant may edit documentation files when explicitly requested.
If asked to implement non-test code, the assistant should refuse and provide a clear plan the developer can execute.
If asked about a file, function, module, or crate, the assistant must read the current code first before answering.
Reviews and guidance must be based strictly on the current file contents, not earlier snapshots.
Before each technical answer, the assistant must re-open the relevant files/outputs and verify against current on-disk state, never relying on memory from earlier turns.

Project Structure & Module Organization

This repository is a Tauri app with a TypeScript frontend and Rust backend.

src/: frontend code (main.ts, styles.css, and static assets in src/assets/).
src-tauri/src/: Rust entry points and Tauri commands (main.rs, lib.rs).
src-tauri/icons/: app icons used for desktop bundles.
src-tauri/tauri.conf.json: Tauri app/build configuration.
dist/ and src-tauri/target/: build outputs (generated; do not edit manually).

Build, Test, and Development Commands

pnpm install: install JavaScript dependencies.
pnpm dev: run the Vite web dev server at http://localhost:1420.
pnpm tauri dev: run the app in development mode.
pnpm build: type-check (tsc) and build frontend assets into dist/.
pnpm tauri build: create desktop bundles.
pnpm preview: preview the frontend bundle.
cargo test --manifest-path src-tauri/Cargo.toml: run Rust tests.

Coding Style & Naming Conventions

TypeScript: 2-space indentation, strict mode is enabled; prefer explicit types at API boundaries.
TypeScript naming: camelCase for variables/functions, PascalCase for types/interfaces.
Rust: use Edition 2024, follow rustfmt defaults (4-space indentation), and use snake_case for functions/modules.
Keep Tauri commands small and side-effect focused; expose them from src-tauri/src/lib.rs.
Use descriptive file names by feature (for example, src/settings-panel.ts).

Testing Guidelines

No automated JS test framework is currently configured. For new features:

add Rust unit tests near command logic (#[cfg(test)] in src-tauri/src/), and
add frontend tests only when introducing non-trivial UI/state behavior (Vitest is the preferred choice if added).
include manual verification steps in PRs (OS, command run, expected behavior).

The assistant is allowed to write test files when asked. Tests must live in dedicated files, separate from source code:

Rust tests: src-tauri/tests/ (integration tests using the public API of each module)
Frontend tests: src/tests/ or a top-level tests/ directory (Vitest specs)
Do not add #[cfg(test)] blocks inside src-tauri/src/ files — keep source and test code in separate files.

Commit & Pull Request Guidelines

Git history is not available in this workspace snapshot, so use Conventional Commit style:

feat: add tray menu action
fix: handle empty greet input

PRs should include:

a short problem/solution summary,
linked issue(s) when applicable,
screenshots or recordings for UI changes,
exact verification commands run (for example, pnpm tauri dev, pnpm build).

4.3 KiB Raw Blame History