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 browsing and exploring the registers of the Spectrum Next computer. It is built with Next.js (App Router), React, and TypeScript.

The application reads register data from `data/nextreg.txt`, parses it on the server, and displays it in a user-friendly interface. Users can search for specific registers and view their details, including per-register notes and source snippets.

## 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/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.

### React / Next.js Patterns

- **Server Components**:
  - `src/app/registers/page.tsx` and `src/app/registers/[hex]/page.tsx` are Server Components.
  - They call `getRegisters()` on the server and pass the resulting data down to client components as props.

- **Client Components**:
  - `RegisterBrowser.tsx`:
    - Marked with `'use client'`.
    - Uses React state to manage search input and filtered results.
    - Renders a list or grid of registers.
  - `RegisterDetail.tsx`:
    - Marked with `'use client'`.
    - Renders a single register with tabs for different access modes.
    - Uses a modal to show the original source lines for the register.

- **Dynamic Routing**:
  - `src/app/registers/[hex]/page.tsx`:
    - Resolves the `[hex]` URL segment.
    - Looks up the corresponding register by `hex_address`.
    - Calls `notFound()` when no matching register exists.

### Working Patterns***

- git branching:
  - Do not create new branches
- git commits:
  - Create COMMIT_EDITMSG file, await any user edits, then commit using that 
    commit note, and then delete the COMMIT_EDITMSG file.
- 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 Junie@<hostname>