Fancy Kit

This npm workspace develops small, independently publishable libraries for Obsidian plug-ins and their shared test fixtures.

The libraries are extracted from, and continuously exercised by, maintained plug-ins and applications rather than existing only as sample abstractions. See Proven in maintained consumers for the concrete TagFolder, DiffZip, Screwdriver, and Self-hosted LiveSync integration and verification boundaries.

The packages use independent 0.x versions. Stable releases are available from npm through the default latest dist-tag. The workspace root and harness application are never published to npm.

Packages

• @vrtmrz/obsidian-plugin-kit: reusable, testable Obsidian UI primitives. See its usage guide for consumer integration.
• @vrtmrz/obsidian-test-session: local real-Obsidian session, bootstrap, and binary preparation infrastructure. See its usage guide for lifecycle and platform boundaries.
• @vrtmrz/ui-interactions: framework-neutral UI contracts, drivers, and an App-free consumer test harness. See its usage and testing guide for adapter composition and scripted tests.
• octagonal-wheels: pure utilities and generic structural algorithms, maintained here with its existing package and commit history. See its import and runtime guide and generated API index.

Workspace application

• Fancy Kit Harness: a public interactive catalogue, guided real-device contract runner, and real Obsidian E2E fixture. Reviewed Harness releases provide a verified web installer that creates a Screwdriver document in a dedicated test Vault; follow the link in the selected GitHub release.

Development

For a quick feedback loop while changing the scoped packages or harness, run:

npm run check:all
npm run test
npm run build
npm run build:harness

Before handing off a repository-wide change, validate every package, including octagonal-wheels, and inspect every package tarball with:

npm run verify:workspace

The octagonal-wheels suite uses headless Chromium. Install its local Playwright browser once with:

npm exec --workspace octagonal-wheels -- playwright install chromium

The equivalent individual whole-workspace commands are check:workspace, test:workspace, build:workspace, build:harness, and pack:workspace.

Real Obsidian E2E remains a local-only suite and is not a default CI gate:

npm run test:e2e:obsidian:install-appimage
npm run test:e2e:obsidian:local-suite

Installation

Install only the packages that a project needs. The commands below use npm's normal compatible version ranges. For the current 0.x versions, those ranges accept patch releases but not the next minor release. Commit the lockfile for repeatable installations; add --save-exact when every dependency upgrade must be reviewed explicitly, including release qualification:

npm install @vrtmrz/ui-interactions
npm install @vrtmrz/obsidian-plugin-kit
npm install octagonal-wheels
npm install -D @vrtmrz/obsidian-test-session
npm install -D playwright @types/node

The plug-in kit installs its matching UI interactions dependency automatically. The test session package is development tooling and should not be bundled into an Obsidian plug-in.

See the package architecture, the release process, and CONTRIBUTING.md for package boundaries, publishing order, API documentation, tests, and UI automation requirements.