decePubClient/CLAUDE.md

# CLAUDE.md

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

## What this is

decePubClient is a Blazor WebAssembly PWA (.NET 10). It is meant as a Pleroma-FE-like client for **PrivaPub**, the
owner's ActivityPub server, whose repo is `thepra/SocialPub`. It is deployed as a static site at
https://decepub.thepra.dev, and its API base address is `https://privapub.thepra.dev`
(`AppConfiguration:ApiBaseAddress` in `wwwroot/appsettings.json`).

**It is still a prototype and is not connected to the server:**
- The feed comes from `Helpers/Faker.cs`. `Storage.GetMessages()` (`Services/IStorage.cs`) and `Pages/ExpandMessage.razor`
  create mock posts.
- Every method in `Services/MessagesService.cs` is a `//TODO` stub.
- `HttpService` (`Services/IHttpService.cs`) is written but not registered in DI.
- The nginx vhost sends `X-Robots-Tag: noindex` while the site shows mock posts.

`Docs/Insomnia_APIs.json` is an old API collection for a localhost backend. Don't treat it as PrivaPub's API.

## Sibling repo dependency

The project references `../SocialPub/PrivaPub.ClientModels/PrivaPub.ClientModels.csproj`, so SocialPub must be
checked out next to this repo. CI clones it there. That project supplies:
- the shared DTOs;
- `Policies` (IsAdmin, IsUser, IsModerator);
- the `FieldsNameResource` and `ErrorsResource` localization resources.

Before wiring anything to the API, read `../SocialPub/CLAUDE.md`. PrivaPub's route names (`/peasants/...`, `/mouth`,
`/anus`, ...) are deliberate. Never "correct" them. The intended API surface is the Mastodon client API plus PrivaPub's
private `/clientapi`.

## Commands

```sh
dotnet build decePubClient.csproj                      # what CI runs (-c Release) on every push to master and on PRs
dotnet run                                             # dev server: https://localhost:7046 / http://localhost:5046
dotnet publish decePubClient.csproj -c Release -o publish   # static site lands in publish/wwwroot
```

`global.json` pins SDK 10.0.100 with `rollForward: latestFeature`. There are no tests and no linter.

## CSS: Tailwind 4 + daisyUI 5, no Node

`Styles/app.css` is compiled into `wwwroot/css/app.css` by the Tailwind CSS standalone binary with the daisyUI
plugin. `app.css` is gitignored and regenerated on every build.

- `tools/tailwind.sh` downloads Tailwind 4.3.3 and daisyUI 5.7.47 into the gitignored `.tools/tailwind/`, checking each
  against a pinned sha256. To upgrade, change the versions and hashes there.
- The `TailwindCompile` target in the csproj runs it, so `dotnet build` / `publish` are enough, in CI as well. Debug
  builds use `--optimize`, Release builds `--minify`. Pass `-p:SkipTailwind=true` to skip it.
- `IncludeTailwindOutput` adds the generated file to `Content` before static web assets are resolved. Without that, a
  clean-clone publish would ship `app.css` without its `.gz`/`.br` copies and outside `service-worker-assets.js`.
  The deploy workflow checks for `css/app.css.gz`.
- `bash tools/tailwind.sh watch` rebuilds the CSS live next to `dotnet watch`. `bash tools/tailwind.sh docs` fetches
  daisyUI's `llms.txt` (its component reference) into `.tools/tailwind/`.
- Tailwind scans every file `.gitignore` doesn't exclude, and only generates the classes it finds written out
  **whole**. Never build a class name by concatenation or interpolation (`"btn-" + size`, `$"btn-{size}"`). Write
  every variant as a literal, e.g. in a switch arm.

Ionicons 4.5 (`wwwroot/vendor/ionicons.min.css`, `<i class="ion-md-...">`) is loaded as its own stylesheet.

## Theme and neumorphism

- `Styles/theme.css` holds two daisyUI themes, `neo-light` (default) and `neo-dark` (`prefersdark`). Every colour
  is an `hsl()` of `--neo-hue-light` / `--neo-hue-dark` / `--neo-chroma` (0 for the grey themes).
- `wwwroot/js/theme.js` sets those variables and `data-theme` on `<html>` from `PageSettings`. It runs in `<head>`
  from localStorage, so there is no flash before Blazor boots. After that, CascadingState calls it through
  `AppStatusService.ApplyTheme` whenever the settings change. With `PreferSystemTheming` it leaves `data-theme` off,
  and the OS decides.
- `Styles/neo.css` holds the neumorphic layer:
  - `neo-raised` / `neo-inset` / `neo-flat`, with sizes `neo-2xs` / `neo-xs` / `neo-sm` / `neo-md` (these replace the
    old `neomorph is-nxsmall` classes);
  - `neo-gradient(-pressed)` and `neo-hue-track`;
  - `@utility <daisy-component>` overrides that give btn, input, select, card, … the neo look. daisyUI puts its rules
    in sublayers of `utilities`, so these overrides beat **every** daisyUI rule. Each override must exclude the
    daisyUI variants it shouldn't touch, e.g. `:not(:where(.btn-ghost, .btn-link, ...))`, and call sites drop a neo
    shadow with `shadow-none!`.
- Never write `@utility collapse`. It brings back Tailwind's own `collapse` utility (`visibility: collapse`), and
  every collapse disappears.

## daisyUI Blazor components (`Components/Daisy/`)

Every daisyUI component has a `D`-prefixed wrapper (`DButton`, `DModal`, `DDropdown`, `DInput`, ...), grouped by
daisyUI's categories into folders whose namespaces are imported in `_Imports.razor`. `/styleguide` (not linked) renders
all of them in every theme. When you add or change one:
- Map each enum to its classes in a switch with whole literal class names.
- Value-holding fields derive from `DInputBase<TValue>`, Blazor's `InputBase`, so `@bind-Value` and EditForm
  validation work. Everything else derives from `DComponentBase` (`Class`, pass-through attributes, `Cx(...)`).
- Open/active state lives in C# (`@bind-IsOpen`, `@bind-Active`) and is rendered with daisyUI's `*-open` modifier
  classes. No JS interop. `DCalendar` is the one exception: it wraps the vendored Cally web component.
- Don't name a parameter after an HTML attribute (`Title`, `Style`, `Id`, `Label`, ...). Blazor matches attributes
  to parameters without regard to case, so the parameter would swallow the attribute.
- Components don't use `Localizer` or `CascadingState`; their user-visible strings are parameters.

## Architecture

**Startup (`Program.cs`).**
- DI registration happens here.
- The named `HttpClient` "default" uses `ApiBaseAddress` as its base address. It falls back to the host's base
  address when that setting is empty.
- `SetDefaultCulture()` (`Extensions/ExtensionMethods.cs`) runs before the app starts. It picks the culture from the
  saved `PublicCacheData` or from the browser language, and maps any `en*` to `en-GB`.

**`LayerComponents/CascadingState.razor`** wraps the router in `App.razor`. It is the app-wide state object, and pages
take it as `[CascadingParameter] CascadingState`. It handles:
- `PublicCacheData` (page settings: theme colours, dark/light/system theming, language), persisted in localStorage;
- the theme, applied through `AppStatusService.ApplyTheme` (`wwwroot/js/theme.js`);
- an online check every 10 seconds;
- `ProcessError` / `ProcessWarning`, which components should call to report errors and warnings;
- `LogFromJs`, which JS calls back into through a `DotNetObjectReference`.

**Components and pages** inherit `LocalizableComponentBase`, which supplies `Localizer`, an `IsLoading` flag and
`AfterRenderAsyncJobs`. `PagesBase` is an empty subclass of it, and only `Authentication.razor` uses it.

**Localization (`Services/CoalescingStringLocalizer.cs`).**
- Lookup order: this repo's `Resources/AllStrings.resx`, then `FieldsNameResource`, then `ErrorsResource`.
- A missing key renders as the key itself, so a typo fails silently.
- The class lives in namespace `collAnon.Client.Services`, a leftover from another project.

**Client storage** comes in two layers:
- **localStorage** (Blazored.LocalStorage, camelCase JSON) holds `AuthData` and `PublicCacheData`, keyed by
  `nameof(Type)`.
- **IndexedDB** (DnetIndexedDb, database `data`) is reached through `IStorage`. Its schema is declared in
  `GenericExtensions.AddIndexedDb()`, and you must bump `WithVersion` when you change it.
- Known gap: `IStorage` reads and writes a `ClientLogs` store that the schema never declares, so the error log writes
  fail silently (they are wrapped in try/catch).

**Auth.**
- `TokenAuthStateProvider` builds the auth state from the `AuthData` token in localStorage.
- `SetToken` is mostly commented out, so there is no real login flow yet.
- `AddApiAuthorization` and `Pages/Authentication.razor` are leftovers from the Blazor template.

**JS interop.**
- `wwwroot/main.js` defines `window.*` helpers. `Services/AppStatusService.cs` calls them, mostly through the
  synchronous `IJSInProcessRuntime`.
- Each helper reports its errors back through `window.logFromJs`.
- The other scripts (IndexedDB, HeadElement, auth, rxjs) are loaded by `<script>` tags in `wwwroot/index.html`.

**PWA.** Published builds use `wwwroot/service-worker.published.js`, and `service-worker.js` is the dev version.

## Deployment

`.gitea/workflows/deploy.yml` runs on a `v*` tag or a manual dispatch, on a self-hosted runner that is also the web
host. The steps:
1. Publish the site.
2. Write `build.json` (commit, ref, time).
3. Snapshot the live directory to `/var/backups/decepub.thepra.dev`.
4. `rsync --delete` into `/var/www/decepub.thepra.dev`.
5. Check that `build.json` serves the new commit and that a deep client route returns 200 (the SPA fallback). Otherwise,
   roll back to the snapshot.

The nginx vhost and headers are in `deploy/nginx/`, and `deploy/max/setup.sh` is the one-time root setup on the
server. If you add a file that must never be cached, add it to the `expires -1` locations in the vhost.

## Conventions

- Indent with tabs.
- `Nullable` is disabled and `ImplicitUsings` is enabled.
- Global Razor usings are in `_Imports.razor`.
- Styling uses the D components, Tailwind utilities and the `neo-*` utilities. Use `gap-*` rather than `space-x/y-*`
  on flex containers; the feeds use `flex-col-reverse`, which `space-*` gets wrong.
- `SUtility.IfTrueThen(cond, "class")` is the helper for conditional classes.