Spectre Shell Signals

`@phcdevworks/spectre-shell-signals` is the reactive primitives package of the Spectre system. It provides `signal`, `computed`, and `effect` without tying Spectre runtime code to a UI framework.

This page is generated from the source repository’s README and ROADMAP on every build. Edit the source repository, not this file.

README

@phcdevworks/spectre-shell-signals

@phcdevworks/spectre-shell-signals is the reactive primitives package of the Spectre system. It provides signal, computed, and effect without tying Spectre runtime code to a UI framework.

Maintained by PHCDevworks. It is the reactive primitive foundation for the Spectre stack, integrated by spectre-tokens, spectre-ui, and spectre-ui-astro in project-design, and by spectre-shell at the app-shell layer.

Repository Snapshot

Field Value
Project team project-shell
Repository role Spectre reactive primitives
Package/artifact @phcdevworks/spectre-shell-signals
Current version/status 1.1.0

Standard Workflow

  1. Read AGENTS.md, then the agent-specific guide for the task.
  2. Check TODO.md and ROADMAP.md for current scope.
  3. Make the smallest repo-local change that satisfies the task.
  4. Run npm run check when validation is required or practical.
  5. Update docs and CHANGELOG.md only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide Path
Agent rules AGENTS.md
Claude Code CLAUDE.md
Codex CODEX.md
Copilot COPILOT.md
Jules JULES.md
Roadmap ROADMAP.md
Todo TODO.md
Changelog CHANGELOG.md
Security SECURITY.md

npm version CI License Node

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, and a .peek() method for untracked reads.
  • 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 with .value (tracked read/write) and .peek() (untracked read).
  • computed(fn) returns a cached computed value with dispose().
  • effect(fn, options?) runs immediately, reruns when tracked dependencies change, and returns a stop function. Pass { onError } to handle errors without stopping the effect.
  • 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, EffectOptions, CleanupRegistrar, and StopEffect.

signal.peek()

peek() reads the current value without registering the caller as a subscriber. Use it inside an effect or computed body when you need the value but do not want to re-run the observer when it changes.

const count = signal(0)

effect(() => {
  // re-runs whenever `flag` changes, but NOT when `count` changes
  if (flag.value) {
    console.log(count.peek())
  }
})

Effect error boundary

Pass onError to handle errors thrown inside an effect without stopping the reactive chain. The effect stays active and re-runs normally when its next dependency changes.

const count = signal(0)

const stop = effect(
  () => {
    if (count.value === 1) throw new Error('bad state')
    console.log(count.value)
  },
  { onError: (err) => console.error('effect error:', err) }
)

count.value = 1 // onError fires, effect stays alive
count.value = 2 // logs 2 normally
stop()

Without onError, errors propagate synchronously to the caller — the initial run throws from effect(), and re-run errors throw from the signal setter.

Ecosystem

spectre-shell-signals is the reactive primitive foundation for the Spectre stack:

Package Role
spectre-shell-signals Reactive primitives (signal, computed, effect)
spectre-tokens Visual language and token contracts (reactive token values)
spectre-ui Token-driven styling and class recipes (reactive component state)
spectre-ui-astro Astro component layer (island lifecycle integration)

Consuming packages depend on this package for reactive state. They do not re-export its primitives or extend its API.

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:version-sync confirms the README “Current version/status” row matches package.json.
  • npm run check:ecosystem validates spectre.manifest.json against the ecosystem contract.
  • 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 — typecheck, lint, build, test, README version-sync, and ecosystem validation must all pass. Do not expand the reactive-primitives scope; see AGENTS.md for boundaries.

Release Notes

See CHANGELOG.md.

License

MIT. See LICENSE.

Roadmap

Spectre Shell Signals Roadmap

@phcdevworks/spectre-shell-signals is the minimal reactive-primitives package for the Spectre shell system. It exposes signal, computed, effect, batch, and directly related types — and nothing else. The scope is intentionally tiny and must stay that way.

1. Phase 1 — Foundation — Delivered

All foundation work is complete as of v1.0.0.

Foundation delivered

  • signal<T> with tracked reads and guarded writes.
  • computed<T> with lazy derivation, caching, and explicit dispose().
  • effect() with dependency tracking, synchronous cleanup, and a stop function.
  • Node subscriber registry and tracking.ts activeObserver stack as private internals — not exported.
  • Public types: Signal, Computed, EffectCallback, EffectCleanup, CleanupRegistrar, StopEffect.
  • Dual ESM/CJS output via tsup. TypeScript 6 with strict mode.
  • npm run check gate: typecheck, lint, build, and test.
  • CI on Node 22 and 24.
  • README, CONTRIBUTING, ROADMAP, and AI-agent coordination docs.

Permanent constraints

  • src/internals/ remains private. Node and tracking.ts are never exported.
  • The synchronous reactive model is the contract. No async scheduler is added speculatively.
  • This package does not own DOM binding, framework adapters, stores, or persistence.

2. Phase 2 — Mature Operations — Delivered

All Phase 2 work is complete as of v1.1.0.

Ergonomics and ecosystem delivered

  • signal.peek() — untracked read. Reads current value without registering a dependency, so the caller does not re-run when the signal changes.
  • batch(fn) — deferred subscriber notification. Effects in diamond-dependency graphs run once per batch rather than once per signal write. Nested calls defer until the outermost batch ends.
  • EffectOptions.onError — optional error handler for effect(). When provided, errors thrown inside the effect callback are passed to onError instead of propagating. The effect stays active and re-runs on the next dependency change.
  • Computed stability audit — confirmed and tested that no-op signal writes do not re-derive downstream computed values or re-run downstream effects.
  • Ecosystem manifest — spectre.manifest.json declares this package’s role, layer, exports, and allowed dependency targets. check:ecosystem validates it in the full check gate.
  • 35-case test suite — covers all ergonomic additions alongside the full Phase 1 behavioral contract.
  • v1.1.0 published to npm.

3. Phase 3 — Integration & Adoption — Delivered

All Phase 3 work is complete. Integration documentation and versioning policy are written; the ecosystem manifest is wired into the check gate. These items are queued for the v1.2.0 release.

What was delivered

  • Integration docs — docs/integration/ covers all three downstream targets: spectre-tokens (static vs. reactive token assessment), spectre-ui (signal consumption inside UI components), and spectre-ui-astro (island hydration and StopEffect teardown).
  • Integration guide — docs/integration/guide.md covers the full consuming- package pattern: install, shared signal instances, computed and effect in component context, cleanup, and Astro-specific teardown notes.
  • Versioning policy — docs/versioning-policy.md documents the semver contract and downstream coordination protocol for major releases.
  • Ecosystem manifest — spectre.manifest.json + check:ecosystem in the full check gate.

Next release: v1.2.0 ← NEXT ACTION

All [Unreleased] items are ready to ship. Run npm run release:propose to confirm the semver classification, then hand off to Bradley Potts for tag and publish.

No implementation work is needed before this release.

4. Phase 4 — Ecosystem Hardening (demand-driven)

These are only pursued when a concrete consuming-package need is proven. Do not start either speculatively.

Async effect support

Adoption trigger: a downstream integration has a reactive async workflow that cannot be expressed by scheduling async calls inside a synchronous effect(). If synchronous effect() can handle the use case (even awkwardly), this is not triggered.

When triggered: additive async variant that does not change the synchronous effect() contract; zero impact on consumers not using the async variant.

DevTools hook

Adoption trigger: debugging reactive dependency graphs becomes a concrete pain point reported by a downstream package maintainer. Theoretical value does not count.

When triggered: opt-in, tree-shakeable inspection hook; zero cost when not activated.

5. Explicitly Out of Scope

  • Stores, atoms, selectors, or app-wide state containers
  • Framework adapters (React, Vue, Solid, Astro-specific hooks)
  • Persistence, localStorage, or sessionStorage helpers
  • Async resources or query layers
  • Event buses or observable streams
  • Middleware, plugins, or scheduler complexity
  • DOM binding helpers or rendering lifecycle
  1. Phase 1 ✓
  2. Phase 2 ✓
  3. Phase 3 ✓
  4. Release v1.2.0 ← next (run npm run release:propose, hand off to Bradley Potts)
  5. Phase 4 — async effects / DevTools only when adoption trigger is met.