데이터가 없으면 컴포넌트가 promise 를 throw 한다 — 예외와 같은 메커니즘이다. 가장 가까운 Suspense 가 그것을 잡아 fallback 을 보이고, promise 가 resolve 되면 다시 렌더한다. throw fetch() 는 렌더할 때마다 새 promise 를 만들므로, 공식 경로는 캐시된 같은 promise 를 use 로 읽는 것이다.

-- Suspense: 렌더가 promise 를 "던지면" 잡아서 기다린다 — 예외와 같은 메커니즘
render :: Component -> Either (Promise a) Html
render c = case cached c of
  Nothing -> Left (fetchData c)      -- throw promise
  Just d  -> Right (view d)

suspense :: Html -> Component -> IO Html
suspense fallback c = case render c of
  Left p  -> show fallback >> await p >> suspense fallback c   -- resolve 되면 다시 렌더
  Right h -> pure h

-- throw fetch() 는 렌더마다 새 promise — 공식 경로: 캐시된 같은 promise 를 use 로
#307

각각 들고 있으면: loading 과 error 가 따로 켜지고 꺼져 네 칸이 생긴다 — 둘 다 꺼짐은 성공, error 만 켜짐은 에러, loading 만 켜짐은 로딩, 둘 다 켜짐은 있을 수 없는 “로딩 + 에러”인데도 적을 수 있다. 그 칸이 한 프레임이라도 그려지면 화면이 튄다. 트리로 옮기면: 로딩(Suspense) → resolve → 성공(본문), 로딩 → reject → 에러(ErrorBoundary), 성공 → 입력 변경으로 promise 를 던지면 → 로딩. 상태는 셋 중 하나라 넷째 칸을 적을 수가 없다.

-- 비동기 데이터를 그리는데 로딩·에러가 늘면서 화면이 튈 때
-- 각각 들고 있으면 2 × 2 = 4 칸: 넷째(로딩이면서 에러)는 있을 수 없는데 적을 수 있다
data Flags a = Flags { loading :: Bool, failed :: Maybe Error, result :: Maybe a }

-- 트리로 옮기면 셋 중 하나: 넷째 칸을 적을 수가 없다
data View a = Loading | Failed Error | Done a

-- Suspense 는 비동기를 동기처럼 보이게 한다: 없으면 promise 를 던지고, 오면 다시 그린다
read :: Resource a -> a

render :: a -> Html                            -- 결과 하나만 받는다. loading·error 를 넘기지 않는다
view :: Resource a -> Html
view r = errorBoundary onError                 -- reject → 가장 가까운 ErrorBoundary
       $ suspense spinner                      -- pending → 가장 가까운 Suspense
       $ render (read r)

-- 확인: 있을 수 없는 조합을 적을 수 있는가. 적을 수 없으면 된 것이다
-- 함정: 스피너가 너무 빨리 떴다 사라지는 건 이 축이 아니다 → 573. stale-while-revalidate → 570
-- 모양은 algebraic effect 의 handler 에서 따왔다 — 다만 되돌아가 이어 실행하지 않고 다시 그린다
#575

Freeze 는 바깥부터 Fragment, Suspense, 그 안의 Suspend 와 children 으로 되어 있다. frozen 이 되면 Suspend 가 끝나지 않는 promise 로 Suspense 를 중단시킨다. 그러면 React 는 안쪽을 계속 렌더하지만 DOM 에 커밋하지 않아, 팝오버가 사라지는 동안 내용이 닫기 직전 모습 그대로 멈춘다. 한 번의 커밋 안에서 React 는 자식을 먼저 처리하므로, Suspense 가 바로 아래 요소에 display none 을 붙이고 안쪽의 layout effect 를 정리하고 ref 를 뗀 다음에 Freeze 의 insertion effect 가 돌아 display 를 되돌린다. 숨긴 모습은 한 번도 그려지지 않는다. 되돌릴 요소는 Fragment ref 에 가짜 관찰자를 넣어 미리 모아 둔다. 풀리면 쌓여 있던 최신 렌더가 한 번에 커밋된다.

-- 닫기와 내용 변경(안내 문구, 고른 항목 맨 위로)이 한 배치로 커밋되면 사라지는 중에 내용이 바뀐다
-- → 퇴장 중엔 커밋을 멈춘다. Suspense 를 빌리고, 딸려 오는 숨김만 걷어낸다
freeze :: Bool -> Tree -> Dom -> Dom
freeze False t _   = commit t                    -- 평소: 렌더한 대로 커밋
freeze True  _ old = unhide (suspend old)        -- 얼림: 렌더는 계속, 커밋은 안 함 → 닫기 직전 모습

-- Suspense 가 중단되면 하는 일 셋 — 앞의 둘은 그대로 쓰고, 셋째만 되돌린다
suspend :: Dom -> Dom
suspend = keepState . skipCommit . hide
  -- {frozen && <Suspend />}: 모듈에 하나 둔 끝나지 않는 promise 를 use → 계속 중단
  -- hide: 바로 아래 요소에 display: none !important, 텍스트는 nodeValue = '', layout effect 정리·ref 떼기

unhide :: Dom -> Dom
unhide = mapElems (\el -> el { display = "" })
  -- 언제: useInsertionEffect. 커밋은 자식 먼저라 Suspense 가 숨긴 직후 같은 커밋 안에서 돈다 → 숨긴 모습이 안 그려진다
  -- 누구를: <Fragment ref> 의 observeUsing 에 가짜 관찰자를 넣어 바로 아래 요소를 Set 으로 모은다
  --         (붙으면 observe · 빠지면 unobserve 가 다시 불린다)
  -- deps 는 [frozen]: React 가 다시 숨기는 건 보임↔숨김이 바뀔 때뿐이다

-- 풀릴 때: 쌓인 최신 렌더가 한 번에 커밋되고, display 는 style prop 의 값(없으면 '')으로 돌아온다
-- 쓰는 쪽: <Popover>{({ isExiting }) => <Freeze frozen={isExiting}>…</Freeze>}</Popover> (React Aria)
--          React 상태로 그리는 hover·press·focus 도 같이 언다. CSS :hover 는 안 언다
-- 버린 길: 닫기 전 상태를 저장 → 다시 그리게 하는 상태를 전부 챙겨야 한다
--          onOpenChangeComplete 로 업데이트를 미룸 → 퇴장이 중간에 끊기면 복잡하다
-- 다만: observeUsing 은 react-dom 19.3 부터다(19.2.0 엔 없다). ref cleanup·use 도 19
--       텍스트 자식은 되돌리지 않아 얼어 있는 동안 비어 보인다
--       퇴장 중엔 ref 가 떨어져 있어 ref 로 재거나 포커스를 다루는 코드는 못 돈다
--       원래 인라인 display 를 지운다 · React 내부 동작에 기댄 트릭이다
#607

React 스트리밍 SSR 은 HTTP 응답 하나를 닫지 않고 조금씩 써 보낸다. 먼저 데이터를 기다리지 않는 부분인 셸을 보낸다. 아직 준비 안 된 Suspense 경계 자리에는 주석 표시와 빈 template, 그리고 fallback 이 들어간다. 경계의 데이터가 오면 같은 응답 뒤쪽에 숨긴 div 로 진짜 내용을 붙이고, 짧은 스크립트가 fallback 을 그 내용으로 바꿔 끼운다. 경계는 준비된 순서대로 오므로 느린 경계 하나가 뒤의 경계를 막지 않는다. 바꿔 끼우기는 바로 하지 않고 모아서 다음 프레임에 하고, 한 번 바꾼 뒤에는 300ms 가 지나야 다시 바꾼다. 마지막 경계가 와야 응답이 닫히고 브라우저의 문서 파싱이 끝난다. 사람에게는 셸이 되자마자 흘려보내고, 크롤러처럼 완성된 문서가 필요하면 모든 경계가 풀릴 때까지 기다렸다가 한 번에 보낸다.

-- 응답 하나 = 셸 하나 + 기다리던 경계마다 조각 하나. 마지막 경계까지 응답은 열려 있다
stream :: Tree -> [Chunk]
stream t = shell t : [ segment b <> swap b | b <- readyOrder (pending t) ]   -- 준비된 순서, 문서 순서가 아니다
  -- 마지막 조각 뒤에야 응답이 닫히고 브라우저 파싱이 끝난다 → defer 스크립트는 가장 느린 경계를 기다린다

-- 셸에서 경계 자리
boundary :: Boundary -> Chunk
boundary b | ready b   = "<!--$-->"  <> html b                                        <> "<!--/$-->"
           | failed b  = "<!--$!-->" <> fallback b                                    <> "<!--/$-->"  -- 클라이언트가 다시 그린다
           | otherwise = "<!--$?--><template id=\"B:" <> n b <> "\"></template>" <> fallback b <> "<!--/$-->"
  -- ready 라도 뒤로 뺀다(셸엔 $? 자리, 내용은 segment+swap): 500B 넘는 경계가 이미 쓴 것과 합쳐 12,800B(progressiveChunkSize) 를 넘을 때
  --   · 스타일시트를 기다려야 할 때 · defer 일 때. 셸이 너무 커져 첫 화면이 늦어지지 않게

segment b = "<div hidden id=\"S:" <> n b <> "\">" <> html b <> "</div>"   -- 화면 밖에 먼저 붙는다
swap    b = "<script>$RC(\"B:" <> n b <> "\",\"S:" <> n b <> "\")</script>" -- $RC 정의는 첫 swap 앞에 한 번 인라인으로

-- $RC: 바로 바꾸지 않는다. 표시를 $~ 로 바꿔 대기열에 넣고 한꺼번에 바꾼다($RV)
reveal :: Ms -> Maybe Ms -> Delay
reveal _   Nothing               = nextFrame                 -- 아직 한 번도 안 바꿨다
reveal now (Just _) | 2000 < now && now < 2300 = 2300 - now  -- 이 구간이면 2.3초에 맞춘다
reveal now (Just last)           = last + 300 - now          -- 지난 바꾸기 300ms 뒤
  -- $RV: 표시 사이 fallback 노드를 지우고 S:n 의 자식을 옮겨 넣고 표시를 "$" 로. _reactRetry 가 있으면 다음 프레임에 그 경계를 하이드레이트
  -- B:n 이 없으면(그 사이 지워졌다) S:n 도 지운다

-- 언제 흘려보내나 (renderToPipeableStream)
send :: Reader -> Hook
send Person  = onShellReady   -- 셸이 되면 pipe. 경계는 오는 대로
send Crawler = onAllReady     -- 다 풀린 뒤 pipe. 작은 경계는 셸 안에 "<!--$-->" 로, 큰 경계는 여전히 뒤로 빠져 $RC 로 끼운다
  -- 셸조차 실패하면 onShellError
  -- pipe: 버퍼가 차면 멈췄다 'drain' 에 이어 쓴다. 'close'·'error' 면 렌더를 취소. pipe 는 한 번만
#612