# Interaction Specification — Wedding Newspaper Generator

> Component-level specifications following the design-agent component template.
> Covers the two surfaces: the CLI authoring flow and the generated newspaper
> page. Per confirmed decisions: CLI-first (Q1=A), content/config input (Q2=A),
> per-article review page (Q3=A), no print preview step (Q4=B), funnies
> generated from content (Q5=X), no formal a11y target (Q6=C), guided empty
> state (Q7=A).

---

## CLI: `generate` command

| Field | Value |
|---|---|
| Component | `generate` CLI command |
| Description | Reads config + content, optionally drafts via local Ollama, emits `newspaper.html` |
| Category | navigation (entry point) |

### States

| State | Description | Trigger |
|---|---|---|
| ready | Prints usage / config guidance | run with no valid input |
| generating | Parses content, builds layout | valid config + content present |
| drafting | Calls local Ollama for lead/fillers | `--draft` flag present |
| reviewing | Hands to review page (US9) | AI draft produced |
| printed | Writes `newspaper.html`, prints success path | render complete |
| error | Content/config/model failure | validation failure |

### Props / Inputs

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `--draft` | boolean | no | — | Whether to run the local Ollama AI draft (US8) |
| `config` | path | no | `config.json` | Masthead metadata + options |
| `content` | path | no | `content/` | Markdown/txt articles + funnies source |

### Responsive behaviour

N/A (CLI). Terminal width-wrapping of help text only.

### Accessibility

| Requirement | Implementation |
|---|---|
| Error clarity | One-line message naming the problem + the exact fix path |
| Reversibility | Generate is idempotent/regenerable; never destroys the couple's content files |

---

## Per-article review page

| Field | Value |
|---|---|
| Component | Article review card |
| Description | Per-article approve / edit / replace control before final render |
| Category | feedback |

### States

| State | Description | Trigger |
|---|---|---|
| pending | Draft ready, not yet decided | AI draft returned |
| approved | Copy kept as-is | user clicks Approve |
| editing | Copy being revised | user clicks Edit |
| replacing | New copy supplied | user clicks Replace |

### Props / Inputs

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `articleId` | string | yes | — | Stable per-article key (the article-level data boundary, US9/AC9.1.5) |
| `status` | pending\|approved\|editing\|replaced | yes | pending | Current review state |
| `copy` | string | yes | — | The article's text |
| `onApprove` | fn | no | — | Keep as-is |
| `onEdit` | fn | no | — | Open inline edit |
| `onReplace` | fn | no | — | Supply replacement copy |

### Responsive behaviour

Stacked cards on narrow; grid of cards on wide. The newspaper is printed, so
this page is on-screen only.

### Accessibility

| Requirement | Implementation |
|---|---|
| Keyboard | Buttons focusable; Enter/Space activate (on-screen tool) |
| Clear status | Each card visibly labelled with its state (pending/approved/…) |

---

## Masthead component (newspaper page)

| Field | Value |
|---|---|
| Component | Masthead |
| Description | Front-page title banner + date / issue / volume (US2/FR2) |
| Category | display / layout |

### States

| State | Description | Trigger |
|---|---|---|
| default | Classic broadsheet masthead | page render |

### Props / Inputs

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `title` | string | yes | — | Newspaper / couple name |
| `dateLine` | string | yes | — | Issue date |
| `issue` | string | yes | — | Issue number |
| `volume` | string | yes | — | "Volume X" |
| `titleStyle` | object | no | serif | Masthead typography |

### Responsive behaviour

Masthead spans the full sheet width on print; on very narrow screen the title
sizes down but the line stays intact (does not wrap awkwardly).

### Accessibility

| Requirement | Implementation |
|---|---|
| Document structure | Masthead is the page's `<header>` / H1 (semantic, matches Q6=C baseline) |

---

## Funnies: crossword & find-a-word

| Field | Value |
|---|---|
| Component | Funnies section |
| Description | Crossword + find-a-word + comics generated from content (US3/FR4/Q5=X) |
| Category | display |

### States

| State | Description | Trigger |
|---|---|---|
| default | Renders crossword grid, clues, solution; find-a-word grid; comic panels | page render |

### Props / Inputs

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `grid` | array | yes | — | Crossword grid (built from content theme words) |
| `cluesAcross` | array | yes | — | Across clues (derived from content) |
| `cluesDown` | array | yes | — | Down clues (derived from content) |
| `findWords` | array | yes | — | Word list for find-a-word (content terms) |
| `comics` | array | no | — | Comic panels + captions |
| `cartoonAlt` | string | no | — | Context note for the xkcd-style cartoon |

### Responsive behaviour

Each puzzle bounded to its column width and an A4-printable height; no
overflow.

### Accessibility

| Requirement | Implementation |
|---|---|
| Clarity | Grid cells have clear borders and legible type (printed keepsake; Q6=C) |

---

## Photo embed (auto-balanced)

| Field | Value |
|---|---|
| Component | Embedded photo |
| Description | Photo embedded in the column layout with caption (FR6/US4) |
| Category | display |

### States

| State | Description | Trigger |
|---|---|---|
| default | Photo + caption fit the column | photo supplied |
| absent | No placeholder; layout renders clean, text-only | no photo supplied (FR7.4) |

### Props / Inputs

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `src` | data/blob | no | — | Locally embedded image |
| `caption` | string | no | — | Caption text |
| `credit` | string | no | — | Credit/byline line |

### Responsive behaviour

Auto-balances into the column structure; falls back to full-width or natural
size if it cannot fit (R-02 from requirements review), never overflowing the
A4 sheet (NFR2).

### Accessibility

| Requirement | Implementation |
|---|---|
| Text alternative | Caption present; decorative `alt` when purely decorative |