@phcdevworks/spectre-shell-signals

@phcdevworks/spectre-shell-signals is the reactive primitives package of the Spectre system. It provides signal, computed, effect, asyncEffect, and batch 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.4.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 |

Small reactive primitives for Spectre packages. The package provides signal, computed, effect, asyncEffect, and batch 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 a full async resource/query layer (loading/error/caching state, request deduplication).
• 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.
• Cancelable async effects with synchronous dependency tracking.
• Batched subscriber notification across multiple signal writes.
• Explicit disposal for computed values and effects.
• A deliberately small public API for shared Spectre runtime state.

Installation

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.
• asyncEffect(fn, options?) runs immediately, reruns when tracked dependencies change, and returns a stop function. Dependencies must be read synchronously, before the first await. Each run gets a fresh AbortSignal, aborted when the effect re-runs or stops. Pass { onError } to handle errors without stopping the effect.
• Types include Signal, Computed, EffectCallback, EffectCleanup, EffectOptions, CleanupRegistrar, StopEffect, AsyncEffectCallback, AsyncEffectContext, and AsyncEffectOptions.

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()

Cleanup callbacks run in reverse registration order, including when one throws. The first cleanup error is reported through onError, or thrown if no handler is provided. A failed cleanup skips that re-run's body; the effect can run again on the next dependency change. Stopping still disposes the effect if cleanup fails.

When a batched effect throws, the remaining queued effects still run before the first error is rethrown.

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

asyncEffect()

asyncEffect is for effect bodies that need to perform async work (e.g. a fetch call) while still participating in the reactive graph. Only the synchronous portion of the callback — before the first await — is tracked; reads after an await belong to a resumed continuation and are not tracked, so read every dependency you need before awaiting anything.

const id = signal(1)

const stop = asyncEffect(async ({ signal: abortSignal, onCleanup }) => {
  const currentId = id.value // tracked: read before the first await
  const response = await fetch(`/api/items/${currentId}`, { signal: abortSignal })
  if (abortSignal.aborted) return
  const item = await response.json()
  console.log(item)
})

id.value = 2 // aborts the in-flight request, re-runs with currentId = 2
stop() // aborts the active request and runs cleanup

Cleanup registered after an async run has been stopped or replaced executes immediately. Cleanup belongs to the run that registered it, even when registered after an await.

Each run receives a fresh AbortSignal that is aborted when the effect re-runs or is stopped — pass it to fetch or any cancelable API so stale work does not race a newer run. Rejections from a run whose signal has since been aborted are swallowed rather than reported to onError, since they belong to a superseded run.

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 |

AI And Automation Boundaries

Claude Code (claude-sonnet-4-6) is the primary development agent for this repository. Codex handles releases, including cutting tagged releases and GitHub Releases, and production stabilization. Jules handles small automated fixes and dependency updates. GitHub Copilot provides development support.

All AI agents with repository access (Claude Code, Codex, Copilot, Jules) have commit, push, and tag authority in this repository. Publishing to npm remains Bradley Potts's sole authority. See AGENTS.md for the full commit-policy and release-authority grant.

Protected from automated change: the reactive-primitives-only scope (no DOM rendering, routing, lifecycle orchestration, async scheduling, stores, persistence, or framework adapters added locally). See AGENTS.md for full agent governance and boundary rules.

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.