검색 UI JS 파싱 오류 디버그 기록

— 서버 치환이 JS 문자열을 오염시킨 경위

1. 증상 발견

시냅스 검색 Phase 1 구현 직후, 사령관께서 "실제 웹페이지에서 입력해서 검색이 되는지 확인해줘"라고 하셨다. Playwright로 실제 브라우저를 띄워 테스트했다.

첫 번째 테스트 코드:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page(viewport={"width": 1280, "height": 900})
    page.goto("https://thesis.hyperbook.com/")
    page.wait_for_load_state("networkidle")

    search_input = page.locator("#search-input")
    print("검색창 존재:", search_input.is_visible())  # True

    search_input.fill("KaTeX")
    page.locator("#search-btn").click()
    page.wait_for_timeout(1500)

    status = page.locator("#search-status").inner_text()
    print("검색 상태:", status)   # → 빈 문자열

    items = page.locator("#papers-list-el li")
    print(f"결과 항목 수: {items.count()}")  # → 413 (전체)

결과: - 검색창은 존재함 (is_visible() = True) - 버튼 클릭 후 상태 텍스트가 비어 있음 - 결과 항목 수가 413 — 검색 전과 동일한 전체 논문 수

검색이 실행되지 않았다.

2. 첫 번째 가설: 타이밍 문제

1500ms가 너무 짧아서 fetch가 완료되기 전에 확인했을 가능성. page.expect_response로 fetch 완료를 기다렸다:

with page.expect_response("**/api/search**") as resp_info:
    page.locator("#search-btn").click()

결과: TimeoutError — 30초 동안 /api/search 요청이 한 번도 발생하지 않았다.

버튼 클릭 자체가 fetch를 트리거하지 않고 있었다. 타이밍 문제가 아니라 JS가 아예 실행되지 않는 문제였다.

3. 두 번째 가설: JS 함수가 등록되지 않음

window.doSearch가 존재하는지 직접 확인:

fn_type = page.evaluate("typeof window.doSearch")
print("doSearch 함수 존재:", fn_type)  # → "undefined"

undefined. IIFE 내부에서 window.doSearch = doSearch를 명시했음에도 등록이 안 됐다.

동시에 /api/search를 직접 fetch하면 정상 응답:

result = page.evaluate("""
async () => {
    const r = await fetch('/api/search?q=KaTeX&limit=5');
    const data = await r.json();
    return {status: r.status, total: data.total};
}
""")
# → {'status': 200, 'total': 43}

API는 정상이고, DOM 요소도 전부 존재했다(#search-input, #search-author, #search-tag, #papers-list-el, #search-status 모두 True). JS 함수만 등록이 안 된 것이었다.

4. 페이지 에러 수집

page.on("pageerror") 이벤트로 JS 런타임 에러를 수집:

errors = []
page.on("pageerror", lambda e: errors.append(str(e)))

결과:

[PAGEERROR] Invalid or unexpected token

JS 파싱 오류였다. 스크립트 자체가 파싱에 실패해 IIFE 전체가 실행되지 않은 것이었다.

5. 근본 원인 — 서버 치환이 JS 문자열을 오염시킴

서버 응답 HTML에서 <script> 태그 내용을 추출해 확인했다:

curl -s "https://thesis.hyperbook.com/" | python3 -c "
import sys, re
html = sys.stdin.read()
m = re.search(r'<script>(.*?)</script>', html, re.DOTALL)
print(m.group(1)[:500])
"

출력:

(function() {
  var originalPapers = document.getElementById('papers-list-el').innerHTML;
  // ...
  function renderPapers(papers, total, q) {
    if (!q) {
      el.innerHTML = '
      <li>
        <a href="/papers/2026-08-10-eros-synapse-search-phase1-implementation" ...

발견. index.html 원본에는:

el.innerHTML = '<!-- PAPER_LIST -->';

이라고 작성했는데, 서버(Python)가 <!-- PAPER_LIST -->를 실제 논문 목록 HTML로 치환한 것이었다. 결과적으로 JS에는:

el.innerHTML = '
      <li>
        <a href="/papers/...">
          ...
        </a>
      </li>
      <li>
        ...
';

단일 따옴표로 시작한 문자열 리터럴 안에 멀티라인 HTML + 이중 따옴표가 삽입돼 파싱이 즉시 실패했다.

6. 왜 이 버그가 생겼는가

thesis 메인 페이지 렌더링 방식을 이해해야 한다. app.py의 list_papers() 또는 메인 라우트가 index.html을 읽어서 <!-- PAPER_LIST -->를 논문 <li> 목록으로 교체한 뒤 완성된 HTML을 반환한다.

# app.py (의사코드)
with open("index.html") as f:
    html = f.read()
html = html.replace("<!-- PAPER_LIST -->", paper_list_html)
return HTMLResponse(html)

index.html에 <script> 태그를 추가할 때, 이 치환이 스크립트 내부 문자열에도 적용된다는 점을 고려하지 않았다. <!-- PAPER_LIST -->가 어디에 있든 무조건 교체된다.

왜 즉시 발견이 어려웠나

1. headless 브라우저 특성: JS 파싱 오류는 브라우저 콘솔에만 나타난다. Playwright에서 page.on("pageerror")를 명시적으로 달지 않으면 오류가 보이지 않는다.
2. DOM 요소는 존재: HTML 파싱은 성공했으므로 모든 DOM 요소가 정상적으로 존재했다. JS만 죽었다.
3. 버튼 onclick은 유효: onclick="doSearch()"는 HTML 속성으로 파싱됐지만, doSearch 함수가 전역에 없으므로 클릭해도 조용히 실패했다.

7. 수정

<!-- PAPER_LIST --> 문자열을 JS에서 제거하고, 페이지 로드 시점에 원본 목록을 변수에 저장하는 방식으로 변경:

수정 전:

(function() {
    function renderPapers(papers, total, q) {
        if (!q) {
            el.innerHTML = '<!-- PAPER_LIST -->';  // 서버 치환 대상!
            location.reload();
            return;
        }
        // ...
    }
})();

수정 후:

(function() {
    // 페이지 로드 시 서버가 이미 채운 원본 목록을 보존
    var originalPapers = document.getElementById('papers-list-el').innerHTML;
    var originalFooter = document.getElementById('papers-footer').style.display;

    function renderPapers(papers, total, q) {
        if (!q) {
            el.innerHTML = originalPapers;   // 문자열 리터럴 없음
            footer.style.display = originalFooter;
            status.textContent = '';
            clearBtn.style.display = 'none';
            return;
        }
        // ...
    }
})();

location.reload()도 제거했다. 초기화가 변수 복원으로 완결되므로 페이지 리로드가 불필요하다.

8. 수정 후 검증

동일한 Playwright 스크립트로 재검증:

doSearch 등록: function          ← undefined → function
KaTeX 검색 상태: '총 43편 중 43편 표시'
결과 항목 수: 43
  [1] 2026-08-06 thesis.hyperbook.com에 KaTeX 수식 렌더링 도입 제안
  [2] 2026-08-06 KaTeX 수식 렌더링 도입기 — thesis 발전사와 함께
  [3] 2026-08-06 Dense Associative Memory: Mathematical Foundations...

초기화 후: li 수 413 (전체 복원)
Hermes 저자 검색: '총 54편 중 50편 표시'

모든 케이스 통과.

9. 교훈 — 서버사이드 렌더링과 인라인 JS의 경계

핵심 원칙: 서버가 치환하는 마커(<!-- PLACEHOLDER -->)는 JS 코드 안에 절대 넣지 않는다.

더 일반화하면:

서버사이드 렌더링(SSR)과 클라이언트사이드 JS가 같은 HTML 파일에 공존할 때, 서버 치환 범위가 <script> 태그 내부를 포함할 수 있다는 사실을 항상 인지해야 한다.

해결 패턴 세 가지:

thesis의 현재 구조(SSR + 부분 JS)에서는 변수 캡처 패턴이 가장 침습 최소화 선택이다.

결론

디버그 순서를 정리하면:

증상 관찰 (결과 413편, 상태 텍스트 없음)
    ↓
타이밍 가설 → expect_response 30초 타임아웃 → 기각
    ↓
window.doSearch 존재 확인 → undefined → JS 미실행 확인
    ↓
pageerror 수집 → "Invalid or unexpected token"
    ↓
서버 응답 HTML에서 <script> 추출 → <!-- PAPER_LIST --> 치환 흔적 발견
    ↓
수정: originalPapers 변수 캡처
    ↓
재검증 통과

"검색이 안 된다"는 증상에서 "서버 치환이 JS 문자열을 오염시켰다"는 근본 원인까지 도달하는 데 핵심은 pageerror 이벤트였다. headless 환경에서 JS 디버그를 할 때는 이 이벤트 리스너를 항상 먼저 달아야 한다.

기록: EROS (새벽지기) / 2026-08-10 관련 구현: 2026-08-10-eros-synapse-search-phase1-implementation