fix custom loading screens, add private endpoint for match into instance

apps/rooms/src/openapi.ts

@@ -505,7 +505,7 @@ export const RestrictionsRequest = z.object({
 	supportsJuniors: z.string().optional().describe('`True` / `False`'),
 })
 
-/** `PUT /rooms/{roomId}/loadscreen` — appends one screen to the list. */
+/** `PUT /rooms/{roomId}/loadscreen` — the posted screen replaces the whole list. */
 export const LoadScreenRequest = z.object({
 	imageName: z.string().describe('A key from the storage upload'),
 	title: z.string().optional(),

apps/rooms/src/rooms.app.ts

@@ -1752,24 +1752,31 @@ const app = new Hono<App>()
 		}
 	)
 
-	// Add a load screen to a room (`LoadScreens[]` — the images shown while the room
-	// loads). Auth-gated (401) and owner/co-owner-only (403). Body is the `imageName`
-	// form field plus optional `title`/`subtitle`. Appends one
-	// `{ ImageName, Title, Subtitle }` to the existing list and returns the updated
-	// room in the `{ success, error, value }` envelope.
+	// Set a room's load screen (`LoadScreens[]` — the image shown while the room loads).
+	// Auth-gated (401) and owner/co-owner-only (403). Body is the `imageName` form field
+	// plus optional `title`/`subtitle`. REPLACES the list with the single posted
+	// `{ ImageName, Title, Subtitle }` and returns the updated room in the
+	// `{ success, error, value }` envelope.
+	//
+	// The field is an array because the client's parser wants one, but the client only
+	// ever renders (and only ever posts) a single screen — appending left the old screen
+	// in slot 0 and the new one unreachable behind it, so setting a load screen appeared
+	// to do nothing. Kept as an array so multi-screen support can land without a
+	// migration.
 	.put(
 		'/rooms/:roomId{[0-9]+}/loadscreen',
 		describeRoute({
 			tags: ['Room settings'],
-			summary: 'Add a load screen to a room',
+			summary: 'Set a room’s load screen',
 			description: [
-				'APPENDS one `{ ImageName, Title, Subtitle }` to the room’s `LoadScreens` — the images',
-				'shown while the room loads. There is no remove or replace counterpart. Owner or',
-				'co-owner only (403 otherwise).',
+				'REPLACES the room’s `LoadScreens` with the single posted `{ ImageName, Title,',
+				'Subtitle }` — the image shown while the room loads. The field is an array (the',
+				'client’s parser expects one) but the client only supports a single screen, so this',
+				'never appends. Owner or co-owner only (403 otherwise).',
 			].join(' '),
 			security: AUTHED,
 			parameters: [roomIdParam],
-			requestBody: form(LoadScreenRequest, 'The load screen to append'),
+			requestBody: form(LoadScreenRequest, 'The load screen to set'),
 			responses: {
 				200: json(RoomEnvelope, 'The updated room, or a rejection with `success: false`'),
 				401: UNAUTHORIZED_RESPONSE,
@@ -1793,8 +1800,8 @@ const app = new Hono<App>()
 			const title = typeof body.title === 'string' ? body.title : ''
 			const subtitle = typeof body.subtitle === 'string' ? body.subtitle : ''
 
-			const existing = Array.isArray(room.LoadScreens) ? (room.LoadScreens as unknown[]) : []
-			const loadScreens = [...existing, { ImageName: imageName, Title: title, Subtitle: subtitle }]
+			// The posted screen becomes the whole list — the client shows one load screen.
+			const loadScreens = [{ ImageName: imageName, Title: title, Subtitle: subtitle }]
 			const updated = await updateRoomFields(c.env.DB, roomId, room, { LoadScreens: loadScreens })
 			await pushRoomUpdate(c, accountId, updated)
 			return roomEnvelope(c, updated)

apps/rooms/src/test/integration/api.test.ts

@@ -1258,7 +1258,7 @@ describe('rooms endpoints', () => {
 		expect(typeof room.SupportsMobile).toBe('boolean')
 	})
 
-	it('PUT /rooms/:id/loadscreen appends a load screen (auth-gated, owner/co-owner-only)', async () => {
+	it('PUT /rooms/:id/loadscreen replaces the load screen (auth-gated, owner/co-owner-only)', async () => {
 		const screensOf = async (): Promise<Array<Record<string, unknown>>> => {
 			const room = (await (await SELF.fetch(`${ORIGIN}/rooms/2`)).json()) as {
 				LoadScreens?: Array<Record<string, unknown>>
@@ -1278,10 +1278,8 @@ describe('rooms endpoints', () => {
 			success: false,
 		})
 
-		const before = (await screensOf()).length
-
-		// Owner adds one (imageName + title + subtitle) — appended, and the success
-		// envelope carries the updated room.
+		// Owner sets one (imageName + title + subtitle) — the success envelope carries the
+		// updated room, and the posted screen is the ONLY entry.
 		const added = await envOf(
 			await putForm(
 				'/rooms/2/loadscreen',
@@ -1290,18 +1288,17 @@ describe('rooms endpoints', () => {
 			)
 		)
 		expect(added).toMatchObject({ success: true })
-		expect(added.value?.LoadScreens as unknown[]).toContainEqual({
-			ImageName: 'sharecamera/2026-07-15/abc.jpg',
-			Title: 'asdf',
-			Subtitle: 'sdf',
-		})
-		expect(await screensOf()).toHaveLength(before + 1)
+		expect(added.value?.LoadScreens).toEqual([
+			{ ImageName: 'sharecamera/2026-07-15/abc.jpg', Title: 'asdf', Subtitle: 'sdf' },
+		])
+		expect(await screensOf()).toHaveLength(1)
 
-		// A second call appends rather than replacing; title/subtitle default to empty.
+		// A second call REPLACES rather than appending (the client renders one screen, so
+		// an appended one would sit unreachable behind the old); title/subtitle default to
+		// empty when omitted.
 		const co = await envOf(await putForm('/rooms/2/loadscreen', { imageName: 'second.jpg' }, '2'))
 		expect(co).toMatchObject({ success: true })
-		expect(await screensOf()).toHaveLength(before + 2)
-		expect(await screensOf()).toContainEqual({ ImageName: 'second.jpg', Title: '', Subtitle: '' })
+		expect(await screensOf()).toEqual([{ ImageName: 'second.jpg', Title: '', Subtitle: '' }])
 	})
 
 	it('PUT /rooms/:id/accessibility sets the room-level Accessibility (auth-gated, owner/co-owner-only)', async () => {