Imported from AshPhox/weather-test-app (AGENTS.md). Install upstream with npx skills add AshPhox/weather-test-app. Copyright stays with the author.

AGENTS.md – WeatherView

Living Document: Update this file whenever the development workflow, coding conventions, or API integrations change.

Agent Role

You are an AI coding assistant working on WeatherView, a professional static weather forecast website. Your primary responsibilities are:

• Maintaining the correctness and quality of the HTML, CSS, and JavaScript codebase
• Keeping the Open-Meteo API integration working reliably
• Ensuring all Playwright tests pass before marking any change complete
• Preserving the design quality and accessibility of the UI

You must not introduce breaking changes to the public interface (search form, unit toggle, weather cards) without running the full test suite.

Project Overview

WeatherView is a zero-build-step static website (HTML + CSS + Vanilla JS) that:

• Accepts a city name as input and geocodes it via the Open-Meteo Geocoding API
• Fetches a 5-day daily weather forecast via the Open-Meteo Forecast API
• Renders a hero summary card and five forecast cards with temperature, weather condition, precipitation, and wind speed
• Supports a °F / °C toggle
• Requires no backend, no API key, and no framework

Stack: HTML5 · CSS3 (Custom Properties, Grid, Glassmorphism) · Vanilla ES2022 JS · Playwright (tests only)

Setup & Build Commands

# Install dependencies (Playwright + http-server)
npm install

# Install Playwright browser binaries (first-time only)
npx playwright install chromium

# Serve the site locally for development
npx http-server . -p 3000 -c-1

# Open in browser
open http://localhost:3000

There is no build step — the site is served directly as static files.

Test & Lint Commands

# Run all Playwright tests (headless, with local webServer)
npm test

# Run tests with browser visible (useful for debugging)
npm run test:headed

# Run a single test by name
npx playwright test --grep "Chicago"

Tests must pass before any change is considered complete. Screenshots are saved to tests/screenshots/ for each city test.

Directory Map / Key Files

weather-test-app/
├── index.html              # Entry point — all UI structure
├── styles.css              # All styling (no external CSS frameworks)
├── app.js                  # All client-side logic (API fetches, DOM rendering)
├── AGENTS.md               # This file
├── package.json            # Dev dependencies (Playwright, http-server)
├── playwright.config.js    # Playwright config with webServer
└── tests/
    ├── weather.spec.js     # City forecast tests (Chicago, Paris, NYC, Rome)
    └── screenshots/        # Auto-generated per-city screenshots

Coding Conventions

General

• No frameworks, no build tools. Plain HTML, CSS, and ES2022 JavaScript.
• Use 'use strict'; at the top of app.js.
• Use const and let; never var.
• Prefer async/await over .then() chains.

HTML

• Semantic elements (<header>, <main>, <footer>, <section>).
• All interactive elements must have accessible aria-* attributes where appropriate.
• IDs are used for JS hooks; classes are used for CSS styling — do not mix these roles.

CSS

• All design tokens are CSS custom properties in :root (colors, radii, shadows, fonts, transitions).
• Animate only transform and opacity (GPU-composited) — never top, left, width, or background.
• Do not add selectors for classes that are not present in index.html or injected by app.js.
• Responsive breakpoints: 768px (tablet) and 480px (mobile) only.
• No external CSS frameworks (e.g., Bootstrap, Tailwind).

JavaScript (app.js)

• All DOM references are declared once at the top of the module.
• API base URLs are top-level constants (GEOCODING_URL, FORECAST_URL).
• The WMO weather code map (WMO_MAP) is the single source of truth for icons and descriptions.
• lastForecastData holds the current forecast; rerender() re-renders on unit change.
• Error messages must be human-readable and shown via showError().

Playwright Tests (tests/weather.spec.js)

• Each test must: navigate to /, fill the search input, click Search, wait for .weather-card, assert 5 cards, assert hero city is non-empty, and save a screenshot to tests/screenshots/{city}.png.
• Do not use hardcoded temperature values — weather data is live and changes daily.

Boundaries & Constraints

Integration Points

Open-Meteo Geocoding API

• URL: https://geocoding-api.open-meteo.com/v1/search
• Params: name, count=1, language=en, format=json
• Returns: latitude, longitude, name, admin1, country, timezone
• Free: No API key required; up to 10,000 requests/day

Open-Meteo Forecast API

• URL: https://api.open-meteo.com/v1/forecast
• Params: latitude, longitude, daily (see below), forecast_days=5, timezone
• Daily variables used: temperature_2m_max, temperature_2m_min, weathercode, precipitation_sum, windspeed_10m_max, sunrise, sunset
• Free: No API key required; up to 10,000 requests/day

WMO Weather Codes

Standard WMO codes (0–99) are mapped to emoji and human-readable descriptions in WMO_MAP in app.js. Extend this map if new codes need to be supported.

Error Handling & Escalation

• Network errors and non-OK HTTP responses throw descriptive Error objects caught in handleSearch().
• showError(msg) displays user-facing error messages in the error state panel.
• If the geocoding API returns no results, the user sees: City "X" not found. Please check the spelling and try again.
• If Playwright tests fail due to flaky network conditions, retry once (retries: 1 in config) before investigating.
• Escalate to a human if the Open-Meteo API changes its response schema.

Compliance & Safety

• No user data is stored or transmitted beyond what is sent to the Open-Meteo public API.
• The Open-Meteo API is free for non-commercial use. For commercial deployment, review open-meteo.com/en/license.
• No cookies, local storage, or tracking of any kind.