# AGENTS.md – guidance for LLM agents

This file helps LLM agents work with the Armandine codebase without introducing antipatterns.

## Stack and goals

- **Svelte 5** + **SvelteKit** with **TypeScript**. The site is a **single pre-rendered page** (no SSR, no backend).
- **adapter-static**: the app is built to static HTML/JS/CSS in `build/`. The gallery is **rendered at build time** from `src/lib/media.ts`; the HTML already contains the full gallery. Lightbox and theme toggle are handled by a **client script** (`static/assets/js/script.js`) that binds to the pre-rendered DOM.
- **PostCSS**: nesting and CSS level 2; component-scoped `<style>` in Svelte where possible; global styles in `src/app.css`.
- **Critical CSS**: after `vite build`, `scripts/critical-css.js` runs Beasties to inline critical CSS into the built HTML.

## Structure

| What | Where |
|------|--------|
| Routes / page | `src/routes/` (`+page.svelte`, `+page.ts`, `+layout.svelte`, `+layout.ts`) |
| Components | `src/lib/components/` (e.g. `GalleryFigure.svelte`, `SiteHeader.svelte`) |
| Media data (build-time gallery) | `src/lib/media.ts` – typed array; loaded in `+page.ts` and passed to the page |
| Client script (lightbox, theme) | `static/assets/js/script.js` – not part of Svelte bundle; preloaded in head |
| GA init | `static/assets/js/ga-init.js` |
| Static assets (favicons, media files) | `static/assets/` (media: `desktop/`, `tablet/`, `mobile/`, `thumbnail/`, `videos/`) |
| Global CSS | `src/app.css` (imported in `+layout.svelte`) |
| Config | `svelte.config.js`, `vite.config.ts`, `tsconfig.json`, `postcss.config.js` |

## Conventions

- Use **Svelte 5** patterns (e.g. `$props()`, runes). Use **TypeScript** for `src/lib` and route logic.
- **Gallery**: Rendered at build time via `GalleryFigure` and `data.mediaItems` from `+page.ts`. Do not move gallery rendering to the client.
- **Lightbox and theme**: Implemented in `static/assets/js/script.js`; they rely on the pre-rendered DOM (e.g. `.gallery-item`, `#lightbox`, `#lb-content`). Keep them in that script; do not reimplement in Svelte for “consistency” (the plan keeps them in JS for optimal loading and preload).
- **Head**: Metadata, JSON-LD, favicons, preload of `script.js`, and GA scripts are set in `+page.svelte`’s `<svelte:head>`.
- **CSS**: Prefer component-scoped `<style>` in Svelte components; use `src/app.css` only for `:root`, `body`, and shared/global rules (e.g. lightbox, which is targeted by the client script).
- **Build**: `pnpm build` = `vite build` then `node scripts/critical-css.js`. Output is `build/`. Dockerfile copies `build/` into the image.

## Build pipeline and CI

- **Local:** `pnpm dev` (dev server), `pnpm build` (production build), `pnpm preview` (serve `build/`), `pnpm check` (Svelte + TypeScript check).
- **CI (Woodpecker):** `ci` runs lint, format:check, and **check** (Svelte/TS). `build` runs `pnpm build` then `docker build` (image uses `build/`).

## Antipatterns to avoid

- **Do not** add a backend, API routes, or SSR for this static site.
- **Do not** move lightbox or theme logic into Svelte components; they stay in `static/assets/js/script.js` and attach to the pre-rendered DOM.
- **Do not** add unscoped global CSS for component-specific styles; use component `<style>` or the existing `app.css` sections.
- **Do not** introduce dynamic routes or server-dependent behavior that would break static export (adapter-static).
- **Do not** remove or bypass the Beasties critical-CSS step without replacing it with an equivalent (e.g. another inlining strategy).

## How to add features

- **New media item:** Add an entry to the `mediaItems` array in `src/lib/media.ts` (type, name, caption, alt, dimensions, loading/fetchpriority as needed). Ensure the corresponding files exist under `static/assets/media/` (desktop, tablet, mobile, thumbnail; videos in `videos/`).
- **New component:** Add a `.svelte` file under `src/lib/components/` (or a subfolder). Use component-scoped `<style>` and PostCSS will process it. Export and use in the appropriate route or parent component.
- **New page:** Add a route under `src/routes/` (e.g. `src/routes/about/+page.svelte` and `+page.ts` if needed). With `prerender = true` in the root layout, all pages are pre-rendered.
- **Change metadata or JSON-LD:** Edit the `<svelte:head>` block in `src/routes/+page.svelte` (or the relevant page). Update the `jsonLd` object and meta tags as needed.
- **Change client behavior (lightbox/theme):** Edit `static/assets/js/script.js`. Ensure the script still targets the same DOM structure (e.g. `.gallery-item`, `data-name`, `data-type`, `data-caption`, `#lightbox`, `#lb-content`, `#lb-caption`, `#lb-close`, `#show_video`, `#theme-toggle`).