FE_14 - PDF Slide Viewer Broken on iOS Safari

[notjackl3]

Summary

Fix the slide viewer so PDFs render correctly on iOS (Safari/iPhone/iPad). The site is currently unusable on iOS during lectures — the slide panel fails to display the PDF, likely due to how EmbedPDF renders pages to a canvas at high scale.
[Estimated hours: 4-6]

Objectives

• Reproduce the failure on a real iOS device (iPhone + iPad, Safari) and document the exact symptom (blank canvas, crash, endless load)
• Identify the root cause in the EmbedPDF/pdfium rendering pipeline (canvas size limits, WASM engine init, memory)
• Fix rendering so slides display and page navigation works on iOS Safari
• Add a graceful fallback if the engine fails to initialize (error message instead of a silent blank panel)
• Verify the rest of the room view (chat, sockets) still works on iOS

Description

Students opening a session on an iPhone or iPad cannot see the slides — the PDF panel does not render, which effectively breaks the site on iOS since the slide viewer is half the room view. Desktop browsers (Chrome/Firefox) work fine.

The viewer (src/app/room/slideViewer.tsx) renders PDF pages via EmbedPDF's RenderLayer with scale={3}, which draws each page to an internal <canvas>. iOS Safari enforces hard canvas limits (max dimensions and total canvas memory per page); a slide page rendered at 3x scale can easily exceed them, producing a blank/black canvas with no thrown error. The pdfium WASM engine (usePdfiumEngine()) may also fail or run out of memory on iOS. Both paths need to be investigated.

User Flow

Student opens session link on iPhone (Safari)
     → Room view loads, chat works
     → Slide panel: PDF never appears (blank area / spinner)
     → Expected: current slide renders, professor sync ("slide:changed") moves pages
     → After fix: slides render on iOS at a scale Safari can handle,
       and any engine failure shows a visible error state instead of blank UI

Technical Details

Affected Files

src/app/room/slideViewer.tsx      # RenderLayer scale={3}, pdfium engine init,
                                  #   canvas-constraining CSS ([&_canvas] rules)
src/app/api/sessions/[sessionId]/slides/[slideSetId]/file/
└── route.ts                      # Serves the PDF (Content-Disposition: inline) — verify
                                  #   headers/range behavior are Safari-friendly

Investigation Notes

• Current render call:

  <RenderLayer documentId={activeDocumentId} pageIndex={pageIndex} scale={3} ... />

  iOS Safari caps canvas dimensions (~4096px historically) and total canvas memory; scale={3} on a 16:9 slide deck likely exceeds this. Try a device-aware scale (e.g. cap by devicePixelRatio and viewport size) instead of a hardcoded 3.
• Check that usePdfiumEngine() (WASM) initializes on iOS Safari — add an error/loading state if engine fails rather than rendering nothing.
• Verify the file route works under Safari's fetch behavior (it re-requests ranges more aggressively than Chrome); confirm Content-Type: application/pdf and caching headers are correct.
• Test with a realistic lecture deck (50+ pages, several MB), not just a 1-page sample — iOS memory limits are per-page cumulative.

Acceptance Criteria

• Slides render correctly in Safari on iPhone and iPad (real devices, not just simulator)
• Page navigation and professor sync (slide:changed / slide:sync) work on iOS
• Rendered slide remains sharp on desktop (no visible quality regression from scale changes)
• Large decks (50+ pages) can be paged through on iOS without the canvas going blank or the tab crashing
• If the PDF engine fails to load, the user sees an explicit error state (not an empty panel)
• No regression in Chrome/Firefox/desktop Safari
• Root cause documented in the PR description (what iOS limit/behavior was hit)

Notes

• If EmbedPDF/pdfium turns out to be fundamentally incompatible with iOS Safari, evaluate rendering at lower scale + CSS upscaling first; swapping libraries (e.g. pdf.js) is a last resort and should be a separate ticket.
• Related history: FE_2 (Embed PDF), FE_5 (PDF Nav BUG), BE_14 (PDF Retrieval and Real-time Display).