auto-imports: the browser manifest is compile-time only and disagrees with the stx runtime

[chrisbbreuer]

storage/framework/browser-auto-imports.json is treated across the docs as the authority on what an stx template gets for free. AGENTS.md says so in as many words, and stacks-composables now defers to it. But the manifest is a compile-time artifact, and the names it declares are not the names the stx runtime provides.

What I can show

1. Nothing in the framework reads the manifest at build time. It is written by generateAutoImportFiles in storage/framework/core/server/src/imports.ts:1157 and read by exactly three things: buddy docs:agent-counts, agents-md-auto-imports.test.ts, and composables-skill-auto-imports.test.ts. All three are checks. No bundler step, no plugin, no injection.

$ grep -rn "browser-auto-imports.json" --include="*.ts" storage/framework/core/ | grep -v dist
storage/framework/core/server/src/imports.ts:1157      # writes it
storage/framework/core/buddy/src/commands/docs/agent-counts.ts:149,177   # checks it

2. What it feeds is a declaration file. imports.ts derives the JSON from the pruned types/browser-auto-imports.d.ts by scraping const NAME: lines. Ambient const declarations tell tsc the name resolves. They do not put anything on the page.

3. The stx runtime ships a different set. From the installed package:

$ grep -rhoE "function (use[A-Z][A-Za-z0-9]*)" node_modules/@stacksjs/stx/dist/*.js | sort -u | wc -l
54

Cross-referencing those 54 against the manifest's 27 use*, the overlap is roughly six (useDark, useFetch, useOnline, usePreferredDark, useScrollLock, useToggle). The rest of the manifest's list, including useAbs, useAuth, useDateFormat, useForm, useNow, useStorage, useSum, useTimeoutFn and the store composables, do not appear as runtime functions in that dist.

The runtime has plenty the manifest lacks, too (useClipboard, useCookie, useHead, useRoute, useQuery, useVirtualList, ...), which is the same gap in the other direction: names that work and are typed as errors.

Why it matters

If a manifest name is not a runtime global, referencing it in a template is a ReferenceError thrown during setup, before any binding applies. That does not degrade the one call; it takes the whole page down. And because the name is in the .d.ts, buddy typecheck passes, so nothing catches it before the browser does.

This is the failure mode AGENTS.md already documents for a different reason - it carries a correction about having listed ref, computed, useColorMode, useLocalStorage and friends as auto-imported when they are in neither manifest. The concern here is one layer deeper: names that ARE in the manifest and still are not there at runtime.

What I have not established

Whether the served /_stx/runtime.js matches the package dist I grepped, and whether some path outside storage/framework/core/ supplies the missing names. Both need a running dev server, which is why this is an issue rather than a patch - I did not want to "fix" the documented list on an inference and make it wrong in a new way.

The cheap confirmation, from a running app:

grep -o 'function use[A-Z][A-Za-z0-9]*' <(curl -s localhost:3000/_stx/runtime.js) | sort -u

Compare that against jq -r '.globals | keys[]' storage/framework/browser-auto-imports.json. Whichever way it comes out, the answer belongs in a test: the manifest and the runtime should not be free to disagree, in either direction.

If it is confirmed

The docs are currently accurate about the manifest and would be wrong about reality. AGENTS.md's auto-import section and the free list in stacks-composables both derive from the manifest (the latter is delimited by <!-- auto-imported:begin --> markers and checked by a test, so there is one place to change). Both would need to derive from whatever turns out to be authoritative instead.

Found while giving the composables skill an accurate list of what a template gets for free (0c46e3c218); it corrected "All are auto-imported" to the manifest's 27, which is right about the manifest and possibly not right about the browser.

[chrisbbreuer]

Settled, without needing a dev server. getCachedSignalsRuntime is exported from @stacksjs/stx, so the runtime that gets served can be generated directly:

const src = await (await import('@stacksjs/stx')).getCachedSignalsRuntime(false)
// 174,278 bytes, 38 distinct `use*` names

Cross-referenced against the manifest's 27 use*, the two lists overlap by five.

	count
in both	5	useDark, useFetch, usePreferredDark, useScrollLock, useToggle
typed, absent at runtime	22	useAbs, useAuth, useAverage, useCeil, useClamp, useDateFormat, useFloor, useForm, useGitStore, useMax, useMin, useNow, useOnline, usePaymentStore, usePrecision, useQueueStore, useRound, useStorage, useSum, useTimeoutFn, useTrunc, useUserStore
runs, not typed	33	useAsync, useClickOutside, useColorMode, useCookie, useCounter, useDebounce, useEventListener, useHead, useLocalStorage, useMediaQuery, useQuery, useRoute, useSearchParams, useSessionStorage, useStore, useTimeout, useWebSocket, ...

The runtime attaches them as real globals, so this is not an artefact of how I counted:

useToggle        window.X =  function X(
useCounter       window.X =  function X(
useLocalStorage  window.X =  function X(
useStorage       (absent)
useAbs           (absent)

And there is no build-time injection to close the gap. Neither bun-plugin-stx nor @stacksjs/stx mentions browser-auto-imports or @stacksjs/composables anywhere in its dist, so nothing rewrites useAbs into an import.

What this means

Both failure directions are live, and each is worse than "a wrong number in a doc":

• 22 names typecheck and throw. buddy typecheck accepts useStorage(...) in a template because the .d.ts declares it; the browser raises a ReferenceError during setup, before any binding applies, which takes the whole page down.
• 33 names work and are typed as errors. useLocalStorage, useColorMode, useCounter, useMediaQuery, useRoute are all real globals that tsc will reject.

This also inverts part of the AGENTS.md correction

AGENTS.md warns that useColorMode, useLocalStorage, useCounter and usePreferredReducedMotion are not auto-imported. Every one of those four is in the served runtime. The sentence is literally true - they are in neither manifest - but the manifest is not what decides whether a name resolves in a template, which is the whole of this issue. An agent following that correction imports four names it did not need to, or avoids them.

My own page is wrong too

fabc00345c added "The 27 you can write bare in a template" to stacks-composables, derived from the manifest because AGENTS.md names it the authority. 22 of those 27 throw. Fixing that now; the list should come from the runtime, and the test guarding it should generate the runtime rather than read the manifest.

Whatever the intended design, the manifest and the runtime should not be free to disagree in either direction, and a generated check can say so.

[chrisbbreuer]

The use* numbers understate this. Across the whole manifest: 83 declared names, 60 runtime window.* globals, 3 in both.

And I found why. storage/framework/core/server/src/imports.ts says it, in a comment added when the file was last pruned:

unplugin-auto-import has not written this file in a long time, and a header naming a tool nobody runs is why nobody thought to check it.

The manifest describes an injection performed by a tool that is no longer run. The names were never re-checked against what stx actually provides, which is why they have drifted apart completely rather than partially.

Every claim in the AGENTS.md section is affected

The utilities and Stripe helpers it lists as free are not in the runtime at all:

debounce   manifest=y  runtime=n      loadCardElement     manifest=y  runtime=n
throttle   manifest=y  runtime=n      confirmPayment      manifest=y  runtime=n
clamp      manifest=y  runtime=n      confirmCardPayment  manifest=y  runtime=n
delay, dateFormat, format             all manifest=y, runtime=n

The "NOT available" list is wrong for 8 of its 13 names. ref, computed, reactive, watch and watchEffect are all real globals, as Vue-compatibility aliases onto stx's own primitives:

window.ref = state
window.reactive = reactive
window.computed = derived
window.watch = $watch
window.watchEffect = function (fn) { return effect(fn) }

useColorMode, useLocalStorage and useCounter are globals too. Only useIntersectionObserver, useScroll, useMouse, useParallax and usePreferredReducedMotion are genuinely absent from both.

That inverts the correction the file carries a scar about. It reads:

NOT ref, computed, reactive, watch or watchEffect. This list named all five for a long time […] None of them are in either manifest. Reactivity in a template comes from stx's own state / derived / effect

The last sentence is right about where reactivity comes from, and the aliases mean the five work anyway. The correction was made on the manifest's authority, and the manifest had already stopped describing anything.

The harm runs both ways

• An agent writes useStorage(...) or debounce(...) bare, on the strength of a list given "in full, because a half-remembered name is the whole problem". buddy typecheck passes. The browser throws during setup and the page does not load.
• An agent avoids ref, computed, useLocalStorage and useColorMode, or imports them from somewhere, because the file says they are not there.

Reproducing

const src = await (await import('@stacksjs/stx')).getCachedSignalsRuntime(false)
const globals = new Set([...src.matchAll(/window\.([A-Za-z_$][\w$]*)\s*=/g)].map(m => m[1]))
const manifest = new Set(Object.keys(
  (await Bun.file('storage/framework/browser-auto-imports.json').json()).globals))
// globals.size 60, manifest.size 83, intersection 3

I have fixed the stacks-composables page against the runtime (a9b011209e) and will do the same for the AGENTS.md section, since it is the one every agent reads first. The deeper question this issue is really asking - whether the manifest should be regenerated from the runtime, the runtime extended to cover it, or the manifest retired along with the tool that stopped writing it - is still open.