tracked() architecture: per-component signal scoping for React

[scottmessinger]

Summary

• Replace useTracked with tracked() — a component wrapper that gives each component its own signal subscription scope
• Fix array mutation bugs (splice/pop/shift were completely broken)
• Add $VERSION as a signal for efficient array structural tracking
• Remove all failed experiments (DirectFor, $$(), createView, vite-plugin)
• Set up oxfmt + oxlint with pedantic + style categories

The tracked() architecture

tracked() wraps a component definition. It sets currentSub once before the component function runs and restores it after. All reactive proxy reads during the component's render are tracked to that component's own effect.

const Row = tracked(({ item, isSelected }) => {
  return (
    <tr className={isSelected ? 'danger' : ''}>
      <td>{item.id}</td>
      <td>{item.label}</td>
    </tr>
  )
})

Key property: Component(props) is synchronous — children render later in separate React calls. So currentSub doesn't leak into children. Each tracked() component independently subscribes to exactly the signals it reads.

Result: label change on row 5 re-renders only Row 5. App doesn't re-render. No 1000-item memo check cascade.

Benchmark results (apples-to-apples, same Row template)

Operation	useTracked (old)	tracked() (new)	delta
create 1000	57.9ms	40.3ms	30% faster
replace all	61.7ms	52.0ms	16% faster
partial update	18.0ms	2.4ms	7.5x faster
select row	5.6ms	3.8ms	32% faster
swap rows	40.6ms	8.7ms	4.7x faster
remove row	7.6ms	6.0ms	21% faster
create 10000	759ms	615ms	19% faster
append 1000	51.0ms	55.5ms	~same
clear	10.7ms	10.5ms	same

Faster or equal on every operation. Zero regressions.

Core changes

• deleteProperty on arrays: splice/pop/shift were throwing "Direct deletion not allowed." Fixed to allow silent deletes with ownKeys bump.
• $VERSION as signal: bumpVersion writes to a signal. Alien-signals deduplicates dirty-marking so 1000 writes during splice cost ~0.2ms (vs 999 ownKeys bumps at ~30ms).
• Array version auto-subscribe: When the reactive proxy returns an array with an active subscriber, automatically subscribe to the version signal. Splice, push, swap all detected.
• trackSelf on array function access: .map(), .forEach() etc. subscribe to ownKeys when there's a subscriber.

Removed (failed experiments)

• packages/vite-plugin/ — $$() compiler transform (double work with React)
• packages/js-krauset-direct/ — DirectFor benchmark (catastrophic on structural mutations)
• packages/react-example/ — unused example
• DirectFor — full DOM rebuild, 788x slower on remove
• $$() / useDirectBindings — bypasses React but does double work, or requires store-coupled components
• createView / useView — marginal improvement (0.07% of reads benefit from getter vs proxy)
• useScopedTracked — correct concept but proxy wrapper slower than tracked()
• use-sync-external-store — vestigial from old useTracked

Tooling

• oxfmt for formatting (replaces prettier)
• oxlint with pedantic + style categories on src/ (replaces eslint)
• CI updated with lint and format:check steps
• Removed eslint, prettier configs

Test plan

• 188 tests pass across all packages
• 0 typecheck errors
• 0 lint errors (pedantic + style on src/)
• All files formatted (oxfmt)
• tracked() correctness: per-component scoping, label isolation, structural operations
• tracked() safe on non-reactive components (acts as memo())
• Nested tracked() components have independent subscriptions
• Krauset benchmark compliance tests (9 operations)

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v0-supergrain	Error		Mar 16, 2026 9:13pm
v0-supergrain-5971	Ready	Preview, Comment, Open in v0	Mar 16, 2026 9:13pm

[Copilot]

Pull request overview

This PR introduces a “compiled reads” pipeline for @supergrain/core stores: createStore returns a branded type to enable a Vite TypeScript transform that rewrites store.foo reads into direct signal access via readSignal(...)(). It also adds a simplified React hook (useTracked) meant to work with compiled reads, plus an ESLint rule to enforce useTracked usage when readSignal is used.

Changes:

• Add Branded<T> + $BRAND to createStore types and introduce readSignal(target, prop) in core.
• Add @supergrain/vite-plugin that rewrites branded property reads into readSignal(...)() and injects imports.
• Add useTracked in @supergrain/react and an @supergrain/eslint-plugin rule (require-use-tracked) with tests.

Reviewed changes

Copilot reviewed 53 out of 55 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
vitest.config.ts	Adds a dedicated node-environment project for eslint-plugin tests.
tsconfig.json	Adds TS project references for new workspace packages (vite-plugin, eslint-plugin).
packages/vite-plugin/vite.config.ts	Library build config for the new Vite plugin package.
packages/vite-plugin/tsconfig.json	TS config for vite-plugin (composite/declarations/outDir).
packages/vite-plugin/tests/transform.test.ts	Unit tests for branded-read transform behavior.
packages/vite-plugin/src/plugin.ts	TS compiler API transform + import injection + Vite plugin wrapper.
packages/vite-plugin/src/index.ts	Exports supergrain() plugin entrypoint.
packages/vite-plugin/package.json	New package metadata/deps/scripts for @supergrain/vite-plugin.
packages/react/tests/use-tracked.test.tsx	React tests validating useTracked + readSignal re-render behavior.
packages/react/src/use-store.ts	Adds useTracked hook intended for compiled reads.
packages/react/src/index.ts	Exports useTracked from @supergrain/react.
packages/js-krauset/src/main.tsx	Updates imports to include $BRAND/Branded (currently unused).
packages/eslint-plugin/vitest.config.ts	Vitest config for eslint-plugin tests.
packages/eslint-plugin/tsconfig.json	TS config for eslint-plugin (composite/outDir).
packages/eslint-plugin/tests/require-use-tracked.test.ts	Tests for require-use-tracked rule.
packages/eslint-plugin/src/rules/require-use-tracked.ts	ESLint rule implementation enforcing useTracked with readSignal.
packages/eslint-plugin/src/index.ts	ESLint plugin entry exporting rules.
packages/eslint-plugin/package.json	New eslint-plugin package metadata (currently points main to TS sources).
packages/core/tests/read-signal.test.ts	New tests validating readSignal reactivity + proxy interop.
packages/core/tests/branded-type.test.ts	Type-level tests for Branded<T> + runtime sanity checks.
packages/core/src/store.ts	Adds $BRAND, Branded<T>, readSignal, and updates createStore return type.
packages/core/src/index.ts	Exports readSignal, setProperty, $BRAND, and Branded.
packages/core/prototype/vite-plugin.ts	Prototype plugin (regex-based) for earlier experimentation.
packages/core/prototype/vite-plugin-bench/vite.config.ts	Prototype bench Vite config.
packages/core/prototype/vite-plugin-bench/src/bench.ts	Prototype bench harness for rewritten vs proxy reads.
packages/core/prototype/vite-plugin-bench/check-transform.ts	Script to print prototype transform output.
packages/core/prototype/realistic.bench.ts	Prototype “realistic” benchmark scenarios.
packages/core/prototype/preact-store.ts	Prototype preact-signals store implementation for benchmarking.
packages/core/prototype/preact-store-correctness.test.ts	Correctness tests for preact-store prototype.
packages/core/prototype/plugin-feasibility/input.ts	Feasibility input for TS compiler detection of branding.
packages/core/prototype/plugin-feasibility/detect-branded.ts	Feasibility script for brand detection via TS checker.
packages/core/prototype/model.ts	Prototype model implementation and benchmarks scaffold.
packages/core/prototype/model.test.ts	Prototype model correctness tests.
packages/core/prototype/model.bench.ts	Prototype model benchmarks.
packages/core/prototype/direct-signal-reads.bench.ts	Benchmarks for “direct signal read” approach.
packages/core/prototype/direct-signal-correctness.test.ts	Correctness tests for “direct signal read” approach.
packages/core/prototype/computed-vs-signal.bench.ts	Benchmarks comparing computed vs signal call overheads.
packages/core/prototype/compiled-vs-stores.bench.ts	Benchmarks comparing compiled approach vs other stores.
packages/core/prototype/compiled-reads.bench.ts	Benchmarks focused on compiled reads.
packages/core/prototype/compiled-reads-and-writes.bench.ts	Benchmarks for compiled reads plus compiled writes.
packages/core/prototype/compiled-correctness.test.ts	Correctness tests for benchmark scenarios.
packages/core/prototype/compiled-alien-vs-preact.bench.ts	Benchmarks comparing alien vs preact primitives under same architecture.
packages/core/prototype/check-versions.mjs	Script to print installed versions for benchmark context.
packages/core/prototype/call-overhead.bench.ts	Benchmarks for per-call overhead in effects.
packages/core/prototype/branded-type.typetest.ts	Large type-level validation suite for Branded<T>.
packages/core/package.json	Updates core package metadata/deps/scripts (includes version change).
packages/core/benchmarks/state-libraries.bench.ts	Adds cross-library benchmarks (zustand/jotai/mobx/valtio/preact).
packages/core/benchmarks/STATE_LIBRARIES.md	Documents benchmark results/interpretation.
packages/core/benchmarks/ROW_OPERATIONS.md	Documents row operation benchmark results.
packages/core/benchmarks/CORE_COMPARISON.md	Documents core vs solid-js/store benchmark results.
packages/core/benchmarks/ADDITIONAL.md	Documents additional benchmark results and analysis.
packages/core/PLAN-model-api.md	Design/plan doc for the compiled reads approach and plugin.
notes/failed-approaches/inline-primitive-checks-optimization.md	Postmortem doc for a reverted micro-optimization attempt.
.claude/settings.local.json	Updates local Claude tool allowlist (dev-only config).

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.