ReviewOS

stacks/stx

signals-api: TypeScript stubs in `signals-api.ts` are dead code at runtime — fragile boundary with the runtime template literal

#1712
Closed glennmichael123 opened this 23 days ago · 1 comment
23 days ago

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/ or stores/ imported by a <script client> → still gets the runtime via the bundler injecting window.stx.state destructure → ✅
  • A .ts file 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:

  1. 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.

  2. 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.

  3. Mark signals-api.ts as types-only: convert to a .d.ts so 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.

  4. Add a parity test: an integration test that imports each function from signals-api.ts and 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

22 days ago

Correction after closer reading

I claimed the signals-api.ts exports are 'stubs' / 'dead code at runtime' — that's wrong. The actual file at packages/stx/src/signals-api.ts:150-198 contains a fully-functional reactive implementation: its own subscribers set, effects tracking, batch handling, _isSignal brand, the works. It's not a stub; it's a real, parallel implementation.

The accurate description of the architecture:

stx ships two independent reactive implementations that don't share state:

  1. packages/stx/src/signals-api.ts — real TS code, imported via module path, used by composables/tests/SSR contexts
  2. The runtime template literal inside packages/stx/src/signals.ts — generated as a string and injected into client pages, owns its own subscribers

Audit of the 5 visible apps (bench-review, paweldregan, training, trailbuddy, stacks) shows:

  • Bundled paths (resources/stores/*.ts, resources/composables/*.ts, <script> blocks in .stx): the stx bundler strips the import line and destructures window.stx.* at the top of the merged setup function. They end up using the runtime template's implementation. ✅
  • Non-bundled paths (storage/framework/core/composables/src/*.ts calling ref/onUnmounted, and the corresponding tests): import lands at signals-api.ts directly. Works correctly because signals-api.ts is a real implementation. ✅

No user code is broken. The original issue framing — that calling state() from a non-bundled context returns 'a state-like object that's not wired into anything reactive' — is incorrect.

Narrowed concern

The genuine architectural debt is:

  1. Two reactive implementations with no shared spec
  2. No parity tests — drift between them goes undetected
  3. No documentation explaining the boundary exists or where it lands
  4. A future fix to one (e.g., the watch() polling fix in #1713) doesn't carry over to the other unless explicitly mirrored

Proposed action (narrowed)

  • Parity test suite: add tests that exercise the same scenario through both implementations and assert equivalent behavior. Catches drift the moment it appears.
  • Docs section in CLAUDE.md (or a dedicated module-level comment in signals-api.ts) explaining: 'this file is the module-import-path reactivity; the page runtime uses a separately-generated implementation in signals.ts; they don't share state — design intent is that the bundler rewrites client-side imports.'
  • Skip: the throw-on-stub-call / fall-through-to-window.stx / convert-to-.d.ts options from the original filing. Those were premised on the wrong characterization.

Sign in to comment on this issue.