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

ab-testing/config/abTests.ts

@@ -157,6 +157,26 @@ const ABTests: ABTest[] = [
 		groups: ["control", "variant"],
 		shouldForceMetricsCollection: false,
 	},
+	/**
+	 * Puzzles & Games rollout, tier v0 (the master switch).
+	 *
+	 * Gates the baseline Puzzles & Games experience: the new Puzzles Hub
+	 * page, and the 6 V0 puzzle pages (sudoku easy/medium/hard/killer,
+	 * word-wheel, wordiply). At v0, there is no archive, no calendar, no
+	 * progress indicators, no sign-in-to-track-progress prompt, no "more
+	 * from puzzles" rail, and the hub's sub-nav has no links yet.
+	 *
+	 * This is the master switch for the whole Puzzles & Games experience:
+	 * turning it off (or down to 0%) hides everything: the hub, the V0
+	 * puzzle pages, and (by the cumulative design below) every later tier
+	 * too, since v1/v2 only take effect when this is also enabled.
+	 *
+	 * See `puzzles-new-hub-v1`/`puzzles-new-hub-v2` below for the later
+	 * rollout tiers, and `src/lib/puzzlesHubVersionExperiment.ts` /
+	 * `src/lib/puzzlesHubExperiment.ts` in dotcom-rendering for the
+	 * corresponding cumulative gate-check helpers
+	 * (`isPuzzlesHubEnabled`/`isPuzzlesHubV1Enabled`/`isPuzzlesHubV2Enabled`).
+	 */
 	{
 		name: "puzzles-new-hub",
 		description: "Rollout of the new Puzzles Hub experience",
@@ -169,6 +189,68 @@ const ABTests: ABTest[] = [
 		groups: ["control", "variant"],
 		shouldForceMetricsCollection: false,
 	},
+	/**
+	 * Puzzles & Games rollout, tier v1 (w/c 12 Oct launch).
+	 *
+	 * Only takes effect when `puzzles-new-hub` (v0) is ALSO enabled for the
+	 * reader. This test does nothing on its own, by design, so the
+	 * rollout can never end up in an inconsistent state (e.g. v1 features
+	 * showing while the v0 baseline they build on is switched off).
+	 *
+	 * On top of v0, this tier activates: the full hub sub-nav links (to
+	 * /word-games, /logic-puzzles, /trivia-and-quizzes), a
+	 * sign-in-to-track-progress message, a calendar/archive view for
+	 * crosswords/logic-puzzles/word-games (not Wordiply, which has no
+	 * archive), progress indicators (Available/Completed), the "More from
+	 * Puzzles & Games" related-content rail, newsletter signup, and
+	 * changes to the existing crossword page (print CTA repositioning, a
+	 * "play other puzzles" container).
+	 *
+	 * To roll back from v1 to v0 without a deploy: flip this test's
+	 * `audienceSize` to `0 / 100` (or `status` to `"OFF"`) while leaving
+	 * `puzzles-new-hub` untouched.
+	 */
+	{
+		name: "puzzles-new-hub-v1",
+		description:
+			"Rollout of the v1 Puzzles & Games features (w/c 12 Oct), on top of the puzzles-new-hub v0 baseline",
+		owners: ["puzzles.team@guardian.co.uk"],
+		status: "ON",
+		expirationDate: "2026-12-31",
+		type: "server",
+		audienceSize: 0 / 100,
+		audienceSpace: "A",
+		groups: ["control", "variant"],
+		shouldForceMetricsCollection: false,
+	},
+	/**
+	 * Puzzles & Games rollout, tier v2 (future, no launch date confirmed
+	 * yet as of this writing).
+	 *
+	 * Only takes effect when BOTH `puzzles-new-hub` (v0) AND
+	 * `puzzles-new-hub-v1` are ALSO enabled for the reader, same
+	 * cumulative-by-design principle as v1 above, applied one tier further.
+	 *
+	 * On top of v0+v1, this tier activates: the On the Ball and Film Reveal
+	 * iframe games (Trivia and Quizzes group), a "Most played" container,
+	 * EventKit-driven navigation, migrating existing crossword pages onto
+	 * the new Puzzle Page template, and search-engine mobile app nudges.
+	 *
+	 * Kept at 0% until that work begins; there is nothing to roll back yet.
+	 */
+	{
+		name: "puzzles-new-hub-v2",
+		description:
+			"Rollout of the v2 Puzzles & Games features (no date confirmed yet), on top of the puzzles-new-hub/puzzles-new-hub-v1 baseline",
+		owners: ["puzzles.team@guardian.co.uk"],
+		status: "ON",
+		expirationDate: "2026-12-31",
+		type: "server",
+		audienceSize: 0 / 100,
+		audienceSpace: "A",
+		groups: ["control", "variant"],
+		shouldForceMetricsCollection: false,
+	},
 	{
 		name: "commercial-prebid-transaction-ids",
 		description:

dotcom-rendering/fixtures/manual/puzzlePage.ts

@@ -0,0 +1,116 @@
+import type { PuzzleConfig } from '../../src/model/puzzles/puzzleConfigs';
+import { puzzleConfigs } from '../../src/model/puzzles/puzzleConfigs';
+import type { FEPuzzlePageType } from '../../src/types/puzzlePage';
+import type { PuzzleItem } from '../../src/types/puzzlesPage';
+import { Standard } from '../generated/fe-articles/Standard';
+
+const sampleMoreFromPuzzlesAndGames: PuzzleItem[] = [
+	{
+		id: 'sudoku-easy-daily',
+		title: 'Sudoku easy',
+		type: 'sudoku-easy',
+		set: 'all',
+		cardVariant: 'compact',
+		cadence: 'Daily',
+		slug: 'sudoku-easy',
+	},
+	{
+		id: 'word-wheel-daily',
+		title: 'Word wheel',
+		type: 'word-wheel',
+		set: 'all',
+		cardVariant: 'compact',
+		cadence: 'Daily',
+		slug: 'word-wheel',
+	},
+];
+
+/**
+ * Illustrative canonical URL matching `frontend`'s public URL shape for
+ * puzzle pages (top-level, mirroring crosswords, distinct from the
+ * `/puzzles-and-games` hub), purely a fixture value, not something DCR
+ * validates or enforces the shape of.
+ */
+const canonicalUrlForSlug = (slug: string): string => {
+	const sudokuMatch = /^sudoku-(.+)$/.exec(slug);
+	if (sudokuMatch) {
+		return `https://www.theguardian.com/sudoku/${sudokuMatch[1]}`;
+	}
+	return `https://www.theguardian.com/${slug}`;
+};
+
+/**
+ * Builds a `FEPuzzlePageType` fixture for the given `slug`, defaulting to a
+ * generic instance for that slug's `PuzzleConfig`. Pass `overrides` to
+ * customise individual fields (deep-merged only one level for `instance`).
+ */
+export const createPuzzlePage = (
+	slug: string,
+	overrides: Partial<FEPuzzlePageType> = {},
+): FEPuzzlePageType => {
+	const puzzleConfig = puzzleConfigs[slug];
+
+	if (!puzzleConfig) {
+		throw new Error(`Unknown puzzle slug in fixture: ${slug}`);
+	}
+
+	return {
+		id: `puzzle-page-${slug}`,
+		slug,
+		webTitle: `${slug} | The Guardian`,
+		config: {
+			...Standard.config,
+			contentType: 'Game',
+			// DCR no longer gates /PuzzlePage on any AB test participation
+			// (the former 'game-page-experiment' gate was removed; routes
+			// will be mapped/exposed via a different project instead), so
+			// this is left empty rather than implying any particular value
+			// is required.
+			serverSideABTests: {},
+		},
+		nav: Standard.nav,
+		pageFooter: Standard.pageFooter,
+		canonicalUrl: canonicalUrlForSlug(slug),
+		editionId: Standard.editionId,
+		instance: {
+			title: `${slug} puzzle`,
+			puzzleDate: '2026-09-11',
+			moreFromPuzzlesAndGames: sampleMoreFromPuzzlesAndGames,
+		},
+		...overrides,
+	};
+};
+
+/** One fixture per supported slug, for local dev preview and tests. */
+export const puzzlePageFixtures: Record<string, FEPuzzlePageType> = Object.keys(
+	puzzleConfigs,
+).reduce<Record<string, FEPuzzlePageType>>((acc, slug) => {
+	acc[slug] = createPuzzlePage(slug);
+	return acc;
+}, {});
+
+/**
+ * A fixture-only illustrative preview/share image URL. None of the real
+ * `puzzleConfigs` registry entries have a real image configured yet (see
+ * docs/puzzle-page.md) - this exists purely so both the with-image and
+ * without-image branches of Puzzle Page's OG/Twitter metadata have fixture
+ * and test coverage, without inventing a placeholder image for the real
+ * registry itself.
+ */
+export const samplePuzzleImageUrl =
+	'https://i.guim.co.uk/img/media/fixture-only-example/puzzle-preview.jpg?width=1200&height=630&quality=85';
+
+/**
+ * Returns a copy of `slug`'s real `PuzzleConfig` with `image` set to
+ * `samplePuzzleImageUrl` - a fixture-only variant for exercising the
+ * with-image branch (the real registry entry itself is left untouched).
+ */
+export const createPuzzleConfigWithImage = (slug: string): PuzzleConfig => {
+	const puzzleConfig = puzzleConfigs[slug];
+
+	if (!puzzleConfig) {
+		throw new Error(`Unknown puzzle slug in fixture: ${slug}`);
+	}
+
+	return { ...puzzleConfig, image: samplePuzzleImageUrl };
+};