Add confirmed uid query param alongside guardian-puzzle-context

Adopts a separately-confirmed mechanism from the native (Android/iOS)
apps' real AmuseLabs integration: append uid=<userId> as a plain
query parameter when the reader is signed in, omitted entirely (not
uid=null or empty) when signed out. This is additive, not a
replacement for guardian-puzzle-context, which still carries dark
mode and puzzle date, for which there is no separately-confirmed
mechanism yet.

Applies uniformly to all 6 registry entries via the shared
buildPuzzleIframeSrc function (renamed from
buildPuzzleIframeSrcWithContext, since it now does more than just the
context), not per-puzzle-type, since the mechanism is provider-level.

uid's value is sourced identically to the existing
guardian-puzzle-context.userId (idToken.claims.legacy_identity_id).
The native apps call their equivalent value a "puzzleId", there is no
independent confirmation the identifier format matches ours, only
that this exact query parameter name/pattern is what they use.

Adds test coverage for uid present/correct when signed in, uid
entirely absent when signed out, and guardian-puzzle-context
coexisting correctly alongside uid in both cases.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: andresilva-guardian

dotcom-rendering/src/components/PuzzleIframe.island.test.tsx

@@ -2,7 +2,7 @@ import { act, render, screen, waitFor } from '@testing-library/react';
 import { getAuthStatus, subscribeToAuthStateChange } from '../lib/identity';
 import { useMatchMedia } from '../lib/useMatchMedia';
 import {
-	buildPuzzleIframeSrcWithContext,
+	buildPuzzleIframeSrc,
 	type PuzzleContext,
 	PuzzleIframe,
 } from './PuzzleIframe.island';
@@ -35,18 +35,15 @@ const signedOut = () => ({ kind: 'SignedOut' as const });
 const contextParam = (context: PuzzleContext) =>
 	`guardian-puzzle-context=${encodeURIComponent(JSON.stringify(context))}`;
 
-describe('buildPuzzleIframeSrcWithContext', () => {
+describe('buildPuzzleIframeSrc', () => {
 	it('appends the context as a JSON query param when the src has none', () => {
 		const context: PuzzleContext = {
 			userId: null,
 			darkMode: false,
 			puzzleDate: null,
 		};
 		expect(
-			buildPuzzleIframeSrcWithContext(
-				'https://example.com/puzzle',
-				context,
-			),
+			buildPuzzleIframeSrc('https://example.com/puzzle', context),
 		).toBe(`https://example.com/puzzle?${contextParam(context)}`);
 	});
 
@@ -57,12 +54,12 @@ describe('buildPuzzleIframeSrcWithContext', () => {
 			puzzleDate: '2026-09-15',
 		};
 		expect(
-			buildPuzzleIframeSrcWithContext(
+			buildPuzzleIframeSrc(
 				'https://example.com/puzzle?set=guardian-sudoku-easy&embed=1',
 				context,
 			),
 		).toBe(
-			`https://example.com/puzzle?set=guardian-sudoku-easy&embed=1&${contextParam(context)}`,
+			`https://example.com/puzzle?set=guardian-sudoku-easy&embed=1&${contextParam(context)}&uid=abc123`,
 		);
 	});
 
@@ -73,22 +70,45 @@ describe('buildPuzzleIframeSrcWithContext', () => {
 			puzzleDate: null,
 		};
 		expect(
-			buildPuzzleIframeSrcWithContext(
-				'https://example.com/puzzle',
-				context,
-			),
+			buildPuzzleIframeSrc('https://example.com/puzzle', context),
 		).toContain('guardian-puzzle-context=');
 	});
 
 	it('returns the src unchanged if it cannot be parsed as an absolute URL', () => {
 		expect(
-			buildPuzzleIframeSrcWithContext('not-a-url', {
+			buildPuzzleIframeSrc('not-a-url', {
 				userId: null,
 				darkMode: false,
 				puzzleDate: null,
 			}),
 		).toBe('not-a-url');
 	});
+
+	it('appends uid alongside guardian-puzzle-context when the reader is signed in', () => {
+		const context: PuzzleContext = {
+			userId: 'user-123',
+			darkMode: false,
+			puzzleDate: null,
+		};
+		const src = buildPuzzleIframeSrc('https://example.com/puzzle', context);
+		const url = new URL(src);
+
+		expect(url.searchParams.get('uid')).toBe('user-123');
+		expect(url.searchParams.has('guardian-puzzle-context')).toBe(true);
+	});
+
+	it('omits uid entirely when the reader is signed out (not uid=null or empty)', () => {
+		const context: PuzzleContext = {
+			userId: null,
+			darkMode: false,
+			puzzleDate: null,
+		};
+		const src = buildPuzzleIframeSrc('https://example.com/puzzle', context);
+		const url = new URL(src);
+
+		expect(url.searchParams.has('uid')).toBe(false);
+		expect(url.searchParams.has('guardian-puzzle-context')).toBe(true);
+	});
 });
 
 describe('PuzzleIframe', () => {
@@ -108,6 +128,9 @@ describe('PuzzleIframe', () => {
 		) as PuzzleContext;
 	};
 
+	const getUidFromSrc = (src: string): string | null =>
+		new URL(src).searchParams.get('uid');
+
 	it('renders userId: null and darkMode: false while signed out with dark mode unavailable', async () => {
 		mockedGetAuthStatus.mockResolvedValue(signedOut());
 
@@ -349,4 +372,70 @@ describe('PuzzleIframe', () => {
 			expect(getContextFromSrc(iframe.src).puzzleDate).toBeNull(),
 		);
 	});
+
+	it('includes uid alongside guardian-puzzle-context once signed in', async () => {
+		mockedGetAuthStatus.mockResolvedValue(signedIn('user-123'));
+
+		render(
+			<PuzzleIframe
+				src="https://example.com/puzzle"
+				title="Puzzle"
+				darkModeAvailable={false}
+				puzzleDate={null}
+			/>,
+		);
+
+		const iframe = await screen.findByTitle<HTMLIFrameElement>('Puzzle');
+		await waitFor(() => expect(getUidFromSrc(iframe.src)).toBe('user-123'));
+		expect(
+			new URL(iframe.src).searchParams.has('guardian-puzzle-context'),
+		).toBe(true);
+	});
+
+	it('omits uid entirely while signed out (not uid=null or empty)', async () => {
+		mockedGetAuthStatus.mockResolvedValue(signedOut());
+
+		render(
+			<PuzzleIframe
+				src="https://example.com/puzzle"
+				title="Puzzle"
+				darkModeAvailable={false}
+				puzzleDate={null}
+			/>,
+		);
+
+		const iframe = await screen.findByTitle<HTMLIFrameElement>('Puzzle');
+		await waitFor(() =>
+			expect(getContextFromSrc(iframe.src).userId).toBeNull(),
+		);
+		expect(new URL(iframe.src).searchParams.has('uid')).toBe(false);
+		expect(
+			new URL(iframe.src).searchParams.has('guardian-puzzle-context'),
+		).toBe(true);
+	});
+
+	it('removes uid again if the reader signs back out', async () => {
+		mockedGetAuthStatus.mockResolvedValueOnce(signedIn('user-123'));
+
+		render(
+			<PuzzleIframe
+				src="https://example.com/puzzle"
+				title="Puzzle"
+				darkModeAvailable={false}
+				puzzleDate={null}
+			/>,
+		);
+
+		const iframe = await screen.findByTitle<HTMLIFrameElement>('Puzzle');
+		await waitFor(() => expect(getUidFromSrc(iframe.src)).toBe('user-123'));
+
+		const onAuthStateChange =
+			mockedSubscribeToAuthStateChange.mock.calls[0]![0];
+		mockedGetAuthStatus.mockResolvedValueOnce(signedOut());
+		await act(async () => {
+			onAuthStateChange();
+		});
+
+		await waitFor(() => expect(getUidFromSrc(iframe.src)).toBeNull());
+	});
 });

dotcom-rendering/src/components/PuzzleIframe.island.tsx

@@ -4,7 +4,7 @@ import { getAuthStatus, subscribeToAuthStateChange } from '../lib/identity';
 import { useMatchMedia } from '../lib/useMatchMedia';
 
 interface Props {
-	/** The already-resolved iframe src URL (with `{slug}` substituted). */
+	/** The already-resolved iframe src URL for this puzzle. */
 	src: string;
 	title: string;
 	/**
@@ -137,14 +137,33 @@ const buildPuzzleContext = (
 
 /**
  * Encodes `context` as JSON into a `guardian-puzzle-context` query
- * parameter on `src`, preserving any existing query parameters (e.g.
- * AmuseLabs' `?set=...&embed=1&idx=1`). Always includes the parameter -
- * unlike the previous `userId`-only mechanism, the context shape itself
- * always carries both fields, so there's no "nothing to add" case to omit
- * it for. Returns `src` unchanged if it cannot be parsed as an absolute
- * URL.
+ * parameter on `src` (preserving any existing query parameters, e.g.
+ * AmuseLabs' `?set=...&embed=1&idx=1`), and, separately, appends a plain
+ * `uid=<userId>` query parameter when the reader is signed in.
+ *
+ * `uid` is a genuinely different, independently-confirmed mechanism from
+ * `guardian-puzzle-context`: the native (Android/iOS) apps' own real,
+ * working AmuseLabs integration appends `&uid=<value>` as a plain query
+ * parameter when the user is authenticated, and omits it entirely when
+ * signed out (their own words: "If the user is authenticated, we add
+ * &uid=<puzzleId>"). It is added here *alongside*, not instead of,
+ * `guardian-puzzle-context` (which still carries dark mode and puzzle
+ * date, for which there is no separately-confirmed mechanism yet). `uid`'s
+ * value is sourced identically to `context.userId`
+ * (`idToken.claims.legacy_identity_id`), the native apps call their
+ * equivalent value a "puzzleId", but there is no independent confirmation
+ * that identifier format matches ours, only that this exact query
+ * parameter name/pattern is what they use for their own equivalent value,
+ * see the "Open questions" section of docs/puzzle-page.md.
+ *
+ * Always includes `guardian-puzzle-context` - unlike the previous
+ * `userId`-only mechanism, the context shape itself always carries all
+ * three fields, so there's no "nothing to add" case to omit it for. `uid`
+ * is the only conditional part, present only when `context.userId` is
+ * non-null, and never sent as `uid=null` or empty. Returns `src` unchanged
+ * if it cannot be parsed as an absolute URL.
  */
-export const buildPuzzleIframeSrcWithContext = (
+export const buildPuzzleIframeSrc = (
 	src: string,
 	context: PuzzleContext,
 ): string => {
@@ -154,6 +173,9 @@ export const buildPuzzleIframeSrcWithContext = (
 			'guardian-puzzle-context',
 			JSON.stringify(context),
 		);
+		if (context.userId !== null) {
+			url.searchParams.set('uid', context.userId);
+		}
 		return url.toString();
 	} catch {
 		return src;
@@ -183,12 +205,16 @@ const postContextMessage = (
  * iframe `src` (so it is present from the very first request the iframe
  * makes), and via `postMessage` once the iframe has loaded (`{ type:
  * 'guardian-puzzle-context', context }` - see `PuzzleContextMessage`).
- * Because `src` is derived from the reactive `usePuzzleUserId()`/
- * `usePuzzleDarkMode()` results, the iframe is automatically reloaded by
- * the browser (a fresh `src` triggers a new navigation) whenever the
- * reader's sign-in state or OS colour-scheme preference changes while on
- * the page - no manual reload fallback is needed for that case, though the
- * `onLoad` `postMessage` still fires again after each such reload too.
+ * When the reader is signed in, also appends a plain `uid=<userId>` query
+ * parameter alongside `guardian-puzzle-context` (see
+ * `buildPuzzleIframeSrc`'s doc comment), a separately-confirmed mechanism
+ * from the native apps' real AmuseLabs integration. Because `src` is
+ * derived from the reactive `usePuzzleUserId()`/`usePuzzleDarkMode()`
+ * results, the iframe is automatically reloaded by the browser (a fresh
+ * `src` triggers a new navigation) whenever the reader's sign-in state or
+ * OS colour-scheme preference changes while on the page - no manual
+ * reload fallback is needed for that case, though the `onLoad`
+ * `postMessage` still fires again after each such reload too.
  */
 export const PuzzleIframe = ({
 	src,
@@ -199,7 +225,7 @@ export const PuzzleIframe = ({
 	const userId = usePuzzleUserId();
 	const darkMode = usePuzzleDarkMode(darkModeAvailable);
 	const context = buildPuzzleContext(userId, darkMode, puzzleDate);
-	const iframeSrc = buildPuzzleIframeSrcWithContext(src, context);
+	const iframeSrc = buildPuzzleIframeSrc(src, context);
 
 	return (
 		<iframe