zero-http 0.2.0

package/documentation/public/data/examples.json

@@ -0,0 +1,62 @@
+[
+  {
+    "title": "Minimal JSON API",
+    "description": "A concise REST API with CORS, JSON parsing, and a simple in-memory store.",
+    "language": "javascript",
+    "code": "const { createApp, json, cors } = require('zero-http')\nconst app = createApp()\n\napp.use(cors({ origin: ['https://example.com'] }))\napp.use(json({ limit: '10kb' }))\n\nconst items = []\n\napp.get('/items', (req, res) => res.json(items))\n\napp.post('/items', (req, res) => {\n\titems.push(req.body)\n\tres.status(201).json({ ok: true, count: items.length })\n})"
+  },
+  {
+    "title": "File Upload with Multipart Streaming",
+    "description": "Stream uploaded files to disk and return metadata. Swap the disk writer for an S3 stream to go cloud-native.",
+    "language": "javascript",
+    "code": "const path = require('path')\nconst os = require('os')\nconst { createApp, multipart } = require('zero-http')\nconst app = createApp()\n\nconst uploadsDir = path.join(os.tmpdir(), 'my-uploads')\n\napp.post('/upload', multipart({\n\tdir: uploadsDir,\n\tmaxFileSize: 10 * 1024 * 1024  // 10 MB\n}), (req, res) => {\n\tres.json({\n\t\tfiles: req.body.files,\n\t\tfields: req.body.fields\n\t})\n})"
+  },
+  {
+    "title": "Static File Server with Caching",
+    "description": "Serve a public directory with browser caching, dotfile protection, and HTML extension fallback.",
+    "language": "javascript",
+    "code": "const path = require('path')\nconst { createApp, static: serveStatic } = require('zero-http')\nconst app = createApp()\n\napp.use(serveStatic(path.join(__dirname, 'public'), {\n\tindex: 'index.html',\n\tmaxAge: 3600000,          // 1 hour (in ms)\n\tdotfiles: 'ignore',\n\textensions: ['html', 'htm'],\n\tsetHeaders: (res, filePath) => {\n\t\tres.setHeader('X-Served-By', 'zero-http')\n\t}\n}))\n\napp.listen(3000)"
+  },
+  {
+    "title": "Rate-Limited Login Endpoint",
+    "description": "Protect a login route with per-IP rate limiting and a global fallback limiter for the whole app.",
+    "language": "javascript",
+    "code": "const { createApp, json, rateLimit } = require('zero-http')\nconst app = createApp()\n\n// Global: 200 req/min per IP\napp.use(rateLimit({ windowMs: 60000, max: 200 }))\napp.use(json())\n\n// Login: 5 attempts per minute\napp.post('/login', rateLimit({\n\twindowMs: 60000,\n\tmax: 5,\n\tmessage: 'Too many login attempts'\n}), (req, res) => {\n\tconst { username, password } = req.body\n\t// ... authenticate ...\n\tres.json({ ok: true })\n})"
+  },
+  {
+    "title": "Request Logging with Custom Output",
+    "description": "Use the built-in logger middleware for colorized dev output, or write short-format entries to a file.",
+    "language": "javascript",
+    "code": "const fs = require('fs')\nconst { createApp, logger } = require('zero-http')\nconst app = createApp()\n\n// Option A: colorized dev output to stdout\napp.use(logger({ format: 'dev' }))\n\n// Option B: append short-format lines to a log file\napp.use(logger({\n\tformat: 'short',\n\tcolors: false,\n\tlogger: (msg) => fs.appendFileSync('access.log', msg + '\\n')\n}))\n\napp.get('/', (req, res) => res.json({ ok: true }))\napp.listen(3000)"
+  },
+  {
+    "title": "Custom Error Handler",
+    "description": "Register a global error handler so thrown errors return structured JSON instead of a bare 500.",
+    "language": "javascript",
+    "code": "const { createApp, json } = require('zero-http')\nconst app = createApp()\napp.use(json())\n\napp.get('/fail', (req, res) => {\n\tthrow new Error('Something broke!')\n})\n\napp.onError((err, req, res, next) => {\n\tconsole.error(`[${new Date().toISOString()}]`, err.stack)\n\tres.status(err.statusCode || 500).json({\n\t\terror: err.message,\n\t\tpath: req.url\n\t})\n})\n\napp.listen(3000)"
+  },
+  {
+    "title": "Server-Side Fetch with Progress",
+    "description": "Use the built-in fetch client with timeout, abort support, and download progress tracking.",
+    "language": "javascript",
+    "code": "const { fetch } = require('zero-http')\n\nasync function download(url) {\n\tconst controller = new AbortController()\n\tsetTimeout(() => controller.abort(), 10000)\n\n\tconst res = await fetch(url, {\n\t\ttimeout: 5000,\n\t\tsignal: controller.signal,\n\t\tonDownloadProgress: ({ loaded, total }) =>\n\t\t\tconsole.log(`${loaded}/${total || '?'} bytes`)\n\t})\n\n\tconsole.log(res.ok, res.status, res.statusText)\n\tconst data = await res.json()\n\treturn data\n}\n\ndownload('https://jsonplaceholder.typicode.com/todos/1')\n\t.then(console.log)\n\t.catch(console.error)"
+  },
+  {
+    "title": "Path-Prefix Middleware (Sub-App)",
+    "description": "Mount middleware on a path prefix. The prefix is stripped from req.url so downstream handlers see relative paths.",
+    "language": "javascript",
+    "code": "const { createApp, json } = require('zero-http')\nconst app = createApp()\napp.use(json())\n\n// Everything under /api gets this middleware\napp.use('/api', (req, res, next) => {\n\tconsole.log('API request:', req.method, req.url)\n\t// req.url is now '/' instead of '/api/'\n\tnext()\n})\n\napp.get('/api/users', (req, res) => {\n\tres.json([{ id: 1, name: 'Alice' }])\n})\n\napp.listen(3000)"
+  },
+  {
+    "title": "CORS with Subdomain Matching",
+    "description": "Allow all subdomains of a root domain using the dot-prefix origin syntax, with credentials enabled.",
+    "language": "javascript",
+    "code": "const { createApp, cors, json } = require('zero-http')\nconst app = createApp()\n\napp.use(cors({\n\torigin: [\n\t\t'https://mysite.com',     // exact match\n\t\t'.mysite.com'             // suffix: matches api.mysite.com, www.mysite.com, etc.\n\t],\n\tcredentials: true,\n\tmethods: 'GET,POST,PUT,DELETE'\n}))\napp.use(json())\n\napp.get('/data', (req, res) => res.json({ secure: true }))\napp.listen(3000)"
+  },
+  {
+    "title": "Full-Featured Server Skeleton",
+    "description": "Combines logging, CORS, body parsing, rate limiting, static serving, error handling, and route parameters in one setup.",
+    "language": "javascript",
+    "code": "const path = require('path')\nconst { createApp, cors, json, urlencoded, text,\n\tstatic: serveStatic, logger, rateLimit, multipart } = require('zero-http')\n\nconst app = createApp()\n\n// Middleware stack\napp.use(logger({ format: 'dev' }))\napp.use(cors())\napp.use(rateLimit({ windowMs: 60000, max: 200 }))\napp.use(json({ limit: '1mb' }))\napp.use(urlencoded({ extended: true }))\napp.use(text())\napp.use(serveStatic(path.join(__dirname, 'public')))\n\n// Routes\napp.get('/health', (req, res) => res.json({ status: 'ok' }))\napp.get('/users/:id', (req, res) => res.json({ id: req.params.id }))\napp.post('/upload', multipart({ maxFileSize: 5 * 1024 * 1024 }),\n\t(req, res) => res.json(req.body))\n\n// Error handler\napp.onError((err, req, res) => {\n\tres.status(500).json({ error: err.message })\n})\n\napp.listen(3000, () => console.log('Server running on :3000'))"
+  }
+]

package/documentation/public/data/options.json

@@ -0,0 +1,13 @@
+[
+  { "option": "createApp()", "type": "function", "default": "—", "notes": "Creates an app instance with use(), get(), post(), put(), delete(), patch(), options(), head(), all(), onError(), listen(), and handler." },
+  { "option": "json([opts])", "type": "function", "default": "—", "notes": "Parses JSON bodies into req.body. Options: limit, strict (true), reviver, type ('application/json')." },
+  { "option": "urlencoded([opts])", "type": "function", "default": "—", "notes": "Parses URL-encoded bodies. Options: extended (false), limit, type ('application/x-www-form-urlencoded')." },
+  { "option": "text([opts])", "type": "function", "default": "—", "notes": "Reads plain text into req.body. Options: type ('text/*'), limit, encoding ('utf8')." },
+  { "option": "raw([opts])", "type": "function", "default": "—", "notes": "Reads raw bytes into a Buffer on req.body. Options: type ('application/octet-stream'), limit." },
+  { "option": "multipart([opts])", "type": "function", "default": "—", "notes": "Streams file parts to disk; sets req.body to { fields, files }. Options: dir (os.tmpdir()/zero-http-uploads), maxFileSize." },
+  { "option": "static(rootPath, [opts])", "type": "function", "default": "—", "notes": "Serves static files with 60+ MIME types. Options: index ('index.html'), maxAge (0), dotfiles ('ignore'), extensions, setHeaders." },
+  { "option": "cors([opts])", "type": "function", "default": "—", "notes": "CORS middleware with preflight handling. Options: origin ('*'), methods, allowedHeaders, credentials (false)." },
+  { "option": "fetch(url, [opts])", "type": "function", "default": "—", "notes": "Node HTTP/HTTPS client. Response has ok, status, statusText, headers.get(), text(), json(), arrayBuffer(). Options: method, headers, body (auto-serialized), timeout, signal, agent, onDownloadProgress, onUploadProgress." },
+  { "option": "rateLimit([opts])", "type": "function", "default": "—", "notes": "Per-IP rate limiter. Sets X-RateLimit-* headers. Options: windowMs (60000), max (100), statusCode (429), message, keyGenerator." },
+  { "option": "logger([opts])", "type": "function", "default": "—", "notes": "Request logger with response timing. Options: format ('dev'|'short'|'tiny'), logger (console.log), colors (auto TTY)." }
+]

package/documentation/public/index.html

@@ -0,0 +1,414 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+	<meta charset="utf-8" />
+	<meta name="viewport" content="width=device-width,initial-scale=1" />
+	<title>zero-http — demo & reference</title>
+	<meta name="description"
+		content="zero-http is a zero-dependency, Express-like HTTP server for Node.js with built-in parsers, static serving, and upload handling." />
+	<meta name="keywords"
+		content="nodejs,http,server,express,expressjs,middleware,body-parser,multipart,uploads,static files,fetch,http client" />
+	<meta name="author" content="Anthony Wiedman" />
+
+	<link rel="stylesheet" href="/styles.css" />
+	<link rel="stylesheet" href="/vendor/prism-okaidia.css" />
+	<link rel="stylesheet" href="/vendor/prism-toolbar.css" />
+	<link rel="stylesheet" href="/prism-overrides.css" />
+
+	<script src="/vendor/prism.min.js" async></script>
+	<script src="/vendor/prism-json.min.js" async></script>
+	<script src="/vendor/prism-javascript.min.js" async></script>
+	<script src="/vendor/prism-copy-to-clipboard.min.js" async></script>
+	<script src="/vendor/prism-toolbar.min.js" async></script>
+
+	<script src="/scripts/helpers.js" defer></script>
+	<script src="/scripts/uploads.js" defer></script>
+	<script src="/scripts/playground.js" defer></script>
+	<script src="/scripts/proxy.js" defer></script>
+	<script src="/scripts/data-sections.js" defer></script>
+	<script src="/scripts/ui.js" defer></script>
+	<script src="/scripts/app.js" defer></script>
+</head>
+
+<body>
+	<a id="top"></a>
+	<div class="ui-shell">
+		<header class="ui-header">
+			<button class="toc-toggle" aria-label="Toggle table of contents" title="Toggle table of contents">
+				<svg viewBox="0 0 24 24" width="20" height="20" fill="none" aria-hidden="true">
+					<path d="M3 6h18M3 12h18M3 18h18" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
+				</svg>
+			</button>
+
+			<a class="brand" href="#top" id="brand-top" style="text-decoration:none;color:inherit;cursor:pointer">
+				<div class="logo">zero-http</div>
+				<div class="subtitle">Zero-dependency Express-like server</div>
+			</a>
+
+			<div class="repo-buttons" role="navigation" aria-label="Repository links">
+				<a class="icon-btn" href="https://github.com/tonywied17/zero-http-npm" target="_blank"
+					rel="noopener noreferrer" aria-label="View on GitHub">
+					<svg class="icon-svg" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+						<path
+							d="M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.56 0-.28-.01-1.02-.02-2-3.2.7-3.88-1.54-3.88-1.54-.53-1.34-1.3-1.7-1.3-1.7-1.06-.72.08-.71.08-.71 1.17.08 1.79 1.2 1.79 1.2 1.04 1.78 2.73 1.27 3.4.97.11-.76.41-1.27.75-1.56-2.56-.29-5.25-1.28-5.25-5.7 0-1.26.45-2.29 1.18-3.1-.12-.29-.51-1.45.11-3.02 0 0 .96-.31 3.15 1.18a10.9 10.9 0 0 1 2.87-.39c.98 0 1.97.13 2.87.39 2.18-1.49 3.14-1.18 3.14-1.18.63 1.57.24 2.73.12 3.02.74.81 1.18 1.84 1.18 3.1 0 4.43-2.7 5.4-5.27 5.69.42.36.8 1.07.8 2.15 0 1.55-.01 2.8-.01 3.18 0 .31.21.68.8.56C20.71 21.39 24 17.08 24 12c0-6.35-5.15-11.5-12-11.5z" />
+					</svg>
+					<span class="sr">GitHub</span>
+				</a>
+				<a class="icon-btn" href="https://www.npmjs.com/package/zero-http" target="_blank"
+					rel="noopener noreferrer" aria-label="View on npm">
+					<svg class="icon-svg" viewBox="0 0 48 22" aria-hidden="true" role="img">
+						<rect width="48" height="22" rx="4" fill="#CB3837"></rect>
+						<text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle"
+							font-family="Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif" font-weight="800"
+							font-size="14" fill="#fff">npm</text>
+					</svg>
+					<span class="sr">npm</span>
+				</a>
+			</div>
+		</header>
+
+		<aside class="toc-sidebar" aria-label="Table of contents">
+			<nav>
+				<div class="toc-toolbar">
+					<button class="toc-tool-btn" id="toc-top-btn" title="Back to top" aria-label="Scroll to top">
+						<svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M8 13V3" stroke="currentColor" stroke-width="2" stroke-linecap="round"/><path d="M3 7l5-5 5 5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
+					</button>
+					<button class="toc-tool-btn" id="toc-toggle-acc" title="Expand all" aria-label="Expand all sections">
+						<svg width="16" height="16" viewBox="0 0 16 16" fill="none"><path d="M2 4l6 4 6-4" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/><path d="M2 9l6 4 6-4" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>
+					</button>
+				</div>
+				<ul>
+					<li><a href="#features">Features</a></li>
+					<li><a href="#quickstart">Quickstart</a></li>
+					<li><a href="#options">Options</a></li>
+					<li><a href="#api-reference">API Reference</a></li>
+					<li><a href="#simple-examples">Simple Examples</a></li>
+					<li><a href="#playground">Playground</a>
+						<ul class="toc-sub">
+							<li class="toc-sub-item"><a href="#upload-testing">Upload multipart data</a></li>
+							<li class="toc-sub-item"><a href="#parser-tests">Parser tests</a></li>
+							<li class="toc-sub-item"><a href="#proxy-test">Proxy test</a></li>
+						</ul>
+					</li>
+				</ul>
+			</nav>
+		</aside>
+		<main class="ui-main">
+			<div class="card docs-card">
+
+				<div class="feature-tabs" id="features">
+					<div class="tabs-nav" role="tablist" aria-label="Docs sections tabs">
+						<button class="tab active" data-target="tab-features" role="tab"
+							aria-selected="true">Features</button>
+						<button class="tab" data-target="tab-behavior" role="tab" aria-selected="false">Server
+							model</button>
+					</div>
+					<div class="tabs-content">
+						<div id="tab-features" class="tab-panel active">
+							<div class="feature-grid">
+								<div class="feature-card">
+									<div class="feature-icon">
+										<img class="icon-svg" src="/vendor/icons/zero.svg" alt="" aria-hidden="true"
+											width="48" height="48" />
+									</div>
+									<h5>Zero-dependency</h5>
+									<p>Small, Express-like API without external deps.</p>
+								</div>
+								<div class="feature-card">
+									<div class="feature-icon">
+										<img class="icon-svg" src="/vendor/icons/plug.svg" alt="" aria-hidden="true"
+											width="48" height="48" />
+									</div>
+									<h5>Pluggable parsers</h5>
+									<p>json(), urlencoded(), text(), raw() built-in.</p>
+								</div>
+								<div class="feature-card">
+									<div class="feature-icon">
+										<img class="icon-svg" src="/vendor/icons/stream.svg" alt="" aria-hidden="true"
+											width="48" height="48" />
+									</div>
+									<h5>Streaming uploads</h5>
+									<p>Multipart streaming to disk for large files.</p>
+								</div>
+								<div class="feature-card">
+									<div class="feature-icon">
+										<img class="icon-svg" src="/vendor/icons/static.svg" alt="" aria-hidden="true"
+											width="48" height="48" />
+									</div>
+									<h5>Static serving</h5>
+									<p>Correct Content-Type handling and caching options.</p>
+								</div>
+								<div class="feature-card">
+									<div class="feature-icon">
+										<img class="icon-svg" src="/vendor/icons/fetch.svg" alt="" aria-hidden="true"
+											width="48" height="48" />
+									</div>
+									<h5>Built-in fetch</h5>
+									<p>Small server-side fetch replacement for HTTP requests.</p>
+								</div>
+							</div>
+						</div>
+						<div id="tab-behavior" class="tab-panel">
+							<div class="behavior-list">
+								<div class="behavior-step">
+									<div class="step-num">1</div>
+									<div class="step-body">
+										<h5>Registration order</h5>
+										<p>Routing and middleware run in the order they're registered—add parsers before
+											handlers.</p>
+									</div>
+								</div>
+								<div class="behavior-step">
+									<div class="step-num">2</div>
+									<div class="step-body">
+										<h5>Body parsing</h5>
+										<p>Body parsers populate <code>req.body</code>; multipart uploads expose
+											<code>req.body.files</code> and <code>req.body.fields</code>.
+										</p>
+									</div>
+								</div>
+								<div class="behavior-step">
+									<div class="step-num">3</div>
+									<div class="step-body">
+										<h5>Handler model</h5>
+										<p>Handlers receive <code>req</code> and <code>res</code>. Use
+											<code>res.json()</code> or <code>res.send()</code> to respond.
+										</p>
+									</div>
+								</div>
+								<div class="behavior-step">
+									<div class="step-num">4</div>
+									<div class="step-body">
+										<h5>Static middleware</h5>
+										<p>Serves files with Content-Type derived from extension and supports caching
+											options.</p>
+									</div>
+								</div>
+							</div>
+						</div>
+					</div>
+				</div>
+
+				<div class="acc-body">
+					<h4 id="quickstart">Quickstart</h4>
+
+					<p class="muted">Install from npm and create a simple server:</p>
+					<pre class="language-bash"><code class="language-bash">npm install zero-http</code></pre>
+
+					<pre class="language-javascript"><code class="language-javascript">const { createApp, json, static } = require('zero-http')
+const path = require('path')
+const app = createApp()
+
+app.use(json({ limit: '10kb' }))
+app.use(static(path.join(__dirname, 'public'), { index: 'index.html' }))
+
+app.get('/ping', (req, res) =&gt; res.json({ pong: true }))
+
+app.listen(3000, () =&gt; {
+	console.log('Server listening on http://localhost:3000')
+})
+</code></pre>
+
+					<p class="muted">To run this demo server from the repo root and open
+						<code>http://localhost:3000</code>.
+					</p>
+					<pre class="language-bash"><code class="language-bash">npm install zero-http
+npm run docs
+# open http://localhost:3000
+</code></pre>
+
+					<h4>API, Options & Examples</h4>
+
+					<div class="muted">Comprehensive reference for configuration options, runtime behavior, and API
+						examples. Expand each section for details and runnable snippets.</div>
+
+					<details class="acc" id="options">
+						<summary>Options (middleware & parser settings)</summary>
+						<div class="acc-body">
+							<p class="muted">Common option shapes and defaults for parsers and upload middleware.</p>
+							<div id="options-items">Loading options…</div>
+						</div>
+					</details>
+
+					<details class="acc" id="api-reference">
+						<summary>API Reference</summary>
+						<div class="acc-body">
+							<div style="display:flex;gap:8px;align-items:center;margin-bottom:8px">
+								<input id="api-search" placeholder="Search API (name, description)"
+									style="flex:1;padding:8px;border-radius:8px;border:1px solid rgba(0,0,0,0.06);background:transparent;color:inherit" />
+								<button id="api-clear" class="btn small" type="button">Clear</button>
+							</div>
+							<div id="api-items">Loading API reference…</div>
+						</div>
+					</details>
+
+					<details class="acc" id="simple-examples">
+						<summary>Simple Examples</summary>
+						<div class="acc-body">
+							<p class="muted">Snippets showing how to compose middleware for common
+								tasks.</p>
+							<div id="examples-items">Loading examples…</div>
+						</div>
+					</details>
+
+					<details class="acc">
+						<summary>Installation & tests</summary>
+						<div class="acc-body">
+
+							<pre class="language-bash"><code class="language-shell">#clone and install dependencies
+git clone https://github.com/tonywied17/zero-http-npm.git
+npm install
+
+# run demo server from repo root
+npm run docs
+
+# or directly:
+node documentation/full-server.js
+
+# run tests (project-specific)
+node test/test.js
+</code></pre>
+
+						</div>
+					</details>
+
+					<h4>Extending</h4>
+					<p>Use the provided middlewares and routing helpers to build controllers, add auth, or swap in
+						different storage backends. The multipart parser exposes file streams and writes each part to
+						disk so you can replace disk writes with S3 streams if desired.</p>
+
+				</div>
+			</div>
+
+			<div class="section-divider constrained" id="playground">
+				<h2 class="section-title">Playground</h2>
+				<p class="muted">Interactive tools to test uploads, body parsers, and the built-in proxy.</p>
+			</div>
+
+			<div class="card upload-card constrained">
+				<div class="card-head">
+					<h3 id="upload-testing">Upload multipart data</h3>
+					<div class="small muted">Drag, drop or pick a file</div>
+				</div>
+				<form id="uploadForm" class="uploadForm" enctype="multipart/form-data">
+					<div class="fileDrop" id="fileDrop">
+						<input id="fileInput" name="file" type="file" class="fileInput" />
+						<div class="fileDrop-inner">Drop files here or <label for="fileInput" class="linkish">choose
+								file</label></div>
+					</div>
+					<input name="desc" class="textInput" placeholder="Description (optional)" />
+
+					<div class="upload-button-wrap">
+						<button type="submit" class="btn primary">Upload</button>
+					</div>
+
+					<div id="uploadResult" class="result mono"></div>
+
+					<div class="controls">
+
+						<div class="left-controls">
+
+							<button id="delAllBtn" type="button" class="btn warn">Delete All</button>
+							<button id="delKeepBtn" type="button" class="btn">Delete (keep 1)</button>
+						</div>
+						<div class="right-controls">
+							<label class="selectWrap">
+								<select id="sortSelect">
+									<option value="mtime">Newest</option>
+									<option value="name">Name</option>
+									<option value="size">Size</option>
+								</select>
+								<select id="sortOrder" title="Sort order" aria-label="Sort order">
+									<option value="desc">Desc</option>
+									<option value="asc">Asc</option>
+								</select>
+							</label>
+							<div class="pager"><button id="prevPage" type="button" class="btn small">◀</button><span
+									id="pageInfo">Page 1</span><button id="nextPage" type="button"
+									class="btn small">▶</button></div>
+						</div>
+					</div>
+					<progress id="uploadProgress" value="0" max="100" style="display:none"></progress>
+				</form>
+
+				<div class="files-wrap combined-files" style="margin-top:18px">
+					<div class="files-column">
+						<div class="card files-card">
+							<div class="card-head">
+								<h3>Uploaded Files</h3>
+								<div class="small muted">Thumbnails and metadata</div>
+							</div>
+							<div id="uploadsList" class="file-grid">(loading...)</div>
+						</div>
+					</div>
+
+					<div class="trash-column">
+						<div class="card trash-card">
+							<div class="card-head">
+								<h3>Trash</h3>
+							</div>
+							<div id="trashList" class="file-grid muted">(loading...)</div>
+							<div style="margin-top:12px"><button id="emptyTrashBtn" type="button" class="btn">Empty
+									Trash</button></div>
+						</div>
+					</div>
+				</div>
+			</div>
+			<div class="card play-card constrained">
+				<div class="card-head">
+					<h3 id="parser-tests">Quick parser tests</h3>
+				</div>
+				<div class="card-body">
+					<div class="playgrid">
+						<form id="jsonPlay" class="play">
+							<label>JSON (raw)
+								<textarea name="json" class="textInput">{"foo":"bar"}</textarea>
+							</label>
+							<button class="btn">Send JSON</button>
+						</form>
+						<form id="urlPlay" class="play">
+							<label>URL-encoded (body)
+								<textarea name="url" class="textInput">foo=bar&amp;baz=qux</textarea>
+							</label>
+							<button class="btn">Send urlencoded</button>
+						</form>
+						<form id="textPlay" class="play">
+							<label>Text (raw)
+								<textarea name="txt" class="textInput">hello world</textarea>
+							</label>
+							<button class="btn">Send text</button>
+						</form>
+					</div>
+					<pre id="playResult" class="result mono" style="margin-top:12px"></pre>
+				</div>
+			</div>
+
+			<div class="card proxy-card constrained">
+				<div class="card-head">
+					<h3 id="proxy-test">Proxy Test</h3>
+				</div>
+				<div class="card-body">
+					<form id="proxyForm" class="play">
+						<label>External URL to proxy
+							<input id="proxyUrl" name="proxyUrl" class="textInput" type="url"
+								placeholder="https://download.samplelib.com/mp4/sample-5s.mp4" required
+								style="width:100%" />
+						</label>
+						<button class="btn">Proxy Fetch</button>
+					</form>
+					<pre id="proxyResult" class="result mono" style="margin-top:12px"></pre>
+				</div>
+			</div>
+
+			<div class="card footnote" style="max-width:1300px;margin:18px auto;">
+				<p class="muted">This demo doubles as a readable API reference and playground — try uploading files,
+					inspect the returned JSON, and use the playground to test parsers.</p>
+			</div>
+		</main>
+
+	</div>
+
+</body>
+
+</html>

package/documentation/public/prism-overrides.css

@@ -0,0 +1,40 @@
+/* Prism overrides loaded after vendor prism.css to ensure theme precedence */
+:root{--prism-pre-bg: linear-gradient(180deg, rgba(11,13,16,0.96), rgba(6,8,10,0.96));}
+
+/* Stronger specificity and !important to override vendor rules */
+body pre[class*="language-"], body code[class*="language-"] {
+  background: var(--prism-pre-bg) !important;
+  padding: 18px !important;
+  border-radius: 10px !important;
+  overflow: auto !important;
+  border: 1px solid rgba(255,255,255,0.04) !important;
+  color: var(--text) !important;
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.02) !important;
+}
+
+/* Ensure code text uses the demo monospace and sizing */
+body code[class*="language-"] { font-family: Menlo, Monaco, Consolas, 'Courier New', monospace !important; font-size:14px !important; }
+
+/* Token color overrides (important to beat vendor palette) */
+.token.comment, .token.prolog, .token.doctype, .token.cdata { color: var(--muted) !important; font-style: italic !important; }
+.token.punctuation { color: rgba(255,255,255,0.6) !important; }
+.token.namespace { opacity: .7 !important; }
+.token.property, .token.tag, .token.constant, .token.symbol, .token.deleted { color: var(--accent-2) !important; }
+.token.boolean, .token.number { color: #f6c177 !important; }
+.token.selector, .token.attr-name, .token.string, .token.char, .token.builtin, .token.inserted { color: var(--success) !important; }
+.token.operator, .token.entity, .token.url, .language-css .token.string, .style .token.string { color: #9fe6a0 !important; }
+.token.atrule, .token.attr-value, .token.keyword { color: var(--accent) !important; font-weight:700 !important; }
+.token.function { color: #8ad1ff !important; }
+.token.regex, .token.important { color: #ffd580 !important; }
+.token.variable { color: #ffd580 !important; }
+
+/* Inline code readability tweak */
+code.inline, :not(pre) > code { background: rgba(255,255,255,0.02) !important; padding:2px 6px !important; border-radius:6px !important; font-size:0.95em !important; }
+
+@media (max-width:640px) {
+  body pre[class*="language-"], body code[class*="language-"] {
+    padding: 8px !important;
+    font-size:13px !important;
+    margin: 0;
+  }
+}

package/documentation/public/scripts/app.js

@@ -0,0 +1,44 @@
+/**
+ * app.js  (entry point)
+ * Single DOMContentLoaded handler that bootstraps every documentation feature.
+ * Each section is initialised by calling into the module that owns it:
+ *
+ *   helpers.js        → DOM selectors, formatters, Prism helpers
+ *   uploads.js        → initUploads()
+ *   playground.js     → initPlayground()
+ *   proxy.js          → initProxy()
+ *   data-sections.js  → loadApiReference(), loadOptions(), loadExamples()
+ */
+
+document.addEventListener('DOMContentLoaded', () =>
+{
+    /* De-indent and highlight static <pre> blocks */
+    try { dedentAllPre(); } catch (e) { }
+    try { highlightAllPre(); } catch (e) { }
+
+    /* Accordion click handling (open/close <details> manually) */
+    try
+    {
+        document.querySelectorAll('details.acc summary').forEach(summary =>
+        {
+            if (summary.dataset.miniExpressSummary === '1') return;
+            summary.dataset.miniExpressSummary = '1';
+            summary.addEventListener('click', (ev) =>
+            {
+                ev.preventDefault();
+                const details = summary.parentElement;
+                if (details) details.open = !details.open;
+            });
+        });
+    } catch (e) { }
+
+    /* Feature modules */
+    initUploads();
+    initPlayground();
+    initProxy();
+
+    /* Data-driven documentation sections */
+    loadApiReference().catch(() => {});
+    loadOptions().catch(() => {});
+    loadExamples().catch(() => {});
+});