diff --git a/README.md b/README.md
index 61238a1..d6fc25f 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,14 @@ A collection of utility tools for development and testing.
## Tools
+### [Base64 → File](./base64-decoder/)
+
+A single-file web tool that decodes a base64 string and saves it back out as a real file. Handles data URIs, URL-safe base64, missing padding and line-wrapped input; detects the file type from magic bytes and previews images, audio, video, PDFs and text before you download. Runs entirely in the browser — no server, no dependencies, nothing uploaded.
+
+```bash
+xdg-open base64-decoder/base64-decoder.html
+```
+
### [Fake Media](./fake-media/)
Generates large collections of placeholder PNG images for testing without downloading real files. Supports a terminal UI and a non-interactive CLI mode. Configurable image sizes, folder structure, file counts, and naming prefixes — uses only Python's standard library.
diff --git a/base64-decoder/README.md b/base64-decoder/README.md
new file mode 100644
index 0000000..35ef46d
--- /dev/null
+++ b/base64-decoder/README.md
@@ -0,0 +1,60 @@
+# Base64 → File
+
+A single-file web tool that decodes a base64 string and saves the result back out as a real file. Useful for pulling attachments out of API responses, log dumps, JSON payloads, config blobs and `data:` URIs without hunting for a working online decoder — and without pasting anything sensitive into someone else's website.
+
+## What it does
+
+Open `base64-decoder.html` in any browser, paste the base64, and the decoded file appears on the right — type detected, previewed, ready to download.
+
+Everything runs locally in the page. There is no server, no build step, no dependencies, and nothing is ever uploaded.
+
+```bash
+xdg-open base64-decoder/base64-decoder.html
+```
+
+## Input handling
+
+The input is cleaned up before decoding, so most real-world paste jobs work as-is:
+
+| Input | Handled |
+|---|---|
+| `data:image/png;base64,iVBORw0...` | Prefix stripped, MIME type read from the header |
+| Line-wrapped / indented base64 | All whitespace removed |
+| URL-safe base64 (`-` and `_`) | Converted to standard `+` and `/` |
+| Missing `=` padding | Restored |
+| Percent-encoded (`%2B`) | URL-decoded first |
+| Wrapping quotes from a JSON value | Trimmed |
+
+Invalid input gives a specific reason — the offending character, or a truncated length — rather than a generic failure.
+
+## Type detection
+
+The file type is worked out in three passes, in order of reliability:
+
+1. **Magic bytes** — ~30 signatures covering PNG, JPEG, GIF, WEBP, BMP, ICO, PDF, ZIP, GZIP, BZ2, XZ, 7z, RAR, TAR, MP3, MP4, MKV, OGG, FLAC, WAV, AVI, SQLite, TTF/OTF/WOFF/WOFF2, ELF, EXE and Java class files
+2. **Data URI header** — if the input was a `data:` URI, its declared MIME type supplies the extension
+3. **Content sniffing** — payloads that decode as valid UTF-8 are checked for SVG, HTML, XML, JSON, PEM and shell scripts
+
+Anything unrecognised falls back to `application/octet-stream` and a `.bin` extension. The suggested filename is always editable before saving.
+
+## Preview
+
+| Decoded type | Preview |
+|---|---|
+| Images | Rendered inline |
+| Audio / video | Playable with controls |
+| PDF | Embedded viewer |
+| Text-based | Syntax-free text view, plus a **Copy text** button |
+| Anything else | Hex dump of the first 192 bytes with an ASCII column |
+
+## Shortcuts
+
+- **Drag and drop** a `.txt` / `.b64` file onto the input to load its contents
+- **Ctrl/Cmd + S** downloads the decoded file
+- **Enter** in the filename field downloads immediately
+
+## Requirements
+
+Any modern browser. Works straight from `file://` — no web server needed.
+
+The **Paste** button uses the clipboard API, which some browsers restrict on `file://` pages; if it does nothing, use Ctrl+V in the input instead.
diff --git a/base64-decoder/base64-decoder.html b/base64-decoder/base64-decoder.html
new file mode 100644
index 0000000..13716fb
--- /dev/null
+++ b/base64-decoder/base64-decoder.html
@@ -0,0 +1,572 @@
+
+
+
+
+
+Base64 → File
+
+
+
+
+
+ Base64 → File
+ |
+ decode base64 and save it back out as a file
+