first pass at the newspaper builder

2026-09-14 11:57:22 +10:00
commit bec1eaac87
497 changed files with 178953 additions and 0 deletions
@@ -0,0 +1,202 @@
+# 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 |