Repository Guidelines

Project Structure & Module Organization

This is a ClojureScript single-page app built with Shadow CLJS, Reagent, and re-frame. Application source lives in src/tl/; core namespaces include core.cljs for startup, db.cljs for default app state, events.cljs and subs.cljs for re-frame wiring, and views.cljs for UI. Static files are served from resources/public/, including index.html, CSS in resources/public/css/, icons, OTIO data, and local media assets. Development helpers live in dev/, including dev.sh, media_server.py, and user.cljs. Generated output goes to resources/public/js/compiled/, target/, and .shadow-cljs/; do not edit or commit generated files.

Build, Test, and Development Commands

npm install: install JavaScript tooling and React dependencies.
npm run dev: run the project development script in dev/dev.sh.
npm run watch: start shadow-cljs watch app with hot reload; open http://localhost:8280/.
npm run media: start the Python media server from dev/media_server.py.
npm run release: produce an optimized app build in resources/public/js/compiled/.
npm run build-report: generate target/build-report.html for bundle inspection.
npm run ancient: check Clojure dependency freshness via antq.

Coding Style & Naming Conventions

Use idiomatic ClojureScript formatting with two-space indentation and aligned maps where useful. Namespace files should match tl.<name> and use kebab-case for functions, events, subscriptions, and local vars. Prefer qualified re-frame event keywords such as ::initialize-db and keep side effects in registered effects or reg-event-fx handlers. Keep comments short and focused on non-obvious behavior.

Testing Guidelines

shadow-cljs.edn includes test in :source-paths, but this repository currently has no committed test suite or npm test script. Add tests under test/tl/ using matching namespace names such as tl.otio-test. When adding test support, include a runnable npm script and document the command here. Until then, verify changes with npm run watch for interactive behavior and npm run release before merging.

Commit & Pull Request Guidelines

Recent commits use short, imperative messages with optional conventional prefixes, for example feat: prev/next frame buttons flanking play and fix: video won't seek. Prefer feat:, fix:, or another clear scope when applicable. Pull requests should describe the user-visible change, note verification commands run, link related issues, and include screenshots or short screen recordings for UI changes.

Security & Configuration Tips

Do not commit large local media, compiled assets, logs, cache directories, or secrets. Keep runtime data in resources/public/ only when it is safe to serve directly to the browser.

2.8 KiB Raw Blame History