# Frontend Asset Builds

All CSS and TypeScript is compiled from source — never edit `app.css` or `app.js` directly.

## Source vs output

Source files live in `src/` at the repo root. Compiled artifacts land in `static/`.

```
src/
  ts/          ← TypeScript source (input to esbuild)
    app.ts
    musehub.ts
    pages/*.ts
  scss/        ← SCSS source (input to sass)
    app.scss
    embed.scss
    _*.scss    ← partials, imported by app.scss

musehub/templates/musehub/static/
  app.js       ← compiled output (do not edit)
  app.css      ← compiled output (do not edit)
  embed.css    ← compiled output (do not edit)
  alpinejs.min.js
  htmx.min.js
  vendor/
```

## Quick reference

| Task | Command |
|------|---------|
| Rebuild everything (CSS + JS + embed) | `npm run build` |
| CSS only | `npm run build:css` |
| JS only | `npm run build:js` |
| Embed stylesheet | `npm run build:embed` |
| Embed player JS | `npm run build:embed-player` |
| TypeScript type-check (no output) | `npm run type-check` |
| Watch CSS during development | `npm run watch:css` |
| Watch JS during development | `npm run watch:js` |

Run all commands from the repo root (`~/ecosystem/musehub`).

## Source → output mapping

| Asset | Source | Output |
|-------|--------|--------|
| Main stylesheet | `src/scss/app.scss` | `musehub/templates/musehub/static/app.css` |
| Embed stylesheet | `src/scss/embed.scss` | `musehub/templates/musehub/static/embed.css` |
| Main JS bundle | `src/ts/app.ts` | `musehub/templates/musehub/static/app.js` |
| Embed player JS | `src/ts/embed-player.ts` | `musehub/templates/musehub/static/embed-player.js` |

`src/scss/app.scss` imports all SCSS partials from `src/scss/_*.scss`. Add new partials there, not inline.

## When to rebuild

Rebuild whenever you change any `.scss` or `.ts` file. The server serves the compiled files
directly — it does not compile on the fly.

`npm run build` also writes `musehub/templates/musehub/static/.cache-id` with a timestamp.
The base template reads this file to generate the `?v=<timestamp>` query string on every
static asset URL, which busts the browser cache automatically after each rebuild.

## CSS not updating in the browser?

1. Run `npm run build` (or `npm run build:css` for CSS only).
2. Hard-refresh: **Cmd+Shift+R** (macOS) / **Ctrl+Shift+R** (Linux/Windows).

If the page still looks wrong, check that you rebuilt to the right output path:

```
musehub/templates/musehub/static/app.css   ✅ correct
musehub/templates/musehub/static/css/app.css  ❌ wrong — served at /static/css/app.css, not /static/app.css
```

## Development workflow

Open two terminals:

```bash
# Terminal 1 — watch CSS
npm run watch:css

# Terminal 2 — watch JS
npm run watch:js
```

Changes to any `.scss` or `.ts` file are compiled instantly. Because the watch builds omit
the cache-id update, you may need an occasional hard-refresh during development.

## Prerequisites

Node.js and the dev dependencies must be installed:

```bash
npm install   # installs esbuild, sass, typescript — runs from repo root
```

`sass` and `esbuild` run on the host (not inside Docker). The compiled output files are
bind-mounted into the container via `docker-compose.override.yml`, so the server picks up
the new files without a restart.