nebula/AGENTS.md

# NEBULA PROJECT KNOWLEDGE BASE

**Generated:** 2026-01-11 | **Commit:** fcbe848 | **Branch:** feat/pkg

## OVERVIEW

Go/Templ wallet UI framework using HTMX 4 for server-driven interactions and WebAwesome (`wa-*`) web components. Hybrid: root is a library (`package nebula`), `cmd/server/` is the reference app.

## STRUCTURE

```
nebula/
├── cmd/server/       # App entry: main.go + routes.go (handlers HERE, not handlers/)
├── views/            # Page templates (.templ) - XxxPage, XxxContent, XxxWithStepper
├── components/       # Reusable UI (sidebar, stepper, navbar, charts)
├── layouts/          # Base (HTML shell), App (dashboard), Centered (auth)
├── models/           # Data structs + DefaultXxxData() factories
├── htmx/             # HTMX 4 context/request/response helpers
├── pkg/config/       # Config models for middleware injection
├── _migrate/         # HTML prototypes pending conversion (technical debt)
├── middleware.go     # Injects HTMX + Config into request context
├── mount.go          # Mount() helper for handler registration
├── options.go        # WithXxx() functional options
└── config.go         # DefaultConfig() + Config struct
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| Add route | `cmd/server/routes.go` | Go 1.22+ patterns: `GET /path/{param}` |
| Add page | `views/` + `models/` | Create XxxPage + model, register in routes.go |
| HTMX patterns | `HTMX.md` | `<hx-partial>`, morphing, SSE, OOB updates |
| Modify layout | `layouts/base.templ` | CDN scripts, htmx-config meta tag |
| WebAwesome ref | [webawesome.com](https://webawesome.com) | All `wa-*` components |
| Migrate HTML | `_migrate/` -> `views/` | See MIGRATION.md |

## CONVENTIONS

### Naming

| Type | Pattern | Example |
|------|---------|---------|
| Page template | `XxxPage(data)` | `DashboardPage(data, tab)` |
| Partial (HTMX) | `XxxContent`, `XxxTab` | `DashboardContent(data, tab)` |
| OOB update | `XxxWithStepper`, `XxxWithOOB` | `WelcomeStepWithStepper(step)` |
| Model | `XxxData`, `XxxState` | `DashboardData`, `LoginState` |
| Factory | `DefaultXxxData()` | `DefaultDashboardData()` |
| Handler | `handleXxx` | `handleDashboard` |

### HTMX 4 Request Pattern

```go
func handleXxx(w http.ResponseWriter, r *http.Request) {
    data := models.DefaultXxxData()
    if r.Header.Get("HX-Request") == "true" {
        views.XxxContent(data).Render(r.Context(), w)  // Partial
        return
    }
    views.XxxPage(data).Render(r.Context(), w)  // Full page
}
```

### OOB Updates (Multi-Target)

```templ
templ XxxStepWithStepper(step int) {
    @XxxStepContent(step)
    <div id="stepper-container" hx-swap-oob="innerHTML">
        @components.Stepper(step, steps)
    </div>
}
```

### Templ Syntax Quick Ref

```templ
if cond { }                          // Conditional
for _, item := range items { }       // Loop
<input disabled?={ isDisabled } />   // Bool attr
<div class={ "base " + extra }>      // String interpolation
@ChildComponent(props)               // Composition
@templ.Raw(html)                     // Raw HTML (avoid)
```

## ANTI-PATTERNS (THIS PROJECT)

| DO NOT | Why |
|--------|-----|
| Edit `*_templ.go` files | Generated by `templ generate` - changes purged |
| Use separate `htmx-ext-*` packages | HTMX 4 bundles extensions at `/dist/ext/` |
| Rely on implicit inheritance | Use `:inherited` modifier (`hx-target:inherited`) |
| Use `TopBar` or `TopBarStyles` | DEPRECATED - use `wa-page` slots instead |
| Manual DOM manipulation | Use `hx-*` attributes; server controls state |
| Put handlers in `handlers/` | Docs outdated - use `cmd/server/routes.go` |

## COMMANDS

```bash
# Generate templ (REQUIRED after .templ changes)
templ generate

# Dev server on :8080
go run ./cmd/server
# OR
make start

# Full cycle: generate + start + open browser
make all

# Build binary
make build  # outputs ./nebula

# Watch mode
templ generate --watch
```

## STACK VERSIONS

- **Go**: 1.25.5 (cutting-edge)
- **templ**: v0.3.977
- **htmx**: 4.0.0-alpha5 (CDN)
- **WebAwesome**: Kit 47c7425b971f443c (CDN)
- **D3.js**: v7 (charts)

## NOTES

- **No tests exist** - `go test ./...` returns "no test files"
- **No CI/CD** - No `.github/workflows/`
- **SQLite WASM** mentioned in docs but not implemented
- **Documentation references `handlers/`** - doesn't exist; handlers are in `cmd/server/routes.go`
- Config split: root `config.go` (app config) vs `pkg/config/` (HTMX feature flags)
- Middleware chain: `nebula.Middleware(opts...)(mux)` injects context for templates