@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/pwa/vite/client-module/build-version.ts

@@ -0,0 +1,43 @@
+import { execFileSync } from 'node:child_process';
+import type { ResolvedPwaConfig } from '../../shared/config/index.js';
+
+export interface BuildVersion {
+  readonly commit: string | null;
+  readonly builtAt: string;
+}
+
+// Any failure (no git, not a checkout, a hung call) means: no commit.
+const git = (root: string, args: ReadonlyArray<string>): string | null => {
+  try {
+    return execFileSync('git', args, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+};
+
+/** `abc1234`, or `abc1234-dirty` when tracked files have uncommitted changes. */
+const gitCommit = (root: string): string | null => {
+  const sha = git(root, ['rev-parse', '--short', 'HEAD']);
+  if (!sha) return null;
+  const changes = git(root, ['status', '--porcelain', '--untracked-files=no']);
+  return changes ? `${sha}-dirty` : sha;
+};
+
+/**
+ * The build's commit and time, read once when the plugin starts. Explicit
+ * `version` options win. Neither feeds the Build ID, which stays a hash of
+ * the Precache and worker config, so a rebuild of the same code is no update.
+ */
+export const resolveBuildVersion = (
+  config: ResolvedPwaConfig,
+  root: string,
+  now: Date = new Date(),
+): BuildVersion => ({
+  commit: config.version.commit ?? gitCommit(root),
+  builtAt: config.version.builtAt ?? now.toISOString(),
+});

package/src/pwa/vite/client-module/client-info.ts

@@ -0,0 +1,58 @@
+import { BuildId, MANIFEST_URL } from '../../shared/build/index.js';
+import type {
+  ClientBuildInfo,
+  ResolvedPwaConfig,
+} from '../../shared/config/index.js';
+import type { WebAppManifest } from '../../shared/manifest/index.js';
+import type { BuildVersion } from './build-version.js';
+
+const DEV_BUILD_ID = BuildId.make('dev');
+
+/** 180×180 if listed, else the first non-maskable PNG. iOS ignores maskable art. */
+const appleTouchIconOf = (manifest: WebAppManifest): string | null => {
+  const icons = manifest.icons ?? [];
+  const exact = icons.find((icon) =>
+    (icon.sizes ?? '').split(/\s+/).includes('180x180'),
+  );
+  const png = icons.find(
+    (icon) =>
+      (icon.type === 'image/png' || icon.src.endsWith('.png')) &&
+      (icon.purpose === undefined || icon.purpose.split(' ').includes('any')),
+  );
+  return (exact ?? png)?.src ?? null;
+};
+
+/**
+ * Default export of `virtual:pwa-toolkit/client` for one environment.
+ * The client environment never knows the Build ID (it builds first); the
+ * server environment gets it once the client build has produced it, and
+ * `dev` while serving. The build's commit and time go to the server
+ * environment too, so they reach the page only through its meta tags and
+ * always describe the build that rendered it.
+ */
+export const clientBuildInfo = (
+  config: ResolvedPwaConfig,
+  context: {
+    readonly serving: boolean;
+    readonly consumer: 'client' | 'server';
+    readonly buildId: BuildId | null;
+    readonly version: BuildVersion;
+  },
+): ClientBuildInfo => {
+  const active = config.enabled && (!context.serving || config.dev);
+  const serverBuildId = context.serving ? DEV_BUILD_ID : context.buildId;
+  const server = context.consumer === 'server';
+  return {
+    enabled: active,
+    swUrl: config.swUrl,
+    scope: '/',
+    update: config.update,
+    buildId: server && active ? serverBuildId : null,
+    builtAt: server ? context.version.builtAt : null,
+    commit: server ? context.version.commit : null,
+    manifestUrl: config.manifest ? MANIFEST_URL : null,
+    appleTouchIconUrl: config.manifest
+      ? appleTouchIconOf(config.manifest)
+      : null,
+  };
+};

package/src/pwa/vite/client-module/client-module.ts

@@ -0,0 +1,67 @@
+import type { Plugin } from 'vite';
+import { VIRTUAL_CLIENT_MODULE_ID } from '../../shared/build/index.js';
+import type { ResolvedPwaConfig } from '../../shared/config/index.js';
+import type { BuildState } from '../build/index.js';
+import { type BuildVersion, resolveBuildVersion } from './build-version.js';
+import { clientBuildInfo } from './client-info.js';
+
+const RESOLVED_ID = `\0${VIRTUAL_CLIENT_MODULE_ID}`;
+const PACKAGE = '@kestack/web-platform';
+
+/**
+ * Serves `virtual:pwa-toolkit/client` to the client and server environments.
+ * On the server `@kestack/web-platform` stays in Vite's module graph (not
+ * externalized) so its import of the virtual module resolves; in the
+ * browser it is pre-bundled with its dependencies, the virtual module left
+ * out for this plugin to serve.
+ */
+export const clientModulePlugin = (
+  config: ResolvedPwaConfig,
+  state: BuildState,
+): Plugin => {
+  let version: BuildVersion | undefined;
+  return {
+    name: 'pwa-toolkit:client-module',
+    enforce: 'pre',
+    sharedDuringBuild: true,
+    configResolved(resolved) {
+      version ??= resolveBuildVersion(config, resolved.root);
+    },
+    configEnvironment(name, environment) {
+      const consumer =
+        environment.consumer ?? (name === 'client' ? 'client' : 'server');
+      return consumer === 'client'
+        ? {
+            optimizeDeps: {
+              rolldownOptions: { external: [VIRTUAL_CLIENT_MODULE_ID] },
+            },
+          }
+        : { resolve: { noExternal: [PACKAGE] } };
+    },
+    resolveId(id) {
+      return id === VIRTUAL_CLIENT_MODULE_ID ? RESOLVED_ID : undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED_ID) return undefined;
+      const { command, consumer } = this.environment.config;
+      const serving = command === 'serve';
+      if (
+        !serving &&
+        consumer === 'server' &&
+        config.enabled &&
+        !state.buildId
+      ) {
+        this.warn(
+          'the server environment built before the client environment, so pages carry no Build ID',
+        );
+      }
+      const info = clientBuildInfo(config, {
+        serving,
+        consumer,
+        buildId: state.buildId,
+        version: version ?? resolveBuildVersion(config, process.cwd()),
+      });
+      return `export default ${JSON.stringify(info)};\n`;
+    },
+  };
+};

package/src/pwa/vite/client-module/index.ts

@@ -0,0 +1 @@
+export { clientModulePlugin } from './client-module.js';

package/src/pwa/vite/dev/dev-plugin.ts

@@ -0,0 +1,72 @@
+import type { Plugin } from 'vite';
+import { BuildId, MANIFEST_URL } from '../../shared/build/index.js';
+import {
+  type ResolvedPwaConfig,
+  workerConfigOf,
+} from '../../shared/config/index.js';
+import { withManifestDefaults } from '../../shared/manifest/index.js';
+import { workerScript } from '../worker-bundle/index.js';
+
+/**
+ * Dev server: serves the manifest, and, only with `dev: true`, a worker
+ * built with Build ID `dev` and an empty Precache (so everything goes to the
+ * network). Without `dev: true` the worker URL falls through to the app and
+ * the page does not register. Rebuilt after any file change.
+ */
+export const devPlugin = (config: ResolvedPwaConfig): Plugin => ({
+  name: 'pwa-toolkit:dev',
+  apply: 'serve',
+  configureServer(server) {
+    let script: Promise<string> | null = null;
+    const build = () =>
+      workerScript(
+        config.enabled
+          ? {
+              killSwitch: false,
+              info: {
+                buildId: BuildId.make('dev'),
+                precache: [],
+                config: workerConfigOf(config),
+              },
+              root: server.config.root,
+              worker: config.worker,
+              mode: server.config.mode,
+              alias: server.config.resolve.alias,
+              minify: false,
+            }
+          : { killSwitch: true },
+      );
+    server.watcher.on('all', () => {
+      script = null;
+    });
+    const manifest = config.manifest
+      ? JSON.stringify(withManifestDefaults(config.manifest), null, 2)
+      : null;
+
+    server.middlewares.use((req, res, next) => {
+      const path = (req.url ?? '').split('?')[0];
+      if (manifest !== null && path === MANIFEST_URL) {
+        res.setHeader('Content-Type', 'application/manifest+json');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.end(manifest);
+        return;
+      }
+      if (!config.dev || path !== config.swUrl) {
+        next();
+        return;
+      }
+      script ??= build();
+      script.then(
+        (code) => {
+          res.setHeader('Content-Type', 'text/javascript');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(code);
+        },
+        (error: unknown) => {
+          script = null;
+          next(error);
+        },
+      );
+    });
+  },
+});

package/src/pwa/vite/dev/index.ts

@@ -0,0 +1 @@
+export { devPlugin } from './dev-plugin.js';

package/src/pwa/vite/index.ts

@@ -0,0 +1 @@
+export { pwa } from './vite.js';

package/src/pwa/vite/precache/asset-kind.ts

@@ -0,0 +1,25 @@
+const DEFAULT_EXTENSIONS = new Set([
+  '.js',
+  '.mjs',
+  '.css',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+  '.eot',
+]);
+
+const extensionOf = (path: string): string => {
+  const slash = path.lastIndexOf('/');
+  const dot = path.lastIndexOf('.');
+  return dot > slash ? path.slice(dot).toLowerCase() : '';
+};
+
+/** Scripts, styles and fonts: what the App Shell needs to boot. */
+export const isDefaultAsset = (path: string): boolean =>
+  DEFAULT_EXTENSIONS.has(extensionOf(path));
+
+export const isHtml = (path: string): boolean => extensionOf(path) === '.html';
+
+export const isSourceMap = (path: string): boolean =>
+  extensionOf(path) === '.map';

package/src/pwa/vite/precache/index.ts

@@ -0,0 +1,6 @@
+export {
+  type OutputFile,
+  selectAssets,
+  selectDocuments,
+  type Selection,
+} from './precache.js';

package/src/pwa/vite/precache/precache.ts

@@ -0,0 +1,97 @@
+import { matchesGlob } from 'node:path/posix';
+import type { PrecacheEntry } from '../../shared/build/index.js';
+import { isDefaultAsset, isHtml, isSourceMap } from './asset-kind.js';
+import { revisionOf } from './revision.js';
+import { outputPathOf, urlOf } from './url-path.js';
+
+/** One file under the client outDir; `path` is relative and uses `/`. */
+export interface OutputFile {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+}
+
+export interface Selection {
+  readonly entries: ReadonlyArray<PrecacheEntry>;
+  readonly bytes: number;
+}
+
+const entryOf = (file: OutputFile, url: string): PrecacheEntry => ({
+  url,
+  revision: revisionOf(file.bytes),
+});
+
+const selection = (
+  picked: ReadonlyArray<readonly [OutputFile, string]>,
+): Selection => ({
+  entries: picked.map(([file, url]) => entryOf(file, url)),
+  bytes: picked.reduce((sum, [file]) => sum + file.bytes.byteLength, 0),
+});
+
+/**
+ * Every Precache entry except HTML documents: scripts, styles, fonts and the
+ * manifest icons, plus `include` matches, minus `exclude` matches. Source
+ * maps and other images stay out unless `include` names them. HTML never
+ * comes in here, because the Build ID is computed from this list and the
+ * documents embed the Build ID.
+ */
+export const selectAssets = (
+  files: ReadonlyArray<OutputFile>,
+  options: {
+    readonly include: ReadonlyArray<string>;
+    readonly exclude: ReadonlyArray<string>;
+    readonly iconUrls: ReadonlyArray<string>;
+    readonly base: string;
+  },
+): Selection & { readonly missingIcons: ReadonlyArray<string> } => {
+  const matches = (globs: ReadonlyArray<string>, path: string) =>
+    globs.some((glob) => matchesGlob(path, glob));
+  const iconPaths = new Map(
+    options.iconUrls.flatMap((url) => {
+      const path = outputPathOf(url, options.base);
+      return path === null ? [] : [[path, url] as const];
+    }),
+  );
+  const picked = files.filter(
+    (file) =>
+      !isHtml(file.path) &&
+      !matches(options.exclude, file.path) &&
+      (matches(options.include, file.path) ||
+        iconPaths.has(file.path) ||
+        (isDefaultAsset(file.path) && !isSourceMap(file.path))),
+  );
+  const present = new Set(files.map((file) => file.path));
+  return {
+    ...selection(picked.map((file) => [file, urlOf(file.path, options.base)])),
+    missingIcons: [...iconPaths]
+      .filter(([path]) => !present.has(path))
+      .map(([, url]) => url),
+  };
+};
+
+/**
+ * The prerendered App Shell and Offline Fallback. Each is keyed by its
+ * navigation path (`/_shell`, `/offline`), which is what the worker looks
+ * up; the file is `<path>.html`, or `<path>/index.html` as a second choice
+ * (hosts that serve it only at `<path>/` then redirect, so it is reported).
+ */
+export const selectDocuments = (
+  files: ReadonlyArray<OutputFile>,
+  paths: ReadonlyArray<string>,
+): Selection & {
+  readonly missing: ReadonlyArray<string>;
+  readonly subfolderIndex: ReadonlyArray<string>;
+} => {
+  const byPath = new Map(files.map((file) => [file.path, file]));
+  const found = paths.map((path) => {
+    const flat = byPath.get(`${path.slice(1)}.html`);
+    const nested = byPath.get(`${path.slice(1)}/index.html`);
+    return { path, file: flat ?? nested, nested: !flat && !!nested };
+  });
+  return {
+    ...selection(
+      found.flatMap(({ path, file }) => (file ? [[file, path] as const] : [])),
+    ),
+    missing: found.filter(({ file }) => !file).map(({ path }) => path),
+    subfolderIndex: found.filter((f) => f.nested).map(({ path }) => path),
+  };
+};

package/src/pwa/vite/precache/revision.ts

@@ -0,0 +1,5 @@
+import { createHash } from 'node:crypto';
+
+/** Content hash of one file; the Precache re-downloads a URL when it changes. */
+export const revisionOf = (bytes: Uint8Array): string =>
+  createHash('sha256').update(bytes).digest('hex').slice(0, 16);

package/src/pwa/vite/precache/url-path.ts

@@ -0,0 +1,21 @@
+/** `base` as `/` or `/app/`. */
+export const normalizeBase = (base: string): string => {
+  const withLead = base.startsWith('/') ? base : `/${base}`;
+  return withLead.endsWith('/') ? withLead : `${withLead}/`;
+};
+
+/** Origin-relative URL of a file under the client outDir. */
+export const urlOf = (path: string, base: string): string =>
+  `${normalizeBase(base)}${path}`;
+
+/**
+ * Output path of a same-origin URL such as a manifest icon `src`, or `null`
+ * when it points elsewhere (another origin, a data URL).
+ */
+export const outputPathOf = (url: string, base: string): string | null => {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) return null;
+  const path = (url.split(/[?#]/)[0] ?? '').replace(/^\.\//, '');
+  if (!path.startsWith('/')) return path;
+  const prefix = normalizeBase(base);
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path.slice(1);
+};

package/src/pwa/vite/vite.ts

@@ -0,0 +1,25 @@
+import * as Schema from 'effect/Schema';
+import type { Plugin } from 'vite';
+import { PwaOptions, resolvePwaConfig } from '../shared/config/index.js';
+import { buildPlugin, makeBuildState } from './build/index.js';
+import { clientModulePlugin } from './client-module/index.js';
+import { devPlugin } from './dev/index.js';
+
+/**
+ * Turns a TanStack Start app into a PWA. Put it after `tanstackStart()`: the
+ * worker builds in a post `buildApp` hook, after the App Shell and Offline
+ * Fallback are prerendered. Start's prerender options are the app's to set;
+ * the build warns with the exact options when those pages are missing.
+ * Invalid options throw here, at config time.
+ */
+export const pwa = (options: PwaOptions = {}): Plugin[] => {
+  const config = resolvePwaConfig(
+    Schema.decodeUnknownSync(PwaOptions)(options),
+  );
+  const state = makeBuildState();
+  return [
+    clientModulePlugin(config, state),
+    buildPlugin(config, state),
+    devPlugin(config),
+  ];
+};

package/src/pwa/vite/worker-bundle/build-module.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from 'vite';
+import { VIRTUAL_BUILD_MODULE_ID } from '../../shared/build/index.js';
+import type { WorkerBuildInfo } from '../../shared/config/index.js';
+import { DEFAULT_ENTRY_ID, DEFAULT_ENTRY_SOURCE } from './entry.js';
+
+const resolved = (id: string) => `\0${id}`;
+
+/**
+ * Serves the worker bundle's virtual modules: `virtual:pwa-toolkit/build`
+ * with the WorkerBuildInfo inlined, and the built-in entry.
+ */
+export const buildModulePlugin = (info: WorkerBuildInfo): Plugin => ({
+  name: 'pwa-toolkit:worker-build-module',
+  enforce: 'pre',
+  resolveId(id) {
+    if (id === VIRTUAL_BUILD_MODULE_ID || id === DEFAULT_ENTRY_ID) {
+      return resolved(id);
+    }
+    return undefined;
+  },
+  load(id) {
+    if (id === resolved(VIRTUAL_BUILD_MODULE_ID)) {
+      return `export default ${JSON.stringify(info)};\n`;
+    }
+    if (id === resolved(DEFAULT_ENTRY_ID)) return DEFAULT_ENTRY_SOURCE;
+    return undefined;
+  },
+});

package/src/pwa/vite/worker-bundle/entry.ts

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const DEFAULT_ENTRY_ID = 'virtual:pwa-toolkit/default-entry';
+
+export const DEFAULT_ENTRY_SOURCE = `import { runServiceWorker } from '@kestack/web-platform/pwa/worker';
+runServiceWorker();
+`;
+
+const APP_ENTRY = 'src/sw.ts';
+
+/**
+ * The worker entry: the `worker` option, else the app's `src/sw.ts`, else the
+ * built-in entry. A configured entry that does not exist is an error.
+ */
+export const resolveWorkerEntry = (
+  root: string,
+  worker: string | null,
+): string => {
+  if (worker !== null) {
+    const path = resolve(root, worker);
+    if (!existsSync(path)) {
+      throw new Error(`pwa-toolkit: worker entry not found: ${path}`);
+    }
+    return path;
+  }
+  const app = resolve(root, APP_ENTRY);
+  return existsSync(app) ? app : DEFAULT_ENTRY_ID;
+};

package/src/pwa/vite/worker-bundle/index.ts

@@ -0,0 +1 @@
+export { workerScript } from './worker-bundle.js';

package/src/pwa/vite/worker-bundle/kill-switch.ts

@@ -0,0 +1,23 @@
+import { CACHE_PREFIX } from '../../shared/build/index.js';
+
+/**
+ * The Kill Switch worker. Plain script with no toolkit runtime, so it works
+ * even when the runtime is what broke: activate at once, delete every toolkit
+ * cache, unregister, then reload the pages it controlled.
+ */
+export const killSwitchSource = (): string => `// pwa-toolkit Kill Switch
+self.addEventListener('install', () => self.skipWaiting());
+self.addEventListener('activate', (event) => {
+  event.waitUntil((async () => {
+    const names = await caches.keys();
+    await Promise.all(
+      names
+        .filter((name) => name.startsWith(${JSON.stringify(CACHE_PREFIX)}))
+        .map((name) => caches.delete(name)),
+    );
+    await self.registration.unregister();
+    const tabs = await self.clients.matchAll({ type: 'window' });
+    await Promise.all(tabs.map((tab) => tab.navigate(tab.url).catch(() => undefined)));
+  })());
+});
+`;

package/src/pwa/vite/worker-bundle/worker-bundle.ts

@@ -0,0 +1,71 @@
+import { type AliasOptions, build, type Rolldown } from 'vite';
+import type { WorkerBuildInfo } from '../../shared/config/index.js';
+import { buildModulePlugin } from './build-module.js';
+import { resolveWorkerEntry } from './entry.js';
+import { killSwitchSource } from './kill-switch.js';
+
+type WorkerScriptInput =
+  | { readonly killSwitch: true }
+  | {
+      readonly killSwitch: false;
+      readonly info: WorkerBuildInfo;
+      /** Vite root of the app. */
+      readonly root: string;
+      /** The `worker` option; `null` picks `src/sw.ts` or the built-in entry. */
+      readonly worker: string | null;
+      readonly mode: string;
+      readonly alias: AliasOptions;
+      readonly minify: boolean;
+    };
+
+const entryChunkOf = (
+  output: Rolldown.RolldownOutput | ReadonlyArray<Rolldown.RolldownOutput>,
+): string => {
+  const outputs = Array.isArray(output) ? output : [output];
+  for (const { output: files } of outputs as Rolldown.RolldownOutput[]) {
+    for (const file of files) {
+      if (file.type === 'chunk' && file.isEntry) return file.code;
+    }
+  }
+  throw new Error('pwa-toolkit: the worker build produced no entry chunk');
+};
+
+/**
+ * The service worker script: the Kill Switch, or the worker entry bundled as
+ * one classic (iife) script with its WorkerBuildInfo inlined. Nothing is
+ * written; the caller decides where the script goes.
+ */
+export const workerScript = async (
+  input: WorkerScriptInput,
+): Promise<string> => {
+  if (input.killSwitch) return killSwitchSource();
+  const output = await build({
+    configFile: false,
+    root: input.root,
+    mode: input.mode,
+    logLevel: 'warn',
+    publicDir: false,
+    resolve: { alias: input.alias },
+    plugins: [buildModulePlugin(input.info)],
+    build: {
+      write: false,
+      copyPublicDir: false,
+      emptyOutDir: false,
+      minify: input.minify,
+      sourcemap: false,
+      modulePreload: false,
+      reportCompressedSize: false,
+      rolldownOptions: {
+        input: resolveWorkerEntry(input.root, input.worker),
+        output: {
+          format: 'iife',
+          entryFileNames: 'sw.js',
+          codeSplitting: false,
+        },
+      },
+    },
+  });
+  return entryChunkOf(
+    output as Rolldown.RolldownOutput | Rolldown.RolldownOutput[],
+  );
+};

package/src/pwa/worker/commands/commands.ts

@@ -0,0 +1,31 @@
+import * as Effect from 'effect/Effect';
+import { type Command, commandReply } from '../../shared/commands/index.js';
+import { attempt, GlobalScope } from '../global-scope/index.js';
+
+/**
+ * Answers one command on the port the client transferred with it. A command
+ * without a port gets no reply (the client times out).
+ */
+export const serveCommand = (
+  command: Command,
+  event: ExtendableMessageEvent,
+): Effect.Effect<void, never, GlobalScope> =>
+  Effect.gen(function* () {
+    const port = event.ports[0];
+    if (port === undefined) return;
+    const reply = yield* answer(command).pipe(
+      Effect.catch((error) =>
+        Effect.succeed(commandReply.failed(error.message)),
+      ),
+    );
+    port.postMessage(reply);
+  });
+
+const answer = (command: Command) => {
+  switch (command.type) {
+    case 'SKIP_WAITING':
+      return Effect.flatMap(GlobalScope, (scope) =>
+        attempt(() => scope.skipWaiting()),
+      ).pipe(Effect.as(commandReply.done()));
+  }
+};

package/src/pwa/worker/commands/index.ts

@@ -0,0 +1 @@
+export { serveCommand } from './commands.js';