docs(ext-api): clarify pauseTracking/resetTracking no-op stub comment (review #12142.A5)

The previous comment described what the Vue intrinsics do but called them
no-op shims without explaining the contract gap. That read as if the
service was relying on dep-tracking suppression that the shim was silently
violating.

Rewrite the comment to make the Phase A scope explicit: this is a no-op
stub by design (the API surface is the contract being stabilized, not the
dep-tracking guarantee), and the real @vue/reactivity import lands together
with the reactive-World contract in #11939. Adds the TODO(#11939) marker so
the swap-in is grep-able alongside the rest of the Phase B handoff points.

No code change - comment-only. Per Architect review #5, we deliberately do
NOT add @vue/reactivity as a direct dep in Phase A.
This commit is contained in:
Connor Byrne
2026-05-11 17:37:51 -07:00
parent c1748c6fe3
commit 3476d06fc9

View File

@@ -18,9 +18,21 @@
import { EffectScope, onScopeDispose, proxyRefs, watch } from 'vue'
// pauseTracking/resetTracking prevent accidental reactive deps during setup hooks.
// They are Vue internals not publicly exported. Use no-op shims so this service
// compiles and runs without a direct @vue/reactivity dep.
// Phase A no-op stub for the Vue `pauseTracking`/`resetTracking` pair.
//
// In Vue's `setupStatefulComponent` (component.ts:829-927) these calls bracket
// `setup()` so that any property reads inside the user's setup body do NOT
// register as reactive dependencies of the surrounding effect. We mirror that
// pattern in the extension scope harness.
//
// We intentionally do NOT take a direct dependency on `@vue/reactivity` for
// Phase A — the contract being stabilized here is the API surface, not the
// dep-tracking guarantee. Real bracketing lands together with the reactive
// World contract in #11939 (Phase B), at which point these stubs are replaced
// by `import { pauseTracking, resetTracking } from '@vue/reactivity'`.
//
// TODO(#11939): swap in the real pauseTracking/resetTracking from
// @vue/reactivity once the reactive-World contract is live.
const pauseTracking = (): void => {}
const resetTracking = (): void => {}