ReviewOS

stacks/stx

refactor(runtime): split signals.ts into focused modules

#2075
Closed glennmichael123 opened this 9 days ago ·
9 days ago

Summary

packages/stx/src/signals.ts has grown to roughly 10,000 lines and now mixes several different responsibilities inside one generated-runtime template literal. That makes changes harder to review, increases the chance of regressions, and makes it difficult to find the correct implementation path.

Plan and execute a behavior-preserving split into focused runtime modules.

Proposed investigation

Identify stable seams first, then extract modules without changing the generated runtime contract:

  • host adapter and native bridge operations
  • reactive primitives and effect scheduling
  • expression evaluation and auto-unwrapping
  • DOM/native binding discovery and manifest hydration
  • structural directives such as :if, :for, and :show
  • attribute, text, HTML, model, class, and style bindings
  • component scopes and lifecycle handling
  • router, data/composable, and devtools integrations
  • runtime assembly and development/production generation

The final boundaries should follow the existing dependency graph rather than forcing a purely conceptual split.

Constraints

  • Preserve both generated runtimes: development and production.
  • Preserve the native host contract and JavaScriptCore bundle output.
  • Keep the browser and native implementations behaviorally aligned.
  • Avoid duplicating runtime globals or creating a second reactive implementation.
  • Keep the template-literal escaping rules intact while extracting code.
  • Preserve tree-shaking/minification behavior where practical.

Acceptance criteria

  • signals.ts is reduced to a small runtime assembler and public generator API.
  • Extracted modules have clear ownership and minimal circular dependencies.
  • Existing browser, native, SPA, component, lifecycle, and signal tests remain green.
  • Add boundary-focused tests where extraction exposes previously implicit contracts.
  • Compare representative development and production runtime behavior before and after the split.
  • Document the resulting module map for future contributors.

This is a refactor task, not a behavior-change task. Any unrelated runtime fixes should be filed separately.

9 days ago

Completed and shipped through 8a0ce53.\n\n- Reduced packages/stx/src/signals.ts to a 281-line runtime assembler and public generator API.\n- Split runtime ownership into focused packages/stx/src/client/signals-*-runtime.ts modules.\n- Added boundary tests for the extracted seams.\n- Preserved the generated runtimes byte-for-byte:\n - dev: 473618 bytes, SHA-256 cd1cc8130538eb6cd0e2b31871c32fc43da9f801c1f82ad389f92285fcda148d\n - prod: 219152 bytes, SHA-256 52c12fdbd88645158c34662eded36cc928fbf3bbb21c3d43175a6622b33695de\n- Documented module ownership and dependency rules in docs/advanced/signals-runtime-architecture.md and packages/stx/src/client/README.md.\n- Final CI is green: typecheck, lint, full test suite, and publish validation (https://github.com/stacksjs/stx/actions/runs/38748020859).\n\nThis remained a behavior-preserving refactor; no runtime contract changes were introduced.

Sign in to comment on this issue.