# Math Tasks Generator

Printable math worksheet generator (A4 PDF) for children aged 7–9. Claude Code-driven workflow: user describes a task idea → Claude generates JSON config → creates HTML pages with Tailwind CSS → converts to PDF via Puppeteer.

**No template engine.** Claude Code generates fresh HTML pages directly from JSON task configs each time.

## Commands

```bash
npm run build:css          # Build Tailwind CSS (minified)
npm run build:css:watch    # Watch mode for CSS
npm run preview            # Serve HTML at localhost:3000
npm run dev                # CSS watch + preview server (concurrent)
npm run pdf -- <file>      # Convert HTML file to PDF
```

Generate problems from a task config:
```bash
node src/scripts/generate-problems.mjs tasks/<task>.json
```

Generate images via Banatie API:
```bash
node src/scripts/banatie.mjs --type background --prompt "forest theme" --output assets/backgrounds/forest.png
node src/scripts/banatie.mjs --type icon --prompt "golden star" --output assets/icons/stars/star1.png
```

## Directory Structure

```
src/
  styles/main.css              — Tailwind source with A4/print styles
  scripts/
    generate-pdf.mjs           — HTML → PDF via Puppeteer
    generate-problems.mjs      — JSON task → concrete problem list
    banatie.mjs                — Banatie API client for image generation
tasks/                         — JSON task definition files
assets/
  backgrounds/                 — large background images per theme (~1200x1700px)
  icons/                       — icon sets in subfolders (128x128px transparent PNG)
output/
  html/                        — generated HTML (gitignored)
  pdf/                         — generated PDFs (gitignored)
  css/                         — built Tailwind CSS (gitignored)
```

## JSON Task Format

Each task is a JSON file in `tasks/` with this structure:

```json
{
  "id": "multiply-2-3",
  "title": "Умножение на 2 и 3",
  "description": "Worksheet for practicing multiplication by 2 and 3",
  "template": "{a} × {b} = ___",
  "variables": {
    "a": { "type": "range", "min": 1, "max": 10 },
    "b": { "type": "set", "values": [2, 3] }
  },
  "problemCount": 20,
  "layout": {
    "columns": 2,
    "problemsPerPage": 20
  },
  "labels": {
    "title": "Умножение",
    "subtitle": "Реши примеры",
    "name": "Имя: _______________",
    "date": "Дата: _______________"
  },
  "theme": {
    "background": "assets/backgrounds/forest.png",
    "icons": "assets/icons/stars/",
    "iconReward": 1
  }
}
```

### Fields

- **template** — problem template with `{variable}` placeholders
- **variables** — each variable is either `range` (min/max) or `set` (explicit values)
- **problemCount** — how many problems to generate
- **layout.columns** — 1 or 2 column layout
- **layout.problemsPerPage** — max problems per A4 page
- **labels** — all visible text (no hardcoded language)
- **theme.background** — path to background image
- **theme.icons** — path to icon directory (for collectible rewards)
- **theme.iconReward** — show an icon every N problems solved

## HTML Generation Guidelines

When generating HTML worksheets:

- **Page size:** A4 = 210mm × 297mm. Use the `.page-a4` class.
- **CSS:** Link to `../css/styles.css` (relative from `output/html/`)
- **Page breaks:** Use `break-after: page` between pages. Each `.page-a4` is one printed page.
- **Background images:** Use absolute paths or paths relative to HTML location. Apply via `.page-background` as a full-page positioned image.
- **Icons:** Inline small 128×128 images next to problems or as rewards.
- **Fonts:** Use system fonts or Google Fonts loaded via `<link>`.
- **Print-friendly:** Avoid shadows, gradients that don't print well. Test with `npm run pdf`.
- **Images in PDF:** Use local file paths (not URLs). Puppeteer resolves `file://` protocol.
- **Embed images** as base64 data URIs when possible for reliable PDF rendering.

## Banatie API

REST API for generating images.

- **Backgrounds:** ~1200×1700px, themed illustrations (forest, space, ocean, etc.)
- **Icons:** 128×128px, transparent PNG, simple collectible items (stars, gems, animals)

Configuration is in `src/scripts/banatie.mjs`. Set the `BANATIE_API_KEY` environment variable for authentication.

## PDF Generation

Puppeteer settings for A4 worksheets:
- Format: A4
- `printBackground: true` (required for background images)
- Margins: zero (CSS handles margins)
- `preferCSSPageSize: true`

## Workflow

1. User describes the math task idea to Claude
2. Claude creates/updates a JSON config in `tasks/`
3. Claude runs `node src/scripts/generate-problems.mjs tasks/<task>.json` to get concrete problems
4. Claude generates HTML file(s) in `output/html/` using the problems and Tailwind classes
5. Run `npm run build:css` to compile CSS
6. Run `npm run pdf -- output/html/<file>.html` to create PDF
7. Preview with `npm run preview` at localhost:3000