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	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

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

Templ Syntax Quick Ref

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

# 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