InitRelease

Author: paradox-solver

.gitignore

@@ -205,3 +205,15 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Office
+*.ppt
+*.pptx
+*.doc
+*.docx
+*.xls
+*.xlsx
+
+venv/
+.venv/
+temp/

ReadMe.md

@@ -0,0 +1,227 @@
+# DOCXPress ✨
+
+**Edit your document like filling a form — entirely in your browser, entirely offline.**
+
+DOCXPress is a lightweight, local‑first DOCX editor built with FastAPI and python‑docx. It lets you update DOCX templates quickly while preserving every bit of original formatting — no Office suite required, ever again.
+
+> 🧩 Think of it as a smart form editor for DOCX files: click, edit, save. All formatting stays exactly as designed.
+
+| Editor View | Exported Document |
+|-------------|-------------------|
+| <img src="assets/editor.png" height="400" alt="DOCXPress Editor Interface"> | <img src="assets/exported.png" height="400" alt="Exported DOCX Preview"> |
+
+*Left: DOCXPress editing interface. Right: Exported document with all edits applied and formatting preserved (template downloaded from [https://word.cloud.microsoft/](https://word.cloud.microsoft/)).*
+
+---
+
+## 🚀 Why DOCXPress?
+
+Tired of opening heavy Word processors just to update a date, change a name, or fill in a template?  
+DOCXPress is a **focused, local‑first** tool for anyone who:
+
+- 🧑‍💻 **Needs to update DOCX templates** without installing Microsoft Word or LibreOffice
+- 🔒 **Values privacy and control** — everything runs locally, your documents never leave your machine
+- 🧩 **Prefers simple, constrained interfaces** that prevent accidental formatting changes
+- ⚡ **Wants instant editing** — upload, click, edit, export, done
+- 🧠 **Appreciates tools built with clear design principles** and technical transparency
+
+This isn’t a full‑featured Word replacement.  
+It’s for **template‑based workflows, form filling, and controlled content updates** — all through your browser, with zero installation.
+
+---
+
+## ✨ Features
+
+### 🖥️ Web‑Based & Intuitive
+- Edit DOCX files directly in your browser — no desktop office software needed
+- Clean, form‑like interface with visual highlighting of editable areas
+- Real‑time text editing with click‑to‑edit interaction
+- Full table cell editing support
+
+### 🔒 Format‑Safe Editing
+- Edit text **without altering original fonts, styles, spacing, or layout**
+- Green dashed boxes = editable paragraphs | Green table cells = editable content
+- Export back to `.docx` with **all original formatting preserved**
+- Export to PDF using Aspose.Words — no Office installation required
+
+### ⚡ Lightweight & Fast
+- Entirely local — no cloud uploads, no registration, no external APIs
+- Fast startup and instant parsing thanks to python‑docx and FastAPI
+- Session‑based editing with manual save control — you decide when to commit changes
+
+### 📤 Flexible Export
+- Save edits to a new `.docx` file
+- Export directly to `.pdf` (using Aspose.Words evaluation version)
+- All processing happens on your machine — your data stays private
+
+---
+
+## 🛠️ How It Works
+
+DOCXPress parses your `.docx` file into structured text and layout data, identifies editable regions (short paragraphs, placeholders, empty table cells), and renders them in a clean web form. Your edits are stored separately and then merged back into the original document — keeping the design completely intact.
+
+Think of it as **“content‑editing decoupled from design‑editing.”**
+
+---
+
+## 📦 Tech Stack
+
+### Backend
+- **FastAPI** – Modern, fast web framework for APIs
+- **python-docx** – DOCX reading/writing
+- **Aspose.Words** – DOCX → PDF conversion (evaluation version, full‑featured)
+- **Jinja2** – HTML templating
+- **Uvicorn** – ASGI server
+
+### Frontend
+- Vanilla JavaScript – lightweight and framework‑free
+- CSS3 – clean, responsive styling
+- HTML5 – semantic markup
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python 3.7+
+- pip
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/paradox-solver/DOCXpress.git
+cd DOCXpress
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the application
+python main.py
+```
+
+Then open your browser to:  
+👉 **http://localhost:8000**
+
+---
+
+## 🧭 Quick Tour
+
+### 1. **Upload a DOCX Template**
+Start from the homepage — drag & drop or select a `.docx` file. *This file is saved to your system `User` repository by default.*
+
+<img src="assets/main.png" width="500" alt="Upload Interface">
+
+### 2. **Edit with Confidence**
+Click any blue‑highlighted text or table cell to edit. All changes are kept in your session until you save.
+
+<img src="assets/editor.png" width="500" alt="Editor View">
+
+### 3. **Save & Export**
+- **Save Changes** – store edits to your local machine (system `User` repository by default)
+- **Export DOCX** – download the edited document as `.docx`
+- **Export PDF** – download a PDF version (converted via Aspose.Words)
+
+---
+
+## 🎨 Design Rationale & Philosophy
+
+DOCXPress is built on a clear, deliberate philosophy that emphasizes **constraint, clarity, and preservation**. It’s not trying to be Microsoft Word — instead, it carves out a specific niche where it can excel with reliability, simplicity, and user control.
+
+### 🌟 Core Principles
+
+**🔒 Local‑First & Offline‑Native**  
+Every part of the workflow happens on your machine. No document data is sent externally, no cloud dependencies, no login required. Your documents stay private, and you can work completely offline.
+
+**📄 Format Preservation as a Non‑Negotiable**  
+DOCXPress does not redesign, reflow, or reinterpret your document. It extracts editable content, lets you modify it, and reassembles the document with pixel‑faithful formatting. The tool acts as a **custodian of your original design**.
+
+**🎯 Editing as Form‑Filling**  
+The interface is intentionally minimal — it feels like filling a web form, not a full‑featured word processor. This constraint is a feature: it focuses the user on **content updates only**, systematically preventing accidental formatting changes and reducing cognitive load.
+
+**⚖️ Scope‑Aware Reliability**  
+The tool is optimized for a specific workflow: **editing existing DOCX templates**. It doesn’t try to support every Word feature. By narrowing its scope, it delivers predictable, high‑quality results without the instability of a general‑purpose editor.
+
+**🔄 Explicit User Control**  
+You choose when to save, when to export, and what changes to keep. The system doesn’t auto‑save or modify your original file without your consent. This mirrors the “commit” model from version control — changes are intentional, traceable, and reversible.
+
+**🧩 Modular & Transparent Architecture**  
+Built on focused, well‑understood libraries (python‑docx, FastAPI, Jinja2). Each component has a clear responsibility, and the data flow — from DOCX parsing to HTML rendering to reassembly — is designed to be inspectable and debuggable.
+
+### 🔧 Philosophy in Practice
+
+These principles directly shape the implementation:
+
+- **Structured Extraction** – Documents are parsed into editable elements (paragraphs, table cells) and immutable styling metadata
+- **Non‑Destructive Workflow** – Edits are stored separately from the original template, enabling clean merges and session‑based undo/redo
+- **Visual Guard Rails** – Green highlights clearly indicate what can be edited; everything else is protected
+- **Session‑Based Isolation** – Each editing session is self‑contained, preventing cross‑file contamination and simplifying state management
+- **Export‑Time Assembly** – The final DOCX is rebuilt at export time, ensuring the original template is the single source of truth for formatting
+
+### 🧠 The Bigger Picture
+
+DOCXPress is part of a growing ethos of **lightweight, respectful software**. In a world of bloated office suites, subscription lock‑in, and opaque cloud services, it offers a quiet alternative: a tool that does one thing well, respects your data, and stays out of your way.
+
+It’s for anyone who believes that software should be **a lens, not a cage** — and that the best tools are often those that embrace constraints to deliver clarity and reliability. ✨
+
+---
+
+## ⚠️ Notes & Limitations
+
+- ✅ **Great for** filling templates, updating forms, editing documents with fixed layouts
+- 🔄 **Supports** paragraphs, tables, text formatting preservation, local PDF export
+- ⚠️ **Not for** creating documents from scratch or designing complex layouts
+- 🧪 **Best results** with standard Word templates and conventional DOCX formatting
+- 📄 **PDF export** uses Aspose.Words evaluation version (watermark with this version)
+- 💾 **Remember to click “Save Changes”** before close the editor or return
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **PDF Export Fails**
+   - Ensure `aspose-words` is properly installed
+   - Check temporary file permissions
+   - Verify DOCX file format compatibility
+
+2. **Edits Not Saved**
+   - Click **Save Changes** before exporting
+   - Check browser console for JavaScript errors
+   - Verify session is still active (`/debug/sessions`)
+
+3. **File Upload Fails**
+   - Ensure file format is `.docx`
+   - Check file size
+   - Verify file integrity
+
+### Debug Endpoints
+- `/debug/sessions` – view active sessions
+- `/test-pdf-direct` – test PDF conversion
+- `/fix-session` – session recovery page
+
+---
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome! Whether you’ve found a bug, have a feature idea, or want to improve the docs — feel free to contribute.
+
+---
+
+## 📄 License
+
+[MIT License](LICENSE) — free to use, modify, and share.
+
+---
+
+## 🙏 Acknowledgments
+
+- [python-docx](https://github.com/python-openxml/python-docx) – excellent DOCX processing library
+- [FastAPI](https://fastapi.tiangolo.com/) – efficient and modern web framework
+- [Aspose.Words](https://products.aspose.com/words/) – reliable DOCX to PDF conversion
+- [Jinja2](https://jinja.palletsprojects.com/) – powerful templating engine
+
+---
+
+**Happy form‑filling — without the Word bloat.** 🎉