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,102 @@
+# Refined Mockups — Wedding Newspaper Generator
+
+> Design-lead refined mockups derived from the user stories (US1–US10),
+> requirements (FR1–FR8, NFR1–NFR9), and the seven confirmed design decisions
+> (CLI-first authoring, content/config input, per-article review page, no print
+> preview, funnies generated from content, no formal a11y target, guided empty
+> state). Rough mockups were not produced (classic scope skips Ideation), so
+> these are designed directly from requirements + stories.
+
+## M1 — The authoring flow (generator UX)
+
+The generator is **CLI-first** (Q1=A): the couple runs a single command, the
+tool reads a content folder + config, optionally invokes local Ollama for the
+AI draft, emits `newspaper.html`, and (per US9) presents a per-article review
+page before the final render.
+
+```
+worktree/
+  config.json            # masthead metadata: title, names, date, issue, volume
+  content/               # markdown/txt articles + funnies source
+  newspaper.html         # the generated, self-contained printable artifact
+```
+
+`newspaper generate [--draft]` flows:
+1. Read `config.json` + `content/` (Q2=A).
+2. If `--draft`, ask local Ollama to draft lead story + fillers (US8), keeping
+   everything on-machine (NFR9).
+3. If AI used, open the **per-article review page** (US9/Q3=A): approve / edit /
+   replace any single article before final render.
+4. Emit self-contained `newspaper.html`, zero-network, openable via `file://`,
+   printable to A4 (FR7, NFR1–NFR4, US5).
+
+## M2 — The newspaper page (reader UX)
+
+The output is a classic broadsheet (US6/NFR8): black ink on white/cream, serif
+headlines + body, column rules. Content flows across multiple A4 pages with
+clean page breaks (US1/FR1). Structural regions (US2/US3/US4/US6/US3-funnies):
+
+```
+┌─────────────────────────────────────────────┐  ┌─────────────────────────────┐
+│  MASTHEAD (title / date · issue · volume)   │  │   interior page header     │
+├──────────────┬──────────────┬───────────────┤  ├────────┬────────┬──────────┤
+│ lead/ front  │ article      │  xkcd-style   │  │ column │ column │ ads/box  │
+│ page story   │ (bylined)    │  cartoon      │  │        │        │          │
+├──────────────┼──────────────┼───────────────┤  ├────────┴────────┴──────────┤
+│ article 3    │  pull quote  │  schedule /   │  │  photo auto-balanced      │
+│              │              │  events block │  │                            │
+├──────────────┴──────────────┴───────────────┤  ├──────────────┬─────────────┤
+│   funnies: crossword · find-a-word · comics  │  │ article cont.│ well-wishes │
+└─────────────────────────────────────────────┘  └──────────────┴─────────────┘
+         page 1                                       page 2+
+```
+
+- **Page 1**: masthead (US2), lead story (FR3.1), interior articles with
+  bylines (FR3.2), xkcd-style cartoon tied to the day (FR5), schedule/events
+  block (FR3.4), pull quotes/sidebars (FR3.3).
+- **Pages 2+**: flowing interior columns, photo auto-balancing (FR6/FR4/US4),
+  the lighter well-wishes corner (FR3.5), and the funnies section (US3/FR4):
+  crossword, find-a-word, comics.
+- **Funnies generated from content** (Q5=X): the generator builds the puzzles
+  from theme words/clues drawn out of the content and uses content-derived
+  context to search for / insert a relevant cartoon.
+
+## M3 — AI per-article review page (US9 / Q3=A)
+
+After the AI draft, the couple sees a review page. Present **one article per
+card**, each with three actions:
+
+| Card action | Behaviour |
+|---|---|
+| **Approve** | Keep this article's copy unchanged; others can still be revised |
+| **Edit** | Edit this article's copy in place; only it re-renders |
+| **Replace** | Supply new copy; it replaces the draft for this article only |
+
+A "Render final newspaper" button appears once every article is approved (or
+the couple opts to keep unapproved ones as-is). Approved articles never change
+when others are edited (US9/AC9.1.2–3).
+
+## M4 — First-run / empty state (US10 / Q7=A)
+
+With no content yet, the couple sees a friendly guided state:
+- A short message ("Welcome — let's make your wedding newspaper").
+- A pointer to the `content/` folder + `config.json`.
+- A **sample issue** they can generate to see the layout (Q7=A), then replace
+  with their real content.
+
+This protects the first-run experience (per the designer contribution in
+user-stories) without fabricating content in the real output (FR7.4).
+
+## M5 — States handled
+
+Per stage Step 2, the generator's surface must handle these states:
+- **empty** — no content: guided empty state (US10).
+- **loading** — AI draft running: simple progress/status line (CLI) or spinner
+  (review page).
+- **error** — missing content/config, model unavailable, template failure:
+  clear one-line message naming the problem + fix path.
+- **success** — generated `newspaper.html`, path shown.
+- **partial** — AI draft done, some articles reviewed, others pending (the
+  review page's natural in-between state).
+
+<!-- refined-mockups-after-confirm -->