kaleidoskop/README.md

# Das Kaleidoskop der Schlummerwelten

A German children's bedtime anthology — 12 independent stories with AI-generated watercolor illustrations — built for [Amazon KDP](https://kdp.amazon.com) (8.5 × 8.5 in, premium color print).

The entire book is written in Markdown and styled with CSS. Running `pnpm book` produces a print-ready PDF.

---

## Project structure

```
kaleidoskop/
├── content/                  # One Markdown file per story (+ front matter & finale)
│   ├── 00-front-matter.md
│   ├── 01-der-glaeserne-sternenwald.md
│   ├── ...
│   └── 13-finale-kaleidoskop.md
│
├── images/                   # AI-generated illustrations (300 DPI PNG/JPG)
│   ├── cover/
│   │   └── cover.png
│   ├── 01/
│   │   ├── scene-1.png       # One image per scene
│   │   ├── scene-2.png
│   │   ├── scene-3.png
│   │   └── scene-4.png
│   └── ... (02/ through 12/)
│
├── templates/
│   ├── book.html             # Master Nunjucks template (title page, TOC, stories)
│   └── story-spread.html     # Per-story layout (image page + text page per scene)
│
├── styles/
│   ├── print.css             # @page rules, bleed, page dimensions
│   ├── layout.css            # Page structure, image/text positioning
│   └── typography.css        # Fonts, colors, story-specific theming
│
├── scripts/
│   ├── build.js              # Markdown → HTML (via Nunjucks + marked)
│   └── pdf.js                # HTML → PDF (via Puppeteer)
│
└── output/
    ├── book.html             # Intermediate build artifact (gitignored)
    └── kaleidoskop.pdf       # Final print-ready PDF
```

---

## Prerequisites

- **Node.js** ≥ 18
- **pnpm** — `npm install -g pnpm`
- **Chromium** (ARM64 / WSL2 only — Puppeteer's bundled Chrome is x86-64)
  ```bash
  sudo apt-get install -y chromium
  ```

---

## Setup

```bash
pnpm install
```

---

## Build commands

| Command | What it does |
|---|---|
| `pnpm build` | Converts Markdown → `output/book.html` |
| `pnpm pdf` | Renders `output/book.html` → `output/kaleidoskop.pdf` |
| `pnpm book` | Both steps in sequence |
| `pnpm watch` | Auto-rebuilds HTML on file changes (no PDF) |

---

## Writing a story

Each story lives in `content/XX-story-name.md`. The file has two parts:

### 1. Frontmatter (YAML)

```yaml
---
number: 1
title: "Der gläserne Sternenwald"
character: Leo
palette:
  primary: "#1a3a6b"      # Main accent color (used for headings, borders)
  secondary: "#c0c0c0"    # Secondary accent (ornaments, dividers)
  text: "#1a3a6b"         # Body text color
  background: "#f0f4ff"   # Text page background color
scenes:
  - image: images/01/scene-1.png
    alt: "Das Glühwürmchen am Fenster"
  - image: images/01/scene-2.png
    alt: "Der Mondlichtpfad"
  - image: images/01/scene-3.png
    alt: "Der gläserne Sternenwald"
  - image: images/01/scene-4.png
    alt: "Das schlafende Kind"
---
```

### 2. Body text

Four scene paragraphs separated by `---`. They map to the four scenes in order:

```markdown
Leo lag in seinem gemütlichen Bett...   ← Scene 1 text

---

Leo schlüpfte in seine Hausschuhe...   ← Scene 2 text

---

Am Ende des Pfades blieben sie stehen... ← Scene 3 text

---

„Es ist Zeit zum Träumen", raunte die Eule. ← Scene 4 text
```

---

## Adding illustrations

Place AI-generated images at the paths listed in the story's frontmatter:

```
images/01/scene-1.png
images/01/scene-2.png
images/01/scene-3.png
images/01/scene-4.png
```

**Before you have images:** The build automatically shows a colored placeholder box (using the story's primary palette color) so you can work on text and layout without waiting for all 48 illustrations.

**Image requirements for KDP:**
- **Resolution:** 300 DPI minimum — upscale AI output with [Upscayl](https://upscayl.org) (free) or Topaz Gigapixel AI
- **Dimensions:** At least 2550 × 2550 px (= 8.5 in × 300 DPI)
- **Format:** PNG or JPG
- **Color space:** RGB (KDP accepts RGB — no CMYK conversion needed)

> See `DOSSIER.md` for the complete AI image prompts for all 48 scenes.

---

## Page layout

Each scene produces two facing pages:

```
┌──────────────┬──────────────┐
│              │              │
│  Full-bleed  │  Story text  │
│ illustration │  (right pg)  │
│  (left pg)   │              │
└──────────────┴──────────────┘
```

- 4 scenes × 2 pages = **8 pages per story**
- 12 stories = **96 interior pages**
- Plus title page, copyright, table of contents, and finale = ~**101 pages total**

The story title appears at the top of the first text page. The story-specific color palette is applied via CSS custom properties injected from the frontmatter.

---

## Customizing the design

### Changing fonts

Add a `@font-face` declaration to `styles/typography.css` and update the `font-family` on `body`. Puppeteer will embed the font in the PDF automatically.

```css
@font-face {
  font-family: 'MyFont';
  src: url('../fonts/MyFont-Regular.woff2') format('woff2');
}

body {
  font-family: 'MyFont', Georgia, serif;
}
```

### Changing per-story colors

Edit the `palette` block in the story's frontmatter. Available properties:

| Key | Applied to |
|---|---|
| `primary` | Story title heading, text color, accent borders |
| `secondary` | Ornament `✦`, dividers |
| `text` | Scene body text |
| `background` | Text page background |

### Dark text pages (e.g. story 9)

Story 9 (*Das Ballett der Nachtfalter*) uses a near-black background. Its text page is overridden in `styles/typography.css`:

```css
[data-story="9"].page--text { background: #0a0a2a; }
[data-story="9"] .scene-text { color: #ffffff; }
```

Add similar overrides for any story that needs special treatment.

### Page size / bleed

Defined in `styles/print.css`:

```css
@page {
  size: 8.75in 8.75in;   /* 8.5in trim + 0.125in bleed on each side */
  margin: 0;
}

.page {
  width: 8.75in;
  height: 8.75in;
}
```

To change trim size, update both values here and the matching `width`/`height` in `scripts/pdf.js`.

---

## KDP submission checklist

1. **Run `pnpm book`** to generate `output/kaleidoskop.pdf`
2. **Verify page count** is correct in your PDF viewer
3. **Check fonts are embedded:**
   ```bash
   pdfinfo output/kaleidoskop.pdf | grep -i font
   # or: pdffonts output/kaleidoskop.pdf
   ```
4. **Upload to KDP:**
   - Log in → Your Books → Create → Paperback
   - Trim size: **8.5 × 8.5 inches**
   - Interior: **Premium Color**, 100 gsm
   - Bleed: **Yes (with bleed)**
   - Upload `output/kaleidoskop.pdf` as the interior file
5. **Use the KDP online previewer** to check layout before ordering a proof
6. **Order a proof copy** before publishing — real print color may differ from screen

---

## AI image prompts

All prompts are in [`DOSSIER.md`](./DOSSIER.md) under each story's `KI-Bild-Prompts` section. The global style guide (paste at the start of every prompt):

```
whimsical storybook illustration, dreamy watercolor style, soft cinematic lighting,
magical atmosphere, high resolution, 300 DPI
```

Recommended tools: **Midjourney**, **DALL-E 3**, **Ideogram**, or **Adobe Firefly**.

---

## Git & large files

Images are tracked in git as binary files. If the repo grows large (each 300 DPI PNG can be 5–20 MB × 48 scenes), consider enabling [Git LFS](https://git-lfs.com):

```bash
git lfs install
git lfs track "images/**/*.png" "images/**/*.jpg"
git add .gitattributes
```

---

## Troubleshooting

**`pnpm pdf` fails with "Syntax error: redirection unexpected"**
Puppeteer's bundled Chrome is x86-64 but your system is ARM64. Install system Chromium:
```bash
sudo apt-get install -y chromium
```
The script auto-detects `/usr/bin/chromium` and uses it instead.

**Images are not showing in the PDF**
Check that the image path in the story's frontmatter matches the actual file location exactly (case-sensitive).

**Text is cut off on a page**
Increase the font size or reduce padding in `styles/typography.css` and `styles/layout.css`. You can also split a long scene text into shorter paragraphs.

**Colors look different in print vs. screen**
KDP calibrates for print. Order a proof copy to see the real result before publishing. Dark tones (story 8 — bronze/chocolate) benefit from premium color paper (100 gsm).