Run Locally: ship a self-contained single-file build (works via file://)

External ES-module scripts can't load over file:// (CORS/null origin), so the
unzipped app never booted on double-click. The "Run Locally" download is now a
single self-contained index.html:

- New SINGLEFILE=1 build target (vite-plugin-singlefile) -> dist-local/, inlining
  all JS + CSS into one file; Monaco workers inlined via ?worker&inline as blob
  workers; worker.format=iife for file:// compatibility.
- zip-dist packages dist-local/ into dist/api-validator.zip; RUN-LOCALLY.txt now
  just says "open index.html".
- getWorker wrapped in try/catch with a no-op fallback so a locked-down file://
  context can never break app boot (editor + Spectral lint still work).

The live site keeps the normal multi-chunk dist/ build.

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

Author: kinlane

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 .DS_Store
 *.log
+dist-local/

package-lock.json

@@ -8,7 +8,7 @@
   "scripts": {
     "compile-rules": "node tools/compile-rules.mjs",
     "dev": "vite",
-    "build": "vite build && node tools/zip-dist.mjs",
+    "build": "vite build && SINGLEFILE=1 vite build && node tools/zip-dist.mjs",
     "preview": "vite preview",
     "check:rulesets": "tsx tools/check-rulesets.ts",
     "check": "npm run check:rulesets"
@@ -23,9 +23,10 @@
     "yaml": "^2.6.1"
   },
   "devDependencies": {
+    "tsx": "^4.22.4",
+    "typescript": "^5.7.2",
     "vite": "^5.4.11",
     "vite-plugin-node-polyfills": "^0.22.0",
-    "typescript": "^5.7.2",
-    "tsx": "^4.22.4"
+    "vite-plugin-singlefile": "^2.3.3"
   }
 }

package.json

@@ -1,6 +1,8 @@
 import * as monaco from 'monaco-editor';
-import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker';
-import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker';
+// Inline the workers (base64 blob) so the single-file "Run Locally" build has no
+// external worker files — it must run from a double-clicked file:// index.html.
+import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker&inline';
+import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker&inline';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { lint, builtinDescriptions, builtinRulesByFormat, builtinRecommendedByFormat } from './spectral';
 import { ARTIFACTS, SAMPLES, artifactById, type ArtifactType } from './artifacts';
@@ -20,7 +22,14 @@ const BUILTIN_META = builtinMetaRaw as Record<string, { format: string; spec: st
 
 self.MonacoEnvironment = {
   getWorker(_id, label) {
-    return label === 'json' ? new JsonWorker() : new EditorWorker();
+    try {
+      return label === 'json' ? new JsonWorker() : new EditorWorker();
+    } catch {
+      // A locked-down context (e.g. a double-clicked file:// page) may refuse to
+      // spawn workers. Fall back to a no-op worker so the editor still boots —
+      // background language services degrade, but editing + Spectral linting work.
+      return new Worker(URL.createObjectURL(new Blob([''], { type: 'text/javascript' })));
+    }
   },
 };
 

src/main.ts

@@ -1,87 +1,43 @@
-// Post-build step: package the built site (dist/) into dist/api-validator.zip so
-// 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).
+// Post-build step: package the SINGLE-FILE build (dist-local/, a self-contained
+// index.html produced by `SINGLEFILE=1 vite build`) into dist/api-validator.zip,
+// which the live site serves for the "Run Locally" button. Because everything —
+// JS, CSS, and the Monaco workers — is inlined, a user can just unzip and open
+// index.html directly (file://); no server or external fetches required.
 //
-// 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.
+// Uses the system `zip` (present on macOS and the ubuntu CI runner). Never fails
+// the build over the optional archive — the site still deploys.
 import { execSync } from 'node:child_process';
-import { existsSync, writeFileSync, chmodSync } from 'node:fs';
+import { existsSync, writeFileSync } from 'node:fs';
 
+const SRC = 'dist-local';   // single-file build output
+const OUTDIR = 'dist';      // where the servable zip must land
 const OUT = 'api-validator.zip';
 
-if (!existsSync('dist')) {
-  console.error('zip-dist: dist/ not found — run `vite build` first.');
-  process.exit(1);
+if (!existsSync(SRC)) {
+  console.warn(`zip-dist: ${SRC}/ not found (run \`SINGLEFILE=1 vite build\`) — skipping zip.`);
+  process.exit(0);
 }
 
-// How-to that travels inside the archive.
+// Short how-to that travels inside the archive.
 writeFileSync(
-  'dist/RUN-LOCALLY.txt',
+  `${SRC}/RUN-LOCALLY.txt`,
   [
     'API Validator — run locally',
     '',
-    'This is the fully built, static app. It runs entirely in your browser; there',
-    'is no backend and no keys are required.',
+    'index.html is fully self-contained (all JavaScript, CSS, and workers are',
+    'inlined). Just unzip and open index.html in your browser — double-click it,',
+    'or drag it into a browser window. No server, no internet, no keys.',
     '',
-    '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.',
-    '',
-    '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)',
-    '',
-    'Or do it by hand, from inside this folder:',
-    '   python3 -m http.server 8000      # then open http://localhost:8000/',
-    '   # or:  npx serve .',
+    'Everything runs locally in your browser.',
     '',
     '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.
 try {
-  execSync(`cd dist && rm -f ${OUT} && zip -r -q -X ${OUT} . -x '*.zip'`, { stdio: 'inherit' });
-  console.log(`zip-dist: wrote dist/${OUT}`);
+  execSync(`rm -f ${OUTDIR}/${OUT} && cd ${SRC} && zip -r -q -X ../${OUTDIR}/${OUT} . -x '*.zip'`, { stdio: 'inherit' });
+  console.log(`zip-dist: wrote ${OUTDIR}/${OUT} from ${SRC}/`);
 } catch (e) {
   console.warn(`zip-dist: could not create ${OUT} (is \`zip\` installed?) — skipping. ${e?.message || e}`);
 }

tools/zip-dist.mjs

@@ -1,13 +1,19 @@
 import { defineConfig } from 'vite';
 import { nodePolyfills } from 'vite-plugin-node-polyfills';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+
+// Two build targets:
+//   default        -> dist/       multi-chunk site for validator.apicommons.org
+//   SINGLEFILE=1   -> dist-local/ ONE self-contained index.html for the
+//                     "Run Locally" download, so a double-clicked file:// page
+//                     works with no external module/worker fetches (which the
+//                     browser blocks over file://). Workers are inlined via
+//                     ?worker&inline in main.ts.
+const singleFile = process.env.SINGLEFILE === '1';
 
-// 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.
 // Strip the `crossorigin` attribute Vite stamps on the injected <link>/<script>
-// tags. On the live (same-origin) site it's a harmless no-op, but when the
-// unzipped "Run Locally" copy is opened over file://, a crossorigin stylesheet is
-// a CORS request against a null origin with no CORS headers — so the browser
+// tags. On the live (same-origin) site it's a harmless no-op, but over file:// a
+// crossorigin stylesheet is a CORS request against a null origin — the browser
 // refuses to apply the CSS. Removing it lets the CSS load from file:// too.
 const stripCrossorigin = {
   name: 'strip-crossorigin',
@@ -25,7 +31,14 @@ export default defineConfig({
       globals: { process: true, Buffer: true },
     }),
     stripCrossorigin,
+    ...(singleFile ? [viteSingleFile()] : []),
   ],
-  worker: { format: 'es' },
-  build: { target: 'es2020', sourcemap: false },
+  // Classic (iife) workers inline as blob URLs that run over file://; ES-module
+  // blob workers can be blocked there.
+  worker: { format: 'iife' },
+  build: {
+    target: 'es2020',
+    sourcemap: false,
+    outDir: singleFile ? 'dist-local' : 'dist',
+  },
 });