This repository contains a static web app for searching a large music metadata database (no server/API calls). It uses:
- Bulma (`bulma.min.css`) for UI (https://bulma.io/documentation/)
- A single HTML file (`index.html`)
- A single JS file (`script.js`)
- A small site stylesheet (`site.css`) for project‑specific tweaks (no frameworks)
- A client-side SQLite database (WASM) fetched as a static asset (paged with HTTP Range if available)

Keep implementation details minimal; this file orients agents to project structure, constraints, and the data model.

---

## Goals (for agents)
- Provide a responsive search UI over a large SQLite metadata DB entirely in-browser.
- No server-side code; all queries run client-side.
- Fast startup, predictable UX, minimal dependencies.

## Non-Goals
- Hosting or streaming audio files.
- Write access to the DB.
- Complex build systems or frameworks.

---

## Repository Layout (expected)

/
- index.html        # Single-page app shell
- bulma.min.css     # Bulma CSS (pinned)
- site.css          # Site-specific styles (tiny utilities like transitions)
- script.js         # All app logic
- /assets/
  - mp3com-meta.sqlite   # Metadata DB (read-only)
- AGENTS.md

- If subfolders are added later (icons, fonts), prefer `/assets/...`.
- Do not introduce bundlers unless requested.

---

## UI/UX Conventions
- Use Bulma components (containers, navbar, form controls, tables, pagination).
- Default to semantic HTML + Bulma classes; avoid inline styles.
- Place any site-specific CSS (e.g., small transitions like fade utilities) in `site.css`.
- Accessibility: ensure focus states, label–input associations, and ARIA for dynamic content.

---

## Data Access (Client-Side)
- Use SQLite compiled to WebAssembly in the browser.
- Prefer an HTTP VFS (range requests) to avoid fetching the entire DB up front.
- Queries should be read-only; no schema migrations/run-time writes.

Minimal runtime expectations
- One network fetch for the WASM runtime.
- The DB file (`/assets/mp3com-meta.sqlite`) fetched lazily by page(s) as needed.

---

## Database Schema (authoritative)

PRAGMA foreign_keys=ON;

CREATE TABLE IF NOT EXISTS artists(
  id   INTEGER PRIMARY KEY,
  name TEXT NOT NULL COLLATE NOCASE UNIQUE
);

CREATE TABLE IF NOT EXISTS albums(
  id        INTEGER PRIMARY KEY,
  artist_id INTEGER NOT NULL REFERENCES artists(id),
  title     TEXT COLLATE NOCASE,
  year      INTEGER,
  UNIQUE(artist_id, title, year)
);

CREATE TABLE IF NOT EXISTS tracks(
  id             INTEGER PRIMARY KEY,
  artist_id      INTEGER NOT NULL REFERENCES artists(id),
  album_id       INTEGER REFERENCES albums(id),
  title          TEXT NOT NULL COLLATE NOCASE,
  track_no       INTEGER,
  year           INTEGER,
  genre          TEXT,
  duration_sec   INTEGER,
  bitrate_kbps   INTEGER,
  samplerate_hz  INTEGER,
  channels       INTEGER,
  filesize_bytes INTEGER,
  sha1           TEXT,   -- optional; may be NULL
  relpath        TEXT NOT NULL
);

-- External-content FTS5 (search over key text fields)
CREATE VIRTUAL TABLE IF NOT EXISTS fts_tracks USING fts5(
  title, artist, album, genre,
  content='tracks', content_rowid='id',
  tokenize = 'unicode61 remove_diacritics 2',
  prefix='2 3 4'
);

-- Keep FTS index in sync
CREATE TRIGGER IF NOT EXISTS tracks_ai AFTER INSERT ON tracks BEGIN
  INSERT INTO fts_tracks(rowid,title,artist,album,genre)
  VALUES (new.id,
          new.title,
          (SELECT name FROM artists WHERE id=new.artist_id),
          (SELECT title FROM albums WHERE id=new.album_id),
          new.genre);
END;

CREATE TRIGGER IF NOT EXISTS tracks_ad AFTER DELETE ON tracks BEGIN
  INSERT INTO fts_tracks(fts_tracks, rowid) VALUES('delete', old.id);
END;

CREATE TRIGGER IF NOT EXISTS tracks_au AFTER UPDATE ON tracks BEGIN
  INSERT INTO fts_tracks(fts_tracks, rowid) VALUES('delete', old.id);
  INSERT INTO fts_tracks(rowid,title,artist,album,genre)
  VALUES (new.id,
          new.title,
          (SELECT name FROM artists WHERE id=new.artist_id),
          (SELECT title FROM albums WHERE id=new.album_id),
          new.genre);
END;

CREATE INDEX IF NOT EXISTS idx_tracks_artist_id ON tracks(artist_id);
CREATE INDEX IF NOT EXISTS idx_tracks_album_id  ON tracks(album_id);
CREATE INDEX IF NOT EXISTS idx_tracks_year      ON tracks(year);

Notes
- Text search should use `fts_tracks MATCH ?` and join back to `tracks` for details.
- Sorting for display can use `ORDER BY rank` (FTS) or `artist,title,year`.

---

## Example Queries (for agents)

Free text:

SELECT t.id, a.name AS artist, t.title, IFNULL(al.title,'') AS album, t.year, t.genre
FROM fts_tracks f
JOIN tracks t ON t.id=f.rowid
JOIN artists a ON a.id=t.artist_id
LEFT JOIN albums al ON al.id=t.album_id
WHERE f MATCH ?            -- e.g., 'queen "bohemian rhapsody"'
ORDER BY rank LIMIT 50;

By artist prefix (fast via FTS `prefix`):

WHERE f MATCH 'artist:beatl*'

Count by year:

SELECT year, COUNT(*) FROM tracks GROUP BY year ORDER BY year;

---

## Local Development

- Serve statically (to enable range requests and avoid file:// issues):
  - Python: `python3 -m http.server 8000`
  - Node: `npx http-server -p 8000`
- Open `http://localhost:8000/`
- Ensure the server sends `Accept-Ranges: bytes` for `/assets/mp3com-meta.sqlite`.

---

## Performance Guidance

- Keep initial DOM minimal; render results incrementally (virtualized list if needed).
- Debounce search input (e.g., 200–300 ms).
- Use `LIMIT`/pagination; avoid `SELECT *` on large result sets.
- Cache prepared statements in JS if the WASM wrapper allows.

---

## Quality Bar

- No console errors.
- Basic keyboard navigation works.
- Layout adapts from mobile → desktop via Bulma columns.
- Reasonable query latency for common searches (<300ms after warm-up).

---

## Security & Privacy

- No third-party trackers.
- Only static file loads; no credentials.
- If adding analytics, prefer privacy-preserving, self-hosted options and document them.

---

## Agent Etiquette

- Do not introduce new build steps or frameworks unless explicitly asked.
- Keep diffs small and focused.
- When editing `index.html`/`script.js`, include inline comments explaining assumptions.
- Verify changes against the schema above.