sitedrift 0.2.0 → 0.3.1

package/AGENTS.md

@@ -59,6 +59,11 @@ only when the host cannot run MCP.
 5. Re-list notes after code changes. Resolve only findings you verified.
 6. Remove or clear notes only when the user explicitly requests it.
 
+Hosted Cloudflare preview deployments are a different mode: their notes are
+browser-local and intentionally unavailable to MCP. Use browser inspection for
+those URLs. Do not claim that a hosted note was shared with an agent or written
+to the project.
+
 ## MCP tools
 
 - `sitedrift_context`: active targets, viewer URL, and capabilities.
@@ -99,3 +104,9 @@ sitedrift --https
 sitedrift accepts loopback hosts only. The control API uses a random bearer
 token stored in `~/.sitedrift/sessions/<port>.json` with mode `0600`. DEV and
 LIVE render on separate origins. Never expose sitedrift through a public proxy.
+
+The optional Cloudflare Pages addon is intentionally public-preview safe: it is
+installed only on non-production builds, exposes only `/__sitedrift/*`, permits
+only `GET` and `HEAD`, allowlists one configured live origin, and sandboxes both
+frames without same-origin authority. Production output and existing API
+Functions are unchanged.

package/README.md

@@ -66,6 +66,42 @@ mkcert isn't found it falls back to an `openssl` self-signed cert and prints the
 one command to trust it on your OS. Already have a cert? Skip all of this and
 pass `--cert <file> --key <file>`.
 
+### Cloudflare preview deployments
+
+Turn every non-production Cloudflare Pages deployment into a compact sitedrift
+review URL. The deployment opens its own preview in DEV Solo mode and can switch
+to Split, Overlay, or Diff against the configured production site.
+
+Install sitedrift and run the wrapper after your static build:
+
+```json
+{
+  "scripts": {
+    "build": "astro build && sitedrift cloudflare --dir dist --live https://example.com"
+  },
+  "devDependencies": {
+    "sitedrift": "^0.3.0"
+  }
+}
+```
+
+Add one scoped Pages Function:
+
+```ts
+// functions/__sitedrift/[[path]].ts
+export { onRequest } from 'sitedrift/cloudflare';
+```
+
+That is the entire integration. On Cloudflare Pages, the wrapper activates only
+when `CF_PAGES=1` and `CF_PAGES_BRANCH` is not `main`. Production builds are
+left unchanged. Use `--production-branch <name>` when production is another
+branch.
+
+Hosted proxies are read-only (`GET`/`HEAD`), sandboxed without same-origin
+authority, and fixed to the configured live origin. Review notes stay in that
+browser's `localStorage`; they are not sent to an API, shared with agents, or
+written to disk. Existing application Functions keep their original routes.
+
 ---
 
 ## See the whole review loop
@@ -122,6 +158,9 @@ npm run docs:screenshots
   notes that appear live. Click a note to jump to its route, copy a per-note
   deep link, dock or float the drawer, and **Send to vault** or export Markdown.
 - **No runtime dependencies.** Node standard library only.
+- **Deploy-preview mode for Cloudflare Pages.** Preview branches can carry the
+  compact comparison toolbar without changing production output or application
+  API routes.
 
 ### Keyboard
 

package/assets/viewer.css

@@ -627,6 +627,9 @@ iframe { display: block; inline-size: 100%; block-size: 100%; border: 0; backgro
 
   &.open { transform: translateX(0); }
 }
+.review-drawer:has(.local-notes-notice:not([hidden])) {
+  grid-template-rows: auto auto minmax(0, 1fr) auto;
+}
 .drawer-head {
   display: flex;
   align-items: center;
@@ -638,6 +641,16 @@ iframe { display: block; inline-size: 100%; block-size: 100%; border: 0; backgro
   & .icon { inline-size: 30px; block-size: 30px; }
   & .icon.active { color: #fff; background: var(--active); border-color: var(--active-line); }
 }
+.local-notes-notice {
+  margin: 12px 16px 0;
+  padding: 9px 10px;
+  color: var(--muted);
+  background: color-mix(in srgb, var(--field) 82%, transparent);
+  border: 1px solid var(--line);
+  border-radius: var(--r);
+  font-size: 12px;
+  line-height: 1.45;
+}
 
 .note-list {
   margin: 0;

package/assets/viewer.html

@@ -140,6 +140,7 @@
       </button>
       <button class="icon" data-action="notes-close" aria-label="Close notes">×</button>
     </div>
+    <p class="local-notes-notice" hidden>Stored only in this browser. These notes are not shared with agents or written to disk.</p>
     <ol class="note-list"></ol>
     <div class="note-compose">
       <div class="note-grip" title="Drag to resize" aria-hidden="true"></div>

package/assets/viewer.js

@@ -1,5 +1,12 @@
-const config = window.__SITEDRIFT_CONFIG__;
+    const config = window.__SITEDRIFT_CONFIG__;
     delete window.__SITEDRIFT_CONFIG__;
+    if (config.hosted) {
+      config.dev = location.origin;
+      config.frameOrigins = { dev: location.origin, live: location.origin };
+      for (const iframe of document.querySelectorAll('iframe[data-side]')) {
+        iframe.setAttribute('sandbox', 'allow-downloads allow-forms allow-modals allow-popups allow-popups-to-escape-sandbox allow-scripts');
+      }
+    }
     const root = document.documentElement;
     const app = document.querySelector('.app');
     const routeInput = document.querySelector('.route');
@@ -26,18 +33,19 @@ const config = window.__SITEDRIFT_CONFIG__;
     if (!['exact', 'ratio'].includes(scrollMode)) scrollMode = 'exact';
     let mirrorLinks = queryOrStoredBool('mirror', 'site-compare-mirror', false);
     let mobileMode = (params.get('mode') || localStorage.getItem('site-compare-mode')) === 'mobile';
-    let compactMode = queryOrStoredBool('compact', 'site-compare-compact', false);
+    let compactMode = queryOrStoredBool('compact', 'site-compare-compact', !!config.hosted);
     const storedView = localStorage.getItem('site-compare-view');
     let viewMode = params.get('view')
       || (params.get('overlay') === '1' ? 'overlay' : params.get('solo') === '1' ? 'solo' : null)
       || storedView
+      || (config.hosted ? 'solo' : null)
       || (innerWidth <= 600 ? 'solo' : 'split');
     let overlayBlend = (params.get('overlayBlend') || localStorage.getItem('site-compare-overlay-blend')) === 'difference' ? 'difference' : 'opacity';
     if (viewMode === 'diff') { viewMode = 'overlay'; overlayBlend = 'difference'; } // back-compat
     if (!['split', 'solo', 'overlay'].includes(viewMode)) viewMode = 'split';
     let overlayAmount = Number(params.get('overlayAmount') ?? localStorage.getItem('site-compare-overlay-amount'));
     if (!Number.isFinite(overlayAmount)) overlayAmount = 50;
-    let focusSide = params.get('focus') === 'live' ? 'live' : params.get('focus') === 'dev' ? 'dev' : order[0];
+    let focusSide = params.get('focus') === 'live' ? 'live' : params.get('focus') === 'dev' ? 'dev' : 'dev';
     let reviewNotes = [];
     let notesSignature = '';
     let notesOpen = params.get('notes') === '1';
@@ -48,6 +56,7 @@ const config = window.__SITEDRIFT_CONFIG__;
       authorization: 'Bearer ' + config.token,
       'content-type': 'application/json',
     };
+    const localNotesKey = 'sitedrift-preview-notes:' + location.host + ':' + config.live;
 
     function queryOrStoredBool(queryName, storageName, fallback) {
       if (params.has(queryName)) return params.get(queryName) === '1';
@@ -67,11 +76,19 @@ const config = window.__SITEDRIFT_CONFIG__;
     }
 
     function frame(side) { return document.querySelector('iframe[data-side="' + side + '"]'); }
-    function proxied(side, route) { return config.frameOrigins[side] + '/__' + side + normalizeRoute(route); }
-    function statusUrl(side, route) { return '/__' + side + normalizeRoute(route); }
-    function direct(side, route) { return config[side] + normalizeRoute(route); }
+    function proxyPath(side) { return config.hosted ? '/__sitedrift/' + side : '/__' + side; }
+    function proxied(side, route) { return config.frameOrigins[side] + proxyPath(side) + normalizeRoute(route); }
+    function statusUrl(side, route) { return proxyPath(side) + normalizeRoute(route); }
+    function direct(side, route) {
+      return config.hosted && side === 'dev'
+        ? location.origin + proxyPath(side) + normalizeRoute(route)
+        : config[side] + normalizeRoute(route);
+    }
     function framePost(side, type, data = {}) {
-      frame(side).contentWindow?.postMessage({ source: 'sitedrift-parent', side, type, ...data }, config.frameOrigins[side]);
+      frame(side).contentWindow?.postMessage(
+        { source: 'sitedrift-parent', side, type, ...data },
+        config.hosted ? '*' : config.frameOrigins[side],
+      );
     }
 
     function statusBadges(side) {
@@ -158,10 +175,34 @@ const config = window.__SITEDRIFT_CONFIG__;
       showToast.timer = setTimeout(() => toast.classList.remove('show'), 1600);
     }
 
-    function escapeHtml(value) {
-      return String(value || '').replace(/[&<>"']/g, (char) => ({
-        '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
-      })[char]);
+    function element(tag, className, text) {
+      const node = document.createElement(tag);
+      if (className) node.className = className;
+      if (text !== undefined) node.textContent = text;
+      return node;
+    }
+
+    function copyIcon() {
+      const ns = 'http://www.w3.org/2000/svg';
+      const svg = document.createElementNS(ns, 'svg');
+      svg.setAttribute('viewBox', '0 0 20 20');
+      svg.setAttribute('aria-hidden', 'true');
+      const path = document.createElementNS(ns, 'path');
+      path.setAttribute('d', 'M8 8V5.5A1.5 1.5 0 0 1 9.5 4h5A1.5 1.5 0 0 1 16 5.5v5A1.5 1.5 0 0 1 14.5 12H12');
+      path.setAttribute('fill', 'none');
+      path.setAttribute('stroke', 'currentColor');
+      path.setAttribute('stroke-width', '1.5');
+      const rect = document.createElementNS(ns, 'rect');
+      rect.setAttribute('x', '4');
+      rect.setAttribute('y', '8');
+      rect.setAttribute('width', '8');
+      rect.setAttribute('height', '8');
+      rect.setAttribute('rx', '1.5');
+      rect.setAttribute('fill', 'none');
+      rect.setAttribute('stroke', 'currentColor');
+      rect.setAttribute('stroke-width', '1.5');
+      svg.append(path, rect);
+      return svg;
     }
 
     function truncate(value, max) {
@@ -192,7 +233,7 @@ const config = window.__SITEDRIFT_CONFIG__;
       const siteName = source.siteName
         || config.brand
         || new URL(direct(side, route)).hostname;
-      const faviconSrc = source.icon || (config.frameOrigins[side] + '/__' + side + '/favicon.ico');
+      const faviconSrc = source.icon || (config.frameOrigins[side] + proxyPath(side) + '/favicon.ico');
       let canonicalPath = canonical;
       try { canonicalPath = new URL(canonical).pathname; } catch {}
       meta[side] = { title, description, canonicalPath, heading };
@@ -205,19 +246,35 @@ const config = window.__SITEDRIFT_CONFIG__;
       fav.onerror = () => { fav.onerror = null; fav.src = '/icon.svg'; };
       fav.src = faviconSrc;
       label.querySelector('.open-side').href = direct(side, route);
-      label.querySelector('.seo-card').innerHTML =
-        '<div class="seo-eyebrow">' + side.toUpperCase() + ' metadata preview</div>' +
-        '<div class="seo-source">' +
-          '<img class="seo-favicon" alt="" src="' + escapeHtml(faviconSrc) + '">' +
-          '<div><div class="seo-site">' + escapeHtml(siteName) + '</div>' +
-          '<div class="seo-url" data-seo="url">' + escapeHtml(crumb(canonical)) + '</div></div>' +
-          '<div class="seo-menu" aria-hidden="true">⋮</div>' +
-        '</div>' +
-        '<div class="seo-title' + (title ? '' : ' seo-empty') + '" data-seo="title">' +
-          escapeHtml(truncate(title || 'Missing page title', 62)) + '</div>' +
-        '<div class="seo-description' + (description ? '' : ' seo-empty') + '" data-seo="desc">' +
-          escapeHtml(truncate(description || 'Missing meta description', 158)) + '</div>' +
-        seoChecksHtml(source.checks || []);
+      const card = label.querySelector('.seo-card');
+      const sourceRow = element('div', 'seo-source');
+      const seoFavicon = element('img', 'seo-favicon');
+      seoFavicon.alt = '';
+      seoFavicon.src = faviconSrc;
+      const sourceText = element('div');
+      sourceText.append(
+        element('div', 'seo-site', siteName),
+        element('div', 'seo-url', crumb(canonical)),
+      );
+      sourceText.lastChild.dataset.seo = 'url';
+      const menu = element('div', 'seo-menu', '⋮');
+      menu.setAttribute('aria-hidden', 'true');
+      sourceRow.append(seoFavicon, sourceText, menu);
+      const seoTitle = element('div', `seo-title${title ? '' : ' seo-empty'}`, truncate(title || 'Missing page title', 62));
+      seoTitle.dataset.seo = 'title';
+      const seoDescription = element(
+        'div',
+        `seo-description${description ? '' : ' seo-empty'}`,
+        truncate(description || 'Missing meta description', 158),
+      );
+      seoDescription.dataset.seo = 'desc';
+      card.replaceChildren(
+        element('div', 'seo-eyebrow', `${side.toUpperCase()} metadata preview`),
+        sourceRow,
+        seoTitle,
+        seoDescription,
+        seoChecks(source.checks || []),
+      );
       const seoFav = label.querySelector('.seo-favicon');
       if (seoFav) seoFav.onerror = () => { seoFav.onerror = null; seoFav.src = '/icon.svg'; };
       const fails = (source.checks || []).filter((check) => !check.ok).length;
@@ -230,20 +287,25 @@ const config = window.__SITEDRIFT_CONFIG__;
       renderMetaDiff();
     }
 
-    function seoChecksHtml(checks) {
+    function seoChecks(checks) {
       const fails = checks.filter((check) => !check.ok).length;
-      const head = '<div class="seo-checks-head"><span>SEO checks</span>'
-        + (fails
-          ? '<span class="bad">' + fails + ' to fix</span>'
-          : '<span class="good">all good</span>')
-        + '</div>';
-      const rows = checks.map((check) =>
-        '<div class="seo-check ' + (check.ok ? 'ok' : 'bad') + '">'
-        + '<span class="seo-check-mark">' + (check.ok ? '✓' : '✗') + '</span>'
-        + '<span class="seo-check-label">' + escapeHtml(check.label) + '</span>'
-        + (check.note ? '<span class="seo-check-note">' + escapeHtml(check.note) + '</span>' : '')
-        + '</div>').join('');
-      return '<div class="seo-checks">' + head + rows + '</div>';
+      const container = element('div', 'seo-checks');
+      const head = element('div', 'seo-checks-head');
+      head.append(
+        element('span', '', 'SEO checks'),
+        element('span', fails ? 'bad' : 'good', fails ? `${fails} to fix` : 'all good'),
+      );
+      container.append(head);
+      for (const check of checks) {
+        const row = element('div', `seo-check ${check.ok ? 'ok' : 'bad'}`);
+        row.append(
+          element('span', 'seo-check-mark', check.ok ? '✓' : '✗'),
+          element('span', 'seo-check-label', check.label),
+        );
+        if (check.note) row.append(element('span', 'seo-check-note', check.note));
+        container.append(row);
+      }
+      return container;
     }
 
     function positionSeoCard(details) {
@@ -420,7 +482,7 @@ const config = window.__SITEDRIFT_CONFIG__;
       const message = event.data || {};
       const side = message.side;
       if (!['dev', 'live'].includes(side)
-        || event.origin !== config.frameOrigins[side]
+        || (!config.hosted && event.origin !== config.frameOrigins[side])
         || message.source !== 'sitedrift-frame'
         || event.source !== frame(side).contentWindow) return;
       if (message.type === 'ready') {
@@ -561,6 +623,10 @@ const config = window.__SITEDRIFT_CONFIG__;
     }
 
     async function notesPull() {
+      if (config.localNotes) {
+        try { applyNotes(JSON.parse(localStorage.getItem(localNotesKey) || '[]')); } catch { applyNotes([]); }
+        return;
+      }
       try {
         const res = await fetch(config.api + '/notes', { cache: 'no-store', headers: apiHeaders });
         const data = await res.json();
@@ -569,6 +635,29 @@ const config = window.__SITEDRIFT_CONFIG__;
     }
 
     async function notesPost(op) {
+      if (config.localNotes) {
+        let notes = [...reviewNotes];
+        if (op.op === 'add') {
+          notes.push({
+            id: crypto.randomUUID ? crypto.randomUUID() : String(Date.now()),
+            text: op.text,
+            author: op.author,
+            route: op.route,
+            side: op.side || null,
+            done: false,
+            createdAt: new Date().toISOString(),
+          });
+        } else if (op.op === 'toggle') {
+          notes = notes.map((note) => note.id === op.id ? { ...note, done: !note.done } : note);
+        } else if (op.op === 'remove') {
+          notes = notes.filter((note) => note.id !== op.id);
+        } else if (op.op === 'clear') {
+          notes = [];
+        }
+        localStorage.setItem(localNotesKey, JSON.stringify(notes));
+        applyNotes(notes);
+        return;
+      }
       try {
         const res = await fetch(config.api + '/notes', {
           method: 'POST',
@@ -632,7 +721,7 @@ const config = window.__SITEDRIFT_CONFIG__;
         copy.className = 'note-copy';
         copy.title = 'Copy a link to this note';
         copy.setAttribute('aria-label', 'Copy link to this note');
-        copy.innerHTML = '<svg viewBox="0 0 20 20" aria-hidden="true"><path d="M8 8V5.5A1.5 1.5 0 0 1 9.5 4h5A1.5 1.5 0 0 1 16 5.5v5A1.5 1.5 0 0 1 14.5 12H12" fill="none" stroke="currentColor" stroke-width="1.5"/><rect x="4" y="8" width="8" height="8" rx="1.5" fill="none" stroke="currentColor" stroke-width="1.5"/></svg>';
+        copy.append(copyIcon());
         copy.addEventListener('click', async () => {
           const url = new URL(location.href);
           url.searchParams.set('path', note.route || '/');
@@ -738,7 +827,15 @@ const config = window.__SITEDRIFT_CONFIG__;
     });
     document.querySelector('[data-action="note-export"]').addEventListener('click', () => {
       const link = document.createElement('a');
-      link.href = '/notes.md';
+      if (config.localNotes) {
+        const lines = ['# sitedrift review notes', ''];
+        for (const note of reviewNotes) {
+          lines.push(`- [${note.done ? 'x' : ' '}] ${note.text} (${note.side || 'both'} ${note.route || '/'})`);
+        }
+        link.href = URL.createObjectURL(new Blob([lines.join('\n') + '\n'], { type: 'text/markdown' }));
+      } else {
+        link.href = '/notes.md';
+      }
       link.download = 'site-compare-notes.md';
       link.click();
       showToast('Exported notes .md');
@@ -754,6 +851,8 @@ const config = window.__SITEDRIFT_CONFIG__;
         showToast('Vault save failed');
       }
     });
+    const localNotesNotice = document.querySelector('.local-notes-notice');
+    if (config.localNotes) localNotesNotice.hidden = false;
 
     divider.addEventListener('pointerdown', (event) => {
       divider.setPointerCapture(event.pointerId);
@@ -854,6 +953,6 @@ const config = window.__SITEDRIFT_CONFIG__;
     autosizeNote();
     setSplit(initialSplit);
     setMode(viewMode);
-    go(params.get('path') || '/');
+    go(params.get('path') || config.initialPath || '/');
     notesPull();
-    setInterval(notesPull, 4000);
+    if (!config.localNotes) setInterval(notesPull, 4000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sitedrift",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Catch the drift between dev and live — frame your local site and production side-by-side on the same route, locked scroll, with a difference-blend overlay. Zero runtime dependencies.",
   "type": "module",
   "bin": {
@@ -55,6 +55,9 @@
   "bugs": {
     "url": "https://github.com/joeseverino/sitedrift/issues"
   },
+  "exports": {
+    "./cloudflare": "./src/cloudflare-runtime.mjs"
+  },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
     "playwright": "^1.60.0"

package/sitedrift.mjs

@@ -6,6 +6,7 @@ import { openBrowser } from './src/browser.mjs';
 import { runAgentCommand } from './src/agent.mjs';
 import { createSession, removeSession, writeSession } from './src/session.mjs';
 import { runMcpServer } from './src/mcp.mjs';
+import { installCloudflarePreview } from './src/cloudflare.mjs';
 
 let command;
 let config;
@@ -19,6 +20,16 @@ try {
 
 if (command?.name === 'mcp') {
   runMcpServer();
+} else if (command?.name === 'cloudflare') {
+  try {
+    const result = installCloudflarePreview(command);
+    console.log(result.installed
+      ? `sitedrift: wrapped ${result.files} HTML files for Cloudflare preview ${result.branch}`
+      : `sitedrift: unchanged (${result.reason})`);
+  } catch (error) {
+    console.error(`sitedrift: ${error.message}`);
+    process.exit(1);
+  }
 } else {
   try {
     const parsed = parseCommand();

package/src/cli.mjs

@@ -7,7 +7,7 @@ const ALIASES = { d: 'dev', l: 'live', p: 'port', o: 'open', h: 'help', v: 'vers
 const BOOLEANS = new Set(['open', 'http', 'https', 'setup-https', 'help', 'version']);
 const VALUE_FLAGS = new Set([
   'dev', 'live', 'port', 'host', 'cert', 'key', 'notes', 'brand', 'author',
-  'vault', 'config', 'route', 'side',
+  'vault', 'config', 'route', 'side', 'dir', 'production-branch',
 ]);
 const KNOWN_FLAGS = new Set([...BOOLEANS, ...VALUE_FLAGS]);
 const CONFIG_NAMES = ['sitedrift.config.json', '.sitedriftrc.json'];
@@ -110,6 +110,7 @@ Usage:
   sitedrift status
   sitedrift context
   sitedrift mcp
+  sitedrift cloudflare --dir dist --live https://example.com
   sitedrift notes list
   sitedrift notes add <text> [--route /path] [--side dev|live] [--author name]
   sitedrift notes resolve|reopen|remove <id>
@@ -179,7 +180,22 @@ export function resolveConfig(argv = process.argv.slice(2)) {
 
 export function parseCommand(argv = process.argv.slice(2)) {
   const name = argv[0];
-  if (name !== 'status' && name !== 'context' && name !== 'notes' && name !== 'mcp') return null;
+  if (!['status', 'context', 'notes', 'mcp', 'cloudflare'].includes(name)) return null;
+  if (name === 'cloudflare') {
+    const { opts, positionals } = parseArgs(argv.slice(1));
+    if (positionals.length) throw new Error(`Unexpected argument: ${positionals[0]}`);
+    if (!opts.live) throw new Error('sitedrift cloudflare requires --live.');
+    return {
+      command: {
+        name,
+        dir: opts.dir || 'dist',
+        live: opts.live,
+        brand: opts.brand || '',
+        productionBranch: opts['production-branch'] || 'main',
+      },
+      argv: [],
+    };
+  }
   if (name === 'mcp') {
     if (argv.length > 1) throw new Error('Usage: sitedrift mcp');
     return { command: { name }, argv: [] };

package/src/cloudflare-runtime.mjs

@@ -0,0 +1,117 @@
+import { frameBridge, rewriteRootPaths } from './frame-content.mjs';
+
+const STRIP_HEADERS = [
+  'content-encoding',
+  'content-length',
+  'content-security-policy',
+  'content-security-policy-report-only',
+  'cross-origin-embedder-policy',
+  'cross-origin-opener-policy',
+  'cross-origin-resource-policy',
+  'transfer-encoding',
+  'x-frame-options',
+];
+
+function cleanHeaders(source) {
+  const headers = new Headers(source);
+  for (const name of STRIP_HEADERS) headers.delete(name);
+  headers.set('cache-control', 'no-store');
+  headers.set('x-robots-tag', 'noindex, nofollow');
+  return headers;
+}
+
+async function configFor(context) {
+  const url = new URL('/__sitedrift/config.json', context.request.url);
+  const response = await context.env.ASSETS.fetch(url);
+  if (!response.ok) throw new Error('sitedrift preview config is unavailable');
+  return response.json();
+}
+
+async function devResponse(context, route) {
+  const requestUrl = new URL(context.request.url);
+  const routeUrl = new URL(route, requestUrl);
+  const pathname = routeUrl.pathname;
+  const accept = context.request.headers.get('accept') || '';
+  if (context.request.method === 'GET' && accept.includes('text/html')) {
+    const clean = pathname.replace(/^\/+/, '');
+    const candidates = pathname.endsWith('/')
+      ? [`/__sitedrift/source/${clean}`]
+      : [`/__sitedrift/source/${clean}`, `/__sitedrift/source/${clean}/`];
+    if (pathname === '/') candidates.unshift('/__sitedrift/source/');
+    for (const pathname of candidates) {
+      const response = await context.env.ASSETS.fetch(new URL(pathname, requestUrl));
+      if (response.ok) return response;
+    }
+  }
+  return context.env.ASSETS.fetch(routeUrl);
+}
+
+async function liveResponse(context, route, live) {
+  const base = new URL(live);
+  const target = new URL(route, `${base.href.replace(/\/$/, '')}/`);
+  if (target.origin !== base.origin) return new Response('Invalid live target.', { status: 400 });
+  const headers = new Headers(context.request.headers);
+  headers.delete('host');
+  headers.delete('accept-encoding');
+  const init = {
+    method: context.request.method,
+    headers,
+    redirect: 'manual',
+  };
+  if (!['GET', 'HEAD'].includes(context.request.method)) init.body = context.request.body;
+  return fetch(target, init);
+}
+
+export async function onRequest(context) {
+  const requestUrl = new URL(context.request.url);
+  if (requestUrl.pathname.startsWith('/__sitedrift/source')) {
+    return new Response('Not found.', { status: 404 });
+  }
+  const match = requestUrl.pathname.match(/^\/__sitedrift\/(dev|live)(\/.*)?$/);
+  if (!match) return context.env.ASSETS.fetch(context.request);
+  if (!['GET', 'HEAD'].includes(context.request.method)) {
+    return new Response('sitedrift preview proxies are read-only.', {
+      status: 405,
+      headers: { allow: 'GET, HEAD' },
+    });
+  }
+
+  const side = match[1];
+  const route = `${match[2] || '/'}${requestUrl.search}`;
+  let upstream;
+  try {
+    const config = await configFor(context);
+    upstream = side === 'dev'
+      ? await devResponse(context, route)
+      : await liveResponse(context, route, config.live);
+  } catch (error) {
+    return new Response(`sitedrift: ${error.message}`, { status: 502 });
+  }
+
+  const headers = cleanHeaders(upstream.headers);
+  const location = upstream.headers.get('location');
+  if (location) {
+    const config = await configFor(context);
+    const base = side === 'live' ? new URL(config.live) : requestUrl;
+    const redirected = new URL(location, base);
+    if (side === 'dev' || redirected.origin === base.origin) {
+      headers.set('location', `/__sitedrift/${side}${redirected.pathname}${redirected.search}${redirected.hash}`);
+    }
+  }
+
+  const type = upstream.headers.get('content-type') || '';
+  const rewritable = /text\/html|text\/css|javascript/.test(type);
+  if (rewritable && context.request.method !== 'HEAD') {
+    let body = rewriteRootPaths(await upstream.text(), `/__sitedrift/${side}`);
+    if (/text\/html/.test(type)) {
+      const bridge = frameBridge(side, `/__sitedrift/${side}`);
+      body = body.includes('</head>') ? body.replace('</head>', `${bridge}</head>`) : `${bridge}${body}`;
+    }
+    return new Response(body, { status: upstream.status, statusText: upstream.statusText, headers });
+  }
+  return new Response(context.request.method === 'HEAD' ? null : upstream.body, {
+    status: upstream.status,
+    statusText: upstream.statusText,
+    headers,
+  });
+}

package/src/cloudflare.mjs

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { assets, renderHostedViewer } from './viewer.mjs';
+
+function htmlFiles(root) {
+  const found = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const file = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== '__sitedrift') found.push(...htmlFiles(file));
+    } else if (entry.isFile() && entry.name.endsWith('.html')) {
+      found.push(file);
+    }
+  }
+  return found;
+}
+
+function routeFor(relative) {
+  if (relative === 'index.html') return '/';
+  if (relative.endsWith('/index.html')) return `/${relative.slice(0, -'index.html'.length)}`;
+  return `/${relative.slice(0, -'.html'.length)}`;
+}
+
+function secureLive(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' && !['localhost', '127.0.0.1', '::1'].includes(url.hostname)) {
+    throw new Error('--live must use HTTPS.');
+  }
+  url.pathname = url.pathname.replace(/\/+$/, '');
+  url.search = '';
+  url.hash = '';
+  return url.href.replace(/\/$/, '');
+}
+
+export function installCloudflarePreview({
+  dir,
+  live,
+  brand = '',
+  productionBranch = 'main',
+  env = process.env,
+  force = false,
+}) {
+  const branch = env.CF_PAGES_BRANCH || '';
+  if (!force && (env.CF_PAGES !== '1' || !branch || branch === productionBranch)) {
+    return { installed: false, reason: branch === productionBranch ? 'production branch' : 'not a Pages preview' };
+  }
+
+  const output = path.resolve(dir);
+  if (!fs.existsSync(output)) throw new Error(`Build output does not exist: ${output}`);
+  const files = htmlFiles(output);
+  if (!files.length) throw new Error(`No HTML files found in ${output}`);
+
+  const liveUrl = secureLive(live);
+  const internal = path.join(output, '__sitedrift');
+  const source = path.join(internal, 'source');
+  const assetDir = path.join(internal, 'assets');
+  fs.mkdirSync(source, { recursive: true });
+  fs.mkdirSync(assetDir, { recursive: true });
+
+  for (const file of files) {
+    const relative = path.relative(output, file);
+    const preserved = path.join(source, relative);
+    fs.mkdirSync(path.dirname(preserved), { recursive: true });
+    fs.copyFileSync(file, preserved);
+    fs.writeFileSync(file, renderHostedViewer({
+      live: liveUrl,
+      brand,
+      initialPath: routeFor(relative),
+    }));
+  }
+
+  fs.writeFileSync(path.join(assetDir, 'viewer.css'), assets.css);
+  fs.writeFileSync(path.join(assetDir, 'viewer.js'), assets.js);
+  fs.writeFileSync(path.join(assetDir, 'icon.svg'), assets.icon);
+  fs.writeFileSync(path.join(internal, 'config.json'), JSON.stringify({ live: liveUrl }));
+  return { installed: true, branch: branch || 'forced', files: files.length };
+}

package/src/frame-content.mjs

@@ -0,0 +1,65 @@
+export function frameBridge(side, prefix = `/__${side}`) {
+  const script = `(() => {
+    const side=${JSON.stringify(side)},prefix=${JSON.stringify(prefix)};
+    let linked=false,mirror=false;
+    const send=(type,data={})=>parent.postMessage({source:'sitedrift-frame',side,type,...data},'*');
+    const root=()=>document.scrollingElement||document.documentElement;
+    const route=()=>location.pathname.replace(prefix,'')+location.search+location.hash||'/';
+    const snapshot=()=>{
+      const q=(s)=>document.querySelector(s);
+      const imgs=[...document.querySelectorAll('img')];
+      const title=(document.title||'').trim();
+      const description=q('meta[name="description"]')?.content?.trim()||'';
+      const canonical=q('link[rel="canonical"]')?.href||'';
+      const checks=[
+        ['Title present',!!title],['Title 30–60 chars',title.length>=30&&title.length<=60,title.length+''],
+        ['Meta description',!!description],['Description 70–160',description.length>=70&&description.length<=160,description.length+''],
+        ['Exactly one H1',document.querySelectorAll('h1').length===1,document.querySelectorAll('h1').length+' found'],
+        ['Canonical link',!!q('link[rel="canonical"]')],['Viewport meta',!!q('meta[name="viewport"]')],
+        ['html lang',!!document.documentElement.lang],['Open Graph title',!!q('meta[property="og:title"]')],
+        ['Open Graph image',!!q('meta[property="og:image"]')],
+        ['Not noindex',!(q('meta[name="robots"]')?.content||'').toLowerCase().includes('noindex')],
+        ['Favicon',!!q('link[rel~="icon"]')],
+        ['Images have alt',imgs.every((img)=>img.hasAttribute('alt')),imgs.filter((img)=>!img.hasAttribute('alt')).length+' missing']
+      ].map(([label,ok,note])=>({label,ok,note}));
+      send('ready',{route:route(),meta:{title,description,canonical,heading:q('h1')?.textContent?.trim()||'',
+        siteName:q('meta[property="og:site_name"]')?.content?.trim()||'',icon:q('link[rel~="icon"]')?.href||'',checks}});
+      send('scroll',{y:scrollY,max:Math.max(0,root().scrollHeight-innerHeight)});
+    };
+    addEventListener('message',(event)=>{
+      const msg=event.data||{};
+      if(msg.source!=='sitedrift-parent'||msg.side!==side)return;
+      if(msg.type==='settings'){linked=!!msg.linked;mirror=!!msg.mirror;document.documentElement.style.scrollBehavior='auto';}
+      if(msg.type==='scroll'){root().scrollTop=msg.y;}
+      if(msg.type==='reload')location.reload();
+    });
+    addEventListener('scroll',()=>send('scroll',{y:scrollY,max:Math.max(0,root().scrollHeight-innerHeight)}),{passive:true});
+    addEventListener('wheel',(event)=>{if(!linked||!event.deltaY)return;event.preventDefault();send('wheel',{delta:event.deltaY,mode:event.deltaMode,height:innerHeight,y:scrollY});},{passive:false,capture:true});
+    addEventListener('keydown',(event)=>{
+      const typing=/^(INPUT|TEXTAREA|SELECT)$/.test(event.target.tagName)||event.target.isContentEditable;
+      if(!typing&&!event.metaKey&&!event.ctrlKey&&!event.altKey&&['r','s','0','/','o','d'].includes(event.key.toLowerCase())){
+        event.preventDefault();send('key',{key:event.key.toLowerCase()});return;
+      }
+      if(linked&&!typing&&!event.metaKey&&!event.ctrlKey&&!event.altKey)send('key',{key:event.key,shift:event.shiftKey,y:scrollY,height:innerHeight,max:Math.max(0,root().scrollHeight-innerHeight)});
+    },true);
+    addEventListener('click',(event)=>{
+      if(!mirror||event.defaultPrevented||event.button!==0||event.metaKey||event.ctrlKey||event.shiftKey||event.altKey)return;
+      const link=event.target.closest('a[href]');if(!link||link.target==='_blank'||link.hasAttribute('download'))return;
+      const url=new URL(link.href,location.href);if(url.origin!==location.origin||!url.pathname.startsWith(prefix))return;
+      event.preventDefault();send('navigate',{route:url.pathname.slice(prefix.length)||'/'});
+    },true);
+    addEventListener('DOMContentLoaded',snapshot,{once:true});if(document.readyState!=='loading')snapshot();
+  })();`;
+  return `<script>${script.replace(/<\//g, '<\\/')}</script>`;
+}
+
+export function rewriteRootPaths(body, prefix) {
+  return body
+    .replace(/(\b(?:href|src|action|poster)=["'])\/(?!\/)/gi, `$1${prefix}/`)
+    .replace(/\bsrcset=(["'])(.*?)\1/gi, (attribute, quote, value) => {
+      const rewritten = value.replace(/(^|,\s*)\/(?!\/)/g, `$1${prefix}/`);
+      return `srcset=${quote}${rewritten}${quote}`;
+    })
+    .replace(/url\((["']?)\/(?!\/)/gi, `url($1${prefix}/`)
+    .replace(/(["'`])\/(@(?:id|vite|fs)\/|_astro\/)/g, `$1${prefix}/$2`);
+}

package/src/proxy.mjs

@@ -1,82 +1,16 @@
 import { send } from './http.mjs';
+import { frameBridge, rewriteRootPaths } from './frame-content.mjs';
 
 // Reverse-proxies the two origins under /__dev/* and /__live/*, rewriting
 // root-relative URLs so both sites render framed side-by-side. Deliberately
 // strips framing/isolation headers — safe for loopback development only.
 export function createProxy({ devBase, liveBase }) {
-  function bridge(side) {
-    const script = `(() => {
-      const side=${JSON.stringify(side)};
-      let linked=false, mirror=false;
-      const send=(type,data={})=>parent.postMessage({source:'sitedrift-frame',side,type,...data},'*');
-      const root=()=>document.scrollingElement||document.documentElement;
-      const route=()=>location.pathname.replace(/^\\/__${side}/,'')+location.search+location.hash||'/';
-      const snapshot=()=>{
-        const q=(s)=>document.querySelector(s);
-        const imgs=[...document.querySelectorAll('img')];
-        const title=(document.title||'').trim();
-        const description=q('meta[name="description"]')?.content?.trim()||'';
-        const canonical=q('link[rel="canonical"]')?.href||'';
-        const checks=[
-          ['Title present',!!title],['Title 30–60 chars',title.length>=30&&title.length<=60,title.length+''],
-          ['Meta description',!!description],['Description 70–160',description.length>=70&&description.length<=160,description.length+''],
-          ['Exactly one H1',document.querySelectorAll('h1').length===1,document.querySelectorAll('h1').length+' found'],
-          ['Canonical link',!!q('link[rel="canonical"]')],['Viewport meta',!!q('meta[name="viewport"]')],
-          ['html lang',!!document.documentElement.lang],['Open Graph title',!!q('meta[property="og:title"]')],
-          ['Open Graph image',!!q('meta[property="og:image"]')],
-          ['Not noindex',!(q('meta[name="robots"]')?.content||'').toLowerCase().includes('noindex')],
-          ['Favicon',!!q('link[rel~="icon"]')],
-          ['Images have alt',imgs.every((img)=>img.hasAttribute('alt')),imgs.filter((img)=>!img.hasAttribute('alt')).length+' missing']
-        ].map(([label,ok,note])=>({label,ok,note}));
-        send('ready',{route:route(),meta:{title,description,canonical,heading:q('h1')?.textContent?.trim()||'',
-          siteName:q('meta[property="og:site_name"]')?.content?.trim()||'',icon:q('link[rel~="icon"]')?.href||'',checks}});
-        send('scroll',{y:scrollY,max:Math.max(0,root().scrollHeight-innerHeight)});
-      };
-      addEventListener('message',(event)=>{
-        const msg=event.data||{};
-        if(msg.source!=='sitedrift-parent'||msg.side!==side)return;
-        if(msg.type==='settings'){linked=!!msg.linked;mirror=!!msg.mirror;document.documentElement.style.scrollBehavior='auto';}
-        if(msg.type==='scroll'){root().scrollTop=msg.y;}
-        if(msg.type==='reload')location.reload();
-      });
-      addEventListener('scroll',()=>send('scroll',{y:scrollY,max:Math.max(0,root().scrollHeight-innerHeight)}),{passive:true});
-      addEventListener('wheel',(event)=>{if(!linked||!event.deltaY)return;event.preventDefault();send('wheel',{delta:event.deltaY,mode:event.deltaMode,height:innerHeight,y:scrollY});},{passive:false,capture:true});
-      addEventListener('keydown',(event)=>{
-        const typing=/^(INPUT|TEXTAREA|SELECT)$/.test(event.target.tagName)||event.target.isContentEditable;
-        if(!typing&&!event.metaKey&&!event.ctrlKey&&!event.altKey&&['r','s','0','/','o','d'].includes(event.key.toLowerCase())){
-          event.preventDefault();send('key',{key:event.key.toLowerCase()});return;
-        }
-        if(linked&&!typing&&!event.metaKey&&!event.ctrlKey&&!event.altKey)send('key',{key:event.key,shift:event.shiftKey,y:scrollY,height:innerHeight,max:Math.max(0,root().scrollHeight-innerHeight)});
-      },true);
-      addEventListener('click',(event)=>{
-        if(!mirror||event.defaultPrevented||event.button!==0||event.metaKey||event.ctrlKey||event.shiftKey||event.altKey)return;
-        const link=event.target.closest('a[href]');if(!link||link.target==='_blank'||link.hasAttribute('download'))return;
-        const url=new URL(link.href,location.href);if(url.origin!==location.origin||!url.pathname.startsWith('/__'+side))return;
-        event.preventDefault();send('navigate',{route:url.pathname.slice(('/__'+side).length)||'/'});
-      },true);
-      addEventListener('DOMContentLoaded',snapshot,{once:true});if(document.readyState!=='loading')snapshot();
-    })();`;
-    return `<script>${script.replace(/<\//g, '<\\/')}</script>`;
-  }
-
   function targetFor(side, pathname, search) {
     const base = side === 'dev' ? devBase : liveBase;
     const relative = pathname.replace(new RegExp(`^/__${side}`), '') || '/';
     return new URL(`${relative}${search}`, `${base.href}/`);
   }
 
-  function rewriteRootPaths(body, side) {
-    const prefix = `/__${side}`;
-    return body
-      .replace(/(\b(?:href|src|action|poster)=["'])\/(?!\/)/gi, `$1${prefix}/`)
-      .replace(/\bsrcset=(["'])(.*?)\1/gi, (attribute, quote, value) => {
-        const rewritten = value.replace(/(^|,\s*)\/(?!\/)/g, `$1${prefix}/`);
-        return `srcset=${quote}${rewritten}${quote}`;
-      })
-      .replace(/url\((["']?)\/(?!\/)/gi, `url($1${prefix}/`)
-      .replace(/(["'`])\/(@(?:id|vite|fs)\/|_astro\/)/g, `$1${prefix}/$2`);
-  }
-
   async function proxy(req, res, side, requestUrl) {
     const target = targetFor(side, requestUrl.pathname, requestUrl.search);
     const headers = { ...req.headers, host: target.host };
@@ -121,9 +55,9 @@ export function createProxy({ devBase, liveBase }) {
       const rewritable = /text\/html|text\/css|javascript/.test(type)
         || (side === 'dev' && /application\/json/.test(type));
       if (rewritable) {
-        let body = rewriteRootPaths(await upstream.text(), side);
+        let body = rewriteRootPaths(await upstream.text(), `/__${side}`);
         if (/text\/html/.test(type)) {
-          const injected = bridge(side);
+          const injected = frameBridge(side);
           body = body.includes('</head>') ? body.replace('</head>', `${injected}</head>`) : `${injected}${body}`;
         }
         res.writeHead(upstream.status, responseHeaders);

package/src/viewer.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 
 // Bumped when the viewer assets change; busts the ?v= cache and reported in
 // /health so the `site compare` wrapper knows when to restart the server.
-export const VIEWER_VERSION = 28;
+export const VIEWER_VERSION = 29;
 
 function readAsset(path) {
   try {
@@ -30,9 +30,33 @@ export function renderViewer({ devBase, liveBase, brand, author, vaultDir }, ses
     token: session.token,
     api: '/api/v1',
     frameOrigins: session.frameUrls,
+    hosted: false,
   }).replace(/</g, '\\u003c');
 
   return assets.html
     .replaceAll('__VERSION__', String(VIEWER_VERSION))
     .replace('__CONFIG__', config);
 }
+
+export function renderHostedViewer({ live, brand = '', initialPath = '/' }) {
+  const config = JSON.stringify({
+    dev: '',
+    live,
+    brand,
+    author: 'you',
+    vault: false,
+    token: '',
+    api: '',
+    frameOrigins: { dev: '', live: '' },
+    hosted: true,
+    localNotes: true,
+    initialPath,
+  }).replace(/</g, '\\u003c');
+
+  return assets.html
+    .replaceAll('/icon.svg', '/__sitedrift/assets/icon.svg')
+    .replaceAll('/viewer.css', '/__sitedrift/assets/viewer.css')
+    .replaceAll('/viewer.js', '/__sitedrift/assets/viewer.js')
+    .replaceAll('__VERSION__', String(VIEWER_VERSION))
+    .replace('__CONFIG__', config);
+}