The headless kernel of a StateWalker application: the packages that start an application from a manifest (backbone.*), hold the workspace and its files (workspace.*), declare host capabilities (platform.*), and keep the state of the dock, panels, file explorer, settings and web-app projects. Nothing here renders UI or depends on React; renderers live in separate *.view.react packages that read this state. All packages are published to npm under @statewalker/*.
packages/
backbone.core backbone.browser backbone.node start an app from an AppManifest
workspace.core workspace.browser Workspace, files, adapters
workspace-vcs.core git as an opt-in project nature
platform.core platform.browser platform.node host capabilities as commands
render.core shell.core mime.core explorer.core panel specs, dock, file viewers, explorer
inline.core settings.core inline content, settings
webapp.core webapp.browser web-app projects served from a ServiceWorker
scripts/ maintenance scripts (see Reference)
The suffix says where a package runs: .core runs anywhere (no DOM, no Node built-ins), .browser needs a browser, .node needs Node.
Main runtime dependencies between the packages (arrows point at the dependency; some edges omitted):
backbone.browser ─┐
backbone.node ────┴─> backbone.core (no other dependencies)
platform.browser ─┐
platform.node ────┴─> platform.core ─────────────┐
workspace.browser ───────────────────────────────┤
workspace-vcs.core ──────────────────────────────┤
settings.core ───────────────────────────────────┤
explorer.core ─> mime.core ─> shell.core ─> render.core ─> workspace.core
webapp.browser ─> webapp.core ───────────────────┘
inline.core (shared-* only)
| Package | What it does | npm |
|---|---|---|
| backbone.core | AppManifest, module resolution and the fragment activation loop. No dependencies. |
@statewalker/backbone.core |
| backbone.browser | Browser bootstrap: bundler mode or runtime import maps with es-module-shims. | @statewalker/backbone.browser |
| backbone.node | Node bootstrap and the backbone-start / backbone-watch scripts. |
@statewalker/backbone.node |
| workspace.core | The Workspace: files, projects, adapters, logging. |
@statewalker/workspace.core |
| workspace.browser | Opens a browser directory as the workspace and keeps it across reloads. | @statewalker/workspace.browser |
| workspace-vcs.core | Git for a workspace project: init, add, commit, log, status, HTTP remotes. | @statewalker/workspace-vcs.core |
| platform.core | Host capabilities (pickers, downloads, clipboard, preferences, URL state) as command declarations. | @statewalker/platform.core |
| platform.browser | Browser handlers for the platform commands. | @statewalker/platform.browser |
| platform.node | Node handlers for the preference commands. | @statewalker/platform.node |
| render.core | Panel spec store, saved dock layout, renderer catalogs. | @statewalker/render.core |
| shell.core | Dock state and the show/close/focus panel commands. | @statewalker/shell.core |
| mime.core | Chooses a viewer for a file by MIME type; files:open / files:visualize. |
@statewalker/mime.core |
| explorer.core | File explorer state: navigation, tree, search, file commands. | @statewalker/explorer.core |
| inline.core | Types and slot for components embedded in content. | @statewalker/inline.core |
| settings.core | Settings sections and their state. | @statewalker/settings.core |
| webapp.core | Web-app projects: convention detection, config, module-server cache. | @statewalker/webapp.core |
| webapp.browser | Serves a web-app project from a ServiceWorker with cross-origin isolation headers. | @statewalker/webapp.browser |
Every package is public; there are no private packages or apps in this repository.
Dependencies from outside the repository, by package: @statewalker/shared-adapters, shared-baseclass, shared-commands, shared-logger, shared-logger-pino, shared-registry, shared-slots; @statewalker/webrun-files and its -browser, -node, -mem, -composite backends, webrun-builder, webrun-dataflow, webrun-modules; @statewalker/webrun-site-builder, webrun-site-host; @statewalker/vcs-* (used by workspace-vcs.core).
Requirements: Node 24 and pnpm 10 through corepack (the version is pinned in packageManager).
corepack enablepnpm installpnpm run build— builds every package'sdist/with tsdown, dependencies first.pnpm run test— vitest in every package.pnpm run typecheck—tsc --noEmitin every package. Needs step 3 (see below).pnpm run lint:checkandpnpm run format:check— Biome, as CI runs them.pnpm run lintandpnpm run formatapply the fixes.
To work on one package: pnpm --filter @statewalker/platform.browser test (or build, typecheck, test:watch where the package defines it).
State and behaviour live here; React views live in *.view.react packages that depend on these packages. Because of that split, every package here is tested with vitest in Node or jsdom, without a browser.
Each package's exports point at dist/ (JavaScript plus .d.ts, built by tsdown without bundling), and also carry a source condition that points at src/*.ts. src/ is in files, so the sources ship to npm too. Consumers get plain JavaScript; tools that resolve the source condition, such as the vitest configs here, run against TypeScript without a build.
backbone.* packages may depend at runtime only on each other. backbone.core vendors the small logger it needs instead of depending on @statewalker/shared-logger. scripts/check-backbone-isolation.ts checks the rule; CI does not run it.
Most .core packages export a ./fragment entry (an init(ctx) for the backbone) and communicate through the workspace's Commands bus (@statewalker/shared-commands) and slots (@statewalker/shared-slots). A fragment can be replaced, or run without its UI, as long as someone answers the same commands.
pnpm run typecheckfails on a fresh clone withTS2307: Cannot find module '@statewalker/workspace.core' or its corresponding type declarations.tscreads sibling packages' types from theirdist/, which only exists afterpnpm run build. Tests do not have this problem, because vitest resolves thesourcecondition.- A command that never returns. Every command declared here uses the
silentdispatch policy: if no fragment handles the command when it is called, the promise never settles and nothing is logged. Check that the fragment that handles it is in the manifest and starts first. - Fragments missing at runtime after installing from npm. The backbone follows only
workspace:dependencies to find fragments. In an installed (non-workspace) project, list every fragment in the manifest'sroots. pnpm run lint:checkprints warnings. Accessibility rules are set towarninbiome.json; warnings do not fail the check.turbo.jsonexists, but the root scripts usepnpm -r, which already runs packages in dependency order.
| Command | Does |
|---|---|
pnpm run build |
pnpm -r run build (tsdown) |
pnpm run test |
pnpm -r run test (vitest) |
pnpm run typecheck |
pnpm -r run typecheck (tsc --noEmit) |
pnpm run lint / lint:check |
biome check --write . / biome check . |
pnpm run format / format:check |
biome format --write . / biome format . |
pnpm changeset |
Record a version bump and changelog entry for your change. |
pnpm exec tsx scripts/check-backbone-isolation.ts |
Check that backbone.* declares no runtime @statewalker/* dependency other than backbone.*. |
scripts/scaffold-substrate.sh creates empty package skeletons and is not needed for normal work.
- Workspace packages refer to each other with
workspace:^. External versions come from the catalog inpnpm-workspace.yaml(catalog:). - Biome 2 formats and lints everything (2 spaces, double quotes, 100 columns).
Packages are published to npm from CI with changesets and npm provenance. After CI passes on main, a release job adds changesets for packages whose packed contents differ from the published version and opens a "chore: version packages" pull request; merging it publishes. To choose the bump or the changelog text yourself, add a changeset with pnpm changeset in your pull request.
MIT, see LICENSE.