feat: finalize mvp dev-widget with adapters, monitor domain, and docs

Author: remcostoeten

.github/workflows/ci.yml

@@ -106,6 +106,13 @@ jobs:
       - name: Build
         run: bun run build
 
+      - name: Validate publish artifact
+        run: |
+          npm pack --dry-run 2>&1 | tee pack-output.txt
+          grep -q "dist/index.mjs" pack-output.txt
+          grep -q "dist/index.d.ts" pack-output.txt
+          grep -q "README.md" pack-output.txt
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v4
         with:

README.md

@@ -1,5 +1,9 @@
 # @remcostoeten/dev-widget
 
+[![npm version](https://img.shields.io/npm/v/@remcostoeten/dev-widget)](https://www.npmjs.com/package/@remcostoeten/dev-widget)
+[![CI](https://github.com/remcostoeten/dev-widget/actions/workflows/ci.yml/badge.svg)](https://github.com/remcostoeten/dev-widget/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 Minimal, type-safe dev widget for React apps.
 
 ## Installation
@@ -30,14 +34,73 @@ export function App(): React.ReactElement {
 }
 ```
 
+## Features
+
+- Auth domain
+- Routes domain
+- Links domain
+- Performance domain
+- System domain
+- Monitor domain
+
+## Feature checklist
+
+- [x] React widget shell with tab categories
+- [x] Domain lifecycle (setup/start/stop) via runtime registry
+- [x] Plugin API with typed event subscription
+- [x] Event bus for cross-domain communication
+- [x] Next.js log ingestion route handler
+- [x] In-memory storage adapter
+- [x] Tauri storage adapter export
+- [x] Route discovery adapter for Next.js and React projects
+- [x] Right rail with diagnostics render panel
+- [x] Keyboard shortcuts (toggle + Escape)
+- [x] Accessibility: focus-visible, reduced-motion handling, live region announcements
+- [x] Internal subpath export (`@remcostoeten/dev-widget/internal`)
+- [x] Source maps and declaration output in package build
+- [x] CI publish artifact validation step
+- [x] Demo app build pipeline
+
+## Needs additional work
+
+- AI providers: `openai` and `local` modes are declared but not implemented yet; only `rules` and `custom` are active (`src/domains/performance/aiProviderFactory.ts`).
+- Runtime prop updates: `DevWidget` memoizes runtime by `shouldRender` only, so runtime does not re-bootstrap when non-visibility props change after mount (`src/devWidget.tsx`).
+- Storage wiring: `providers.storage` is part of public config but not wired into runtime/domain persistence flow yet (`src/types/public.ts` and `src/core/bootstrap.ts`).
+- Endpoint validation: Next log handler accepts event payloads without schema validation; malformed event shapes can be persisted (`src/adapters/next/routeHandler.ts`).
+- CI parity: local checks pass, but final release confidence still depends on a pushed branch and green remote GitHub Actions run.
+
+## Plugin API
+
+```ts
+import { createRuntime } from '@remcostoeten/dev-widget'
+
+const runtime = createRuntime({ mode: 'always' })
+
+await runtime.registerPlugin({
+	id: 'my-plugin',
+	version: '1.0.0',
+	register(ctx) {
+		ctx.onEvent('performance/drop-detected', function onDrop(payload) {
+			console.log('FPS drop:', payload.fps)
+		})
+	}
+})
+```
+
 ## Subpath exports
 
 ```ts
 import { DevWidget } from '@remcostoeten/dev-widget/react'
 import { createLogHandler } from '@remcostoeten/dev-widget/next'
 import { createTauriStorage } from '@remcostoeten/dev-widget/tauri'
+import type { WidgetDomain } from '@remcostoeten/dev-widget/internal'
 ```
 
+## Accessibility
+
+The widget includes keyboard shortcuts, focus-visible styling, live announcements, and reduced-motion support.
+See `specs/10-dev-widget-accessibility-keyboard-spec.md` for the detailed behavior contract.
+
 ## Core options
 
 - `enabled?: boolean`
@@ -50,12 +113,18 @@ import { createTauriStorage } from '@remcostoeten/dev-widget/tauri'
 - `accessibility?: { reducedMotion?: 'system' | 'always' | 'never'; announceUpdates?: boolean }`
 - `rightRail?: { enabled?: boolean; defaultPanel?: string | null; collapsible?: boolean; panels?: PanelConfig[] }`
 
-## Types
+## Changelog
 
-Root export includes the full public API and all public types.
+- [CHANGELOG.md](CHANGELOG.md)
 
-```ts
-import type { WidgetProps, FeatureConfig, PerfEvent } from '@remcostoeten/dev-widget'
+## Contributing
+
+```bash
+bun run lint
+bun run format:check
+bun run type-check
+bun test
+bun run build
 ```
 
 ## License

__test__/adapters.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from 'bun:test'
+import { createLogHandler } from '../src/adapters/next/routeHandler'
+
+describe('createLogHandler', () => {
+	test('POST returns success with event count', async () => {
+		const handler = createLogHandler()
+		const req = new Request('http://localhost/api/dev-widget/logs', {
+			method: 'POST',
+			body: JSON.stringify({ events: [{ id: '1' }, { id: '2' }] }),
+			headers: { 'Content-Type': 'application/json' }
+		})
+
+		const res = await handler.POST(req)
+		const body = (await res.json()) as { success: boolean; count: number }
+		expect(body.success).toBe(true)
+		expect(body.count).toBe(2)
+	})
+
+	test('POST handles invalid JSON', async () => {
+		const handler = createLogHandler()
+		const req = new Request('http://localhost/api/dev-widget/logs', {
+			method: 'POST',
+			body: 'not json'
+		})
+
+		const res = await handler.POST(req)
+		expect(res.status).toBe(400)
+	})
+})

__test__/hydrationObserver.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect, mock } from 'bun:test'
+import { setupHydrationObserver } from '../src/domains/system/hydrationObserver'
+
+describe('hydrationObserver', () => {
+	test('ignores non-hydration errors', () => {
+		const callback = mock(() => {})
+		const cleanup = setupHydrationObserver(callback)
+
+		console.error('Some other error')
+		expect(callback).not.toHaveBeenCalled()
+
+		cleanup()
+	})
+
+	test('captures "Text content did not match" with server/client details', () => {
+		const callback = mock(() => {})
+		const cleanup = setupHydrationObserver(callback)
+
+		const msg = 'Text content did not match. Server: "Hello" Client: "World"'
+		console.error(msg)
+
+		expect(callback).toHaveBeenCalledTimes(1)
+		const calls = callback.mock.calls as any[]
+		const error = calls[0][0]
+		expect(error.message).toBe(msg)
+		expect(error.serverContent).toBe('Hello')
+		expect(error.clientContent).toBe('World')
+
+		cleanup()
+	})
+
+	test('captures "Hydration failed because"', () => {
+		const callback = mock(() => {})
+		const cleanup = setupHydrationObserver(callback)
+
+		const msg = 'Hydration failed because the initial UI does not match what was rendered on the server.'
+		console.error(msg)
+
+		expect(callback).toHaveBeenCalledTimes(1)
+		const calls = callback.mock.calls as any[]
+		expect(calls[0][0].message).toBe(msg)
+
+		cleanup()
+	})
+
+	test('captures component stack from args', () => {
+		const callback = mock(() => {})
+		const cleanup = setupHydrationObserver(callback)
+
+		const stack = '\n    in div\n    in App'
+		console.error('Text content did not match.', stack)
+
+		expect(callback).toHaveBeenCalledTimes(1)
+		const calls = callback.mock.calls as any[]
+		expect(calls[0][0].componentStack).toBe(stack)
+
+		cleanup()
+	})
+})

__test__/index.test.ts

@@ -9,7 +9,7 @@ describe('package entry point', () => {
 	})
 
 	test('exports FEATURE_IDS', () => {
-		expect(FEATURE_IDS).toEqual(['auth', 'routes', 'performance', 'system', 'links'])
+		expect(FEATURE_IDS).toEqual(['auth', 'routes', 'performance', 'system', 'links', 'monitor'])
 	})
 
 	test('exports DEFAULTS', () => {
@@ -104,7 +104,7 @@ describe('eventBus', () => {
 describe('registry', () => {
 	test('registers and retrieves domains', () => {
 		const registry = createRegistry()
-		const mockDomain = {
+		const mockDomain: any = {
 			id: 'auth' as FeatureId,
 			setup() {},
 			start() {},
@@ -120,7 +120,7 @@ describe('registry', () => {
 
 	test('tracks started state', () => {
 		const registry = createRegistry()
-		const mockDomain = {
+		const mockDomain: any = {
 			id: 'routes' as FeatureId,
 			setup() {},
 			start() {},

__test__/lifecycle.test.ts

@@ -0,0 +1,45 @@
+import { describe, test, expect } from 'bun:test'
+import { bootstrap } from '../src/core/bootstrap'
+
+describe('runtime lifecycle', () => {
+	test('start activates all registered domains', async () => {
+		const runtime = bootstrap({})
+		await runtime.start()
+		const domains = runtime.registry.listDomains()
+		for (const id of domains) {
+			expect(runtime.registry.isStarted(id)).toBe(true)
+		}
+	})
+
+	test('stop then start works again', async () => {
+		const runtime = bootstrap({})
+		await runtime.start()
+		await runtime.stop()
+		await runtime.start()
+		const domains = runtime.registry.listDomains()
+		for (const id of domains) {
+			expect(runtime.registry.isStarted(id)).toBe(true)
+		}
+	})
+
+	test('disabled features are not started', async () => {
+		const runtime = bootstrap({ disable: ['auth', 'links'] })
+		await runtime.start()
+		expect(runtime.registry.isStarted('auth')).toBe(false)
+		expect(runtime.registry.isStarted('links')).toBe(false)
+		expect(runtime.registry.isStarted('performance')).toBe(true)
+	})
+
+	test('plugin registration works', async () => {
+		const runtime = bootstrap({})
+		let called = false
+		await runtime.registerPlugin({
+			id: 'test-plugin',
+			version: '0.0.1',
+			register() {
+				called = true
+			}
+		})
+		expect(called).toBe(true)
+	})
+})

__test__/linksDomain.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from 'bun:test'
+import { createBus } from '../src/core/eventBus'
+import { createLinksDomain } from '../src/domains/links/linksDomain'
+
+describe('createLinksDomain', () => {
+	test('loads links from extractor and validates against routes', async () => {
+		const bus = createBus()
+		const domain = createLinksDomain(bus)
+
+		domain.setup({
+			extractLinks: async function getLinks() {
+				return [
+					{ target: '/known', sourceFile: 'a.tsx', sourceType: 'next-link' },
+					{ target: '/missing', sourceFile: 'b.tsx', sourceType: 'anchor' }
+				]
+			}
+		})
+
+		bus.publish('routes/discovered', {
+			count: 1,
+			routes: [{ path: '/known', sourceFile: 'src/app/known/page.tsx', isDynamic: false }]
+		})
+
+		await domain.start()
+		const state = domain.getState()
+		expect(state.links.length).toBeGreaterThan(0)
+		expect(state.diagnostics.length).toBe(1)
+	})
+})