ROADMAP.md at main · desertthunder.dev/voltx

desertthunder.dev / voltx
a reactive (signals based) hypermedia web framework (wip) stormlightlabs.github.io/volt/
hypermedia frontend signals
voltx / ROADMAP.md
at main 17 kB view raw view rendered
  1# Roadmap
  2
  3- [Completed](#completed)
  4- [TODO](#to-do)
  5    - [Parking Lot](#parking-lot)
  6
  7| Version | State | Milestone                                                                        |
  8| ------- | ----- | -------------------------------------------------------------------------------- |
  9|         |   ✓   | [Foundations](#foundations)                                                      |
 10|         |   ✓   | [Reactivity & Bindings](#reactivity--bindings)                                   |
 11|         |   ✓   | [Actions & Effects](#actions--effects)                                           |
 12|         |   ✓   | [Plugins Framework](#plugins-framework)                                          |
 13|         |   ✓   | [Backend Integration & HTTP Actions](#backend-integration--http-actions)         |
 14|         |   ✓   | [Proxy-Based Reactivity Enhancements](#proxy-based-reactivity-enhancements)      |
 15| v0.1.0  |   ✓   | [Markup Based Reactivity](#markup-based-reactivity)                              |
 16| v0.2.0  |   ✓   | [Reactive Attributes & Event Modifiers](#reactive-attributes--event-modifiers)   |
 17| v0.3.0  |   ✓   | [Global State](#global-state)                                                    |
 18| v0.4.0  |   ✓   | [Animation & Transitions](#animation--transitions)                               |
 19| v0.5.0  |   ✓   | [Navigation & History API Routing](#navigation--history-api-routing)             |
 20|         |   ✓   | [Refactor](#evaluator--binder-hardening)                                         |
 21| v0.5.1  |   ✓   | [Error Handling & Diagnostics](#error-handling--diagnostics) (partial)           |
 22| v0.6.0  |       | [Error Handling & Diagnostics](#error-handling--diagnostics)                     |
 23| v0.6.0  |       | [Bundle Size Optimization](#bundle-size-optimization)                            |
 24| v0.6.0  |       | [IIFE Build Support](#iife-build-support)                                        |
 25| v0.7.0  |       | [Testing & Benchmarking](#testing--benchmarking)                                 |
 26| v0.7.0  |       | [CSP Compatibility](#csp-compatibility)                                          |
 27| v0.8.0  |       | [DOM Morphing & Streaming](#dom-morphing--streaming)                             |
 28| v0.9.0  |       | [Scope Inheritance & State Management](#scope-inheritance--state-management)     |
 29| v0.10.0 |       | [Background Requests & Reactive Polling](#background-requests--reactive-polling) |
 30| v0.11.0 |       | [Attribute Prefix Support](#attribute-prefix-support)                            |
 31| v0.12.0 |       | [Persistence & Offline](#persistence--offline) (advanced features)               |
 32| v0.13.0 |       | [Inspector & Developer Tools](#inspector--developer-tools)                       |
 33| v1.0.0  |       | [Stable Release](#stable-release)                                                |
 34
 35## Completed
 36
 37_NOTE_: `data-x-*` is now `data-volt-*`
 38
 39### Foundations
 40
 41**Goal:** Establish project structure, tooling, and base reactivity primitives.
 42**Outcome:** A bootable TypeScript project with working reactivity primitives and test coverage.
 43**Summary:** A TypeScript project scaffold with implemented signal() (subscribe/set/get) and foundational reactivity tests establishes the base system.
 44
 45### Reactivity & Bindings
 46
 47**Goal:** Connect signals to DOM via declarative `data-x-*` bindings.
 48**Outcome:** Reactive text/attribute binding with signals → DOM synchronization.
 49**Summary:** Reactive DOM bindings (`data-x-text`, `data-x-html`, `data-x-class`) with a safe expression evaluator, mutation batching, and DOM testing ensure synchronized updates between signals and UI.
 50
 51### Actions & Effects
 52
 53**Goal:** Add event-driven behavior and derived reactivity.
 54**Outcome:** Fully functional reactive UI layer with event bindings and computed updates.
 55**Summary:** An event binding system with `$el`, `$event`, and derived signals (computed, effect, async effects) delivers a complete reactive event-driven UI layer.
 56
 57### Plugins Framework
 58
 59**Goal:** Build a modular plugin architecture with dynamic registration.
 60**Outcome:** Stable plugin API enabling community-driven extensions.
 61**Summary:** A modular plugin API with lifecycle hooks and built-in extensions (persist, scroll, url) enables dynamic feature registration and community contributions.
 62
 63### Backend Integration & HTTP Actions
 64
 65**Goal:** Provide backend integration with declarative HTTP requests and responses.
 66**Outcome:** VoltX.js can make backend requests and update the DOM
 67**Summary:** Declarative HTTP directives (data-volt-get|post|put|patch|delete) with swap strategies, loading indicators, error handling, and form serialization integrate VoltX.js seamlessly with backend APIs.
 68
 69### Markup Based Reactivity
 70
 71**Goal:** Allow Volt apps to declare state, bindings, and behavior entirely in HTML markup
 72**Outcome:** Authors can ship examples without companion JavaScript bundles
 73**Summary:** Declarative HTML state, binding, control-flow, and event directives with SSR support and a sandboxed evaluator enable Volt apps to run without separate JavaScript bundles.
 74
 75### Proxy-Based Reactivity Enhancements
 76
 77**Goal:** Use JavaScript Proxies to improve reactivity ergonomics and automatic dependency tracking.
 78**Outcome:** More intuitive API with automatic dependency tracking and optional deep reactivity for objects/arrays.
 79**Summary:** Proxy-driven automatic dependency tracking, deep reactive() objects, reactive arrays, lazy signal creation, and debugging utilities improve reactivity ergonomics and performance.
 80
 81### Reactive Attributes & Event Modifiers
 82
 83**Goal:** Extend VoltX.js with expressive attribute patterns and event options for fine-grained control.
 84**Outcome:** VoltX.js supports rich declarative behaviors and event semantics built entirely on standard DOM APIs.
 85**Summary:** Introduced expressive attribute patterns and event modifiers for precise DOM and input control, for fine-grained declarative behavior entirely through standard DOM APIs.
 86
 87### Global State
 88
 89**Goal:** Implement store/context pattern
 90**Outcome:** VoltX.js provides intuitive global state management
 91**Summary:** The scope injects helpers like `$origin`, `$scope`, `$pulse`, `$store`, `$uid`, `$probe`, `$pins`, and `$arc`, giving templates access to global state, microtask scheduling, deterministic IDs, element refs, and custom event dispatch without leaving declarative markup.
 92
 93### Animation & Transitions
 94
 95**Goal:** Add animation primitives for smooth UI transitions with Alpine/Datastar parity.
 96**Outcome:** VoltX.js enables declarative animations and view transitions alongside reactivity.
 97**Summary:** The surge directive ships fade/slide/scale/blur presets with duration and delay overrides, per-phase enter/leave control, and easing helpers, while the shift plugin applies reusable keyframe animations—both composable with `data-volt-if`/`data-volt-show` as showcased in the animations demo.
 98
 99### Navigation & History API Routing
100
101**Goal:** Provide seamless client-side navigation with a first-class History API router.
102**Outcome:** VoltX.js delivers accessible, stateful navigation with clean URLs and signal-driven routing.
103**Summary:** Added seamless client-side navigation through a History API–powered router, enabling declarative routing with `data-volt-navigate` and `data-volt-url`, reactive URL synchronization, smooth transitions, scroll and focus restoration, dynamic route parsing, and full integration with signals and the View Transition API for accessible, stateful navigation and clean URLs.
104
105## To-Do
106
107**Focus:** Versions v0.5.5 through v0.9.x prioritize core framework capabilities and performance:
108
109- Bundle size reduction to <15KB gzipped (currently 19KB)
110- CSP compatibility (removing Function constructor dependency)
111- DOM morphing and SSE streaming support
112- Optional scope inheritance for improved ergonomics
113
114These milestones strengthen VoltX.js as a signals-based reactive framework with declarative-first design.
115
116### Error Handling & Diagnostics
117
118**Goal**: Provide clear, actionable feedback when runtime or directive errors occur.
119**Outcome**: VoltX.js surfaces developer-friendly diagnostics for expression evaluation,
120directive parsing, and network operations, making it easier to debug apps without opaque stack traces.
121**Deliverables**:
122    - ✓ v0.5.1: Centralized error boundary system for directives and effects
123    - ✓ v0.5.1: Sandbox error wrapping with contextual hints (directive name, expression, element)
124    - ✓ v0.5.1: `$volt.report(error, context)` API for plugin and app-level reporting
125    - ✓ v0.6.0: Enhanced console error messages with directive context
126    - ✓ v0.6.0: Differentiated error levels: warn, error, fatal
127    - ✓ v0.6.0: Documentation: "Understanding VoltX Errors" guide
128    - v0.6.0: Add error handling examples to demo
129    - v0.13.0: Visual in-DOM error overlays for development mode
130    - v0.13.0: Runtime health monitor tracking failures
131    - v0.13.0: Configurable global error policy
132
133### Persistence & Offline
134
135**Goal:** Introduce persistent storage and offline-first behaviors.
136**Outcome:** Resilient state persistence and offline replay built into VoltX.js.
137**Deliverables:**
138    - ✓ Persistent signals (localStorage, sessionStorage, indexedDb)
139    - ✓ Storage plugin (`data-volt-persist`)
140    - v0.12.0: Storage modifiers on signals (`.local`, `.session`, `.ifmissing`)
141    - v0.12.0: Sync strategy API (merge, overwrite, patch) for conflict resolution
142    - v0.12.0: Cache invalidation strategies
143    - v0.12.0: Offline queue for deferred stream events and HTTP requests
144    - v0.12.0: Service Worker integration for offline-first apps
145    - v0.12.0: Background sync for deferred requests
146    - v0.12.0: Cross-tab synchronization via `BroadcastChannel`
147
148### Bundle Size Optimization
149
150**Goal:** Reduce bundle size to <15KB gzipped while maintaining full feature set.
151**Outcome:** Lightweight runtime footprint with comprehensive declarative capabilities.
152**Deliverables:**
153    - v0.6.0: Audit and tree-shake unused code paths
154    - v0.6.0: Optimize evaluator and binder implementations
155    - v0.6.0: Minimize plugin footprint, ensure lazy loading
156    - v0.6.0: Refactor expression compiler for smaller output
157    - v0.6.0: Compress constant strings and reduce runtime helpers
158    - v0.6.0: Optimize signal subscription management
159    - v0.6.0: Production mode stripping (remove dev-only error messages)
160    - v0.6.0: Aggressive minification pipeline tuning
161    - v0.6.0: Target: <15KB gzipped sustained
162
163### IIFE Build Support
164
165**Goal:** Provide an IIFE build target for VoltX.js to support direct `<script>` tag usage without module systems.
166**Outcome:** VoltX.js can be used via CDN without build tools or module bundlers.
167**Deliverables:**
168    - v0.6.0: IIFE build output (voltx.iife.js) alongside ESM build
169    - v0.6.0: Global `Volt` namespace for browser environments
170    - v0.6.0: CDN-friendly distribution (unpkg, jsdelivr)
171    - v0.6.0: Update build pipeline to generate IIFE bundle
172    - v0.6.0: Document usage: `<script src="voltx.iife.min.js"></script>`
173    - v0.6.0: Ensure plugins work with IIFE build
174    - v0.6.0: Add IIFE examples to documentation
175
176### Testing & Benchmarking
177
178**Goal:** Establish comprehensive testing infrastructure and performance benchmarking.
179**Outcome:** VoltX.js has rigorous end-to-end testing and quantifiable performance metrics against competing frameworks.
180**Deliverables:**
181    - v0.7.0: Playwright-based integration test suite for real browser testing
182    - v0.7.0: End-to-end tests for all core directives and plugins
183    - v0.7.0: Cross-browser compatibility tests (Chrome, Firefox, Safari)
184    - v0.7.0: Memory usage and leak detection benchmarks
185    - v0.7.0: Bundle size tracking and regression detection
186    - v0.7.0: Reactivity performance benchmarks (signal updates, computed chains, effect execution)
187    - v0.7.0: DOM update performance benchmarks
188    - v0.7.0: CI integration for automated benchmark runs and regression alerts
189
190### CSP Compatibility
191
192**Goal:** Make VoltX.js Content Security Policy compliant without 'unsafe-eval'.
193**Outcome:** VoltX.js can run in strict CSP environments (no Function constructor).
194**Deliverables:**
195    - v0.7.0: Research and design CSP-safe evaluator architecture
196    - v0.7.0: Evaluate trade-offs: AST interpreter vs limited expression subset
197    - v0.7.0: Implement CSP-safe expression evaluator (AST-based or restricted syntax)
198    - v0.7.0: Maintain expression feature parity where possible
199    - v0.7.0: Fallback mode detection for environments requiring CSP
200    - v0.7.0: Full test coverage for CSP mode
201    - v0.7.0: Documentation on CSP limitations and alternatives
202    - v0.7.0: Bundle split: standard build vs CSP build
203
204### DOM Morphing & Streaming
205
206**Goal:** Add intelligent DOM morphing and Server-Sent Events for real-time updates.
207**Outcome:** Built-in morphing and SSE streaming for seamless server-driven UI updates.
208**Deliverables:**
209    - v0.8.0: Integrate Idiomorph or implement lightweight morphing algorithm
210    - v0.8.0: `data-volt-morph` attribute for morphing-based swaps
211    - v0.8.0: Preserve focus, scroll, and input state during morphs
212    - v0.8.0: Server-Sent Events (SSE) integration
213    - v0.8.0: `data-volt-stream` attribute for SSE endpoints
214    - v0.8.0: Automatic reconnection with exponential backoff
215    - v0.8.0: Signal patching from backend SSE events
216    - v0.8.0: JSON Patch support for partial updates
217    - v0.8.0: `data-volt-ignore-morph` for selective exclusion
218    - v0.8.0: WebSocket as alternative to SSE
219    - v0.8.0: Unified streaming API across SSE/WebSocket
220
221### Scope Inheritance & State Management
222
223**Goal:** Improve data scoping with optional inheritance for ergonomic nested components.
224**Outcome:** Flexible scoping patterns for complex component hierarchies.
225**Deliverables:**
226    - v0.9.0: Optional scope inheritance via `data-volt-scope="inherit"`
227    - v0.9.0: Child scopes inherit parent signals with override capability
228    - v0.9.0: $parent accessor for explicit parent scope access
229    - v0.9.0: Scoped context providers for dependency injection
230    - v0.9.0: Enhanced $store with namespacing and modules
231    - v0.9.0: Cross-scope signal sharing patterns
232
233### Background Requests & Reactive Polling
234
235**Goal:** Enable declarative background data fetching and periodic updates.
236**Outcome:** VoltX.js elements can fetch or refresh data automatically based on time, visibility, or reactive conditions.
237**Deliverables:**
238    - v0.10.0: `data-volt-visible` for fetching when element enters viewport (IntersectionObserver)
239    - v0.10.0: `data-volt-poll` attribute for periodic background requests
240    - v0.10.0: Configurable intervals, delays, and signal-based triggers
241    - v0.10.0: Automatic cancellation when elements unmount
242    - v0.10.0: Conditional polling tied to reactive signals
243    - v0.10.0: Background task scheduler with priority management
244
245### Attribute Prefix Support
246
247**Goal:** Support multiple attribute prefix options for developer preference.
248**Outcome:** VoltX.js supports `voltx-`, `vx-`, and `data-volt-` prefixes.
249**Deliverables:**
250    - v0.11.0: Add support for `voltx-*` and `vx-*` attribute prefixes
251    - v0.11.0: Recommend `vx-*` as primary in documentation
252    - v0.11.0: Maintain backward compatibility with `data-volt-*`
253    - v0.11.0: Update demo to use recommended prefix
254
255### Inspector & Developer Tools
256
257**Goal:** Improve developer experience and runtime introspection.
258**Outcome:** First-class developer ergonomics; VoltX.js is enjoyable to debug and extend.
259**Deliverables:**
260    - v0.13.0: Visual in-DOM error overlays for development mode
261    - v0.13.0: Runtime health monitor tracking failures
262    - v0.13.0: Configurable global error policy (silent, overlay, throw)
263    - v0.13.0: Developer overlay for inspecting signals, subscriptions, and effects
264    - v0.13.0: Time-travel debugging for signal history
265    - v0.13.0: Signal dependency graph visualization
266    - v0.13.0: Performance profiling tools
267    - v0.13.0: Browser console integration (`window.$volt.inspect()`)
268    - v0.13.0: Dev logging toggle (`Volt.debug = true`)
269    - v0.13.0: Request/response debugging (HTTP actions, SSE streams)
270    - v0.13.0: Browser DevTools extension with full integration
271
272### Stable Release
273
274**Goal:** Prepare & ship the stable release
275**Outcome:** VoltX.js 1.0 is stable, documented, performant, and ready for production.
276**Deliverables:**
277    - ✓ Documentation site (VitePress)
278    - Full API reference with examples
279    - Create generator in `@voltx/cli` package
280    - Finalized plugin registry and CLI (`volt plugins list/init`)
281    - Versioned documentation (<https://stormlightlabs.github.io/volt>)
282    - Announcement post and release notes
283    - Community contribution guide & governance doc
284
285## Parking Lot
286
287### Evaluator & Binder Hardening
288
289All expression evaluation now flows through a cached `new Function` compiler guarded by a hardened scope proxy, with the binder slimmed into a directive registry so plugins self-register while tests verify the sandboxed error surfaces.