Contributing to Torchtimer

Contributions are welcome: bug fixes, accessibility improvements, UX enhancements, and build tooling changes. This guide covers local setup, conventions, and the PR process.

Local setup

Prerequisites: Deno v2+.

Clone with --recurse-submodules (or run git submodule update --init after cloning) to populate common-web/.

On the submodule: common-web includes web components shared by other reese.biz projects. Torchtimer is self-contained and served at reese.biz/torchtimer/.

Dev server

deno task dev
# open http://localhost:3000

Starts an esbuild dev server at the project root. CSS and HTML changes take effect on refresh. TypeScript changes are bundled on demand with no rebuild step.

Full build

Bundles TypeScript, cache-busts assets, and assembles the staging/ deploy payload:

deno task build

Serve and browse the result:

cd staging
deno run --allow-net --allow-read jsr:@std/http/file-server --port 8000
# open http://localhost:8000

Testing

Unit tests cover the pure-logic modules. Run them with:

deno task test

No flags required; the tested modules don't access the DOM, filesystem, or network.

File	What it covers
`tests/timer.test.ts`	Timer lifecycle: create, light, add time, tick, pause, reset, death; round mode create, advance, add, convert
`tests/sync.test.ts`	`serializeForSync` and `deserializeFromSync` across all four timer states
`tests/share.test.ts`	`buildFragment`, `decodeFragmentToData` encoding/decoding, round-trips
`tests/flame.test.ts`	`flameParams`, `glowParams`, `computeWind`, `computeHeadBg`
`tests/sway.test.ts`	`computeTorchSway`: determinism, amplitude, seed independence, bounds
`tests/noise.test.ts`	`valueNoise` and `fbm`: range, determinism, octave stacking
`tests/smokegl.test.ts`	`buildSmokeInstances`: empty pool, particle layout, instance count
`tests/cracks.test.ts`	`generateCracks`: structure, determinism
`tests/qr.test.ts`	`getQrModules`: module grid dimensions, content variation
`tests/utils.test.ts`	`formatTime`, `nextTorchNumber`, and other pure utility functions

The DOM-manipulating and WebGL setup code in render.ts, dom.ts, torches.ts, overlay.ts, live.ts, viewer.ts, audio.ts, and main.ts requires a browser environment and is not covered.

When to add tests: any new pure function (no DOM, no network, deterministic output) should have unit tests. When fixing a bug in a pure function, add a regression test that would have caught it before adding the fix. Don't write tests for coverage alone; write them to document a real behavior or guard a real failure mode.

Guidelines

No framework. The frontend is plain TypeScript with native ES modules and a thin esbuild bundling step.
No CSS framework. All styles live in css/ and common-web/ using custom properties.
Minimal dependencies. Torchtimer aims for as few dependencies as reasonably possible.
Pure functions, please. Extract pure logic out of modules without DOM dependencies so they can be unit tested. Side-effectful code (rendering, WebGL, event handlers) is expected to be manually tested.
Module structure. src/main.ts is the entry point (wiring + boot only). Logic lives in:
- src/timer.ts: immutable timer state machine (unlit/running/paused/dead) for both time-based and round-based modes
- src/sync.ts: live-sync serialization/deserialization
- src/share.ts: URL fragment encoding and decoding
- src/types.ts: shared TypeScript types and interfaces
- src/state.ts: global application state singletons and shared constants
- src/utils.ts: pure math, color, and formatting utilities
- src/noise.ts: 2D value noise and fractal Brownian motion
- src/flame.ts: particle system parameter computation for flame, smoke, and sparks
- src/sway.ts: per-torch body sway computation
- src/glow.ts: canvas and DOM glow effects for lit torches
- src/cracks.ts: procedural glowing crack lines and specks on the torch head
- src/audio.ts: procedural per-torch audio (flame and popping sounds)
- src/render.ts: per-frame render loop
- src/dom.ts: DOM manipulation for torch elements
- src/torches.ts: torch lifecycle and interaction
- src/duration.ts: Pass Time/Rounds, Add Time/Rounds, custom duration modal, and mode toggle logic
- src/live.ts: Torchbearer live-hosting UI and session management
- src/viewer.ts: viewer mode entry, exit, and poll-driven state application
- src/overlay.ts: canvas overlay initialisation and resize handling
- src/smokegl.ts: WebGL2 instanced smoke particle renderer
Build script is build-time only. build.ts handles bundling and cache-busting. No runtime logic belongs there.

Deployment

Deployment happens from the reese.biz repository: a Forgejo Actions workflow there builds this app and publishes it under reese.biz/torchtimer/ via Codeberg Pages, alongside the rest of the site.

PRs to main run tests automatically via .forgejo/workflows/test.yml.

The live sync backend, torchtimer-service, is a Cloudflare Worker deployed separately using Wrangler.

Filing issues

Open an issue in this repository for bugs, accessibility problems, or feature requests.

Pull requests

Fork the repository and create a branch.
Make your changes. Test locally using the dev workflow above.
Open a PR against main with a clear description of what changed and why.
CI runs tests automatically. A failing test run blocks merge.

Keep PRs focused. A bug fix and an unrelated refactor are two separate PRs. If you're unsure whether a larger change is the right direction, open an issue to discuss first.