✨feature: Release first public version #release

README.md

@@ -1,14 +1,119 @@
 # Open Directory Downloader
 
-GUI downloader for open directory listings (Apache/Nginx autoindex). No extra software required; uses built-in HTTP and optionally `wget` if available.
+Desktop GUI for browsing and downloading from open directory listings (Apache/Nginx autoindex). It works out of the box with built-in HTTP/HTTPS and can optionally use `wget` for faster folder pulls when available.
 
-## Getting started
+## Features
 
-1. Install Node.js (LTS recommended).
-2. Run `npm install`.
-3. Run `npm start`.
+- Remote directory browser with tree view and list view
+- Local folder browser with drag-and-drop targets
+- Download single files or entire folders
+- Optional `wget` mode for recursive folder downloads
+- Progress display for individual files and aggregate folder downloads
+- Light/dark themes with persistence
 
-## Notes
+## Requirements
 
-- The remote listing parser expects an autoindex HTML page (like Apache "Index of").
-- Folder downloads can use `wget` automatically if detected and the checkbox is enabled.
+- Node.js (LTS recommended)
+- npm (bundled with Node.js)
+- Optional: `wget` on your PATH to enable recursive folder downloads via `wget`
+
+## Install
+
+```bash
+npm install
+```
+
+## Run
+
+```bash
+npm start
+```
+
+## Usage
+
+1. Enter a remote URL that points to an autoindex listing (for example an "Index of" page).
+2. Choose a local destination folder (prompted on first launch or via the Browse button).
+3. Select a file or folder from the remote list:
+   - Double-click a folder to enter it.
+   - Drag a remote item onto a local folder to download there.
+   - Or select an item and use "Download Selected".
+4. Watch progress in the toolbar and logs in the Session Log panel.
+
+## Screenshot
+
+Add a screenshot to show the UI. Suggested filename: `docs/screenshot.png`.
+
+```text
+docs/screenshot.png
+```
+
+If you want to embed it:
+
+```markdown
+![Open Directory Downloader UI](docs/screenshot.png)
+```
+
+## How it works
+
+Open Directory Downloader is an Electron app with three layers:
+
+- Main process (`src/main.js`) handles HTTP/HTTPS, parsing directory listings, and performing downloads.
+- Preload (`src/preload.js`) exposes safe IPC APIs to the renderer.
+- Renderer (`src/renderer.js`) drives the UI, local/remote navigation, and progress display.
+
+Remote parsing supports common Apache autoindex layouts (table and `<pre>` formats). Folder downloads are performed by recursively crawling the listing and downloading files, unless `wget` mode is enabled.
+
+## Development
+
+- Main process: `src/main.js`
+- Renderer: `src/renderer.js`
+- Preload: `src/preload.js`
+- UI markup: `src/index.html`
+- Styling: `src/styles.css`
+
+Recommended workflow:
+
+1. Run `npm start` to launch the Electron app.
+2. Make changes to renderer assets (`src/index.html`, `src/renderer.js`, `src/styles.css`).
+3. Restart the app to pick up main/preload changes; renderer changes may require a manual refresh or restart depending on Electron caching.
+
+## Optional `wget` mode
+
+If `wget` is detected on the system, the "Use wget if available" toggle is enabled.
+
+- Folder downloads will use `wget -r -np -nH -P <destDir> <url>`
+- File downloads still use the built-in HTTP/HTTPS client
+
+## Project scripts
+
+```bash
+npm start   # Launch the Electron app
+npm run pack
+npm run dist
+```
+
+## Packaging
+
+This project uses `electron-builder` for packaging.
+
+- `npm run pack` builds unpacked artifacts
+- `npm run dist` builds platform installers
+
+See `package.json` for configuration defaults. You may need to add an `electron-builder` config if you want icons, signing, or platform-specific settings.
+
+## Limitations and notes
+
+- The remote listing parser expects a standard autoindex HTML page.
+- If a server customizes its directory listing heavily, parsing may fail.
+- Aggregate progress for folder downloads requires size metadata from the listing; otherwise progress is indeterminate.
+- Some servers may block recursive downloading or throttle requests.
+
+## Troubleshooting
+
+- "HTTP 403/404": The server may block listing or direct file access.
+- Empty list: Verify the URL ends with a trailing `/` and is an autoindex page.
+- `wget` toggle disabled: Install `wget` and ensure it is on your PATH, then restart the app.
+
+## License
+
+MIT