@a83/orbiter-admin 0.2.0 → 0.3.1

package/README.md

@@ -1,45 +1,70 @@
 # @a83/orbiter-admin
 
-Standalone admin UI for Orbiter CMS. A self-contained Node.js server — no Astro required.
+Standalone admin server for [Orbiter CMS](https://orbiter.sh) — a self-contained Hono HTTP server that reads and writes a `.pod` file.
 
----
+[![npm](https://img.shields.io/npm/v/@a83/orbiter-admin?color=8b7cf8)](https://www.npmjs.com/package/@a83/orbiter-admin)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/aeon022/orbiter/blob/main/LICENSE)
 
-## What it is
+---
 
-Orbiter stores everything in a single `.pod` file (SQLite). This package is the admin interface: a Hono HTTP server that reads and writes that file. It runs independently from your public site, on its own port or subdomain.
+Orbiter stores everything — content, media, schema, users — in a single `.pod` file (SQLite). This package is the admin interface: a Hono HTTP server that runs on its own port, independent from your Astro site.
 
 ```
 content.pod  ←  shared file
-     ↑                  ↑
-orbiter-admin      orbiter-integration
-(this package)     (Astro, reads at build time)
+     ↑                       ↑
+@a83/orbiter-admin      @a83/orbiter-integration
+writes content           reads at Astro build time
+port 4322                your public site
 ```
 
+Run the admin on a VPS or a separate service. The Astro site can be deployed anywhere — Netlify, Vercel, static hosting — as long as it can reach the same `.pod` file (same server, shared volume, or periodic rsync).
+
+---
+
+## Install
+
+```bash
+npm install @a83/orbiter-admin
+```
+
+Requires **Node.js 20+**.
+
 ---
 
 ## Start
 
 ```bash
-ORBITER_POD=/absolute/path/to/content.pod npm start
+ORBITER_POD=/absolute/path/to/content.pod npx @a83/orbiter-admin
 ```
 
-Development (auto-reload on changes):
+Or add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "admin": "orbiter-admin"
+  },
+  "dependencies": {
+    "@a83/orbiter-admin": "latest"
+  }
+}
+```
 
 ```bash
-ORBITER_POD=/absolute/path/to/content.pod npm run dev
+ORBITER_POD=/absolute/path/to/content.pod npm run admin
 ```
 
-Opens at **http://localhost:4322**
+Opens at **[http://localhost:4322](http://localhost:4322)** — redirects to `/login.html`.
 
-> Use an absolute path. The server changes its working directory internally, so relative paths break.
+> **Use an absolute path** for `ORBITER_POD`. The server changes its working directory internally, so relative paths resolve incorrectly.
 
 ---
 
-## Demo
+## Demo (from the monorepo)
 
 ```bash
-# From the monorepo root
-npm run seed
+git clone https://github.com/aeon022/orbiter.git
+cd orbiter && npm install && npm run seed
 ORBITER_POD=$(pwd)/apps/demo/demo.pod npm run dev --workspace=packages/admin
 ```
 
@@ -47,50 +72,110 @@ Login: `admin` / `admin`
 
 ---
 
-## Env vars
+## Environment variables
 
-| Variable        | Required | Default       | Description                              |
-|-----------------|----------|---------------|------------------------------------------|
-| `ORBITER_POD`   | yes      | —             | Absolute path to the `.pod` file         |
-| `PORT`          | no       | `4322`        | HTTP port                                |
-| `ADMIN_ORIGIN`  | no       | `localhost:4321,localhost:4322` | Allowed CORS origins (comma-separated) |
+| Variable        | Required | Default | Description |
+|-----------------|----------|---------|-------------|
+| `ORBITER_POD`   | **yes**  | —       | Absolute path to the `.pod` file |
+| `PORT`          | no       | `4322`  | HTTP port |
+| `ADMIN_ORIGIN`  | no       | `*`     | Allowed CORS origins (comma-separated) |
 
 ---
 
 ## What's inside
 
-**Dashboard** — entry counts, recently edited content, notes, to-do list, build trigger.
+### Dashboard
+Entry counts per collection, recently updated entries, persistent scratchpad + to-do list, build webhook status and manual trigger.
+
+### Entry editor
+All schema fields rendered as inputs. Autosave, version history with restore, draft/published toggle.
+
+**Rich-media block editor:**
+- **Inline image blocks** — float left, right, center, or full width; text wraps naturally
+- **Video blocks** — paste a YouTube, Vimeo, Wistia, or direct `.mp4`/`.webm` URL; renders as responsive 16:9 embed
+- **`/` block picker** — type `/img` or `/vid` to insert
+- **Relation picker** — pick entries from another collection
+
+**Media picker — three tabs:**
+- **Library** — browse all uploaded files
+- **From URL** — paste a Dropbox, Google Drive, OneDrive, or any public URL; Orbiter fetches and stores the file server-side (bypasses CORS)
+- **External link** — paste a URL to store a reference without downloading; great for Cloudinary, hosted assets, or large files you don't want to copy
+
+### Media library
+Upload, browse, and manage files. Images, video, PDF, any file type. Folder categories, type filter, inline preview, copy URL, alt text. Configurable backend (see below).
+
+### Schema editor
+Add, reorder, and remove fields on any collection. Changes take effect immediately — no migration or restart needed.
+
+| Field type | Input |
+|------------|-------|
+| `string` | Single-line text |
+| `richtext` | Block editor |
+| `number` | Numeric |
+| `url` / `email` | With validation |
+| `date` / `datetime` | Date picker |
+| `select` | Dropdown |
+| `array` | Tag input |
+| `media` | Media library picker |
+| `relation` | Entry picker (cross-collection) |
+
+### Settings
+Site name, URL, locale, build webhook URL, media backend, GitHub sync, public API token, theme.
+
+### Users
+Create and manage admin/editor accounts (admin role only). Roles:
+
+| Feature | editor | admin |
+|---------|--------|-------|
+| Create / edit / delete entries | ✅ | ✅ |
+| Manage media | ✅ | ✅ |
+| Edit schema | ✅ | ✅ |
+| Site settings | ✅ | ✅ |
+| Manage users | ❌ | ✅ |
+
+### Import
+WordPress WXR importer — upload the `.xml` export from WordPress Tools → Export; Orbiter converts posts, pages, categories, tags, and featured images.
 
-**Collections** — browse and manage entries per collection.
+---
 
-**Editor** — all schema fields rendered as inputs, autosave, version history, draft/published toggle. Inline image blocks with float alignment (left/right/center/full). Video embedding — YouTube, Vimeo, Wistia, direct mp4/webm URL. Media picker with cloud URL import (Dropbox, Google Drive, OneDrive). Relation picker, conditional field visibility.
+## Build webhook
 
-**Media library** — upload, browse and manage files. Stored as BLOBs in the pod. Images, video, PDF, any file type.
+Configure a webhook URL in **Settings → Build**. Orbiter fires a `POST` to it:
+- **Automatically** — whenever an entry transitions from draft to published
+- **Manually** — via the **Trigger build** button on the dashboard
 
-**Schema** — add, reorder, and remove fields on any collection. Live changes, no restart.
+Works with Netlify build hooks, Vercel deploy hooks, and GitHub Actions `workflow_dispatch`.
 
-**Settings** — site name, URL, locale, API token, build webhook, theme.
+---
 
-**Users** — manage admin users (admin role only).
+## Media backends
 
-**Import** — WordPress WXR importer.
+Configure in **Settings → Media storage**. No restart required — stored in the pod.
+
+| Backend | Where files go | Best for |
+|---------|---------------|----------|
+| `blob` | SQLite BLOB in the `.pod` file (default) | Small–medium sites |
+| `local` | Directory on the server (`media.local_path`) | Self-hosted VPS with persistent disk |
+| `github` | GitHub Contents API → jsDelivr CDN | Open-source projects, free global CDN |
+| **External link** | URL stored, nothing fetched | Dropbox, Drive, Cloudinary, any public URL |
+
+For the **GitHub backend**, files are served from `cdn.jsdelivr.net/gh/owner/repo@branch/path` — no egress cost, cached globally. Configure repo, branch, directory, and token in Settings.
+
+For **External links**, use the External link tab in the image picker. Orbiter makes a `HEAD` request to detect mime type, then stores only the URL. `/orbiter/media/[id]` redirects — no change needed in templates.
 
 ---
 
 ## Themes
 
-Three themes, two schemes (dark / light), two layouts (classic / glass).
+Three themes × two schemes (dark/light) × two layouts (classic/glass). Switchable live — preference saved to `localStorage`.
 
-| Theme       | Character                              |
-|-------------|----------------------------------------|
-| Space       | Dark: space station HUD — cyan + blue  |
-|             | Light: solar command — ice blue        |
-| Zen         | Japandi — slate, mauve, moss           |
-| Catppuccin  | Mocha (dark) / Latte (light)           |
+| Theme | Dark | Light |
+|-------|------|-------|
+| **Space** | Space station HUD — cyan + electric blue | Solar Command — ice blue |
+| **Zen** | Japandi — slate, mauve, moss | Japandi light |
+| **Catppuccin** | Mocha | Latte |
 
-Glass layout is the default — frosted panels, backdrop blur, animated gradient background.
-
-Preference saved to `localStorage`.
+**Glass layout** (default) — frosted panels, backdrop blur, animated gradient orbs. Classic grid also available.
 
 ---
 
@@ -98,7 +183,26 @@ Preference saved to `localStorage`.
 
 ```bash
 curl http://localhost:4322/health
-# {"ok":true,"pod":"/path/to/content.pod"}
+# {"ok":true,"pod":"/absolute/path/to/content.pod"}
+```
+
+---
+
+## Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+RUN npm install @a83/orbiter-admin
+EXPOSE 4322
+CMD ["node", "node_modules/@a83/orbiter-admin/src/server.js"]
+```
+
+```bash
+docker run -p 4322:4322 \
+  -e ORBITER_POD=/data/content.pod \
+  -v $(pwd)/content.pod:/data/content.pod \
+  my-orbiter-admin
 ```
 
 ---
@@ -107,9 +211,9 @@ curl http://localhost:4322/health
 
 | Package | Description |
 |---------|-------------|
-| `@a83/orbiter-core` | SQLite engine, pod management, auth |
-| `@a83/orbiter-integration` | Astro integration, `orbiter:collections` virtual module |
-| `@a83/orbiter-admin` | This package — standalone admin server |
-| `@a83/orbiter-cli` | `orbiter init`, `add-user`, `export`, `pack`, `unpack` |
+| [`@a83/orbiter-core`](https://www.npmjs.com/package/@a83/orbiter-core) | SQLite engine, pod management, auth, media backends |
+| [`@a83/orbiter-admin`](https://www.npmjs.com/package/@a83/orbiter-admin) | **This package** — standalone admin server |
+| [`@a83/orbiter-integration`](https://www.npmjs.com/package/@a83/orbiter-integration) | Astro integration, `orbiter:collections` virtual module |
+| [`@a83/orbiter-cli`](https://www.npmjs.com/package/@a83/orbiter-cli) | `orbiter init`, `add-user`, `export`, `pack`, `unpack` |
 
-**orbiter.sh** · MIT · [github.com/aeon022/orbiter](https://github.com/aeon022/orbiter)
+**[orbiter.sh](https://orbiter.sh)** · MIT · [github.com/aeon022/orbiter](https://github.com/aeon022/orbiter)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a83/orbiter-admin",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Standalone admin server for Orbiter CMS",
   "type": "module",
   "main": "./src/server.js",
@@ -26,7 +26,7 @@
     "directory": "packages/admin"
   },
   "dependencies": {
-    "@a83/orbiter-core": "^0.2.0",
+    "@a83/orbiter-core": "^0.3.1",
     "@hono/node-server": "^1.14.4",
     "hono": "^4.7.11"
   }

package/public/editor.html

@@ -1378,7 +1378,8 @@
       document.querySelectorAll('.img-pick-pane').forEach(p=>p.classList.remove('active'));
       btn.classList.add('active');
       document.getElementById('img-pick-pane-'+tab).classList.add('active');
-      if (tab==='url') setTimeout(()=>document.getElementById('img-url-inp').focus(), 40);
+      if (tab==='url')  setTimeout(()=>document.getElementById('img-url-inp').focus(),  40);
+      if (tab==='link') setTimeout(()=>document.getElementById('img-link-inp').focus(), 40);
     };
 
     window.importFromUrl = async function() {
@@ -1411,6 +1412,36 @@
       if (e.key==='Enter') { e.preventDefault(); importFromUrl(); }
     });
 
+    window.addExternalLink = async function() {
+      const inp    = document.getElementById('img-link-inp');
+      const url    = inp.value.trim();
+      if (!url) return;
+      const btn    = document.getElementById('img-link-btn');
+      const status = document.getElementById('img-link-status');
+      btn.disabled=true; btn.textContent='Wird verknüpft…'; status.textContent='';
+      try {
+        const res = await fetch('/api/media/add-link', {
+          method:'POST', credentials:'include',
+          headers:{'Content-Type':'application/json'},
+          body: JSON.stringify({ url, alt:'', folder:'' })
+        });
+        if (!res.ok) { const e=await res.json().catch(()=>({})); status.textContent='Fehler: '+(e.error||res.status); return; }
+        const media = await res.json();
+        mediaData.unshift(media);
+        closeImgPicker();
+        doInsertImg(media.id, media.alt??'');
+        inp.value='';
+      } catch(e) {
+        status.textContent='Netzwerkfehler: '+e.message;
+      } finally {
+        btn.disabled=false; btn.textContent='Verknüpfen';
+      }
+    };
+
+    document.getElementById('img-link-inp').addEventListener('keydown', e=>{
+      if (e.key==='Enter') { e.preventDefault(); addExternalLink(); }
+    });
+
     function escHtml(str) {
       return String(str??'').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
     }
@@ -1540,6 +1571,7 @@
       <div class="img-pick-tabs">
         <button class="img-pick-tab active" onclick="imgPickTab('library',this)">Library</button>
         <button class="img-pick-tab" onclick="imgPickTab('url',this)">From URL</button>
+        <button class="img-pick-tab" onclick="imgPickTab('link',this)">External link</button>
       </div>
       <div id="img-pick-pane-library" class="img-pick-pane active">
         <div class="img-pick-body">
@@ -1559,6 +1591,18 @@
           <button id="img-url-btn" class="img-url-btn" onclick="importFromUrl()">Importieren</button>
         </div>
       </div>
+      <div id="img-pick-pane-link" class="img-pick-pane">
+        <div class="img-url-pane">
+          <input id="img-link-inp" class="img-url-inp" type="url" placeholder="https://…" />
+          <div class="img-url-hint">
+            Datei bleibt extern — Orbiter speichert nur den Link.<br>
+            <strong>Dropbox</strong>, <strong>Google Drive</strong>, <strong>OneDrive</strong>,
+            <strong>Cloudinary</strong>, jede öffentlich zugängliche URL.
+          </div>
+          <div id="img-link-status" class="img-url-status"></div>
+          <button id="img-link-btn" class="img-url-btn" onclick="addExternalLink()">Verknüpfen</button>
+        </div>
+      </div>
     </div>
   </div>
   <input type="file" id="img-file-inp" accept="image/*" style="display:none">

package/public/settings.html

@@ -363,6 +363,72 @@
           </div>
         </div>
 
+        <div class="settings-group">
+          <div class="group-header">Media storage</div>
+          <div class="setting-row">
+            <div><div class="setting-label">Backend</div><div class="setting-desc">Where uploaded files are stored</div></div>
+            <select class="input" name="media.backend" id="media-backend-select">
+              <option value="blob"   ${(get('media.backend')||'blob')==='blob'   ? 'selected':''}>blob — SQLite BLOB (default)</option>
+              <option value="local"  ${get('media.backend')==='local'  ? 'selected':''}>local — filesystem</option>
+              <option value="github" ${get('media.backend')==='github' ? 'selected':''}>github — GitHub + jsDelivr CDN</option>
+              <option value="s3"     ${get('media.backend')==='s3'     ? 'selected':''}>s3 — S3-compatible (AWS, R2, B2, MinIO)</option>
+            </select>
+          </div>
+
+          <div id="media-local-fields" style="display:none">
+            <div class="setting-row">
+              <div><div class="setting-label">Local path</div><div class="setting-desc">Absolute or relative path on the server</div></div>
+              <input class="input" name="media.local_path" value="${get('media.local_path')}" placeholder="./media" />
+            </div>
+          </div>
+
+          <div id="media-s3-fields" style="display:none">
+            <div class="setting-row">
+              <div><div class="setting-label">Bucket</div></div>
+              <input class="input" name="media.s3_bucket" value="${get('media.s3_bucket')}" placeholder="my-media-bucket" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Region</div><div class="setting-desc">AWS region or "auto" for R2</div></div>
+              <input class="input" name="media.s3_region" value="${get('media.s3_region')||'auto'}" placeholder="eu-central-1" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Endpoint</div><div class="setting-desc">Custom endpoint for R2, B2, MinIO — leave blank for AWS</div></div>
+              <input class="input" name="media.s3_endpoint" value="${get('media.s3_endpoint')}" placeholder="https://xxxx.r2.cloudflarestorage.com" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Access Key ID</div></div>
+              <input class="input" type="password" name="media.s3_access_key" value="${get('media.s3_access_key')}" autocomplete="off" placeholder="Access key ID" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Secret Access Key</div></div>
+              <input class="input" type="password" name="media.s3_secret_key" value="${get('media.s3_secret_key')}" autocomplete="off" placeholder="Secret access key" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Public URL</div><div class="setting-desc">Base URL for serving files, e.g. your R2 public domain or CDN</div></div>
+              <input class="input" name="media.s3_public_url" value="${get('media.s3_public_url')}" placeholder="https://media.example.com" />
+            </div>
+          </div>
+
+          <div id="media-github-fields" style="display:none">
+            <div class="setting-row">
+              <div><div class="setting-label">GitHub token</div><div class="setting-desc">Uses the token from the GitHub section above if left blank</div></div>
+              <input class="input" type="password" name="media.github_token" value="${get('media.github_token')}" autocomplete="off" placeholder="ghp_… (optional, falls back to GitHub token above)" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Repository</div><div class="setting-desc">owner/repo — can differ from your content repo</div></div>
+              <input class="input" name="media.github_repo" value="${get('media.github_repo')}" placeholder="owner/my-media" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Branch</div></div>
+              <input class="input" name="media.github_branch" value="${get('media.github_branch')||'main'}" placeholder="main" />
+            </div>
+            <div class="setting-row">
+              <div><div class="setting-label">Directory</div><div class="setting-desc">Subdirectory inside the repo</div></div>
+              <input class="input" name="media.github_dir" value="${get('media.github_dir')||'media'}" placeholder="media" />
+            </div>
+          </div>
+        </div>
+
         <div class="save-row">
           <button type="submit" class="btn-save">Save settings</button>
         </div>
@@ -546,22 +612,44 @@
       </div>
     `;
 
+    // Media backend: show/hide conditional fields
+    function updateMediaFields() {
+      const v = document.getElementById('media-backend-select')?.value ?? 'blob';
+      document.getElementById('media-local-fields').style.display  = v === 'local'  ? '' : 'none';
+      document.getElementById('media-s3-fields').style.display     = v === 's3'     ? '' : 'none';
+      document.getElementById('media-github-fields').style.display = v === 'github' ? '' : 'none';
+    }
+    document.getElementById('media-backend-select')?.addEventListener('change', updateMediaFields);
+    updateMediaFields();
+
     // Site form
     document.getElementById('site-form').addEventListener('submit', async e => {
       e.preventDefault();
       const fd = new FormData(e.target);
       await saveMeta([
-        ['site.name',        fd.get('site.name')],
-        ['site.url',         fd.get('site.url')],
-        ['site.description', fd.get('site.description')],
-        ['site.locale',      fd.get('site.locale')],
-        ['site.locales',     fd.get('site.locales')],
-        ['build.webhook_url',fd.get('build.webhook_url')],
-        ['github.token',     fd.get('github.token')],
-        ['github.repo',      fd.get('github.repo')],
-        ['github.branch',    fd.get('github.branch')],
-        ['api.enabled',      fd.get('api.enabled') ? '1' : '0'],
-        ['api.token',        fd.get('api.token')],
+        ['site.name',           fd.get('site.name')],
+        ['site.url',            fd.get('site.url')],
+        ['site.description',    fd.get('site.description')],
+        ['site.locale',         fd.get('site.locale')],
+        ['site.locales',        fd.get('site.locales')],
+        ['build.webhook_url',   fd.get('build.webhook_url')],
+        ['github.token',        fd.get('github.token')],
+        ['github.repo',         fd.get('github.repo')],
+        ['github.branch',       fd.get('github.branch')],
+        ['media.backend',       fd.get('media.backend')],
+        ['media.local_path',    fd.get('media.local_path')],
+        ['media.github_token',  fd.get('media.github_token')],
+        ['media.github_repo',   fd.get('media.github_repo')],
+        ['media.github_branch', fd.get('media.github_branch')],
+        ['media.github_dir',    fd.get('media.github_dir')],
+        ['media.s3_bucket',     fd.get('media.s3_bucket')],
+        ['media.s3_region',     fd.get('media.s3_region')],
+        ['media.s3_endpoint',   fd.get('media.s3_endpoint')],
+        ['media.s3_access_key', fd.get('media.s3_access_key')],
+        ['media.s3_secret_key', fd.get('media.s3_secret_key')],
+        ['media.s3_public_url', fd.get('media.s3_public_url')],
+        ['api.enabled',         fd.get('api.enabled') ? '1' : '0'],
+        ['api.token',           fd.get('api.token')],
       ]);
       showBanner('site-banner','banner-ok','Settings saved');
     });

package/src/routes/entries.js

@@ -3,6 +3,14 @@ import { openPod } from '@a83/orbiter-core';
 
 export const entryRoutes = new Hono();
 
+function fireWebhook(podPath) {
+  const db  = openPod(podPath);
+  const url = db.getMeta('build.webhook_url') ?? '';
+  db.setMeta('build.last_triggered', new Date().toISOString());
+  db.close();
+  if (url) fetch(url, { method: 'POST' }).catch(() => {});
+}
+
 // GET /api/collections/:id/entries?status=draft|published
 entryRoutes.get('/:collectionId/entries', (c) => {
   const { collectionId } = c.req.param();
@@ -45,11 +53,16 @@ entryRoutes.put('/:collectionId/entries/:slug', async (c) => {
   const { collectionId, slug } = c.req.param();
   const body = await c.req.json();
 
-  const db = openPod(c.get('podPath'));
-  const ok = db.updateEntry(collectionId, slug, body);
+  const db     = openPod(c.get('podPath'));
+  const before = db.getEntry(collectionId, slug);
+  const ok     = db.updateEntry(collectionId, slug, body);
   if (!ok) { db.close(); return c.json({ error: 'Not found' }, 404); }
   const updated = db.getEntry(collectionId, body.slug ?? slug);
   db.close();
+
+  if (body.status === 'published' && before?.status !== 'published') {
+    fireWebhook(c.get('podPath'));
+  }
   return c.json(updated);
 });
 
@@ -99,5 +112,6 @@ entryRoutes.patch('/:collectionId/entries/:slug/status', async (c) => {
   if (!entry) { db.close(); return c.json({ error: 'Not found' }, 404); }
   db.updateEntry(collectionId, slug, { slug, data: entry.data, status });
   db.close();
+  if (status === 'published') fireWebhook(c.get('podPath'));
   return c.json({ ok: true });
 });

package/src/routes/media.js

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { openPod } from '@a83/orbiter-core';
+import { openPod, getMediaBackend } from '@a83/orbiter-core';
 import { randomUUID } from 'node:crypto';
 
 export const mediaRoutes = new Hono();
@@ -13,12 +13,34 @@ mediaRoutes.get('/', (c) => {
   return c.json(items);
 });
 
-// GET /api/media/:id/raw  — serve the binary
-mediaRoutes.get('/:id/raw', (c) => {
-  const db   = openPod(c.get('podPath'));
-  const item = db.getMediaItem(c.req.param('id'));
+// GET /api/media/:id/raw  — serve binary or redirect to CDN
+mediaRoutes.get('/:id/raw', async (c) => {
+  const db      = openPod(c.get('podPath'));
+  const item    = db.getMediaItem(c.req.param('id'));
+  if (!item) { db.close(); return c.json({ error: 'Not found' }, 404); }
+
+  // External backends: redirect to CDN/storage URL
+  if (item.url) {
+    db.close();
+    return c.redirect(item.url, 302);
+  }
+
+  // Local backend: read from disk
+  if (item.path) {
+    const backend = getMediaBackend(db);
+    const result  = await backend.get(item.id).catch(() => null);
+    db.close();
+    if (!result?.data) return c.json({ error: 'File not found on disk' }, 404);
+    return new Response(result.data, {
+      headers: {
+        'Content-Type':  item.mime_type,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      },
+    });
+  }
+
+  // Default: serve BLOB from SQLite
   db.close();
-  if (!item) return c.json({ error: 'Not found' }, 404);
   return new Response(item.data, {
     headers: {
       'Content-Type':  item.mime_type,
@@ -29,25 +51,31 @@ mediaRoutes.get('/:id/raw', (c) => {
 
 // POST /api/media  — multipart upload
 mediaRoutes.post('/', async (c) => {
-  const form     = await c.req.formData();
-  const file     = form.get('file');
-  const alt      = form.get('alt')?.toString()    ?? null;
-  const folder   = form.get('folder')?.toString() ?? '';
+  const form   = await c.req.formData();
+  const file   = form.get('file');
+  const alt    = form.get('alt')?.toString()    ?? null;
+  const folder = form.get('folder')?.toString() ?? '';
 
   if (!file || typeof file === 'string') return c.json({ error: 'No file provided' }, 400);
 
-  const buffer   = Buffer.from(await file.arrayBuffer());
-  const id       = randomUUID();
-  const db       = openPod(c.get('podPath'));
-  db.insertMedia(id, file.name, file.type, buffer.byteLength, buffer, alt, folder);
-  const item = db.getMediaItem(id);
-  db.close();
+  const buffer  = Buffer.from(await file.arrayBuffer());
+  const id      = randomUUID();
+  const db      = openPod(c.get('podPath'));
 
-  const { data: _, ...meta } = item;
-  return c.json(meta, 201);
+  try {
+    const backend = getMediaBackend(db);
+    await backend.upload(id, file.name, file.type, buffer.byteLength, buffer, alt, folder);
+    const item    = db.getMediaItem(id);
+    db.close();
+    const { data: _, ...meta } = item;
+    return c.json(meta, 201);
+  } catch (err) {
+    db.close();
+    return c.json({ error: err.message }, 500);
+  }
 });
 
-// POST /api/media/import-url  — server-side fetch from a public URL (Dropbox, GDrive, etc.)
+// POST /api/media/import-url  — server-side fetch from a public URL
 mediaRoutes.post('/import-url', async (c) => {
   let body;
   try { body = await c.req.json(); } catch { return c.json({ error: 'Invalid JSON' }, 400); }
@@ -76,20 +104,64 @@ mediaRoutes.post('/import-url', async (c) => {
   const filename = url.split('/').pop()?.split('?')[0] || 'imported';
   const id       = randomUUID();
   const db       = openPod(c.get('podPath'));
-  db.insertMedia(id, filename, mime, buffer.byteLength, buffer, alt ?? null, folder ?? '');
+
+  try {
+    const backend = getMediaBackend(db);
+    await backend.upload(id, filename, mime, buffer.byteLength, buffer, alt ?? null, folder ?? '');
+    const item    = db.getMediaItem(id);
+    db.close();
+    const { data: _, ...meta } = item;
+    return c.json(meta, 201);
+  } catch (err) {
+    db.close();
+    return c.json({ error: err.message }, 500);
+  }
+});
+
+// POST /api/media/add-link  — store an external URL reference, no data fetched
+mediaRoutes.post('/add-link', async (c) => {
+  let body;
+  try { body = await c.req.json(); } catch { return c.json({ error: 'Invalid JSON' }, 400); }
+  const { url, alt, folder, filename: providedName } = body;
+  if (!url) return c.json({ error: 'No URL provided' }, 400);
+
+  // Detect mime via HEAD request, fall back to extension sniffing
+  let mime = 'application/octet-stream';
+  try {
+    const head = await fetch(url, { method: 'HEAD', redirect: 'follow', headers: { 'User-Agent': 'Orbiter-Admin/1.0' } });
+    const ct = head.headers.get('content-type');
+    if (ct) mime = ct.split(';')[0].trim();
+  } catch {
+    const ext = url.split('?')[0].split('.').pop()?.toLowerCase();
+    const extMap = { jpg:'image/jpeg', jpeg:'image/jpeg', png:'image/png', gif:'image/gif',
+                     webp:'image/webp', avif:'image/avif', svg:'image/svg+xml',
+                     mp4:'video/mp4', webm:'video/webm', pdf:'application/pdf' };
+    if (extMap[ext]) mime = extMap[ext];
+  }
+
+  const filename = providedName || url.split('/').pop()?.split('?')[0] || 'link';
+  const id       = randomUUID();
+  const db       = openPod(c.get('podPath'));
+  db.insertMedia(id, filename, mime, 0, null, alt ?? null, folder ?? '', url, null);
   const item = db.getMediaItem(id);
   db.close();
-
   const { data: _, ...meta } = item;
   return c.json(meta, 201);
 });
 
 // DELETE /api/media/:id
-mediaRoutes.delete('/:id', (c) => {
+mediaRoutes.delete('/:id', async (c) => {
   const db   = openPod(c.get('podPath'));
   const item = db.getMediaItem(c.req.param('id'));
   if (!item) { db.close(); return c.json({ error: 'Not found' }, 404); }
-  db.deleteMedia(item.id);
-  db.close();
-  return c.json({ ok: true });
+
+  try {
+    const backend = getMediaBackend(db);
+    await backend.delete(item.id);
+    db.close();
+    return c.json({ ok: true });
+  } catch (err) {
+    db.close();
+    return c.json({ error: err.message }, 500);
+  }
 });

package/src/routes/meta.js

@@ -7,6 +7,9 @@ const ALLOWED_KEYS = [
   'site.name', 'site.url', 'site.description', 'site.locale', 'site.locales',
   'build.webhook_url',
   'github.token', 'github.repo', 'github.branch',
+  'media.backend', 'media.local_path',
+  'media.github_token', 'media.github_repo', 'media.github_branch', 'media.github_dir',
+  'media.s3_bucket', 'media.s3_region', 'media.s3_endpoint', 'media.s3_access_key', 'media.s3_secret_key', 'media.s3_public_url',
   'api.enabled', 'api.token',
   'dashboard.notes', 'dashboard.todos',
   'ui.theme',