# Songbook live JSON consumer checklist

Last refreshed: 2026-07-01 04:08 AWST

Purpose: make the browser seed-loading contract explicit so follow-up jobs and future UI edits do not guess how `chords.system8.json` and `songs.json` should be consumed.

## UI load order

1. Try `./chords.system8.json` first with a no-store fetch.
2. If that request fails, returns non-2xx, or cannot parse as JSON, fall back to `./songs.json`.
3. Normalize the loaded public seed songs before rendering.
4. If the browser already has localStorage songs, keep the user/local copy authoritative and use the seed only as an import source.
5. If both JSON routes fail, keep the app shell usable: render the current local library if present, otherwise show an empty searchable library plus import/backup controls.

## Graceful offline/failure behaviour

- Online and healthy: the app loads `chords.system8.json`; `songs.json` remains byte-for-byte equivalent while retained as fallback.
- Canonical route stale/broken: the browser may continue via `songs.json`, but the canonical route should be treated as a reportable live-site issue.
- Fully offline after prior install: cached app shell and any browser-local songs should remain usable; do not wipe localStorage just because seed routes fail.
- Fresh offline/no cache: the user should still see the shell and import/export controls once the HTML/JS shell is available; seed-song absence must not expose private data or break backup controls.

## Public-data boundary

The seed JSON files are public runtime assets. They must contain only public/demo song data. Never include:

- private gig notes or private localStorage backups
- payment credentials, tokens, API keys, router details, Wi-Fi passwords, or account secrets
- unpublished contact details or private audience/payment wording

## Regression evidence to keep current

Run from `/home/nk/chords-system8-live-site`:

```sh
npm test
python3 -m json.tool chords.system8.json >/tmp/chords-system8-json-route-local.json
python3 -m json.tool songs.json >/tmp/chords-system8-songs-route-local.json
cmp -s chords.system8.json songs.json
```

Browser-facing checks:

- Homepage links to this checklist and the JSON route status card.
- `app.js` contains `const urls=['./chords.system8.json','./songs.json']` in that order.
- Console may show a seed-load warning only when a route genuinely fails; it must not erase existing local songs.
- Public checklist copy must not contain credential assignments.

Report only if the load order changes, the canonical/fallback files diverge unexpectedly, a public route stops returning parseable JSON, or regression tests fail.