# Vellum Development Roadmap

This roadmap outlines the next steps for improving Vellum based on feedback and responses. Tasks are prioritized (High, Medium, Low) to focus on critical enhancements first, ensuring a robust, flexible, and developer-friendly tool.

## 1. Enhance Documentation
- **Priority**: High
- **Details**:
  - Add comprehensive JSDoc comments to all public methods, classes, and utilities in `src/`.
  - Document the expected structure of a mod’s `init` function (parameters, return values).
  - Detail the toolkit’s API for dispatching actions and binding to classes.
  - Create a README or API guide covering:
    - How to create and structure mods.
    - How to interact with the action system.
    - How to customize renderers and handle content types.
    - Best practices for dependency management and priority settings.
- **Outcome**: Improved onboarding for developers and contributors.

## 2. Improve Type Safety with JSDoc
- **Priority**: Medium
- **Details**:
  - Enhance JSDoc annotations with type hints for function parameters, return types, and object shapes.
  - Focus on critical areas: action details, mod metadata, renderer functions.
  - Ensure all public APIs are fully annotated for IDE support.
- **Outcome**: Reduced runtime errors and better code clarity without TypeScript.

## 3. Optimize Mod Loading for Performance
- **Priority**: Medium
- **Details**:
  - Implement batching or lazy loading for mods to manage resource use in large applications.
  - Add a configuration option to limit concurrent mod loads.
  - Explore lazy loading based on user interactions or viewport visibility.
- **Outcome**: Faster initial load times and scalability for large mod sets.

## 4. Add Optional Security Features for Mod Sources
- **Priority**: Medium
- **Details**:
  - Introduce an optional whitelist for trusted mod sources, configurable by consumers.
  - Document how to implement and use the whitelist.
  - Provide guidelines for securing mod URLs and mitigating dynamic import risks.
- **Outcome**: Enhanced security for applications needing strict source control.

## 5. Expand Test Coverage for Edge Cases
- **Priority**: High
- **Details**:
  - Add tests for these edge cases:
    - Circular dependencies in `sortMods` (verify fallback behavior).
    - Failed dynamic mod additions in `handleModMutations` (test error handling).
    - Renderer failures in `update` (ensure graceful degradation).
    - Mod unloading (confirm resource cleanup).
    - Action type collisions (validate system robustness).
- **Outcome**: Greater reliability across diverse scenarios.

## 6. Explore Enhancements to the Action System
- **Priority**: Low
- **Details**:
  - Investigate ways to prevent action type collisions in large applications.
  - Consider optional namespacing (e.g., `<modName>:<action>`) or a registry for uniqueness.
  - Document best practices for action naming to minimize conflicts.
- **Outcome**: A scalable action system for complex use cases.

## 7. Develop Renderer Plugins for Popular Frameworks
- **Priority**: Medium
- **Details**:
  - Create npm-hosted renderer plugins:
    - `@thefarce/vellum.renderers.react.v18` (React v18)
    - `@thefarce/vellum.renderers.vue.v3` (Vue v3)
    - `@thefarce/vellum.renderers.svelte.v4` (Svelte v4)
    - `@thefarce/vellum.renderers.lit.v2` (Lit v2)
  - Document each plugin with integration examples.
- **Outcome**: Easier integration with popular frameworks, boosting adoption.

## 8. Document Styling Options for Shadow DOM
- **Priority**: Low
- **Details**:
  - Document how to style within Vellum’s shadow DOM using CSS parts or variables.
  - Consider an option to disable shadow DOM for alternative styling approaches.
- **Outcome**: Improved consumer flexibility for styling without core changes.

## 9. Implement Mod Unloading
- **Priority**: Medium
- **Details**:
  - Add an `'action:unload'` handler for dynamic mod removal.
  - Implement cleanup in `disconnectedCallback` or `executeMods` to free resources.
  - Ensure unloaded mods are removed from the action registry and internal state.
- **Outcome**: Prevention of resource leaks in dynamic applications.

## 10. Namespace Vellum Events
- **Priority**: High
- **Details**:
  - Prefix all events with `vellum:` (e.g., `'vellum:mod-loaded'`, `'vellum:mod-load-failed'`).
  - Update event dispatches across the codebase.
  - Document new event names in the API guide.
- **Outcome**: Reduced risk of event conflicts in larger systems.

---

## Next Steps
- **Immediate Focus**: High-priority tasks (Documentation, Testing Coverage, Event Naming) for quick wins in reliability and usability.
- **Next Version**: Medium-priority tasks (Performance, Security, Renderer Plugins, Mod Unloading, Type Safety) for significant enhancements.
- **Future Consideration**: Low-priority tasks (Action System, Shadow DOM) for refinement as needed.

This roadmap ensures Vellum evolves into a top-tier tool for modular web applications. Let me know if you’d like to tweak priorities or details!