# MNW Frontend

Server-rendered HTML via Askama templates, HTMX for interactivity, hand-authored CSS. No JS framework. There is one build step: `frontend/` is TypeScript compiled to `static/dist/`, and the tab strips and several other regions are described in Rust under `src/quasi/` and rendered into the templates as strings.

## Design System

Typography and brand colors come from the cross-project brand system (three-tier type system, base palette, diamond mark rule). `docs/design-system.md` is the charter and the source of truth for token names; this file records how templates and CSS use them.

### Where the tokens live

| Group | Tokens | File |
|-------|--------|------|
| Surfaces | `--surface-page`, `--surface-raised`, `--surface-sunken`, `--surface-overlay`, `--surface-well`, `--bevel-light`, `--bevel-dark` | `static/style.css` `:root` |
| Content | `--content`, `--content-secondary`, `--content-muted`, `--content-on-action` | `static/style.css` `:root` |
| Action and status | `--action`, `--action-hover`, `--success`, `--warning`, `--danger`, `--info` | `static/style.css` `:root` |
| Lines and focus | `--border`, `--border-strong`, `--focus-ring`, `--hover-surface`, `--overlay` | `static/style.css` `:root` |
| Typeface | `--font-mono`, `--font-sans`, `--font-display` | `static/typography.css` (generated) |
| Type size, spacing, radius | `--text-*`, `--gap-*`, `--radius-*` | `static/geometry.css` (generated) |

The `:root` block in `style.css` holds the platform default. Creator profile, project and item pages inject a `<style>` that supersedes it with the chosen theme, so every one of these is themeable.

### Rules

- **No pure white/black.** Use `--surface-page` and `--content` instead.
- **Accent color is for the dot only.** Do not use `--action` for arbitrary borders or decoration.
- **No hex or `rgba()` literals outside `:root`.** Every colour elsewhere is a `var()` or a `color-mix()` over one. Write the token, not `var(--token, #fallback)`.

## Template Structure

```
templates/
  base.html                    Head from crate::shell, page blocks, footer, script tail
  index.html                   Landing page
  pages/                       Full page templates (extend base.html)
    login.html, discover.html, item.html, project.html, library.html, ...
  dashboards/                  Dashboard pages (extend base.html, tabbed)
    dashboard-user.html        User dashboard (Projects, Payments, Analytics, Settings, Support)
    dashboard-project.html     Project dashboard (Overview, Content, Analytics, Monetization, Code, Cloud Sync, Settings)
    dashboard-item.html        Item dashboard (Overview, Details, Pricing, Files, Sales)
    dashboard-blog-editor.html, dashboard-export.html, dashboard-import.html
    admin-*.html               Admin panels (waitlist, users, uploads, appeals, reports, metrics)
  wizards/                     Multi-step create flows (join, project, item)
  partials/                    HTMX fragments (no base.html, returned directly)
    tabs/                      Dashboard tab and settings-section content
      user_profile.html, user_account.html, user_payments.html,
      user_creator.html, user_media.html, user_sessions.html,
      user_settings.html, user_synckit.html
      project_code.html, project_monetization.html, project_promotions.html,
      project_settings.html, project_subscriptions.html, project_synckit.html
      item_details.html, item_embed.html, item_overview.html, item_pricing.html
      library_collections.html, library_purchases.html
    admin_*.html               Admin table rows (HTMX swap targets)
    _ui.html                   Shared Askama macros
    alert.html, form_status.html, save_status.html  Status feedback fragments
```

### Conventions

- Full pages extend `base.html` and define `{% block content %}`.
- The document head is not written in `base.html`. `crate::shell::head()` emits it, so a described screen that owns its whole document and an Askama page get the same head.
- Tab content is loaded via HTMX (`hx-get="/dashboard/tabs/payments"` etc).
- Partials are standalone HTML fragments, no `{% extends %}`.
- Template structs live in `src/templates/dashboard.rs` (pages), `src/templates/partials.rs` (fragments), `src/templates/public/` (landing, auth, git, health) and `src/templates/embed.rs`.

## CSS Architecture

Five stylesheets, loaded in this order by `crate::shell::head()`: `typography.css`, `geometry.css`, `timing.css`, `layout.css`, `style.css`. The first four are generated by `build.rs` through makeover-build and are marked do-not-edit at the top of each file. `style.css` is the only hand-authored one. No preprocessor, no minification pipeline.

### Section Order

`style.css` opens with a FILE STRUCTURE comment that indexes every section by name; search the file for a section name to jump to it. The order is:

1. **Foundations** (`@font-face`, `:root` tokens, element base)
2. **Buttons** (`.btn-primary`, `.btn-secondary`, `.btn-danger`, plus `.small` / `.btn-compact` / `.btn-link` / `.btn-tiny` modifiers)
3. **Forms** (`.form-group`, `.form-section`, `.field-row`, the `input--*` modifiers)
4. **Tabs** (`.tabs`, `.tab`, `.tab.chosen`)
5. **Tables** (`.data-table`, then `.compact-table`)
6. **Utilities** (spacing, sizing, text, state, shapes)
7. **Badges** and **Tags**
8. **Cards** and **Stats** (`.card`, `.card-muted`, `.card--bordered`, `.stat-box`)
9. **Filter bar**, **Discussion**, **Notification surfaces** (the `.info-box` / `.warning-box` / `.error-message` roles)
10. **Page-scoped layouts**, the long run: error, buy, sectioned content, item, project, library, article, admin, import wizard, delete account, export, receipt, Fan+, purchase, project settings, cart, profile
11. **Sections, Navigation, Header and footer, Layout utilities, Specific components**, then **HTMX loading indicators**, **Toast**, **Save status**, **HTMX transitions**, **Focus styles**, **Paywall**, **Modals**
12. A second, larger run of **page-scoped layouts** (landing, docs, use cases, git browser, discover, and one section per tab or partial), ending with **Layer handoffs**, the **described modal** and the **media picker**

The notification-surface primitives are not all in the section that names them: `.empty-state` sits in Utilities, `.banner` just above Sections, `.toast` and `.modal` in their own sections after Specific components, `.progress-bar` with the audio upload, `.callout` in the Account tab section and `.alert` with the documentation pages. Search the file for the class, not for the section.

Responsive rules are not all at the end either: the 768px and 480px blocks sit in the middle of the second page-scoped run, and the later sections carry their own `@media` queries.

### Utility Classes

| Class | Styles | Use for |
|-------|--------|---------|
| `.text-sm` | `font-size: var(--text-note)` | Secondary text (emails, dates) |
| `.text-xs` | `font-size: var(--text-fine)` | Tertiary text (IDs, annotations) |
| `.muted` | `opacity: 0.7` | De-emphasized content |
| `.dimmed` | `opacity: 0.6` | Further de-emphasized |
| `.dimmer` | `opacity: 0.5` | Furthest de-emphasized |
| `.meta` | `font-size: var(--text-note); opacity: 0.7` | Labels, captions |
| `.nowrap` | `white-space: nowrap` | Dates, status badges |
| `.scroll-x` | `overflow-x: auto; -webkit-overflow-scrolling: touch` | Horizontal scroll wrappers |
| `.text-center` | `text-align: center` | Centered blocks |
| `.text-right` | `text-align: right` | Right-aligned cells |
| `.fw-bold` | `font-weight: bold` | Emphasis without a heading |
| `.small` | `padding: var(--gap-bound) var(--gap-group); font-size: var(--text-fine)` | Compact buttons in tables |
| `.empty-state` | `text-align: center; padding: var(--gap-page); opacity: 0.6` | Empty list messages |

### Table Classes

**`.data-table`**: Full-featured tables with alternating row backgrounds, hover states, and sortable headers. Used for transactions, blog posts, content items.

**`.compact-table`**: Lighter admin/dashboard tables. Provides `width: 100%`, `border-collapse`, cell padding, header styling and row borders. Used for admin user/waitlist/upload tables, invite codes, wave history.

### Badges

`.badge` is the base. Tone comes from a `data-tone` attribute rather than a modifier class:

```html
<span class="badge" data-tone="success">Trusted</span>
```

`success`, `warning` and `danger` are the tones. The modifiers that exist beside them are `.badge--founder-locked`, `.badge--founder-pending`, `.badge--inline-l`, `.badge--inline-tiny`, `.badge-new`, the `.badge.ai-tier*` disclosure set and `.badge.is-faded`.

### Button Variants

Buttons use the `.btn-*` family. See `design-system.md` § Buttons for the current class names, colors, and modifiers. Do not use the bare `.primary` / `.secondary` / `.danger` classes; use `.btn-primary`, `.btn-secondary`, `.btn-danger`.

## HTMX Patterns

### Tab Navigation

Tab strips are not written as markup. Each one is described in Rust and rendered into its Askama page as a string: `src/quasi/user_tabs.rs`, `project_tabs.rs`, `item_tabs.rs`, `library_tabs.rs` and `settings_tabs.rs`. The page passes the result through:

```html
{{ tabs|safe }}
```

The description names each tab, the region its panel lands in, and what fetches that panel:

```rust
let mut strip = Slot::new(STRIP, RegionKind::TabGroup)
    .across(layout::Fallback::Menu)
    .showing_one(shown);

for (at, tab) in tabs.iter().enumerate() {
    let mut region = Slot::bespoke(tab.panel, "item-panel").label(tab.label);
    if at != shown {
        region = region.fed_by(
            Action::get(format!("/dashboard/item/{item_id}/tabs/{}", tab.route))
                .awaiting()
                .replacing(tab.panel),
        );
    }
    strip = strip.with(Node::Region(region));
}
```

Three things follow from this and are worth knowing before touching a strip.

- **Each panel is its own region.** There is no single `#tab-content` pane for every tab to swap into, so an action outside the strip names the panel it means (`#item-sales`, `#user-settings`).
- **The shown tab is rendered inline by the page handler** and is the one tab that does not fetch. The page arrives at final geometry rather than fetching its first panel after load.
- **A deep link is a `?tab=` query**, read server-side by each module's `shown_at`, not a `#tab-*` hash restored by JS. Unknown names answer the first tab.

`Action::awaiting()` is what an act in flight says. There is no `setActiveTab`, no `tab-spinner` indicator and no hash restore.

### Admin Table Updates

Admin actions (suspend, approve, trust) return the full table partial to replace the table body:

```html
<button class="btn-secondary small"
        hx-post="/api/admin/users/{{ user.id }}/trust"
        hx-target="#users-table"
        hx-swap="innerHTML">Trust</button>
```

### Form Feedback

Form submissions target a status element for inline feedback:

```html
<form hx-put="/api/users/me"
      hx-target="#profile-save-status"
      hx-swap="innerHTML"
      hx-indicator="#profile-spinner">
```

The handler returns an `AlertTemplate` or `FormStatusTemplate` partial. `hx-indicator` is the idiom in Askama markup; a described region uses `Action::awaiting()` instead.

### CSRF

All mutating requests include CSRF tokens. `base.html` emits a `csrf-token` meta tag. `frontend/src/core/net.ts` reads it and returns the `X-CSRF-Token` header from `csrfHeaders()`, which `core/index.ts` also exports on `window` for hand-written `fetch()` calls. HTMX requests get the header from `frontend/src/core/htmx-glue.ts`, which attaches it on `htmx:config:request`. The token is read live on every request because it rotates mid-session.

## JavaScript

Two layers. `frontend/src/` is TypeScript, compiled to `static/dist/` and loaded as a module. Everything else in `static/` is hand-written JS loaded with a plain `<script>`.

| File | Purpose |
|------|---------|
| `frontend/src/core/dispatch.ts` | Delegated event dispatcher: `data-action`, `data-change`, `data-input`, `data-submit`, `data-after` |
| `frontend/src/core/net.ts` | `csrfHeaders()` and the fetch helpers |
| `frontend/src/core/toast.ts` | `showToast(message)` |
| `frontend/src/core/htmx-glue.ts` | htmx lifecycle hooks |
| `static/htmx.min.js` | HTMX library (vendored), plus the `hx-history-cache` and `hx-prompt` extensions |
| `static/quasi-*.js` | The renderer's behaviour modules, one per described capability |
| `static/actions-*.js` | Verb registration shims for pages, partials, tabs and dashboards |
| `static/passkey.js` | WebAuthn passkey registration and authentication |
| `static/upload.js` | `S3Uploader`, file upload with progress bars |
| `static/page-*.js`, `tab-*.js`, `wizard-*.js` | Per-screen behaviour, loaded by the screen that needs it |

### Conventions

- No inline `<script>` in templates and no `on*` or `hx-on::` attributes. `script-src 'self'` with no `unsafe-inline` is enforced, and logic in an attribute value breaks it.
- Behaviour is named with a verb in `data-action` and resolved against the dispatcher's registry. Never invent a private attribute for a behaviour; add a verb.
- Use `csrfHeaders()` for all `fetch()` calls.
- Use `showToast(message)` for user notifications.
- Use `hx-confirm` for destructive actions.
- No external JS dependencies beyond HTMX.
- No JS framework, vanilla DOM manipulation only.
- `_hyperscript` is declined permanently. See `design-system.md` § Interaction idioms.

## Static Assets

```
static/
  style.css           Main stylesheet
  typography.css      Generated: the three typeface tokens
  geometry.css        Generated: type size, spacing, radius tokens
  timing.css          Generated: duration tokens
  layout.css          Generated: layout primitives and the bevel pair
  wizard.css, media-player.css, no-js.css, embed-*.css   Loaded per screen
  htmx.min.js         HTMX library
  dist/               Compiled output of frontend/src (core/ and islands/)
  quasi-*.js          Renderer behaviour modules
  actions-*.js        Verb registration shims
  passkey.js          WebAuthn integration
  upload.js           File upload with progress
  fonts/              Quasi Body, Quasi Mono (woff2), Young Serif (ttf + woff2)
  images/             Logo, favicons, og-card, screenshots
  bases/              Content-addressed theme base images
  patterns/           Background SVGs
```

## Progressive Disclosure

The dashboard conditionally shows features based on user state. The gates are the `Gate` enums in the tab-strip modules, not template conditionals:

- **Projects and Analytics tabs** (`src/quasi/user_tabs.rs`): only visible when `can_create_projects` is true.
- **Every user tab except Support**: hidden once the account is deactivated. Support is the one tab a deactivated account keeps, because it is the only thing it can do.
- **Media settings section** (`src/quasi/settings_tabs.rs`): only when the reader can create projects.
- **SSH Keys settings section**: only when git hosting is enabled on the server.
- **Forums settings section**: only when the Multithreaded integration is configured.
- **Cloud Sync settings section**: only when the reader owns at least one sync app.
- **Code tab** (`src/quasi/project_tabs.rs`): only when the project has git enabled.
- **Cloud Sync tab** (project dashboard): only when SyncKit is configured for the project.
- **Files tab** (`src/quasi/item_tabs.rs`): absent on a bundle, which carries other items rather than files of its own.
- **Onboarding checklist**: auto-dismissed when all steps complete (or manually skipped).

## Key Paths

| What | Where |
|------|-------|
| CSS | `static/style.css`, `static/layout.css` |
| Generated tokens | `static/typography.css`, `static/geometry.css`, `static/timing.css` |
| Document head and script tail | `src/shell.rs` |
| Base template | `templates/base.html` |
| Dashboard pages | `templates/dashboards/` |
| Tab partials | `templates/partials/tabs/` |
| Admin partials | `templates/partials/admin_*.html` |
| Described regions | `src/quasi/` |
| Template structs | `src/templates/dashboard.rs`, `src/templates/partials.rs` |
| Dashboard handlers | `src/routes/pages/dashboard/` |
| TypeScript core | `frontend/src/core/` |
| JS (passkeys) | `static/passkey.js` |
| JS (uploads) | `static/upload.js` |