@korajs/cli 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/vite.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The offline app shell for Kora apps (NEW-DX-3).
+ *
+ * A Kora app's DATA works offline; this makes its INTERFACE open offline too. The plugin
+ * runs only in `vite build`:
+ * - After the bundle is written (and after the template's sqlite WASM copy step), it walks
+ *   the output directory and writes `sw.js`: a small, dependency-free service worker that
+ *   precaches the built shell (index.html, hashed JS/CSS/WASM, the worker, the OPFS proxy
+ *   and public files) into a cache versioned by the content of every precached file.
+ * - It injects a registration script into `index.html` with a "new version available"
+ *   flow: the new worker waits, the page shows a reload prompt (or dispatches
+ *   `kora:update-available` for the app to show its own), and only an accepted update
+ *   activates it and reloads, so old and new assets never mix in one page.
+ *
+ * In `vite dev` it injects a script that unregisters any Kora service worker left on the
+ * dev origin, so a stale shell can never shadow the dev server.
+ *
+ * Built in-house instead of `vite-plugin-pwa` (CLAUDE.md: justify every dependency): the
+ * whole worker is under 150 lines, needs no Workbox runtime, and its caching rules are the
+ * ones a Kora app specifically needs (never cache the sync endpoint or auth routes; never
+ * serve an unhashed file such as `assets/sqlite3.wasm` cache-first).
+ */
+interface KoraServiceWorkerOptions {
+    /**
+     * URL path prefixes the worker never handles (always straight to the network, never
+     * cached). Defaults to the sync endpoint, auth routes and server operational endpoints:
+     * `['/kora-sync', '/auth', '/__kora', '/health']`.
+     */
+    bypass?: string[];
+    /**
+     * Show the built-in "new version available" banner. Defaults to true. Set false to show
+     * your own UI: listen for the `kora:update-available` window event and call
+     * `event.detail.update()` when the user accepts.
+     */
+    updatePrompt?: boolean;
+    /**
+     * A navigation waits this long for the network before the cached shell is served
+     * (a captive portal or a stalled 2G link otherwise leaves a blank page). Defaults to 4000.
+     */
+    navigationTimeoutMs?: number;
+    /** File name of the generated worker, relative to the output directory. Defaults to `sw.js`. */
+    fileName?: string;
+}
+/** The subset of Vite's resolved config this plugin reads. */
+interface ResolvedViteConfig {
+    root: string;
+    base: string;
+    command: 'build' | 'serve';
+    build: {
+        outDir: string;
+    };
+}
+interface HtmlTag {
+    tag: string;
+    attrs?: Record<string, string | boolean>;
+    children?: string;
+    injectTo?: 'head' | 'body' | 'head-prepend' | 'body-prepend';
+}
+/**
+ * A Vite plugin, typed structurally so `@korajs/cli` does not depend on `vite`.
+ */
+interface KoraVitePlugin {
+    name: string;
+    enforce?: 'pre' | 'post';
+    configResolved(config: ResolvedViteConfig): void;
+    transformIndexHtml(html: string): {
+        html: string;
+        tags: HtmlTag[];
+    };
+    closeBundle: {
+        order: 'post';
+        sequential: true;
+        handler(): void;
+    };
+}
+/** Default URL prefixes the service worker never touches. */
+declare const DEFAULT_SW_BYPASS: readonly string[];
+/**
+ * `<meta name="kora-shell">`, injected into every built HTML page: the worker recognises a
+ * page of a Kora build by it (RT-109).
+ */
+declare const SW_SHELL_META = "kora-shell";
+/** Cache-name prefix shared by every version, so `activate` can delete old versions. */
+declare const SW_CACHE_PREFIX = "kora-shell-";
+/**
+ * Vite plugin that gives a Kora app an offline app shell.
+ *
+ * @param options - Bypass prefixes, update prompt and navigation timeout
+ * @returns A Vite plugin (add it last in `plugins`)
+ *
+ * @example
+ * ```typescript
+ * import { koraServiceWorker } from '@korajs/cli/vite'
+ * export default defineConfig({ plugins: [react(), koraServiceWorker()] })
+ * ```
+ */
+declare function koraServiceWorker(options?: KoraServiceWorkerOptions): KoraVitePlugin;
+/**
+ * The files to precache from a build directory, and a version derived from their content.
+ *
+ * Skipped: the worker itself, source maps, pre-compressed siblings (`.br`, `.gz`), dot
+ * directories (`.vite/`), and an unhashed copy whose bytes equal a content-hashed file
+ * (the templates copy `sqlite3-<hash>.wasm` to `sqlite3.wasm`; precaching both would
+ * double a ~1 MB first download on the slow links Kora targets).
+ *
+ * @param outDir - Absolute build directory
+ * @param base - Vite `base` (URL prefix ending in `/`)
+ * @param swFileName - The worker's own file name, excluded from the list
+ * @returns Precache URLs (sorted) and a 16-hex-digit content version
+ */
+declare function collectPrecache(outDir: string, base: string, swFileName?: string): {
+    urls: string[];
+    version: string;
+};
+/**
+ * Vite/Rollup content-hash naming (`name-[hash].ext`): the last `-`/`.` token of the stem
+ * is 8+ `[A-Za-z0-9_]` characters with an uppercase letter or digit. The same rule the
+ * production server uses for `immutable` caching, so the two never disagree.
+ */
+declare function isHashedName(path: string): boolean;
+interface WorkerSourceInput {
+    version: string;
+    precache: string[];
+    shellUrl: string;
+    bypass: string[];
+    navigationTimeoutMs: number;
+}
+/**
+ * Source of the generated service worker.
+ *
+ * - install: precache every shell file into `kora-shell-<version>` (bypassing the HTTP
+ *   cache). It does NOT skip waiting: an update waits for the page to accept it.
+ * - activate: delete every other `kora-shell-*` cache, then claim clients.
+ * - fetch (same-origin GET only, bypass prefixes untouched). One build per active worker
+ *   (RT-109): while this worker is active the page runs THIS worker's build, online and
+ *   offline alike, until the user accepts an update (or every tab of the app closes and
+ *   the waiting worker takes over at the next start):
+ *   - navigations: network first (with a timeout). A page of a Kora build (it carries
+ *     `<meta name="kora-shell">`) that is not byte-identical to one of this build's
+ *     precached pages belongs to another build (a deploy happened): this build's copy of
+ *     that page (or its shell) is served instead. Other documents (server-rendered pages,
+ *     downloads) pass through. Offline or timed out: this build's copy or shell;
+ *   - files this build precached: cache first (this build's bytes, the unhashed
+ *     `sqlite3.wasm` and public files included, never a newer deploy's);
+ *   - other content-hashed files: cache first (their bytes can never change);
+ *   - everything else: network first, falling back to the cache.
+ */
+declare function serviceWorkerSource(input: WorkerSourceInput): string;
+/**
+ * Registration and update flow, injected into the built `index.html`.
+ *
+ * @param input - Worker URL, scope and whether to show the built-in prompt
+ * @returns Module script source
+ */
+declare function registrationScript(input: {
+    swUrl: string;
+    scope: string;
+    updatePrompt: boolean;
+}): string;
+
+export { DEFAULT_SW_BYPASS, type KoraServiceWorkerOptions, type KoraVitePlugin, SW_CACHE_PREFIX, SW_SHELL_META, collectPrecache, isHashedName, koraServiceWorker, registrationScript, serviceWorkerSource };

package/dist/vite.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+// src/vite/service-worker.ts
+import { createHash } from "crypto";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { join, relative, resolve, sep } from "path";
+var DEFAULT_SW_BYPASS = ["/kora-sync", "/auth", "/__kora", "/health"];
+var SW_SHELL_META = "kora-shell";
+var SW_CACHE_PREFIX = "kora-shell-";
+function koraServiceWorker(options = {}) {
+  const fileName = options.fileName ?? "sw.js";
+  const bypass = options.bypass ?? [...DEFAULT_SW_BYPASS];
+  const updatePrompt = options.updatePrompt ?? true;
+  const navigationTimeoutMs = options.navigationTimeoutMs ?? 4e3;
+  let config = null;
+  return {
+    name: "kora-service-worker",
+    enforce: "post",
+    configResolved(resolved) {
+      config = resolved;
+    },
+    transformIndexHtml(html) {
+      if (!config) return { html, tags: [] };
+      const children = config.command === "build" ? registrationScript({
+        swUrl: `${config.base}${fileName}`,
+        scope: config.base,
+        updatePrompt
+      }) : DEV_UNREGISTER_SCRIPT;
+      const tags = [
+        { tag: "script", attrs: { type: "module" }, children, injectTo: "body" }
+      ];
+      if (config.command === "build") {
+        tags.push({
+          tag: "meta",
+          attrs: { name: SW_SHELL_META, content: "1" },
+          injectTo: "head-prepend"
+        });
+      }
+      return { html, tags };
+    },
+    closeBundle: {
+      order: "post",
+      sequential: true,
+      handler() {
+        if (!config || config.command !== "build") return;
+        const outDir = resolve(config.root, config.build.outDir);
+        if (!existsSync(join(outDir, "index.html"))) return;
+        const { urls, version } = collectPrecache(outDir, config.base, fileName);
+        writeFileSync(
+          join(outDir, fileName),
+          serviceWorkerSource({
+            version,
+            precache: urls,
+            shellUrl: `${config.base}index.html`,
+            bypass,
+            navigationTimeoutMs
+          })
+        );
+      }
+    }
+  };
+}
+function collectPrecache(outDir, base, swFileName = "sw.js") {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const rel = relative(outDir, full).split(sep).join("/");
+      if (rel === swFileName || /\.(map|br|gz)$/.test(rel)) continue;
+      files.push({
+        path: rel,
+        digest: createHash("sha256").update(readFileSync(full)).digest("hex")
+      });
+    }
+  };
+  walk(outDir);
+  const hashedDigests = new Set(files.filter((f) => isHashedName(f.path)).map((f) => f.digest));
+  const kept = files.filter((f) => isHashedName(f.path) || !hashedDigests.has(f.digest)).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const version = createHash("sha256");
+  for (const f of kept) version.update(`${f.path}\0${f.digest}
+`);
+  return {
+    urls: kept.map((f) => `${base}${f.path}`),
+    version: version.digest("hex").slice(0, 16)
+  };
+}
+function isHashedName(path) {
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  const match = /[.-]([A-Za-z0-9_]{8,})$/.exec(stem);
+  return match !== null && /[A-Z0-9]/.test(match[1]);
+}
+function serviceWorkerSource(input) {
+  return `// Generated by @korajs/cli koraServiceWorker(). Do not edit: rebuilt on every \`vite build\`.
+const VERSION = ${JSON.stringify(input.version)}
+const CACHE = ${JSON.stringify(SW_CACHE_PREFIX)} + VERSION
+const PRECACHE = ${JSON.stringify(input.precache)}
+const SHELL = ${JSON.stringify(input.shellUrl)}
+const BYPASS = ${JSON.stringify(input.bypass)}
+const NAVIGATION_TIMEOUT_MS = ${JSON.stringify(input.navigationTimeoutMs)}
+const PRECACHED = new Set(PRECACHE)
+const PAGES = PRECACHE.filter((url) => /.html?$/i.test(url))
+const SHELL_MARKER = ${JSON.stringify(`name="${SW_SHELL_META}"`)}
+
+self.addEventListener('install', (event) => {
+	event.waitUntil(
+		caches.open(CACHE).then((cache) =>
+			cache.addAll(PRECACHE.map((url) => new Request(url, { cache: 'reload' }))),
+		),
+	)
+})
+
+self.addEventListener('activate', (event) => {
+	event.waitUntil(
+		caches
+			.keys()
+			.then((keys) =>
+				Promise.all(
+					keys
+						.filter((key) => key.startsWith(${JSON.stringify(SW_CACHE_PREFIX)}) && key !== CACHE)
+						.map((key) => caches.delete(key)),
+				),
+			)
+			.then(() => self.clients.claim()),
+	)
+})
+
+self.addEventListener('message', (event) => {
+	if (event.data && event.data.type === 'KORA_SW_SKIP_WAITING') self.skipWaiting()
+})
+
+function isHashed(pathname) {
+	const name = pathname.slice(pathname.lastIndexOf('/') + 1)
+	const match = /[.-]([A-Za-z0-9_]{8,})\\.[A-Za-z0-9]+$/.exec(name)
+	return match !== null && /[A-Z0-9]/.test(match[1])
+}
+
+function fromCache(request) {
+	return caches.open(CACHE).then((cache) => cache.match(request, { ignoreSearch: true }))
+}
+
+// This build's copy of the page a navigation asked for: the precached page of that path,
+// else the app shell (client-side routes).
+function ownPage(url) {
+	return caches.open(CACHE).then((cache) =>
+		(PAGES.includes(url.pathname) ? cache.match(url.pathname) : Promise.resolve(undefined)).then(
+			(page) => page || cache.match(SHELL),
+		),
+	)
+}
+
+// A navigation the network answered: kept when it is not a Kora page or is one of THIS
+// build's pages; a page of another build (a newer deploy) is replaced by this build's
+// copy, so one active worker serves one build (RT-109).
+async function sameBuildOrOwn(url, response) {
+	const type = (response.headers && response.headers.get('content-type')) || ''
+	if (!response.ok || !/html/i.test(type)) return response
+	const text = await response.clone().text()
+	if (!text.includes(SHELL_MARKER)) return response
+	const cache = await caches.open(CACHE)
+	for (const page of PAGES) {
+		const cached = await cache.match(page)
+		if (cached && (await cached.text()) === text) return response
+	}
+	return (await ownPage(url)) || response
+}
+
+function networkWithTimeout(request, ms) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error('timeout')), ms)
+		fetch(request).then(
+			(response) => {
+				clearTimeout(timer)
+				resolve(response)
+			},
+			(error) => {
+				clearTimeout(timer)
+				reject(error)
+			},
+		)
+	})
+}
+
+self.addEventListener('fetch', (event) => {
+	const request = event.request
+	if (request.method !== 'GET') return
+	const url = new URL(request.url)
+	if (url.origin !== self.location.origin) return
+	if (BYPASS.some((prefix) => url.pathname === prefix || url.pathname.startsWith(prefix + '/')))
+		return
+
+	if (request.mode === 'navigate') {
+		event.respondWith(
+			networkWithTimeout(request, NAVIGATION_TIMEOUT_MS).then(
+				(response) => sameBuildOrOwn(url, response),
+				() => ownPage(url).then((page) => page || Response.error()),
+			),
+		)
+		return
+	}
+
+	if (PRECACHED.has(url.pathname)) {
+		event.respondWith(fromCache(request).then((cached) => cached || fetch(request)))
+		return
+	}
+
+	if (isHashed(url.pathname)) {
+		event.respondWith(
+			fromCache(request).then(
+				(cached) =>
+					cached ||
+					fetch(request).then((response) => {
+						if (response.ok && response.type === 'basic') {
+							const copy = response.clone()
+							caches.open(CACHE).then((cache) => cache.put(request, copy))
+						}
+						return response
+					}),
+			),
+		)
+		return
+	}
+
+	event.respondWith(
+		fetch(request).catch(() =>
+			fromCache(request).then((cached) => cached || Response.error()),
+		),
+	)
+})
+`;
+}
+var DEV_UNREGISTER_SCRIPT = `if ('serviceWorker' in navigator) {
+	navigator.serviceWorker.getRegistrations().then((registrations) => {
+		for (const registration of registrations) {
+			const script = registration.active || registration.waiting || registration.installing
+			if (script && /\\/sw\\.js$/.test(new URL(script.scriptURL).pathname)) registration.unregister()
+		}
+	})
+	caches.keys().then((keys) => keys.filter((k) => k.startsWith(${JSON.stringify(SW_CACHE_PREFIX)})).forEach((k) => caches.delete(k)))
+}`;
+function registrationScript(input) {
+  return `// Kora offline app shell: service worker registration and update flow.
+if ('serviceWorker' in navigator && window.isSecureContext && /^https?:$/.test(location.protocol)) {
+	const swUrl = ${JSON.stringify(input.swUrl)}
+	const showPrompt = ${JSON.stringify(input.updatePrompt)}
+	let accepted = false
+	navigator.serviceWorker.addEventListener('controllerchange', () => {
+		// Reload only for an update the user accepted, never for the first install's claim.
+		if (accepted) location.reload()
+	})
+	const offer = (worker) => {
+		// No controller means this is the first install: there is nothing to update.
+		if (!navigator.serviceWorker.controller) return
+		const update = () => {
+			accepted = true
+			worker.postMessage({ type: 'KORA_SW_SKIP_WAITING' })
+		}
+		const event = new CustomEvent('kora:update-available', { detail: { update }, cancelable: true })
+		const handled = !window.dispatchEvent(event)
+		if (showPrompt && !handled) renderPrompt(update)
+	}
+	const renderPrompt = (update) => {
+		if (document.getElementById('kora-update-prompt')) return
+		const bar = document.createElement('div')
+		bar.id = 'kora-update-prompt'
+		bar.setAttribute('role', 'status')
+		bar.style.cssText = 'position:fixed;left:16px;right:16px;bottom:16px;z-index:2147483647;display:flex;gap:12px;align-items:center;justify-content:space-between;max-width:480px;margin:0 auto;padding:12px 16px;border-radius:8px;background:#111;color:#fff;font:14px/1.4 system-ui,sans-serif;box-shadow:0 4px 16px rgba(0,0,0,.3)'
+		const text = document.createElement('span')
+		text.textContent = 'A new version is available.'
+		const button = document.createElement('button')
+		button.type = 'button'
+		button.textContent = 'Reload'
+		button.style.cssText = 'padding:6px 12px;border:0;border-radius:6px;background:#fff;color:#111;font:inherit;cursor:pointer'
+		button.addEventListener('click', () => {
+			button.disabled = true
+			update()
+		})
+		bar.append(text, button)
+		document.body.append(bar)
+	}
+	window.addEventListener('load', () => {
+		navigator.serviceWorker
+			.register(swUrl, { scope: ${JSON.stringify(input.scope)}, updateViaCache: 'none' })
+			.then((registration) => {
+				if (registration.waiting) offer(registration.waiting)
+				registration.addEventListener('updatefound', () => {
+					const worker = registration.installing
+					if (!worker) return
+					worker.addEventListener('statechange', () => {
+						if (worker.state === 'installed') offer(worker)
+					})
+				})
+				// Long-lived tabs (kiosks, shared tablets) still learn about new deploys.
+				const check = () => registration.update().catch(() => {})
+				setInterval(check, 60 * 60 * 1000)
+				document.addEventListener('visibilitychange', () => {
+					if (document.visibilityState === 'visible') check()
+				})
+			})
+			.catch((error) => console.warn('[kora] service worker registration failed:', error))
+	})
+}`;
+}
+export {
+  DEFAULT_SW_BYPASS,
+  SW_CACHE_PREFIX,
+  SW_SHELL_META,
+  collectPrecache,
+  isHashedName,
+  koraServiceWorker,
+  registrationScript,
+  serviceWorkerSource
+};
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite/service-worker.ts"],"sourcesContent":["import { createHash } from 'node:crypto'\nimport { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'\nimport { join, relative, resolve, sep } from 'node:path'\n\n/**\n * The offline app shell for Kora apps (NEW-DX-3).\n *\n * A Kora app's DATA works offline; this makes its INTERFACE open offline too. The plugin\n * runs only in `vite build`:\n * - After the bundle is written (and after the template's sqlite WASM copy step), it walks\n *   the output directory and writes `sw.js`: a small, dependency-free service worker that\n *   precaches the built shell (index.html, hashed JS/CSS/WASM, the worker, the OPFS proxy\n *   and public files) into a cache versioned by the content of every precached file.\n * - It injects a registration script into `index.html` with a \"new version available\"\n *   flow: the new worker waits, the page shows a reload prompt (or dispatches\n *   `kora:update-available` for the app to show its own), and only an accepted update\n *   activates it and reloads, so old and new assets never mix in one page.\n *\n * In `vite dev` it injects a script that unregisters any Kora service worker left on the\n * dev origin, so a stale shell can never shadow the dev server.\n *\n * Built in-house instead of `vite-plugin-pwa` (CLAUDE.md: justify every dependency): the\n * whole worker is under 150 lines, needs no Workbox runtime, and its caching rules are the\n * ones a Kora app specifically needs (never cache the sync endpoint or auth routes; never\n * serve an unhashed file such as `assets/sqlite3.wasm` cache-first).\n */\nexport interface KoraServiceWorkerOptions {\n\t/**\n\t * URL path prefixes the worker never handles (always straight to the network, never\n\t * cached). Defaults to the sync endpoint, auth routes and server operational endpoints:\n\t * `['/kora-sync', '/auth', '/__kora', '/health']`.\n\t */\n\tbypass?: string[]\n\t/**\n\t * Show the built-in \"new version available\" banner. Defaults to true. Set false to show\n\t * your own UI: listen for the `kora:update-available` window event and call\n\t * `event.detail.update()` when the user accepts.\n\t */\n\tupdatePrompt?: boolean\n\t/**\n\t * A navigation waits this long for the network before the cached shell is served\n\t * (a captive portal or a stalled 2G link otherwise leaves a blank page). Defaults to 4000.\n\t */\n\tnavigationTimeoutMs?: number\n\t/** File name of the generated worker, relative to the output directory. Defaults to `sw.js`. */\n\tfileName?: string\n}\n\n/** The subset of Vite's resolved config this plugin reads. */\ninterface ResolvedViteConfig {\n\troot: string\n\tbase: string\n\tcommand: 'build' | 'serve'\n\tbuild: { outDir: string }\n}\n\ninterface HtmlTag {\n\ttag: string\n\tattrs?: Record<string, string | boolean>\n\tchildren?: string\n\tinjectTo?: 'head' | 'body' | 'head-prepend' | 'body-prepend'\n}\n\n/**\n * A Vite plugin, typed structurally so `@korajs/cli` does not depend on `vite`.\n */\nexport interface KoraVitePlugin {\n\tname: string\n\tenforce?: 'pre' | 'post'\n\tconfigResolved(config: ResolvedViteConfig): void\n\ttransformIndexHtml(html: string): { html: string; tags: HtmlTag[] }\n\tcloseBundle: { order: 'post'; sequential: true; handler(): void }\n}\n\n/** Default URL prefixes the service worker never touches. */\nexport const DEFAULT_SW_BYPASS: readonly string[] = ['/kora-sync', '/auth', '/__kora', '/health']\n\n/**\n * `<meta name=\"kora-shell\">`, injected into every built HTML page: the worker recognises a\n * page of a Kora build by it (RT-109).\n */\nexport const SW_SHELL_META = 'kora-shell'\n\n/** Cache-name prefix shared by every version, so `activate` can delete old versions. */\nexport const SW_CACHE_PREFIX = 'kora-shell-'\n\n/**\n * Vite plugin that gives a Kora app an offline app shell.\n *\n * @param options - Bypass prefixes, update prompt and navigation timeout\n * @returns A Vite plugin (add it last in `plugins`)\n *\n * @example\n * ```typescript\n * import { koraServiceWorker } from '@korajs/cli/vite'\n * export default defineConfig({ plugins: [react(), koraServiceWorker()] })\n * ```\n */\nexport function koraServiceWorker(options: KoraServiceWorkerOptions = {}): KoraVitePlugin {\n\tconst fileName = options.fileName ?? 'sw.js'\n\tconst bypass = options.bypass ?? [...DEFAULT_SW_BYPASS]\n\tconst updatePrompt = options.updatePrompt ?? true\n\tconst navigationTimeoutMs = options.navigationTimeoutMs ?? 4000\n\tlet config: ResolvedViteConfig | null = null\n\n\treturn {\n\t\tname: 'kora-service-worker',\n\t\tenforce: 'post',\n\t\tconfigResolved(resolved) {\n\t\t\tconfig = resolved\n\t\t},\n\t\ttransformIndexHtml(html) {\n\t\t\tif (!config) return { html, tags: [] }\n\t\t\tconst children =\n\t\t\t\tconfig.command === 'build'\n\t\t\t\t\t? registrationScript({\n\t\t\t\t\t\t\tswUrl: `${config.base}${fileName}`,\n\t\t\t\t\t\t\tscope: config.base,\n\t\t\t\t\t\t\tupdatePrompt,\n\t\t\t\t\t\t})\n\t\t\t\t\t: DEV_UNREGISTER_SCRIPT\n\t\t\tconst tags: HtmlTag[] = [\n\t\t\t\t{ tag: 'script', attrs: { type: 'module' }, children, injectTo: 'body' },\n\t\t\t]\n\t\t\tif (config.command === 'build') {\n\t\t\t\t// Marks the document as a page of a Kora build: the worker serves its OWN\n\t\t\t\t// build's copy of such a page until the user accepts an update (RT-109).\n\t\t\t\ttags.push({\n\t\t\t\t\ttag: 'meta',\n\t\t\t\t\tattrs: { name: SW_SHELL_META, content: '1' },\n\t\t\t\t\tinjectTo: 'head-prepend',\n\t\t\t\t})\n\t\t\t}\n\t\t\treturn { html, tags }\n\t\t},\n\t\tcloseBundle: {\n\t\t\torder: 'post',\n\t\t\tsequential: true,\n\t\t\thandler() {\n\t\t\t\tif (!config || config.command !== 'build') return\n\t\t\t\tconst outDir = resolve(config.root, config.build.outDir)\n\t\t\t\tif (!existsSync(join(outDir, 'index.html'))) return\n\t\t\t\tconst { urls, version } = collectPrecache(outDir, config.base, fileName)\n\t\t\t\twriteFileSync(\n\t\t\t\t\tjoin(outDir, fileName),\n\t\t\t\t\tserviceWorkerSource({\n\t\t\t\t\t\tversion,\n\t\t\t\t\t\tprecache: urls,\n\t\t\t\t\t\tshellUrl: `${config.base}index.html`,\n\t\t\t\t\t\tbypass,\n\t\t\t\t\t\tnavigationTimeoutMs,\n\t\t\t\t\t}),\n\t\t\t\t)\n\t\t\t},\n\t\t},\n\t}\n}\n\n/**\n * The files to precache from a build directory, and a version derived from their content.\n *\n * Skipped: the worker itself, source maps, pre-compressed siblings (`.br`, `.gz`), dot\n * directories (`.vite/`), and an unhashed copy whose bytes equal a content-hashed file\n * (the templates copy `sqlite3-<hash>.wasm` to `sqlite3.wasm`; precaching both would\n * double a ~1 MB first download on the slow links Kora targets).\n *\n * @param outDir - Absolute build directory\n * @param base - Vite `base` (URL prefix ending in `/`)\n * @param swFileName - The worker's own file name, excluded from the list\n * @returns Precache URLs (sorted) and a 16-hex-digit content version\n */\nexport function collectPrecache(\n\toutDir: string,\n\tbase: string,\n\tswFileName = 'sw.js',\n): { urls: string[]; version: string } {\n\tconst files: { path: string; digest: string }[] = []\n\tconst walk = (dir: string): void => {\n\t\tfor (const entry of readdirSync(dir, { withFileTypes: true })) {\n\t\t\tif (entry.name.startsWith('.')) continue\n\t\t\tconst full = join(dir, entry.name)\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\twalk(full)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif (!entry.isFile()) continue\n\t\t\tconst rel = relative(outDir, full).split(sep).join('/')\n\t\t\tif (rel === swFileName || /\\.(map|br|gz)$/.test(rel)) continue\n\t\t\tfiles.push({\n\t\t\t\tpath: rel,\n\t\t\t\tdigest: createHash('sha256').update(readFileSync(full)).digest('hex'),\n\t\t\t})\n\t\t}\n\t}\n\twalk(outDir)\n\n\tconst hashedDigests = new Set(files.filter((f) => isHashedName(f.path)).map((f) => f.digest))\n\tconst kept = files\n\t\t.filter((f) => isHashedName(f.path) || !hashedDigests.has(f.digest))\n\t\t.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))\n\n\tconst version = createHash('sha256')\n\tfor (const f of kept) version.update(`${f.path}\\0${f.digest}\\n`)\n\treturn {\n\t\turls: kept.map((f) => `${base}${f.path}`),\n\t\tversion: version.digest('hex').slice(0, 16),\n\t}\n}\n\n/**\n * Vite/Rollup content-hash naming (`name-[hash].ext`): the last `-`/`.` token of the stem\n * is 8+ `[A-Za-z0-9_]` characters with an uppercase letter or digit. The same rule the\n * production server uses for `immutable` caching, so the two never disagree.\n */\nexport function isHashedName(path: string): boolean {\n\tconst name = path.slice(path.lastIndexOf('/') + 1)\n\tconst dot = name.lastIndexOf('.')\n\tconst stem = dot > 0 ? name.slice(0, dot) : name\n\tconst match = /[.-]([A-Za-z0-9_]{8,})$/.exec(stem)\n\treturn match !== null && /[A-Z0-9]/.test(match[1] as string)\n}\n\ninterface WorkerSourceInput {\n\tversion: string\n\tprecache: string[]\n\tshellUrl: string\n\tbypass: string[]\n\tnavigationTimeoutMs: number\n}\n\n/**\n * Source of the generated service worker.\n *\n * - install: precache every shell file into `kora-shell-<version>` (bypassing the HTTP\n *   cache). It does NOT skip waiting: an update waits for the page to accept it.\n * - activate: delete every other `kora-shell-*` cache, then claim clients.\n * - fetch (same-origin GET only, bypass prefixes untouched). One build per active worker\n *   (RT-109): while this worker is active the page runs THIS worker's build, online and\n *   offline alike, until the user accepts an update (or every tab of the app closes and\n *   the waiting worker takes over at the next start):\n *   - navigations: network first (with a timeout). A page of a Kora build (it carries\n *     `<meta name=\"kora-shell\">`) that is not byte-identical to one of this build's\n *     precached pages belongs to another build (a deploy happened): this build's copy of\n *     that page (or its shell) is served instead. Other documents (server-rendered pages,\n *     downloads) pass through. Offline or timed out: this build's copy or shell;\n *   - files this build precached: cache first (this build's bytes, the unhashed\n *     `sqlite3.wasm` and public files included, never a newer deploy's);\n *   - other content-hashed files: cache first (their bytes can never change);\n *   - everything else: network first, falling back to the cache.\n */\nexport function serviceWorkerSource(input: WorkerSourceInput): string {\n\treturn `// Generated by @korajs/cli koraServiceWorker(). Do not edit: rebuilt on every \\`vite build\\`.\nconst VERSION = ${JSON.stringify(input.version)}\nconst CACHE = ${JSON.stringify(SW_CACHE_PREFIX)} + VERSION\nconst PRECACHE = ${JSON.stringify(input.precache)}\nconst SHELL = ${JSON.stringify(input.shellUrl)}\nconst BYPASS = ${JSON.stringify(input.bypass)}\nconst NAVIGATION_TIMEOUT_MS = ${JSON.stringify(input.navigationTimeoutMs)}\nconst PRECACHED = new Set(PRECACHE)\nconst PAGES = PRECACHE.filter((url) => /\\.html?$/i.test(url))\nconst SHELL_MARKER = ${JSON.stringify(`name=\"${SW_SHELL_META}\"`)}\n\nself.addEventListener('install', (event) => {\n\tevent.waitUntil(\n\t\tcaches.open(CACHE).then((cache) =>\n\t\t\tcache.addAll(PRECACHE.map((url) => new Request(url, { cache: 'reload' }))),\n\t\t),\n\t)\n})\n\nself.addEventListener('activate', (event) => {\n\tevent.waitUntil(\n\t\tcaches\n\t\t\t.keys()\n\t\t\t.then((keys) =>\n\t\t\t\tPromise.all(\n\t\t\t\t\tkeys\n\t\t\t\t\t\t.filter((key) => key.startsWith(${JSON.stringify(SW_CACHE_PREFIX)}) && key !== CACHE)\n\t\t\t\t\t\t.map((key) => caches.delete(key)),\n\t\t\t\t),\n\t\t\t)\n\t\t\t.then(() => self.clients.claim()),\n\t)\n})\n\nself.addEventListener('message', (event) => {\n\tif (event.data && event.data.type === 'KORA_SW_SKIP_WAITING') self.skipWaiting()\n})\n\nfunction isHashed(pathname) {\n\tconst name = pathname.slice(pathname.lastIndexOf('/') + 1)\n\tconst match = /[.-]([A-Za-z0-9_]{8,})\\\\.[A-Za-z0-9]+$/.exec(name)\n\treturn match !== null && /[A-Z0-9]/.test(match[1])\n}\n\nfunction fromCache(request) {\n\treturn caches.open(CACHE).then((cache) => cache.match(request, { ignoreSearch: true }))\n}\n\n// This build's copy of the page a navigation asked for: the precached page of that path,\n// else the app shell (client-side routes).\nfunction ownPage(url) {\n\treturn caches.open(CACHE).then((cache) =>\n\t\t(PAGES.includes(url.pathname) ? cache.match(url.pathname) : Promise.resolve(undefined)).then(\n\t\t\t(page) => page || cache.match(SHELL),\n\t\t),\n\t)\n}\n\n// A navigation the network answered: kept when it is not a Kora page or is one of THIS\n// build's pages; a page of another build (a newer deploy) is replaced by this build's\n// copy, so one active worker serves one build (RT-109).\nasync function sameBuildOrOwn(url, response) {\n\tconst type = (response.headers && response.headers.get('content-type')) || ''\n\tif (!response.ok || !/html/i.test(type)) return response\n\tconst text = await response.clone().text()\n\tif (!text.includes(SHELL_MARKER)) return response\n\tconst cache = await caches.open(CACHE)\n\tfor (const page of PAGES) {\n\t\tconst cached = await cache.match(page)\n\t\tif (cached && (await cached.text()) === text) return response\n\t}\n\treturn (await ownPage(url)) || response\n}\n\nfunction networkWithTimeout(request, ms) {\n\treturn new Promise((resolve, reject) => {\n\t\tconst timer = setTimeout(() => reject(new Error('timeout')), ms)\n\t\tfetch(request).then(\n\t\t\t(response) => {\n\t\t\t\tclearTimeout(timer)\n\t\t\t\tresolve(response)\n\t\t\t},\n\t\t\t(error) => {\n\t\t\t\tclearTimeout(timer)\n\t\t\t\treject(error)\n\t\t\t},\n\t\t)\n\t})\n}\n\nself.addEventListener('fetch', (event) => {\n\tconst request = event.request\n\tif (request.method !== 'GET') return\n\tconst url = new URL(request.url)\n\tif (url.origin !== self.location.origin) return\n\tif (BYPASS.some((prefix) => url.pathname === prefix || url.pathname.startsWith(prefix + '/')))\n\t\treturn\n\n\tif (request.mode === 'navigate') {\n\t\tevent.respondWith(\n\t\t\tnetworkWithTimeout(request, NAVIGATION_TIMEOUT_MS).then(\n\t\t\t\t(response) => sameBuildOrOwn(url, response),\n\t\t\t\t() => ownPage(url).then((page) => page || Response.error()),\n\t\t\t),\n\t\t)\n\t\treturn\n\t}\n\n\tif (PRECACHED.has(url.pathname)) {\n\t\tevent.respondWith(fromCache(request).then((cached) => cached || fetch(request)))\n\t\treturn\n\t}\n\n\tif (isHashed(url.pathname)) {\n\t\tevent.respondWith(\n\t\t\tfromCache(request).then(\n\t\t\t\t(cached) =>\n\t\t\t\t\tcached ||\n\t\t\t\t\tfetch(request).then((response) => {\n\t\t\t\t\t\tif (response.ok && response.type === 'basic') {\n\t\t\t\t\t\t\tconst copy = response.clone()\n\t\t\t\t\t\t\tcaches.open(CACHE).then((cache) => cache.put(request, copy))\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn response\n\t\t\t\t\t}),\n\t\t\t),\n\t\t)\n\t\treturn\n\t}\n\n\tevent.respondWith(\n\t\tfetch(request).catch(() =>\n\t\t\tfromCache(request).then((cached) => cached || Response.error()),\n\t\t),\n\t)\n})\n`\n}\n\n/** Unregisters Kora service workers on the dev origin (dev must never be served a stale shell). */\nconst DEV_UNREGISTER_SCRIPT = `if ('serviceWorker' in navigator) {\n\tnavigator.serviceWorker.getRegistrations().then((registrations) => {\n\t\tfor (const registration of registrations) {\n\t\t\tconst script = registration.active || registration.waiting || registration.installing\n\t\t\tif (script && /\\\\/sw\\\\.js$/.test(new URL(script.scriptURL).pathname)) registration.unregister()\n\t\t}\n\t})\n\tcaches.keys().then((keys) => keys.filter((k) => k.startsWith(${JSON.stringify(SW_CACHE_PREFIX)})).forEach((k) => caches.delete(k)))\n}`\n\n/**\n * Registration and update flow, injected into the built `index.html`.\n *\n * @param input - Worker URL, scope and whether to show the built-in prompt\n * @returns Module script source\n */\nexport function registrationScript(input: {\n\tswUrl: string\n\tscope: string\n\tupdatePrompt: boolean\n}): string {\n\treturn `// Kora offline app shell: service worker registration and update flow.\nif ('serviceWorker' in navigator && window.isSecureContext && /^https?:$/.test(location.protocol)) {\n\tconst swUrl = ${JSON.stringify(input.swUrl)}\n\tconst showPrompt = ${JSON.stringify(input.updatePrompt)}\n\tlet accepted = false\n\tnavigator.serviceWorker.addEventListener('controllerchange', () => {\n\t\t// Reload only for an update the user accepted, never for the first install's claim.\n\t\tif (accepted) location.reload()\n\t})\n\tconst offer = (worker) => {\n\t\t// No controller means this is the first install: there is nothing to update.\n\t\tif (!navigator.serviceWorker.controller) return\n\t\tconst update = () => {\n\t\t\taccepted = true\n\t\t\tworker.postMessage({ type: 'KORA_SW_SKIP_WAITING' })\n\t\t}\n\t\tconst event = new CustomEvent('kora:update-available', { detail: { update }, cancelable: true })\n\t\tconst handled = !window.dispatchEvent(event)\n\t\tif (showPrompt && !handled) renderPrompt(update)\n\t}\n\tconst renderPrompt = (update) => {\n\t\tif (document.getElementById('kora-update-prompt')) return\n\t\tconst bar = document.createElement('div')\n\t\tbar.id = 'kora-update-prompt'\n\t\tbar.setAttribute('role', 'status')\n\t\tbar.style.cssText = 'position:fixed;left:16px;right:16px;bottom:16px;z-index:2147483647;display:flex;gap:12px;align-items:center;justify-content:space-between;max-width:480px;margin:0 auto;padding:12px 16px;border-radius:8px;background:#111;color:#fff;font:14px/1.4 system-ui,sans-serif;box-shadow:0 4px 16px rgba(0,0,0,.3)'\n\t\tconst text = document.createElement('span')\n\t\ttext.textContent = 'A new version is available.'\n\t\tconst button = document.createElement('button')\n\t\tbutton.type = 'button'\n\t\tbutton.textContent = 'Reload'\n\t\tbutton.style.cssText = 'padding:6px 12px;border:0;border-radius:6px;background:#fff;color:#111;font:inherit;cursor:pointer'\n\t\tbutton.addEventListener('click', () => {\n\t\t\tbutton.disabled = true\n\t\t\tupdate()\n\t\t})\n\t\tbar.append(text, button)\n\t\tdocument.body.append(bar)\n\t}\n\twindow.addEventListener('load', () => {\n\t\tnavigator.serviceWorker\n\t\t\t.register(swUrl, { scope: ${JSON.stringify(input.scope)}, updateViaCache: 'none' })\n\t\t\t.then((registration) => {\n\t\t\t\tif (registration.waiting) offer(registration.waiting)\n\t\t\t\tregistration.addEventListener('updatefound', () => {\n\t\t\t\t\tconst worker = registration.installing\n\t\t\t\t\tif (!worker) return\n\t\t\t\t\tworker.addEventListener('statechange', () => {\n\t\t\t\t\t\tif (worker.state === 'installed') offer(worker)\n\t\t\t\t\t})\n\t\t\t\t})\n\t\t\t\t// Long-lived tabs (kiosks, shared tablets) still learn about new deploys.\n\t\t\t\tconst check = () => registration.update().catch(() => {})\n\t\t\t\tsetInterval(check, 60 * 60 * 1000)\n\t\t\t\tdocument.addEventListener('visibilitychange', () => {\n\t\t\t\t\tif (document.visibilityState === 'visible') check()\n\t\t\t\t})\n\t\t\t})\n\t\t\t.catch((error) => console.warn('[kora] service worker registration failed:', error))\n\t})\n}`\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@korajs/cli",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "description": "Kora.js CLI tooling and project scaffolding",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,6 +22,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./vite": {
+      "import": {
+        "types": "./dist/vite.d.ts",
+        "default": "./dist/vite.js"
+      },
+      "require": {
+        "types": "./dist/vite.d.cts",
+        "default": "./dist/vite.cjs"
+      }
+    },
     "./create": {
       "import": "./dist/create.js",
       "require": "./dist/create.cjs"
@@ -38,7 +48,7 @@
     "esbuild": "^0.28.0",
     "validate-npm-package-name": "^7.0.2",
     "ws": "^8.18.0",
-    "@korajs/core": "1.0.0-beta.12"
+    "@korajs/core": "1.0.0-beta.13"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
@@ -49,12 +59,12 @@
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.0.4",
-    "@korajs/store": "1.0.0-beta.12",
-    "@korajs/test": "1.0.0-beta.12",
-    "@korajs/merge": "1.0.0-beta.12",
-    "@korajs/server": "1.0.0-beta.12",
-    "@korajs/sync": "1.0.0-beta.12",
-    "korajs": "1.0.0-beta.12"
+    "@korajs/server": "1.0.0-beta.13",
+    "@korajs/merge": "1.0.0-beta.13",
+    "@korajs/store": "1.0.0-beta.13",
+    "@korajs/sync": "1.0.0-beta.13",
+    "@korajs/test": "1.0.0-beta.13",
+    "korajs": "1.0.0-beta.13"
   },
   "license": "MIT",
   "scripts": {

package/templates/react-basic/AGENTS.md

@@ -12,7 +12,7 @@ This is a **Kora.js** application: an offline-first app where all data lives in
 2. **Never fetch application data over HTTP.** Do not add REST or GraphQL calls for app data, and do not talk to the sync server directly. Read and write through Kora collections only; sync happens automatically in the background.
 3. **Await readiness before direct collection access.** Outside the UI bindings, `await app.ready` before calling `app.<collection>` methods. The bindings handle this for you inside components.
 4. **Offline must keep working.** Any feature you add must function with the network off. Never gate a write or a read on connectivity. If you find yourself checking `navigator.onLine` before a data operation, you are doing it wrong.
-5. **Surface mutation errors.** Fire-and-forget mutate calls swallow errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
+5. **Surface mutation errors.** Fire-and-forget mutate calls put errors into the mutation state. Always render the mutation's `error` in the UI or handle the promise from the async variant. Silent failure is the worst failure.
 6. **Do not touch `src/kora-worker.ts`.** It wires the SQLite WASM binary URL for both dev and production builds. Changing it breaks production builds in ways that only show up after deploy.
 7. **Do not add a state management library for server or app data.** Kora's reactive queries are the store. Local UI state (form inputs, toggles) can use the framework's normal state tools.
 
@@ -52,12 +52,12 @@ export default defineSchema({
 })
 ```
 
-If you bump collections in a way that changes shapes, increment `version` and run `npx kora migrate`.
+If you change a collection's shape, increment `version` and add a `migrations` entry for it (`migrate().addField(...)`): each device migrates its local database on its next open. `npx kora migrate` generates the matching migration for server databases and a transform stub for clients still on the older version.
 
 ## Project conventions
 
 - Feature code lives in `src/modules/<feature>/` with the pattern: `<feature>.schema.ts` (collection definition, imported into `src/schema.ts`), `<feature>.queries.ts` (query builders), `<feature>.mutations.ts` (mutation functions taking a collection accessor).
-- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, add-wins for arrays). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
+- Conflict handling is declarative. Concurrent edits merge automatically (last-write-wins per field, arrays as multisets that keep every device's additions and removals, objects per top-level key). If a field needs domain-specific merging (counters, quantities), add a `resolve` function in the schema rather than writing sync logic.
 - `kora.config.ts` controls the dev environment (ports, sync server, schema watcher).
 
 ## Commands
@@ -77,11 +77,11 @@ Sync is configured in `src/main.*` via `createApp({ sync: { url, authClient } })
 import { useCollection, useMutation, useQuery, useSyncStatus } from '@korajs/react'
 
 const todos = useCollection('todos')
-const rows = useQuery(orderedTodos(todos))            // reactive, no loading state for local data
+const rows = useQuery(orderedTodos(todos))            // reactive; [] on the very first render
 const addTodo = useMutation((data) => todos.insert(data))
 addTodo.mutate({ title: 'x' })                        // fire-and-forget; errors land in addTodo.error
 await addTodo.mutateAsync({ title: 'x' })             // throws on failure; use when you need the error
 const status = useSyncStatus()                        // status.status, status.pendingOperations
 ```
 
-Rules: always render `mutation.error` somewhere. The app must work under React StrictMode (the framework's hooks are StrictMode-safe; keep `<StrictMode>` in `src/main.tsx`). `useQuery` returns data synchronously from the local store, so do not add loading spinners for local reads.
+Rules: always render `mutation.error` somewhere. The app must work under React StrictMode (the framework's hooks are StrictMode-safe; keep `<StrictMode>` in `src/main.tsx`). `useQuery` reads the local store: no network, no spinner. Its very first render returns `[]` before the local query has run; use `useQueryState` when you must tell "loading" from "no rows".

package/templates/react-basic/vite.config.ts

@@ -1,5 +1,6 @@
 import { copyFileSync, existsSync, readdirSync } from 'node:fs'
 import { join, resolve } from 'node:path'
+import { koraServiceWorker } from '@korajs/cli/vite'
 import react from '@vitejs/plugin-react'
 import type { Plugin } from 'vite'
 import { defineConfig } from 'vite'
@@ -70,8 +71,10 @@ function sqliteWasmHotfix(): Plugin {
 	}
 }
 
+// koraServiceWorker() (build only, keep it last): precaches the built app shell so the
+// app opens offline, with a "new version available" reload prompt. See @korajs/cli/vite.
 export default defineConfig({
-	plugins: [react(), crossOriginIsolation(), sqliteWasmHotfix()],
+	plugins: [react(), crossOriginIsolation(), sqliteWasmHotfix(), koraServiceWorker()],
 	worker: {
 		format: 'es',
 	},