# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

`bes.is` — a Blazor Server app (single ASP.NET Core project, no test project) hosting a
collection of small, mostly self-contained JS/HTML experiments/tools (RPN calculator,
QR code scan/generate, a Netflix→Letterboxd converter, a JSON query playground, BRP
lookup, etc.), each on its own route.

## Commands

Run from the repo root or `Blog/`:

```
dotnet build                         # build
dotnet run --project Blog            # run locally (http://localhost:5296)
dotnet watch --project Blog          # run with hot reload
```

There is no test project in the solution — don't invent `dotnet test` commands or test
files unless asked to add a test project first.

Publishing is done via the Rider run configuration "Publish Blog to custom server" (self-contained
`linux-x64`, Release, ReadyToRun) — not part of normal dev workflow.

## Architecture

**One project, one layout, many independent page-features.** `Blog/Components/Pages/*.razor`
are the routes (`@page "/Xyz"`), each linked from `SiteFooter.razor`. Most pages are a
`.razor` file paired with a `.razor.js` file of the same name — this is the pattern to
follow for any new interactive page.

### The `.razor` + `.razor.js` pairing

Blazor's `<PageScript Src="./Components/Pages/Foo.razor.js"/>` (wrapping the built-in
`<page-script>` custom element, registered in `wwwroot/Blog.lib.module.js`) loads a JS
module scoped to that page. The module can export `onLoad`, `onUpdate`, `onDispose`
lifecycle hooks, called as the custom element connects/re-renders/disconnects (this
matters across Blazor's enhanced navigation, which doesn't do a full page reload).
Page logic is written in vanilla JS DOM manipulation, not Blazor data binding — components
grab elements with `getById` and wire up listeners directly in `onLoad`.

`PageScript.razor`, `Log.razor`, `Panel.razor`, and the `StackOp*.razor` components live in
`Components/_Shared/` and are reused across pages (e.g. `Log` renders a debug/error log
panel that JS writes into via `writeDebug`/`writeError`; `Panel` is a bordered
fieldset-with-legend used for docs/credits/grouped controls).

### `wwwroot/common.module.js`

Shared JS helpers imported by page scripts:
- `h(tag, attrs?, children?)` / `t(text)` — a small hyperscript-style DOM builder (no
  framework, just `document.createElement`/`appendChild`). Prefer this over manual DOM
  building or template strings in new page scripts.
- `getById(id)` — like `document.getElementById` but throws instead of returning null.
- `writeError` / `writeInfo` / `writeDebug` / `resetLog` — write into the `#log` element
  that `Log.razor` renders.
- `debounce(fn, wait)`.

Other `wwwroot/*.js` files (`dactal.js`, `qrcode.js`, `lz-string.module.js`, `jsonql-js/`)
are third-party or semi-vendored libraries used by specific pages (e.g. `Query.razor.js`
uses both `dactal.js` and `jsonql-js` to run two query languages against the same mock
BRP dataset in `wwwroot/brp.json`).

### rvrb feature (stats read off another BEAM node)

`Rvrb.razor`/`.razor.cs`/`.razor.js` (route `/rvrb`) shows the status and stats of the
rvrb Elixir bot (`~/Developer/elixir/rvrb`), which runs on the same server. `Services/RvrbService.cs`
gets them by joining the bot's Erlang cluster: [BeamSharp](https://github.com/Besselking/BeamSharp)
(referenced as a project from the sibling checkout, it is not on NuGet yet) makes this site a
hidden Erlang node and calls `Rvrb.Stats.snapshot/0` on the bot the way any BEAM node would —
no HTTP endpoint on the Elixir side.

The node is started on the *first request* rather than at boot, and a failure is a value
(`RvrbStatus.Unreachable`) rather than an exception: the site must not fail to start, or a page
fail to render, because EPMD is down or the bot was deployed without distribution. `Models/RvrbSnapshot.cs`
holds the shapes and `Services/RvrbSnapshotReader.cs` decodes the Erlang term into them by hand —
the term is an Elixir map written by Elixir, not a serialized C# type.

Configuration lives under `Rvrb` (`RvrbOptions`): `Node`, `LocalNode`, `CallTimeout`, `CacheFor`
in `appsettings.json`, and `Cookie` — the shared Erlang cookie — from user secrets in development
(`dotnet user-secrets set "Rvrb:Cookie" ...`) or `Rvrb__Cookie` in the environment. The bot's own
side of this (enabling distribution on its release) is documented in the rvrb repo's README.

### BRP feature (the one page with a real backend)

`BRP.razor`/`.razor.cs` and `BrpTestData.razor` are backed by `Services/BrpService.cs`,
which calls an external "Haal Centraal BRP" lookup API (base address configured in
`Program.cs` as `https://brp.bes.is/`) and caches responses via `HybridCache`
(`Microsoft.Extensions.Caching.Hybrid`). `Models/BRPEntry.cs` and
`Models/RaadpleegMetBurgerservicenummer.cs` model the request/response shapes. Test/mock
data lives in `Resources/test-data.json` and `wwwroot/brp.json`.

### Styling

`wwwroot/app.css` is one hand-maintained stylesheet (no CSS framework, no build step),
organized into numbered sections (Tokens → Reset/base → Typography → Layout → Controls →
Components → Media) with CSS custom properties as the single source of design tokens
(colors, spacing scale, fonts). It uses `light-dark()` and `color-scheme` for automatic
dark mode — don't hardcode light/dark colors, extend the token set in section 1 instead.
`MainLayout.razor.css` holds the one layout-specific scoped stylesheet.