Offline Document Stamper

A Progressive Web App (PWA) for stamping documents offline. Drag, resize, rotate, and position stamps on documents with precision. Perfect for batch processing documents that need signatures and stamps.

Features

• Drag & Drop Positioning: Click and drag stamps anywhere on the document
• Rotation Control: Rotate stamps to any angle (-180° to 180°)
• Opacity Adjustment: Preview stamp placement with transparency
• Resize Support: Scale stamps up or down with mouse or keyboard
• Keyboard Shortcuts: Arrow keys for precise positioning
• Position Persistence: Stamp position/settings saved between sessions
• Batch Processing: Replace document while keeping stamp position
• Offline Support: Works completely offline after first load
• PWA Installable: Install as a standalone app on desktop/mobile

Quick Start

Installation

cd offline-stamper
npm install

Development

npm run dev

Open your browser to http://localhost:5173

Build for Production

npm run build
npm run preview

How to Use

1. Upload Document: Click "Document Image" and select your document
2. Upload Stamp: Click "Stamp PNG" and select your stamp (transparent PNG recommended)
3. Position Stamp:
   • Drag the stamp to position it
   • Use corner handle to resize
   • Use sliders for opacity and rotation
4. Download: Click "💾 Download" to save the stamped document
5. Batch Process: Click "🔄 Replace Doc" to stamp another document (stamp stays in place)

Keyboard Shortcuts

Keys	Action
←↑→↓	Move stamp by 1px
Shift + Arrow	Move stamp by 10px
+ or =	Scale stamp up
- or _	Scale stamp down
R	Reset stamp position
D	Download stamped document

Features Explained

Position Persistence

The app saves your stamp position, size, rotation, and opacity in browser localStorage. This means:

• Reloading the page keeps your settings
• Perfect for batch processing multiple documents
• Settings persist until you click "Reset Position"

Offline Capability

After the first visit:

• All app files are cached
• Works without internet
• Can be installed as a standalone app
• No data is sent to any server

High-Quality Output

• Downloads preserve original document resolution
• Stamps rendered with smooth anti-aliasing
• PNG format maintains transparency
• Timestamped filenames prevent overwriting

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Opera 76+

All modern browsers with Canvas API and service worker support.

Deployment

GitHub Pages (Automated)

This project includes automatic GitHub Pages deployment.

1. Push your code to GitHub
2. Enable GitHub Pages in Settings → Pages → Source: GitHub Actions
3. Your site will automatically deploy on every push

Manual Deployment

Deploy to any static hosting:

npm run build
# Upload the dist/ folder to your hosting provider

Privacy & Security

• 100% Local Processing: All operations happen in your browser
• No Server Uploads: Documents and stamps never leave your device
• No Analytics: Zero tracking or data collection
• No External Dependencies: After first load, works completely offline

Technical Details

Tech Stack

• Vanilla JavaScript (ES modules)
• HTML5 Canvas API
• Vite build tool
• Vite PWA plugin with Workbox
• localStorage for state persistence

File Structure

offline-stamper/
├── index.html          # Main HTML with UI
├── app.js              # Core stamping logic
├── vite.config.js      # Vite + PWA configuration
├── package.json        # Dependencies
├── public/             # Static assets
│   ├── icon.png
│   ├── icon-192.png
│   └── icon-512.png
└── dist/               # Production build

Development

Adding Features

The app is structured as a single-page application:

• index.html: UI layout and styles
• app.js: Canvas rendering, event handling, state management

Canvas Rendering

The app uses HTML5 Canvas with transformation matrices for:

• Rotation around stamp center point
• Hit detection with inverse transforms
• High-quality image smoothing

State Management

State is managed in a simple object with localStorage sync:

{
  x: number,      // X position
  y: number,      // Y position
  scale: number,  // Scale factor
  rotation: number, // Rotation in degrees
  opacity: number  // Opacity 0-1
}

Troubleshooting

Stamp not appearing:

• Ensure you uploaded both document and stamp
• Check stamp file is a valid image (PNG recommended)

Can't resize stamp:

• Drag the small square handle in the bottom-right corner
• Use + and - keys for keyboard resizing

Position not saving:

• Check browser localStorage is enabled
• Some browsers in private mode don't persist localStorage

License

MIT License - Feel free to use for any purpose

Credits

• PWA Plugin: vite-plugin-pwa
• Build Tool: Vite