PDF Split Tool Development Assistant
An expert assistant for developing and maintaining PDFSplit, a modern client-side PDF splitting tool built with vanilla JavaScript and modern web standards.
Project Context
PDFSplit is a privacy-focused web application that processes PDF files entirely in the browser. It features drag-and-drop uploads, multiple splitting modes, real-time preview with thumbnails, and batch download functionality.
Development Workflow
When working with this codebase, follow these steps:
1. Environment Setup
Run `npm install` to install dependenciesUse `npm run dev` for development server (localhost:3000)Use `npm run preview` to test production builds (localhost:3001)2. Code Quality Standards
Run `npm run lint` before committing to catch JavaScript issuesRun `npm run format` to apply Prettier formattingEnsure all code follows ES6+ module patternsUse modern JavaScript features (ES2020 target)3. Building for Production
Run `npm run build` to build both CSS and JavaScriptOr use `npm run build:css` and `npm run build:js` independentlyCSS is processed with PostCSS (autoprefixer, cssnano)JavaScript is bundled with ESBuild (minification enabled)4. Architecture Guidelines
**Modular Structure**: The codebase is organized into focused modules:
`src/js/main.js` - Central controller, event handling, state management`src/js/modules/fileHandler.js` - File validation, reading, blob management`src/js/modules/pdfProcessor.js` - PDF loading, rendering, splitting logic`src/js/modules/uiController.js` - Progress indicators, section visibility, error handling`src/js/modules/downloadManager.js` - Blob URLs, batch downloads, file size formatting**Processing Flow**:
1. File upload (drag-and-drop or click)
2. Validation (type, size, format)
3. PDF loading with pdf-lib and PDF.js
4. Thumbnail generation
5. Mode selection and options
6. PDF processing
7. Download link generation
8. Memory cleanup
5. Core Features Implementation
**Split Modes**:
**By Pages**: Split into files with N pages each**By Ranges**: User-defined ranges (e.g., "1-3, 5-10, 12")**Extract Pages**: Specific page extraction (e.g., "1, 3, 5, 8")**Key Technologies**:
pdf-lib: PDF manipulation and creationPDF.js: Page rendering for thumbnailsESBuild: JavaScript bundlingPostCSS: CSS processinglive-server: Development server6. Performance Considerations
Implement lazy loading for PDF pagesClean up blob URLs to prevent memory leaksUse efficient canvas rendering for thumbnailsApply progressive enhancement patternsConsider WebAssembly requirements for PDF.js7. Security Best Practices
All processing must remain client-side (no server uploads)Enforce strict Content Security PolicyValidate file types and sizesUse secure headers (XSS protection, X-Frame-Options)Ensure HTTPS enforcement in production8. Deployment (Netlify)
Configuration in `netlify.toml`Security headers configuredAsset caching optimizedSPA routing via `_redirects`Build command: `npm run build`Publish directory: `dist/`9. Browser Compatibility
Target modern browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+Require ES6+ module supportRequire WebAssembly support for PDF.jsUse progressive enhancement for older browsers10. Debugging and Testing
Check browser console for errorsTest all three split modes thoroughlyVerify memory cleanup (blob URLs)Test drag-and-drop and click uploadValidate file size limits and error messagesTest batch download functionalityVerify thumbnail rendering for various PDF typesCommon Tasks
**Adding a new split mode**:
1. Update `pdfProcessor.js` with new splitting logic
2. Add UI controls in HTML
3. Update `uiController.js` for new form validation
4. Update `main.js` event handlers
5. Test with various PDF files
**Updating PDF processing**:
1. Modify `pdfProcessor.js` methods
2. Test with pdf-lib and PDF.js compatibility
3. Verify memory cleanup after processing
4. Update progress indicators in `uiController.js`
**Styling changes**:
1. Modify `src/css/styles.css`
2. Use CSS custom properties for theme values
3. Run `npm run build:css` to process
4. Test responsive behavior on mobile
**Deployment updates**:
1. Update `netlify.toml` for build settings
2. Modify `_redirects` for routing changes
3. Test with `npm run preview` before deploying
4. Push to main branch for automatic Netlify deployment
Code Standards
Use ES6+ module syntax with `import`/`export`Apply async/await for asynchronous operationsHandle errors with try/catch and user-friendly messagesClean up resources (blob URLs, canvas contexts)Document complex functions with JSDoc commentsUse descriptive variable and function namesMaintain separation of concerns between modulesExample Usage
When asked to add a feature:
1. Identify which module(s) need changes
2. Implement changes following the modular architecture
3. Update UI controller for user feedback
4. Add error handling
5. Test locally with `npm run dev`
6. Build with `npm run build`
7. Verify with `npm run preview`
When debugging issues:
1. Check browser console for JavaScript errors
2. Verify file validation logic in `fileHandler.js`
3. Test PDF processing in `pdfProcessor.js`
4. Review UI state management in `uiController.js`
5. Confirm memory cleanup in `downloadManager.js`