explorer/AGENTS.md

# AGENT.md

This document provides an overview of the Next Explorer project, its structure, and its implementation details.

## Project Overview

Next Explorer is a web application for exploring the Spectrum Next ecosystem. It is built with Next.js (App Router), React, and TypeScript.

It has two main areas:
- Registers: parsed from `data/nextreg.txt`, browsable with real-time filtering and deep links.
- ZXDB Explorer: a deep, cross‑linked browser for ZXDB entries, releases, labels, magazines, genres, languages, and machine types backed by MySQL using Drizzle ORM.

## Project Structure

The project is a Next.js application with the following structure:
```

next-explorer/
├── eslint.config.mjs
├── next.config.ts
├── package.json
├── pnpm-lock.yaml
├── tsconfig.json
├── data/
│   ├── nextreg.txt
│   ├── custom_parsers.txt
│   └── wikilinks.txt
├── node_modules/...
├── public/...
└── src/
├── middleware.js
├── app/
│   ├── layout.tsx
│   ├── page.module.css
│   ├── page.tsx
│   └── registers/
│       ├── page.tsx
│       ├── RegisterBrowser.tsx
│       ├── RegisterDetail.tsx
│       └── [hex]/
│           └── page.tsx
├── components/
│   ├── Navbar.tsx
│   └── ThemeDropdown.tsx
├── scss/
│   ├── _bootswatch.scss
│   ├── _explorer.scss
│   ├── _variables.scss
│   └── nbn.scss
├── services/
│   └── register.service.ts
└── utils/
├── register_parser.ts
└── register_parsers/
├── reg_default.ts
└── reg_f0.ts
```
- **`data/`**: Contains the raw input data for the Spectrum Next explorer.
  - `nextreg.txt`: Main register definition file.
  - `custom_parsers.txt`, `wikilinks.txt`: Auxiliary configuration/data used by the parser.
- **`src/app/`**: Next.js App Router entrypoint.
  - `layout.tsx`: Root layout for all routes.
  - `page.tsx`: Application home page.
  - `registers/`: Routes and components for the register explorer.
    - `page.tsx`: Server Component that loads and lists all registers.
    - `RegisterBrowser.tsx`: Client Component implementing search/filter and listing.
    - `RegisterDetail.tsx`: Client Component that renders a single register’s details, including modes, notes, and source modal.
    - `[hex]/page.tsx`: Dynamic route that renders details for a specific register by hex address.
- `src/app/zxdb/`: ZXDB Explorer routes and client components.
  - `page.tsx`: ZXDB hub page linking to entries, releases, labels, etc.
  - `entries/[id]/page.tsx` + `EntryDetail.tsx`: Entry details (SSR initial data).
  - `releases/page.tsx` + `ReleasesExplorer.tsx`: Releases search + filters.
  - `labels/page.tsx`, `labels/[id]/page.tsx` + client: Labels search and detail.
  - `genres/`, `languages/`, `machinetypes/`: Category hubs and detail pages.
  - `magazines/`, `issues/`: Magazine and issue browsing.
- `src/app/api/zxdb/`: Zod‑validated API routes (Node runtime) for search and category browsing.
- `src/server/`:
  - `env.ts`: Zod env parsing/validation (t3.gg style). Validates `ZXDB_URL` (mysql://).
  - `server/db.ts`: Drizzle over `mysql2` singleton pool.
  - `server/schema/zxdb.ts`: Minimal Drizzle models (entries, labels, helper tables, lookups).
  - `server/repo/zxdb.ts`: Repository queries for search, details, categories, and facets.
- **`src/components/`**: Shared UI components such as `Navbar` and `ThemeDropdown`.
- **`src/services/register.service.ts`**: Service layer responsible for loading and caching parsed register data.
- **`src/utils/register_parser.ts` & `src/utils/register_parsers/`**: Parsing logic for `nextreg.txt`, including mode/bitfield handling and any register-specific parsing extensions.

## Implementation Details

Comment what the code does, not what the agent has done. The documentation's purpose is the state of the application today, not a log of actions taken.

### Data Parsing

- `getRegisters()` in `src/services/register.service.ts`:
  - Reads `data/nextreg.txt` from disk.
  - Uses `parseNextReg()` from `src/utils/register_parser.ts` to convert the raw text into an array of `Register` objects.
  - Returns the in-memory representation of all registers (and can be extended to cache results across calls).

- `parseNextReg()` and related helpers in `register_parser.ts`:
  - Parse the custom `nextreg.txt` format into structured data:
    - Register addresses (hex/dec).
    - Names, notes, and descriptive text.
    - Per-mode read/write/common bitfield views.
    - Optional source lines and external links (e.g. wiki URLs).
  - Delegate special-case parsing to functions in `src/utils/register_parsers/` (e.g. `reg_default.ts`, `reg_f0.ts`) when needed.

### TypeScript Patterns
 - No explicity any types.
 - Use `const` for constants.
 - Use `type` for interfaces.
 - No `enum`.

### UI / Bootstrap Patterns

The project uses the **Bootswatch Pulse** theme (purple primary) with `react-bootstrap` and `react-bootstrap-icons`.

- **Always use react-bootstrap components** over raw HTML+className for Bootstrap elements:
  - `Card`, `Table`, `Badge`, `Button`, `Alert`, `Form.Control`, `Form.Select`, `Form.Check`, `InputGroup`, `Spinner`, `Collapse` etc.
  - Icons from `react-bootstrap-icons` (e.g. `Search`, `ChevronDown`, `Download`, `BoxArrowUpRight`).
- **Match existing patterns** — see `RegisterBrowser.tsx` and `Navbar.tsx` for canonical react-bootstrap usage.
- **Shared explorer components** in `src/components/explorer/`:
  - `ExplorerLayout` — two-column layout (sidebar + content).
  - `FilterSidebar` — `Card` wrapper with optional "Reset all filters" button.
  - `FilterSection` — collapsible filter group with label, badge, and `Collapse` animation.
  - `MultiSelectChips` — chip-toggle selector with optional collapsed summary mode.
  - `Pagination` — prev/next with page counter and loading spinner.
- **Stale-while-revalidate pattern** — show previous results at reduced opacity during loading (`className={loading ? "opacity-50" : ""}`), never blank the screen.
- **Empty states** — only show a section/card if it has data. Do not render empty cards with "No X recorded" placeholders; omit them entirely.
- **Tables** — use react-bootstrap `<Table size="sm" striped>` for data tables. Human-readable sizes (KB/MB) over raw bytes. Omit columns that add noise without value (e.g. MD5 hashes).
- **Alerts** — use `<Alert variant="warning">` for "no results" states with actionable suggestions (e.g. offering to broaden filters).

### React / Next.js Patterns

- **Server Components**:
  - `src/app/registers/page.tsx` and `src/app/registers/[hex]/page.tsx` are Server Components.
  - ZXDB pages under `/zxdb` server‑render initial content for fast first paint, with ISR (`export const revalidate = 3600`) on non‑search pages.
  - Server components call repository functions directly on the server and pass data to client components for presentation.

- **Client Components**:
  - `RegisterBrowser.tsx`:
    - Marked with `'use client'`.
    - Uses React state to manage search input and filtered results.
  - `RegisterDetail.tsx`:
    - Marked with `'use client'`.
    - Renders a single register with tabs for different access modes.
  - ZXDB client components (e.g., `EntriesExplorer.tsx`, `EntryDetail.tsx`, `labels/*`) receive initial data from the server and keep interactions on the client without blocking the first paint.

- **Dynamic Routing**:
  - Pages and API routes must await dynamic params in Next.js 15:
    - Pages: `export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; }`
    - API: `export async function GET(req, ctx: { params: Promise<{ id: string }> }) { const raw = await ctx.params; /* validate with Zod */ }`
  - `src/app/registers/[hex]/page.tsx` resolves the `[hex]` segment and calls `notFound()` if absent.

### ZXDB Integration

- Database connection via `mysql2` pool wrapped by Drizzle (`src/server/db.ts`).
- Env validation via Zod (`src/env.ts`) ensures `ZXDB_URL` is a valid `mysql://` URL.
- Supports optional local file mirroring via `ZXDB_LOCAL_FILEPATH` and `WOS_LOCAL_FILEPATH` env vars.
- Minimal Drizzle schema models used for fast search and lookups (`src/server/schema/zxdb.ts`).
- Repository consolidates SQL with typed results (`src/server/repo/zxdb.ts`). Gracefully handles missing tables (e.g. `releases`) by checking `information_schema.tables`.
- API routes under `/api/zxdb/*` validate inputs with Zod and run on Node runtime.
- UI under `/zxdb` is deeply cross‑linked and server‑renders initial data for performance. Links use Next `Link` to enable prefetching.
  - Helper SQL `ZXDB/scripts/ZXDB_help_search.sql` must be run to create `search_by_*` tables for efficient searches.
  - Lookup tables use column `text` for display names; the Drizzle schema maps it as `name`.

### Working Patterns***

- git branching:
  - Do not create new branches
- git commits:
  - Create or update COMMIT_EDITMSG file if commits pending, await any user 
    edits, or additional instructions. Once told, commit all the changes
    using that commit note, and then delete the COMMIT_EDITMSG file. 
    Remember to keep the first line as the subject <50char
- git commit messages:
  - Use imperative mood (e.g., "Add feature X", "Fix bug Y").
  - Include relevant issue numbers if applicable.
  - Sign-off commit message as <agent-name>@<hostname>
- validation and review:
  - When changes are visual or UX-related, provide concrete links/routes to validate.
  - Call out what to inspect visually (e.g., section names, table columns, empty states).
  - Use the local `.env` for any environment-dependent behavior.
  - Provide fully clickable links when sharing validation URLs.
- submodule hygiene:
  - The `ZXDB` submodule is read-only in this repo; do not commit SQL dumps from it.
  - Use `bin/setup-zxdb-local.sh` (or `pnpm setup:zxdb-local`) to add local excludes for SQL files.
- deploy workflow:
  - `bin/deploy.sh` refuses to run with uncommitted or untracked files at the repo root.
- testing:
  - **DO NOT** not restart the dev-server, use the already running one.
  - Use tsc -noEmit to check for type errors
  - **DO NOT** 'build' the application, Next.js build breaks the dev-server.
  
### References

- ZXDB setup and API usage: `docs/ZXDB.md`