@phcdevworks/spectre-shell-signals

Small synchronous reactive primitives for Spectre packages. The package provides signal, computed, and effect without tying Spectre runtime code to a UI framework.

Part of the PHCDevworks Spectre shell ecosystem — composable, zero-dependency packages for client-side shell applications.

Contributing | Changelog | Roadmap | Security Policy

When to use this package

• You need synchronous reactive primitives (signal, computed, effect) without a full state management framework.
• You want typed, lazily-evaluated derived values with explicit disposal.
• You are building on top of a Spectre shell or want framework-agnostic reactive state in vanilla TypeScript.

When not to use this package

• You need a global store, atoms, selectors, or async resource primitives.
• You need framework-specific hooks such as useSignal for React or Vue.
• You need persistence, devtools, observables, event buses, or middleware.
• You need cross-component state coordination patterns beyond sharing signal instances.

Capabilities

• Mutable signals through a .value getter and setter.
• Lazily evaluated computed values with dependency tracking.
• Synchronous effects with cleanup registration.
• Explicit disposal for computed values and effects.
• A deliberately small public API for shared Spectre runtime state.

Install

npm install @phcdevworks/spectre-shell-signals

Quick Start

import { computed, effect, signal } from '@phcdevworks/spectre-shell-signals'

const count = signal(0)
const doubled = computed(() => count.value * 2)

const stop = effect((onCleanup) => {
  console.log(`count=${count.value}; doubled=${doubled.value}`)
  onCleanup(() => console.log('effect cleanup'))
})

count.value = 2
stop()
doubled.dispose()

API

• signal(initialValue) returns a mutable signal.
• computed(fn) returns a cached computed value with dispose().
• effect(fn) runs immediately, reruns when tracked dependencies change, and returns a stop function.
• batch(fn) defers subscriber notification until fn returns, so effects run once per batch rather than once per write.
• Types include Signal, Computed, EffectCallback, EffectCleanup, CleanupRegistrar, and StopEffect.

Boundaries

This package owns only low-level reactive primitives. It does not own DOM rendering, routing, lifecycle orchestration, async scheduling, stores, persistence, or framework adapters.

Development

npm install
npm run check

Useful scripts:

• npm run typecheck validates TypeScript without emitting files.
• npm run lint runs ESLint.
• npm run test runs the Vitest suite once.
• npm run build emits ESM, CJS, and declarations to dist.
• npm run check runs the standard package verification flow.

AI-agent coordination starts in AGENTS.md, with companion guidance in CLAUDE.md, CODEX.md, COPILOT.md, JULES.md, and .github/copilot-instructions.md.

Troubleshooting

Problem	Likely cause	Fix
npm run check fails on typecheck	Type error in source or tests	Run npm run typecheck to isolate
dist/ is missing after clone	Build output is gitignored	Run npm run build
Tests fail in CI but pass locally	Node version mismatch	CI runs Node 22 and 24; match locally
Effect runs more than expected	Unintended .value read in tracked scope	Move non-reactive reads outside the effect callback

Contributing

See CONTRIBUTING.md. The gate is npm run check — all of typecheck, lint, build, and tests must pass. Do not expand the reactive-primitives scope; see AGENTS.md for boundaries.

Release Notes

See CHANGELOG.md.

License

MIT. See LICENSE.