← Kembali

CV Preview Tanpa Reload: Menjinakkan PDF di dalam Pool Iframe

browser caching chromium debugging frontend htmx iframe javascript pdf

CV Preview Tanpa Reload: Menjinakkan PDF di dalam Pool Iframe

Halaman daftar kandidat di SkillTrace harus memungkinkan recruiter berpindah cepat antar-CV dengan tombol panah — panel preview yang menampilkan file asli (PDF) dalam <iframe>, terkunci di tengah-kanan layar. Perjalanan dari "iframe yang sekali dibuka langsung kosong" menuju "pindah antar-kandidat secara instan" ternyata melewati empat bug browser yang menarik: kapan PDF viewer-nya gagal me-render ulang di node yang sama, kenapa file ke-download tapi layar kosong, kenapa tombol panah tiba-tiba "stuck" saat fokus masuk ke dalam iframe, dan kenapa kandidat yang sudah di-preload justru blank — sampai akhirnya pool 50 kandidat terbaik dipanaskan otomatis begitu screening selesai. Ini catatan debugging-nya.

Work Log

  • [00:10:00] Kapal panel awal: iframe + blob URL + loading overlay + fallback TXT — PDF sebenarnya render (terlihat di log PDF.js), tapi layout/overlay membuatnya tak terlihat
  • [00:40:00] Sederhanakan drastis jadi satu iframe polos height:70vh yang memuat URL CV autentik per kandidat — user konfirmasi: "sudah tampil"
  • [01:00:00] User minta panel selalu terlihat di tengah-kanan saat scroll + pindah kandidat tanpa reload
  • [01:20:00] Percobaan pertama: warm HTTP cache dengan iframe 1px tersembunyi + Cache-Control: private, max-age=600 — tetap terasa "load" saat berpindah
  • [01:50:00] Keputusan: kept-alive frame pool — muat CV sekali, render permanen, pindah = pindah visibility (CSS murni)
  • [02:20:00] Pool 5 frame bekerja… sampai user klik kandidat ke-10 → blank padahal Network menunjukkan file ter-download → Chromium PDF-viewer reuse bug
  • [02:50:00] Fix node-reuse: setiap CV baru mendapat <iframe> DOM baru (swapFrameNode)
  • [03:10:00] Pool 5 → 20 dengan window preload ±5 (klik #30 → hangat #25–#35)
  • [03:40:00] Bug baru: klik row berfungsi tapi panah ↑/↓ "stuck" di #30 → fokus tersesat di dalam iframe
  • [04:05:00] Fix 3 lapis: stealFocus() + mousedown capture + forwarded keydown per-frame
  • [04:25:00] Verifikasi di browser + pytest test_web.py (94 passed)
  • [04:40:00] Bug preload-then-show: kandidat yang sudah di-preload (ke frame tersembunyi) blank saat dipanah, yang belum pernah di-load normal → fix sementara: loadIntoFrame selalu rebuild node → semua render, tapi jadi "reload ±2s" tiap pindah
  • [05:05:00] User: keep-alive untuk 50 kandidat skor terbaik → POOL_SIZE 20 → 50 + aturan shownOnce (pernah tampil → reuse instan; baru-preload → build ulang)
  • [05:35:00] Auto-preload top-50 setelah screening selesai: data-progress/data-score + preloadBestScores() (page load + tiap htmx:afterSwap saat progress 100%)
  • [05:50:00] Test update (pool 50, data-progress, data-score) → 94 passed → commit 5bd26bd

Context

  • Proyek: SkillTrace — mesin screening CV berbasis evidence (Django monolith + Celery + PostgreSQL + Redis)
  • Halaman: /jobs/<uid>/candidates/ — tabel kandidat (di-poll HTMX tiap 3 detik) + panel preview CV tetap di tengah-kanan
  • CV disajikan lewat view autentik same-origin (@xframe_options_sameorigin: X-Frame-Options: SAMEORIGIN), streaming dari object storage, bukan URL /media publik
  • Interaksi: klik row / panah ↑↓ / Esc; "Open original" buka file di tab baru. Kandidat yang sudah pernah dibuka harus langsung tampil lagi — scroll & zoom PDF-nya pun ikut tersimpan
  • Setelah screening selesai, pool otomatis diisi 50 kandidat skor teratas (tabel sudah diurutkan best-score-first); baris yang belum selesai di-screen (tanpa skor) dilewati

Problem 1 — Pindah kandidat selalu "load" meski file sudah di-cache

Preload pertama menghangatkan cache browser: iframe 1px tersembunyi memuat CV tetangga lebih dulu, dan view CV mengirim Cache-Control: private, max-age=600. Dipikir pindah akan instan. Kenyataannya tetap ada momen blank/loading tiap pindah.

Akar masalah: cache tidak menghindari re-render. Setiap iframe.src diubah, browser menghancurkan dan membuat dokumen PDF dari nol — re-parse + re-render seluruh PDF. HTTP cache hanya menghapus beban network, bukan biaya render.

Solusi — kept-alive frame pool. Jangan pernah mengganti src setelah file ter-load. Alokasikan pool iframe yang semua bertumpuk di posisi yang sama; berpindah kandidat cukup memindahkan class .cv-active:

.cv-frame {
  position: absolute; inset: 0; width: 100%; height: 100%;
  visibility: hidden; opacity: 0; transition: opacity .12s ease;
}
.cv-frame.cv-active { visibility: visible; opacity: 1; }

Sengaja memakai visibility — bukan display:none — karena visibility:hidden tetap menjaga PDF ter-render di background, jadi kandidat yang pernah dibuka kembali tampil seketika (scroll/zoom ikut tersimpan). Pool di-evict dengan LRU (frame paling lama tak dipakai dibuang, frame aktif tidak pernah di-evict), dan frame hidup di luar region swap HTMX sehingga polling 3 detik tidak menghancurkan CV yang sudah ter-load.

Problem 2 — Kandidat #1–#5 tampil, klik #10 blank padahal file ter-download

Pool 5 bekerja, tapi begitu slot habis dan user lompat jauh (klik #10), frame-nya kosong. Yang bikin bingung: DevTools Network menunjukkan file benar-benar ter-download (200 / disk-cache), PDF.js-nya pun berhasil parse. Console juga dipenuhi warning Partitioned cookie or storage access... — kelihatan seperti penyebab.

Akar masalah 1 (red herring): warning partitioning itu pesan info Chrome soal dynamic state partitioning untuk iframe — ia muncul juga untuk PDF yang berhasil dirender. Bukan penyebabnya.

Akar masalah 2 (yang sebenarnya): Chromium PDF viewer reuse bug. View PDF bawaan Chrome gagal me-render ulang ketika node <iframe> yang sama diarahkan ke URL PDF kedua. Klik #10 → node yang pernah menampilkan PDF lain di-set src ke PDF baru → byte ter-download tapi plugin tidak inisialisasi ulang → layar kosong.

Solusi — jangan pernah re-use node untuk PDF kedua. Setiap kali slot diisi kandidat baru, buat <iframe> DOM baru untuk PDF itu:

function swapFrameNode(slot) {
  var fresh = document.createElement("iframe");
  fresh.className = "cv-frame";
  /* salin status aktif bila perlu */
  slot.frame.parentNode.appendChild(fresh);
  slot.frame.parentNode.removeChild(slot.frame);
  slot.frame = fresh;
  fresh.src = slot.cvUrl;   // node perawan → plugin viewer segar
}

Setiap PDF kini render di view-instance yang "perawan", jadi selalu tampil. (Sekadar menitip src="about:blank" sebelum gotaject bukan obat — inti masalahnya reuse node itu sendiri.)

Problem 3 — Arrow ↑/↓ stuck padahal klik row berfungsi

Setelah pool 20 + preload window ±5 stabil, muncul keluhan baru: klik #30 memuat benar, tapi begitu tekan panah ↑/↓, navigasi tidak pindah — masih mentok di #30. Padahal handler keydown-nya sudah benar dan selectCandidate bekerja (terbukti dari klik).

Akar masalah — ownership fokus. Handler document.addEventListener("keydown", ...) hanya dipanggil bila fokus berada di dokumen utama. Begitu fokus masuk ke dalam iframe (misal user mengklik PDF untuk zoom), semua keydown panah dikonsumsi oleh inner document iframe itu sendiri — tidak pernah naik/bubble ke document halaman induk. Klik row tetap bekerja karena listener click di document menangkap klik pada <tr> (dan mengklik <tr>/<td> yang non-focusable tidak memindahkan fokus keluar dari iframe). Hasilnya pola yang khas: klik jalan, panah mati.

Solusi — 3 lapis:

// 1) Paksa fokus kembali ke dokumen utama setelah tiap navigasi
function stealFocus() {
  var f = cvActiveSlot && cvActiveSlot.frame;
  if (f && document.activeElement && f.contains(document.activeElement)) f.blur();
  panelEl.setAttribute("tabindex", "-1");
  if (document.activeElement !== document.body) panelEl.focus({ preventScroll: true });
}
selectCandidate = function() { /* ... show, preload, scroll ... */ stealFocus(); };

// 2) Klik di luar panel → blur frame aktif; klik di dalam panel → biarkan (zoom PDF)
document.addEventListener("mousedown", function (e) {
  if (e.target.closest && e.target.closest("#cv-preview-panel")) return;
  var f = cvActiveSlot && cvActiveSlot.frame;
  if (f && document.activeElement && f.contains(document.activeElement)) f.blur();
}, true);

// 3) Forward keydown dari dalam frame same-origin (about:blank / TXT)
function wireFrameKeyboard(frame) {
  try {
    var doc = frame.contentDocument;
    if (!doc || doc === frame.ownerDocument) return;
    doc.addEventListener("keydown", navigateFromKey);   // panah → selectCandidate
  } catch (e) { /* dokumen PDF = ekstensi cross-origin, tak bisa diakses */ }
}

Lapis ke-3 di-re-wire tiap frame load dan setelah swapFrameNode. Khusus frame PDF, contentDocument adalah dokumen ekstensi cross-origin (tidak scriptable) → dibungkus try/catch dan dilewati. Kombinasi ini membuat panah tetap responsif bahkan setelah user berinteraksi dengan isi PDF, selama fokus kembali ke dokumen utama.

Problem 4 — Kandidat yang sudah ter-preload malah blank, lalu "rasa preload hilang"

Setelah fix fokus, muncul pola baru: panah yang menuju kandidat yang sudah pernah di-preload ke frame tersembunyi justru blank, sementara kandidat yang belum pernah di-load dan di-klik pertama kali tampil normal. Kenapa?

Dokumen PDF yang selesai dimuat saat iframe-nya visibility:hidden tidak merender apa pun — plugin viewer-nya diinisialisasi dalam keadaan tersembunyi, dan membalik menjadi visibility:visible saja tidak memaksa render. Kandidat hasil klik pertama tidak pernah load saat tersembunyi (dibuat, di-set src, langsung ditampilkan), jadi plugin-nya sehat. Inilah bagian kedua dari Chromium reuse quirk: ia tidak hanya menimpa node yang menampilkan PDF pertama lalu diarahkan ke PDF kedua (Problem 2), tapi juga node yang diisi sekali oleh preload tersembunyi.

Fix pertama (yang salah arah): loadIntoFrame membangun ulang node setiap kali kandidat ditampilkan — termasuk yang sudah ada di frameByUid (fresh node diisi dari cache yang hangat):

if (existing) { delete frameByUid[existing.uid]; existing.uid = null; }
loadCandidateIntoslot(c, slot, now);   // swapFrameNode + src → selalu render

Semua tampil, tetapi setiap perpindahan menciptakan node baru → PDF di-re-parse ulang → terasa "load ±2 detik". User menyebutnya "rasa preloadnya hilang".

Keputusan: keep-alive top 50 — reuse hanya kalau pernah tampil

Biaya re-parse hanya muncul ketika node di-build ulang; satu-satunya cara pindah seketika adalah memakai kembali node yang sudah pernah render saat visible. Penengahannya dengan membedakan dua status per slot — pernah tampil vs sekadar pernah di-load (shownOnce):

function loadIntoFrame(c, now) {
  var existing = frameByUid[c.uid];
  if (existing && existing.shownOnce) {   // pernah tampil → reuse → instan
    existing.lastUsed = now;
    return existing;
  }
  // belum pernah tampil (hasil preload tersembunyi) → build ulang node
  var slot = existing || nextFreeSlot() || evictLRU();
  loadCandidateIntoslot(c, slot, now);     // fresh node → dijamin render
  return slot;
}
// showCandidate: slot.shownOnce = true;  lalu pindahkan .cv-active (hapus dari slot lama)
  • shownOnce === false (belum pernah ditampilkan): node di-build ulang dari cache → dijamin render (biaya satu re-parse, tanpa network).
  • shownOnce === true (pernah tampil, render saat visible): node dipakai ulang apa adanya → perpindahan murni CSS visibility, tanpa re-parse; scroll & zoom PDF ikut tersimpan.
  • Pool dinaikkan ke POOL_SIZE = 50 (50 iframe statis, dirender lewat loop template) dan preloadNearest mengisi semua slot bebas (cap ±5 dihapus). Karena tabel sudah diurutkan skor tertinggi di atas, pool 50 = 50 kandidat terbaik yang stay-alive.
  • Saat aktif dipindah, .cv-active harus dihapus dari slot lama dulu: pool bertumpuk penuh dan frame aktif yang tertinggal akan menutupi yang baru.

Bonus: auto-preload setelah screening selesai

Kandidat yang di-klik selalu sudah selesai di-screen, jadi begitu screening kelar tidak perlu menunggu klik. Fragment HTMX kini memuat data-progress di root dan data-score di tiap baris; begitu progress mencapai 100 — baik di page-load maupun di tiap htmx:afterSwap polling — preloadBestScores() mengisi pool dengan 50 kandidat ber-skor terbaik di background. Yang belum selesai di-screen (tanpa skor) dilewati, jadi "top 50" selalu berarti "50 terbaik yang sudah jelas skornya". Hasilnya: kandidat terbaik sudah hangat dan rendern cepat di klik pertama.

Insight

  • Cache ≠ instant render. Cache-Control menghilangkan biaya network, bukan biaya re-render. "File udah ke download" dan "layar masih blank" adalah dua hal yang bisa terjadi bersamaan — jangan simpulkan keduanya dari tab Network saja.
  • Fokus adalah milik satu dokumen. Keydown tidak pernah melintasi batas iframe. Gejala "klik jalan, panah mati" hampir selalu menunjuk ke fokus yang terjebak di dalam iframe — cek cepat: document.activeElement.tagName === "IFRAME".
  • Element yang "dewasa" bisa membawa bug. Membuat node DOM baru untuk dokumen baru (PDF plugin) kadang lebih aman daripada re-use node — ini versi frontend dari "jangan share Scribd instance". LRU eviction memastikan biaya memori tetap terbatas (50 PDF hanya yang paling sering digunakan).
  • "Pernah tampil" ≠ "pernah di-load". Dokumen yang selesai dimuat saat tersembunyi bisa blank saat ditampilkan; dokumen yang pernah dirender saat visible akan selalu tampil lagi. shownOnce adalah pembeda kuncinya, dan ia yang membuat "reuse node" aman untuk dipakai.
  • Asimetri biaya keep-alive. Menampilkan kandidat hasil preload pertama kali ≈ satu re-parse (tanpa network, berkat cache); kunjungan berikutnya = 0. Dengan 50 kandidat terbaik yang stay-alive, "rasa preload" kembali terasa tanpa mengorbankan jaminan render.
  • Preload adalah "uang" yang menunggu. Mengisi pool di background begitu screening kelar menukar biaya idle dengan kecepatan klik-pertama — pemicunya harus sinyal deterministik (progress 100%), bukan tebakan kapan user kembali ke tab.
  • Blur mengembalikan fokus ke body. Memanggil frame.blur() cukup untuk mengembalikan keydown ke document; fokus ke panel tabindex="-1" (preventScroll, tanpa fokus-ring) adalah jaring pengaman untuk kasus fokus null.

Gotchas

  • visibility:hidden menjaga iframe tetap ter-render; display:none bisa membuat browser menunda/suspend render plugin. Pilih visibility untuk pool.
  • Tapi visibility:hidden selama load adalah kutukan: PDF yang selesai dimuat saat tersembunyi bisa blank ketika dibalik visible. Jaga aturan "reuse node hanya jika sudah pernah tampil" (shownOnce).
  • Saat membangun ulang pool, .cv-active hanya boleh ada di satu frame — frame keep-alive bertumpuk penuh dan aktif yang tertinggal akan menutupi yang baru. Hapus dari slot lama sebelum menandai yang baru.
  • Warning Partitioned cookie or storage access di console bukan tanda aplikasi rusak — itu pesan info storage-partitioning yang juga muncul untuk iframe yang render normal. Jangan buang waktu mengejar red herring ini.
  • scrollIntoView pada elemen yang sudah terlepas dari DOM (setelah HTMX swap tanpa re-sync) adalah no-op, bukan exception — tidak akan menampakkan dirinya sebagai error console.
  • Pool 50 menghangatkan 50 kandidat terbaik (urutan data-score), tapi 50 PDF ter-render memakan RAM — POOL_SIZE tetap konstanta terpusat yang mudah diturunkan.
  • data-progress harus dibaca dari elemen hasil swap (e.detail.target), bukan variabel lama — polling HTMX merefresh tabel tiap 3 detik.
  • Row tabel di-poll ulang HTMX tiap 3 detik: kunci pool dengan uid kandidat (bukan index) supaya frame yang sudah hangat tetap terpakai; frame milik uid yang hilang di-prune.
  • Kunjungan kedua ke kandidat yang sama harus memercik (disk cache) — kalau tidak, periksa header Cache-Control: private, max-age=600 (cache privat, TTL pendek, sesuai kebutuhan privasi data kandidat).

Kesimpulan

Empat jebakan yang saling terhubung: (1) mengubah src iframe selalu me-render ulang PDF sehingga "cache tidak cukup", diselesaikan dengan kept-alive frame pool yang berpindah lewat visibility; (2) Chromium gagal me-render ulang PDF di node iframe yang di-reuse, diselesaikan dengan <iframe> baru untuk tiap PDF; (3) fokus yang masuk ke dalam iframe mencuri event panah, diselesaikan dengan menegaskan kembali kepemilikan keyboard ke dokumen utama; dan (4) PDF yang selesai dimuat saat tersembunyi blank ketika dibalik visible — diselesaikan dengan aturan shownOnce: node dipakai ulang hanya bila sudah pernah tampil, dan di-build ulang (dari cache) bila baru hasil preload.

Keputusan UX terakhir memperbesar pool ke 50 kandidat terbaik (urutan skor sudah jadi milik tabel) dan mengotomatiskan warm-up-nya: begitu screening selesai, preloadBestScores mengisi pool di background sehingga klik pertama ke kandidat top-50 tampil cepat, dan perpindahan panah antar mereka terasa instan tanpa reload. 94 test tetap hijau.

Stats

  • Total errors di kode: 0 (semua adalah ketidakcocokan perilaku browser, bukan crash)
  • Perubahan kode netto: kept-alive pool 50 + auto-preload (job_candidates.html, _candidates_section.html) + 1 header cache (candidate_cv_view)
  • Browser yang ter-pengaruhi: Chromium PDF viewer (reuse bug + load-tersembunyi + fokus iframe)
  • Rentang waktu pengerjaan: ±2 sesi (est. 6,5 jam, termasuk iterasi diskusi UX)
  • Lapisan yang didiagnosis: tampilan/overlay → HTTP cache → plugin PDF browser → fokus/keyboard → lifecycle preload-visible

Terakhir diperbarui 24 Sep 2026 23:08

Comments