docs(marketing): design shared poster catalog

2026-10-10 18:36:15 -08:00 · 2026-07-26 02:18:33 +02:00
1 parent 0688f948d2
commit 2409b0dedc
@@ -0,0 +1,109 @@
+# Twenty Shared Marketing Posters Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Generate 20 original posters and expose the complete approved poster showcase through both Xtream and Stalker marketing fixtures.
+
+**Architecture:** A new pure Nx library owns provider-neutral poster-showcase metadata. Xtream and Stalker adapt the same ordered fixtures into their respective protocol shapes and independently serve the shared local PNG files.
+
+**Tech Stack:** TypeScript, Nx, Jest, Express, built-in image generation, PNG/sips validation
+
+---
+
+### Task 1: Create the shared fixture library
+
+**Files:**
+- Create: `libs/shared/marketing-fixtures/project.json`
+- Create: `libs/shared/marketing-fixtures/src/index.ts`
+- Create: `libs/shared/marketing-fixtures/src/lib/marketing-movie.fixture.ts`
+- Create: `libs/shared/marketing-fixtures/src/lib/marketing-movie.fixture.spec.ts`
+- Create: `libs/shared/marketing-fixtures/tsconfig.json`
+- Create: `libs/shared/marketing-fixtures/tsconfig.lib.json`
+- Create: `libs/shared/marketing-fixtures/tsconfig.spec.json`
+- Create: `libs/shared/marketing-fixtures/jest.config.ts`
+- Modify: `tsconfig.base.json`
+
+- [ ] Define a provider-neutral fixture type with category key, title, slug,
+  description, director, actors, genre, rating, tagline, and year.
+- [ ] Move the existing 15 poster-showcase fixtures into the library.
+- [ ] Add the 20 approved new fixtures before the existing fixtures.
+- [ ] Add Jest coverage for exact counts, unique titles/slugs, ordering, and
+  valid category keys.
+- [ ] Run `pnpm nx test shared-marketing-fixtures` and
+  `pnpm nx lint shared-marketing-fixtures`.
+
+### Task 2: Generate the 20 posters
+
+**Files:**
+- Create: `apps/xtream-mock-server/public/marketing/poster/black-harbor.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/the-paper-astronaut.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/summer-static.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/house-of-tides.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/open-late.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/white-room-six.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/field-notes.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/a-thousand-steps.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/the-small-hours.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/copper-rain.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/willow-engine.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/quiet-thunder.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/parallel-kitchens.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/first-string.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/the-long-museum.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/cloud-hotel.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/unpaid-overtime.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/deep-green.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/november-radio.png`
+- Create: `apps/xtream-mock-server/public/marketing/poster/the-last-orange.png`
+
+- [ ] Issue one built-in image-generation request per title.
+- [ ] Inspect title spelling, composition, originality, and forbidden text.
+- [ ] Copy approved outputs into the project and downscale with
+  `sips -z 768 512`.
+- [ ] Verify every file is an RGB PNG at exactly 512 × 768.
+- [ ] Build and inspect a 5 × 4 contact sheet of the final project files.
+
+### Task 3: Adapt Xtream to the shared showcase
+
+**Files:**
+- Modify: `apps/xtream-mock-server/src/app/generators/marketing.generator.ts`
+- Modify: `apps/xtream-mock-server/README.md`
+- Modify: `docs/architecture/xtream-mock-server.md`
+
+- [ ] Replace the local `POSTER_SHOWCASE_MOVIES` metadata with a mapping from
+  the shared fixture library.
+- [ ] Put showcase movies before generated-artwork movies in `MOVIES`.
+- [ ] Keep `listMarketingArtworkFixtures()` limited to the original generated
+  artwork pack.
+- [ ] Update documented title counts from 45 to 65.
+- [ ] Run `pnpm nx lint xtream-mock-server`.
+
+### Task 4: Add the Stalker marketing scenario
+
+**Files:**
+- Modify: `apps/stalker-mock-server/src/app/scenarios.ts`
+- Modify: `apps/stalker-mock-server/src/app/data-generator.ts`
+- Modify: `apps/stalker-mock-server/src/main.ts`
+- Modify: `apps/stalker-mock-server/README.md`
+- Modify: `docs/architecture/stalker-mock-server.md`
+
+- [ ] Add `marketingFixture?: true` and MAC `00:1A:79:00:00:07`.
+- [ ] Build deterministic Stalker VOD categories/items from the shared fixture.
+- [ ] Add the local poster asset route backed by the shared PNG directory.
+- [ ] Document credentials, offline artwork behavior, and screenshot use.
+- [ ] Run `pnpm nx lint stalker-mock-server`.
+
+### Task 5: Verify both providers
+
+**Files:**
+- Inspect all files changed above.
+
+- [ ] Run `pnpm nx test shared-marketing-fixtures`.
+- [ ] Start both mock servers with Nx.
+- [ ] Assert Xtream returns all 35 showcase titles and the 20 new titles first.
+- [ ] Assert Stalker marketing VOD returns all 35 showcase titles and the 20 new
+  titles first.
+- [ ] Fetch every new poster URL from both servers and assert `image/png`.
+- [ ] Run `pnpm run release:notes:validate` and `git diff --check`.
+- [ ] Confirm docs are updated; skip a release note because mock-server and
+  documentation paths are release-gate exempt.
@@ -0,0 +1,96 @@
+# Shared Marketing Poster Catalog Design
+
+## Goal
+
+Add 20 original fictional movie posters in the same approved theatrical style
+as the existing poster showcase, then expose the complete showcase through both
+the Xtream and Stalker mock servers for deterministic screenshot capture.
+
+## Poster set
+
+The new titles are:
+
+1. Black Harbor — maritime crime thriller
+2. The Paper Astronaut — stop-motion family animation
+3. Summer Static — coming-of-age drama
+4. House of Tides — gothic coastal mystery
+5. Open Late — workplace comedy
+6. White Room Six — psychological thriller
+7. Field Notes — nature documentary
+8. A Thousand Steps — mountain sports drama
+9. The Small Hours — urban romantic drama
+10. Copper Rain — neo-noir
+11. Willow Engine — family fantasy
+12. Quiet Thunder — contemporary western drama
+13. Parallel Kitchens — science-fiction comedy
+14. First String — music drama
+15. The Long Museum — art mystery
+16. Cloud Hotel — family animation
+17. Unpaid Overtime — office satire
+18. Deep Green — survival adventure
+19. November Radio — period drama
+20. The Last Orange — Mediterranean family drama
+
+Every poster is an RGB PNG at exactly 512 × 768 pixels. The artwork uses one
+clear theatrical key image, a legible English title exactly once, original
+fictional people or characters, and no actor names, taglines, credits, brands,
+logos, watermarks, or copied franchise imagery.
+
+## Shared fixture boundary
+
+A new pure Nx utility library owns the manually approved movie metadata:
+
+`libs/shared/marketing-fixtures`
+
+Its public API exports the fixture type, the existing 15 showcase movies, the
+new 20 movies, and the combined 35-title showcase. The fixture uses provider-
+neutral category keys. Xtream and Stalker translate those keys to their own
+category identifiers and response shapes.
+
+This keeps one source of truth without making either mock application import
+from the other application. The existing 30-title generated artwork manifest
+remains separate: it still owns its matched poster/backdrop generation jobs,
+while the shared showcase owns manually approved local posters and uses each
+server's deterministic backdrop fallback where needed.
+
+## Xtream integration
+
+`marketing.generator.ts` imports the shared showcase and adapts it to
+`MarketingMovie`. Showcase movies are ordered before the original generated
+artwork movies so their posters appear in initial marketing catalog grids.
+The existing `marketing:marketing` credentials remain unchanged.
+
+The existing Xtream artwork route continues to serve PNGs from
+`apps/xtream-mock-server/public/marketing/poster/`, even though catalog URLs
+end in `.svg` for fallback compatibility.
+
+## Stalker integration
+
+Stalker adds a dedicated `marketing` scenario at MAC
+`00:1A:79:00:00:07`. For this scenario, VOD categories and items come from the
+shared showcase instead of faker. The list uses ordinary non-series VOD shapes,
+stable IDs, local cover URLs, fictional metadata, and deterministic playback
+commands.
+
+Stalker also exposes `/assets/marketing/poster/:slug` and reads the same
+committed PNG directory. It serves the asset itself rather than depending on
+the Xtream server being online. Missing files return 404; the marketing
+scenario must never emit a missing poster URL.
+
+## Screenshot visibility
+
+The 20 new movies are first in the combined showcase. Both provider adapters
+preserve that order, making new posters visible on the first catalog pages
+used for screenshots. All artwork is local and requires no internet access.
+
+## Verification
+
+- Shared fixture tests prove exactly 35 unique titles/slugs, with the 20 new
+  entries first and valid provider-neutral category keys.
+- All 20 new PNGs are inspected and verified as RGB 512 × 768 images.
+- Xtream `marketing:marketing` returns all 35 showcase titles and every new
+  poster URL responds with `image/png`.
+- Stalker MAC `00:1A:79:00:00:07` returns the same showcase and every new cover
+  URL responds with `image/png`.
+- Run the shared fixture tests, both mock-server lints, release-note validation,
+  and targeted HTTP smoke checks.