@kestack/web-platform 0.0.0-stage → 0.0.0

package/src/pwa/rpc/worker/runner-platform.ts

@@ -0,0 +1,200 @@
+import * as Effect from 'effect/Effect';
+import * as FiberSet from 'effect/FiberSet';
+import * as Option from 'effect/Option';
+import * as Queue from 'effect/Queue';
+import * as Stream from 'effect/Stream';
+import type * as WorkerRunner from 'effect/workers/WorkerRunner';
+import type { BuildId } from '../../shared/build/index.js';
+import type { WorkerHost } from '../../shared/worker-host/index.js';
+import {
+  checkVersionSkew,
+  isRequest,
+  matchClientEnvelope,
+  RPC_ENVELOPE_KEY,
+  type WorkerEnvelope,
+} from '../handshake/index.js';
+import {
+  type Connection,
+  makeConnections,
+  type PageHandle,
+} from './connections.js';
+import { makeKeepAlive } from './keep-alive.js';
+
+/** The part of the Service Worker API `Clients` used to spot closed pages. */
+export interface ClientLookup {
+  get(id: string): Promise<unknown>;
+}
+
+/** While calls are in flight, how often to look for closed pages that sent them. */
+const SWEEP_MS = 10_000;
+
+const isPage = (source: unknown): source is PageHandle =>
+  typeof source === 'object' &&
+  source !== null &&
+  typeof (source as { id?: unknown }).id === 'string' &&
+  typeof (source as { postMessage?: unknown }).postMessage === 'function';
+
+/**
+ * Effect's `WorkerRunnerPlatform` over `WorkerHost.messages`. Each Page
+ * Client connection is one port; replies go through the page's `Client`. A
+ * page that `clients.get` no longer finds is a disconnect. The runner never
+ * ends on its own, even with no pages left: the next message may be the first
+ * of a new connection.
+ */
+export const makeRunnerPlatform = (
+  host: WorkerHost['Service'],
+  clients: ClientLookup,
+): WorkerRunner.WorkerRunnerPlatform['Service'] => ({
+  start: <O, I>() =>
+    Effect.map(Queue.make<number>(), (disconnects) => {
+      const keepAlive = makeKeepAlive();
+      const connections = makeConnections(() => {
+        if (!connections.busy) keepAlive.release();
+      });
+
+      const post = (
+        page: PageHandle,
+        connectionId: string,
+        body:
+          | { readonly type: 'READY' | 'VERSION_SKEW' | 'UNKNOWN_CONNECTION' }
+          | { readonly type: 'MESSAGE'; readonly message: unknown },
+        transfers: ReadonlyArray<unknown> = [],
+      ) => {
+        const envelope: WorkerEnvelope = {
+          [RPC_ENVELOPE_KEY]: 1,
+          buildId: host.buildId,
+          connectionId,
+          ...body,
+        };
+        page.postMessage(envelope, transfers as Transferable[]);
+      };
+
+      const disconnect = (connection: Connection) => {
+        connections.close(connection);
+        Queue.offerUnsafe(disconnects, connection.portId);
+      };
+
+      // A connection this instance never saw (the worker restarted) is
+      // adopted when nothing on it was lost: a new Request from a page with
+      // no other call open. A message event reaches exactly one worker
+      // instance, so the Request cannot run twice.
+      const adopt = (
+        page: PageHandle,
+        envelope: { buildId: BuildId; connectionId: string; open: number },
+        message: unknown,
+      ): Connection | undefined =>
+        envelope.open === 0 &&
+        isRequest(message) &&
+        Option.isNone(checkVersionSkew(envelope.buildId, host.buildId))
+          ? connections.open(page, envelope.connectionId)
+          : undefined;
+
+      const checking = new Set<string>();
+      const checkPage = (clientId: string) => {
+        if (checking.has(clientId)) return;
+        checking.add(clientId);
+        void clients.get(clientId).then(
+          (found) => {
+            checking.delete(clientId);
+            if (found === undefined)
+              connections.ofClient(clientId).forEach(disconnect);
+          },
+          () => checking.delete(clientId),
+        );
+      };
+
+      const sendUnsafe = (
+        portId: number,
+        message: O,
+        transfers?: ReadonlyArray<unknown>,
+      ) => {
+        const connection = connections.byPort(portId);
+        if (connection === undefined) return;
+        connection.inFlight.response(message);
+        post(
+          connection.page,
+          connection.connectionId,
+          { type: 'MESSAGE', message },
+          transfers,
+        );
+        checkPage(connection.clientId);
+      };
+
+      const run = <A, E, R>(
+        handler: (portId: number, message: I) => Effect.Effect<A, E, R> | void,
+      ) =>
+        Effect.scoped(
+          Effect.gen(function* () {
+            const fibers = yield* FiberSet.make<unknown, never>();
+            const fork = yield* FiberSet.runtime(fibers)<R>();
+
+            const onEvent = (event: ExtendableMessageEvent) => {
+              const found = matchClientEnvelope(event.data);
+              const page = event.source;
+              if (Option.isNone(found) || !isPage(page)) return;
+              const envelope = found.value;
+              const connection = connections.find(
+                page.id,
+                envelope.connectionId,
+              );
+              const reply = (
+                type: 'READY' | 'VERSION_SKEW' | 'UNKNOWN_CONNECTION',
+              ) => post(page, envelope.connectionId, { type });
+
+              switch (envelope.type) {
+                case 'CONNECT': {
+                  const skew = checkVersionSkew(envelope.buildId, host.buildId);
+                  if (Option.isSome(skew)) return reply('VERSION_SKEW');
+                  connections.open(page, envelope.connectionId);
+                  return reply('READY');
+                }
+                case 'MESSAGE': {
+                  const current =
+                    connection ?? adopt(page, envelope, envelope.message);
+                  if (current === undefined) return reply('UNKNOWN_CONNECTION');
+                  current.page = page;
+                  current.inFlight.request(envelope.message);
+                  // Before the handler: a call may complete synchronously.
+                  if (connections.busy) keepAlive.extend(event);
+                  const result = handler(current.portId, envelope.message as I);
+                  if (Effect.isEffect(result))
+                    fork(result.pipe(Effect.catchCause(Effect.logError)));
+                  return;
+                }
+                case 'PING':
+                  if (connection === undefined) reply('UNKNOWN_CONNECTION');
+                  return;
+                case 'CLOSE':
+                  if (connection !== undefined) disconnect(connection);
+                  return;
+              }
+            };
+
+            const sweep = setInterval(() => {
+              for (const connection of connections.all())
+                if (connection.inFlight.size > 0)
+                  checkPage(connection.clientId);
+            }, SWEEP_MS);
+            yield* Effect.addFinalizer(() =>
+              Effect.sync(() => clearInterval(sweep)),
+            );
+
+            yield* Stream.runForEach(host.messages, (event) =>
+              Effect.sync(() => {
+                onEvent(event);
+                if (connections.busy) keepAlive.extend(event);
+              }),
+            );
+            return yield* Effect.never;
+          }),
+        );
+
+      return {
+        run,
+        send: (portId, message, transfers) =>
+          Effect.sync(() => sendUnsafe(portId, message, transfers)),
+        sendUnsafe,
+        disconnects,
+      } satisfies WorkerRunner.WorkerRunner<O, I>;
+    }),
+});

package/src/pwa/rpc/worker/worker.ts

@@ -0,0 +1,44 @@
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type * as Rpc from 'effect/rpc/Rpc';
+import type * as RpcGroup from 'effect/rpc/RpcGroup';
+import * as RpcServer from 'effect/rpc/RpcServer';
+import type { WorkerError } from 'effect/workers/WorkerError';
+import { WorkerRunnerPlatform } from 'effect/workers/WorkerRunner';
+import { WorkerHost } from '../../shared/worker-host/index.js';
+import { makeRunnerPlatform } from './runner-platform.js';
+
+declare const self: ServiceWorkerGlobalScope;
+
+const platform = Layer.effect(WorkerRunnerPlatform)(
+  Effect.map(Effect.service(WorkerHost), (host) =>
+    makeRunnerPlatform(host, self.clients),
+  ),
+);
+
+/**
+ * The Worker Server: Effect RPC served inside the service worker over
+ * `WorkerHost.messages`. Provide the group's handlers, then pass the result
+ * to `runServiceWorker({ layer })`.
+ *
+ * Stateless: the browser may stop the worker at any time, and the next
+ * message starts a fresh Worker Server. Worker Clients it no longer knows
+ * reconnect, and their streams resume through Subscription Restart. A page
+ * whose Build ID differs gets `VersionSkew` instead of a connection.
+ */
+export const WorkerServer = {
+  layer: <Rpcs extends Rpc.Any>(
+    group: RpcGroup.RpcGroup<Rpcs>,
+  ): Layer.Layer<
+    never,
+    WorkerError,
+    | WorkerHost
+    | Rpc.ToHandler<Rpcs>
+    | Rpc.Middleware<Rpcs>
+    | Rpc.ServicesServer<Rpcs>
+  > =>
+    RpcServer.layer(group).pipe(
+      Layer.provide(RpcServer.layerProtocolWorkerRunner),
+      Layer.provide(platform),
+    ),
+};

package/src/pwa/shared/build/build.ts

@@ -0,0 +1,78 @@
+import * as Schema from 'effect/Schema';
+import { canonicalJson } from './canonical-json.js';
+import { fnv1a64 } from './fnv1a.js';
+
+/** The identity of one build of the app. */
+export const BuildId = Schema.NonEmptyString.pipe(Schema.brand('BuildId'));
+export type BuildId = typeof BuildId.Type;
+
+/**
+ * One URL saved when a version installs. `url` is origin-relative
+ * (`/assets/app-3f9a.js`); `revision` is a content hash of the file.
+ */
+export const PrecacheEntry = Schema.Struct({
+  url: Schema.String.check(Schema.isStartingWith('/')),
+  revision: Schema.NonEmptyString,
+});
+export type PrecacheEntry = typeof PrecacheEntry.Type;
+
+export const PrecacheList = Schema.Array(PrecacheEntry);
+export type PrecacheList = typeof PrecacheList.Type;
+
+/** Meta tag the page reads its Build ID from: `<meta name=… content=buildId>`. */
+export const BUILD_ID_META_NAME = 'pwa-toolkit:build-id';
+/** Meta tag with the time the build ran, as an ISO 8601 string. */
+export const BUILT_AT_META_NAME = 'pwa-toolkit:built-at';
+/** Meta tag with the git commit the build came from. */
+export const COMMIT_META_NAME = 'pwa-toolkit:commit';
+
+/** Virtual module the plugin serves to the service worker bundle. */
+export const VIRTUAL_BUILD_MODULE_ID = 'virtual:pwa-toolkit/build';
+/** Virtual module the plugin serves to the client and ssr environments. */
+export const VIRTUAL_CLIENT_MODULE_ID = 'virtual:pwa-toolkit/client';
+
+export const MANIFEST_URL = '/manifest.webmanifest';
+
+/** Every cache the toolkit owns starts with this; the Kill Switch deletes them all. */
+export const CACHE_PREFIX = 'pwa-toolkit:';
+const PRECACHE_PREFIX = `${CACHE_PREFIX}precache:`;
+const RUNTIME_PREFIX = `${CACHE_PREFIX}runtime:`;
+
+/** Per-build Precache; old builds' caches are deleted on activate. */
+export const precacheCacheName = (buildId: BuildId): string =>
+  `${PRECACHE_PREFIX}${buildId}`;
+
+/** Runtime Cache for a rule's `cacheName`; survives updates. */
+export const runtimeCacheName = (cacheName: string): string =>
+  `${RUNTIME_PREFIX}${cacheName}`;
+
+/**
+ * Runtime Cache for navigations when `navigation.cachePages` is on. Saved
+ * pages point at their build's hashed assets, so the cache belongs to one
+ * build and is deleted when another activates.
+ */
+export const pagesCacheName = (buildId: BuildId): string =>
+  runtimeCacheName(`pages:${buildId}`);
+
+export const isToolkitCacheName = (name: string): boolean =>
+  name.startsWith(CACHE_PREFIX);
+export const isPrecacheCacheName = (name: string): boolean =>
+  name.startsWith(PRECACHE_PREFIX);
+export const isRuntimeCacheName = (name: string): boolean =>
+  name.startsWith(RUNTIME_PREFIX);
+
+/**
+ * Build ID from the Precache list and the worker config. Entry order does not
+ * matter; the same inputs give the same ID in node and in the browser.
+ */
+export const computeBuildId = (input: {
+  readonly precache: PrecacheList;
+  readonly config: unknown;
+}): BuildId => {
+  const entries = input.precache
+    .map((entry) => `${entry.url}\u0000${entry.revision}`)
+    .sort();
+  return BuildId.make(
+    fnv1a64(`${entries.join('\n')}\u0001${canonicalJson(input.config)}`),
+  );
+};

package/src/pwa/shared/build/canonical-json.ts

@@ -0,0 +1,11 @@
+/** JSON with object keys sorted at every depth, so equal values give equal text. */
+export const canonicalJson = (value: unknown): string =>
+  JSON.stringify(value, (_key, inner: unknown) =>
+    inner !== null && typeof inner === 'object' && !Array.isArray(inner)
+      ? Object.fromEntries(
+          Object.entries(inner).sort(([a], [b]) =>
+            a < b ? -1 : a > b ? 1 : 0,
+          ),
+        )
+      : inner,
+  );

package/src/pwa/shared/build/fnv1a.ts

@@ -0,0 +1,13 @@
+const OFFSET_BASIS = 0xcbf29ce484222325n;
+const PRIME = 0x100000001b3n;
+const MASK = 0xffffffffffffffffn;
+
+/** FNV-1a 64-bit over the UTF-8 bytes of `input`, as 16 lowercase hex chars. */
+export const fnv1a64 = (input: string): string => {
+  let hash = OFFSET_BASIS;
+  for (const byte of new TextEncoder().encode(input)) {
+    hash ^= BigInt(byte);
+    hash = (hash * PRIME) & MASK;
+  }
+  return hash.toString(16).padStart(16, '0');
+};

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

@@ -0,0 +1,19 @@
+export {
+  BUILD_ID_META_NAME,
+  BuildId,
+  BUILT_AT_META_NAME,
+  CACHE_PREFIX,
+  COMMIT_META_NAME,
+  computeBuildId,
+  isPrecacheCacheName,
+  isRuntimeCacheName,
+  isToolkitCacheName,
+  MANIFEST_URL,
+  pagesCacheName,
+  PrecacheEntry,
+  PrecacheList,
+  precacheCacheName,
+  runtimeCacheName,
+  VIRTUAL_BUILD_MODULE_ID,
+  VIRTUAL_CLIENT_MODULE_ID,
+} from './build.js';

package/src/pwa/shared/commands/commands.ts

@@ -0,0 +1,60 @@
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+/**
+ * FROZEN. The one message a page sends a worker outside Worker RPC: it goes
+ * to the waiting worker, a newer build than the page, so every worker
+ * version ever shipped must understand these shapes. Never change or remove
+ * a field; add a new `type` instead. A worker ignores a `type` it does not
+ * know and sends no reply, so senders must time out.
+ */
+export const COMMAND_KEY = '__pwaToolkit';
+const Envelope = { [COMMAND_KEY]: Schema.Literal(1) } as const;
+
+/** Client → worker, via `worker.postMessage(command, [port])`. */
+export const Command = Schema.Struct({
+  ...Envelope,
+  type: Schema.Literal('SKIP_WAITING'),
+});
+export type Command = typeof Command.Type;
+export type CommandType = Command['type'];
+
+/** Worker → client, posted once on the command's transferred `MessagePort`. */
+export const CommandReply = Schema.Union([
+  Schema.Struct({ ...Envelope, type: Schema.Literal('DONE') }),
+  Schema.Struct({
+    ...Envelope,
+    type: Schema.Literal('FAILED'),
+    message: Schema.String,
+  }),
+]);
+export type CommandReply = typeof CommandReply.Type;
+
+export const makeCommand = (type: CommandType): Command => ({
+  [COMMAND_KEY]: 1,
+  type,
+});
+
+export const commandReply = {
+  done: (): CommandReply => ({ [COMMAND_KEY]: 1, type: 'DONE' }),
+  failed: (message: string): CommandReply => ({
+    [COMMAND_KEY]: 1,
+    type: 'FAILED',
+    message,
+  }),
+};
+
+/** Whether `data` carries the command key at all (another listener's message if not). */
+export const isCommandEnvelope = (data: unknown): boolean =>
+  typeof data === 'object' && data !== null && COMMAND_KEY in data;
+
+const decodeCommand = Schema.decodeUnknownOption(Command);
+const decodeReply = Schema.decodeUnknownOption(CommandReply);
+
+export const matchCommand = (data: unknown): Option.Option<Command> =>
+  isCommandEnvelope(data) ? decodeCommand(data) : Option.none();
+
+export const matchCommandReply = (
+  data: unknown,
+): Option.Option<CommandReply> =>
+  isCommandEnvelope(data) ? decodeReply(data) : Option.none();

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

@@ -0,0 +1,11 @@
+export {
+  COMMAND_KEY,
+  CommandReply,
+  commandReply,
+  Command,
+  type CommandType,
+  isCommandEnvelope,
+  makeCommand,
+  matchCommandReply,
+  matchCommand,
+} from './commands.js';

package/src/pwa/shared/config/config.ts

@@ -0,0 +1,185 @@
+import * as Schema from 'effect/Schema';
+import { BuildId, PrecacheList } from '../build/index.js';
+import { WebAppManifest } from '../manifest/index.js';
+import { StrategyRule } from '../strategy/index.js';
+import { PRESET_NAMES, PRESETS } from './presets.js';
+
+const Path = Schema.String.check(Schema.isStartingWith('/'));
+const PositiveInt = Schema.Int.check(Schema.isGreaterThan(0));
+
+/** How navigations resolve: network, then App Shell, then Offline Fallback. */
+export const NavigationConfig = Schema.Struct({
+  shell: Schema.Boolean,
+  shellPath: Path,
+  offlineFallback: Path,
+  networkTimeoutMs: PositiveInt,
+  cachePages: Schema.Boolean,
+  /** Path prefixes whose navigations the worker never handles. */
+  denylist: Schema.Array(Path),
+});
+export type NavigationConfig = typeof NavigationConfig.Type;
+
+/** The page never reloads unasked; it only checks for a newer build this often. */
+export const UpdateConfig = Schema.Struct({
+  checkIntervalMinutes: PositiveInt,
+});
+export type UpdateConfig = typeof UpdateConfig.Type;
+
+/** `include` and `exclude` are globs relative to the client outDir. */
+const PrecacheConfig = Schema.Struct({
+  include: Schema.Array(Schema.String),
+  exclude: Schema.Array(Schema.String),
+  warnAboveBytes: PositiveInt,
+});
+
+/** Options to `pwa({...})`. Everything is optional; see `resolvePwaConfig`. */
+export const PwaOptions = Schema.Struct({
+  enabled: Schema.optionalKey(Schema.Boolean),
+  dev: Schema.optionalKey(Schema.Boolean),
+  preset: Schema.optionalKey(Schema.Literals(PRESET_NAMES)),
+  manifest: Schema.optionalKey(WebAppManifest),
+  precache: Schema.optionalKey(
+    PrecacheConfig.mapFields((f) => ({
+      include: Schema.optionalKey(f.include),
+      exclude: Schema.optionalKey(f.exclude),
+      warnAboveBytes: Schema.optionalKey(f.warnAboveBytes),
+    })),
+  ),
+  strategies: Schema.optionalKey(Schema.Array(StrategyRule)),
+  navigation: Schema.optionalKey(
+    NavigationConfig.mapFields((f) => ({
+      shell: Schema.optionalKey(f.shell),
+      shellPath: Schema.optionalKey(f.shellPath),
+      offlineFallback: Schema.optionalKey(f.offlineFallback),
+      networkTimeoutMs: Schema.optionalKey(f.networkTimeoutMs),
+      cachePages: Schema.optionalKey(f.cachePages),
+      denylist: Schema.optionalKey(f.denylist),
+    })),
+  ),
+  neverCache: Schema.optionalKey(Schema.Array(Path)),
+  update: Schema.optionalKey(
+    UpdateConfig.mapFields((f) => ({
+      checkIntervalMinutes: Schema.optionalKey(f.checkIntervalMinutes),
+    })),
+  ),
+  /** Worker entry, relative to the Vite root. Default: `src/sw.ts` if it exists, else the built-in entry. */
+  worker: Schema.optionalKey(Schema.NonEmptyString),
+  swUrl: Schema.optionalKey(Path),
+  /**
+   * What the page reports about its build. Default: the time the build
+   * runs, and `git rev-parse --short HEAD` (with `-dirty` for uncommitted
+   * changes), or none when git is not available.
+   */
+  version: Schema.optionalKey(
+    Schema.Struct({
+      commit: Schema.optionalKey(Schema.NonEmptyString),
+      builtAt: Schema.optionalKey(Schema.NonEmptyString),
+    }),
+  ),
+});
+/** What the user writes. */
+export type PwaOptions = typeof PwaOptions.Encoded;
+
+export interface ResolvedPwaConfig {
+  readonly enabled: boolean;
+  readonly dev: boolean;
+  readonly preset: (typeof PRESET_NAMES)[number];
+  readonly manifest: WebAppManifest | null;
+  readonly precache: typeof PrecacheConfig.Type;
+  readonly strategies: ReadonlyArray<StrategyRule>;
+  readonly navigation: NavigationConfig;
+  readonly neverCache: ReadonlyArray<string>;
+  readonly update: UpdateConfig;
+  /** `null` means: `src/sw.ts` if it exists, else the built-in entry. */
+  readonly worker: string | null;
+  readonly swUrl: string;
+  /** Overrides from `version`; the plugin fills the rest when it starts. */
+  readonly version: {
+    readonly commit: string | null;
+    readonly builtAt: string | null;
+  };
+}
+
+/**
+ * Fills every default. Precedence: explicit option, then preset, then base.
+ * User `strategies` rules come first, then the preset's (first match wins).
+ */
+export const resolvePwaConfig = (
+  options: typeof PwaOptions.Type,
+): ResolvedPwaConfig => {
+  const preset = options.preset ?? 'app';
+  const defaults = PRESETS[preset];
+  return {
+    enabled: options.enabled ?? true,
+    dev: options.dev ?? false,
+    preset,
+    manifest: options.manifest ?? null,
+    precache: {
+      include: options.precache?.include ?? [],
+      exclude: options.precache?.exclude ?? [],
+      warnAboveBytes: options.precache?.warnAboveBytes ?? 5 * 1024 * 1024,
+    },
+    strategies: [...(options.strategies ?? []), ...defaults.strategies],
+    navigation: {
+      shell: options.navigation?.shell ?? defaults.navigation.shell,
+      shellPath: options.navigation?.shellPath ?? '/_shell',
+      offlineFallback: options.navigation?.offlineFallback ?? '/offline',
+      networkTimeoutMs: options.navigation?.networkTimeoutMs ?? 3000,
+      cachePages:
+        options.navigation?.cachePages ?? defaults.navigation.cachePages,
+      denylist: options.navigation?.denylist ?? [],
+    },
+    neverCache: options.neverCache ?? ['/api/auth/'],
+    update: {
+      checkIntervalMinutes: options.update?.checkIntervalMinutes ?? 60,
+    },
+    worker: options.worker ?? null,
+    swUrl: options.swUrl ?? '/sw.js',
+    version: {
+      commit: options.version?.commit ?? null,
+      builtAt: options.version?.builtAt ?? null,
+    },
+  };
+};
+
+/** The config the worker runs with; part of the Build ID input. */
+export const WorkerConfig = Schema.Struct({
+  strategies: Schema.Array(StrategyRule),
+  navigation: NavigationConfig,
+  neverCache: Schema.Array(Path),
+});
+export type WorkerConfig = typeof WorkerConfig.Type;
+
+export const workerConfigOf = (config: ResolvedPwaConfig): WorkerConfig => ({
+  strategies: config.strategies,
+  navigation: config.navigation,
+  neverCache: config.neverCache,
+});
+
+/** Default export of `virtual:pwa-toolkit/build` (worker bundle only). */
+export const WorkerBuildInfo = Schema.Struct({
+  buildId: BuildId,
+  precache: PrecacheList,
+  config: WorkerConfig,
+});
+export type WorkerBuildInfo = typeof WorkerBuildInfo.Type;
+
+/**
+ * Default export of `virtual:pwa-toolkit/client` (client and ssr).
+ * `buildId` is `null` in the client environment, which builds before the ID
+ * exists; the page reads it from the Build ID meta tag instead.
+ */
+export const ClientBuildInfo = Schema.Struct({
+  enabled: Schema.Boolean,
+  swUrl: Path,
+  scope: Path,
+  update: UpdateConfig,
+  buildId: Schema.NullOr(BuildId),
+  /** When the build ran (ISO 8601). Server environment only, like `buildId`. */
+  builtAt: Schema.NullOr(Schema.String),
+  /** The git commit the build came from. Server environment only. */
+  commit: Schema.NullOr(Schema.String),
+  manifestUrl: Schema.NullOr(Path),
+  appleTouchIconUrl: Schema.NullOr(Schema.String),
+});
+export type ClientBuildInfo = typeof ClientBuildInfo.Type;

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

@@ -0,0 +1,11 @@
+export {
+  ClientBuildInfo,
+  NavigationConfig,
+  PwaOptions,
+  type ResolvedPwaConfig,
+  resolvePwaConfig,
+  UpdateConfig,
+  WorkerBuildInfo,
+  WorkerConfig,
+  workerConfigOf,
+} from './config.js';

package/src/pwa/shared/config/presets.ts

@@ -0,0 +1,45 @@
+import type { StrategyRule } from '../strategy/index.js';
+
+export const PRESET_NAMES = ['app', 'content'] as const;
+export type PresetName = (typeof PRESET_NAMES)[number];
+
+interface Preset {
+  readonly strategies: ReadonlyArray<StrategyRule>;
+  readonly navigation: {
+    readonly shell: boolean;
+    readonly cachePages: boolean;
+  };
+}
+
+const DAY_SECONDS = 24 * 60 * 60;
+
+/**
+ * `app` for signed-in dashboards and tools, `content` for docs and content
+ * sites (settled from the playground's lifecycle runs). Images are left out of the Precache, so every preset caches them at runtime.
+ */
+export const PRESETS: Record<PresetName, Preset> = {
+  app: {
+    strategies: [
+      {
+        match: { origin: 'same-origin', destination: ['image'] },
+        strategy: 'cache-first',
+        cacheName: 'images',
+        maxEntries: 200,
+        maxAgeSeconds: 30 * DAY_SECONDS,
+      },
+    ],
+    navigation: { shell: true, cachePages: false },
+  },
+  content: {
+    strategies: [
+      {
+        match: { origin: 'same-origin', destination: ['image'] },
+        strategy: 'stale-while-revalidate',
+        cacheName: 'images',
+        maxEntries: 300,
+        maxAgeSeconds: 30 * DAY_SECONDS,
+      },
+    ],
+    navigation: { shell: false, cachePages: true },
+  },
+};