spark-html-offline 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# ⚡ spark-html-offline
+
+Offline-capable URL imports for [spark-html](https://www.npmjs.com/package/spark-html)
+— a tiny service worker that caches `<div import="https://…">` components on
+first fetch and serves them when the CDN is unreachable or the user is
+offline. Zero dependencies.
+
+It kills the #1 critique of CDN imports: **"CDN down = component gone."**
+With the worker installed, a component imported by URL is served from cache
+instantly on every visit after the first, and refreshed in the background —
+users are never more than one visit behind, and never broken.
+
+```js
+// src/main.js — zero config
+import { offline } from 'spark-html-offline';
+offline();
+```
+
+```js
+// vite.config.js — emits /spark-sw.js in build, serves it in dev
+import spark from 'spark-html/vite';
+import offlineSw from 'spark-html-offline/vite';
+
+export default { plugins: [spark(), offlineSw()] };
+```
+
+```html
+<!-- this now works on a plane -->
+<div import="https://esm.sh/some-pkg/card.html"></div>
+```
+
+Works with any CDN — esm.sh, unpkg, jsdelivr, raw.githubusercontent, your own.
+
+## Install
+
+```bash
+npm install spark-html-offline
+```
+
+## How it works
+
+The worker intercepts **cross-origin GET requests only** (the CDN-import
+case) with a cache-first, background-revalidate strategy:
+
+1. **First visit** — fetched from the network, stored in the cache.
+2. **Every visit after** — served from cache instantly; a background fetch
+   refreshes the entry for next time.
+3. **Network gone** — the cached copy is served; a URL never seen before
+   answers `504`.
+
+Same-origin requests are untouched by default, so dev servers, HMR, and your
+own assets behave exactly as before.
+
+## Options
+
+```js
+// vite.config.js
+offlineSw({
+  file: 'spark-sw.js',        // emitted worker file name
+  include: ['/components/'],  // ALSO cache these same-origin paths
+  exclude: ['/api/'],         // never touch these (substring match)
+  cacheName: 'spark-offline-v1',
+});
+```
+
+```js
+// main.js
+offline({
+  sw: 'spark-sw.js',  // worker URL, relative to the page base
+  scope: '/',         // registration scope
+});
+```
+
+`offline()` no-ops safely wherever service workers don't exist — prerender
+builds, old browsers, non-secure origins — your app runs exactly as before,
+just without the safety net.
+
+## No build step?
+
+You don't need Vite. Generate the worker once and host it next to
+`index.html`:
+
+```js
+// node make-sw.mjs > spark-sw.js
+import { swSource } from 'spark-html-offline';
+console.log(swSource({ include: ['/components/'] }));
+```
+
+Then call `offline()` from any `<script type="module">`.
+
+## API
+
+| Export | Meaning |
+|--------|---------|
+| `offline(options?)` | Register the worker. Returns the registration, or `null` where unsupported. |
+| `swSource(options?)` | The full worker source as a string. |
+| `shouldHandle(url, origin, config?)` | The matching rule the worker uses (exported for tests/tooling). |
+| `CACHE_NAME` | Default cache bucket name (`'spark-offline-v1'`). |
+| `spark-html-offline/vite` | Vite plugin — emits the worker in build, serves it in dev. |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "spark-html-offline",
+  "version": "0.1.0",
+  "description": "Offline-capable URL imports for spark-html — a tiny service worker that caches CDN-imported components on first fetch and serves them when the network is gone. Zero dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "homepage": "https://wilkinnovo.github.io/spark",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./vite": {
+      "types": "./src/vite.d.ts",
+      "default": "./src/vite.js"
+    }
+  },
+  "scripts": {
+    "test": "node test/offline.js"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/spark-html-offline"
+  },
+  "keywords": [
+    "spark-html",
+    "service-worker",
+    "offline",
+    "pwa",
+    "cdn",
+    "cache-first",
+    "stale-while-revalidate"
+  ],
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,46 @@
+/** Options shared by the worker generator and the vite plugin. */
+export interface OfflineSwOptions {
+  /** Same-origin URL substrings to cache too (e.g. ['/components/']). */
+  include?: string[];
+  /** URL substrings the worker must never touch. */
+  exclude?: string[];
+  /** Override the cache bucket name (default 'spark-offline-v1'). */
+  cacheName?: string;
+}
+
+export interface OfflineOptions {
+  /** Worker URL, relative to the page base (default 'spark-sw.js'). */
+  sw?: string;
+  /** Registration scope (default: the worker's directory). */
+  scope?: string;
+}
+
+/** Default cache bucket name. */
+export const CACHE_NAME: string;
+
+/** True when the worker should intercept this URL. */
+export function shouldHandle(
+  url: string,
+  origin: string,
+  config?: { include?: string[]; exclude?: string[] },
+): boolean;
+
+/** The full service-worker source as a string. */
+export function swSource(options?: OfflineSwOptions): string;
+
+/** Register the worker (no-op where service workers don't exist). */
+export function offline(options?: OfflineOptions): Promise<ServiceWorkerRegistration | null>;
+
+declare const _default: {
+  offline: typeof offline;
+  swSource: typeof swSource;
+  shouldHandle: typeof shouldHandle;
+  CACHE_NAME: string;
+};
+export default _default;
+
+/** Vite plugin: emits the worker in build, serves it in dev. */
+export interface OfflineVitePluginOptions extends OfflineSwOptions {
+  /** Emitted file name (default 'spark-sw.js'). */
+  file?: string;
+}

package/src/index.js

@@ -0,0 +1,130 @@
+/**
+ * spark-html-offline — URL-imported components that survive a dead CDN.
+ *
+ * The #1 critique of `<div import="https://esm.sh/…/card.html">` is
+ * "CDN down = component gone". This package is a tiny service worker
+ * that caches those cross-origin fetches on first load and serves them
+ * cache-first afterwards (refreshing in the background), so a component
+ * imported by URL keeps working when the CDN is slow, flaky, or the
+ * user is offline.
+ *
+ *   // main.js — zero config
+ *   import { offline } from 'spark-html-offline';
+ *   offline();
+ *
+ *   // vite.config.js — emits + serves the worker file for you
+ *   import offlineSw from 'spark-html-offline/vite';
+ *   plugins: [spark(), offlineSw()]
+ *
+ * Works with any CDN (esm.sh, unpkg, jsdelivr, your own). By default it
+ * ONLY handles cross-origin GETs — local dev files are never intercepted,
+ * so dev servers and HMR behave exactly as before. Same-origin paths can
+ * opt in via `include` (e.g. `include: ['/components/']` to make your own
+ * fragments offline-capable too).
+ *
+ * No build step? Write the worker once with `swSource()` (or copy it from
+ * the README), host it next to index.html, and call `offline()`.
+ */
+
+/** Cache name — bump the suffix to invalidate everything on upgrade. */
+export const CACHE_NAME = 'spark-offline-v1';
+
+/**
+ * Decide whether the worker should handle a URL.
+ * Cross-origin http(s) → yes (the CDN-import case), unless excluded.
+ * Same-origin → only when it matches an `include` substring.
+ * This exact function is embedded into the generated worker.
+ */
+export function shouldHandle(url, origin, config) {
+  var u;
+  try { u = new URL(url); } catch (e) { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  var cfg = config || {};
+  var i;
+  for (i = 0; i < (cfg.exclude || []).length; i++) {
+    if (url.indexOf(cfg.exclude[i]) !== -1) return false;
+  }
+  if (u.origin !== origin) return true;
+  for (i = 0; i < (cfg.include || []).length; i++) {
+    if (url.indexOf(cfg.include[i]) !== -1) return true;
+  }
+  return false;
+}
+
+/**
+ * The service-worker source, as a string — write it to a file served from
+ * your origin (the vite plugin does this for you as /spark-sw.js).
+ *
+ * Strategy: cache-first with background revalidation (stale-while-
+ * revalidate). First visit fetches + caches; every visit after serves
+ * from cache instantly and refreshes the entry in the background, so
+ * users are never more than one visit behind — and never broken.
+ *
+ * @param {object} [options]
+ * @param {string[]} [options.include] Same-origin URL substrings to cache too.
+ * @param {string[]} [options.exclude] URL substrings to never touch.
+ * @param {string}   [options.cacheName] Override the cache bucket name.
+ */
+export function swSource(options = {}) {
+  const config = JSON.stringify({
+    include: options.include || [],
+    exclude: options.exclude || [],
+  });
+  const cache = JSON.stringify(options.cacheName || CACHE_NAME);
+  return `/* generated by spark-html-offline — cache-first for URL imports */
+'use strict';
+var CACHE = ${cache};
+var CONFIG = ${config};
+var shouldHandle = ${shouldHandle.toString()};
+
+self.addEventListener('install', function () { self.skipWaiting(); });
+self.addEventListener('activate', function (event) {
+  event.waitUntil(self.clients.claim());
+});
+self.addEventListener('fetch', function (event) {
+  var req = event.request;
+  if (req.method !== 'GET') return;
+  if (!shouldHandle(req.url, self.location.origin, CONFIG)) return;
+  event.respondWith(caches.open(CACHE).then(function (cache) {
+    return cache.match(req).then(function (cached) {
+      var refresh = fetch(req).then(function (res) {
+        if (res && res.ok) cache.put(req, res.clone());
+        return res;
+      }).catch(function () { return null; });
+      if (cached) {
+        // Serve instantly; keep the worker alive while the refresh lands.
+        event.waitUntil(refresh);
+        return cached;
+      }
+      return refresh.then(function (fresh) {
+        return fresh || new Response('', { status: 504, statusText: 'offline and never cached' });
+      });
+    });
+  }));
+});
+`;
+}
+
+/**
+ * Register the worker. Call once from main.js. No-ops safely where
+ * service workers don't exist (prerender, old browsers, non-secure
+ * origins) — your app runs exactly as before, just without the net.
+ *
+ * @param {object} [options]
+ * @param {string} [options.sw='spark-sw.js'] Worker URL (relative to the page base).
+ * @param {string} [options.scope] Registration scope (default: the worker's directory).
+ * @returns {Promise<ServiceWorkerRegistration|null>}
+ */
+export async function offline(options = {}) {
+  if (typeof navigator === 'undefined' || !navigator.serviceWorker) return null;
+  if (typeof globalThis.__SPARK_PRERENDER__ !== 'undefined' && globalThis.__SPARK_PRERENDER__) return null;
+  const sw = options.sw || 'spark-sw.js';
+  try {
+    return await navigator.serviceWorker.register(sw, options.scope ? { scope: options.scope } : undefined);
+  } catch (e) {
+    console.warn(`[spark-offline] service worker registration failed: ${e.message}`);
+    return null;
+  }
+}
+
+export default { offline, swSource, shouldHandle, CACHE_NAME };

package/src/vite.d.ts

@@ -0,0 +1,8 @@
+import type { OfflineVitePluginOptions } from './index.js';
+
+/** Vite plugin: emits the service worker in build, serves it in dev. */
+export default function sparkOffline(options?: OfflineVitePluginOptions): {
+  name: string;
+  configureServer(server: unknown): void;
+  generateBundle(): void;
+};

package/src/vite.js

@@ -0,0 +1,35 @@
+/**
+ * spark-html-offline/vite — emit + serve the worker file.
+ *
+ * Build: writes the generated service worker into the output dir (default
+ * name /spark-sw.js) so `offline()` finds it in production.
+ * Dev: serves the same source from the dev server, so the worker can be
+ * exercised locally too (it only touches cross-origin URLs by default, so
+ * HMR and local files are unaffected).
+ *
+ *   import offlineSw from 'spark-html-offline/vite';
+ *   plugins: [spark(), offlineSw({ include: ['/components/'] })]
+ */
+import { swSource } from './index.js';
+
+export default function sparkOffline(options = {}) {
+  const file = (options.file || 'spark-sw.js').replace(/^\//, '');
+  const source = swSource(options);
+  return {
+    name: 'spark-html-offline',
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        if ((req.url || '').split('?')[0] === `/${file}`) {
+          res.setHeader('Content-Type', 'text/javascript');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(source);
+          return;
+        }
+        next();
+      });
+    },
+    generateBundle() {
+      this.emitFile({ type: 'asset', fileName: file, source });
+    },
+  };
+}