archvillainette
9c6e2963e9
## Summary
A Support inbox drawer on the topbar, next to the notification bell, fed by
the plugin-owned support inbox in sow-nodebb-plugin-support#15.
It is not a lookalike: the rows are rendered with core's own
`partials/notifications_list` partial, from entries the support plugin now
returns in core's notification field names, inside a dropdown that copies
Harmony's `partials/sidebar/notifications.tpl`. So the drawer has the
notification drawer's avatar block, stretched link, muted timeago, per-entry
read dot, All/Unread filter row, and the same two footer buttons — and needs
no CSS of its own, because it reuses the `.notifications-dropdown` classes
this theme already styles.
Behaviour matches the bell too: opening the box does not mark anything read;
an entry is read when you click it or use "Mark all read", and the dot toggles
both ways. Only the API paths differ, because the list is plugin-owned (core's
unread count is one aggregate with no hook to carve one type out of it).
Every string is a translation key.
## Test plan
- [x] `for f in tests/*.test.js; do node "$f"; done` — all pass, including the
updated topbar contract test
- [x] Live against a dev NodeBB as a `support:viewall` holder: badge count 4,
four rows, per-entry read dot drops the badge to 3, Unread filter hides
the read row, "Mark all read" clears every dot and hides the badge,
empty state reads "Nothing new" — no console errors
- [x] Screenshotted side by side with the real notifications dropdown; the two
are structurally identical
Depends on sow-nodebb-plugin-support#15 for the endpoints.
Generated with Claude CodeReviewed-on: #45
Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
168 lines
9.2 KiB
Markdown
168 lines
9.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project
|
|
|
|
This repository is `nodebb-theme-westgate`, a NodeBB theme for the Shadows Over Westgate forum and website.
|
|
|
|
It is forked from `nodebb-theme-quickstart` and should remain a small, focused NodeBB child theme rather than a full replacement for NodeBB or Harmony.
|
|
|
|
Shadows Over Westgate (SoW) is a Neverwinter Nights persistent-world project.
|
|
Its community forum and wiki run on NodeBB (a Node.js forum platform). This
|
|
theme is the visual layer for that forum. It is consumed by sow-nodebb
|
|
(https://git.westgate.pw/ShadowsOverWestgate/sow-nodebb), which pins this repo
|
|
by exact commit in `plugins.lock` and compiles it into the production forum
|
|
image at image-build time. Switching themes in the Admin Control Panel does
|
|
nothing in production; only the theme pinned and activated in sow-nodebb is
|
|
compiled in.
|
|
|
|
## How It Is Used
|
|
|
|
There is no build step in this repo; NodeBB compiles the SCSS. To see changes
|
|
live, use the `docker-compose.dev.yml` dev loop in sow-nodebb (see How To Test
|
|
below). Release: merge here, re-pin the commit SHA in sow-nodebb's
|
|
`plugins.lock`, rebuild and publish the image there.
|
|
|
|
## How To Test
|
|
|
|
Fast checks, no forum needed:
|
|
|
|
- `node tests/<name>.test.js` — contract tests (topbar, footer, icons, wiki
|
|
tables). There is no `npm test` script; run each file directly.
|
|
- `node scripts/check-emails.js` — when working on email templates.
|
|
|
|
Live visual check against a real forum — **always possible, never skip it**.
|
|
Every change in this repo can be seen in a browser before it ships; there is no
|
|
theme change that can only be checked in production. A unit test cannot tell
|
|
you that a colour is unreadable, so look at the page.
|
|
|
|
Use the sibling checkout at `../sow-nodebb`:
|
|
|
|
1. `cd ../sow-nodebb && cp .env.example .env`, then uncomment the "Theme
|
|
development" block so this working tree is the mounted package:
|
|
`PLUGIN_PATH=../sow-nodebb-theme`, `PLUGIN_ID=nodebb-theme-westgate`,
|
|
`EXTRA_PLUGINS=nodebb-plugin-westgate-wiki nodebb-plugin-westgate-pages`.
|
|
2. `nix develop --command make dev` — the forum comes up at
|
|
`http://localhost:4567` (or `HTTP_PORT`) with this theme already active.
|
|
Dev admin login: `admin` / `Admin12345!` (defaults; dev-only).
|
|
3. NodeBB compiles this theme's SCSS and templates at build time, so a browser
|
|
reload alone is not enough after editing them: `make dev-build`, then
|
|
reload. `make dev-restart` if changes still don't show.
|
|
4. `make dev-reset` wipes everything; required after changing `PLUGIN_*` or
|
|
`EXTRA_PLUGINS` in `.env`.
|
|
|
|
A fresh database is empty, so pages that render content (wiki, categories,
|
|
topics) need seeding first. `../sow-nodebb/AGENTS.md` has the recipes for
|
|
seeding over the REST API, for writing plugin settings straight to Redis, and
|
|
for driving a headless browser on this NixOS box (the Playwright MCP server
|
|
does not work here). Point any browser tooling at `http://localhost:4567` to
|
|
load pages, take screenshots, and compare before/after.
|
|
|
|
**Assume the stack is dirty when you arrive, and leave it clean.** Reset it
|
|
(`make dev-reset`) before the first boot of a testing session and tear it down
|
|
after every cycle, including a failed one; a stack carrying the last session's
|
|
data is the usual reason a screenshot shows something that no longer exists in
|
|
the code. Full hygiene rules live in `../sow-nodebb/AGENTS.md`. Two things
|
|
that bite here in particular:
|
|
|
|
- **Templates and client JS are compiled**, so a browser reload alone proves
|
|
nothing after editing them. `make dev-build` — and note the build marker
|
|
lives on the container filesystem, so a plain `restart` skips the rebuild.
|
|
- **Playwright login on this forum**: the form is `#username` / `#password`
|
|
with a `#login` submit button, and a successful login lands on
|
|
`/?loggedin=true`, which `page.waitForURL('**/')` never matches. Wait on
|
|
`page.waitForLoadState('networkidle')` instead.
|
|
|
|
## Design Context
|
|
|
|
- `PRODUCT.md`: strategic design context — register, users, purpose,
|
|
positioning, brand personality, anti-references, design principles,
|
|
accessibility target (WCAG AA). Read it before design work.
|
|
- `DESIGN.md`: the visual system — palette ("The Velvet Ledger"), typography,
|
|
elevation, components, and do's/don'ts, with machine-readable tokens in its
|
|
frontmatter and `.impeccable/design.json`.
|
|
|
|
## Guidance Map
|
|
|
|
- `README.md` and `GAME_ICONS.md`: repo intro and icon usage notes.
|
|
- `theme.json`, `plugin.json`: theme metadata, hooks, static dirs.
|
|
- `theme.scss` (imports-only) and `scss/`: all styling; `scss/overrides.scss`
|
|
holds pre-Bootstrap variable overrides.
|
|
- `templates/`: Harmony template overrides (same relative paths as Harmony).
|
|
- `custom_pages/`: source content and mockups for custom-pages surfaces.
|
|
- `lib/`, `public/client.js`: server hooks and client behavior.
|
|
- `tests/`: contract tests for topbar, footer, icons, wiki table rendering,
|
|
and the Bootstrap dark-repaint variables. Plain assert scripts: run each with
|
|
`node tests/<name>.test.js`; there is no `npm test` script.
|
|
|
|
## Theme Direction
|
|
|
|
The visual target is black velvet silk, darkness, vampirism, decadence, and decay.
|
|
|
|
Use this palette direction:
|
|
|
|
- Plum and near-black as the dominant base.
|
|
- Muted gold for accents, borders, small highlights, and important affordances.
|
|
- Red only sparingly, preferably as a subtle detail or state color.
|
|
- Avoid bright, playful, clinical, or flat SaaS-style treatment.
|
|
- Favor depth, restraint, texture, and rich contrast over loud ornament.
|
|
|
|
## NodeBB Theme Rules
|
|
|
|
Follow the current NodeBB theme model:
|
|
|
|
- `theme.json` defines theme metadata and the base theme.
|
|
- This project uses `baseTheme: "nodebb-theme-harmony"`.
|
|
- Keep this as a child theme unless the user explicitly asks for a larger rewrite.
|
|
- `theme.scss` is the theme entry point and must stay imports-only.
|
|
- Do not append substantive CSS/SCSS directly to `theme.scss`.
|
|
- Do not add new root-level theme styling files.
|
|
- Put substantive Westgate-specific style overrides under focused files in `scss/`.
|
|
- Keep `scss/overrides.scss` focused on Bootstrap/Harmony variable overrides that must load before Bootstrap.
|
|
- Template overrides belong under `templates/` and must preserve the same relative path as the Harmony template they replace.
|
|
- Do not copy or redefine Harmony templates unless an actual override is needed.
|
|
- If a template does not exist here, NodeBB inherits it from the configured base theme.
|
|
- In the Westgate topbar, notification, chat, draft, and navigation count bubbles must honor NodeBB/Harmony's `hidden` class and only display when there is an actual count to check.
|
|
|
|
NodeBB theme documentation: https://docs.nodebb.org/development/themes/
|
|
|
|
## Current Files Of Interest
|
|
|
|
- `theme.json`: theme metadata and `baseTheme`.
|
|
- `plugin.json`: hooks, scripts, modules, template path, and static dirs.
|
|
- `theme.scss`: NodeBB SCSS entry point.
|
|
- `scss/overrides.scss`: current Westgate override layer.
|
|
- `lib/theme.js` and `lib/controllers.js`: server-side theme hooks/controllers.
|
|
- `public/client.js`: client-side theme behavior.
|
|
- `templates/`: local template overrides and admin templates.
|
|
|
|
## Working Practices
|
|
|
|
- Keep edits scoped to the theme package unless the task explicitly names the NodeBB install.
|
|
- Prefer existing NodeBB, Harmony, Bootstrap, and local theme patterns over introducing new frameworks.
|
|
- Keep selectors maintainable and avoid broad global overrides unless they are intentional theme-wide tokens or resets.
|
|
- Avoid unrelated formatting churn.
|
|
- Before overriding a template, inspect the corresponding Harmony template and copy only what is necessary.
|
|
- Preserve accessibility: readable contrast, visible focus states, usable hover/active states, and no text hidden purely for visual effect unless there is an accessible alternative.
|
|
|
|
## Tests
|
|
|
|
Tests must survive harmless changes to constants, defaults, wording, ordering, fixture data, and internal implementation details. A test that fails merely because a basic value changed is usually a bad test. Only assert exact values when the value is part of a documented public contract, external protocol, compatibility requirement, security rule, migration, or business rule.
|
|
|
|
## Agent skills
|
|
|
|
### Issue tracker
|
|
|
|
Issues live in Gitea at git.westgate.pw (`ShadowsOverWestgate/sow-nodebb-theme`), managed with the `tea` CLI. Issues follow ownership — file work in the repo that owns it, not the one you happen to be standing in. See `docs/agents/issue-tracker.md`.
|
|
|
|
### Triage labels
|
|
|
|
Default label vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
|
|
|
|
### Domain docs
|
|
|
|
Single-context: `CONTEXT.md` at the repo root plus `docs/adr/`. See `docs/agents/domain.md`.
|
|
|
|
### Where work lives
|
|
|
|
Markdown here is **reference, law, or an ADR — nothing else** (`sow-codebase` ADR-0001). Live work -> wayfinder maps + Gitea issues (closeable, assignable, queryable). Settled decisions -> ADR files in `docs/adr/` (immutable, never closed, only superseded). Standing law -> `DOCTRINE.md` / `AGENTS.md` / `CONTEXT.md`. Current-state reference -> docs describing what the code does now. Everything else — plans, specs, concepts, handoffs, trackers — is process: it belongs in a Gitea issue, not a file. Harvest unfinished intent to an issue before deleting a process doc. `sow-docs` is deprecated and read-only.
|