to_implement.md

To Implement

1. Core Runtime Robustness

Safe execution abstraction

• Introduce safeRun helper for sync/async fallbacks
  • What: Centralize repetitive try/catch guard patterns.
  • Why: Reduce duplication and keep behavior consistent.
  • How: Add src/core/safeRun.ts and replace repeated guarded blocks.

Remove remaining lint warnings

• Remove non-null assertion in src/core/eventBus.ts
  • What: Eliminate set! usage in unsubscribe path.
  • Why: Keep lint output clean and improve safety.
  • How: Capture stable local reference and guard before delete.
• Replace new Array(capacity) in ring buffer
  • What: Avoid lint warning in src/domains/performance/logger.ts.
  • Why: Keep quality gate warning-free.
  • How: Use Array.from({ length: capacity }) or equivalent typed init.

2. Feature Completeness

Routes domain implementation

• Implement actual route discovery pipeline
  • What: Populate RoutesState.routes from project/app sources.
  • Why: Current routes tab is mostly placeholder.
  • How: Add discovery adapter(s), call parseRoutes, handle errors/loading states.

Links domain implementation

• Implement link extraction + validation integration
  • What: Populate LinksState.links and diagnostics.
  • Why: Current links tab is mostly placeholder.
  • How: Extract links from source, validate via validateLinks, publish results.

AI provider wiring

• Wire props.providers?.ai into bootstrap/runtime
  • What: Use configured AI provider in perf analysis.
  • Why: Current bootstrap sets aiProvider to undefined.
  • How: Add provider factory + adapter resolution and inject into createPerfDomain.

Persistence path for perf logs

• Implement persistence in Next route handler
  • What: createLogHandler should store events, not only count them.
  • Why: Needed for historical analysis and external integrations.
  • How: Add storage abstraction and write path with validation + failure handling.

3. UI/UX Completeness

Right rail panel content integration

• Render actual right-rail content in Shell
  • What: Pass children renderer into RightRail.
  • Why: Current rail largely acts as icon strip without contextual content.
  • How: Map panel id -> panel presenter and render domain-specific side content.

Theme and system mode behavior

• Review system theme resolution behavior
  • What: Verify dark/light system mapping semantics.
  • Why: Current logic defaults system to dark in shell token resolution.
  • How: Resolve via media query source of truth and keep tokens synchronized.

4. API and Package Design

Public API narrowing

• Move internal-heavy exports to dedicated advanced subpath
  • What: Keep root export focused on stable public contract.
  • Why: Better semver safety and lower cognitive load.
  • How: Introduce @remcostoeten/dev-widget/internal and migrate internal type exports.

Dist artifact polish

• Add declaration map/source map distribution policy
  • What: Decide whether to ship .d.ts.map and source maps.
  • Why: Better go-to-definition/debugging in consumer editors.
  • How: Configure tsup/tsconfig emit and include required files in package.

5. Testing and CI

Increase effective test coverage

• Add lifecycle tests for runtime and domains
  • What: Test start/stop, event publishing, and reset flows.
  • Why: Current coverage is low and misses critical behavior.
  • How: Add focused Bun tests alongside domain/runtime modules.

Add contract tests for adapters and providers

• Test better-auth/cookie/jwt providers and next/tauri adapters
  • What: Validate environment-conditional and edge-case behavior.
  • Why: Adapter/provider behavior drives integration reliability.
  • How: Mock browser/server globals and assert typed outputs/fail paths.

Release automation hardening

• Add CI step for npm artifact validation
  • What: Validate npm pack --dry-run in CI before release publish.
  • Why: Prevent accidental bad tarball release.
  • How: Add dedicated job/check in .github/workflows/ci.yml and release workflow.