Skip to content

feat(next-plugin): keep one coordinator and engine session per app - #966

Open
owjs3901 wants to merge 17 commits into
mainfrom
feat/next-coordinator-registry
Open

owjs3901 wants to merge 17 commits into
mainfrom
feat/next-coordinator-registry

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Stacked PR: this branch was branched from feat/compiler-sessions (#965) (#965 ← #964 ← #963). It must be merged after #963 → #964 → #965 are merged in that order; until then the diff also shows the earlier PRs' commits.

NXT-07 step 4: turns the Next plugin's Turbopack coordinator into a per-app registry.

Previous problem

  • The coordinator was a module-global singleton.
  • When a second app in the same process called startCoordinator, the first app's listener was closed.
  • The two apps shared one engine state (numbering, sheets, theme, config).

Changes

  • A registry keyed by the normalized distDir (absolute path, lowercased on Windows).
  • openCoordinatorCompiler(distDir, compiler): on the first call, opens an engine session for that app alone. The session is openCompilerSession from feat(plugin-utils): add openCompilerSession for per-app engine state #965 with a module resolver attached.
    • plugin.ts runs the whole setup (registerShorthands, setPrefix, import*, registerTheme, importCanonicalMap, seedFileMap, prewarm extraction, getCss/export*) with this session compiler, and passes the same compiler to the coordinator.
    • If the same app is re-evaluated with a different engine (engine option changed), the previous session is dropped and a session is opened on the new engine.
  • startCoordinator({ distDir, ... })
    • Replaces only the same app's previous coordinator and adds one reference. Other apps' coordinators are untouched.
    • Extraction tracking state (active/pending counters, extractedFiles, bucket maps, wait timing) is kept per coordinator.
  • close() is safe to call more than once. Each call drops one reference, and the last close drops the app's session and removes its registry entry.
  • Write serialization (safeWrite) is keyed by path, so it stays global.
  • Updated the README's "Extraction engine" section and added a next-plugin Patch changepack.

Expected conflicts

Test plan

  • bun test packages/next-plugin/src/__tests__/*.test.ts: 18 files, 213 pass
  • 100% coverage for coordinator.ts, plugin.ts (ran coordinator.test.ts and plugin.test.ts with --coverage)
  • New tests
    • Two apps' coordinators respond at the same time, and closing one leaves the other responding.
    • One session per app; differently written distDir values normalize to the same key. Prefixes do not mix between the two apps.
    • The session is kept until the last close, duplicate closes are ignored, and the session is dropped after the last close.
    • A new session is opened when the engine changes.
  • The existing "replaces an existing coordinator without retaining its server" test still passes as is
  • bunx tsc --noEmit (next-plugin), bunx prettier --check (code files). The README already has prettier warnings on main too.

스택 PR: 이 브랜치는 feat/compiler-sessions (#965) 위에서 분기했습니다(#965 ← #964 ← #963). #963 → #964 → #965 순서로 머지된 뒤에 머지해야 하며, 그 전까지 diff에는 앞선 PR의 커밋이 함께 보입니다.

요약

NXT-07 4단계: Next 플러그인의 Turbopack coordinator를 앱별 registry로 바꿉니다.

기존 문제

  • coordinator는 모듈 전역 싱글턴이었습니다.
  • 같은 프로세스에서 두 번째 앱이 startCoordinator를 부르면 첫 번째 앱의 listener가 닫혔습니다.
  • 두 앱이 엔진 상태(번호 매김, 시트, 테마, 설정) 하나를 함께 썼습니다.

변경 내용

  • 정규화한 distDir(절대 경로, Windows에서는 소문자)를 키로 registry를 둡니다.
  • openCoordinatorCompiler(distDir, compiler): 처음 호출될 때 그 앱만의 엔진 세션을 엽니다. 세션은 #965의 openCompilerSession 위에 모듈 resolver를 함께 붙입니다.
    • plugin.ts는 setup 전부(registerShorthands, setPrefix, import*, registerTheme, importCanonicalMap, seedFileMap, prewarm 추출, getCss/export*)를 이 세션 compiler로 실행하고, 같은 compiler를 coordinator에 넘깁니다.
    • 같은 앱이 다른 엔진으로 다시 평가되면(engine 옵션 변경) 이전 세션을 버리고 새 엔진에서 세션을 엽니다.
  • startCoordinator({ distDir, ... })
    • 같은 앱의 이전 coordinator만 교체하고 참조를 하나 늘립니다. 다른 앱의 coordinator는 건드리지 않습니다.
    • 추출 추적 상태(active/pending 카운터, extractedFiles, bucket 맵, 대기 타이밍)를 coordinator마다 따로 둡니다.
  • close()는 여러 번 불러도 안전합니다. 호출할 때마다 참조를 하나 줄이고, 마지막 close에서 앱의 세션을 버리고 registry 항목을 지웁니다.
  • 쓰기 직렬화(safeWrite)는 경로를 키로 하므로 계속 전역에 둡니다.
  • README의 "Extraction engine" 절을 갱신하고, next-plugin Patch changepack을 추가했습니다.

충돌 예상

테스트 계획

  • bun test packages/next-plugin/src/__tests__/*.test.ts: 18개 파일, 213개 통과
  • coordinator.ts, plugin.ts 커버리지 100% (coordinator.test.ts와 plugin.test.ts를 --coverage로 실행)
  • 새 테스트
    • 두 앱의 coordinator가 동시에 응답하고, 하나를 닫아도 다른 하나는 계속 응답합니다.
    • 앱마다 세션이 하나이고, distDir을 다르게 써도 같은 키로 정규화됩니다. prefix가 두 앱 사이에 섞이지 않습니다.
    • 마지막 close 전까지 세션이 유지되고, 중복 close는 무시되며, 마지막 close 뒤에는 세션이 버려집니다.
    • 엔진이 바뀌면 세션을 새로 엽니다.
  • 기존 "replaces an existing coordinator without retaining its server" 테스트 그대로 통과
  • bunx tsc --noEmit (next-plugin), bunx prettier --check(코드 파일). README는 main에서도 이미 prettier 경고가 있는 파일입니다.

Refs #686

🤖 Generated with Claude Code

owjs3901 and others added 6 commits November 15, 2026 19:43
…bals

Two apps in one process shared the single process-wide engine state.
Gather the persistent state into values that can be exchanged with the
live globals:

- css::engine_state::CssState holds the prefix, debug flag, atom hoist
  threshold and plan, slot reservation, class map, file map, canonical
  map, file routes, custom shorthands, theme tokens and Tailwind
  definitions. css::test_state::TestStateGuard is now built on it.
- extractor::ExtractorCaches holds the vanilla-extract imported runs and
  stripped TypeScript of the calling thread.
- devup_ui_binding_core::session keeps session 0 live from the start and
  parks every other session's EngineState (CSS state + stylesheet).
  select_session swaps a parked state with the live globals,
  with_session runs a closure under the session lock and swaps back,
  also on unwind. Extractor caches are parked per thread and aligned on
  every switch, since they hold Rc values and session file numbers.
- PerSession<T> keys host values by the live session; the WASM and
  native module resolvers use it.

Existing call sites read the globals unchanged; until a host creates a
session the engine behaves as before.

Refs #686

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add the engine session calls to the WASM and native engines:

- createSession() returns the id of a new session with a clean state
- selectSession(id) makes it live; every later call works on its state
- dropSession(id) drops it with its module resolver, returning whether
  it existed; dropping the live session makes session 0 live

The shared argument boundary checks the id as an unsigned 32-bit
integer before engine entry. The ABI grows from 29 to 32 names: the
WASM glue check, the native adapter and typings, the e2e ABI list, the
validation positions (47 in 20 functions, 283 invalid-input cases) and
a parity corpus scenario follow it.

Refs #686

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hape

Refs #686

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs #686

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
openCompilerSession(compiler) creates an engine session on a shared
compiler and returns { id, compiler, close }. Every function read from
the scoped compiler selects the session before it runs; the calls are
synchronous and JavaScript is single-threaded, so no other session's
call can run between the selection and the call. close() drops the
session, after which calls through the scoped compiler throw.

Refs #686

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Turbopack coordinator was a module-level singleton: starting a
second app in the same process closed the first app's listener, and
both apps shared one engine state.

Coordinators are now kept in a registry keyed by the resolved distDir:

- openCoordinatorCompiler(distDir, compiler) opens the app's own engine
  session (with the module resolver) on first use; the plugin runs its
  setup through it and hands it to the coordinator
- startCoordinator replaces only the previous coordinator of the same
  app and takes a reference; each coordinator keeps its extraction
  tracking in a state of its own
- close() is idempotent and releases the reference; the last close
  drops the app's session and its registry entry
- moving an app to another engine opens a new session there

Refs #686

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
bindings/devup-ui-binding/index.mjs 100.00% <100.00%> (ø)
bindings/devup-ui-binding/src/host.rs 100.00% <100.00%> (ø)
bindings/devup-ui-binding/src/lib.rs 100.00% <ø> (ø)
bindings/devup-ui-wasm/src/lib.rs 100.00% <100.00%> (ø)
bindings/devup-ui-wasm/src/reservation.rs 100.00% <100.00%> (ø)
bindings/devup-ui-wasm/src/state.rs 100.00% <100.00%> (ø)
bindings/devup-ui-wasm/src/state/tests.rs 100.00% <ø> (ø)
libs/binding/src/lib.rs 100.00% <100.00%> (ø)
libs/binding/src/session.rs 100.00% <100.00%> (ø)
libs/css/src/engine_state.rs 100.00% <100.00%> (ø)
... and 10 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

owjs3901 and others added 11 commits November 16, 2026 08:04
Keep main's check_resolved_path/resolved_module re-exports beside the
session re-exports in libs/binding. removeFile (#951) only touches the
file map, canonical map, class map and global sheet, which CssState and
EngineState already swap per session; a new session test pins that
forgetting a file in one session leaves another session's styles alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in main through #963, including removeFile (#951). The ABI now
holds 33 names: main's 30 plus createSession, selectSession and
dropSession. Updated script.js, the native typings and README, the
e2e ABI list and consumer, and compiler-types (32 without Output).

Validation covers 48 positions in 21 functions (288 cases), and the
summary reports 21 functions. The corpus keeps both new scenarios and
adds remove-file-stays-in-its-session, which checks that removeFile
only forgets the file in the live session (28 scenarios).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No conflicts. openCompilerSession wraps every compiler function in a
Proxy that selects the session first, so removeFile from main (#951)
runs on the scoped session like every other call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main's coordinator (#951) tracked deleted sources in a module-level
extractedSources map, while this branch moved all extraction tracking
into each app's CoordinatorState. extractedSources now lives in that
state too, so each app forgets only its own deleted files. removeFile
is read from the session-scoped compiler the plugin hands over, so it
runs on the app's own engine session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
extractor/lib.rs keeps both this branch's ExtractorCaches export and
main's vanilla_extract_theme_import_tests module. Main added no binding
exports since the last merge, so the counts stay: 33 ABI names, 21
validated functions with 48 positions and 288 cases, and 28 parity
scenarios. #967's serialization cache needs no session state: a session
switch swaps the sheet through a tracked mutable borrow, which forgets
the cached serializations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
extractor/lib.rs keeps both the ExtractorCaches export and main's
vanilla_extract_theme_import_tests module, as #963 and #964 resolved it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Takes #964's merge with main (33cf39c) into the stack. Its tree adds
nothing beyond the main merge before this one, so no file changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
coordinator.ts: main's Turbopack theme reload (#944) kept its watch in
module globals; it now lives in each app's CoordinatorState, created
from options.theme, and refreshTheme(state) runs before each /css and
/extract of that app. The reload registers the theme through the app's
session compiler, so one app's devup.json never reaches another's
engine. close() writes the pending files synchronously (#917) before
releasing the app, and resetCoordinator keeps clearing the registry
instead of the removed globals. extractor/lib.rs keeps both the
ExtractorCaches export and vanilla_extract_theme_import_tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Takes #965's merges with main and #964 into the stack. Its tree adds
nothing beyond the main merge before this one, so no file changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the conflict with #946 in packages/next-plugin/src/coordinator.ts.
The transform cache becomes per app: it lives in each app's
CoordinatorState next to extractedSources, a theme refresh clears only
that app's cache, and a removed source drops only the owning app's entry.
themeStamp is replaced by #946's fileStamp. Adds a test that two apps
never share cached extractions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolve the conflict with #938 in packages/next-plugin/src/coordinator.ts.
#938 adds no new module state: its error-returning waitForBase and
waitForBucket, missingFiles and incompleteCssError now read the app's own
CoordinatorState, so one app's extractions never complete another app's
CSS. A test covers two apps expecting the same base files. #939's
shared-slot reservation runs on the app's own engine session; its test
now expects that session instead of the shared engine.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant