D. Rimron-Soutter
ad77b47117
Context - Housekeeping commit to capture all current ZXDB Explorer work before index-page performance optimizations. Includes - Server-rendered entry detail page with ISR and parallelized DB queries. - Node runtime for ZXDB API routes and params validation updates for Next 15. - ZXDB repository extensions (facets, label queries, category queries). - Cross-linking and Link-based prefetch across ZXDB UI. - Cache headers on low-churn list APIs. Notes - Follow-up commit will focus specifically on speeding up index pages via SSR initial data and ISR. Signed-off-by: Junie@lucy.xalior.com
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# 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. 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 Junie@<hostname> |