@kestack/web-platform 0.0.0-stage → 0.0.0

package/src/pwa/shared/manifest/index.ts

@@ -0,0 +1,5 @@
+export {
+  manifestIconUrls,
+  WebAppManifest,
+  withManifestDefaults,
+} from './manifest.js';

package/src/pwa/shared/manifest/manifest.ts

@@ -0,0 +1,102 @@
+import * as Schema from 'effect/Schema';
+
+const Display = Schema.Literals([
+  'fullscreen',
+  'standalone',
+  'minimal-ui',
+  'browser',
+]);
+
+const DisplayOverride = Schema.Literals([
+  'fullscreen',
+  'standalone',
+  'minimal-ui',
+  'browser',
+  'window-controls-overlay',
+  'tabbed',
+]);
+
+const Orientation = Schema.Literals([
+  'any',
+  'natural',
+  'landscape',
+  'landscape-primary',
+  'landscape-secondary',
+  'portrait',
+  'portrait-primary',
+  'portrait-secondary',
+]);
+
+/** `purpose` is a space-separated list of `any`, `maskable`, `monochrome`. */
+const ManifestImage = Schema.Struct({
+  src: Schema.NonEmptyString,
+  sizes: Schema.optionalKey(Schema.String),
+  type: Schema.optionalKey(Schema.String),
+  purpose: Schema.optionalKey(
+    Schema.String.check(
+      Schema.isPattern(
+        /^(any|maskable|monochrome)( (any|maskable|monochrome))*$/,
+      ),
+    ),
+  ),
+});
+
+const Screenshot = Schema.Struct({
+  ...ManifestImage.fields,
+  form_factor: Schema.optionalKey(Schema.Literals(['narrow', 'wide'])),
+  label: Schema.optionalKey(Schema.String),
+  platform: Schema.optionalKey(Schema.String),
+});
+
+const Shortcut = Schema.Struct({
+  name: Schema.NonEmptyString,
+  short_name: Schema.optionalKey(Schema.String),
+  description: Schema.optionalKey(Schema.String),
+  url: Schema.NonEmptyString,
+  icons: Schema.optionalKey(Schema.Array(ManifestImage)),
+});
+
+/** The W3C Web App Manifest fields the toolkit understands. */
+export const WebAppManifest = Schema.Struct({
+  id: Schema.optionalKey(Schema.String),
+  name: Schema.NonEmptyString,
+  short_name: Schema.optionalKey(Schema.String),
+  description: Schema.optionalKey(Schema.String),
+  lang: Schema.optionalKey(Schema.String),
+  dir: Schema.optionalKey(Schema.Literals(['ltr', 'rtl', 'auto'])),
+  start_url: Schema.optionalKey(Schema.String),
+  scope: Schema.optionalKey(Schema.String),
+  display: Schema.optionalKey(Display),
+  display_override: Schema.optionalKey(Schema.Array(DisplayOverride)),
+  orientation: Schema.optionalKey(Orientation),
+  theme_color: Schema.optionalKey(Schema.String),
+  background_color: Schema.optionalKey(Schema.String),
+  categories: Schema.optionalKey(Schema.Array(Schema.String)),
+  icons: Schema.optionalKey(Schema.Array(ManifestImage)),
+  screenshots: Schema.optionalKey(Schema.Array(Screenshot)),
+  shortcuts: Schema.optionalKey(Schema.Array(Shortcut)),
+});
+export type WebAppManifest = typeof WebAppManifest.Type;
+
+/** The manifest as emitted: `start_url` and `scope` `/`, `display` `standalone`, `id` = `start_url`. */
+export const withManifestDefaults = (
+  manifest: WebAppManifest,
+): WebAppManifest => {
+  const start_url = manifest.start_url ?? '/';
+  return {
+    ...manifest,
+    id: manifest.id ?? start_url,
+    start_url,
+    scope: manifest.scope ?? '/',
+    display: manifest.display ?? 'standalone',
+  };
+};
+
+/** Icon URLs to precache: every icon, never screenshots. */
+export const manifestIconUrls = (
+  manifest: WebAppManifest,
+): ReadonlyArray<string> =>
+  [
+    ...(manifest.icons ?? []),
+    ...(manifest.shortcuts ?? []).flatMap((shortcut) => shortcut.icons ?? []),
+  ].map((icon) => icon.src);

package/src/pwa/shared/strategy/index.ts

@@ -0,0 +1,8 @@
+export {
+  findStrategyRule,
+  isNeverCached,
+  matchStrategyRule,
+  type RequestLike,
+  StrategyRule,
+  StrategyName,
+} from './strategy.js';

package/src/pwa/shared/strategy/pattern.ts

@@ -0,0 +1,20 @@
+const compiled = new Map<string, RegExp>();
+
+/** Compiles a regex source once and reuses it; rules are matched per request. */
+export const compilePattern = (source: string): RegExp => {
+  let regExp = compiled.get(source);
+  if (regExp === undefined) {
+    regExp = new RegExp(source);
+    compiled.set(source, regExp);
+  }
+  return regExp;
+};
+
+export const isValidPattern = (source: string): boolean => {
+  try {
+    compilePattern(source);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/src/pwa/shared/strategy/strategy.ts

@@ -0,0 +1,107 @@
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { compilePattern, isValidPattern } from './pattern.js';
+
+export const StrategyName = Schema.Literals([
+  'network-first',
+  'cache-first',
+  'stale-while-revalidate',
+  'network-only',
+  'cache-only',
+]);
+export type StrategyName = typeof StrategyName.Type;
+
+/**
+ * Which GET requests a rule applies to. Every present condition must hold.
+ * `origin` is `'same-origin'` (the default) or an exact origin such as
+ * `'https://fonts.gstatic.com'`; `pattern` is a regex source tested against
+ * the full URL; `destination` lists `Request.destination` values.
+ */
+const RuntimeCacheMatch = Schema.Struct({
+  origin: Schema.String.pipe(
+    Schema.withDecodingDefaultKey(Effect.succeed('same-origin')),
+  ),
+  pathPrefix: Schema.optionalKey(
+    Schema.String.check(Schema.isStartingWith('/')),
+  ),
+  pattern: Schema.optionalKey(
+    Schema.String.check(
+      Schema.makeFilter<string>((source) => isValidPattern(source), {
+        expected: 'a valid RegExp source',
+      }),
+    ),
+  ),
+  destination: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+
+/**
+ * One Runtime Cache rule. `cacheName` is the rule's own name (lowercase,
+ * digits, dashes); the real cache is `runtimeCacheName(cacheName)`.
+ * `networkTimeoutMs` applies to `network-first` only.
+ */
+export const StrategyRule = Schema.Struct({
+  match: RuntimeCacheMatch,
+  strategy: StrategyName,
+  cacheName: Schema.String.check(Schema.isPattern(/^[a-z0-9][a-z0-9-]*$/)),
+  networkTimeoutMs: Schema.optionalKey(PositiveInt),
+  maxEntries: Schema.optionalKey(PositiveInt),
+  maxAgeSeconds: Schema.optionalKey(PositiveInt),
+});
+export type StrategyRule = typeof StrategyRule.Type;
+
+/** The parts of a `Request` rule matching reads; a real `Request` fits. */
+export interface RequestLike {
+  readonly url: string;
+  readonly method: string;
+  readonly destination: string;
+}
+
+/** Whether `rule` applies to `request`, seen from a worker at `selfOrigin`. */
+export const matchStrategyRule = (
+  rule: StrategyRule,
+  request: RequestLike,
+  selfOrigin: string,
+): boolean => {
+  if (request.method !== 'GET') return false;
+  const url = new URL(request.url);
+  const { match } = rule;
+  const origin = match.origin === 'same-origin' ? selfOrigin : match.origin;
+  return (
+    url.origin === origin &&
+    (match.pathPrefix === undefined ||
+      url.pathname.startsWith(match.pathPrefix)) &&
+    (match.pattern === undefined ||
+      compilePattern(match.pattern).test(url.href)) &&
+    (match.destination === undefined ||
+      match.destination.includes(request.destination))
+  );
+};
+
+/** The first matching rule; rule order is priority. */
+export const findStrategyRule = (
+  rules: ReadonlyArray<StrategyRule>,
+  request: RequestLike,
+  selfOrigin: string,
+): Option.Option<StrategyRule> =>
+  Option.fromNullishOr(
+    rules.find((rule) => matchStrategyRule(rule, request, selfOrigin)),
+  );
+
+/**
+ * Whether a same-origin request's path starts with a `neverCache` prefix.
+ * Such requests bypass every cache, including navigations.
+ */
+export const isNeverCached = (
+  neverCache: ReadonlyArray<string>,
+  request: Pick<RequestLike, 'url'>,
+  selfOrigin: string,
+): boolean => {
+  const url = new URL(request.url);
+  return (
+    url.origin === selfOrigin &&
+    neverCache.some((prefix) => url.pathname.startsWith(prefix))
+  );
+};

package/src/pwa/shared/worker-host/index.ts

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

package/src/pwa/shared/worker-host/worker-host.ts

@@ -0,0 +1,22 @@
+import * as Context from 'effect/Context';
+import type * as Stream from 'effect/Stream';
+import type { BuildId } from '../build/index.js';
+
+interface WorkerHostService {
+  readonly buildId: BuildId;
+  /**
+   * Every `message` event that is not a command, from worker
+   * start. Listeners are registered synchronously at script start and events
+   * are buffered until the first subscriber, so none are lost.
+   */
+  readonly messages: Stream.Stream<ExtendableMessageEvent>;
+}
+
+/**
+ * What the service worker runtime offers the `layer` given to
+ * `runServiceWorker`. Worker RPC's Worker Server builds on it.
+ */
+export class WorkerHost extends Context.Service<
+  WorkerHost,
+  WorkerHostService
+>()('@kestack/web-platform/pwa/WorkerHost') {}

package/src/pwa/splash/devices.ts

@@ -0,0 +1,28 @@
+// Every iOS screen the Splash is drawn for, in portrait points. Screens
+// that share a size and scale share a row. iPhones open in portrait only;
+// an iPad opens either way, so it gets both.
+export const PHONES = [
+  { width: 440, height: 956, scale: 3 }, // 16 Pro Max, 17 Pro Max
+  { width: 430, height: 932, scale: 3 }, // 14 Pro Max, 15 Plus, 15 Pro Max, 16 Plus
+  { width: 428, height: 926, scale: 3 }, // 12 Pro Max, 13 Pro Max, 14 Plus
+  { width: 420, height: 912, scale: 3 }, // Air
+  { width: 414, height: 896, scale: 3 }, // XS Max, 11 Pro Max
+  { width: 414, height: 896, scale: 2 }, // XR, 11
+  { width: 402, height: 874, scale: 3 }, // 16 Pro, 17, 17 Pro
+  { width: 393, height: 852, scale: 3 }, // 14 Pro, 15, 15 Pro, 16
+  { width: 390, height: 844, scale: 3 }, // 12, 13, 14, 16e
+  { width: 375, height: 812, scale: 3 }, // X, XS, 11 Pro, 12 mini, 13 mini
+  { width: 375, height: 667, scale: 2 }, // SE (2nd and 3rd), 8
+] as const;
+
+export const TABLETS = [
+  { width: 1032, height: 1376, scale: 2 }, // Pro 13" (M4)
+  { width: 1024, height: 1366, scale: 2 }, // Pro 12.9"
+  { width: 834, height: 1210, scale: 2 }, // Pro 11" (M4)
+  { width: 834, height: 1194, scale: 2 }, // Pro 11", Air 11"
+  { width: 834, height: 1112, scale: 2 }, // Air 10.5"
+  { width: 820, height: 1180, scale: 2 }, // Air 10.9", 10th and 11th gen
+  { width: 810, height: 1080, scale: 2 }, // 7th to 9th gen
+  { width: 768, height: 1024, scale: 2 }, // mini 5th gen
+  { width: 744, height: 1133, scale: 2 }, // mini 6th gen and later
+] as const;

package/src/pwa/splash/index.ts

@@ -0,0 +1 @@
+export { splashHead, splashScreens } from './splash.ts';

package/src/pwa/splash/splash.ts

@@ -0,0 +1,44 @@
+import { PHONES, TABLETS } from './devices.ts';
+
+type Device = (typeof PHONES)[number] | (typeof TABLETS)[number];
+type Orientation = 'portrait' | 'landscape';
+
+// iOS matches a startup image by the screen's portrait size in points,
+// its scale and the way it is held; the image is in pixels, as held.
+const screen = (device: Device, tablet: boolean, orientation: Orientation) => {
+  const portrait = orientation === 'portrait';
+  const width = (portrait ? device.width : device.height) * device.scale;
+  const height = (portrait ? device.height : device.width) * device.scale;
+  return {
+    tablet,
+    scale: device.scale,
+    width,
+    height,
+    href: `/splash/${width}x${height}.png`,
+    media: `(device-width: ${device.width}px) and (device-height: ${device.height}px) and (-webkit-device-pixel-ratio: ${device.scale}) and (orientation: ${orientation})`,
+  };
+};
+
+/** Each Splash image: its size in pixels, where it is served, and the iOS screen it is for. */
+export const splashScreens = [
+  ...PHONES.map((device) => screen(device, false, 'portrait')),
+  ...TABLETS.flatMap((device) => [
+    screen(device, true, 'portrait'),
+    screen(device, true, 'landscape'),
+  ]),
+];
+
+/**
+ * The tags that give iOS the Splash. iOS shows a startup image only with
+ * `apple-mobile-web-app-capable`; the status bar still follows a theme
+ * switch, as the theme's StatusBar strip paints the top edge. Android draws
+ * its own Splash from the manifest's name, icon and background colour.
+ */
+export const splashHead = () => ({
+  meta: [{ name: 'apple-mobile-web-app-capable', content: 'yes' }],
+  links: splashScreens.map((each) => ({
+    rel: 'apple-touch-startup-image',
+    href: each.href,
+    media: each.media,
+  })),
+});

package/src/pwa/virtual.d.ts

@@ -0,0 +1,13 @@
+// Virtual modules served by `pwa()`. Ids live in `shared/build`.
+
+declare module 'virtual:pwa-toolkit/build' {
+  import type { WorkerBuildInfo } from './shared/config/index.js';
+  const info: WorkerBuildInfo;
+  export default info;
+}
+
+declare module 'virtual:pwa-toolkit/client' {
+  import type { ClientBuildInfo } from './shared/config/index.js';
+  const info: ClientBuildInfo;
+  export default info;
+}

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

@@ -0,0 +1,153 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import type { Plugin, ResolvedConfig, ViteBuilder } from 'vite';
+import { computeBuildId, MANIFEST_URL } from '../../shared/build/index.js';
+import {
+  type ResolvedPwaConfig,
+  workerConfigOf,
+} from '../../shared/config/index.js';
+import {
+  manifestIconUrls,
+  withManifestDefaults,
+} from '../../shared/manifest/index.js';
+import type { BuildState } from './build-state.js';
+import { mergeHeaders } from './headers.js';
+import { bundleFiles, overlay, readTree } from './output-files.js';
+import { selectAssets, selectDocuments } from '../precache/index.js';
+import {
+  assertAfterStart,
+  missingDocumentsMessage,
+  subfolderIndexMessage,
+} from './start-setup.js';
+import { workerScript } from '../worker-bundle/index.js';
+
+const NAME = 'pwa-toolkit:build';
+
+const writeOutput = async (path: string, content: string) => {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
+};
+
+const readOptional = (path: string): Promise<string | null> =>
+  readFile(path, 'utf8').catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  });
+
+/**
+ * The production pipeline. In the client environment's `generateBundle`:
+ * emit the manifest, pick the non-HTML Precache entries and compute the
+ * Build ID. In a post `buildApp` hook, after every environment and Start's
+ * prerender: add the App Shell and Offline Fallback, write the worker (or
+ * the Kill Switch) to the client outDir, and merge `_headers`.
+ */
+export const buildPlugin = (
+  config: ResolvedPwaConfig,
+  state: BuildState,
+): Plugin => {
+  let vite: ResolvedConfig;
+
+  const writeWorker = async (builder: ViteBuilder) => {
+    const environments = Object.values(builder.environments);
+    // Without a builder that builds them (a plain Vite app), Vite builds
+    // every environment after the post hooks; do it now, as Vite would.
+    if (environments.every((environment) => !environment.isBuilt)) {
+      for (const environment of environments) await builder.build(environment);
+    }
+    const client = builder.environments['client'];
+    if (!client) throw new Error('pwa-toolkit: no client environment');
+    const outDir = resolve(client.config.root, client.config.build.outDir);
+    const script = config.enabled
+      ? await workerScript({
+          killSwitch: false,
+          info: await finalBuildInfo(outDir),
+          root: client.config.root,
+          worker: config.worker,
+          mode: vite.mode,
+          alias: vite.resolve.alias,
+          minify: client.config.build.minify !== false,
+        })
+      : await workerScript({ killSwitch: true });
+    await writeOutput(join(outDir, config.swUrl), script);
+    const headersPath = join(outDir, '_headers');
+    const noCache = config.manifest
+      ? [config.swUrl, MANIFEST_URL]
+      : [config.swUrl];
+    await writeOutput(
+      headersPath,
+      mergeHeaders(await readOptional(headersPath), noCache),
+    );
+  };
+
+  const finalBuildInfo = async (outDir: string) => {
+    const { assets, buildId } = state;
+    if (!assets || !buildId) {
+      throw new Error(
+        'pwa-toolkit: the client environment produced no Build ID',
+      );
+    }
+    const { navigation } = config;
+    const documents = selectDocuments(await readTree(outDir), [
+      ...(navigation.shell ? [navigation.shellPath] : []),
+      navigation.offlineFallback,
+    ]);
+    if (documents.missing.length > 0) {
+      vite.logger.warn(missingDocumentsMessage(navigation, documents.missing));
+    }
+    if (documents.subfolderIndex.length > 0) {
+      vite.logger.warn(subfolderIndexMessage(documents.subfolderIndex));
+    }
+    const bytes = assets.bytes + documents.bytes;
+    if (bytes > config.precache.warnAboveBytes) {
+      vite.logger.warn(
+        `pwa-toolkit: the Precache is ${(bytes / 1024 / 1024).toFixed(1)} MiB; every install downloads all of it. Narrow it with precache.exclude.`,
+      );
+    }
+    return {
+      buildId,
+      precache: [...assets.entries, ...documents.entries],
+      config: workerConfigOf(config),
+    };
+  };
+
+  return {
+    name: NAME,
+    apply: 'build',
+    enforce: 'post',
+    sharedDuringBuild: true,
+    configResolved(resolved) {
+      vite = resolved;
+      assertAfterStart(resolved.plugins, NAME);
+    },
+    async generateBundle(_options, bundle) {
+      if (this.environment.name !== 'client') return;
+      if (config.manifest) {
+        this.emitFile({
+          type: 'asset',
+          fileName: MANIFEST_URL.slice(1),
+          source: `${JSON.stringify(withManifestDefaults(config.manifest), null, 2)}\n`,
+        });
+      }
+      if (!config.enabled) return;
+      const env = this.environment.config;
+      const publicFiles =
+        env.publicDir && env.build.copyPublicDir
+          ? await readTree(env.publicDir)
+          : [];
+      const assets = selectAssets(overlay(publicFiles, bundleFiles(bundle)), {
+        ...config.precache,
+        iconUrls: config.manifest ? manifestIconUrls(config.manifest) : [],
+        base: env.base,
+      });
+      for (const url of assets.missingIcons) {
+        this.warn(`manifest icon ${url} is not in the build output`);
+      }
+      state.assets = assets;
+      state.buildId = computeBuildId({
+        precache: assets.entries,
+        config: workerConfigOf(config),
+      });
+    },
+    buildApp: { order: 'post', handler: writeWorker },
+  };
+};

package/src/pwa/vite/build/build-state.ts

@@ -0,0 +1,17 @@
+import type { BuildId } from '../../shared/build/index.js';
+import type { Selection } from '../precache/index.js';
+
+/**
+ * What the client environment's build leaves for the later steps: the
+ * non-HTML Precache entries and the Build ID computed from them. The server
+ * environment reads the Build ID; the worker build reads both.
+ */
+export interface BuildState {
+  assets: Selection | null;
+  buildId: BuildId | null;
+}
+
+export const makeBuildState = (): BuildState => ({
+  assets: null,
+  buildId: null,
+});

package/src/pwa/vite/build/headers.ts

@@ -0,0 +1,34 @@
+const BEGIN = '# pwa-toolkit: begin';
+const END = '# pwa-toolkit: end';
+
+const withoutManagedBlock = (text: string): string => {
+  const begin = text.indexOf(BEGIN);
+  const end = text.indexOf(END);
+  if (begin === -1 || end < begin) return text;
+  return text.slice(0, begin) + text.slice(end + END.length).replace(/^\n/, '');
+};
+
+/**
+ * Cloudflare `_headers` with `Cache-Control: no-cache` for each path, so
+ * browsers always revalidate the worker script and the manifest. The app's
+ * own rules stay as they are; a path the app already lists is left to it.
+ * Re-running replaces the toolkit's block instead of adding another.
+ */
+export const mergeHeaders = (
+  existing: string | null,
+  paths: ReadonlyArray<string>,
+): string => {
+  const own = withoutManagedBlock(existing ?? '');
+  const listed = new Set(
+    own
+      .split('\n')
+      .filter((line) => line.length > 0 && !/^\s/.test(line))
+      .map((line) => line.trim()),
+  );
+  const rules = paths
+    .filter((path) => !listed.has(path))
+    .map((path) => `${path}\n  Cache-Control: no-cache`);
+  if (rules.length === 0) return own;
+  const head = own.length === 0 || own.endsWith('\n') ? own : `${own}\n`;
+  return `${head}${BEGIN}\n${rules.join('\n')}\n${END}\n`;
+};

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

@@ -0,0 +1,2 @@
+export { buildPlugin } from './build-plugin.js';
+export { type BuildState, makeBuildState } from './build-state.js';

package/src/pwa/vite/build/output-files.ts

@@ -0,0 +1,49 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import type { Rolldown } from 'vite';
+import type { OutputFile } from '../precache/index.js';
+
+/** Every file under `dir` (none when it does not exist), paths relative with `/`. */
+export const readTree = async (dir: string): Promise<OutputFile[]> => {
+  const entries = await readdir(dir, {
+    recursive: true,
+    withFileTypes: true,
+  }).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  });
+  return Promise.all(
+    entries
+      .filter((entry) => entry.isFile())
+      .map(async (entry) => {
+        const path = join(entry.parentPath, entry.name);
+        return {
+          path: relative(dir, path).split(sep).join('/'),
+          bytes: new Uint8Array(await readFile(path)),
+        };
+      }),
+  );
+};
+
+const encoder = new TextEncoder();
+
+/** The files a Rolldown bundle is about to write. */
+export const bundleFiles = (bundle: Rolldown.OutputBundle): OutputFile[] =>
+  Object.values(bundle).map((file) => ({
+    path: file.fileName,
+    bytes:
+      file.type === 'chunk'
+        ? encoder.encode(file.code)
+        : typeof file.source === 'string'
+          ? encoder.encode(file.source)
+          : file.source,
+  }));
+
+/** `later` wins over `earlier` for the same path, as a bundle output overwrites a public file. */
+export const overlay = (
+  earlier: ReadonlyArray<OutputFile>,
+  later: ReadonlyArray<OutputFile>,
+): OutputFile[] => {
+  const paths = new Set(later.map((file) => file.path));
+  return [...earlier.filter((file) => !paths.has(file.path)), ...later];
+};

package/src/pwa/vite/build/start-setup.ts

@@ -0,0 +1,50 @@
+import type { NavigationConfig } from '../../shared/config/index.js';
+
+// Start's plugin whose post `buildApp` hook prerenders pages.
+const START_POST_BUILD = 'tanstack-start-core:post-build';
+
+/**
+ * The worker must build after Start prerenders the App Shell and Offline
+ * Fallback. Both post `buildApp` hooks run in plugin order, so `pwa()` has
+ * to come after `tanstackStart()`.
+ */
+export const assertAfterStart = (
+  plugins: ReadonlyArray<{ readonly name: string }>,
+  ownName: string,
+): void => {
+  const names = plugins.map((plugin) => plugin.name);
+  const start = names.indexOf(START_POST_BUILD);
+  if (start !== -1 && start > names.indexOf(ownName)) {
+    throw new Error(
+      'pwa-toolkit: put pwa() after tanstackStart() in the Vite plugins, so the worker builds after prerendering',
+    );
+  }
+};
+
+/**
+ * Start's plugin keeps its options to itself, so the app sets the prerender
+ * options; this names exactly what is missing.
+ */
+export const missingDocumentsMessage = (
+  navigation: NavigationConfig,
+  missing: ReadonlyArray<string>,
+): string => {
+  const lines = [
+    `pwa-toolkit: not in the Precache, no prerendered HTML for ${missing.join(', ')}. Set in tanstackStart({...}):`,
+  ];
+  if (navigation.shell && missing.includes(navigation.shellPath)) {
+    lines.push(
+      `  spa: { enabled: true, prerender: { outputPath: '${navigation.shellPath}' } },`,
+    );
+  }
+  if (missing.includes(navigation.offlineFallback)) {
+    lines.push(
+      `  pages: [{ path: '${navigation.offlineFallback}', prerender: { enabled: true, crawlLinks: false, autoSubfolderIndex: false } }],`,
+      '  prerender: { autoStaticPathsDiscovery: false },',
+    );
+  }
+  return lines.join('\n');
+};
+
+export const subfolderIndexMessage = (paths: ReadonlyArray<string>): string =>
+  `pwa-toolkit: ${paths.join(', ')} prerendered as <path>/index.html, which hosts redirect to <path>/. Set prerender: { autoSubfolderIndex: false } on those pages.`;