Run Locally: relative asset base + launcher scripts so the unzipped app works

- vite base '/' -> './' so built asset (CSS/JS/worker) paths are relative and
  resolve from any folder — fixes the unzipped copy where absolute /assets/*
  404'd when index.html was opened outside the domain root.
- zip now ships start.command / start.sh / start.bat launchers (start a local
  server + open the browser) and a clearer RUN-LOCALLY.txt explaining a server
  is required (browsers block modules + workers over file://).

Relative base is safe on the live site too (served from root).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kinlane

tools/zip-dist.mjs

@@ -2,8 +2,12 @@
 // the "Run Locally" button can hand a user the whole app as a static bundle they
 // serve themselves. Runs after `vite build`; uses the system `zip` (present on
 // macOS and the ubuntu CI runner).
+//
+// The build uses a relative base ('./'), so assets resolve from any folder. The
+// app still needs a real HTTP server — browsers block ES modules and web workers
+// over file:// — so we include double-clickable launchers + a how-to.
 import { execSync } from 'node:child_process';
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, writeFileSync, chmodSync } from 'node:fs';
 
 const OUT = 'api-validator.zip';
 
@@ -12,7 +16,7 @@ if (!existsSync('dist')) {
   process.exit(1);
 }
 
-// A short how-to that travels inside the archive.
+// How-to that travels inside the archive.
 writeFileSync(
   'dist/RUN-LOCALLY.txt',
   [
@@ -21,23 +25,57 @@ writeFileSync(
     'This is the fully built, static app. It runs entirely in your browser; there',
     'is no backend and no keys are required.',
     '',
-    '1. Unzip this archive.',
-    '2. From the unzipped folder, start any static web server at the folder ROOT:',
+    'IMPORTANT: you must serve the folder over http — you cannot just double-click',
+    'index.html. Browsers block JavaScript modules and web workers over file://,',
+    'so the page would load but the app would not run.',
     '',
-    '     python3 -m http.server 8000',
-    '   or',
-    '     npx serve .',
+    'Easiest: double-click the launcher for your OS (it starts a local server and',
+    'opens your browser):',
+    '   • macOS:    start.command',
+    '   • Windows:  start.bat',
+    '   • Linux:    start.sh   (or run it in a terminal)',
     '',
-    '3. Open http://localhost:8000/ in your browser.',
-    '',
-    '(Opening index.html directly via file:// will not work — ES modules need to be',
-    'served over http, so use a local server as above.)',
+    'Or do it by hand, from inside this folder:',
+    '   python3 -m http.server 8000      # then open http://localhost:8000/',
+    '   # or:  npx serve .',
     '',
     'Source: https://github.com/api-commons/api-validator',
     '',
   ].join('\n'),
 );
 
+// macOS / Linux launcher — serve this folder and open the browser.
+writeFileSync(
+  'dist/start.command',
+  [
+    '#!/bin/bash',
+    'cd "$(dirname "$0")"',
+    'PORT=8000',
+    'URL="http://localhost:$PORT/"',
+    'echo "Serving API Validator at $URL  (press Ctrl+C to stop)"',
+    '( sleep 1; (command -v open >/dev/null && open "$URL") || (command -v xdg-open >/dev/null && xdg-open "$URL") ) &',
+    'python3 -m http.server "$PORT" 2>/dev/null || python -m http.server "$PORT"',
+    '',
+  ].join('\n'),
+);
+// A plain .sh alias for Linux users who prefer it.
+writeFileSync('dist/start.sh', 'exec "$(dirname "$0")/start.command"\n');
+chmodSync('dist/start.command', 0o755);
+chmodSync('dist/start.sh', 0o755);
+
+// Windows launcher.
+writeFileSync(
+  'dist/start.bat',
+  [
+    '@echo off',
+    'cd /d "%~dp0"',
+    'set PORT=8000',
+    'start "" "http://localhost:%PORT%/"',
+    'py -m http.server %PORT% 2>nul || python -m http.server %PORT%',
+    '',
+  ].join('\r\n'),
+);
+
 // Build the archive from inside dist/ (so paths are relative), excluding any
 // pre-existing zip. -X drops extra macOS metadata for a clean cross-platform zip.
 // Never fail the build over the optional archive — the site still deploys.

vite.config.ts

@@ -1,9 +1,11 @@
 import { defineConfig } from 'vite';
 import { nodePolyfills } from 'vite-plugin-node-polyfills';
 
-// Static SPA served from a custom domain (validator.spotlight-rules.com), so base '/'.
+// Static SPA. Use a RELATIVE base ('./') so the built assets resolve no matter
+// where the app is served from — the custom domain root (validator.apicommons.org)
+// AND an unzipped "Run Locally" copy served from any folder.
 export default defineConfig({
-  base: '/',
+  base: './',
   plugins: [
     nodePolyfills({
       // The Spotlight (Spectral) engine pulls in a few Node built-ins.