Airlock

Airlock is a local-first file utility suite. Every file operation runs in the browser. No uploads. No backend processing.

Why it exists

• Most file tools require upload to a server.
• Airlock is designed for privacy-sensitive workflows where local-only processing is non-negotiable.
• The UI is built to be fast, clear, and production-friendly for open-source adoption.

Current status (Phase 7)

Implemented in this version:

• Shared shell with tool switching
• Persistent privacy banner
• Drag-and-drop file intake with browse fallback
• Output card with size delta and one-click download
• Image Compressor
• Image Resizer (aspect ratio lock)
• Format Converter (PNG, JPEG, WebP)

Image tools added in Phase 3:

• Image Crop (percentage-based crop box)
• Rotate / Flip
• Image Watermark (text + optional logo overlay)
• Image Collage (multi-file grid)
• EXIF Viewer
• EXIF Stripper (re-export without metadata)
• Background Remove (in-browser model)

Utility tools added in Phase 4:

• QR Code Generator (PNG output)
• Base64 Encode/Decode (text and file workflows)
• Hash Generator (SHA-256, SHA-384, SHA-512)
• Color Converter (HEX, RGB, HSL)
• JSON Formatter / Minifier / Validator

Phase 5 additions:

• Batch Image Pipeline (compress, resize, convert)
• ZIP packaging for batch output
• Theme toggle (light/dark) and responsive polish
• Expanded UI smoke coverage across all tool groups

Phase 6 additions:

• Offline artifact generation (dist/offline.html) with inlined shell assets and rewritten local paths
• Release packaging for hosted and offline distributions under release/
• Verified file:// runtime for offline distribution shell and all tool routes

Phase 7 additions:

• README restructuring for release readability with collapsed screenshot galleries
• Packaging helper tests for offline/release script behavior
• Production hardening command path (hardening:prod) for pre-release verification

Audit notes:

• Local-only checklist and results: docs/phase5-local-only-audit.md

Packaging notes:

• Hosted artifact: release/hosted (standard Vite output)
• Offline artifact: release/offline/airlock-offline.html plus sibling release/offline/assets

PDF tools added in Phase 2:

• PDF Merge (multi-file)
• PDF Split (range mode and single-page preview split)
• PDF Rotate (selected pages)
• PDF Reorder/Delete
• PDF Watermark (text)
• PDF to Images (ZIP)
• Images to PDF
• PDF Text Extraction
• PDF Password flow placeholder with explicit validation and transparent limitation note

Local-only guarantee

Airlock processes files in browser memory using canvas and local APIs. During processing, the app does not send file payloads to any remote server.

Run locally

npm install
npm run dev

Open the local URL printed by Vite.

Build

npm run build
npm run preview

Offline and release artifacts (Phase 6)

npm run build:offline
npm run release:artifacts

Generated outputs:

• dist/offline.html
• release/hosted/*
• release/offline/airlock-offline.html
• release/offline/assets/*

Tests

npm run test

Current test coverage focuses on PDF page-selection parsing logic used by split/rotate/reorder flows. Phase 3 adds unit coverage for image math helpers used by crop and collage workflows. Phase 4 adds utility coverage for color conversion and JSON validation/formatting behavior. Phase 5 adds batch planning tests and end-to-end UI validation for upload/edit/export flows. Phase 7 adds packaging helper coverage for offline asset path rewriting and release-note generation.

Production hardening

npm run hardening:prod

This command runs linting, all unit tests, release artifact generation, and artifact verification checks.

Project structure

src/
  shell/
    FileDropZone.tsx
    DownloadResult.tsx
    PrivacyBanner.tsx
    ToolLayout.tsx
  tools/
    batch/
      imageBatch.ts
      plan.ts
    image/
      compress.ts
      resize.ts
      convert.ts
      crop.ts
      rotateFlip.ts
      watermark.ts
      collage.ts
      exif.ts
      backgroundRemove.ts
      math.ts
      shared.ts
    utils/
      qr.ts
      base64.ts
      hash.ts
      color.ts
      json.ts
    pdf/
      merge.ts
      split.ts
      rotate.ts
      reorderDelete.ts
      watermark.ts
      pdfToImages.ts
      imagesToPdf.ts
      extractText.ts
      common.ts
  App.tsx
  index.css

Known limitations

• Password protect/unlock is intentionally marked as a transparent placeholder in this phase.
• Per-page split currently exposes range split and a single-page preview split; full one-file-per-page bundle mode is planned for a follow-up.
• PDF rendering uses browser memory; very large PDFs may need future streaming optimizations.
• Background removal model can take longer on first run because model assets initialize in browser context.
• EXIF availability depends on source format and device metadata behavior.
• Base64 decode assumes valid payload input; malformed payloads surface explicit decoding errors.
• Background removal performance can vary by browser CPU/GPU and model warm-up state.
• Offline package still requires the local assets directory next to airlock-offline.html for chunk/model/worker files.

Screenshot evidence (Phase 6)

Overview (click to expand)

Image tools (click to expand)

PDF tools (click to expand)

Utility tools (click to expand)