From 49f7cde50edc44609e1b527ffae3b45b8086c629 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:04:18 +0900 Subject: [PATCH] =?UTF-8?q?fix(platform):=20lifecycle=20=EB=A6=AC=EC=8A=A4?= =?UTF-8?q?=EB=84=88=20=EC=A3=BC=EC=9D=B8=20=EA=B7=9C=EC=B9=99=EC=9D=84=20?= =?UTF-8?q?=EC=8B=A4=EC=A0=9C=EC=97=90=20=EB=A7=9E=EC=B6=94=EA=B3=A0=20?= =?UTF-8?q?=ED=85=8C=EC=8A=A4=ED=8A=B8=EB=A5=BC=20=EB=91=94=EB=8B=A4=20(05?= =?UTF-8?q?-03)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: browser-lifecycle.ts는 자신을 "창 lifecycle 리스너의 유일한 주인"이라 적고 어떤 capability도 visibilitychange·online·offline·focus· pagehide·pageshow 리스너를 직접 달지 않는다고 약속한다. optional-runtime-host.ts도 같은 말을 한다. 실제로는 - telemetry 수집기가 기본 구성에서 자기 pagehide 리스너를 단다 (telemetry-collector.ts onPageExit). - 네이티브 파일 선택기가 선택 창이 열린 동안 window focus 리스너를 단다(browser-file-picker.ts, 리뷰가 세지 않은 두 번째 예외). - lifecycle 런타임은 SW나 realtime이 있을 때만 만들어져 기본 구성에는 없다. 또 createBrowserLifecycleRuntime을 직접 부르는 테스트가 없어 bfcache 복원 때 generation 증가(K3), dispose 때 리스너 해제(K4) 변이가 살아남았다. 고른 방법: 리뷰 권고 (a). 주석을 "런타임이 있을 때 capability는 여기에 구독한다"로 좁히고, 런타임이 생기는 조건과 알려진 예외 둘을 적는다. tests/unit/browser-lifecycle.test.ts를 추가해 리스너 수, generation, visibility·connectivity, 구독자 격리, beforeunload 부착·해제·prompt, dispose 뒤 0개를 확인한다. 버린 대안: - (b) telemetry를 lifecycle 런타임에 연결하고 기본 구성에서도 런타임을 만든다: "기본 구성은 부작용 없는 생성" 원칙과 조립 순서를 함께 바꿔야 해 이번 범위를 넘는다. - (c) lint로 이벤트 이름을 막고 예외 파일을 적는다: 예외 목록 관리 비용에 비해 지금 이득이 작다. 다운스트림이 lifecycle 런타임을 켤 때 다시 본다. 위험·한계: 규칙은 여전히 주석뿐이고 검사가 없다(주석에 그렇게 적었다). src 동작은 바뀌지 않는다. 검증: - RED(주석): 주석의 "single owner"와 telemetry-collector.ts의 pagehide, browser-file-picker.ts의 focus 리스너를 대조해 불일치 확인. - RED(테스트 공백): 새 테스트는 현재 코드에서 5/5 통과하고, 변이 4개를 모두 잡는다. K3(generation += 1 제거) → "expected {...} to match object { generation: 2 }", K4(dispose의 pagehide·pageshow 해제 제거) → "expected 2 to be +0", beforeunload 상시 부착 → "expected 1 to be +0", dirty 검사 제거 → preventDefault "to not be called". - 회귀: browser-lifecycle, optional-runtime-host, runtime-adapters 3파일 30/30 통과. tsc app·test 통과, eslint 통과, check-adapter-inventory PASS. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md --- src/adapters/platform/browser-lifecycle.ts | 19 ++- src/bootstrap/optional-runtime-host.ts | 5 +- tests/unit/browser-lifecycle.test.ts | 166 +++++++++++++++++++++ 3 files changed, 184 insertions(+), 6 deletions(-) create mode 100644 tests/unit/browser-lifecycle.test.ts diff --git a/src/adapters/platform/browser-lifecycle.ts b/src/adapters/platform/browser-lifecycle.ts index 3e82e224..3340529f 100644 --- a/src/adapters/platform/browser-lifecycle.ts +++ b/src/adapters/platform/browser-lifecycle.ts @@ -1,9 +1,20 @@ /** - * §20.4. The single owner of window lifecycle listeners. + * §20.4. The shared owner of window lifecycle listeners. * - * No capability adds its own `visibilitychange`, `online`, `offline`, `focus`, - * `pagehide` or `pageshow` listener. They subscribe here instead, so the - * listener count stays constant and leak inspection (§23.14) is meaningful. + * When this runtime exists, a capability that needs `visibilitychange`, + * `online`, `offline`, `focus`, `pagehide` or `pageshow` subscribes here + * instead of adding its own listener, so the listeners this runtime holds stay + * constant and leak inspection (§23.14) can count them. + * + * 05-03. The rule is narrower than "the only such listener in the page": + * - The runtime exists only when a Service Worker or realtime capability is + * composed (`startAfterMount` in `optional-runtime-host.ts`). The default + * composition has none, and `browserLifecycle()` returns null there. + * - Two adapters hold their own window listener: the telemetry collector's + * `pagehide` page-exit flush (attached while a queue waits for a flush, and + * composed by default) and the native file picker's `focus` listener (held + * while a picker is open, to notice dismissal). + * No check enforces this. A new exception belongs in the list above. * * §20.6: nothing in this module is a correctness boundary. `beforeunload` is a * user prompt, never a place to complete a command, write a checkpoint or diff --git a/src/bootstrap/optional-runtime-host.ts b/src/bootstrap/optional-runtime-host.ts index 916ac188..21714859 100644 --- a/src/bootstrap/optional-runtime-host.ts +++ b/src/bootstrap/optional-runtime-host.ts @@ -85,8 +85,9 @@ export function createOptionalRuntimeHost( if (stopPromise) return stopPromise; if (startPromise) return startPromise; startPromise = (async () => { - // 1. The lifecycle observer is the single window listener owner. It is - // only created when something downstream can actually consume it. + // 1. The lifecycle observer owns the shared window lifecycle listeners + // (exceptions are listed in browser-lifecycle.ts). It is only created + // when something downstream can actually consume it. if (serviceWorker || capabilities.realtime.length > 0) { lifecycle = createBrowserLifecycleRuntime(input.browserLifecycleHost); } diff --git a/tests/unit/browser-lifecycle.test.ts b/tests/unit/browser-lifecycle.test.ts new file mode 100644 index 00000000..7854ace5 --- /dev/null +++ b/tests/unit/browser-lifecycle.test.ts @@ -0,0 +1,166 @@ +import { describe, expect, it, vi } from "vitest"; + +import { + createBrowserLifecycleRuntime, + type BrowserLifecycleEvent, +} from "../../src/adapters/platform/index.ts"; + +type Listener = (event: unknown) => void; + +// 05-03. Records listeners per target so the test can count what the runtime +// attached and fire events without a DOM. +function createHost(initial: { hidden?: boolean; online?: boolean } = {}) { + const listeners = new Map>(); + const target = (scope: string) => ({ + addEventListener: (type: string, listener: Listener) => { + const key = `${scope}:${type}`; + const set = listeners.get(key) ?? new Set(); + set.add(listener); + listeners.set(key, set); + }, + removeEventListener: (type: string, listener: Listener) => { + listeners.get(`${scope}:${type}`)?.delete(listener); + }, + }); + const document = { + ...target("document"), + visibilityState: initial.hidden ? "hidden" : "visible", + }; + const host = { + ...target("window"), + document, + navigator: { onLine: initial.online ?? true }, + }; + const count = (key?: string) => + [...listeners.entries()] + .filter(([name]) => key === undefined || name === key) + .reduce((total, [, set]) => total + set.size, 0); + const fire = (key: string, event: unknown = {}) => { + for (const listener of [...(listeners.get(key) ?? [])]) listener(event); + }; + return { host, document, count, fire }; +} + +function create(initial?: Parameters[0]) { + const fake = createHost(initial); + const runtime = createBrowserLifecycleRuntime( + fake.host as unknown as Parameters[0], + ); + return { ...fake, runtime }; +} + +describe("browser lifecycle runtime", () => { + it("attaches one listener per lifecycle event and no beforeunload", () => { + const { count } = create(); + for (const key of [ + "document:visibilitychange", + "window:online", + "window:offline", + "window:focus", + "window:pagehide", + "window:pageshow", + ]) { + expect(count(key)).toBe(1); + } + expect(count("window:beforeunload")).toBe(0); + expect(count()).toBe(6); + }); + + it("starts a new generation only on a bfcache restore", () => { + const { runtime, fire } = create(); + const events: BrowserLifecycleEvent[] = []; + runtime.subscribe((event) => events.push(event)); + + expect(runtime.getSnapshot()).toMatchObject({ + generation: 1, + pageState: "ACTIVE", + }); + fire("window:pageshow", { persisted: false }); + expect(runtime.getSnapshot()).toMatchObject({ + generation: 1, + pageState: "ACTIVE", + }); + + fire("window:pagehide", { persisted: true }); + expect(runtime.getSnapshot().pageState).toBe("PAGEHIDE"); + fire("window:pageshow", { persisted: true }); + expect(runtime.getSnapshot()).toMatchObject({ + generation: 2, + pageState: "BFCACHE_RESTORED", + }); + expect(events.map((event) => event.kind)).toEqual([ + "PAGESHOW", + "PAGEHIDE", + "PAGESHOW", + ]); + expect(events.at(-1)).toMatchObject({ + persisted: true, + snapshot: { generation: 2 }, + }); + }); + + it("tracks visibility and connectivity and isolates a throwing subscriber", () => { + const { runtime, document, fire } = create({ hidden: true, online: false }); + expect(runtime.getSnapshot()).toMatchObject({ + visibility: "HIDDEN", + connectivityHint: "OFFLINE", + }); + const received = vi.fn(); + runtime.subscribe(() => { + throw new Error("subscriber defect"); + }); + runtime.subscribe(received); + + document.visibilityState = "visible"; + fire("document:visibilitychange"); + fire("window:online"); + expect(runtime.getSnapshot()).toMatchObject({ + visibility: "VISIBLE", + connectivityHint: "ONLINE", + }); + expect(received).toHaveBeenCalledTimes(2); + }); + + it("holds beforeunload only while a dirty source is registered", () => { + const { runtime, count, fire } = create(); + let dirty = false; + const unregister = runtime.registerDirtySource(() => dirty); + const unregisterBroken = runtime.registerDirtySource(() => { + throw new Error("reporter defect"); + }); + expect(count("window:beforeunload")).toBe(1); + + const clean = { preventDefault: vi.fn() }; + fire("window:beforeunload", clean); + expect(clean.preventDefault).not.toHaveBeenCalled(); + + dirty = true; + const prompted = { preventDefault: vi.fn() }; + fire("window:beforeunload", prompted); + expect(prompted.preventDefault).toHaveBeenCalledOnce(); + + unregister(); + expect(count("window:beforeunload")).toBe(1); + unregisterBroken(); + expect(count("window:beforeunload")).toBe(0); + }); + + it("removes every listener on dispose and ignores later subscriptions", () => { + const { runtime, count, fire } = create(); + runtime.registerDirtySource(() => true); + const received = vi.fn(); + runtime.subscribe(received); + expect(count()).toBe(7); + + runtime.dispose(); + expect(count()).toBe(0); + + const late = vi.fn(); + runtime.subscribe(late); + runtime.registerDirtySource(() => true); + fire("window:focus"); + expect(count()).toBe(0); + expect(received).not.toHaveBeenCalled(); + expect(late).not.toHaveBeenCalled(); + }); +});