docs: add JOSS paper and v0.6.1 plan

Author: InfantLab

CITATION.cff

@@ -3,7 +3,10 @@ message: "If you use this software, please cite it as below."
 authors:
 - family-names: Addyman
   given-names: Caspar
-orcid: https://orcid.org/0000-0003-0001-9548
-title:InfantLab/video-annotation-viewer: v0.3.0: VideoAnnotator runner & viewer web app
-version: v0.3.0
-date-released: 2025-08-26
+  orcid: https://orcid.org/0000-0003-0001-9548
+title: "Video Annotation Viewer"
+version: 0.6.0
+date-released: 2025-12-15
+repository-code: "https://github.com/InfantLab/video-annotation-viewer"
+url: "https://github.com/InfantLab/video-annotation-viewer"
+license: MIT

README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <img src="public/icon-64x64.png" alt="Video Annotation Viewer Icon" width="64" height="64">
-  <h1>Video Annotation Viewer v0.4.0</h1>
+  <h1>Video Annotation Viewer v0.6.0</h1>
 </div>
 
 [![TypeScript 5](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
@@ -21,6 +21,10 @@
 
 Advanced multimodal video annotation analysis tool for both **reviewing VideoAnnotator pipeline outputs** and **creating new annotation jobs**. Features synchronized pose detection, speech recognition, speaker diarization, and scene detection visualization with integrated job management.
 
+JOSS submission prep (targeting v0.6.1) lives in:
+- `paper/paper.md`
+- `docs/development/ROADMAP_v0.6.1.md`
+
 > Companion processing pipeline: [VideoAnnotator](https://github.com/InfantLab/VideoAnnotator)
 
 ## Overview

docs/JOSS_BUILD.md

@@ -0,0 +1,30 @@
+# Building the JOSS paper locally
+
+JOSS papers are compiled with the Open Journals toolchain (Pandoc via `openjournals/inara`).
+
+## Expected files
+
+- `paper/paper.md`
+- `paper/paper.bib`
+
+## Option A: Docker (recommended)
+
+From the repository root:
+
+```bash
+docker run --rm \
+  --volume $PWD/paper:/data \
+  --env JOURNAL=joss \
+  openjournals/inara
+```
+
+On success, `paper/paper.pdf` will be created next to `paper/paper.md`.
+
+## Option B: GitHub Action
+
+Open Journals provides a GitHub Action for PDF generation. If we add it later, the output PDF will appear as a workflow artifact in the Actions tab.
+
+## Notes
+
+- If you are on Windows PowerShell, `$PWD` is still supported, but Docker volume path handling may differ depending on your Docker installation.
+- The compilation step is sensitive to YAML metadata formatting and missing citations; if compilation fails, check the frontmatter in `paper/paper.md` and the citekeys in `paper/paper.bib`.

docs/development/ROADMAP_v0.6.0.md

@@ -1,4 +1,7 @@
-# Video Annotation Viewer v0.6.0 Roadmap
+# Video Annotation Viewer v0.6.0 Roadmap (Superseded)
+
+> This roadmap has been superseded by [ROADMAP_v0.6.1.md](./ROADMAP_v0.6.1.md).
+> v0.6.0 was released in December 2025; the active JOSS release implementation plan is v0.6.1.
 
 **Theme:** JOSS Paper & Public Release  
 **Status:** 📋 PLANNED  

docs/development/ROADMAP_v0.6.1.md

@@ -0,0 +1,196 @@
+# Video Annotation Viewer v0.6.1 Roadmap (JOSS Submission Release)
+
+**Theme:** JOSS Paper + Release Readiness (No New Features)
+
+**Status:** 📋 PLANNED
+
+**Target Window:** As soon as VideoAnnotator **v1.4.2** is tagged/released (Dec 2025–Jan 2026)
+
+**Previous Version:** v0.6.0 (Job Results Viewer + Artifacts ZIP support — 2025-12-15)
+
+---
+
+## 🎯 Overview
+
+v0.6.1 is a **documentation + release process** release to support a **JOSS submission** for Video Annotation Viewer (vav), coordinated with the VideoAnnotator server **v1.4.2** release.
+
+This roadmap is a **full implementation plan**: it lists concrete deliverables, owners, acceptance criteria, and the release steps required to submit to JOSS.
+
+### Scope constraints (non-negotiable)
+
+- **No new user-facing features** unless they are required to make existing claims verifiable for reviewers.
+- **CI improvements only**: improve stability/“scores” of existing CI checks; do not add new mandatory quality gates.
+- **Server coordination first**: we will not cut v0.6.1 until the server’s v1.4.2 tag/contract is available.
+
+---
+
+## ✅ Current State (Dec 19, 2025)
+
+- App is already at **v0.6.0** (see `package.json` + `CHANGELOG.md`).
+- Lint/typecheck are currently clean (`npm run lint:strict`, `npx tsc --noEmit`).
+- JOSS draft exists at `docs/joss.md`, but **JOSS submission requires `paper.md` + bibliography** and the draft currently:
+  - references `paper.bib` that does not exist
+  - contains a stray `:contentReference[...]` token that likely breaks compilation
+
+---
+
+## 📦 Workstreams
+
+### 1) JOSS paper & submission artifacts 📄 (Owner: Docs)
+
+**Goal:** Have a paper that compiles in the Open Journals toolchain and a repository that satisfies the JOSS reviewer checklist.
+
+#### 1.1 Paper files (blocking)
+- [ ] Create `paper/` folder
+- [ ] Move/rename `docs/joss.md` → `paper/paper.md`
+- [ ] Create `paper/paper.bib`
+- [ ] Remove compilation-breaking tokens (e.g., `:contentReference[...]`)
+- [ ] Replace placeholder references with real citations and in-text citekeys (e.g., `[@key]`)
+- [ ] Validate paper length stays within JOSS guidance (250–1000 words)
+- [ ] Document and run the local paper compilation step (see `docs/JOSS_BUILD.md`)
+
+**Acceptance criteria:** `paper/paper.md` + `paper/paper.bib` compile successfully via the local JOSS build procedure in `docs/JOSS_BUILD.md`.
+
+#### 1.2 Repo metadata (blocking)
+- [ ] Update `CITATION.cff` (version, release date, title, author ORCIDs if available)
+- [ ] Ensure `LICENSE` is present and OSI-approved (already present; verify no contradictions)
+- [ ] Ensure `README.md` reflects current version and reviewer-facing quickstart (see Workstream 2)
+
+**Acceptance criteria:** JOSS reviewer can find how to cite, how to install/run, and what the software does within 5 minutes.
+
+#### 1.3 JOSS submission checklist mapping
+Add a short checklist mapping in this repo (either in this roadmap or a dedicated `docs/JOSS_CHECKLIST.md`) covering:
+- [ ] Paper present (`paper/paper.md`, `paper/paper.bib`)
+- [ ] License present (`LICENSE`)
+- [ ] Citation metadata present (`CITATION.cff`)
+- [ ] Installation instructions present (README)
+- [ ] Tests runnable locally (README + `docs/TESTING_GUIDE.md`)
+- [ ] Archive DOI minted for the tagged release (Zenodo)
+
+---
+
+### 2) Documentation: “Reviewer journey” 📚 (Owner: Docs + Client)
+
+**Goal:** A reviewer can clone, run, and verify core claims quickly.
+
+- [ ] Update `README.md` header/version references (currently stale)
+- [ ] Add a short **Local Run** section:
+  - install deps
+  - run dev server
+  - open the app
+- [ ] Add a short **Connect to VideoAnnotator** section:
+  - required env vars (`VITE_API_BASE_URL`, `VITE_API_TOKEN`) and localStorage fallbacks
+  - expected default server URL
+- [ ] Update `docs/CLIENT_SERVER_COLLABORATION_GUIDE.md` to the v1.4.2 contract (endpoints, auth, artifacts)
+- [ ] Update `docs/TESTING_GUIDE.md` to current scripts and CI expectations
+
+**Acceptance criteria:** Following docs, a reviewer can (a) run the UI locally, and (b) either load demo artifacts or connect to a running v1.4.2 server.
+
+---
+
+### 3) CI health (“scores”) ✅ (Owner: Client)
+
+**Goal:** Improve reliability of existing CI checks without changing which checks are required.
+
+Current CI behavior (reference):
+- Required: lint + unit tests
+- Optional (non-blocking): coverage, e2e, lighthouse
+
+Planned improvements:
+- [ ] Reduce flakiness in existing Playwright smoke tests (no new tests required)
+- [ ] Stabilize Lighthouse CI runs (reduce transient failures)
+- [ ] Document a simple “CI score” metric (e.g., % green over last N runs)
+
+**Acceptance criteria (CI score):** Over the **last 10 runs on `main`**, optional jobs (`e2e`, `lighthouse`, `coverage`) are green in **≥80%** of runs, with failures triaged and documented.
+
+---
+
+### 4) Server-team coordination (VideoAnnotator v1.4.2) 🔁 (Owner: Server + Client)
+
+This section is intended to be shareable with the VideoAnnotator server team.
+
+**Blocking asks for the server team:**
+- [ ] Publish/tag **VideoAnnotator v1.4.2** (or confirm final tag name/date)
+- [ ] Provide a versioned **OpenAPI spec** for that tag (or confirm where to fetch it)
+- [ ] Confirm artifacts/results bundle expectations:
+  - ZIP includes source video
+  - stable directory structure and filenames (or document variability)
+  - stable metadata keys for pipeline ID, parameters, and versions
+- [ ] Confirm auth + CORS expectations for local reviewer runs (token format, headers, allowed origins)
+
+**Client-side follow-ups (once server tag exists):**
+- [ ] Validate the viewer against v1.4.2 (manual smoke + documented steps)
+- [ ] Update any pinned OpenAPI snapshots and compatibility notes
+
+**Acceptance criteria:** We can state a clear compatibility line in release notes: “v0.6.1 supports VideoAnnotator v1.4.2”.
+
+---
+
+## 📋 Development Phases
+
+### Phase 1: Paper packaging + server contract (Week 1)
+- [ ] Create `paper/` structure and bibliography
+- [ ] Remove paper compilation blockers
+- [ ] Draft server coordination asks and confirm v1.4.2 tag timeline
+
+**Milestone:** Paper compiles locally; server tag plan confirmed.
+
+### Phase 2: Documentation refresh + CI stabilization (Weeks 2–3)
+- [ ] Refresh README + key docs for reviewer journey
+- [ ] Improve CI score for optional jobs (stability only)
+
+**Milestone:** Docs are reviewer-ready; CI optional jobs mostly green.
+
+### Phase 3: Release + archive + submit (Week 4)
+- [ ] Bump version to v0.6.1 + update changelog
+- [ ] Tag release + GitHub release notes
+- [ ] Archive tagged release via Zenodo and obtain archive DOI
+- [ ] Submit to JOSS and start review
+
+**Milestone:** v0.6.1 is tagged and archived; JOSS submission created.
+
+---
+
+## 🎯 Success Criteria
+
+### Must-have (blocking v0.6.1 release)
+- [ ] `paper/paper.md` + `paper/paper.bib` compile successfully
+- [ ] `README.md` provides a reviewer-friendly run path
+- [ ] `CITATION.cff` is accurate for v0.6.1
+- [ ] VideoAnnotator server **v1.4.2** is tagged/released and compatibility statement is documented
+
+### Must-have (blocking JOSS submission)
+- [ ] v0.6.1 is tagged and archived (Zenodo DOI)
+- [ ] Paper references the archived DOI (once available)
+
+### CI score goals (non-blocking but tracked)
+- [ ] Optional CI jobs are green ≥80% over last 10 runs on `main`
+
+---
+
+## 🚫 Out of scope
+
+- New viewer features
+- Major UI redesigns
+- New mandatory test gates
+- Major performance/architecture work
+- Full accessibility compliance (track separately)
+
+---
+
+## 🔧 Release checklist (operator steps)
+
+- [ ] Update version to `0.6.1` and add release notes to `CHANGELOG.md`
+- [ ] Run locally: `npm run lint:strict`, `npx tsc --noEmit`, `npm run test:run`
+- [ ] Build: `npm run build`
+- [ ] Tag `v0.6.1` and create GitHub release
+- [ ] Confirm Zenodo archive DOI minted from the `v0.6.1` tag
+- [ ] Submit to JOSS (repository URL, tagged release URL, archive DOI, paper)
+
+---
+
+**Document Version:** 1.0
+
+**Created:** 2025-12-19
+
+**Status:** 📋 Planning — JOSS submission prep for v0.6.1

docs/joss.md

@@ -1,68 +1,8 @@
----
-title: "Video Annotation Viewer: an interactive web application for exploring, comparing, and auditing behavioral video annotations"
-tags:
-  - visualization
-  - web application
-  - scientific tooling
-  - behavioral science
-  - reproducibility
-authors:
-  - name: Caspar Addyman
-    orcid: 0000-0000-0000-0000
-    affiliation: 1
-  - name: Irene Uwerikowe
-    affiliation: 1
-  - name: Jeremiah (Jerry) Ishaya
-    affiliation: 1
-  - name: Daniel Stamate
-    affiliation: 2
-  - name: Mark Tomlinson
-    affiliation: 1
-affiliations:
-  - name: Institute for Life Course Health Research, Department of Global Health, Stellenbosch University, South Africa
-    index: 1
-  - name: Department of Computing, Goldsmiths, University of London, United Kingdom
-    index: 2
-date: 27 August 2025
-bibliography: paper.bib
----
+# JOSS paper draft (moved)
 
-# Summary
+The canonical JOSS submission files are now located at:
 
-**Video Annotation Viewer** is a lightweight web application for *visualizing, filtering, and comparing* annotations overlaid on video. It targets lab workflows where researchers need to audit automated outputs, align them with human judgments, and communicate findings. The Viewer:
+- `paper/paper.md`
+- `paper/paper.bib`
 
-- plays videos with **overlayed tracks** (e.g., landmarks, gaze on/off, bounding boxes, utterance spans);
-- provides **timelines, filters, and side-by-side comparisons** across multiple runs or conditions;
-- reads standardized JSON/CSV outputs (including those from **VideoAnnotator**) and exports selected segments, screenshots, or summary tables.
-
-# Statement of need
-
-When automated pipelines scale up, researchers must still *inspect and trust* what detectors produced—especially where constructs are subjective, culturally variable, or ethically sensitive. Visual inspection and efficient comparison improve reliability, uncover edge cases, and make downstream validation more efficient. Prior discussions of the “measurement gap” in large-scale observational research emphasize that scalable automation must be paired with *interpretable review* tools to be credible and useful. 
-
-The Viewer addresses this by providing a focused, domain-agnostic interface: load a folder or manifest of videos + annotations; scrub, filter, and compare; export the evidence. It is not a monolithic analysis suite; it is the *inspection lens* researchers can adopt irrespective of their chosen detectors/models.
-
-# Functionality
-
-- **Overlayed playback.** Draw tracks and events (e.g., facial AUs, poses, segments) on the video; toggle layers; adjust thresholds.
-- **Timeline & filters.** Zoomable timelines, text search over events, and filters by detector, label, confidence, or time window.
-- **Comparison.** Side-by-side view of (a) different models on the same video or (b) the same model on different videos/conditions.
-- **Review & export.** Bookmark moments, export stills or CSV summaries, and generate minimal “review packets” for human raters.
-- **Interoperability.** Reads the standardized outputs from *VideoAnnotator* but accepts any tool that emits timestamped events/tracks.
-
-# Design & architecture
-
-- **Backend tasks (optional).** If configured, the Viewer can submit jobs to a running VideoAnnotator service to process new videos and display results when ready.
-- **Decoupled front end.** Modern web stack with stateless reading of manifest + annotation files; no database required for local use.
-- **Reproducibility.** View-state can be serialized (e.g., selected layers, thresholds, time range) for sharing exact audit contexts with collaborators.
-
-# Validation and usability
-
-We include demo manifests with short clips and annotations to exercise overlays, comparisons, and exports, supporting lab onboarding and smoke testing. The tool is designed to support expert review workflows where automated outputs are checked against human judgments before broader use in research or practice. :contentReference[oaicite:6]{index=6}
-
-# Acknowledgements
-
-We thank colleagues across behavioral research communities who emphasized the need for transparent *review tools* to complement automated pipelines and bridge the gap between scalable coding and expert interpretation. 
-
-# References
-
-*References are provided in `paper.bib` (visual analytics for behavioral data, auditability in ML, and prior work on observational methods that motivate inspection tools).*
+This file is retained as a pointer for historical context.

package.json

@@ -13,6 +13,7 @@
     "build": "vite build",
     "build:dev": "vite build --mode development",
     "lint": "eslint .",
+    "lint:strict": "eslint . --max-warnings 0",
     "preview": "vite preview",
     "test": "vitest",
     "test:ui": "vitest --ui",