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 + ZxdbExplorer.tsx: Search + filters with server-rendered initial content and ISR.
  • 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.

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., ZxdbExplorer.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.
• 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 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@

References

• ZXDB setup and API usage: docs/ZXDB.md