Spectre Shell

`@phcdevworks/spectre-shell` is the app bootstrap shell package of the Spectre system. It wires a root element to route definitions, starts the router, imports shared shell styles, and exposes a small readiness signal for Spectre apps.

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

@phcdevworks/spectre-shell is the app bootstrap shell package of the Spectre system. It wires a root element to route definitions, starts the router, imports shared shell styles, and exposes a small readiness signal for Spectre apps.

Maintained by PHCDevworks. It is the app-layer integration point that composes spectre-shell-router and spectre-shell-signals with spectre-tokens and spectre-ui from project-design, without owning router, signals, or styling internals itself.

Repository Snapshot

Field Value
Project team project-shell
Repository role Spectre app bootstrap shell
Package/artifact @phcdevworks/spectre-shell
Current version/status 1.2.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

Thin application bootstrap shell for Spectre apps. It wires a root element to route definitions, starts the router, imports shared shell styles, and exposes a small readiness signal.

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 are wiring a Spectre app into a DOM root and need bootstrap lifecycle management.
  • You want optional beforeMount / afterMount callbacks and a bootReady signal without writing the plumbing yourself.
  • You are composing @phcdevworks/spectre-shell-router and @phcdevworks/spectre-shell-signals into a working shell.

When not to use this package

  • You need a full application framework — this package handles startup only.
  • You need server-side rendering, SSR hydration, or meta-framework integration.
  • You need application state, domain logic, or component rendering — those belong downstream.

Capabilities

  • Bootstraps a Spectre app into a provided root element.
  • Accepts route factories compatible with @phcdevworks/spectre-shell-router.
  • Runs optional beforeMount and afterMount lifecycle callbacks.
  • Installs optional shell plugins before route registration.
  • Returns the router instance for programmatic navigation and subscriptions.
  • Exposes bootReady as a reactive signal.
  • Loads package-level shell styles through ./styles.js.

Install

npm install @phcdevworks/spectre-shell

Quick Start

import { bootstrapApp } from '@phcdevworks/spectre-shell'

const root = document.querySelector<HTMLElement>('#app')

if (!root) {
  throw new Error('Missing #app root element.')
}

bootstrapApp({
  root,
  routes: () => [
    {
      path: '/',
      loader: async () => ({
        render({ root }) {
          root.textContent = 'Ready'
        },
      }),
    },
  ],
})

Bootstrap Sequence

When bootstrapApp() is called, the shell runs the following steps in order:

  1. beforeMount() — optional callback fires before route registration.
  2. routes() — the route factory is called and routes are collected.
  3. new Router(routes, root) — routing control is handed to @phcdevworks/spectre-shell-router.
  4. bootReady.value = true — the readiness signal is set.
  5. afterMount() — optional callback fires after the router is running and bootReady is set.

Steps 1–4 are wrapped in an error boundary. Failures throw [spectre-shell] Bootstrap failed: <message> with the original error preserved as cause. If afterMount fires, bootstrap succeeded.

API

  • bootstrapApp(options) runs the shell bootstrap flow and returns the Router instance created from options.routes(), giving consumers direct access to router.navigate(), router.back()/forward(), and router.subscribe().
  • bootReady is a signal that becomes true after the router starts.
  • BootstrapOptions defines root, routes, beforeMount, afterMount, and plugins.
  • ShellPlugin defines a named install(context) callback. The context exposes bootReady for read/write signal access during plugin setup.
import { effect } from '@phcdevworks/spectre-shell-signals'
import { bootstrapApp, bootReady, type ShellPlugin } from '@phcdevworks/spectre-shell'

const analyticsPlugin: ShellPlugin = {
  name: 'analytics',
  install({ bootReady }) {
    console.debug('Shell ready before routes:', bootReady.value)
  },
}

effect(() => {
  console.debug('Shell ready:', bootReady.value)
})

const router = bootstrapApp({
  root,
  routes: () => [...],
  plugins: [analyticsPlugin],
  beforeMount() {
    console.debug('Preparing routes')
  },
  afterMount() {
    console.debug('Router mounted')
  },
})

router.navigate('/about')

Ecosystem

spectre-shell is the SPA entry point of the Spectre stack. Each package owns a distinct layer:

Package Role
spectre-shell SPA bootstrap — wires root, router, styles, and bootReady signal
spectre-shell-router Client-side routing — path matching, lazy loaders, guards, named routes
spectre-shell-signals Reactive primitives — signal, computed, effect, batch
spectre-tokens Design token contract — CSS variables, JS values, Tailwind preset
spectre-ui Styling layer — class recipes, CSS bundles, Tailwind integration
spectre-ui-astro Astro component adapter — SpButton, SpCard, SpInput, and more

Two deployment paths exist in the Spectre ecosystem:

  • SPA path — spectre-shell bootstraps a vanilla TypeScript app into a DOM root via bootstrapApp(). Use this when building a client-side application without a meta-framework.
  • Astro path — spectre-ui-astro delivers Spectre components as Astro islands. The shell is not used in this path; Astro owns the lifecycle.

Boundaries

This package owns the bootstrap surface between an app root and Spectre routing primitives. It does not own route matching internals, general-purpose state management, component rendering, persistence, design tokens, or framework adapters.

Server-Side Rendering

This package does not support SSR. bootstrapApp() assumes a live DOM environment: it calls new Router(routes, root) against a real element and sets a signal value synchronously. There is no hydration path, no server-entry point, and no framework adapter.

SSR support will be evaluated only if a concrete integration requirement from a WordPress or Astro context is identified. Until then, the SSR stance is: not supported, not planned.

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 declarations and JavaScript 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
Tests fail in CI but pass locally Node version mismatch CI runs Node 22 and 24; match locally
dist/ is missing after clone Build output is gitignored Run npm run build
bootReady stays false Bootstrap threw before setting signal Check for errors in beforeMount or routes()
Styles not applied styles.js side-effect not imported bootstrapApp handles this; verify sideEffects in bundler config

Contributing

See CONTRIBUTING.md. The gate is npm run check — typecheck, lint, build, tests, and check:ecosystem must all pass. Do not add routing logic, state management, or rendering to this package; see AGENTS.md for boundaries.

Release Notes

See CHANGELOG.md.

License

MIT. See LICENSE.

Roadmap

Spectre Shell Roadmap

@phcdevworks/spectre-shell is the thin SPA bootstrap layer for the Spectre system. It wires a root DOM element to route definitions, starts the router, loads shared shell styles, and exposes a bootReady readiness signal.

The foundation is complete at v1.2.0. Phase 2 (P2.1–P2.5) is fully done and prepared for release. Phase 3 (broader adoption) is now open.

Phase 1: Foundation — Complete (v0.0.1 – v1.1.0)

All Phase 1 deliverables shipped. See CHANGELOG.md for details.

  • Bootstrap error boundary, lifecycle hooks, bootReady signal — v1.0.0
  • CI pipeline on Node 22 and 24 — v0.0.2
  • Consumer smoke validation against built output — v1.1.0
  • SSR stance documented — browser-only, not planned — v1.1.0
  • Plugin system evaluated and proposal written — v1.1.0

Phase 2: Ecosystem Integration

The Spectre package stack is now stable across all five packages (spectre-shell, spectre-shell-router, spectre-shell-signals, spectre-tokens, spectre-ui). Phase 2 is about wiring them into real SPA applications and making that story clear for downstream consumers.

P2.1 Integration Example

Status: Done

A minimal SPA that exercises all five Spectre packages together: shell, router, signals, tokens, and ui. This validates end-to-end assembly from bootstrapApp() through styled output, and serves as the canonical reference pattern for any downstream app.

Delivered as examples/minimal-spa, an npm-workspace member built with Vite:

  • bootstrapApp() wired to two routes (/, /about) with lazy loader() functions
  • bootReady observed via effect() from spectre-shell-signals
  • spectre-tokens/spectre-ui CSS imported from each package’s published index.css export
  • vite build resolves @phcdevworks/spectre-shell and its ecosystem dependencies through their published package.json exports → dist/, validating the real install path rather than source

P2.2 Plugin System Implementation

Status: Done in v1.2.0

plugins?: ShellPlugin[] implemented on BootstrapOptions. ShellPlugin and ShellPluginContext exported from the public API. Plugin execution order, invocation, and error boundary propagation covered in tests.

P2.3 Ecosystem Documentation

Status: Complete in v1.1.1

The README now maps the Spectre packages and their roles. Consumers discovering the shell through spectre-ui-astro or spectre-tokens have a clear map of how everything fits together.

Deliverables:

  • Ecosystem table in README.md (aligned with the pattern in shell-signals and shell-router READMEs)
  • Clear distinction between the SPA path (shell-based) and the Astro path (ui-astro)
  • Cross-links to package repositories

P2.4 Router Signal Bridge

Status: Decided — app-layer. Phase 2 closed on this item.

spectre-shell-router exposes router.subscribe(), onNavigationStart, and onNavigationEnd. Consuming apps wire currentRoute and navigating signals directly using spectre-shell-signals at the app layer. The shell does not export these signals — it stays thin. Revisit only if two or more independent apps repeat the same wiring pattern.

P2.5 Programmatic Navigation

Status: Done in v1.2.0.

bootstrapApp now returns the Router instance created from options.routes() instead of void (Option A). Additive change — no existing call sites break; gives consumers full router access (navigate, replace, back, forward, subscribe). Covered in tests/bootstrap.test.ts; documented in README.md.

Unblocked by this release:

  • spectre-init Phase 6 template modernization (navigate() in templates)
  • spectre-shell Phase 3 (Phase 2 is now fully closed)

Phase 3: Broader Adoption

Phase 2 is fully closed (P2.4 decided ✓, P2.5 implemented ✓). Phase 3 is open.

P3.1 Starter Template

A reusable starter repo or create-spectre-app scaffolding that pre-wires the full SPA stack. Depends on P2.1 validated and stable and P2.5 shipped.

P3.2 Framework Adapter Consideration

The shell is browser-only vanilla TypeScript. Evaluate whether a thin adapter (e.g. @phcdevworks/spectre-shell-vue) belongs in the ecosystem. Triggered only when a downstream app requires a framework-specific bootstrap entry point.

Explicitly Out of Scope

  • Routing internals — belong in @phcdevworks/spectre-shell-router
  • Reactive primitives — belong in @phcdevworks/spectre-shell-signals
  • Token and style definitions — belong in @phcdevworks/spectre-tokens and @phcdevworks/spectre-ui
  • Astro component rendering — belongs in @phcdevworks/spectre-ui-astro
  • Full application framework — this package handles startup orchestration only