# AGENTS.md — Elm News-Site Layout Benchmark

Instructions for LLM agents working in this project. Read all of it before writing code.

## 1. Task Definition

Build a mockup layout for a news website in Elm, compiled to static files served from `public/`.

### Requirements

- **Title:** "Test News Site" (banner).
- **Layout:** short top banner + 3 columns:
  - Left column (~20% width): simple nav with Home, Local News, Breaking News.
  - Center column (~60% width): feature area — cards with an image, headline, and excerpt.
  - Right column (~20% width): listing of additional news — headlines with URLs.
- **Banner size:** ~2 cm on a desktop screen; ~25% of a vertical mobile screen height.
- **Theme colors:** light gray background, dark gray text, dark blue links.
- **Responsive** to mobile, tablet, and desktop widths.
- **Data-driven:** build the center and right columns by looping over arrays.
  - Center-column array items: `{ headline, url, imageUrl }` where images live in `public/images/`.
  - Right-column array items: `{ headline, url }`.

### Static-file requirements

- External CSS in `public/style.css`; use common CSS class naming conventions (see `llm-advice/css-class-naming-conventions.txt`).
- Compile Elm into `public/`: `elm make src/Main.elm --output=public/main.js`
- Create `public/index.html` that pulls in the CSS and JS.
- **All URL references in static files must be relative**, not absolute. Assume `elm reactor` is started in the project root, not inside `public/`. So the script tag uses `main.js`, never `/main.js` or `../dist/main.js`. Same rule applies to CSS and image URLs.

### Completion criteria

The project is complete when a Playwright test asserts all of:

1. The banner/title "Test News Site" is visible.
2. All feature-card images load (`naturalWidth > 0`).
3. The three columns render at a desktop viewport (e.g., 1280×800).

Also create a Playwright test that verifies the browser can display the layout.

## 2. Project Structure

```
project-root/
├── elm.json              # Elm application manifest
├── package.json          # npm deps (playwright, selenium, elm-test)
├── AGENTS.md             # this file
├── llm-advice/           # reference docs for LLMs (shadowing, CSS naming)
├── src/                  # Elm source modules (Main.elm goes here)
├── public/               # HTML, compiled JS, hand-written JS/CSS, binary assets
│   └── images/           # images referenced by the layout
├── tests/                # Elm unit tests (elm-test)
└── tmp/                  # scratch/temp files only (create if needed)
```

Rules:

- Elm sources go in `src/`. Tests go in `tests/`. Everything served to the browser goes in `public/`.
- Never `cd` above the project root or use `..` paths to escape it. If you need temp files, create/use `tmp/` in the project root.

## 3. Toolchain

| Tool | Location / Notes |
|------|------------------|
| Elm compiler | `/home/johnk/.local/bin/elm` — version 0.19.2 |
| elm-test | installed globally; run with `elm-test` |
| playwright-cli | installed; see https://www.npmjs.com/package/playwright |
| selenium / selenium-webdriver | installed; see https://www.npmjs.com/package/selenium-webdriver |
| elm reactor | use as the dev/test web server, started from the project root |

You may install additional packages via npm/pip3/etc. if needed; mention any installs in your final summary.

Prefer existing libraries over reinventing utilities (HTTP, JSON, dates), but for simple view/layout code the standard `Html` module is sufficient.

### Adding dependencies

- Add Elm packages with `elm install <pkg>/<name>` — do NOT copy library source into the repo manually.
- Already declared in `elm.json`: `elm/browser`, `elm/core`, `elm/html`, `elm/json`, `elm/random` (+ indirect `time`, `url`, `virtual-dom`). Test dep: `elm-explorations/test`.

## 4. Elm Version Gotchas (0.19.x)

Write code targeting Elm 0.19.0–0.19.2; the whole 0.19.x line shares the same API.

Training data from before 2018 is often outdated. Watch for these differences vs. old 0.18-era code:

- Package namespaces changed from `elm-lang/*` to `elm/*` (e.g., `elm/html`, not `elm-lang/html`).
- `Html.App` is deprecated; use `Browser.sandbox` / `Browser.element` instead.
- Older `Browser.Sandbox` signatures differ subtly from current ones.
- Upgrade guide: https://raw.githubusercontent.com/elm/compiler/refs/heads/main/docs/upgrade-instructions/0.19.0.md

### Module entry point

Your module must expose a `main : Program` value — not just an `init` function. Build it with `Browser.sandbox` or `Browser.element`.

In `index.html`, the calling convention is:

```html
<script src="main.js"></script>
<script>Elm.Main.init({ node: document.getElementById('the-node-id') })</script>
```

Note the global starts with `Elm.` (i.e., `Elm.Main.init(...)`), not bare `Main.init(...)`.

## 5. Debugging Discipline

This section exists because the most common failure mode is falling into a compiler-error rabbit hole and mutating unrelated code repeatedly.

1. **Assume the Elm compiler is correct.** If there are compilation errors, your code is wrong — read the error messages carefully and fix exactly what they point at.
2. **Naming/undefined-symbol errors:** check your import lines. Elm requires explicit imports of every symbol you use.
3. **"Missing closing brace"-style errors:** look at the actual code and count braces; don't guess.
4. **Never shadow variables**: do not bind a name in an inner scope that already exists in an outer scope. Details: `llm-advice/shadowing.txt`.
5. **Stop condition:** if the same error persists after a couple of targeted fixes, stop and tell the user rather than continuing to mutate code. Do not blame the toolchain.
6. **Runtime-but-blank-page problems** are usually bad URLs in `index.html` (absolute paths, `../` escapes) — see §1 static-file rules.
7. For general advice, consult the `llm-advice/` directory.

## 6. Testing

- **Unit tests:** `elm-test` (deps already configured; example in `tests/Example.elm`). References:
  - https://elmprogramming.com/easy-to-test.html
  - https://github.com/elm-explorations/test
- **Frontend/layout tests:** Playwright (preferred) or Selenium. Serve the site with `elm reactor` from the project root while testing.
- The completion gate is the Playwright assertions listed in §1.

## 7. Reference Docs

- `llm-advice/shadowing.txt` — Elm variable shadowing pitfalls.
- `llm-advice/css-class-naming-conventions.txt` — CSS class naming conventions to follow in `public/style.css`.
- Elm 0.19 upgrade instructions: https://raw.githubusercontent.com/elm/compiler/refs/heads/main/docs/upgrade-instructions/0.19.0.md