# Guide for AI chats: Numsolar offer template "Dagsljus" (Daylight)

Give this file and the `src/` folder to the AI chat, then write what you want
to change.

## What the template is

- A small web app. Numsolar opens `dist/index.html?offerurl=<data URL>` in a
  headless Chromium, waits for `html.offer-ready` and prints the pages to an
  A4 PDF.
- Stack: TypeScript, Preact with htm templates (`html\`...\``, no JSX),
  Paged.js for the pages, Vite. Base library: `@numsolar/offer-templating` 0.2.0.
- The kit `kit/` (`@numsolar/template-kit`): the data selectors
  (`@numsolar/template-kit/offer-data`: `hero`, `facts`, `price`, `months`,
  `shares`, `roofs`, …), the components (`CoverFrame`, `Hero`, `MonthlyBars`,
  `ShareBars`, `PriceTable`, `ProductCards`, …), the glossary (`glossary(data)`),
  `tokens.css` + `components.css` (themes, Inter, type sizes in pt).
- Theme: `light`. Page margins: 16/16/22/16 mm.

## Files

| File | What it does |
| --- | --- |
| `src/main.ts` | Entry point: `@page` rules, the footer in the margin, "Sida x / y", PDF metadata. |
| `src/pages/Pages.ts` | `src/pages/Pages.ts` (the five pages: `Cover`, `Installation`, `Economy`, `Price`, `Closing`). |
| `src/texts.ts` | The template's own texts; the shared terms come from the kit's glossary. |
| `src/assets/style.css` | The layout of this template, on the kit's tokens. |
| `src/pages.test.ts` | Vitest: mounts the pages with the sample houses (only in the Numsolar workspace). |

## Rules (keep these, or the PDF breaks)

1. Keep `<App>` and `onRenderedPages` in `src/main.ts`: it adds `offer-ready` to `<html>`.
2. `@page` rules and `position: running(...)` go only in the
   `<style type="pagedjs+text/css">` block in `src/main.ts`. Other CSS goes in `style.css`.
3. Read the data through the kit's selectors, not by path. A selector gives
   `null` for a missing value; then the block renders nothing. Never print 0
   for a missing value, never `NaN`.
4. Never compute physics or money. Print what Numsolar sends.
5. Never fetch other URLs (the renderer blocks them). Use `Img` / `CoverFrame` for pictures.
6. Style with the kit's tokens (`--surface`, `--text`, `--accent`, …). Nothing below 8 pt.
7. One term for one thing: use the glossary (`t.subsidy` = "Skattereduktion för grön teknik").
   Never print the installer's internal adjustment names unless `showSubsidyTitles` is on.
8. The hero is rounded for display (`settings.roundHero`, default 100). The price page never rounds.
9. After a change: `npm run check`, `npm test` and `npm run build`.

## The data the template reads

The JSON at `?offerurl=` (contract v2, `docs/template_data_contract.md` in
Numsolar). Energy in Wh (the selectors give kWh), money in `offer.currency`.

| Page | Keys |
| --- | --- |
| 1 | `images.illustration` (else `screenshots[0]`), `yearly_simulation.summary.utility_savings[0]` (hero), `requirement.solar_panels_count`, `offer.summary.solar_panel_kw` / `battery_kwh`, `site.address`, `prospect.*`, `manager.*`, `offer.number` / `offer_date` / `offer_due` |
| 2 | `offer.configuration_lines[]` × `equipment[]` (cards), `requirement.roofs[]` (with panels), `structural` (`automatic` / `entered` only) |
| 3 | `monthly_simulation.*` (MonthlyBars), `yearly_simulation.summary` (`finances.roi_year`, `balances[25]`, `balances_blank[25]`) |
| 4 | visible lines, `offer.subtotals`, `offer.grand_total`, `offer.adjustments[]` (subsidy names: only with `showSubsidyTitles`) |
| 5 | `agreement.schedule`, `offer.offer_due`, setting `termsHtml` |
| footer | `organisation.title`, `agreement.organisation.org_number` |

Settings (`useSettings()`): `accent`, `logoDataUrl`, `termsHtml`, `roundHero`, `showSubsidyTitles`.