TL;DR
packages/stx/src/signals-api.ts:150-400 exports TypeScript implementations of state, derived, effect, batch, peek, untrack, isSignal, onMount, onDestroy, and friends. These functions have full bodies and look like the canonical reactivity primitives.
They're not. The actual runtime behavior comes from the template-literal-generated runtime inside packages/stx/src/signals.ts, which the dev server / build pipeline injects into pages. The signals-api.ts versions only exist for IDE autocomplete and type-checking from TypeScript modules (server-side composables, stores, etc.).
This creates a hidden fork: if user code calls state(0) from a place where the signals.ts runtime hasn't been injected (e.g., a bare TypeScript module imported at SSR time), they get the signals-api.ts implementation. That implementation runs, returns "a state-like object" — but it's not wired into the same reactive graph as anything in the page. Bindings won't react. Effects won't fire. And there's no warning.
Where this happens
The intended split:
- Page
<script client>→ bundled into setup function → runtime template literal injected →state()is the runtime version → fully reactive ✅ - TypeScript composables under
functions/orstores/imported by a<script client>→ still gets the runtime via the bundler injectingwindow.stx.statedestructure → ✅ - A
.tsfile imported by something OTHER than a client script (an SSR-time server module, a Node CLI, a test) → gets the signals-api.ts stub → not reactive, no error ❌
How to verify
Search for any code that imports state / derived from 'stx' outside of a <script client> block context. The composables/* directory uses them legitimately (they're meant to compose into client scripts), but other server-side code paths might call them and silently get the wrong impl.
Proposed fix
Pick one:
Make the stubs throw: change signals-api.ts impls to throw an explicit "the stx runtime is not loaded in this context — did you call state() from a server-only module?" error. This breaks SOME existing patterns but surfaces the bug at first use.
Make the stubs fall through to window.stx if present:
state = (...args) => (typeof window !== 'undefined' && window.stx?.state ? window.stx.state(...args) : nonReactiveStub(...args)). Works in browser contexts that happen to load the runtime; still silent in pure-Node contexts.Mark signals-api.ts as types-only: convert to a
.d.tsso users can import types but the runtime can't accidentally execute the stubs. Requires checking which downstream code actually invokes the functions vs just imports the types.Add a parity test: an integration test that imports each function from
signals-api.tsand verifies it produces a reactive object. Doesn't fix the underlying issue but flags drift.
Found during a deep-scan audit. The framework's largest single architectural debt point.
🤖 Filed via Claude Code