Add Puzzle Page: generic template for iframe-based puzzles (Sudoku, Word wheel, Wordiply)

[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).

• 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 iframe URL, group, and per-puzzle SEO description. All 6 entries share the same
  AmuseLabs URL template (parameterised by slug), aside from Wordiply, which uses its own provider.
• 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.
• PuzzleIframe.island.tsx, a generic sandboxed iframe wrapper. It passes a guardian-puzzle-context
  object (signed-in user id, or null, plus whether dark mode is active) to the puzzle provider, both
  as a URL parameter and via postMessage, kept in sync if the reader signs in or out while on the
  page.
• Per-puzzle SEO metadata: a curated description per game (not a generic or templated string),
  wired into the page's meta description plus Open Graph and 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, so no og:image/twitter:image tag is emitted for any of
  them today. This is a deliberate decision, not an oversight: no site-wide default/fallback share
  image exists anywhere in DCR or frontend today, so an unset image simply omits the tag, matching
  existing sitewide behaviour for any other page without an image.
• 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 (deployed
  independently via Fastly), with no code change or redeploy. Only one feature is gated behind a
  tier so far: the "More from Puzzles & Games" related-content rail is gated behind
  puzzles-new-hub-v1, since it's a later-phase feature per the product rollout plan.
• docs/puzzle-page.md: what's implemented, the request contract field reference, local testing
  instructions, and an "Open questions / known limitations" section covering things like the real
  AmuseLabs archive URL still being unknown, dark mode honouring being unconfirmed on the provider
  side, and SEO risks to revisit before shipping calendar/archive features (with a concrete,
  cautionary example already seen elsewhere on the site).

Why?

To give readers a consistent, dedicated page for playing Sudoku, Word wheel, and Wordiply, replacing
ad hoc/one-off pages per game with a single, shared, maintainable template, 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, not just unit test assertions, for: correct iframe src per game, correct meta
  description / Open Graph / Twitter tags, and the "More from Puzzles & Games" rail correctly
  appearing or not appearing depending on the rollout tier flags.
• This branch went through several rounds of review feedback since first opened: a naming pass
  ("Game Page" to "Puzzle Page"), a scope reduction (removing Codeword, Futoshiki, Suguru,
  On the Ball, and Film Reveal, none of which are part of V0), and the SEO/rollout-gating work
  described above. 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:493c1fdb5e278375392ac6a81ec555516a365258f0280f8e5292a8d0e3be55d9

🐛 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:493c1fdb5e278375392ac6a81ec555516a365258f0280f8e5292a8d0e3be55d9"

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

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

# Refer to image via the GitHub commit SHA tag
# IMAGE_IDENTIFIER=":sha-53c842c7d9d2343fd1332b687f7629f6911febfa"

# 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/deployTools --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 31099 of dotcom:rendering-all to CODE

All deployment options

• Deploy build 31099 of dotcom:rendering-all to CODE
• Deploy parts of build 31099 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]

As I mentioned further down, you'll probably need to make a few changes to this implementation for the user handling. Basically, we need to pass the user ID to the iframe and reload the iframe when the user logs in.

[andresilva-guardian]

This is done, the iframe src now gets the reader's user ID appended as a query param (sourced from idToken.claims.legacy_identity_id), and we also send it via postMessage({ type: 'guardian-puzzle-user', userId }, '*') after load. The iframe reloads automatically when the sign-in state changes, so a login/logout mid-session is picked up. Documented in docs/puzzle-page.md under "User identity passed to the puzzle iframe". Marking this resolved. Let me know if AmuseLabs/Wordiply need a different message shape once they've had a chance to confirm on their end.

[gustavo-olmedo]

I don't think we currently support dark mode, I didn't do anything for the main puzzle list, but we could double-check this just in case.

[andresilva-guardian]

I looked into this. DCR does have real dark mode support, and the Puzzle Page's chrome (masthead, footer, etc.) follows it automatically like every other page — no extra work needed there. The part I can't confirm is the iframe content itself, since that's entirely controlled by AmuseLabs/Wordiply and we have no visibility or control over it. I haven't tested it live in dark mode against either provider yet. I've logged this as an open question in the doc rather than guessing. Happy to test it properly once we have a way to preview both providers side by side.

[gustavo-olmedo]

The print button is a little bit more complicated. We're not looking to print the entire page, only the content of the iframe, and only for sudoku because that functionality currently exists in the old sudoku which is currently a static page. For now, we can print whatever the iframe provides, which isn't ideal because it includes some extra things like menus and controls, but that's the approach we're aiming for in V0.

[andresilva-guardian]

Agreed this isn't ideal. Right now it's a plain window.print() on the whole page, not scoped to just the iframe content, and it's not sudoku-specific. Given this was already flagged as an accepted V0 compromise ("print whatever the iframe provides"), I've left the behaviour as-is for now rather than building custom print handling, but I'll add an explicit note to the doc's limitations section so it doesn't get lost. Let me know if this needs to be prioritised before V0 ships, since a proper fix would mean coordinating with AmuseLabs on what they expose for print.

[gustavo-olmedo]

This is what I was telling you, that maybe we could have a shared layout down the road, but if we're not going to include the crossword, I wouldn’t add extra elements that we won't be releasing, like comments, for example. If you look at the design in Figma, this page actually looks pretty simple, I mean, there aren’t many elements besides the iframe and a few icons where needed.

[andresilva-guardian]

Agreed, and this is already how it's built, since crossword isn't part of Puzzle Page, the layout doesn't include a comments section, setter byline, or PDF link at all. It's just the iframe plus the share/print controls where enabled, matching the Figma design.

[gustavo-olmedo]

I know this is a test but just wanted to flag I originally added these to the POC because they were part of the design, but we don't have Codeword, Futoshiki, or Suguru for now.

[andresilva-guardian]

Removed all three from the registry (and the tests), the V0 set is now exactly the 6 puzzles we agreed on (4 Sudoku variants, Word wheel, Wordiply). There's a comment in the registry noting these three were descoped and may come back later.

[gustavo-olmedo]

We're not going to include Trivia and Quizzes either.

[andresilva-guardian]

Same change as the Codeword/Futoshiki/Suguru removal. On the Ball and Film Reveal (Trivia and Quizzes group) are also out of the registry now.

[gustavo-olmedo]

This URL is supposed to point to the AmuseLabs archive. In the POC it was only there as an example, so we'd need to find the correct URL.

[andresilva-guardian]

Still open... I haven't found or been given a real AmuseLabs archive URL, so I didn't want to guess one. hasArchive is still just a boolean flag in the registry; there's no archive URL field anywhere yet, and nothing currently renders an archive link. I've written this up explicitly as an open question in the doc. Could someone confirm the correct URL(s) so I can wire this up properly?

[gustavo-olmedo]

Just want to mention, this game is Moviegrid. I don't think we'll include it in V0, it's a nice-to-have rather than a must-have. The reason we're not including Moviegrid is that they didn't originally have an API that we could use for the archive. They have since added one, but we haven't tested it yet, and given the timelines, we'd rather not take the risk for V0.

[andresilva-guardian]

Removed, same change as items 5/6 above, film-reveal is out of the registry entirely for now given it's a nice-to-have and the archive API hasn't been tested yet.

[gustavo-olmedo]

I also added this here originally, but I'm wondering if it might be better placed in something like puzzles.validate.ts. It might be worth checking whether we can keep it there so we're not mixing too much code with the user-related logic. Just a thought though, don't change it if you're not sure.

[andresilva-guardian]

Done ✅ Puzzle Page validation now lives in its own src/model/validate.puzzlePage.ts rather than the shared validate.ts. I went with that name instead of puzzles.validate.ts to match this repo's existing per-page-type file naming convention, but the goal (keeping it separate from user-related code) is met either way.

[gustavo-olmedo]

Instead of GamePage, I originally added a puzzlesPage type here. Maybe we could use puzzlePage or something along those lines instead.

[andresilva-guardian]

Done ✅ renamed everything from "Game"/"GamePage" to "Puzzle"/"PuzzlePage" across the board: types, files, components, the endpoint itself (/GamePage → /PuzzlePage), fixtures, and tests. The frontend repo went through the same rename to match.

[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.

[github-actions]

Deploy build 3137 of dotcom:ab-testing to CODE

All deployment options

• Deploy build 3137 of dotcom:ab-testing to CODE
• Deploy parts of build 3137 to CODE by previewing it first
• What's on CODE right now?

---

From guardian/actions-riff-raff.

[andresilva-guardian]

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.

Thanks for the detailed context! 💪 Here's where things stand against each point:

• 18th deadline essentials: the puzzle page itself works end-to-end for all 6 V0 puzzles, ad slots are already in the layout, print is there, comments are correctly not included, and the subnav is in place (the page lives under /puzzles-and-games as you expected). One thing worth flagging: "More from Puzzles & Games" is technically built (there's a component ready to render it), but based on the rollout spreadsheet you shared, this is clearly a 12th-deadline (v1) feature rather than an 18th one, so I've gated it to only appear once a v1 flag is switched on, keeping it hidden for the 18th launch. We'll still need the selection rules for what shows there whenever we do turn it on, let me know who to loop in on that.

• AmuseLabs/Wordiply user info + analytics: the puzzle iframe now gets the reader's identity passed through, specifically a small "puzzle context" object (user ID, or null if signed out, plus whether dark mode is active) sent both as a URL parameter and via postMessage once the iframe loads, and kept in sync if the reader signs in/out while on the page. What I haven't done yet is validate any of this from an analytics perspective on AmuseLabs' side, or confirm the exact message shape is what they expect. Could you help me get in touch with Victoria for AmuseLabs platform access so I can check this properly? Good to know changes can take up to an hour to show up there too.

• AmuseLabs dark mode: we're already sending a dark-mode signal (derived from the reader's real OS/browser preference, not just a static flag), so we're ready on our end whenever they can tell us how to use it. If you've got the URL parameter they mentioned, send it my way and I'll wire it in.

• Responsive design: haven't explicitly verified this yet, will do this before touching anything postMessage/game-state related, exactly as you suggested.

• Saving game state: correctly left alone for now, there's no API for it yet, so this is parked for the 25th once that's available.

• 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.