Add Puzzle Page: generic template for iframe-based puzzles, print scoped to Sudoku

[andresilva-guardian]

What does this change?

Adds "Puzzle Page" to dotcom-rendering, a generic page template for the Guardian's iframe-based
puzzles, currently covering 6 V0 games: Sudoku (easy, medium, hard, killer), Word wheel, and
Wordiply. Crosswords are explicitly out of scope and remain entirely on their own, separate
ArticleDesign.Crossword / CrosswordLayout.tsx flow (untouched, no plans to change that here).

Access control: this endpoint has no route-level gate of its own. Reader-facing access control
lives entirely on the frontend side, via its existing PuzzlesHubExperiment A/B gate, currently
at 0% audience across all 3 rollout tiers described below. No real reader can reach a Puzzle Page
today.

• POST /PuzzlePage endpoint (src/server/handler.puzzlePage.web.ts /
  render.puzzlePage.web.tsx), accepting FEPuzzlePageType (see src/types/puzzlePage.ts).
• PuzzleConfig registry (src/model/puzzles/puzzleConfigs.ts), the single source of truth for
  each puzzle's group, per-puzzle SEO copy, print eligibility, and iframe identity. Each entry's
  iframe config is a discriminated union keyed by provider (amuselabs or wordiply), holding
  only the minimal, provider-specific identity data (e.g. AmuseLabs' confirmed set identifier),
  not a pre-baked final URL. A dedicated per-provider URL-building strategy
  (src/lib/puzzleIframeUrl.ts) assembles the final iframe URL per provider, since each provider
  accepts a genuinely different set of query parameters (confirmed against a real product
  integration requirements document and the native Android/iOS apps' own working AmuseLabs
  integration), rather than one function blindly applying the same parameters to every provider.
• Print is scoped to Sudoku only (printEnabled: true for the 4 Sudoku variants,
  false for Word wheel/Wordiply), per explicit product guidance: an existing static Sudoku print
  page is being retired at V0 launch, so the new Sudoku puzzle page's print button is the only
  remaining way for those readers to print and play, making it a priority to have working
  correctly for V0. No other puzzle currently has a product need for print.
• PuzzlePageLayout.tsx / PuzzlePage.tsx, a fresh, self-contained layout, not a fork of
  CrosswordLayout.tsx, reusing existing generic building blocks (Masthead, Section, Footer,
  AdSlot, ShareButton.island) rather than duplicating them. The page displays instance.puzzleDate
  next to the title in a human-readable format (e.g. "15 September 2026").
• PuzzleIframe.island.tsx, a generic sandboxed iframe wrapper. For every provider, it passes a
  guardian-puzzle-context object (signed-in user id or null, whether dark mode is active, and
  which puzzle date is being shown), both as a URL parameter and via postMessage. For AmuseLabs
  specifically, it also appends uid (signed-in user id, omitted when signed out) and
  darkMode=0|1 (a plain literal value), matching AmuseLabs' own real, confirmed integration
  contract. The iframe's minimum height increases at narrower viewports (below the tablet
  breakpoint) to leave room for AmuseLabs' own internal responsive reflow (a side menu that moves
  below the puzzle grid on smaller screens, per direct product/design guidance). The exact height
  is a best-effort, generous estimate, not a confirmed pixel value from AmuseLabs, and is flagged
  in code and in docs/puzzle-page.md as needing revisiting once tested against a real embed on a
  real device.
• Per-puzzle SEO metadata: a curated, date-templated title/description per game (sourced
  verbatim from the product team's SEO spreadsheet), wired into the page's <title>, meta
  description, and Open Graph/Twitter card tags. An optional image field also exists on
  PuzzleConfig for a future per-puzzle share/preview image, none of the 6 V0 games has one
  configured yet, a deliberate decision (no site-wide default/fallback share image exists anywhere
  in DCR or frontend today), not an oversight.
• A 3-tier, cumulative rollout gating structure in ab-testing/config/abTests.ts
  (puzzles-new-hub, puzzles-new-hub-v1, puzzles-new-hub-v2), all currently at 0% audience.
  Each tier only takes effect if the tier(s) below it are also enabled, so the team can roll
  forward or back between feature phases, or switch everything off, purely via config, with no
  code change or redeploy. Only one feature is gated behind a tier so far: the "More from Puzzles &
  Games" related-content rail, gated behind puzzles-new-hub-v1, a later-phase feature. Note: only
  this repo currently has these v1/v2 tiers wired up anywhere, frontend only checks the v0 tier
  today, since it has no v1/v2-scoped feature of its own yet, this will need mirroring on the
  frontend side once the first v1-scoped frontend feature is built.
• docs/puzzle-page.md: what's implemented, the request contract field reference, local testing
  instructions, and an "Open questions / known limitations" section covering the real AmuseLabs
  archive URL/id mechanism still needing to be wired up for future calendar navigation, dark mode
  and iframe-height honouring being unconfirmed against a real AmuseLabs embed, and a documented
  note that today's hardcoded PuzzleConfig registry is a deliberate V0-only stopgap, expected to
  be superseded by a future server-side "Puzzles Server" / Archive API, per direct product
  guidance, not the intended long-term architecture.

Why?

To give readers a consistent, dedicated page for playing Sudoku, Word wheel, and Wordiply,
including being able to reach a specific day's puzzle by URL and print Sudoku (replacing an
existing static print page being retired at V0 launch), while keeping the existing crossword
experience completely untouched and this new work hidden from the public until the team is ready
to roll it out.

How has this change been tested?

• Full test suite passing (tsc --noEmit clean, full-repo eslint clean).
• Manual verification against a running local dev server (make dev), POSTing real fixtures
  (fixtures/manual/puzzlePage.ts) for all 6 V0 slugs to /PuzzlePage and inspecting the rendered
  HTML directly for: the exact, correct, real-world iframe URL per puzzle (including a previously
  broken killer sudoku identifier, now fixed and independently verified), correct meta/OG/Twitter
  tags, correct puzzle-date display, correct per-provider query parameters, correct print-button
  presence/absence per puzzle, and the responsive iframe height media query.
• This branch went through several rounds of review feedback and product direction changes since
  first opened: a naming pass ("Game Page" to "Puzzle Page"), a scope reduction, the SEO/rollout
  gating work described above, fixing a real, confirmed bug where killer sudoku pointed at the
  wrong AmuseLabs identifier, a per-provider URL-building refactor, and the print/responsive
  refinements described above, driven by direct, ongoing product/design review. See individual
  commits for the full history.

Screenshots

Not applicable. No visual/user-facing change to any existing page or design system component.
Puzzle Page is a new, currently unreleased (0% audience) page type.

[github-actions]

🚀 Image pushed to AWS ECR

Image digest: sha256:9f65c51414dcb647bd0fa2e6953b8f2f6d7dcfc8434161deefc0cd97fe39ca27

🐛 Run the image locally

The following can be used to run the image locally:

# Refer to image using the immutable digest. Find alternatives below.
IMAGE_IDENTIFIER="@sha256:9f65c51414dcb647bd0fa2e6953b8f2f6d7dcfc8434161deefc0cd97fe39ca27"

# Refer to image using branch tag
# IMAGE_IDENTIFIER=":branch-afs-puzzles-game-page"

# Refer to image using build tag
# IMAGE_IDENTIFIER=":build-31166"

# Set environment variables for the AWS CLI
AWS_PROFILE="<A_PROFILE_FROM_JANUS>"
AWS_DEFAULT_REGION="eu-west-1"

IMAGE_ACCOUNT_ID=$(aws ssm get-parameter --name /organisation/accounts/artifacts --query "Parameter.Value" --output text)
REGISTRY="${IMAGE_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com"
IMAGE="${REGISTRY}/guardian/dotcom-rendering${IMAGE_IDENTIFIER}"

# Login to AWS ECR https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html
aws ecr get-login-password | docker login --username AWS --password-stdin $REGISTRY

# Pull the image
docker pull $IMAGE

# Run the image. You'll likely need to set additional flags. See https://docs.docker.com/reference/cli/docker/container/run.
docker run $IMAGE

---

From guardian/actions-publish-image.

[github-actions]

Deploy build 31166 of dotcom:rendering-all to CODE

All deployment options

• Deploy build 31166 of dotcom:rendering-all to CODE
• Deploy parts of build 31166 to CODE by previewing it first
• What's on CODE right now?

---

From guardian/actions-riff-raff.

[gustavo-olmedo]

As a general comment, let's try to keep the terminology consistent across the platform. I'd use "puzzles" rather than "games". One thing to consider is that when we originally started this work, the idea was also to have a /puzzles URL. I still think it makes sense for the frontend to have a convention where /puzzles maps to the Puzzles controller, but we've now changed the public URL to /puzzles-and-games. I'd still keep using "puzzles" when referring to this concept internally.

[gustavo-olmedo]

A few things more to keep in mind, at least from what I can remember right now:

• For the 18th deadline: the main thing we need is the puzzle page where users can actually play, plus the print functionality for Sudoku. There might also be some ad slots, but I'm not sure about that yet. If there's time, we could add the "More from Puzzles & Games" section at the bottom. We'd need to ask what should go there, though , specifically, what rules we need to use to decide which puzzles to show, because we don't know that yet. Comments are not needed for this deadline. The subnav is also something I'd double-check, although I think it should be fine given that the page lives under /puzzles-and-games. This is mainly about the new page. For Crossword, I'd find out what changes are actually required by asking Murray or Karolina, or we can work through that together later. The priority for now is getting the iframe page working, and once you finish that part, let me know and we can look at Crossword.

• The iframe page: it needs to be generic enough to support different games, but for this version we're mainly looking for it to work with Wordiply, which we own, and Word Wheel and Sudoku from AmuseLabs. AmuseLabs has its own platform, and there's a representation of the Guardian user on their platform. So when you render an AmuseLabs iframe, you'll need to pass the user information through. We should also validate that this is working correctly from an analytics perspective. One thing to be aware of is that their platform can sometimes take around an hour to update, so don't be surprised if changes aren't reflected immediately. You could ask Victoria about access to the AmuseLabs platform, although I think access might be limited.

• AmuseLabs dark mode: they also said that if the user switches to dark mode, the device can detect it and potentially change the state inside the iframe. It would be worth checking whether this actually works as expected. I think it might be possible to handle it by adding an extra parameter to the URL, but we'd need to test it.

• Responsive behaviour: before starting on the postMessage work for saving the user's game state, I'd first try playing the games and checking whether there are any issues with the responsive design. Hopefully there aren't any, but we should verify this first, and again.

• Saving game state / postMessages: although there have been discussions about communicating with the iframe and saving the user's game state, I'd leave that until the end. In fact, without the API there's not much we can do with it yet because the API doesn't exist. This is what we need for the 25th deadline, rather than the 18th. So I'd focus on getting the iframe page itself working first, and leave the state management integration until later.

• A/B testing: one thing I'd think about from the beginning is how we're going to handle the A/B test experiments. We have one experiment that will be used for the 18th, and then we'll be launching more things on the 25th. We should make sure we're able to move backwards if needed, for example, if we're asked to go back from the 25th version to the 18th version, or to switch everything off, we should be able to do that without having to make code changes or redeploy everything.

[gustavo-olmedo]

• A/B testing rollback: this is sorted. We've set up three cumulative, independent flags in dotcom-rendering's A/B config, one for the 18th baseline, one for whatever ships on the 12th, and one reserved for future work after that, all currently at 0% audience so nothing is public yet. Each flag only takes effect if the one(s) below it are also on, so we can cleanly roll back from the 12th version to the 18th, or switch the whole thing off, purely by changing config (deployed independently via Fastly). No code changes or redeploys needed on either the frontend or DCR side.

• 18th deadline essentials: yes, the only issue with "More from Puzzles & Games" is that we still need to define the selection rules as you said, I don't think that's particularly difficult. In fact I always try to flag that, but that still takes time, and that time is better spent on the things we've already prioritised for the deadline. We can add this later without any problem, but I'd prefer to make sure we've finished everything we need for the 18th first.

• AmuseLabs/Wordiply user info + analytics: I've already contacted Victoria to get you access to the AmuseLabs platform, so you should be able to test this there.

• AmuseLabs dark mode: Yes, I saw that this is already being used on mobile, but I haven't tested it myself yet.

• Responsive design: The responsive behaviour is important for v0, one thing I remember being important here is that the iframe has its own responsive behaviour. For example, we might define a width and height for the iframe, but the required height can change at smaller screen sizes on AmuseLabs. Some puzzles have a menu on the right that moves below the puzzle on smaller screens, so we need to make sure the iframe has enough height to accommodate that. I'd check this before considering the responsive work done.

• Saving game state: Sounds good.

• A/B testing rollback: Sounds good. Just remember that this also needs to be added/used on the Frontend side.

[gu-prout]

Seen on PROD (merged by @andresilva-guardian 9 minutes and 26 seconds ago) Please check your changes!