# tui-pages website

Static marketing site for the [`tui-pages`](https://gitlab.com/filipriec/tui-pages) Rust crate.
No build step required — open `index.html` in a browser and you're done.

## Stack

| Layer | Tech | Source |
| --- | --- | --- |
| HTML | Hand-written semantic | `*.html` |
| CSS framework | Tailwind CSS v3 (Play CDN) | runtime |
| Components | DaisyUI v4 (prebuilt CSS) | runtime |
| Interactivity | HTMX 2 | runtime |
| Light JS | Alpine.js 3 | runtime |
| Code highlight | highlight.js 11 (Rust, TOML, Bash) | runtime |
| Fonts | Inter + JetBrains Mono (Google Fonts) | runtime |
| Icons | Lucide (inline SVG) | hand-written |
| Page transitions | View Transitions API (native) | n/a |

Everything is loaded from public CDNs. The only thing served from this repo is
the HTML, our small `static/css/site.css` layer, and the SVG assets in
`static/img/`.

## Local development

```bash
# Just open the file
xdg-open index.html     # Linux
open index.html         # macOS

# Or serve it (recommended — gives you a stable URL for htmx)
python3 -m http.server 8000
# then visit http://localhost:8000
```

The `Makefile` wraps the Python server and a few convenience commands:

```bash
make serve       # python3 -m http.server 8000  (serves the WORKING TREE — use this while iterating)
make size        # report file sizes
make validate    # quick HTML syntax check (search for unclosed tags)
make tidy        # run html-tidy on every .html (warnings only)
make video NAME=foo   # regenerate the ASCII background from video/foo.mp4
```

> **Note:** `make serve` reads from the working tree (so it picks up the latest
> `static/js/mountain.js` after a `make video`). For a production build, use
> `nix run .#serve` — but note that the Nix build only includes **git-tracked**
> files, so you must `git add` your new `mountain.js` (and any other new files)
> before `nix run .#serve` will pick them up.

## Animated ASCII video background

The page background is an **animated chafa ASCII playback of a video**, running
at 12 fps behind the entire page. `ffmpeg` extracts frames from a video you
provide; `chafa` converts each frame to an 80 × 24 ASCII grid; a bundler
(`tools/build_mountain_js.py`) concatenates all grids into a single JS array
(`static/js/mountain.js`). A tiny cycler (`static/js/mountain-bg.js`) swaps
`textContent` on a single `<pre>` every ~83 ms.

### Swap the video

1. Drop a `.mp4` in `video/`:

   ```bash
   cp ~/Videos/my-clip.mp4 video/myclip.mp4
   ```

2. Build it into the site (run inside the nix dev shell for ffmpeg + chafa):

   ```bash
   nix develop -c make video NAME=myclip
   ```

   This runs three steps:
   - `make video-frames NAME=myclip` — `ffmpeg` extracts PNGs at 12 fps into `build/myclip/`, then `chafa -s 80x24 --symbols ascii` produces ASCII for each
   - `make video-bundle NAME=myclip` — bundles all `frame-*.txt` into `static/js/mountain.js`
   - the wrapper `make video` does both

3. Serve and view:

   ```bash
   make serve
   # → http://localhost:8000
   ```

### Helper targets

```bash
make video-list              # show available videos in video/
make video-frames NAME=foo   # only extract + chafa, skip the bundle
make video-bundle NAME=foo   # only re-bundle from an existing build/foo/
```

### Tuning

- **Frame rate** — edit `Makefile` `fps=12` in the `video-frames` target. If
  you change it, also update `TP_MOUNTAIN_FPS` at the bottom of
  `static/js/mountain.js` (regenerated automatically each `make video`).
- **ASCII resolution** — `-s 80x24` in the `chafa` call. Wider/higher = larger
  bundle, more detail.
- **Bundle size** — the resulting `static/js/mountain.js` is `~1.7 kB × N_FRAMES`
  (333 kB for a 15 s clip at 12 fps). For long videos, drop `fps` or downscale
  the source video first.
```
       ↓ chafa -s 80x24
build/mountain/frame-*.txt   intermediate ASCII grids
       ↓
static/js/mountain.js        bundled 60-frame array (≈120 kB)
       ↓ requestAnimationFrame
DOM <pre.tp-mountain-frame>  what you actually see, 12 fps
```

To re-render (you need `chafa` and `python3` on `$PATH`, or use `nix develop`):

```bash
make mountain          # frames + bundle, end-to-end
make mountain-frames   # just the PNG + ASCII frames
make mountain-bundle   # just rebundle the JS array from existing frames
```

### How it's wired

- `static/js/mountain.js` exposes `window.TP_MOUNTAIN_FRAMES` (an array of
  60 template strings) plus `TP_MOUNTAIN_N_FRAMES = 60` and
  `TP_MOUNTAIN_FPS = 12`.
- `static/js/mountain-bg.js` mounts a `<pre class="tp-mountain-frame"
  aria-hidden="true">` to `document.body`, sets the first frame as
  `textContent`, then cycles with `requestAnimationFrame` and a
  `setInterval`-style accumulator so frame drops don't desync.
- The script pauses when `document.hidden` is true (no wasted CPU on
  backgrounded tabs) and respects `prefers-reduced-motion: reduce` by
  showing a single mid-loop frame and not animating.
- Style lives in `static/css/ascii.css`:
  - `position: fixed; inset: 0; z-index: 0` — full-bleed, behind page content
  - `color: #f4a26b` (rust-orange) with a 0.45 opacity and a soft
    `text-shadow` glow — picks up the brand colour
  - `font-family: 'JetBrains Mono'` for the in-browser renderer
  - A `::after` pseudo-element overlays a 2 px CRT scanline pattern that
    ticks downward at 8 s/cycle
  - Light theme (`data-theme="winter"`) drops the glow, dims the opacity
    to 0.20, and switches the scanlines to white-on-transparent
  - The scanline animation is killed inside
    `@media (prefers-reduced-motion: reduce)`

The hero (`#hero`) is **not** part of the mountain background — it keeps
the original static `static/img/terminal-default.svg` mockup, exactly as
designed. The terminal sits on top of the mountain as a discrete card.

### Tuning the animation

The renderer is parameterized at the top of `tools/mountain.py`:

| Constant | Default | What it does |
| --- | --- | --- |
| `W, H` | 320 × 200 | Output PNG resolution |
| `N_FRAMES` | 60 | How long the loop is |
| `HORIZON_FRAC` | 0.45 | Sky height as a fraction of the image |
| `SEED` | deterministic | Heightmap random seed |
| `STEPS` | 80 | Forward steps per frame in camera space |

Bump `W`/`H` for sharper terrain, or `--symbols ascii+block+half` in the
chafa call inside `tools/build_mountain_js.py` for denser glyphs. Both
changes require a `make mountain` rebuild and a higher page weight
(mountain.js is currently ≈120 kB).

## Nix (optional, recommended)

A `flake.nix` is included that ships a reproducible dev shell, a buildable
package, a `serve` app, and an `html-tidy` check. You do **not** need Nix to
use this project — it's a convenience.

```bash
# Enter the dev shell (gives you: gnumake, python3, asciinema, html-tidy, …)
nix develop

# Build the whole site → ./result/  (16 files, ~150 kB, ready to upload)
nix build
ls result/

# Build + serve on http://localhost:8000  (or $PORT)
nix run .#serve

# Validate the HTML, format the flake
nix flake check
nix fmt
```

### What the flake provides

| Output | Command | What it does |
| --- | --- | --- |
| `packages.<sys>.default` | `nix build` | Assembles the static site into a single derivation |
| `apps.<sys>.serve` | `nix run .#serve` | Builds the package, then `python3 -m http.server` it |
| `devShells.<sys>.default` | `nix develop` | Shell with `make`, `python3`, `asciinema`, `tidy`, `curl` |
| `checks.<sys>.tidy` | `nix flake check` | Runs `html-tidy` over every `.html` in the built site |
| `formatter.<sys>` | `nix fmt` | `nixpkgs-fmt` for the flake itself |

### Why no Rust toolchain?

The crate lives in `../komp_ac/tui-pages/`. This repo only contains the
*static* website, so the flake intentionally omits `rust-overlay` and a
`rustPlatform` — they would add hundreds of MB to the shell closure for
nothing. When the site eventually gains a Rust backend, those inputs come
back.

### Why the per-system pattern?

Mirrored from the upstream Codex CLI flake so future contributors see a
shape they already recognise. `forAllSystems` is a one-liner that
guarantees `linux`/`darwin` × `x86_64`/`aarch64` parity without sprinkling
`if` branches across the file.

## Going to production

The CDN approach is fine for marketing pages. For better performance
(smaller CSS, no runtime Tailwind compile), swap the Play CDN for the
**Tailwind standalone CLI**:

```bash
# 1. Download the standalone CLI
#    https://tailwindcss.com/blog/standalone-cli

# 2. Put the binary in ./bin/tailwindcss

# 3. Create src/site.css that imports Tailwind and DaisyUI:
#        @import "tailwindcss";
#        @plugin "daisyui";

# 4. Build
./bin/tailwindcss -i src/site.css -o static/css/site.css --minify
```

Then in `index.html` remove the Tailwind Play CDN `<script>` and the DaisyUI
`<link>`, and ensure `/static/css/site.css` is loaded last in `<head>`.

## File layout

```
tui-pages-web/
├── index.html              # landing page
├── examples.html           # examples gallery
├── 404.html                # not found
├── robots.txt              # search engine hints
├── sitemap.xml             # sitemap
├── tools/
│   ├── mountain.py             # pure-Python 3D-mountain PNG renderer
│   └── build_mountain_js.py    # bundles 60 ASCII frames into mountain.js
├── static/
│   ├── css/
│   │   ├── site.css        # our custom layer (small)
│   │   └── ascii.css       # animation rules for the mountain background
│   ├── img/
│   │   ├── favicon.svg
│   │   ├── logo.svg
│   │   ├── og-image.svg        # 1200x630 social share card
│   │   ├── terminal-default.svg
│   │   ├── terminal-canvas.svg
│   │   └── terminal-keybindings.svg
│   ├── js/
│   │   ├── mountain.js         # 60-frame ASCII array (≈120 kB)
│   │   └── mountain-bg.js      # requestAnimationFrame cycler
│   └── demos/              # (empty — drop asciinema .cast files here)
├── content/                # (empty — markdown for blog/changelog later)
├── flake.nix               # Nix dev shell, package, app, checks
├── flake.lock              # (generated — pinned nixpkgs)
├── Makefile
├── .gitignore
└── README.md
```

## Adding an asciinema demo to the hero

The hero currently shows the **static SVG mockup**
`static/img/terminal-default.svg`. To replace it with a real asciinema
recording (much more impressive, but requires a recorded cast):

1. Record one of the examples:

   ```bash
   cd ../komp_ac/tui-pages/examples/default
   asciinema rec ../../tui-pages-web/static/demos/intro.cast
   # ... run the app for a few seconds, hit ctrl-d to stop
   ```

2. In `index.html`, replace the `<!-- Hero terminal mockup -->` block
   with:

   ```html
   <div class="tp-terminal">
     <asciinema-player src="/static/demos/intro.cast" autoplay loop></asciinema-player>
   </div>
   ```

3. Add the asciinema player to the `<head>`:

   ```html
   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.css">
   <script src="https://cdn.jsdelivr.net/npm/asciinema-player@3.7.0/dist/bundle/asciinema-player.js" defer></script>
   ```

The 3D-mountain ASCII background is independent of the hero and stays as-is.

## License

The website source is MIT-licensed. The terminal mockup SVGs in `static/img/`
are hand-drawn and original. The crate itself is at
<https://gitlab.com/filipriec/tui-pages>.