mirror of
https://github.com/AmanTahiliani/box-box.git
synced 2026-08-08 04:06:18 -04:00
Compare commits
3 Commits
chore/agen
...
feat/issue
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ba7f653e3c | ||
|
|
75ca5f4deb | ||
|
|
094620fa08 |
49
.agents/README.md
Normal file
49
.agents/README.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# `.agents/` — harness-agnostic agentic dev toolkit
|
||||
|
||||
Portable skills, prompts, and scripts that drive the box-box development lifecycle.
|
||||
Any harness (Claude, Codex, opencode, …) can read these — the canonical workflows
|
||||
live here, not in a tool-specific folder. The shared project context every harness
|
||||
reads is `AGENTS.md` (→ `CLAUDE.md`).
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
skills/ Codex/open agent skills: groom, write-spec, implement, review, lenses
|
||||
personas/ grill.md (base) + lens overlays (architect, …) — the interrogation voices
|
||||
prompts/ ready-spec.md (groomed spec), implement.md/review.md dispatch prompts
|
||||
lib/gh.sh GitHub issue + Project (#2) state helpers: issue_*, set_stage/effort/priority
|
||||
lib/dispatch.sh dispatch(): Ready issue → worktree → harness → gate → PR
|
||||
harnesses.sh headless adapters (one fn per harness) + run_gate — the ONLY tool-specific code
|
||||
bin/dev CLI: `dev implement <issue#> --harness <name> [--dry-run]`
|
||||
```
|
||||
|
||||
## The lifecycle
|
||||
|
||||
`Icebox → Research → Ready → In Progress → In Review → Done` (the Project `Stage` field).
|
||||
|
||||
- **Groom** (interactive, Claude): `/groom <issue#>` runs a seeded grill-me → writes a
|
||||
Ready spec into the issue body → sets Effort/Priority → leaves Stage at `Research`.
|
||||
You review and flip to `Ready`.
|
||||
- **Implement** (any harness): `.agents/bin/dev implement <issue#> --harness <name>`
|
||||
(or `/implement …` in Claude to supervise) → isolated worktree → runs the harness
|
||||
headless on the spec → build gate → opens a PR → sets Stage `In Review`.
|
||||
- **Review + merge**: use the `review` skill from a harness different from the
|
||||
implementer to create a local review packet and PR comment, then you merge.
|
||||
|
||||
## Skills and harnesses
|
||||
|
||||
`.agents/skills` is the canonical home for reusable workflows. Codex discovers
|
||||
repo skills from that path directly, and Claude can use the same files through
|
||||
`.claude/skills -> ../.agents/skills`. Other harnesses can read the same
|
||||
`SKILL.md` files explicitly or enter the workflow through `.agents/bin/dev`.
|
||||
Do not put canonical workflow instructions under `.claude/`; that directory is
|
||||
local adapter state.
|
||||
|
||||
## Adding / fixing a harness
|
||||
|
||||
Edit one function in `harnesses.sh`: `harness_<name> <workdir> <promptfile>`, running the
|
||||
tool non-interactively in `<workdir>` on the prompt. `claude`/`codex`/`opencode` are
|
||||
wired; `pi`/`cursor` are stubs — confirm their headless flags before trusting.
|
||||
|
||||
Always `--dry-run` a new harness first: it renders the exact prompt and plan, touching
|
||||
nothing (no worktree, PR, or state change).
|
||||
45
.agents/bin/dev
Executable file
45
.agents/bin/dev
Executable file
@@ -0,0 +1,45 @@
|
||||
#!/usr/bin/env bash
|
||||
# .agents/bin/dev — box-box agentic dev CLI. Works from any harness's shell.
|
||||
#
|
||||
# dev implement <issue#> --harness <claude|codex|opencode|pi|cursor> [--dry-run] [--base <branch>]
|
||||
#
|
||||
# Grooming is driven interactively via the Claude Code /groom skill; this CLI covers
|
||||
# the implement lane (dispatch a Ready issue to a harness → worktree → gate → PR).
|
||||
|
||||
set -o pipefail
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)"
|
||||
|
||||
usage() {
|
||||
cat >&2 <<EOF
|
||||
box-box dev CLI
|
||||
|
||||
dev implement <issue#> --harness <name> [--dry-run] [--base <branch>]
|
||||
|
||||
harnesses: claude, codex, opencode (supported) · pi, cursor (verify flags in .agents/harnesses.sh)
|
||||
--dry-run render the prompt + plan, touch nothing (no worktree/PR/state change)
|
||||
--base base branch for the worktree/PR (default: main)
|
||||
EOF
|
||||
exit 2
|
||||
}
|
||||
|
||||
cmd="${1:-}"; shift 2>/dev/null || true
|
||||
case "$cmd" in
|
||||
implement)
|
||||
issue="${1:-}"; shift 2>/dev/null || true
|
||||
harness=""; passthru=()
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--harness) harness="${2:-}"; shift 2 ;;
|
||||
--dry-run) passthru+=(--dry-run); shift ;;
|
||||
--base) passthru+=(--base "${2:-}"); shift 2 ;;
|
||||
*) echo "unknown arg: $1" >&2; usage ;;
|
||||
esac
|
||||
done
|
||||
[ -n "$issue" ] && [ -n "$harness" ] || usage
|
||||
# shellcheck source=/dev/null
|
||||
source "$ROOT/.agents/lib/dispatch.sh"
|
||||
dispatch "$issue" "$harness" ${passthru[@]+"${passthru[@]}"}
|
||||
;;
|
||||
""|-h|--help|help) usage ;;
|
||||
*) echo "unknown command: $cmd" >&2; usage ;;
|
||||
esac
|
||||
60
.agents/harnesses.sh
Normal file
60
.agents/harnesses.sh
Normal file
@@ -0,0 +1,60 @@
|
||||
#!/usr/bin/env bash
|
||||
# .agents/harnesses.sh — headless harness adapters.
|
||||
#
|
||||
# ONE function per harness: harness_<name> <workdir> <promptfile>
|
||||
# Each runs the harness NON-INTERACTIVELY inside <workdir>, feeding it the rendered
|
||||
# prompt, expected to edit files (and ideally commit). This is the ONLY harness-specific
|
||||
# code in the toolkit — tune the exact flags here per tool/version.
|
||||
#
|
||||
# Autonomy note: these run unattended, so each uses the tool's "just do it" mode
|
||||
# (accept edits / full-auto). Only run harnesses you trust on code you can review via PR.
|
||||
|
||||
# ---- MUST-HAVE ----
|
||||
|
||||
harness_claude() { # Claude Code — print mode, auto-accept edits
|
||||
local dir="$1" prompt="$2"
|
||||
( cd "$dir" && claude -p "$(cat "$prompt")" --permission-mode acceptEdits )
|
||||
}
|
||||
|
||||
harness_codex() { # OpenAI Codex CLI — non-interactive exec, full auto
|
||||
local dir="$1" prompt="$2"
|
||||
( cd "$dir" && codex exec --full-auto "$(cat "$prompt")" )
|
||||
}
|
||||
|
||||
harness_opencode() { # opencode — non-interactive run
|
||||
local dir="$1" prompt="$2"
|
||||
( cd "$dir" && opencode run "$(cat "$prompt")" )
|
||||
}
|
||||
|
||||
harness_cursor() { # Cursor CLI agent — composer-2.5, headless full-auto
|
||||
local dir="$1" prompt="$2"
|
||||
( cd "$dir" && cursor-agent -p "$(cat "$prompt")" --model composer-2.5 --force --trust )
|
||||
}
|
||||
|
||||
harness_agy() { # Antigravity CLI — Gemini 3.1 Pro, headless full-auto
|
||||
# --new-project is required for --model to take effect (otherwise agy resumes the
|
||||
# previous conversation and silently keeps its old model).
|
||||
local dir="$1" prompt="$2"
|
||||
( cd "$dir" && agy --print --new-project --print-timeout 60m \
|
||||
--model="Gemini 3.1 Pro (High)" --dangerously-skip-permissions "$(cat "$prompt")" )
|
||||
}
|
||||
|
||||
# ---- NICE-TO-HAVE (verify the exact invocation for your version before trusting) ----
|
||||
|
||||
harness_pi() { # pi — CONFIRM headless CLI + flags
|
||||
local dir="$1" prompt="$2"
|
||||
( cd "$dir" && pi run "$(cat "$prompt")" ) # placeholder — verify
|
||||
}
|
||||
|
||||
# ---- build/typecheck gate (fast, local) ----
|
||||
# Returns non-zero on failure. This is a smoke gate — CI runs the full suite. Tune freely.
|
||||
run_gate() {
|
||||
local dir="$1"
|
||||
( cd "$dir" && go build ./... ) || return 1
|
||||
if [ -d "$dir/frontend/node_modules" ]; then
|
||||
( cd "$dir/frontend" && npx tsc --noEmit ) || return 1
|
||||
else
|
||||
echo " (gate: frontend deps absent in worktree — tsc/vitest deferred to CI)" >&2
|
||||
fi
|
||||
return 0
|
||||
}
|
||||
121
.agents/lib/dispatch.sh
Normal file
121
.agents/lib/dispatch.sh
Normal file
@@ -0,0 +1,121 @@
|
||||
#!/usr/bin/env bash
|
||||
# .agents/lib/dispatch.sh — implement a Ready issue with a chosen harness in an
|
||||
# isolated git worktree, run the build gate, and open a PR.
|
||||
#
|
||||
# Source it, then: dispatch <issue#> <harness> [--dry-run] [--base <branch>]
|
||||
# (or use the CLI: .agents/bin/dev implement <issue#> --harness <name> [--dry-run])
|
||||
|
||||
_AGENTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
# shellcheck source=/dev/null
|
||||
source "$_AGENTS_DIR/lib/gh.sh"
|
||||
# shellcheck source=/dev/null
|
||||
source "$_AGENTS_DIR/harnesses.sh"
|
||||
|
||||
_slug() { echo "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c1-40; }
|
||||
|
||||
_render_prompt() { # <issue#> <title> <body>
|
||||
echo "# Implement: $2"
|
||||
echo
|
||||
cat "$_AGENTS_DIR/prompts/implement.md"
|
||||
echo; echo "---"; echo
|
||||
echo "## Spec — issue #$1"
|
||||
echo
|
||||
echo "$3"
|
||||
}
|
||||
|
||||
_pr_body() { # <issue#> <harness> <gate>
|
||||
cat <<EOF
|
||||
Implements #$1.
|
||||
|
||||
- **Harness:** $2 (dispatched via \`.agents/bin/dev\`)
|
||||
- **Local gate** (\`go build\` + \`tsc --noEmit\`): **$3**
|
||||
- Full test suite + independent review run in CI / by a reviewer harness.
|
||||
|
||||
See #$1 for the groomed spec, Test Plan, and Definition of Done.
|
||||
|
||||
Closes #$1
|
||||
EOF
|
||||
}
|
||||
|
||||
dispatch() { # <issue#> <harness> [--dry-run] [--base <branch>]
|
||||
local issue="$1" harness="$2"; shift 2 || { echo "usage: dispatch <issue#> <harness> [--dry-run] [--base <branch>]"; return 2; }
|
||||
local dry=0 base="main"
|
||||
while [ $# -gt 0 ]; do
|
||||
case "$1" in
|
||||
--dry-run) dry=1 ;;
|
||||
--base) base="$2"; shift ;;
|
||||
*) echo "dispatch: unknown flag '$1'" >&2; return 2 ;;
|
||||
esac; shift
|
||||
done
|
||||
|
||||
# adapter must exist
|
||||
if ! declare -f "harness_$harness" >/dev/null 2>&1; then
|
||||
echo "no adapter for harness '$harness' — add harness_$harness() to .agents/harnesses.sh" >&2; return 2
|
||||
fi
|
||||
|
||||
local repo_root title body slug branch wt prompt
|
||||
repo_root="$(git rev-parse --show-toplevel)" || return 1
|
||||
title="$(issue_title "$issue")" || { echo "issue #$issue not found on $REPO" >&2; return 1; }
|
||||
body="$(issue_body "$issue")"
|
||||
slug="$(_slug "$title")"
|
||||
branch="feat/issue-${issue}-${slug}"
|
||||
wt="$repo_root/.worktrees/issue-${issue}"
|
||||
prompt="$(mktemp "${TMPDIR:-/tmp}/boxbox-prompt-${issue}.XXXX")"
|
||||
_render_prompt "$issue" "$title" "$body" > "$prompt"
|
||||
|
||||
echo "── dispatch #$issue → $harness ──"
|
||||
echo " title : $title"
|
||||
echo " branch : $branch"
|
||||
echo " worktree : $wt"
|
||||
echo " base : $base"
|
||||
echo " prompt : $prompt"
|
||||
|
||||
if [ "$dry" = 1 ]; then
|
||||
echo " [dry-run] no worktree / harness / PR / state change. Prompt preview:"
|
||||
sed 's/^/ | /' "$prompt"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# preflight: warn (don't block) if not Ready
|
||||
local stage; stage="$(get_field "$issue" Stage)"
|
||||
[ "$stage" = "Ready" ] || echo " ⚠ Stage is '$stage' (not Ready) — dispatching anyway"
|
||||
|
||||
# isolated worktree
|
||||
if [ -d "$wt" ]; then
|
||||
echo " worktree exists — reusing"
|
||||
else
|
||||
git -C "$repo_root" worktree add -b "$branch" "$wt" "$base" || return 1
|
||||
fi
|
||||
|
||||
set_stage "$issue" "In Progress"
|
||||
|
||||
echo " running $harness (headless)…"
|
||||
( harness_"$harness" "$wt" "$prompt" ); local hrc=$?
|
||||
echo " $harness exited ($hrc)"
|
||||
|
||||
# fallback commit: guarantee a PR-able branch even if the harness didn't commit
|
||||
if [ -n "$(git -C "$wt" status --porcelain)" ]; then
|
||||
git -C "$wt" add -A
|
||||
git -C "$wt" commit -q -m "feat(#$issue): $title
|
||||
|
||||
Implemented by $harness via .agents/dev dispatch." && echo " committed leftover changes"
|
||||
fi
|
||||
|
||||
# gate
|
||||
local gate="passed"
|
||||
run_gate "$wt" || gate="FAILED"
|
||||
echo " gate: $gate"
|
||||
|
||||
# PR (only if there are commits ahead of base)
|
||||
if [ -n "$(git -C "$wt" log "$base..$branch" --oneline 2>/dev/null)" ]; then
|
||||
git -C "$wt" push -u origin "$branch" || { echo " push failed — inspect $wt" >&2; return 1; }
|
||||
local draft=""; [ "$gate" = "FAILED" ] && draft="--draft"
|
||||
local pr
|
||||
pr="$(gh pr create -R "$REPO" --head "$branch" --base "$base" $draft \
|
||||
--title "$title (#$issue)" --body "$(_pr_body "$issue" "$harness" "$gate")")" || { echo " gh pr create failed" >&2; return 1; }
|
||||
echo " PR: $pr${draft:+ (draft — gate failed)}"
|
||||
set_stage "$issue" "In Review"
|
||||
else
|
||||
echo " no commits on $branch — leaving Stage 'In Progress'. Inspect the worktree: $wt" >&2
|
||||
fi
|
||||
}
|
||||
68
.agents/lib/gh.sh
Normal file
68
.agents/lib/gh.sh
Normal file
@@ -0,0 +1,68 @@
|
||||
#!/usr/bin/env bash
|
||||
# .agents/lib/gh.sh — harness-agnostic helpers for the box-box agentic dev lifecycle.
|
||||
#
|
||||
# Source it, then call the functions:
|
||||
# source .agents/lib/gh.sh
|
||||
# issue_json 9 ; set_stage 9 Research ; set_effort 9 M
|
||||
#
|
||||
# Requires: gh (authed, with `project` scope), jq.
|
||||
# Config is overridable via env vars.
|
||||
|
||||
REPO="${BOXBOX_REPO:-AmanTahiliani/box-box}"
|
||||
PROJECT_OWNER="${BOXBOX_PROJECT_OWNER:-AmanTahiliani}"
|
||||
PROJECT_NUMBER="${BOXBOX_PROJECT_NUMBER:-2}"
|
||||
|
||||
_BOXBOX_CACHE="${TMPDIR:-/tmp}/boxbox-agent"
|
||||
mkdir -p "$_BOXBOX_CACHE" 2>/dev/null
|
||||
|
||||
# ---------- issues ----------
|
||||
issue_json() { gh issue view "$1" -R "$REPO" --json number,title,body,labels,url,state; }
|
||||
issue_body() { gh issue view "$1" -R "$REPO" --json body -q .body; }
|
||||
issue_title() { gh issue view "$1" -R "$REPO" --json title -q .title; }
|
||||
issue_url() { gh issue view "$1" -R "$REPO" --json url -q .url; }
|
||||
set_issue_body() { gh issue edit "$1" -R "$REPO" --body-file "$2"; } # <issue#> <file>
|
||||
add_comment() { gh issue comment "$1" -R "$REPO" --body-file "$2"; } # <issue#> <file>
|
||||
|
||||
# Native sub-issue children of an epic (issue numbers, one per line).
|
||||
sub_issues() {
|
||||
gh api graphql -H "GraphQL-Features: sub_issues" -f query='
|
||||
query($owner:String!,$repo:String!,$num:Int!){
|
||||
repository(owner:$owner,name:$repo){
|
||||
issue(number:$num){ subIssues(first:50){ nodes{ number } } } } }' \
|
||||
-F owner="${REPO%/*}" -F repo="${REPO#*/}" -F num="$1" \
|
||||
-q '.data.repository.issue.subIssues.nodes[].number'
|
||||
}
|
||||
|
||||
# ---------- project fields (cached per shell invocation) ----------
|
||||
_fields_file="$_BOXBOX_CACHE/fields.json"
|
||||
_items_file="$_BOXBOX_CACHE/items.json"
|
||||
_pid_file="$_BOXBOX_CACHE/project_id"
|
||||
|
||||
_refresh_fields() { gh project field-list "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --format json > "$_fields_file"; }
|
||||
_refresh_items() { gh project item-list "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --format json --limit 200 > "$_items_file"; }
|
||||
project_refresh() { _refresh_fields; _refresh_items; } # call once at the start of a session to get fresh state
|
||||
|
||||
_project_id() { [ -s "$_pid_file" ] || gh project view "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --format json | jq -r .id > "$_pid_file"; cat "$_pid_file"; }
|
||||
_field_id() { [ -s "$_fields_file" ] || _refresh_fields; jq -r --arg n "$1" '.fields[]|select(.name==$n)|.id' "$_fields_file"; }
|
||||
_option_id() { [ -s "$_fields_file" ] || _refresh_fields; jq -r --arg f "$1" --arg o "$2" '.fields[]|select(.name==$f)|.options[]?|select(.name==$o)|.id' "$_fields_file"; }
|
||||
_item_id() { [ -s "$_items_file" ] || _refresh_items; jq -r --arg n "$1" '.items[]|select(.content.number==($n|tonumber))|.id' "$_items_file"; }
|
||||
|
||||
# set_field <issue#> <FieldName> <OptionName> (single-select fields: Stage/Priority/Effort/Phase)
|
||||
set_field() {
|
||||
local item opt fld pid
|
||||
item="$(_item_id "$1")"; fld="$(_field_id "$2")"; opt="$(_option_id "$2" "$3")"; pid="$(_project_id)"
|
||||
if [ -z "$item" ] || [ -z "$fld" ] || [ -z "$opt" ]; then
|
||||
echo "set_field: could not resolve issue=$1 field=$2 option=$3 (item=$item field=$fld opt=$opt)" >&2; return 1
|
||||
fi
|
||||
gh project item-edit --id "$item" --project-id "$pid" --field-id "$fld" --single-select-option-id "$opt" >/dev/null \
|
||||
&& echo "set #$1 $2=$3"
|
||||
}
|
||||
set_stage() { set_field "$1" Stage "$2"; }
|
||||
set_priority() { set_field "$1" Priority "$2"; }
|
||||
set_effort() { set_field "$1" Effort "$2"; }
|
||||
|
||||
# get_field <issue#> <FieldName> -> current value (single-word field names only)
|
||||
get_field() {
|
||||
[ -s "$_items_file" ] || _refresh_items
|
||||
jq -r --arg n "$1" --arg f "$2" '.items[]|select(.content.number==($n|tonumber))|.[($f|ascii_downcase)] // "-"' "$_items_file"
|
||||
}
|
||||
35
.agents/personas/architect.md
Normal file
35
.agents/personas/architect.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Lens overlay: Architect
|
||||
|
||||
Apply this **on top of** the base grill (`grill.md`). Bias every question toward
|
||||
technical soundness and fit with the existing box-box architecture.
|
||||
|
||||
## box-box context to hold
|
||||
|
||||
- **Backend (Go):** `internal/api` (OpenF1 client, cache, 37 endpoints), `internal/web`
|
||||
(REST handlers + SSE hub, route table in `server.go`), `internal/store` (domain
|
||||
SQLite), `internal/query` (read models over the domain DB), `internal/ingest`,
|
||||
`internal/live` (SignalR).
|
||||
- **Frontend (React+Vite+TS):** TanStack Router/Query, `src/api.ts` (typed fetchers),
|
||||
`src/types.ts` (payload mirrors), `src/lib` (client helpers), `src/pages`,
|
||||
`src/components` (incl. `components/live`).
|
||||
- **Patterns to respect** (see CLAUDE.md "How To Extend"): ServeMux longest-prefix
|
||||
route ordering in `server.go`, cache TTL tiers, `?source=openf1|local|auto`
|
||||
resolution, two-phase standings load, lazy tab loads, stale-data fallback banner.
|
||||
|
||||
## Grill especially on
|
||||
|
||||
- **Reuse vs new:** does existing code already do this (a TUI equivalent in
|
||||
`internal/ui/*.go`, a query model, an `api.ts` fetcher)? Port vs rebuild.
|
||||
- **Data flow & source:** OpenF1 live vs domain DB vs cache; payload size; rate
|
||||
limits; how `?source` is handled.
|
||||
- **Seams:** which files/modules change; new endpoint (mind registration order!) vs
|
||||
extend an existing one; new component vs extend; where shared logic lives
|
||||
(`frontend/src/lib/*`).
|
||||
- **Testability:** how does this land in `go test` / `vitest` / hermetic Playwright?
|
||||
What seam makes it testable without live OpenF1?
|
||||
- **Risk:** domain-DB migrations, perf on large sessions, backward compat, and
|
||||
failure / stale-data behavior.
|
||||
|
||||
Keep questions concrete and decision-shaped — e.g. *"port the GPS normalization from
|
||||
`internal/ui/trackmap.go`, or recompute in a shared `frontend/src/lib/trackmap.ts` so
|
||||
it's unit-testable?"* — each with your recommendation.
|
||||
51
.agents/personas/grill.md
Normal file
51
.agents/personas/grill.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Persona: The Grill
|
||||
|
||||
You run a **grill-me** session. Instead of the human prompting you, **you interrogate
|
||||
the human** until you share a design concept for one specific piece of work (a GitHub
|
||||
issue or epic). The shared understanding — not the document — is the real output.
|
||||
|
||||
## Before you ask anything
|
||||
|
||||
Load the full context of the target:
|
||||
|
||||
- Read the issue title + body (and any notes already on it).
|
||||
- Read `CLAUDE.md`.
|
||||
- Explore the code paths the work implicates.
|
||||
|
||||
## Rules
|
||||
|
||||
1. **One question at a time.** Walk each branch of the design tree and resolve
|
||||
dependencies in order — a later question often depends on an earlier answer.
|
||||
2. **Recommend, consequence-first.** Every question carries your recommended answer
|
||||
and a short "why". **Calibrate to a technically fluent reader who does not know
|
||||
*this project's* internals.** Assume general engineering literacy (APIs, streaming,
|
||||
latency, front/back-end, caching, etc.) and don't explain those. **Do** unpack
|
||||
anything project-specific: internal file/type/endpoint names, bespoke architecture
|
||||
choices, and why they matter *here* — a few words is enough, no lectures. Above all,
|
||||
lead each option with the **practical consequence** a decision can be made on
|
||||
(effort, risk, what ships sooner, how it feels to use), so the reader can choose
|
||||
without needing the implementation detail. Recommendation first, with why it's the
|
||||
better call **for them**.
|
||||
- *Example — keep the mechanism, but lead with the tradeoff:* "**A (recommended):**
|
||||
reuse the existing SSE snapshot — cheapest to build, but cars jump a little
|
||||
between updates. **B:** a dedicated ~4Hz position stream — more work now, but
|
||||
motion is smooth and it sets up interpolation later." (Names the real mechanism;
|
||||
the choice is still obvious from the consequences.)
|
||||
3. **Hybrid asking.**
|
||||
- Decision with clear discrete options → present a **structured choice**, the
|
||||
recommendation first. *(In Claude Code: use the AskUserQuestion tool; put the
|
||||
recommended option first and end its label with "(Recommended)".)* Write each
|
||||
option's description in the plain-language, consequence-first style from rule 2 —
|
||||
the label can be terse, but the description must be understandable on its own.
|
||||
- Genuinely open-ended → ask in **prose**.
|
||||
4. **Explore before you ask.** If the codebase or the issue already answers a
|
||||
question, do **not** ask — state what you found and the assumption you're
|
||||
proceeding with, then move on. Only ask about real forks the human must decide.
|
||||
5. **Stay in scope.** Grill the design of *this* work, not the whole app. Note
|
||||
out-of-scope temptations instead of chasing them.
|
||||
|
||||
## Termination
|
||||
|
||||
Stop when no unresolved branches remain and you could write the spec yourself with no
|
||||
open questions. Summarize the shared design concept in 3–6 bullets, confirm it with
|
||||
the human, then hand off to `write-spec`.
|
||||
21
.agents/prompts/implement.md
Normal file
21
.agents/prompts/implement.md
Normal file
@@ -0,0 +1,21 @@
|
||||
You are an autonomous coding agent working in an **isolated git worktree** on the
|
||||
**box-box** repo. Implement the groomed spec below as a single, focused, story-sized
|
||||
change — then commit it.
|
||||
|
||||
## Ground rules
|
||||
- Read `AGENTS.md` / `CLAUDE.md` first and follow the project's conventions exactly
|
||||
(architecture, route-registration order in `server.go`, cache TTL tiers,
|
||||
`api.ts`/`types.ts` mirrors, test layout).
|
||||
- Implement ONLY this story's scope. Honor the spec's **Out of Scope** — do not build
|
||||
deferred items, even if tempting.
|
||||
- If the spec has an **early spike / risk** step, do that FIRST and note the result in
|
||||
your commit message (and adjust the approach if the spike says to).
|
||||
- Add or extend tests per the **Test Plan**. Make the relevant suites pass:
|
||||
`go build ./...`, `go test ./...`, and in `frontend/`: `npm run test`, `tsc --noEmit`.
|
||||
- Keep the change reviewable and story-sized. **Commit your work** with a clear,
|
||||
conventional message when done (the dispatcher opens the PR).
|
||||
- Satisfy every item in the spec's **Definition of Done**.
|
||||
|
||||
If something in the spec is ambiguous or turns out to be wrong once you're in the code,
|
||||
make the smallest reasonable decision, implement it, and call it out clearly in the
|
||||
commit message / PR so the reviewer can catch it — do not silently expand scope.
|
||||
27
.agents/prompts/ready-spec.md
Normal file
27
.agents/prompts/ready-spec.md
Normal file
@@ -0,0 +1,27 @@
|
||||
## Context
|
||||
{one paragraph: the problem and why it matters, grounded in the grooming}
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] {observable behaviour 1}
|
||||
- [ ] {observable behaviour 2}
|
||||
|
||||
## Technical Approach
|
||||
- **Files to touch:** {real paths}
|
||||
- **Data source:** {OpenF1 live | domain DB | cache | ...}
|
||||
- **Endpoints/components:** {new or extended — note route-registration order if new}
|
||||
- **Key decisions:** {the forks resolved during the grill}
|
||||
|
||||
## Test Plan
|
||||
- {cases mapped to the real suites: go test · vitest · hermetic Playwright}
|
||||
|
||||
## Out of Scope
|
||||
- {explicitly deferred}
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Tests added and green (`go test` · `vitest` · `tsc --noEmit` · hermetic Playwright as applicable)
|
||||
- [ ] Matches CLAUDE.md conventions (route order, cache TTLs, `api.ts`/`types.ts` mirrors)
|
||||
- [ ] No console / preview errors (UI verified in preview)
|
||||
- [ ] Story-sized PR, linked to this issue
|
||||
|
||||
---
|
||||
_Groomed {date} · Effort {S|M|L} · Priority {P0|P1|P2} · via /groom_
|
||||
20
.agents/prompts/review.md
Normal file
20
.agents/prompts/review.md
Normal file
@@ -0,0 +1,20 @@
|
||||
You are an independent reviewer for a box-box pull request. Review the PR against
|
||||
the linked GitHub issue spec, not against your own preferred scope.
|
||||
|
||||
## Ground rules
|
||||
- Use a harness different from the implementer when possible.
|
||||
- Read `AGENTS.md` / `CLAUDE.md`, the PR body/diff, and the linked issue body.
|
||||
- Run the relevant local gates and capture logs under `.review/issue-<n>-pr-<pr>/logs`.
|
||||
- For UI changes, create a local visual packet under `.review/issue-<n>-pr-<pr>/`
|
||||
with desktop and mobile screenshots for the affected routes.
|
||||
- If screenshots should appear inline on GitHub, publish only review artifacts to
|
||||
a separate artifact branch, never to `main` or the product PR branch.
|
||||
- Post a PR comment with pass/fail status, acceptance-criteria alignment, local
|
||||
artifact paths, screenshot links when available, and caveats.
|
||||
- Do not merge. The human owns the merge gate.
|
||||
|
||||
## Output
|
||||
- A local packet with `summary.md`, optional `index.html`, screenshots, logs, and
|
||||
any visual diffs.
|
||||
- A GitHub PR comment that makes the review visually scannable.
|
||||
- A clear recommendation: pass, pass with caveats, or needs changes.
|
||||
42
.agents/skills/groom/SKILL.md
Normal file
42
.agents/skills/groom/SKILL.md
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: groom
|
||||
description: Groom a box-box GitHub issue into a Ready spec via a seeded grill-me interrogation. Use when the user asks to groom an issue, for example "/groom <issue-number>" or "$groom <issue-number>" with optional "--lens architect". Single-issue path: asks targeted questions, writes a structured spec into the issue body, sets Effort/Priority, and leaves Stage at Research for approval.
|
||||
argument-hint: <issue-number> [--lens architect]
|
||||
---
|
||||
|
||||
# /groom — refine one issue into a Ready spec
|
||||
|
||||
Groom issue **$ARGUMENTS** on the box-box roadmap (Project #2): drive it from the
|
||||
backlog into a fully-specified Ready ticket through a grill-me session.
|
||||
|
||||
## 0. Setup
|
||||
- Parse the first token of the arguments as the **issue number**. An optional
|
||||
`--lens <name>` pulls in a lens overlay (currently: `architect`).
|
||||
- Run: `source .agents/lib/gh.sh && project_refresh` (fresh field/item state).
|
||||
- Load context **before asking anything**: `issue_json <n>`, read `CLAUDE.md`, and
|
||||
explore the code paths the issue implicates.
|
||||
- Move it into grooming if it isn't already there: `set_stage <n> Research`.
|
||||
|
||||
## 1. Grill
|
||||
- Read `.agents/personas/grill.md`. If `--lens <name>` was given, also read
|
||||
`.agents/personas/<name>.md` and apply it on top.
|
||||
- Run the grill exactly per those rules: **one question at a time**, recommendation
|
||||
first, **hybrid** asking (AskUserQuestion for discrete decisions with the
|
||||
recommended option first and labelled "(Recommended)"; prose for open-ended), and
|
||||
**explore the code to self-answer** wherever possible — only ask about genuine forks.
|
||||
- Track the resolved decisions as you go.
|
||||
|
||||
## 2. Synthesize
|
||||
- When no open branches remain, summarize the shared design concept in 3–6 bullets and
|
||||
confirm it with the user.
|
||||
- Then invoke the **write-spec** skill for issue `<n>`, handing it the resolved
|
||||
decisions, so it renders `.agents/prompts/ready-spec.md` into the issue body and
|
||||
sets Effort + Priority.
|
||||
|
||||
## 3. Hand back (human gate)
|
||||
- Do **not** auto-advance to Ready — that's the user's call. Report that the spec is
|
||||
written, Stage is `Research`, and they should review the issue and flip Stage →
|
||||
`Ready` when satisfied (`set_stage <n> Ready`).
|
||||
- Print the issue URL (`issue_url <n>`).
|
||||
|
||||
Stay focused on THIS issue's design throughout. Note but don't chase out-of-scope ideas.
|
||||
32
.agents/skills/implement/SKILL.md
Normal file
32
.agents/skills/implement/SKILL.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
name: implement
|
||||
description: Dispatch a Ready box-box issue to a coding harness (claude/codex/opencode/pi/cursor) in an isolated git worktree, run the build gate, and open a PR. Use when supervising implementation via "/implement <issue-number> --harness <name> [--dry-run]" or from any harness terminal with .agents/bin/dev.
|
||||
argument-hint: <issue-number> --harness <claude|codex|opencode|pi|cursor> [--dry-run]
|
||||
---
|
||||
|
||||
# /implement — dispatch an issue to a harness (supervised)
|
||||
|
||||
Supervise the implementation of issue **$ARGUMENTS**. You are SUPERVISING, not coding —
|
||||
a fresh harness does the work in its own isolated worktree with clean context. Do not
|
||||
edit project files yourself.
|
||||
|
||||
## Steps
|
||||
1. Parse: `<issue-number> --harness <name> [--dry-run] [--base <branch>]`.
|
||||
2. **Preflight (report, don't hard-block):** `source .agents/lib/gh.sh` and check
|
||||
`get_field <n> Stage` is `Ready` and the issue body has an "## Acceptance Criteria"
|
||||
section (a groomed spec). If it's not Ready or has no spec, say so and recommend
|
||||
`/groom <n>` first — proceed only if the user confirms.
|
||||
3. **Dispatch:** run `.agents/bin/dev implement <n> --harness <name> [flags]`. For a
|
||||
first run against an unfamiliar harness, suggest `--dry-run` first so the user can
|
||||
eyeball the prompt.
|
||||
4. **Report the outcome:** branch, worktree path, gate result (pass/FAILED → draft PR),
|
||||
and the PR URL. On success, Stage will be `In Review`.
|
||||
5. If no PR was created (no changes, or push failed), surface exactly why and point at
|
||||
the worktree (`.worktrees/issue-<n>`) so the user can inspect. Diagnose from the
|
||||
dispatcher output; recommend a fix or re-run — don't silently take over the coding.
|
||||
|
||||
## Notes
|
||||
- The harness adapters and the gate live in `.agents/harnesses.sh` — the single place
|
||||
to tune per-tool flags.
|
||||
- From any harness shell, run the same thing directly:
|
||||
`.agents/bin/dev implement <n> --harness <name>`.
|
||||
22
.agents/skills/lens-architect/SKILL.md
Normal file
22
.agents/skills/lens-architect/SKILL.md
Normal file
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: lens-architect
|
||||
description: Grill/analyze a box-box issue or epic from a software-architecture perspective and post the findings as a comment. Use standalone as "/lens-architect <issue-number>" for an on-the-fly architecture review, or let /groom compose it via "--lens architect". Reads the base grill + architect persona and focuses on reuse, data flow, seams, testability, and risk.
|
||||
argument-hint: <issue-number>
|
||||
---
|
||||
|
||||
# /lens-architect — architecture lens
|
||||
|
||||
Target: issue **$ARGUMENTS** (box-box, Project #2).
|
||||
|
||||
1. `source .agents/lib/gh.sh`; load context (`issue_json <n>`, `CLAUDE.md`, and the
|
||||
relevant code paths).
|
||||
2. Read `.agents/personas/grill.md` + `.agents/personas/architect.md` and run a focused
|
||||
grill from the architecture lens: hybrid asking (AskUserQuestion for discrete
|
||||
decisions, recommendation first; prose otherwise), recommend every answer, and
|
||||
explore the code to self-answer before asking.
|
||||
3. When aligned, write an **"## Architecture review"** summary (decisions taken,
|
||||
files/seams affected, risks, the test seam) to a temp file and `add_comment <n> <file>`.
|
||||
4. Print the issue URL.
|
||||
|
||||
If invoked from **within /groom**, skip the comment — instead return the architecture
|
||||
decisions inline so groom can fold them into the spec.
|
||||
53
.agents/skills/review/SKILL.md
Normal file
53
.agents/skills/review/SKILL.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
name: review
|
||||
description: Locally review a box-box PR against its linked GitHub issue spec, run tests, capture visual screenshots when applicable, create a .review packet, and post a GitHub PR comment. Use when a ticket implementation is ready for independent local review before the human merge gate.
|
||||
argument-hint: <pr-number> [--harness <name>] [--publish-screenshots]
|
||||
---
|
||||
|
||||
# /review — local independent PR review
|
||||
|
||||
Review PR **$ARGUMENTS** for box-box using the local-only lifecycle. You are
|
||||
reviewing, not implementing. Do not merge the PR.
|
||||
|
||||
## 0. Setup
|
||||
- Parse the PR number. Optional `--harness <name>` records which reviewer harness is
|
||||
acting; optional `--publish-screenshots` allows pushing visual artifacts to a
|
||||
dedicated artifact branch.
|
||||
- Read `.agents/prompts/review.md`, `AGENTS.md`, the PR metadata/diff, and the linked
|
||||
issue body.
|
||||
- Identify the implementer harness from the PR body when present. If it matches the
|
||||
reviewer harness, call that out as a reduced independence caveat.
|
||||
- Create `.review/issue-<issue>-pr-<pr>/logs`, `screenshots`, and `artifacts`.
|
||||
|
||||
## 1. Verify
|
||||
- Run the smallest meaningful gates first, then broaden based on risk:
|
||||
`go test` for touched Go packages, `npm run test` and `npm run build` for frontend
|
||||
changes, and hermetic Playwright when user-facing routes changed.
|
||||
- Save all command output to `.review/issue-<issue>-pr-<pr>/logs`.
|
||||
- Inspect the diff for spec conformance, scope leaks, missing tests, and known project
|
||||
conventions from `AGENTS.md`.
|
||||
|
||||
## 2. Visual Packet
|
||||
- If the PR changes UI, start a local seeded or mocked preview and capture desktop and
|
||||
mobile screenshots for affected routes.
|
||||
- Prefer hermetic mocks/seeded data over live external state.
|
||||
- Save screenshots under `.review/issue-<issue>-pr-<pr>/screenshots`.
|
||||
- Create a concise `summary.md`; create `index.html` when screenshots exist.
|
||||
|
||||
## 3. Publish
|
||||
- If `--publish-screenshots` is present, publish only review artifacts to a dedicated
|
||||
branch such as `review-artifacts/pr-<pr>/` and use raw GitHub URLs in the comment.
|
||||
- Post a PR comment with:
|
||||
- reviewer harness and implementer harness
|
||||
- result: pass, pass with caveats, or needs changes
|
||||
- local packet path
|
||||
- gates run and results
|
||||
- acceptance-criteria checklist
|
||||
- screenshots or artifact links when available
|
||||
- caveats that the human must inspect
|
||||
- If the result is pass/pass-with-caveats, set the linked issue's custom Project
|
||||
`Stage` to `In Review` using `.agents/lib/gh.sh`. Do not set `Done`.
|
||||
|
||||
## 4. Hand Back
|
||||
- Tell the human exactly what to open locally and what decision remains theirs.
|
||||
- Do not merge or delete worktrees.
|
||||
30
.agents/skills/write-spec/SKILL.md
Normal file
30
.agents/skills/write-spec/SKILL.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: write-spec
|
||||
description: Render a groomed design into the box-box Ready-spec template and write it into a GitHub issue body, then set Effort and Priority. Called by /groom after a grill session, or run standalone as "/write-spec <issue-number>" to (re)write an issue's spec from agreed decisions. Does not change Stage.
|
||||
argument-hint: <issue-number>
|
||||
---
|
||||
|
||||
# /write-spec — write the Ready spec into an issue
|
||||
|
||||
Target issue: **$ARGUMENTS** (box-box, Project #2).
|
||||
|
||||
## Steps
|
||||
1. `source .agents/lib/gh.sh`
|
||||
2. Gather the agreed design decisions: from the current grooming conversation if one
|
||||
is in progress; otherwise ask the user for the key points, or read the issue and
|
||||
explore the code to draft them and confirm.
|
||||
3. Read `.agents/prompts/ready-spec.md` and fill every placeholder:
|
||||
- Concrete, **behavioural** acceptance criteria (checkboxes).
|
||||
- Technical approach grounded in **real files/paths** and the chosen data source.
|
||||
- Test plan mapped to the actual suites (`go test` · `vitest` · hermetic Playwright).
|
||||
- Explicit out-of-scope.
|
||||
- Keep the Definition of Done checklist verbatim.
|
||||
- Stamp the footer: date (from the current-date context), Effort (S/M/L),
|
||||
Priority (P0–P2).
|
||||
4. Write it into the issue body: save the filled template to a temp file under the
|
||||
scratchpad and `set_issue_body <n> <file>`. The spec is the single source of truth —
|
||||
only preserve prior body text that captures decisions the spec doesn't.
|
||||
5. Set fields: `set_effort <n> <S|M|L>` and `set_priority <n> <P0|P1|P2>`.
|
||||
6. Print the issue URL and a one-line summary of what was written.
|
||||
|
||||
Do **not** change Stage — `/groom` owns state transitions.
|
||||
1
.claude/skills
Symbolic link
1
.claude/skills
Symbolic link
@@ -0,0 +1 @@
|
||||
../.agents/skills
|
||||
9
.gitignore
vendored
9
.gitignore
vendored
@@ -22,7 +22,8 @@ frontend/node_modules/
|
||||
frontend/dist/
|
||||
|
||||
# Local Claude workspace settings
|
||||
.claude/
|
||||
.claude/*
|
||||
!.claude/skills
|
||||
|
||||
# Playwright
|
||||
node_modules/
|
||||
@@ -31,3 +32,9 @@ node_modules/
|
||||
/blob-report/
|
||||
/playwright/.cache/
|
||||
/playwright/.auth/
|
||||
|
||||
# agentic dev: isolated implementation worktrees
|
||||
.worktrees/
|
||||
|
||||
# agentic dev: local review packets
|
||||
.review/
|
||||
|
||||
198
docs/PRODUCT_ROADMAP.md
Normal file
198
docs/PRODUCT_ROADMAP.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# box-box — Product & UX Roadmap
|
||||
|
||||
> An F1-geek + product/UX analysis of box-box as an F1 companion, and a
|
||||
> prioritized plan to make it richer than "data in tables" — for both live race
|
||||
> weekends and the quiet stretch between rounds.
|
||||
|
||||
## Where the app is today (honest read)
|
||||
|
||||
box-box has a strong data layer with two front doors (TUI + web) and six web
|
||||
surfaces:
|
||||
|
||||
| Surface | What it does today | Where it's thin |
|
||||
|---|---|---|
|
||||
| **Command Center** (`/`) | Hero weekend + countdown, season calendar, championship snapshot, weekend schedule, news | Strong launcher, but tells you *when*, rarely *what to care about*. It's a menu, not a companion |
|
||||
| **Race Hub** (`/race-hub`) | Per-session tabs: Overview, Race Story (position-evolution scrubber), Strategy (stints), Laps, Conditions, Race Control | `RaceStoryCanvas` is the best "beyond tables" work in the app. Everything else is still tables |
|
||||
| **Live Timing** (`/live`) | SSE timing tower, battle chips, gap sparklines, pinned drivers, RC feed | Solid tower, but it's "a spreadsheet that updates" — no track map, no telemetry, no "what just happened" |
|
||||
| **Championship** (`/championship`) | Standings + hub stats (wins/poles/form) + points simulator | Good; the simulator is a genuine differentiator |
|
||||
| **Briefing** (`/briefing`) | 7 RSS feeds (FIA, BBC, Autosport, RaceFans, Guardian, RACER, F1 YouTube) + readability extraction | Passive reading list, not tied to the season narrative |
|
||||
| **Data Library** (`/admin`) | Ingestion / coverage admin | Fine as-is |
|
||||
|
||||
**Biggest finding:** the app already *pulls* the richest data in F1 — GPS
|
||||
`Location`, full car telemetry (throttle / brake / DRS / gear / rpm / speed),
|
||||
team-radio audio, mini-sector `Segments`, speed traps, overtakes — and the web
|
||||
app visualizes almost none of it. The **track map exists only in the TUI**
|
||||
(`internal/ui/trackmap.go`); telemetry is fetched and shown to nobody. This is a
|
||||
large latent asset.
|
||||
|
||||
## Core product thesis
|
||||
|
||||
An F1 companion serves two different jobs; the app currently treats them the same
|
||||
(data, in tables, per session):
|
||||
|
||||
1. **On a race weekend — the "second screen."** The user is watching the
|
||||
broadcast (or can't, and wants to *feel* it). They want: what's happening now,
|
||||
why it matters, what to watch next. The broadcast supplies emotion; box-box
|
||||
should supply **the data the broadcast doesn't show** — the delta the director
|
||||
cut away from, the undercut developing, the tyre cliff approaching.
|
||||
|
||||
2. **Between races — "understand the season."** No live action. The user wants to
|
||||
make sense of what happened and anticipate what's next: rewatch the story of
|
||||
the last race, argue strategy, track the title fight, get smart before the next
|
||||
round.
|
||||
|
||||
Everything below makes each job *feel* like a companion instead of a database.
|
||||
|
||||
---
|
||||
|
||||
## Race-weekend experience ("second screen")
|
||||
|
||||
### 1. Live Track Map — highest-leverage missing feature
|
||||
Port the TUI's GPS outline (`trackmap.go`, `GetLocation`) to a web SVG dot-map:
|
||||
cars as team-colored dots on the circuit outline, DRS zones highlighted, sectors
|
||||
tinted by status. Turn mini-sectors purple/green live using the `Segments` data
|
||||
already fetched. Tap a car → mini-telemetry readout. This is what turns "updating
|
||||
spreadsheet" into "I'm watching the race."
|
||||
|
||||
### 2. "What just happened" synthesized event rail — the companion voice
|
||||
Combine Race Control + overtakes + pit stops + position deltas into plain-English
|
||||
beats: *"LAP 34 — VER pits (2.4s), rejoins P4 behind NOR — undercut on RUS is
|
||||
live."* The inputs all exist; this is a synthesis layer, not new data. It's the
|
||||
difference between *data* and *commentary*.
|
||||
|
||||
### 3. Telemetry compare overlay
|
||||
On the tower / a driver panel, pick two drivers → overlaid speed/throttle/brake
|
||||
traces + delta-time graph for their last comparable lap. *The* tifosi feature —
|
||||
"where did Leclerc lose the lap." `/api/v1/laps/comparison` + car data already
|
||||
exist; this needs a chart, not a table.
|
||||
|
||||
### 4. Live strategy / tyre-degradation view
|
||||
Stints + tyre age + pit-lane times → live pit window and tyre-cliff panel, with
|
||||
**undercut/overcut threat** indicators from gap-to-car-behind vs. pit-loss time.
|
||||
The pit-window calculator exists in the TUI (`pitwindow.go`); bring it to the web
|
||||
and make it live.
|
||||
|
||||
### 5. Team radio, surfaced
|
||||
`GetTeamRadio` returns audio clips. Add a "Radio" ticker on the live page — play
|
||||
button + driver + timestamp. Peak emotional content, and no rival dashboard has it
|
||||
inline.
|
||||
|
||||
### 6. Session-aware Command Center
|
||||
When a session is live, the home hero should pull the top battles, leader gap, and
|
||||
last RC flag onto the front page instead of only saying "LIVE." Make the front
|
||||
page reactive to the moment.
|
||||
|
||||
---
|
||||
|
||||
## Between-races experience ("understand the season")
|
||||
|
||||
### 7. Race replay as a first-class story
|
||||
Grow `RaceStoryCanvas` from a scrubber into a narrative replay: auto-generated
|
||||
"chapters" (start, first pit phase, VSC, decisive overtake, finish) with a
|
||||
headline each (derived from RC + position swings), and scrub the position graph
|
||||
and track map together. The "watch the race in 90 seconds" mode that makes people
|
||||
open the app on a Tuesday.
|
||||
|
||||
### 8. Driver pages + rivalry view (a real gap)
|
||||
No driver profile exists in the web app. Add a **driver page** (season form,
|
||||
teammate H2H — already computed in the champ hub — quali vs. race pace, tyre
|
||||
management, track-by-track) and a **rivalry view** (two drivers → cumulative
|
||||
points, H2H, gap-over-season). Feeds the argument every fan has.
|
||||
|
||||
### 9. Next-race preview / "get smart" page
|
||||
Between races the app goes quiet. Fill it: circuit characteristics, last year's
|
||||
result (2023/24 is cached), typical strategy (1 vs 2 stop), DRS zones, weather
|
||||
outlook, and the storylines (title-fight math to watch). Turn dead air into
|
||||
anticipation.
|
||||
|
||||
### 10. Championship scenario narratives
|
||||
Extend the simulator from "drag points around" to narrative permutations:
|
||||
*"VER clinches if he outscores NOR by 9 this weekend"* / *"first race McLaren can
|
||||
seal constructors'."* The stuff fans actually search for.
|
||||
|
||||
### 11. Briefing → calendar-aware season digest
|
||||
Reframe the news reader into a paddock digest tied to the calendar: group by GP,
|
||||
tag by team/driver, surface a "since last race" summary. Optionally an
|
||||
LLM-generated weekly briefing (a `claude-haiku` summarization pass over ingested
|
||||
RSS — cheap and on-brand).
|
||||
|
||||
---
|
||||
|
||||
## New / better data sources
|
||||
|
||||
- **Jolpica (Ergast successor, `api.jolpi.ca`)** — free historical results back to
|
||||
1950: qualifying, pit stops, lap times, circuit metadata. Unlocks all-time
|
||||
records, "best-ever at this track," and career stats OpenF1 (2023+) can't give.
|
||||
High value for driver pages and the "get smart" preview.
|
||||
- **OpenF1 weather timeseries** — already fetched; plot it as a session-long strip
|
||||
(track temp / rain / wind) instead of a table. Weather narrates strategy.
|
||||
- **Circuit metadata / DRS zones / corner names** — enriches the track map and
|
||||
previews. Some is in OpenF1 circuit info; curate the rest once as static data.
|
||||
- **Static per-race context** — a tiny curated JSON per round (tyre allocation,
|
||||
notable stats) goes a long way for previews.
|
||||
|
||||
---
|
||||
|
||||
## Cross-cutting UX principles
|
||||
|
||||
1. **Replace tables with a shape wherever a shape carries the meaning.** Lap times
|
||||
→ a trace with fastest lap marked. Stints → a horizontal tyre timeline. Gaps →
|
||||
the sparkline already shipped. Keep tables only where data is genuinely tabular
|
||||
(standings) — but annotate them.
|
||||
2. **Always answer "so what?"** Every number sits next to its meaning (a gap next
|
||||
to "undercut live," a tyre age next to "5 laps from the cliff").
|
||||
3. **One primary "moment" per screen.** The Command Center should always have a
|
||||
single obvious "here's what to watch/do now."
|
||||
4. **Make between-races feel alive.** The app currently rewards you only on
|
||||
Sundays. Previews, digests, replays, and rivalries give a reason to open it
|
||||
midweek.
|
||||
|
||||
---
|
||||
|
||||
## Suggested sequencing (impact × effort)
|
||||
|
||||
**Phase 1 — turn live into a companion (highest impact; data already in hand)**
|
||||
1. Web track map (SVG + GPS + mini-sectors)
|
||||
2. Telemetry compare overlay (speed/throttle/brake + delta)
|
||||
3. "What just happened" synthesized event rail
|
||||
4. Team radio ticker
|
||||
|
||||
**Phase 2 — own the between-races window**
|
||||
5. Narrative race replay (grow `RaceStoryCanvas`)
|
||||
6. Driver pages + rivalry view
|
||||
7. Next-race preview page
|
||||
|
||||
**Phase 3 — depth & reach**
|
||||
8. Jolpica/Ergast historical integration + all-time records
|
||||
9. Championship scenario narratives
|
||||
10. Calendar-aware briefing digest (optional LLM summaries)
|
||||
|
||||
---
|
||||
|
||||
## Execution tracking (GitHub)
|
||||
|
||||
This roadmap is tracked on GitHub:
|
||||
|
||||
- **Project board:** https://github.com/users/AmanTahiliani/projects/2 ("box-box Roadmap")
|
||||
- **Epics:** issues #2–#8 (label `epic`), one per epic above, on Phase milestones
|
||||
- **Stories:** issues #9–#31, wired as native **sub-issues** under their epic (progress rolls up automatically)
|
||||
- **Labels:** `epic`, `enabler`, `research`, `area:{live,viz,between-races,championship,data,ux}`
|
||||
- **Milestones:** `Phase 1 — Live Companion`, `Phase 2 — Between-Races`, `Phase 3 — Depth & Reach`
|
||||
|
||||
**Board fields:** `Stage` (Icebox → Research → Ready → In Progress → In Review → Done),
|
||||
`Priority` (P0–P2), `Effort` (S/M/L), `Phase` (1–3).
|
||||
|
||||
**Working model — active vs. bank:**
|
||||
- Only **1–2 epics active** at a time (currently **E1 Live Race Companion** + **E2 Viz
|
||||
Primitives**); the other five epics are the theme-level idea bank.
|
||||
- `Stage = Icebox` is the story-level bank. The 10 E1/E2 stories are seeded to
|
||||
`Ready`; everything else is `Icebox`. Promote a handful to `Ready`/`In Progress`
|
||||
per cycle; use `Research` to scope a vague idea before it's `Ready`.
|
||||
**Board views** (built):
|
||||
- **Backlog** — Table, all epics with expandable sub-issues: the full bank.
|
||||
- **Board** — grouped by `Stage`, filtered `-stage:Icebox`: the active-WIP wall.
|
||||
- **Roadmap** — Table grouped by `Phase` (Phase 1/2/3). Note: this is a
|
||||
phase-grouped table, not a timeline. A true timeline roadmap needs a date or
|
||||
iteration field (GitHub won't draw/persist a roadmap layout without one); add a
|
||||
`Target date` field and populate it once phases have real target dates, then
|
||||
switch this view to the Roadmap layout.
|
||||
415
frontend/src/components/CommandCenterHero.tsx
Normal file
415
frontend/src/components/CommandCenterHero.tsx
Normal file
@@ -0,0 +1,415 @@
|
||||
import { Link } from '@tanstack/react-router'
|
||||
import { Activity, ArrowRight, Play } from 'lucide-react'
|
||||
import { sessionTypeAbbrev } from '../lib/coverage'
|
||||
import { countryDecal, countryFlag, formatGpDateRange } from '../lib/gpIdentity'
|
||||
import { classifySessionStatus, type HeroStateKind } from '../lib/hero'
|
||||
import { sortLiveTimingRows, trackStatusInfo } from '../lib/live'
|
||||
import {
|
||||
formatCountdown,
|
||||
formatSessionScheduleTime,
|
||||
meetingStartTime,
|
||||
sessionStartTime,
|
||||
type FocusMeetingKind,
|
||||
} from '../lib/schedule'
|
||||
import type { EnrichedResult, LiveStreamData, Meeting, Session, WeekendSession } from '../types'
|
||||
import '../styles/hero.css'
|
||||
|
||||
export interface CommandCenterHeroProps {
|
||||
state: HeroStateKind
|
||||
now: Date
|
||||
accent: string
|
||||
liveActive: boolean
|
||||
liveData: LiveStreamData | null | undefined
|
||||
focusMeeting: Meeting
|
||||
focusKind: FocusMeetingKind
|
||||
sessions: WeekendSession[]
|
||||
currentSession: Session | null
|
||||
nextSession: Session | null
|
||||
analysisSessionKey?: number
|
||||
analysisSessionName?: string
|
||||
lastRaceName: string
|
||||
lastRacePodium: EnrichedResult[]
|
||||
lastRaceSessionKey?: number
|
||||
nextMeeting: Meeting | null
|
||||
}
|
||||
|
||||
export function CommandCenterHero({
|
||||
state,
|
||||
now,
|
||||
accent,
|
||||
liveActive,
|
||||
liveData,
|
||||
focusMeeting,
|
||||
focusKind,
|
||||
sessions,
|
||||
currentSession,
|
||||
nextSession,
|
||||
analysisSessionKey,
|
||||
analysisSessionName,
|
||||
lastRaceName,
|
||||
lastRacePodium,
|
||||
lastRaceSessionKey,
|
||||
nextMeeting,
|
||||
}: CommandCenterHeroProps) {
|
||||
const accentStyle = {
|
||||
'--gp-accent': accent,
|
||||
'--hero-accent': accent,
|
||||
} as React.CSSProperties
|
||||
|
||||
return (
|
||||
<div className="hero-panel cc-hero" data-testid="cc-focus">
|
||||
<section className="hero-card ui-card glass-panel" style={accentStyle}>
|
||||
<div
|
||||
className={`hero-accent${state === 'live' ? ' hero-accent--live' : ''}`}
|
||||
aria-hidden="true"
|
||||
/>
|
||||
<div className="hero-body">
|
||||
<div className="hero-inner">
|
||||
{state === 'live' && (
|
||||
<LiveHero
|
||||
liveActive={liveActive}
|
||||
liveData={liveData}
|
||||
currentSession={currentSession}
|
||||
focusMeeting={focusMeeting}
|
||||
/>
|
||||
)}
|
||||
{state === 'upcoming' && (
|
||||
<UpcomingHero
|
||||
now={now}
|
||||
focusMeeting={focusMeeting}
|
||||
focusKind={focusKind}
|
||||
sessions={sessions}
|
||||
currentSession={currentSession}
|
||||
nextSession={nextSession}
|
||||
liveActive={liveActive}
|
||||
analysisSessionKey={analysisSessionKey}
|
||||
analysisSessionName={analysisSessionName}
|
||||
/>
|
||||
)}
|
||||
{state === 'between' && (
|
||||
<BetweenHero
|
||||
now={now}
|
||||
lastRaceName={lastRaceName}
|
||||
lastRacePodium={lastRacePodium}
|
||||
lastRaceSessionKey={lastRaceSessionKey}
|
||||
nextMeeting={nextMeeting}
|
||||
analysisSessionKey={analysisSessionKey}
|
||||
analysisSessionName={analysisSessionName}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function LiveHero({
|
||||
liveActive,
|
||||
liveData,
|
||||
currentSession,
|
||||
focusMeeting,
|
||||
}: {
|
||||
liveActive: boolean
|
||||
liveData: LiveStreamData | null | undefined
|
||||
currentSession: Session | null
|
||||
focusMeeting: Meeting
|
||||
}) {
|
||||
const sessionName =
|
||||
liveData?.Session?.SessionName ?? currentSession?.session_name ?? 'Live session'
|
||||
const trackStatus = trackStatusInfo(liveData?.TrackStatus)
|
||||
const topThree = sortLiveTimingRows(liveData).filter((r) => r.Position > 0).slice(0, 3)
|
||||
const decal = countryDecal(focusMeeting)
|
||||
|
||||
return (
|
||||
<>
|
||||
<div className="hero-row">
|
||||
<span className="hero-decal mono">{decal}</span>
|
||||
<div className="hero-identity">
|
||||
<div className="hero-eyebrow hero-eyebrow--live mono">● Live now</div>
|
||||
<h1 className="hero-title">{sessionName}</h1>
|
||||
<div className="hero-sub mono">
|
||||
{[focusMeeting.meeting_name, focusMeeting.circuit_short_name].filter(Boolean).join(' · ')}
|
||||
</div>
|
||||
<div className={`hero-track-status hero-track-status--${trackStatus.key}`}>
|
||||
{trackStatus.label}
|
||||
</div>
|
||||
</div>
|
||||
{topThree.length > 0 && (
|
||||
<div className="hero-timing" data-testid="hero-live-timing">
|
||||
{topThree.map((row) => (
|
||||
<div key={row.RacingNumber} className="hero-timing-row">
|
||||
<span className={`hero-timing-pos hero-timing-pos--p${row.Position}`}>
|
||||
P{row.Position}
|
||||
</span>
|
||||
<span className="hero-timing-driver">
|
||||
<span
|
||||
className="hero-timing-bar"
|
||||
style={{ background: `#${row.Info?.TeamColour ?? '9aa0a6'}` }}
|
||||
/>
|
||||
{row.Info?.Tla ?? row.RacingNumber}
|
||||
</span>
|
||||
<span className="hero-timing-gap">
|
||||
{row.Position === 1 ? 'LEAD' : row.Driver.Interval || row.Driver.GapToLeader || '—'}
|
||||
</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
)}
|
||||
<div className="hero-countdown">
|
||||
<div className="hero-cd-label mono">{liveActive ? 'SignalR' : 'On track'}</div>
|
||||
<div className="hero-cd-value hero-cd-value--live mono">LIVE</div>
|
||||
<div className="hero-cd-sub mono">{sessionName}</div>
|
||||
</div>
|
||||
</div>
|
||||
<div className="hero-actions">
|
||||
<Link to="/live" className="hero-cta hero-cta--primary" data-testid="hero-live-link">
|
||||
Open Live Timing <ArrowRight size={16} />
|
||||
</Link>
|
||||
</div>
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
function UpcomingHero({
|
||||
now,
|
||||
focusMeeting,
|
||||
focusKind,
|
||||
sessions,
|
||||
currentSession,
|
||||
nextSession,
|
||||
liveActive,
|
||||
analysisSessionKey,
|
||||
analysisSessionName,
|
||||
}: {
|
||||
now: Date
|
||||
focusMeeting: Meeting
|
||||
focusKind: FocusMeetingKind
|
||||
sessions: WeekendSession[]
|
||||
currentSession: Session | null
|
||||
nextSession: Session | null
|
||||
liveActive: boolean
|
||||
analysisSessionKey?: number
|
||||
analysisSessionName?: string
|
||||
}) {
|
||||
const decal = countryDecal(focusMeeting)
|
||||
const countdownTarget =
|
||||
nextSession && sessionStartTime(nextSession)
|
||||
? sessionStartTime(nextSession)!
|
||||
: meetingStartTime(focusMeeting)
|
||||
|
||||
const kindLabel =
|
||||
focusKind === 'current'
|
||||
? 'Current weekend'
|
||||
: focusKind === 'next'
|
||||
? 'Next weekend'
|
||||
: 'Weekend'
|
||||
|
||||
const sortedSessions = [...sessions].sort((a, b) => {
|
||||
const left = sessionStartTime(a.session)?.getTime() ?? 0
|
||||
const right = sessionStartTime(b.session)?.getTime() ?? 0
|
||||
return left - right
|
||||
})
|
||||
|
||||
return (
|
||||
<>
|
||||
<div className="hero-row">
|
||||
<span className="hero-decal mono">{decal}</span>
|
||||
<div className="hero-identity">
|
||||
<div className="hero-eyebrow mono">{kindLabel}</div>
|
||||
<h1 className="hero-title">{focusMeeting.meeting_name}</h1>
|
||||
<div className="hero-sub mono">
|
||||
{[focusMeeting.location, focusMeeting.circuit_short_name].filter(Boolean).join(' · ')}
|
||||
</div>
|
||||
<div className="hero-sub mono">{formatGpDateRange(focusMeeting)}</div>
|
||||
</div>
|
||||
<div className="hero-countdown" data-testid="hero-countdown">
|
||||
{nextSession ? (
|
||||
<>
|
||||
<div className="hero-cd-label mono">Next · {nextSession.session_name}</div>
|
||||
{countdownTarget && (
|
||||
<div className="hero-cd-value mono">{formatCountdown(countdownTarget, now)}</div>
|
||||
)}
|
||||
<div className="hero-cd-sub mono">{formatSessionScheduleTime(nextSession.date_start)}</div>
|
||||
</>
|
||||
) : (
|
||||
<>
|
||||
<div className="hero-cd-label mono">Status</div>
|
||||
<div className="hero-cd-value mono">Complete</div>
|
||||
<div className="hero-cd-sub mono">Weekend finished</div>
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{sortedSessions.length > 0 && (
|
||||
<div className="hero-schedule-strip" data-testid="hero-schedule-strip" role="list">
|
||||
{sortedSessions.map(({ session }) => {
|
||||
const status = classifySessionStatus(session, now)
|
||||
const isNext = nextSession?.session_key === session.session_key
|
||||
const isCurrent = currentSession?.session_key === session.session_key
|
||||
const isLive = isCurrent && liveActive
|
||||
return (
|
||||
<Link
|
||||
key={session.session_key}
|
||||
to="/race-hub"
|
||||
search={{ session_key: session.session_key }}
|
||||
className={`hero-schedule-card${isNext ? ' is-next' : ''}${
|
||||
status === 'done' ? ' is-done' : ''
|
||||
}${isLive ? ' is-live' : ''}`}
|
||||
role="listitem"
|
||||
>
|
||||
<div className="hero-schedule-abbrev mono">
|
||||
{sessionTypeAbbrev(session.session_type, session.session_name)}
|
||||
</div>
|
||||
<div className="hero-schedule-name">{session.session_name}</div>
|
||||
<div className="hero-schedule-time mono">
|
||||
{formatSessionScheduleTime(session.date_start)}
|
||||
</div>
|
||||
<div
|
||||
className={`hero-schedule-marker mono${
|
||||
isLive ? ' hero-schedule-marker--live' : isNext ? ' hero-schedule-marker--next' : ''
|
||||
}`}
|
||||
>
|
||||
{isCurrent ? 'On track' : status === 'done' ? 'Done' : isNext ? 'Next' : 'Upcoming'}
|
||||
</div>
|
||||
</Link>
|
||||
)
|
||||
})}
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className="hero-actions">
|
||||
<Link
|
||||
to="/live"
|
||||
className="hero-secondary-link"
|
||||
style={{ display: 'inline-flex', alignItems: 'center', gap: '6px' }}
|
||||
>
|
||||
<Play size={14} /> Watch Live
|
||||
</Link>
|
||||
{analysisSessionKey != null && (
|
||||
<Link
|
||||
to="/race-hub"
|
||||
search={{ session_key: analysisSessionKey }}
|
||||
className="hero-secondary-link"
|
||||
data-testid="hero-analysis-link"
|
||||
style={{ display: 'inline-flex', alignItems: 'center', gap: '6px' }}
|
||||
>
|
||||
<Activity size={14} /> Open Analysis
|
||||
{analysisSessionName ? ` · ${analysisSessionName}` : ''}
|
||||
</Link>
|
||||
)}
|
||||
</div>
|
||||
</>
|
||||
)
|
||||
}
|
||||
|
||||
function BetweenHero({
|
||||
now,
|
||||
lastRaceName,
|
||||
lastRacePodium,
|
||||
lastRaceSessionKey,
|
||||
nextMeeting,
|
||||
analysisSessionKey,
|
||||
analysisSessionName,
|
||||
}: {
|
||||
now: Date
|
||||
lastRaceName: string
|
||||
lastRacePodium: EnrichedResult[]
|
||||
lastRaceSessionKey?: number
|
||||
nextMeeting: Meeting | null
|
||||
analysisSessionKey?: number
|
||||
analysisSessionName?: string
|
||||
}) {
|
||||
const nextStart = nextMeeting ? meetingStartTime(nextMeeting) : null
|
||||
const podium = lastRacePodium
|
||||
.filter((r) => r.position >= 1 && r.position <= 3)
|
||||
.sort((a, b) => a.position - b.position)
|
||||
|
||||
return (
|
||||
<>
|
||||
<div className="hero-row">
|
||||
<div className="hero-identity">
|
||||
<div className="hero-eyebrow mono">Between race weekends</div>
|
||||
{lastRaceName && (
|
||||
<h1 className="hero-title" data-testid="hero-last-race">
|
||||
After {lastRaceName}
|
||||
</h1>
|
||||
)}
|
||||
{!lastRaceName && <h1 className="hero-title">Season pause</h1>}
|
||||
</div>
|
||||
|
||||
{podium.length > 0 && (
|
||||
<div className="hero-podium" data-testid="hero-podium">
|
||||
{podium.map((r) => (
|
||||
<div key={r.driver_number} className="hero-podium-row">
|
||||
<span className={`hero-podium-pos hero-podium-pos--p${r.position} mono`}>
|
||||
P{r.position}
|
||||
</span>
|
||||
<span className="hero-podium-driver">
|
||||
<span
|
||||
className="hero-timing-bar"
|
||||
style={{ background: `#${r.team_colour}` }}
|
||||
/>
|
||||
{r.name_acronym}
|
||||
</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
)}
|
||||
|
||||
{nextMeeting && (
|
||||
<div className="hero-countdown" data-testid="hero-next-gp-countdown">
|
||||
<div className="hero-between-next">
|
||||
{countryFlag(nextMeeting) && (
|
||||
<span className="hero-flag" aria-hidden="true">
|
||||
{countryFlag(nextMeeting)}
|
||||
</span>
|
||||
)}
|
||||
<div>
|
||||
<div className="hero-cd-label mono">Next GP</div>
|
||||
<div className="hero-title" style={{ fontSize: '20px' }}>
|
||||
{nextMeeting.meeting_name}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{nextStart && (
|
||||
<>
|
||||
<div className="hero-cd-value mono" style={{ marginTop: 'var(--s3)' }}>
|
||||
{formatCountdown(nextStart, now)}
|
||||
</div>
|
||||
<div className="hero-cd-sub mono">{formatGpDateRange(nextMeeting)}</div>
|
||||
</>
|
||||
)}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
|
||||
<div className="hero-actions">
|
||||
{lastRaceSessionKey != null && (
|
||||
<Link
|
||||
to="/race-hub"
|
||||
search={{ session_key: lastRaceSessionKey }}
|
||||
className="hero-secondary-link"
|
||||
data-testid="hero-last-race-link"
|
||||
>
|
||||
View {lastRaceName || 'last race'} results →
|
||||
</Link>
|
||||
)}
|
||||
{analysisSessionKey != null && analysisSessionKey !== lastRaceSessionKey && (
|
||||
<Link
|
||||
to="/race-hub"
|
||||
search={{ session_key: analysisSessionKey }}
|
||||
className="hero-secondary-link"
|
||||
data-testid="hero-analysis-link"
|
||||
>
|
||||
Open Analysis{analysisSessionName ? ` · ${analysisSessionName}` : ''}
|
||||
</Link>
|
||||
)}
|
||||
<Link to="/live" className="hero-secondary-link">
|
||||
Live Timing →
|
||||
</Link>
|
||||
</div>
|
||||
</>
|
||||
)
|
||||
}
|
||||
27
frontend/src/lib/hero.ts
Normal file
27
frontend/src/lib/hero.ts
Normal file
@@ -0,0 +1,27 @@
|
||||
import type { Session } from '../types'
|
||||
import { sessionEndTime, sessionStartTime, type FocusMeetingKind } from './schedule'
|
||||
|
||||
export type HeroStateKind = 'live' | 'upcoming' | 'between'
|
||||
|
||||
export interface HeroStateInputs {
|
||||
now: Date
|
||||
liveActive: boolean
|
||||
currentSession: Session | null
|
||||
focusKind: FocusMeetingKind | null
|
||||
}
|
||||
|
||||
export function classifySessionStatus(session: Session, now: Date): 'live' | 'done' | 'upcoming' {
|
||||
const start = sessionStartTime(session)
|
||||
const end = sessionEndTime(session)
|
||||
if (start && end && now >= start && now < end) return 'live'
|
||||
if (start && now >= start) return 'done'
|
||||
return 'upcoming'
|
||||
}
|
||||
|
||||
export function heroState(inputs: HeroStateInputs): HeroStateKind {
|
||||
const { liveActive, currentSession, focusKind } = inputs
|
||||
|
||||
if (liveActive || currentSession) return 'live'
|
||||
if (focusKind === 'current') return 'upcoming'
|
||||
return 'between'
|
||||
}
|
||||
@@ -1,38 +1,38 @@
|
||||
import { useEffect, useMemo, useState } from 'react'
|
||||
import { useQueries, useQuery } from '@tanstack/react-query'
|
||||
import { Link } from '@tanstack/react-router'
|
||||
import { fetchLiveState, fetchLocalMeetings, fetchSeasonMeetings, fetchSeasons, fetchSessions, fetchWeekend, fetchChampionshipHub } from '../api'
|
||||
import {
|
||||
fetchChampionshipHub,
|
||||
fetchLiveState,
|
||||
fetchLocalMeetings,
|
||||
fetchRaceHub,
|
||||
fetchSeasonMeetings,
|
||||
fetchSeasons,
|
||||
fetchSessions,
|
||||
fetchWeekend,
|
||||
} from '../api'
|
||||
import { CommandCenterHero } from '../components/CommandCenterHero'
|
||||
import { PaddockBriefing } from '../components/PaddockBriefing'
|
||||
import { RACE_HUB_DATASETS, countWeekendStats, formatCoverageHint, sessionTypeAbbrev } from '../lib/coverage'
|
||||
import { countryAccent, countryDecal, countryFlag, formatGpDateRange } from '../lib/gpIdentity'
|
||||
import { classifySessionStatus, heroState } from '../lib/hero'
|
||||
import {
|
||||
currentAndNextSession,
|
||||
focusMeetingKind,
|
||||
formatCountdown,
|
||||
formatSessionScheduleTime,
|
||||
meetingHasStarted,
|
||||
mostRecentPastMeeting,
|
||||
nextUpcomingMeeting,
|
||||
pickFocusMeeting,
|
||||
sessionEndTime,
|
||||
sessionStartTime,
|
||||
sortSessionsByStart,
|
||||
} from '../lib/schedule'
|
||||
import { countryAccent, countryDecal, countryFlag, formatGpDateRange } from '../lib/gpIdentity'
|
||||
import type { Meeting, Session, Weekend, WeekendSession } from '../types'
|
||||
import { PaddockBriefing } from '../components/PaddockBriefing'
|
||||
import { Play, Activity, Calendar, Trophy } from 'lucide-react'
|
||||
|
||||
type WeekendStatusKind = 'live' | 'current' | 'next' | 'recent' | 'fallback'
|
||||
import { Trophy } from 'lucide-react'
|
||||
|
||||
const missingDatasets = Object.fromEntries(
|
||||
RACE_HUB_DATASETS.map((dataset) => [dataset, { status: 'missing', source: 'none', count: 0 }]),
|
||||
) as WeekendSession['datasets']
|
||||
|
||||
function classifySessionStatus(session: Session, now: Date): 'live' | 'done' | 'upcoming' {
|
||||
const start = sessionStartTime(session)
|
||||
const end = sessionEndTime(session)
|
||||
if (start && end && now >= start && now < end) return 'live'
|
||||
if (start && now >= start) return 'done'
|
||||
return 'upcoming'
|
||||
}
|
||||
|
||||
function meetingStatus(meeting: Meeting, focusKey: number | undefined, now: Date) {
|
||||
if (meeting.meeting_key === focusKey) return 'focus'
|
||||
if (meetingHasStarted(meeting, now)) return 'past'
|
||||
@@ -148,7 +148,36 @@ export function CommandCenterPage() {
|
||||
focusWeekendSessions[0]?.session
|
||||
const analysisSessionKey = actionSession?.session_key
|
||||
|
||||
const weekendsLoading = weekendQueries.some((q) => q.isLoading)
|
||||
const liveActive = liveQuery.data?.is_live === true
|
||||
const heroStateKind = heroState({
|
||||
now: nowDate,
|
||||
liveActive,
|
||||
currentSession,
|
||||
focusKind,
|
||||
})
|
||||
|
||||
const lastPastMeeting = useMemo(
|
||||
() => mostRecentPastMeeting(focusMeetings, nowDate),
|
||||
[focusMeetings, nowDate],
|
||||
)
|
||||
const lastPastWeekend = lastPastMeeting ? weekendsByKey.get(lastPastMeeting.meeting_key) : undefined
|
||||
const lastRaceAnalysis = pickAnalysisSession(lastPastWeekend)
|
||||
const lastRaceSessionKey = lastRaceAnalysis?.session.session_key
|
||||
|
||||
const lastRaceHubQuery = useQuery({
|
||||
queryKey: ['race-hub', lastRaceSessionKey, 'hero-podium'],
|
||||
queryFn: () => fetchRaceHub(lastRaceSessionKey!),
|
||||
enabled: lastRaceSessionKey != null && heroStateKind === 'between',
|
||||
staleTime: 60_000,
|
||||
})
|
||||
|
||||
const nextMeetingForHero = useMemo(() => {
|
||||
if (heroStateKind !== 'between') return null
|
||||
return nextUpcomingMeeting(focusMeetings, nowDate)
|
||||
}, [heroStateKind, focusMeetings, nowDate])
|
||||
|
||||
const lastRacePodium = lastRaceHubQuery.data?.results ?? []
|
||||
const lastRaceName = champHub?.last_race ?? lastPastMeeting?.meeting_name ?? ''
|
||||
|
||||
if (seasonsQuery.isLoading) {
|
||||
return <div className="page loading-state">loading command center…</div>
|
||||
@@ -189,19 +218,7 @@ export function CommandCenterPage() {
|
||||
)
|
||||
}
|
||||
|
||||
const liveActive = liveQuery.data?.is_live === true
|
||||
const statusKind: WeekendStatusKind = liveActive
|
||||
? 'live'
|
||||
: focusKind === 'current'
|
||||
? 'current'
|
||||
: focusKind === 'next'
|
||||
? 'next'
|
||||
: focusKind === 'recent'
|
||||
? 'recent'
|
||||
: 'fallback'
|
||||
|
||||
const accent = countryAccent(focusMeeting ?? null)
|
||||
const decal = countryDecal(focusMeeting ?? null)
|
||||
const accentStyle = { '--gp-accent': accent } as React.CSSProperties
|
||||
|
||||
return (
|
||||
@@ -224,76 +241,25 @@ export function CommandCenterPage() {
|
||||
</div>
|
||||
)}
|
||||
|
||||
{focusMeeting && (
|
||||
<div className="cc-hero">
|
||||
<section className="cc-weekend-band ui-card glass-panel" data-testid="cc-focus">
|
||||
<div className="cc-band-accent" aria-hidden="true" />
|
||||
<div className="cc-band-body">
|
||||
<div className="cc-band-row">
|
||||
<span className="cc-band-decal mono">{decal}</span>
|
||||
<div className="cc-band-titles">
|
||||
<div className="cc-band-eyebrow mono">
|
||||
<WeekendKindLabel kind={statusKind} />
|
||||
</div>
|
||||
<h1 className="cc-band-name">{focusMeeting.meeting_name}</h1>
|
||||
<div className="cc-band-sub mono">
|
||||
{[focusMeeting.location, focusMeeting.circuit_short_name]
|
||||
.filter(Boolean)
|
||||
.join(' · ')}
|
||||
</div>
|
||||
<div className="cc-band-sub mono cc-band-dates">{formatGpDateRange(focusMeeting)}</div>
|
||||
</div>
|
||||
<CountdownBlock
|
||||
{focusMeeting && focusKind && (
|
||||
<CommandCenterHero
|
||||
state={heroStateKind}
|
||||
now={nowDate}
|
||||
accent={accent}
|
||||
liveActive={liveActive}
|
||||
liveData={liveQuery.data?.data}
|
||||
focusMeeting={focusMeeting}
|
||||
focusKind={focusKind}
|
||||
sessions={focusWeekendSessions}
|
||||
currentSession={currentSession}
|
||||
nextSession={nextSession}
|
||||
meeting={focusMeeting}
|
||||
now={nowDate}
|
||||
analysisSessionKey={analysisSessionKey}
|
||||
analysisSessionName={actionSession?.session_name}
|
||||
lastRaceName={lastRaceName}
|
||||
lastRacePodium={lastRacePodium}
|
||||
lastRaceSessionKey={lastRaceSessionKey}
|
||||
nextMeeting={nextMeetingForHero}
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div className="cc-actions-row" data-testid="cc-actions">
|
||||
<Link
|
||||
to="/live"
|
||||
className={`cc-pri-action ui-card interactive ${liveActive ? 'is-live ui-cta-primary' : ''}`}
|
||||
data-testid="cc-action-live"
|
||||
>
|
||||
<span className="cc-pri-label" style={{ display: 'flex', alignItems: 'center', gap: '8px' }}><Play size={16} /> Watch Live</span>
|
||||
<span className="cc-pri-meta mono">{liveActive ? 'Feed active' : 'Standby'}</span>
|
||||
</Link>
|
||||
<Link
|
||||
to="/race-hub"
|
||||
search={analysisSessionKey ? { session_key: analysisSessionKey } : {}}
|
||||
className="cc-pri-action ui-card interactive"
|
||||
data-testid="cc-action-race-hub"
|
||||
>
|
||||
<span className="cc-pri-label" style={{ display: 'flex', alignItems: 'center', gap: '8px' }}><Activity size={16} /> Open Analysis</span>
|
||||
<span className="cc-pri-meta mono">
|
||||
{actionSession
|
||||
? `${actionSession.session_name} · session ${actionSession.session_key}`
|
||||
: 'Pick a session'}
|
||||
</span>
|
||||
</Link>
|
||||
{nextSession && sessionStartTime(nextSession) && (
|
||||
<a
|
||||
href="#cc-schedule"
|
||||
className="cc-pri-action ui-card interactive"
|
||||
data-testid="cc-action-schedule"
|
||||
onClick={(e) => {
|
||||
e.preventDefault()
|
||||
document.getElementById('cc-schedule')?.scrollIntoView({ behavior: 'smooth' })
|
||||
}}
|
||||
>
|
||||
<span className="cc-pri-label" style={{ display: 'flex', alignItems: 'center', gap: '8px' }}><Calendar size={16} /> Schedule</span>
|
||||
<span className="cc-pri-meta mono">
|
||||
next: {nextSession.session_name}
|
||||
</span>
|
||||
</a>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className="cc-dashboard-grid">
|
||||
@@ -483,65 +449,3 @@ function FormSparkline({ form, color }: { form: number[], color: string }) {
|
||||
)
|
||||
}
|
||||
|
||||
function WeekendKindLabel({ kind }: { kind: WeekendStatusKind }) {
|
||||
switch (kind) {
|
||||
case 'live':
|
||||
return <span className="cc-kind cc-kind-live">● Live now</span>
|
||||
case 'current':
|
||||
return <span className="cc-kind cc-kind-current">Current weekend</span>
|
||||
case 'next':
|
||||
return <span className="cc-kind cc-kind-next">Next weekend</span>
|
||||
case 'recent':
|
||||
return <span className="cc-kind cc-kind-recent">Recent weekend</span>
|
||||
default:
|
||||
return <span className="cc-kind">Weekend</span>
|
||||
}
|
||||
}
|
||||
|
||||
interface CountdownBlockProps {
|
||||
liveActive: boolean
|
||||
currentSession: Session | null
|
||||
nextSession: Session | null
|
||||
meeting: Meeting
|
||||
now: Date
|
||||
}
|
||||
|
||||
function CountdownBlock({ liveActive, currentSession, nextSession, meeting, now }: CountdownBlockProps) {
|
||||
if (liveActive) {
|
||||
return (
|
||||
<div className="cc-countdown-block">
|
||||
<div className="cc-cd-label mono">SignalR</div>
|
||||
<div className="cc-cd-value cc-cd-live">LIVE</div>
|
||||
<div className="cc-cd-sub mono">{currentSession?.session_name ?? 'Feed connected'}</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
if (currentSession) {
|
||||
return (
|
||||
<div className="cc-countdown-block">
|
||||
<div className="cc-cd-label mono">On Track</div>
|
||||
<div className="cc-cd-value cc-cd-current">{currentSession.session_name}</div>
|
||||
<div className="cc-cd-sub mono">In session</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
if (nextSession && sessionStartTime(nextSession)) {
|
||||
return (
|
||||
<div className="cc-countdown-block">
|
||||
<div className="cc-cd-label mono">Next · {nextSession.session_name}</div>
|
||||
<div className="cc-cd-value mono">{formatCountdown(sessionStartTime(nextSession)!, now)}</div>
|
||||
<div className="cc-cd-sub mono">{formatSessionScheduleTime(nextSession.date_start)}</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
if (meetingHasStarted(meeting, now)) {
|
||||
return (
|
||||
<div className="cc-countdown-block">
|
||||
<div className="cc-cd-label mono">Status</div>
|
||||
<div className="cc-cd-value cc-cd-done">Complete</div>
|
||||
<div className="cc-cd-sub mono">Weekend finished</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
373
frontend/src/styles/hero.css
Normal file
373
frontend/src/styles/hero.css
Normal file
@@ -0,0 +1,373 @@
|
||||
.hero-panel {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--s4);
|
||||
}
|
||||
|
||||
.hero-card {
|
||||
display: flex;
|
||||
background: var(--surface);
|
||||
border: 1px solid rgba(255, 255, 255, 0.08);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
min-height: 124px;
|
||||
}
|
||||
|
||||
.hero-accent {
|
||||
width: 4px;
|
||||
flex-shrink: 0;
|
||||
box-shadow: 0 0 12px var(--hero-accent, var(--gp-accent));
|
||||
background: var(--hero-accent, var(--gp-accent));
|
||||
}
|
||||
|
||||
.hero-accent--live {
|
||||
animation: hero-pulse 1.4s ease-in-out infinite;
|
||||
}
|
||||
|
||||
@keyframes hero-pulse {
|
||||
0%, 100% { opacity: 1; }
|
||||
50% { opacity: 0.55; }
|
||||
}
|
||||
|
||||
.hero-body {
|
||||
flex: 1;
|
||||
padding: var(--s5);
|
||||
min-width: 0;
|
||||
position: relative;
|
||||
overflow: hidden;
|
||||
background:
|
||||
radial-gradient(ellipse at top right, color-mix(in srgb, var(--gp-accent) 15%, transparent), transparent 60%),
|
||||
linear-gradient(to right, rgba(255, 255, 255, 0.03) 1px, transparent 1px),
|
||||
linear-gradient(to bottom, rgba(255, 255, 255, 0.03) 1px, transparent 1px),
|
||||
var(--surface);
|
||||
background-size: 100% 100%, 20px 20px, 20px 20px, 100% 100%;
|
||||
}
|
||||
|
||||
.hero-body::after {
|
||||
content: "";
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
background: linear-gradient(90deg, transparent 0%, rgba(0, 0, 0, 0.3) 100%);
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.hero-inner {
|
||||
position: relative;
|
||||
z-index: 1;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--s5);
|
||||
}
|
||||
|
||||
.hero-row {
|
||||
display: flex;
|
||||
align-items: stretch;
|
||||
gap: var(--s6);
|
||||
min-width: 0;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.hero-identity {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.hero-decal {
|
||||
font-size: 56px;
|
||||
font-weight: 800;
|
||||
line-height: 0.85;
|
||||
letter-spacing: -0.04em;
|
||||
color: color-mix(in srgb, var(--gp-accent) 35%, var(--text-3));
|
||||
opacity: 0.9;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.hero-eyebrow {
|
||||
font-size: 10px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.14em;
|
||||
text-transform: uppercase;
|
||||
color: var(--text-3);
|
||||
margin-bottom: var(--s2);
|
||||
}
|
||||
|
||||
.hero-eyebrow--live {
|
||||
color: var(--red);
|
||||
}
|
||||
|
||||
.hero-title {
|
||||
font-size: 28px;
|
||||
font-weight: 800;
|
||||
letter-spacing: -0.02em;
|
||||
line-height: 1.1;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.hero-sub {
|
||||
font-size: 12px;
|
||||
color: var(--text-2);
|
||||
margin-top: var(--s2);
|
||||
}
|
||||
|
||||
.hero-countdown {
|
||||
text-align: right;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.hero-cd-label {
|
||||
font-size: 10px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.12em;
|
||||
text-transform: uppercase;
|
||||
color: var(--text-3);
|
||||
margin-bottom: var(--s2);
|
||||
}
|
||||
|
||||
.hero-cd-value {
|
||||
font-size: 22px;
|
||||
font-weight: 700;
|
||||
font-variant-numeric: tabular-nums;
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.hero-cd-value--live {
|
||||
color: var(--red);
|
||||
font-size: 28px;
|
||||
letter-spacing: 0.08em;
|
||||
}
|
||||
|
||||
.hero-cd-sub {
|
||||
font-size: 11px;
|
||||
color: var(--text-3);
|
||||
margin-top: var(--s2);
|
||||
}
|
||||
|
||||
.hero-track-status {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: var(--s3);
|
||||
font-size: 10px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.12em;
|
||||
text-transform: uppercase;
|
||||
padding: var(--s2) var(--s3);
|
||||
border-radius: 4px;
|
||||
margin-top: var(--s3);
|
||||
}
|
||||
|
||||
.hero-track-status--green { color: #3dd68c; background: rgba(61, 214, 140, 0.1); }
|
||||
.hero-track-status--yellow { color: #f5c842; background: rgba(245, 200, 66, 0.1); }
|
||||
.hero-track-status--sc,
|
||||
.hero-track-status--vsc { color: #f5a623; background: rgba(245, 166, 35, 0.12); }
|
||||
.hero-track-status--red { color: var(--red); background: rgba(225, 6, 0, 0.12); }
|
||||
.hero-track-status--unknown { color: var(--text-3); background: rgba(255, 255, 255, 0.05); }
|
||||
|
||||
.hero-timing {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--s2);
|
||||
min-width: 200px;
|
||||
}
|
||||
|
||||
.hero-timing-row {
|
||||
display: grid;
|
||||
grid-template-columns: 28px 1fr auto;
|
||||
align-items: center;
|
||||
gap: var(--s3);
|
||||
padding: var(--s2) var(--s3);
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
border-radius: 6px;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.hero-timing-pos {
|
||||
font-weight: 700;
|
||||
color: var(--text-3);
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
|
||||
.hero-timing-pos--p1 { color: #ffd700; }
|
||||
.hero-timing-pos--p2 { color: #c0c0c0; }
|
||||
.hero-timing-pos--p3 { color: #cd7f32; }
|
||||
|
||||
.hero-timing-bar {
|
||||
width: 3px;
|
||||
height: 14px;
|
||||
border-radius: 2px;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.hero-timing-driver {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: var(--s3);
|
||||
font-weight: 600;
|
||||
font-family: var(--f-mono);
|
||||
}
|
||||
|
||||
.hero-timing-gap {
|
||||
font-size: 11px;
|
||||
color: var(--text-3);
|
||||
font-family: var(--f-mono);
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
|
||||
.hero-cta {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: var(--s3);
|
||||
font-size: 14px;
|
||||
font-weight: 700;
|
||||
color: var(--red);
|
||||
text-decoration: none;
|
||||
transition: opacity 0.1s;
|
||||
}
|
||||
|
||||
.hero-cta:hover {
|
||||
opacity: 0.85;
|
||||
}
|
||||
|
||||
.hero-cta--primary {
|
||||
padding: var(--s3) var(--s5);
|
||||
background: rgba(225, 6, 0, 0.12);
|
||||
border: 1px solid rgba(225, 6, 0, 0.35);
|
||||
border-radius: 6px;
|
||||
}
|
||||
|
||||
.hero-actions {
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: var(--s3);
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.hero-secondary-link {
|
||||
font-size: 12px;
|
||||
font-weight: 600;
|
||||
color: var(--text-2);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.hero-secondary-link:hover {
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.hero-schedule-strip {
|
||||
display: flex;
|
||||
gap: var(--s3);
|
||||
overflow-x: auto;
|
||||
padding-bottom: var(--s2);
|
||||
}
|
||||
|
||||
.hero-schedule-card {
|
||||
flex: 0 0 auto;
|
||||
min-width: 120px;
|
||||
padding: var(--s3) var(--s4);
|
||||
border-radius: 6px;
|
||||
border: 1px solid rgba(255, 255, 255, 0.06);
|
||||
background: rgba(255, 255, 255, 0.02);
|
||||
text-decoration: none;
|
||||
color: inherit;
|
||||
transition: background 0.1s, border-color 0.1s;
|
||||
}
|
||||
|
||||
.hero-schedule-card:hover {
|
||||
background: rgba(255, 255, 255, 0.05);
|
||||
}
|
||||
|
||||
.hero-schedule-card.is-next {
|
||||
border-color: color-mix(in srgb, var(--gp-accent) 50%, transparent);
|
||||
background: color-mix(in srgb, var(--gp-accent) 8%, transparent);
|
||||
}
|
||||
|
||||
.hero-schedule-card.is-done {
|
||||
opacity: 0.55;
|
||||
}
|
||||
|
||||
.hero-schedule-card.is-live {
|
||||
border-color: rgba(225, 6, 0, 0.4);
|
||||
background: rgba(225, 6, 0, 0.08);
|
||||
}
|
||||
|
||||
.hero-schedule-abbrev {
|
||||
font-size: 10px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.1em;
|
||||
color: var(--text-3);
|
||||
}
|
||||
|
||||
.hero-schedule-name {
|
||||
font-size: 12px;
|
||||
font-weight: 600;
|
||||
margin: var(--s2) 0;
|
||||
}
|
||||
|
||||
.hero-schedule-time {
|
||||
font-size: 10px;
|
||||
color: var(--text-3);
|
||||
}
|
||||
|
||||
.hero-schedule-marker {
|
||||
font-size: 9px;
|
||||
font-weight: 700;
|
||||
letter-spacing: 0.1em;
|
||||
text-transform: uppercase;
|
||||
margin-top: var(--s2);
|
||||
color: var(--text-3);
|
||||
}
|
||||
|
||||
.hero-schedule-marker--next { color: var(--gp-accent); }
|
||||
.hero-schedule-marker--live { color: var(--red); }
|
||||
|
||||
.hero-podium {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--s2);
|
||||
min-width: 200px;
|
||||
}
|
||||
|
||||
.hero-podium-row {
|
||||
display: grid;
|
||||
grid-template-columns: 32px 1fr;
|
||||
align-items: center;
|
||||
gap: var(--s3);
|
||||
padding: var(--s2) var(--s3);
|
||||
background: rgba(255, 255, 255, 0.03);
|
||||
border-radius: 6px;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.hero-podium-pos {
|
||||
font-weight: 700;
|
||||
font-family: var(--f-mono);
|
||||
color: var(--text-3);
|
||||
}
|
||||
|
||||
.hero-podium-pos--p1 { color: #ffd700; }
|
||||
.hero-podium-pos--p2 { color: #c0c0c0; }
|
||||
.hero-podium-pos--p3 { color: #cd7f32; }
|
||||
|
||||
.hero-podium-driver {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: var(--s3);
|
||||
font-weight: 600;
|
||||
font-family: var(--f-mono);
|
||||
}
|
||||
|
||||
.hero-between-next {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: var(--s4);
|
||||
}
|
||||
|
||||
.hero-flag {
|
||||
font-size: 32px;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
@media (min-width: 700px) {
|
||||
.hero-row {
|
||||
flex-wrap: nowrap;
|
||||
}
|
||||
}
|
||||
@@ -12,9 +12,20 @@ vi.mock('../api', () => ({
|
||||
fetchSessions: vi.fn(),
|
||||
fetchWeekend: vi.fn(),
|
||||
fetchLiveState: vi.fn(),
|
||||
fetchChampionshipHub: vi.fn(),
|
||||
fetchRaceHub: vi.fn(),
|
||||
}))
|
||||
|
||||
import { fetchSeasons, fetchLocalMeetings, fetchSeasonMeetings, fetchSessions, fetchWeekend, fetchLiveState } from '../api'
|
||||
import {
|
||||
fetchSeasons,
|
||||
fetchLocalMeetings,
|
||||
fetchSeasonMeetings,
|
||||
fetchSessions,
|
||||
fetchWeekend,
|
||||
fetchLiveState,
|
||||
fetchChampionshipHub,
|
||||
fetchRaceHub,
|
||||
} from '../api'
|
||||
|
||||
const mockFetchSeasons = vi.mocked(fetchSeasons)
|
||||
const mockFetchLocalMeetings = vi.mocked(fetchLocalMeetings)
|
||||
@@ -22,6 +33,8 @@ const mockFetchSeasonMeetings = vi.mocked(fetchSeasonMeetings)
|
||||
const mockFetchSessions = vi.mocked(fetchSessions)
|
||||
const mockFetchWeekend = vi.mocked(fetchWeekend)
|
||||
const mockFetchLiveState = vi.mocked(fetchLiveState)
|
||||
const mockFetchChampionshipHub = vi.mocked(fetchChampionshipHub)
|
||||
const mockFetchRaceHub = vi.mocked(fetchRaceHub)
|
||||
|
||||
const meeting: Meeting = {
|
||||
meeting_key: 1229,
|
||||
@@ -102,6 +115,48 @@ describe('CommandCenterPage', () => {
|
||||
vi.clearAllMocks()
|
||||
mockFetchLiveState.mockResolvedValue({ is_live: false, data: null })
|
||||
mockFetchSessions.mockResolvedValue([])
|
||||
mockFetchChampionshipHub.mockResolvedValue({
|
||||
season: 2025,
|
||||
round: 1,
|
||||
total_rounds: 1,
|
||||
rounds_left: 0,
|
||||
last_race: 'Monaco',
|
||||
round_labels: ['R1'],
|
||||
drivers: [],
|
||||
teams: [],
|
||||
})
|
||||
mockFetchRaceHub.mockResolvedValue({
|
||||
source: 'local',
|
||||
session_key: 9472,
|
||||
datasets: fullDatasets,
|
||||
results: [
|
||||
{
|
||||
driver_number: 1,
|
||||
position: 1,
|
||||
name_acronym: 'VER',
|
||||
full_name: 'Max Verstappen',
|
||||
team_name: 'Red Bull Racing',
|
||||
team_colour: '3671c6',
|
||||
dnf: false,
|
||||
dns: false,
|
||||
dsq: false,
|
||||
duration: 7200,
|
||||
gap_to_leader: null,
|
||||
number_of_laps: 78,
|
||||
points: 25,
|
||||
session_key: 9472,
|
||||
meeting_key: 1229,
|
||||
},
|
||||
],
|
||||
starting_grid: [],
|
||||
drivers: [],
|
||||
stints: [],
|
||||
pit_stops: [],
|
||||
positions: [],
|
||||
race_control: [],
|
||||
weather: [],
|
||||
laps: [],
|
||||
})
|
||||
})
|
||||
|
||||
it('shows empty state when no seasons are ingested', async () => {
|
||||
@@ -131,11 +186,10 @@ describe('CommandCenterPage', () => {
|
||||
expect(screen.getByTestId('cc-session-9472')).toBeInTheDocument()
|
||||
})
|
||||
expect(screen.getByTestId('cc-focus')).toHaveTextContent('Monaco')
|
||||
expect(screen.getByTestId('cc-focus')).toHaveTextContent('MON')
|
||||
expect(screen.getByTestId('cc-season-calendar')).toHaveTextContent('Season Calendar')
|
||||
expect(screen.getByTestId('cc-calendar-1229')).toHaveTextContent('R01')
|
||||
expect(screen.getByText('No live session')).toBeInTheDocument()
|
||||
expect(screen.getByTestId('cc-action-race-hub')).toHaveTextContent('Race')
|
||||
expect(screen.getByTestId('hero-last-race-link')).toHaveTextContent('Monaco')
|
||||
})
|
||||
|
||||
it('uses OpenF1 calendar metadata to focus the current weekend when local ingest is behind', async () => {
|
||||
@@ -181,9 +235,9 @@ describe('CommandCenterPage', () => {
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('cc-focus')).toHaveTextContent('Monaco')
|
||||
})
|
||||
expect(screen.getByTestId('cc-focus')).toHaveTextContent('Current weekend')
|
||||
expect(screen.getByTestId('cc-focus')).toHaveTextContent('Live now')
|
||||
expect(screen.getByTestId('cc-session-9602')).toHaveTextContent('On track')
|
||||
expect(screen.getByTestId('cc-action-race-hub')).toHaveTextContent('Qualifying')
|
||||
expect(screen.getByTestId('hero-live-link')).toHaveAttribute('href', '/live')
|
||||
|
||||
vi.useRealTimers()
|
||||
})
|
||||
|
||||
123
frontend/src/test/hero.test.ts
Normal file
123
frontend/src/test/hero.test.ts
Normal file
@@ -0,0 +1,123 @@
|
||||
import { describe, it, expect } from 'vitest'
|
||||
import { heroState, classifySessionStatus } from '../lib/hero'
|
||||
import { currentAndNextSession } from '../lib/schedule'
|
||||
import type { Session } from '../types'
|
||||
|
||||
const session = (overrides: Partial<Session> = {}): Session => ({
|
||||
session_key: 9472,
|
||||
session_name: 'Race',
|
||||
session_type: 'Race',
|
||||
meeting_key: 1,
|
||||
date_start: '2025-05-25T13:00:00+00:00',
|
||||
date_end: '2025-05-25T15:00:00+00:00',
|
||||
gmt_offset: '02:00:00',
|
||||
...overrides,
|
||||
})
|
||||
|
||||
describe('heroState', () => {
|
||||
it('returns live when the live snapshot is active', () => {
|
||||
const now = new Date('2025-05-24T12:00:00Z')
|
||||
expect(
|
||||
heroState({
|
||||
now,
|
||||
liveActive: true,
|
||||
currentSession: null,
|
||||
focusKind: 'current',
|
||||
}),
|
||||
).toBe('live')
|
||||
})
|
||||
|
||||
it('returns live when a session is in progress', () => {
|
||||
const now = new Date('2025-05-25T14:00:00Z')
|
||||
const sessions = [session()]
|
||||
const { current } = currentAndNextSession(sessions, now)
|
||||
expect(
|
||||
heroState({
|
||||
now,
|
||||
liveActive: false,
|
||||
currentSession: current,
|
||||
focusKind: 'current',
|
||||
}),
|
||||
).toBe('live')
|
||||
})
|
||||
|
||||
it('returns upcoming during a focus weekend gap before the next session', () => {
|
||||
const now = new Date('2025-05-24T12:00:00Z')
|
||||
const sessions = [
|
||||
session({
|
||||
session_key: 1,
|
||||
session_name: 'FP1',
|
||||
date_start: '2025-05-23T10:00:00+00:00',
|
||||
date_end: '2025-05-23T11:00:00+00:00',
|
||||
}),
|
||||
session({
|
||||
session_key: 2,
|
||||
session_name: 'Race',
|
||||
date_start: '2025-05-25T13:00:00+00:00',
|
||||
date_end: '2025-05-25T15:00:00+00:00',
|
||||
}),
|
||||
]
|
||||
const { current, next } = currentAndNextSession(sessions, now)
|
||||
expect(current).toBeNull()
|
||||
expect(next?.session_key).toBe(2)
|
||||
expect(
|
||||
heroState({
|
||||
now,
|
||||
liveActive: false,
|
||||
currentSession: current,
|
||||
focusKind: 'current',
|
||||
}),
|
||||
).toBe('upcoming')
|
||||
})
|
||||
|
||||
it('returns upcoming when the weekend just ended but is still the focus weekend', () => {
|
||||
const now = new Date('2025-05-25T16:00:00Z')
|
||||
const sessions = [session()]
|
||||
const { current } = currentAndNextSession(sessions, now)
|
||||
expect(current).toBeNull()
|
||||
expect(
|
||||
heroState({
|
||||
now,
|
||||
liveActive: false,
|
||||
currentSession: current,
|
||||
focusKind: 'current',
|
||||
}),
|
||||
).toBe('upcoming')
|
||||
})
|
||||
|
||||
it('returns between before the next grand prix weekend', () => {
|
||||
const now = new Date('2025-06-01T12:00:00Z')
|
||||
expect(
|
||||
heroState({
|
||||
now,
|
||||
liveActive: false,
|
||||
currentSession: null,
|
||||
focusKind: 'next',
|
||||
}),
|
||||
).toBe('between')
|
||||
})
|
||||
|
||||
it('returns between after the season when only a recent meeting remains', () => {
|
||||
const now = new Date('2026-01-01T00:00:00Z')
|
||||
expect(
|
||||
heroState({
|
||||
now,
|
||||
liveActive: false,
|
||||
currentSession: null,
|
||||
focusKind: 'recent',
|
||||
}),
|
||||
).toBe('between')
|
||||
})
|
||||
})
|
||||
|
||||
describe('classifySessionStatus', () => {
|
||||
it('marks a session as done immediately after it ends', () => {
|
||||
const now = new Date('2025-05-25T15:00:00Z')
|
||||
expect(classifySessionStatus(session(), now)).toBe('done')
|
||||
})
|
||||
|
||||
it('marks a session as live during its window', () => {
|
||||
const now = new Date('2025-05-25T14:00:00Z')
|
||||
expect(classifySessionStatus(session(), now)).toBe('live')
|
||||
})
|
||||
})
|
||||
257
frontend/src/test/hero.test.tsx
Normal file
257
frontend/src/test/hero.test.tsx
Normal file
@@ -0,0 +1,257 @@
|
||||
import { describe, it, expect, vi } from 'vitest'
|
||||
import type { ComponentProps, ReactNode } from 'react'
|
||||
import { render, screen } from '@testing-library/react'
|
||||
import type { EnrichedResult, LiveStreamData, Meeting, WeekendSession } from '../types'
|
||||
|
||||
vi.mock('@tanstack/react-router', () => ({
|
||||
Link: ({
|
||||
to,
|
||||
children,
|
||||
...rest
|
||||
}: {
|
||||
to: string
|
||||
children: ReactNode
|
||||
className?: string
|
||||
'data-testid'?: string
|
||||
}) => (
|
||||
<a href={to} {...rest}>
|
||||
{children}
|
||||
</a>
|
||||
),
|
||||
}))
|
||||
|
||||
import { CommandCenterHero } from '../components/CommandCenterHero'
|
||||
|
||||
const focusMeeting: Meeting = {
|
||||
meeting_key: 1229,
|
||||
meeting_name: 'Monaco',
|
||||
meeting_official_name: 'FORMULA 1 GRAND PRIX DE MONACO 2025',
|
||||
location: 'Monaco',
|
||||
country_name: 'Monaco',
|
||||
country_code: 'MON',
|
||||
country_flag: '',
|
||||
circuit_short_name: 'Monaco',
|
||||
date_start: '2025-05-23T00:00:00+00:00',
|
||||
date_end: '2025-05-25T00:00:00+00:00',
|
||||
year: 2025,
|
||||
}
|
||||
|
||||
const weekendSessions: WeekendSession[] = [
|
||||
{
|
||||
session: {
|
||||
session_key: 9472,
|
||||
session_name: 'Race',
|
||||
session_type: 'Race',
|
||||
meeting_key: 1229,
|
||||
date_start: '2025-05-25T13:00:00+00:00',
|
||||
date_end: '2025-05-25T15:00:00+00:00',
|
||||
gmt_offset: '02:00:00',
|
||||
},
|
||||
source: 'local',
|
||||
datasets: {} as WeekendSession['datasets'],
|
||||
},
|
||||
]
|
||||
|
||||
const liveData: LiveStreamData = {
|
||||
Drivers: {
|
||||
'1': {
|
||||
RacingNumber: '1',
|
||||
Position: 1,
|
||||
PrevPosition: 1,
|
||||
GapToLeader: '',
|
||||
Interval: '',
|
||||
LastLapTime: '1:14.000',
|
||||
LastLapPB: false,
|
||||
LastLapOB: false,
|
||||
BestLapTime: '1:13.500',
|
||||
BestLapPB: false,
|
||||
BestLapOB: false,
|
||||
BestLapNum: 10,
|
||||
InPit: false,
|
||||
PitOut: false,
|
||||
Retired: false,
|
||||
KnockedOut: false,
|
||||
Cutoff: false,
|
||||
OnFlyingLap: false,
|
||||
NumberOfLaps: 10,
|
||||
SpeedTrap: '',
|
||||
Sectors: [],
|
||||
},
|
||||
'44': {
|
||||
RacingNumber: '44',
|
||||
Position: 2,
|
||||
PrevPosition: 2,
|
||||
GapToLeader: '+1.2',
|
||||
Interval: '+1.2',
|
||||
LastLapTime: '1:14.200',
|
||||
LastLapPB: false,
|
||||
LastLapOB: false,
|
||||
BestLapTime: '1:13.700',
|
||||
BestLapPB: false,
|
||||
BestLapOB: false,
|
||||
BestLapNum: 10,
|
||||
InPit: false,
|
||||
PitOut: false,
|
||||
Retired: false,
|
||||
KnockedOut: false,
|
||||
Cutoff: false,
|
||||
OnFlyingLap: false,
|
||||
NumberOfLaps: 10,
|
||||
SpeedTrap: '',
|
||||
Sectors: [],
|
||||
},
|
||||
},
|
||||
DriverInfo: {
|
||||
'1': {
|
||||
RacingNumber: '1',
|
||||
BroadcastName: 'M VERSTAPPEN',
|
||||
Tla: 'VER',
|
||||
TeamName: 'Red Bull Racing',
|
||||
TeamColour: '3671c6',
|
||||
FirstName: 'Max',
|
||||
LastName: 'Verstappen',
|
||||
},
|
||||
'44': {
|
||||
RacingNumber: '44',
|
||||
BroadcastName: 'L HAMILTON',
|
||||
Tla: 'HAM',
|
||||
TeamName: 'Ferrari',
|
||||
TeamColour: 'e8002d',
|
||||
FirstName: 'Lewis',
|
||||
LastName: 'Hamilton',
|
||||
},
|
||||
},
|
||||
Tyres: {},
|
||||
RCMessages: [],
|
||||
Weather: {
|
||||
AirTemp: 20,
|
||||
TrackTemp: 30,
|
||||
Humidity: 50,
|
||||
WindSpeed: 1,
|
||||
WindDir: 0,
|
||||
Rainfall: false,
|
||||
},
|
||||
Session: {
|
||||
MeetingName: 'Monaco',
|
||||
CircuitName: 'Monaco',
|
||||
SessionType: 'Race',
|
||||
SessionName: 'Race',
|
||||
},
|
||||
TrackStatus: '1',
|
||||
CurrentLap: 10,
|
||||
TotalLaps: 78,
|
||||
Clock: '',
|
||||
ClockRefTime: '',
|
||||
ClockExtrapolating: false,
|
||||
Stints: {},
|
||||
}
|
||||
|
||||
const podium: EnrichedResult[] = [
|
||||
{
|
||||
driver_number: 1,
|
||||
position: 1,
|
||||
name_acronym: 'VER',
|
||||
full_name: 'Max Verstappen',
|
||||
team_name: 'Red Bull Racing',
|
||||
team_colour: '3671c6',
|
||||
dnf: false,
|
||||
dns: false,
|
||||
dsq: false,
|
||||
duration: 7200,
|
||||
gap_to_leader: null,
|
||||
number_of_laps: 78,
|
||||
points: 25,
|
||||
session_key: 9472,
|
||||
meeting_key: 1229,
|
||||
},
|
||||
{
|
||||
driver_number: 44,
|
||||
position: 2,
|
||||
name_acronym: 'HAM',
|
||||
full_name: 'Lewis Hamilton',
|
||||
team_name: 'Ferrari',
|
||||
team_colour: 'e8002d',
|
||||
dnf: false,
|
||||
dns: false,
|
||||
dsq: false,
|
||||
duration: 7205,
|
||||
gap_to_leader: 3.2,
|
||||
number_of_laps: 78,
|
||||
points: 18,
|
||||
session_key: 9472,
|
||||
meeting_key: 1229,
|
||||
},
|
||||
]
|
||||
|
||||
function renderHero(overrides: Partial<ComponentProps<typeof CommandCenterHero>> = {}) {
|
||||
const props: ComponentProps<typeof CommandCenterHero> = {
|
||||
state: 'upcoming',
|
||||
now: new Date('2025-05-24T12:00:00Z'),
|
||||
accent: '#d61a3e',
|
||||
liveActive: false,
|
||||
liveData: null,
|
||||
focusMeeting,
|
||||
focusKind: 'current',
|
||||
sessions: weekendSessions,
|
||||
currentSession: null,
|
||||
nextSession: weekendSessions[0].session,
|
||||
lastRaceName: '',
|
||||
lastRacePodium: [],
|
||||
nextMeeting: null,
|
||||
...overrides,
|
||||
}
|
||||
|
||||
return render(<CommandCenterHero {...props} />)
|
||||
}
|
||||
|
||||
describe('CommandCenterHero', () => {
|
||||
it('renders live timing link and top three in live state', () => {
|
||||
renderHero({
|
||||
state: 'live',
|
||||
liveActive: true,
|
||||
liveData,
|
||||
currentSession: weekendSessions[0].session,
|
||||
})
|
||||
|
||||
expect(screen.getByTestId('hero-live-link')).toHaveAttribute('href', '/live')
|
||||
expect(screen.getByTestId('hero-live-timing')).toHaveTextContent('VER')
|
||||
expect(screen.getByTestId('hero-live-timing')).toHaveTextContent('HAM')
|
||||
expect(screen.getByText('TRACK CLEAR')).toBeInTheDocument()
|
||||
})
|
||||
|
||||
it('renders countdown and schedule strip in upcoming state', () => {
|
||||
renderHero({
|
||||
state: 'upcoming',
|
||||
nextSession: weekendSessions[0].session,
|
||||
})
|
||||
|
||||
expect(screen.getByTestId('hero-countdown')).toHaveTextContent('1d 01h 00m 00s')
|
||||
expect(screen.getByTestId('hero-schedule-strip')).toHaveTextContent('Race')
|
||||
expect(screen.getByTestId('hero-schedule-strip')).toHaveTextContent('Next')
|
||||
})
|
||||
|
||||
it('renders last race podium and next GP countdown in between state', () => {
|
||||
const nextMeeting: Meeting = {
|
||||
...focusMeeting,
|
||||
meeting_key: 1301,
|
||||
meeting_name: 'Canada',
|
||||
country_code: 'CAN',
|
||||
date_start: '2025-06-06T00:00:00+00:00',
|
||||
date_end: '2025-06-08T00:00:00+00:00',
|
||||
}
|
||||
|
||||
renderHero({
|
||||
state: 'between',
|
||||
lastRaceName: 'Monaco',
|
||||
lastRacePodium: podium,
|
||||
nextMeeting,
|
||||
now: new Date('2025-06-01T12:00:00Z'),
|
||||
})
|
||||
|
||||
expect(screen.getByTestId('hero-last-race')).toHaveTextContent('After Monaco')
|
||||
expect(screen.getByTestId('hero-podium')).toHaveTextContent('VER')
|
||||
expect(screen.getByTestId('hero-podium')).toHaveTextContent('HAM')
|
||||
expect(screen.getByTestId('hero-next-gp-countdown')).toHaveTextContent('Canada')
|
||||
expect(screen.getByTestId('hero-next-gp-countdown')).toHaveTextContent('4d')
|
||||
})
|
||||
})
|
||||
@@ -9,7 +9,7 @@ test.describe('Command Center', () => {
|
||||
await expect(page.getByTestId('command-center')).toBeVisible()
|
||||
await expect(page.getByTestId('cc-focus')).toBeVisible()
|
||||
await expect(page.getByTestId('cc-session-9472')).toBeVisible()
|
||||
await expect(page.getByTestId('cc-actions')).toBeVisible()
|
||||
await expect(page.getByTestId('hero-last-race-link')).toBeVisible()
|
||||
})
|
||||
|
||||
test('nav link reaches command center from race hub', async ({ page }) => {
|
||||
@@ -21,8 +21,8 @@ test.describe('Command Center', () => {
|
||||
|
||||
test('open analysis action opens race hub for the focus session', async ({ page }) => {
|
||||
await page.goto('/')
|
||||
await expect(page.getByTestId('cc-action-race-hub')).toContainText(String(FULL_SESSION))
|
||||
await page.getByTestId('cc-action-race-hub').click()
|
||||
await expect(page.getByTestId('hero-last-race-link')).toBeVisible()
|
||||
await page.getByTestId('hero-last-race-link').click()
|
||||
await expect(page).toHaveURL(new RegExp(`/race-hub\\?session_key=${FULL_SESSION}`))
|
||||
await expect(page.getByTestId('rh-identity')).toBeVisible()
|
||||
await expect(page.getByTestId(`rh-session-${FULL_SESSION}`)).toBeVisible()
|
||||
|
||||
Reference in New Issue
Block a user