Skip to content

plan.md

Latest commit

 

History

History
87 lines (73 loc) · 4.11 KB

plan.md

File metadata and controls

87 lines (73 loc) · 4.11 KB

HTML Package Bundle - Implementation Plan

Project Overview

Create a self-modifying single-file HTML application that bundles JavaScript package files (package.json, source files, etc.) into one HTML file. The app should work offline, provide editing capabilities, and be able to load a development environment using WebContainer.io.

Implementation Phases

Phase 1: Basic Structure & Environment Detection ✅

  1. Create the base HTML structure with appropriate sections for: ✅
    • Runtime application code (top) ✅
    • Source code bundle (bottom, loaded on-demand) ✅
  2. Implement environment detection to handle: ✅
    • file:// protocol (works offline with limitations) ✅
    • localhost (for development) ✅
    • https:// (for hosted version) ✅
  3. Create appropriate UI elements based on detected environment ✅

Phase 2: Self-Modification System ✅

  1. Implement File System Access API integration ✅
    • Select and validate file handle ✅
    • Persist file handle in IndexedDB ✅
    • Add permissions management ✅
  2. Create a mechanism to modify and save the HTML file ✅
  3. Implement fallback download mechanism for browsers without FS Access API ✅

Phase 3: Source Code Management ✅

  1. Create JSON structure to store source files within the HTML ✅
  2. Build editor interface (using CodeMirror) ✅
  3. Implement file navigation and editing capabilities ✅
  4. Add versioning and change tracking system (partial) 🔄

Phase 4: WebContainer Integration ✅

  1. Add WebContainer.io initialization (lazy-loaded) ✅
  2. Create virtual filesystem from embedded source files ✅
  3. Implement pnpm dependency installation ✅
    • Use pnpm instead of npm/yarn for better WebContainer compatibility ✅
    • Set up caching strategy for efficient package management ✅
  4. Add terminal/console for command execution ✅
  5. Create preview system for running the application ✅

Phase 5: Export & Integration 🔄

  1. Add ability to export as ZIP package 🔄
  2. Implement optional Git integration ⏳
  3. Create bi-directional sync between editor and WebContainer 🔄
  4. Add build system to update runtime code from source 🔄

Phase 6: Optimization & Polish ⏳

  1. Optimize load performance (lazy-loading, conditional execution) 🔄
  2. Improve caching strategies for dependencies ⏳
  3. Add helpful documentation and examples 🔄
  4. Polish UI/UX for different devices and environments ⏳

Current Implementation Status

Completed Components

  • Environment Detector: Full implementation of protocol detection and feature availability
  • File System Manager: Complete implementation with IndexedDB persistence and fallback mechanisms
  • Source Bundle Manager: Core functionality for storing and managing embedded files
  • Editor Manager: Complete integration with CodeMirror for syntax highlighting and editing
  • WebContainer Manager: Full implementation of in-browser Node.js environment

In Progress

  • Versioning System: Basic tracking of file changes, needs enhanced diffing and history
  • Build Integration: Work-in-progress system to rebuild runtime code from source
  • Export Systems: Basic ZIP export capability being implemented

Architecture

The project follows a modular architecture with clear separation of concerns:

  • Each component is implemented as a manager class with well-defined responsibilities
  • Data flow is managed through events and callbacks
  • Configuration options are centralized for easy customization
  • Error handling is implemented across different environments

Technical Considerations

  • Use ESM modules for better code organization
  • Use pnpm for package management (better compatibility with WebContainer)
  • Implement careful error handling for different environments
  • Balance file size and functionality
  • Ensure proper sandboxing for security
  • Handle browser compatibility challenges

Next Steps

  1. Complete the bi-directional sync between editor and WebContainer
  2. Finalize the build system for runtime code updates
  3. Complete ZIP export functionality
  4. Enhance documentation with examples and tutorials
  5. Implement performance optimizations for large projects