portapack 0.3.1 → 0.3.3

package/docs/contributing.md

@@ -17,10 +17,12 @@ Refer to our detailed [Development Guide](./development.md) for comprehensive se
 ### 🧪 Development Workflow
 
 1. **Fork the Repository**
+
    - Navigate to [PortaPack GitHub Repository](https://github.com/manicinc/portapack)
-   - Click "Fork" 
+   - Click "Fork"
 
 2. **Clone Your Fork**
+
    ```bash
    git clone https://github.com/YOUR_USERNAME/portapack.git
    cd portapack
@@ -38,6 +40,7 @@ Refer to our detailed [Development Guide](./development.md) for comprehensive se
 We use [Conventional Commits](https://www.conventionalcommits.org/) for structured commit messages.
 
 #### Commit Types
+
 - `feat`: New features
 - `fix`: Bug fixes
 - `docs`: Documentation changes
@@ -47,6 +50,7 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) for structur
 - `chore`: Maintenance tasks
 
 #### Commit Command
+
 ```bash
 npm run commit
 ```
@@ -104,4 +108,4 @@ Please review our [Code of Conduct](./code-of-conduct.md) before contributing.
 
 Open source thrives on community contributions. Your effort helps improve PortaPack for everyone! 🎉
 
-**Happy Coding!** 💻✨
+**Happy Coding!** 💻✨

package/docs/deployment.md

@@ -16,10 +16,10 @@ When changes are pushed to master, semantic-release will:
 
 ### Release Types
 
-| Commit Format | Result |
-|--------------|--------|
-| `fix:` | 🔧 PATCH release |
-| `feat:` | ✨ MINOR release |
+| Commit Format                | Result           |
+| ---------------------------- | ---------------- |
+| `fix:`                       | 🔧 PATCH release |
+| `feat:`                      | ✨ MINOR release |
 | `feat:` + `BREAKING CHANGE:` | 🚨 MAJOR release |
 
 ## 📦 Manual Release (Optional Fallback)
@@ -45,6 +45,7 @@ In your GitHub repository:
 2. Add the following secrets:
 
 - `NPM_TOKEN`
+
   - Create at npmjs.com > Access Tokens
   - Choose type: `Automation` (read + publish)
   - Paste into GitHub as `NPM_TOKEN`
@@ -61,6 +62,7 @@ In your GitHub repository:
 ## 🧪 Test Coverage
 
 ### Tools Used
+
 - Jest
 - Coveralls
 
@@ -102,17 +104,20 @@ The project automatically generates a test coverage report and makes it accessib
 ## 🧼 Pre-commit Hooks
 
 We use Husky + `lint-staged`:
+
 - ✅ Auto-lint + format on commit
 - ✅ Validate commit messages via Commitizen
 
 ## 🧯 Troubleshooting
 
 ### Commit Fails?
+
 - Use `npm run commit` (or `git cz`) to follow the correct format
 - Check Husky is installed (`.husky/` exists)
 - Run `npm install` again to restore hooks
 
 ### Release Fails?
+
 - Check GitHub Actions logs
 - Ensure `NPM_TOKEN` secret is added
 - Ensure commit messages follow Conventional Commits
@@ -129,4 +134,4 @@ npm run commit
 feat(fonts): add base64 embedding with MIME detection
 fix(extractor): fallback on missing asset
 chore(ci): enable docs deploy with GitHub Pages
-```
+```

package/docs/development.md

@@ -16,6 +16,7 @@ npm install -g commitizen
 ## 🚀 Getting Started
 
 1. Clone the repository:
+
    ```bash
    git clone https://github.com/manicinc/portapack.git
    cd portapack
@@ -38,17 +39,18 @@ npm run dev
 ```
 
 This command simultaneously runs:
+
 - TypeScript rebuild watcher
 - Documentation server
 - Test runner
 
 ### Specific Development Scripts
 
-| Command | Purpose |
-|---------|---------|
+| Command             | Purpose                      |
+| ------------------- | ---------------------------- |
 | `npm run dev:build` | Watch and rebuild TypeScript |
-| `npm run dev:docs` | Start documentation server |
-| `npm run dev:test` | Run tests in watch mode |
+| `npm run dev:docs`  | Start documentation server   |
+| `npm run dev:test`  | Run tests in watch mode      |
 
 ## 🧪 Testing Strategies
 
@@ -89,6 +91,7 @@ npm run build
 ```
 
 Builds include:
+
 - TypeScript compilation
 - API documentation generation
 - Documentation site build
@@ -165,4 +168,4 @@ portapack/
 
 ## 📄 License
 
-MIT License - Built by Manic Agency
+MIT License - Built by Manic Agency

package/docs/getting-started.md

@@ -36,7 +36,7 @@ import { pack } from 'portapack';
 async function bundleLocalSite() {
   const result = await pack('./index.html');
   console.log(result.html);
-  
+
   // Access metadata about the build
   console.log(`Output size: ${result.metadata.outputSize} bytes`);
   console.log(`Build time: ${result.metadata.buildTimeMs} ms`);
@@ -49,9 +49,9 @@ async function bundleWithOptions() {
     minifyCss: true,
     minifyJs: true,
     baseUrl: 'https://example.com',
-    embedAssets: true
+    embedAssets: true,
   });
- 
+
   // Use or save the bundled HTML
   console.log(result.html);
 }
@@ -59,12 +59,12 @@ async function bundleWithOptions() {
 // Recursive bundling of a website
 async function bundleWebsite() {
   const result = await pack('https://example.com', {
-    recursive: 2,  // Crawl up to 2 levels deep
+    recursive: 2, // Crawl up to 2 levels deep
     minifyHtml: true,
     minifyCss: true,
-    minifyJs: true
+    minifyJs: true,
   });
-  
+
   console.log(`Bundled ${result.metadata.pagesBundled} pages`);
 }
 ```
@@ -77,24 +77,23 @@ For more specific use cases, you can access individual components:
 import {
   generatePortableHTML,
   generateRecursivePortableHTML,
-  bundleMultiPageHTML,
-  fetchAndPackWebPage,
+  bundleMultiPageHTML
 } from 'portapack';
 
 // Bundle a single HTML file or URL
 const singleResult = await generatePortableHTML('./index.html', {
-  minifyHtml: true
+  minifyHtml: true,
 });
 
 // Recursively bundle a site
 const recursiveResult = await generateRecursivePortableHTML('https://example.com', 2, {
-  minifyCss: true
+  minifyCss: true,
 });
 
 // Create multi-page bundle
 const multiPageBundle = await bundleMultiPageHTML([
   { path: '/', html: '<html>...</html>' },
-  { path: '/about', html: '<html>...</html>' }
+  { path: '/about', html: '<html>...</html>' },
 ]);
 ```
 
@@ -117,7 +116,7 @@ For details, see the [CLI Reference](https://manicinc.github.io/portapack/cli).
 
 - 📖 [Explore CLI Options](https://manicinc.github.io/portapack/cli)
 - 🛠 [Advanced Configuration](https://manicinc.github.io/portapack/configuration)
-- 💻 [API Reference](https://manicinc.github.io/portapack/api/)
+- 💻 [API Reference](https://manicinc.github.io/portapack/api/README.html)
 
 ## Troubleshooting
 
@@ -126,6 +125,7 @@ Encountering issues? Check our [Troubleshooting Guide](https://manicinc.github.i
 ## Contributing
 
 Interested in improving PortaPack?
+
 - [View Contributing Guidelines](https://manicinc.github.io/portapack/contributing)
 
 ## Support
@@ -133,4 +133,4 @@ Interested in improving PortaPack?
 - 🐛 [Report an Issue](https://github.com/manicinc/portapack/issues)
 - 💬 [Community Support](https://discord.gg/DzNgXdYm)
 
-Built by [Manic.agency](https://manic.agency)
+Built by [Manic.agency](https://manic.agency)

package/docs/index.md

@@ -37,4 +37,4 @@ features:
     details: MIT licensed, tested, documented, and easy to contribute to.
 
 footer: Built by [Manic.agency](https://manic.agency) — Open Source & Empowering Designers and Developers
----
+---

package/docs/roadmap.md

@@ -0,0 +1,233 @@
+# PortaPack Roadmap
+
+## Version 2: Enhanced Bundling Capabilities
+
+Version 2 focuses on addressing core limitations and expanding compatibility with modern web applications.
+
+### 🎯 Script Execution Enhancement
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| **Script Execution Manager** | Preserve loading order of async/defer scripts | High |
+| **Dependency Analysis** | Detect and maintain script dependencies | High |
+| **Script Initialization Sequencing** | Ensure scripts initialize in the correct order | Medium |
+
+**Implementation:** Add a lightweight runtime script that:
+- Maintains a queue of scripts to execute
+- Respects original async/defer behavior
+- Adds proper event listeners for load/error events
+- Enforces correct execution order
+
+### 🔄 Module Support
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| **ES Module Transformation** | Convert ES modules to browser-compatible format | High |
+| **Import Resolution** | Resolve and inline imported modules | High |
+| **Export Management** | Create namespace for module exports | Medium |
+
+**Implementation:**
+- Parse import statements using an AST parser
+- Resolve modules relative to source files
+- Rewrite as namespaced functions
+- Create a runtime module resolution system
+
+### 📦 Resource Optimization
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| **Bundle Chunking** | Split large bundles into multiple linked files | Medium |
+| **Lazy Loading** | Load assets only when needed | Medium |
+| **Selective Embedding** | Configure thresholds for embedding vs. linking | Low |
+
+**Implementation:**
+- Create a manifest system for chunked resources
+- Add intersection observer for lazy loading
+- Implement size-based decision logic for embedding
+
+### 🖥️ Enhanced SPA Support
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| **Rendered State Capture** | Wait for JavaScript rendering before capture | High |
+| **Route Detection** | Automatically discover SPA routes | Medium |
+| **State Interaction** | Simulate user interactions to capture states | Medium |
+
+**Implementation:**
+- Add configurable wait strategies
+- Implement navigation state detection
+- Create event simulation system
+
+### 🔒 Authentication Support
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| **Authentication Configuration** | Pass credentials to the crawler | High |
+| **Login Sequence** | Define authentication steps | Medium |
+| **Session Management** | Maintain authenticated state during crawling | Medium |
+
+**Implementation:**
+- Add cookie and header configuration options
+- Create login sequence definition format
+- Implement session persistence
+
+### 💼 Developer Experience
+
+| Feature | Description | Priority |
+|---------|-------------|----------|
+| **Enhanced Diagnostics** | Improved logging and error reporting | Medium |
+| **Preview Server** | Built-in server for bundle testing | Medium |
+| **Bundle Analysis** | Visual report of bundle composition | Low |
+
+**Implementation:**
+- Expand logging with visualization options
+- Create lightweight preview server
+- Implement size and composition analyzer
+
+## Version 3: Universal Content Platform
+
+Version 3 transforms PortaPack from a bundling tool into a comprehensive offline content platform.
+
+### 📱 Cross-Platform Applications
+
+| Platform | Key Features |
+|----------|-------------|
+| **Desktop** (macOS, Windows, Linux) | Native app with system integration, background bundling |
+| **Mobile** (iOS, Android) | Touch-optimized interface, efficient storage management |
+| **Browser Extensions** | One-click saving, context menu integration |
+
+**Implementation:**
+- Use Electron for desktop applications
+- React Native for mobile platforms
+- Extension APIs for major browsers
+
+### ☁️ Synchronization System
+
+| Feature | Description |
+|---------|-------------|
+| **Encrypted Sync** | End-to-end encrypted content synchronization |
+| **Delta Updates** | Bandwidth-efficient incremental synchronization |
+| **Reading State Sync** | Preserve reading position across devices |
+| **Selective Sync** | Choose what content syncs to which devices |
+
+**Implementation:**
+- Create secure synchronization protocol
+- Implement conflict resolution system
+- Build metadata synchronization service
+
+### 🧠 Content Intelligence
+
+| Feature | Description |
+|---------|-------------|
+| **Automatic Summarization** | AI-generated summaries of saved content |
+| **Smart Tagging** | Automatic categorization and organization |
+| **Content Relationships** | Identify connections between saved items |
+| **Content Extraction** | Convert complex pages to readable format |
+
+**Implementation:**
+- Integrate NLP models for content understanding
+- Develop concept extraction algorithms
+- Create relationship graph between content
+- Build advanced readability transformations
+
+### 🔍 Advanced Search & Organization
+
+| Feature | Description |
+|---------|-------------|
+| **Full-Text Search** | Search across all content |
+| **Semantic Search** | Find content by meaning, not just keywords |
+| **Smart Collections** | Automatically organize related content |
+| **Timeline Views** | Chronological content organization |
+
+**Implementation:**
+- Build full-text search engine with indexing
+- Implement vector-based semantic search
+- Create automatic collection generation
+- Develop flexible visualization components
+
+### ✏️ Interactive Features
+
+| Feature | Description |
+|---------|-------------|
+| **Annotation System** | Highlights, notes, and comments |
+| **Content Transformations** | Dark mode, font adjustment, text-to-speech |
+| **Social Sharing** | Controlled sharing with privacy options |
+| **Export Capabilities** | Convert to PDF, EPUB, and other formats |
+
+**Implementation:**
+- Create cross-platform annotation framework
+- Build content adaptation engine
+- Implement secure sharing mechanism
+- Develop export converters for multiple formats
+
+### 🔧 Technical Architecture Expansion
+
+| Component | Purpose |
+|-----------|---------|
+| **Sync Service** | Handle cross-device synchronization |
+| **Auth System** | Manage user accounts and security |
+| **Content Processing** | Pipeline for intelligent content handling |
+| **Analytics** | Privacy-focused usage tracking |
+
+**Implementation:**
+- Build scalable backend services
+- Create secure authentication system
+- Develop modular processing pipeline
+- Implement privacy-preserving analytics
+
+### 🧩 Developer Platform
+
+| Feature | Description |
+|---------|-------------|
+| **Plugin System** | Custom processors and content handlers |
+| **API** | Third-party integration capabilities |
+| **Webhooks** | Automation triggers and notifications |
+| **Theme Engine** | Customization of the reading experience |
+
+**Implementation:**
+- Create plugin architecture with sandboxing
+- Develop comprehensive API documentation
+- Implement webhook system with security
+- Build theme and template engine
+
+### 🤖 Machine Learning Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| **Topic Extraction** | Identify main topics in content |
+| **Entity Recognition** | Detect people, places, organizations |
+| **Recommendation Engine** | Suggest related content |
+| **On-Device Processing** | Local ML for privacy and performance |
+
+**Implementation:**
+- Deploy NLP models for content analysis
+- Create entity linking system
+- Develop recommendation algorithms
+- Optimize ML models for on-device usage
+
+## Development Timeline
+
+### Version 2 Milestones
+
+1. **Phase 1:** Script Execution Manager & Module Support
+2. **Phase 2:** Resource Optimization & SPA Support
+3. **Phase 3** Authentication Support & Developer Experience 
+4. **Phase 4** Stabilization & Release
+
+### Version 3 Phased Approach
+
+1. **Foundation Phase:**
+   - Cross-platform application architecture
+   - Core synchronization system
+   - Basic content intelligence
+
+2. **Expansion Phase:**
+   - Advanced search and organization
+   - Interactive features
+   - Developer platform beta
+
+3. **Intelligence Phase:**
+   - Full machine learning capabilities
+   - Recommendation engine
+   - Advanced content relationships
+

package/docs/site.webmanifest

@@ -0,0 +1 @@
+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}

package/docs/troubleshooting.md

@@ -5,8 +5,10 @@
 ### 1. Installation Problems
 
 #### npm Install Fails
+
 - **Symptom**: Error during `npm install`
 - **Solutions**:
+
   ```bash
   # Clear npm cache
   npm cache clean --force
@@ -19,8 +21,10 @@
 ### 2. CLI Errors
 
 #### Permission Denied
+
 - **Symptom**: `EACCES` errors
 - **Solutions**:
+
   ```bash
   # Use npm with sudo (not recommended long-term)
   sudo npm install -g portapack
@@ -31,6 +35,7 @@
   ```
 
 #### Asset Embedding Failures
+
 - **Symptom**: Some assets not embedded
 - **Possible Causes**:
   - Incorrect base URL
@@ -40,6 +45,7 @@
 ### 3. Performance Issues
 
 #### Slow Recursive Crawling
+
 - **Solution**: Limit crawl depth
   ```bash
   portapack -i https://site.com --recursive --max-depth 2
@@ -48,6 +54,7 @@
 ### 4. Minification Problems
 
 #### CSS/JS Not Minifying
+
 - **Check**:
   - Use `--no-minify-css` or `--no-minify-js` flags
   - Verify asset paths
@@ -56,12 +63,14 @@
 ## 🔍 Debugging Techniques
 
 ### Verbose Logging
+
 ```bash
 # Enable verbose output
 portapack -i ./site --verbose
 ```
 
 ### Dry Run
+
 ```bash
 # Preview bundling without generating file
 portapack -i ./site --dry-run
@@ -70,6 +79,7 @@ portapack -i ./site --dry-run
 ## 🌐 Network & Security
 
 ### Proxy Configuration
+
 ```bash
 # Set proxy for asset fetching
 export HTTP_PROXY=http://proxy.example.com
@@ -79,6 +89,7 @@ portapack -i https://site.com
 ## 📊 Diagnostics
 
 ### Generate Diagnostic Report
+
 ```bash
 # Create debug information
 portapack --diagnostics > portapack-debug.log
@@ -104,4 +115,4 @@ portapack --diagnostics > portapack-debug.log
 
 - Limited support for complex Single Page Applications (SPAs)
 - Some dynamic content may not embed correctly
-- Large sites might require significant memory
+- Large sites might require significant memory

package/examples/main.ts

@@ -13,7 +13,6 @@ import {
   generatePortableHTML,
   bundleMultiPageHTML,
   generateRecursivePortableHTML,
-  fetchAndPackWebPage
 } from '../src/index'; // 🔧 use '../src/index' for dev, '../dist/index' for built
 
 const TEMP_DIR = path.join(os.tmpdir(), 'portapack-example');
@@ -40,10 +39,7 @@ function logMetadata(meta: any, filePath: string) {
 }
 
 // Accepts a function that returns { html, metadata }
-async function timedBundle(
-  name: string,
-  task: () => Promise<{ html: string; metadata: any }>
-) {
+async function timedBundle(name: string, task: () => Promise<{ html: string; metadata: any }>) {
   const start = Date.now();
   console.log(chalk.cyanBright(`\n⏳ ${name}`));
 
@@ -66,26 +62,15 @@ async function timedBundle(
       embedAssets: true,
       minifyHtml: true,
       minifyCss: true,
-      minifyJs: true
+      minifyJs: true,
     })
   );
 
-  // 🔹 Fetch and display raw HTML from remote site (no metadata)
-  console.log(chalk.cyan('\n⏳ Fetch and Pack Web Page (raw)'));
-  try {
-    const { html, metadata } = await fetchAndPackWebPage('https://getbootstrap.com');
-    const filePath = await writeTempFile('fetched-page.html', html);
-    console.log(chalk.green('✅ Saved fetched HTML:'), `file://${filePath}`);
-    console.log(`📦 Size: ${(metadata.outputSize / 1024).toFixed(2)} KB`);
-  } catch (err) {
-    console.error(chalk.red('❌ Failed to fetch web page:'), err);
-  }
-
   // 🔹 Multi-page manual bundle
   await timedBundle('Multi-Page Site Bundling', async () => {
     const pages = [
       { url: 'https://example.com', html: '<html><body>Page 1</body></html>' },
-      { url: 'https://example.com/about', html: '<html><body>Page 2</body></html>' }
+      { url: 'https://example.com/about', html: '<html><body>Page 2</body></html>' },
     ];
     const html = bundleMultiPageHTML(pages);
     return {
@@ -94,8 +79,8 @@ async function timedBundle(
         input: 'manual pages',
         pagesBundled: pages.length,
         outputSize: html.length,
-        buildTimeMs: 0
-      }
+        buildTimeMs: 0,
+      },
     };
   });
 
@@ -104,15 +89,5 @@ async function timedBundle(
     generateRecursivePortableHTML('https://getbootstrap.com', 2)
   );
 
-  // 🔹 Broken page test
-  console.log(chalk.cyan('\n⏳ Broken Page Test'));
-  try {
-    const { html, metadata} = await fetchAndPackWebPage('https://example.com/404');
-    const brokenOut = await writeTempFile('broken-page.html', html);
-    console.log(chalk.yellow('⚠️ Page returned something, saved to:'), `file://${brokenOut}`);
-  } catch {
-    console.log(chalk.red('🚫 Could not fetch broken page as expected.'));
-  }
-
   console.log(chalk.gray(`\n📁 Output directory: ${TEMP_DIR}\n`));
 })();

package/examples/sample-project/script.js

@@ -1 +1 @@
-console.log('hello');
+console.log('hello');