SHELLS.md already documents this and the reasoning is sound: each branchs RouterScope<R> is installed inside its branch, which is a descendant of the chrome, and context lookups only walk upward — so context.router<BranchR>() cannot resolve from chromeBuilder.
What makes it easy to trip on anyway is that the neighbouring call does work: context.router<AppRoute>() resolves fine from the chrome, because the main router sits above the shell. So within a few lines of the same builder, one typed router lookup succeeds and another fails — and the failure is a runtime lookup miss, not a compile error.
Building a bottom bar in the chrome that needs both "push a full screen on the root stack" (works) and "read the active branchs stack" (does not) is a natural thing to reach for.
Suggestion
Either or both:
- make the assertion message name the fix directly — something like "
context.router<BranchR>() is not available in chromeBuilder; use context.shell() for branch state, or context.router<RootR>() for the main stack";
- pass the shell controller into
chromeBuilder as an explicit argument alongside activeBranch / switchBranch, so the correct accessor is in scope rather than something to remember.
The existing prose is accurate; this is about turning a documented gotcha into something the API or the error message prevents.
SHELLS.md already documents this and the reasoning is sound: each branchs
RouterScope<R>is installed inside its branch, which is a descendant of the chrome, and context lookups only walk upward — socontext.router<BranchR>()cannot resolve fromchromeBuilder.What makes it easy to trip on anyway is that the neighbouring call does work:
context.router<AppRoute>()resolves fine from the chrome, because the main router sits above the shell. So within a few lines of the same builder, one typed router lookup succeeds and another fails — and the failure is a runtime lookup miss, not a compile error.Building a bottom bar in the chrome that needs both "push a full screen on the root stack" (works) and "read the active branchs stack" (does not) is a natural thing to reach for.
Suggestion
Either or both:
context.router<BranchR>()is not available in chromeBuilder; usecontext.shell()for branch state, orcontext.router<RootR>()for the main stack";chromeBuilderas an explicit argument alongsideactiveBranch/switchBranch, so the correct accessor is in scope rather than something to remember.The existing prose is accurate; this is about turning a documented gotcha into something the API or the error message prevents.