@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/pwa/extras/online/online.ts

@@ -0,0 +1,35 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as SubscriptionRef from 'effect/SubscriptionRef';
+import { isBrowser, listen } from '../../browser/dom-events.js';
+import { useSubscriptionRef } from '../../browser/subscription-ref.js';
+import { lazyService } from '../lazy-service/index.js';
+
+/** `navigator.onLine`: false means surely offline; true only means a network exists. */
+export class Online extends Context.Service<
+  Online,
+  { readonly online: SubscriptionRef.SubscriptionRef<boolean> }
+>()('@kestack/web-platform/pwa/Online') {
+  static readonly layer: Layer.Layer<Online> = Layer.effect(
+    this,
+    Effect.gen(function* () {
+      const online = yield* SubscriptionRef.make(
+        isBrowser() ? navigator.onLine : true,
+      );
+      if (isBrowser()) {
+        const set = (value: boolean) => () =>
+          Effect.runSync(SubscriptionRef.set(online, value));
+        yield* listen(window, 'online', set(true));
+        yield* listen(window, 'offline', set(false));
+      }
+      return { online };
+    }),
+  );
+}
+
+const useOnlineService = lazyService(Online, Online.layer);
+
+/** Whether the browser is online; `true` during SSR and until known. */
+export const useOnline = (): boolean =>
+  useSubscriptionRef(useOnlineService()?.online, true);

package/src/pwa/extras/storage/index.ts

@@ -0,0 +1 @@
+export { StoragePersistence, useStoragePersistence } from './storage.js';

package/src/pwa/extras/storage/storage.ts

@@ -0,0 +1,101 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import { useEffect, useMemo, useState } from 'react';
+import { lazyService } from '../lazy-service/index.js';
+
+const storage = (): Option.Option<StorageManager> =>
+  typeof navigator !== 'undefined' && navigator.storage !== undefined
+    ? Option.some(navigator.storage)
+    : Option.none();
+
+const call = <K extends 'persisted' | 'persist' | 'estimate'>(
+  method: K,
+): Effect.Effect<Option.Option<Awaited<ReturnType<StorageManager[K]>>>> =>
+  Effect.suspend(() =>
+    Option.match(
+      Option.filter(storage(), (s) => typeof s[method] === 'function'),
+      {
+        onNone: () => Effect.succeed(Option.none()),
+        onSome: (s) =>
+          Effect.tryPromise(
+            () =>
+              s[method]() as Promise<Awaited<ReturnType<StorageManager[K]>>>,
+          ).pipe(Effect.map(Option.some), Effect.orElseSucceed(Option.none)),
+      },
+    ),
+  );
+
+/** Persistent storage and usage. Every member is none where the Storage API is missing. */
+export class StoragePersistence extends Context.Service<
+  StoragePersistence,
+  {
+    readonly persisted: Effect.Effect<Option.Option<boolean>>;
+    readonly persist: Effect.Effect<Option.Option<boolean>>;
+    readonly estimate: Effect.Effect<
+      Option.Option<{ readonly usage: number; readonly quota: number }>
+    >;
+  }
+>()('@kestack/web-platform/pwa/StoragePersistence') {
+  static readonly layer: Layer.Layer<StoragePersistence> = Layer.succeed(this, {
+    persisted: call('persisted'),
+    persist: call('persist'),
+    estimate: call('estimate').pipe(
+      Effect.map(
+        Option.map((estimate) => ({
+          usage: estimate.usage ?? 0,
+          quota: estimate.quota ?? 0,
+        })),
+      ),
+    ),
+  });
+}
+
+const useStorageService = lazyService(
+  StoragePersistence,
+  StoragePersistence.layer,
+);
+
+const runOr = <A>(effect: Effect.Effect<A> | undefined, fallback: A) =>
+  effect === undefined ? Promise.resolve(fallback) : Effect.runPromise(effect);
+
+/** `null` while unknown or where the Storage API is missing. */
+export const useStoragePersistence = (): {
+  readonly persisted: boolean | null;
+  readonly persist: () => Promise<boolean | null>;
+  readonly estimate: () => Promise<{
+    readonly usage: number;
+    readonly quota: number;
+  } | null>;
+} => {
+  const service = useStorageService();
+  const [persisted, setPersisted] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    if (service === undefined) return;
+    let mounted = true;
+    void Effect.runPromise(service.persisted).then(
+      (value) => mounted && setPersisted(Option.getOrNull(value)),
+    );
+    return () => {
+      mounted = false;
+    };
+  }, [service]);
+
+  return useMemo(
+    () => ({
+      persisted,
+      persist: async () => {
+        const value = Option.getOrNull(
+          await runOr(service?.persist, Option.none()),
+        );
+        setPersisted(value);
+        return value;
+      },
+      estimate: async () =>
+        Option.getOrNull(await runOr(service?.estimate, Option.none())),
+    }),
+    [persisted, service],
+  );
+};

package/src/pwa/index.ts

@@ -0,0 +1,5 @@
+// The PWA on the page: plug `pwaRoot` into the root document; the rest is
+// for screens that show the PWA's state.
+export * from './react/index.js';
+export { pwaRoot } from './root/index.ts';
+export { splashHead, splashScreens } from './splash/index.ts';

package/src/pwa/react/head.ts

@@ -0,0 +1,69 @@
+import {
+  BUILD_ID_META_NAME,
+  BUILT_AT_META_NAME,
+  COMMIT_META_NAME,
+} from '../shared/build/index.js';
+import type { ClientBuildInfo } from '../shared/config/index.js';
+
+export interface HeadTags {
+  readonly meta: Array<{ readonly name: string; readonly content: string }>;
+  readonly links: Array<{
+    readonly rel: string;
+    readonly href: string;
+    readonly sizes?: string;
+  }>;
+}
+
+/**
+ * The build this page came from. `builtAt` is an ISO 8601 string, so the
+ * server and the browser render the same text; format it after mount.
+ * Each field is `null` when the build has none (`buildId` while the PWA is off).
+ */
+export interface PwaVersion {
+  readonly buildId: string | null;
+  readonly builtAt: string | null;
+  readonly commit: string | null;
+}
+
+const metaContent = (name: string): string | null =>
+  document.querySelector(`meta[name="${name}"]`)?.getAttribute('content') ??
+  null;
+
+/**
+ * The server knows the build from the virtual module; the client build does
+ * not, so in the browser it reads the tags the server rendered. The page
+ * then reports the build that rendered it, even while a newer one waits.
+ */
+export const pageVersion = (info: ClientBuildInfo): PwaVersion =>
+  typeof document === 'undefined'
+    ? { buildId: info.buildId, builtAt: info.builtAt, commit: info.commit }
+    : {
+        buildId: metaContent(BUILD_ID_META_NAME),
+        builtAt: metaContent(BUILT_AT_META_NAME),
+        commit: metaContent(COMMIT_META_NAME),
+      };
+
+const metaOf = (name: string, content: string | null) =>
+  content === null ? [] : [{ name, content }];
+
+export const headTags = (
+  info: ClientBuildInfo,
+  version: PwaVersion,
+): HeadTags => ({
+  // No `apple-mobile-web-app-capable`: it puts iOS home-screen apps in the
+  // legacy mode, where the status bar ignores an in-place theme switch.
+  meta: [
+    { name: 'mobile-web-app-capable', content: 'yes' },
+    ...metaOf(BUILD_ID_META_NAME, version.buildId),
+    ...metaOf(BUILT_AT_META_NAME, version.builtAt),
+    ...metaOf(COMMIT_META_NAME, version.commit),
+  ],
+  links: [
+    ...(info.manifestUrl === null
+      ? []
+      : [{ rel: 'manifest', href: info.manifestUrl }]),
+    ...(info.appleTouchIconUrl === null
+      ? []
+      : [{ rel: 'apple-touch-icon', href: info.appleTouchIconUrl }]),
+  ],
+});

package/src/pwa/react/index.ts

@@ -0,0 +1,3 @@
+export { clearRuntimeCache, PwaProvider, pwaHead, usePwa } from './react.js';
+export type { PwaVersion } from './head.js';
+export { UpdatePrompt } from './update-prompt.js';

package/src/pwa/react/react.tsx

@@ -0,0 +1,98 @@
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import info from 'virtual:pwa-toolkit/client';
+import { useSubscriptionRef } from '../browser/subscription-ref.js';
+import {
+  clearRuntimeCache as clearRuntimeCacheEffect,
+  Pwa,
+  PwaStatus,
+} from '../client/index.js';
+import {
+  type HeadTags,
+  headTags,
+  pageVersion,
+  type PwaVersion,
+} from './head.js';
+
+/** `null` outside `PwaProvider`, during SSR, and until the service is built. */
+const PwaContext = createContext<Pwa['Service'] | null>(null);
+
+const UNSUPPORTED = PwaStatus.Unsupported();
+
+/**
+ * Registers the service worker after mount (never during SSR) and gives
+ * `usePwa` its status. Render it once, in the root route.
+ */
+export const PwaProvider = (props: {
+  readonly children?: ReactNode;
+}): ReactNode => {
+  const [pwa, setPwa] = useState<Pwa['Service'] | null>(null);
+
+  useEffect(() => {
+    const runtime = ManagedRuntime.make(Pwa.layer(info));
+    let mounted = true;
+    runtime.context().then(
+      (context) => mounted && setPwa(Context.get(context, Pwa)),
+      (error: unknown) =>
+        console.error('pwa-toolkit: client failed to start', error),
+    );
+    return () => {
+      mounted = false;
+      setPwa(null);
+      void runtime.dispose();
+    };
+  }, []);
+
+  return (
+    <PwaContext.Provider value={pwa}>{props.children}</PwaContext.Provider>
+  );
+};
+
+/**
+ * The PWA's status with `checkForUpdate` and `applyUpdate`, and the
+ * `version` this page runs. `status` is `Unsupported` during SSR and until
+ * `PwaProvider` has started; `version` is known from the first render.
+ */
+export const usePwa = (): {
+  readonly status: PwaStatus;
+  readonly version: PwaVersion;
+  readonly checkForUpdate: () => Promise<void>;
+  readonly applyUpdate: () => Promise<void>;
+} => {
+  const pwa = useContext(PwaContext);
+  const status = useSubscriptionRef(pwa?.status, UNSUPPORTED);
+  const version = useMemo(() => pageVersion(info), []);
+  return useMemo(
+    () => ({
+      status,
+      version,
+      checkForUpdate: () =>
+        pwa === null
+          ? Promise.resolve()
+          : Effect.runPromise(pwa.checkForUpdate),
+      applyUpdate: () =>
+        pwa === null ? Promise.resolve() : Effect.runPromise(pwa.applyUpdate),
+    }),
+    [status, version, pwa],
+  );
+};
+
+/** Deletes every Runtime Cache. Works outside `PwaProvider` (e.g. in sign-out). */
+export const clearRuntimeCache = (): Promise<void> =>
+  Effect.runPromise(clearRuntimeCacheEffect);
+
+/**
+ * Head tags for the root route: manifest link, Apple icon, and the meta
+ * tags for the Build ID (read by Worker RPC), build time and commit.
+ * Hydration-safe: in the browser they come from the tags the server rendered.
+ */
+export const pwaHead = (): HeadTags => headTags(info, pageVersion(info));

package/src/pwa/react/update-prompt.tsx

@@ -0,0 +1,26 @@
+import { createToastManager, Toaster } from '#components/ui/toast';
+import { type ReactNode, useState } from 'react';
+import { usePwa } from './react.js';
+import { useUpdateToast } from './update-toast.js';
+
+/**
+ * Persistent toast while an update is ready; accepting applies it.
+ * Renders its own toast viewport, so it does not need the app's `Toaster`.
+ */
+export const UpdatePrompt = (props: {
+  readonly message?: string;
+  readonly acceptLabel?: string;
+}): ReactNode => {
+  const { status, applyUpdate } = usePwa();
+  const [manager] = useState(createToastManager);
+  useUpdateToast(
+    manager,
+    status,
+    {
+      message: props.message ?? 'A new version is available.',
+      acceptLabel: props.acceptLabel ?? 'Reload',
+    },
+    applyUpdate,
+  );
+  return <Toaster toastManager={manager} />;
+};

package/src/pwa/react/update-toast.ts

@@ -0,0 +1,57 @@
+import type { createToastManager } from '#components/ui/toast';
+import { useEffect, useRef } from 'react';
+import type { PwaStatus } from '../client/index.js';
+
+type ToastManager = ReturnType<typeof createToastManager>;
+
+/**
+ * Mirrors the status into one persistent toast: shown while UpdateReady,
+ * busy while Updating, gone otherwise. Closing it hides it until the next update.
+ */
+export const useUpdateToast = (
+  manager: ToastManager,
+  status: PwaStatus,
+  labels: { readonly message: string; readonly acceptLabel: string },
+  apply: () => Promise<void>,
+): void => {
+  const id = useRef<string | null>(null);
+  const closed = useRef(false);
+  const latestApply = useRef(apply);
+  latestApply.current = apply;
+
+  useEffect(() => {
+    const tag = status._tag;
+    if (tag !== 'UpdateReady' && tag !== 'Updating') {
+      const open = id.current;
+      id.current = null;
+      closed.current = false;
+      if (open !== null) manager.close(open);
+      return;
+    }
+    if (closed.current) return;
+    const applying = tag === 'Updating';
+    const options = {
+      title: labels.message,
+      type: applying ? 'loading' : undefined,
+      timeout: 0,
+      actionProps: {
+        children: labels.acceptLabel,
+        disabled: applying,
+        onClick: () => void latestApply.current(),
+      },
+    };
+    if (id.current === null) {
+      id.current = manager.add({
+        ...options,
+        // Also fires for our own `close` above, after `id` is already cleared.
+        onClose: () => {
+          if (id.current === null) return;
+          id.current = null;
+          closed.current = true;
+        },
+      });
+    } else {
+      manager.update(id.current, options);
+    }
+  }, [manager, status._tag, labels.message, labels.acceptLabel]);
+};

package/src/pwa/root/index.ts

@@ -0,0 +1 @@
+export { pwaRoot } from './root.tsx';

package/src/pwa/root/root.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import type { RootPlugin } from '../../client/index.ts';
+import { InstallPrompt, useInstall } from '../extras/index.js';
+import { PwaProvider, pwaHead, UpdatePrompt } from '../react/index.js';
+import { splashHead } from '../splash/index.ts';
+
+/**
+ * The PWA, plugged into the root document: the manifest, icons, Build ID
+ * and iOS splash tags in every page's head; the service worker registered
+ * after mount; the Update Prompt when a new version waits; and the Install
+ * Prompt, offered once. Leave it out and the app is no PWA.
+ */
+export const pwaRoot = (
+  options: { readonly installTitle?: string } = {},
+): RootPlugin => ({
+  head: () => {
+    const pwa = pwaHead();
+    const splash = splashHead();
+    return {
+      meta: [...pwa.meta, ...splash.meta],
+      links: [...pwa.links, ...splash.links],
+    };
+  },
+  Provider: (props: { readonly children: ReactNode }) => {
+    // The browser offers install once, early, so it is caught at the root.
+    useInstall();
+    return (
+      <PwaProvider>
+        {props.children}
+        <UpdatePrompt />
+        <InstallPrompt
+          {...(options.installTitle === undefined
+            ? {}
+            : { title: options.installTitle })}
+        />
+      </PwaProvider>
+    );
+  },
+});

package/src/pwa/rpc/client/client.ts

@@ -0,0 +1,105 @@
+import type * as Context from 'effect/Context';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import type * as Scope from 'effect/Scope';
+import type * as Rpc from 'effect/rpc/Rpc';
+import * as RpcClient from 'effect/rpc/RpcClient';
+import type { RpcClientError } from 'effect/rpc/RpcClientError';
+import type * as RpcGroup from 'effect/rpc/RpcGroup';
+import * as Worker from 'effect/workers/Worker';
+import type { WorkerError } from 'effect/workers/WorkerError';
+import type { VersionSkew } from '../handshake/index.js';
+import { makeClientPlatform } from './platform.js';
+import info from 'virtual:pwa-toolkit/client';
+import {
+  controllerComing,
+  pageBuildId,
+  serviceWorkerContainer,
+} from './page-environment.js';
+import { makeSkewState, withVersionSkew } from './version-skew.js';
+
+export { VersionSkew } from '../handshake/index.js';
+
+type Client<Rpcs extends Rpc.Any> = RpcClient.RpcClient<
+  Rpcs,
+  RpcClientError | VersionSkew
+>;
+
+interface Options {
+  /**
+   * While calls are in flight, how often the Worker Client checks that the
+   * Worker Server still knows it; also how long it waits for the handshake.
+   * Default 5 seconds.
+   */
+  readonly livenessInterval?: Duration.Input;
+}
+
+const make = <Rpcs extends Rpc.Any>(
+  group: RpcGroup.RpcGroup<Rpcs>,
+  options?: Options,
+): Effect.Effect<
+  Client<Rpcs>,
+  WorkerError,
+  Scope.Scope | Rpc.MiddlewareClient<Rpcs>
+> =>
+  Effect.gen(function* () {
+    const buildId = yield* pageBuildId;
+    const container = yield* serviceWorkerContainer;
+    const livenessMs = Duration.toMillis(
+      options?.livenessInterval ?? '5 seconds',
+    );
+    yield* controllerComing({
+      enabled: info.enabled,
+      container,
+      graceMs: livenessMs,
+    });
+    const skew = makeSkewState();
+    const protocol = yield* RpcClient.makeProtocolWorker({ size: 1 }).pipe(
+      Effect.provideService(
+        Worker.WorkerPlatform,
+        makeClientPlatform({
+          buildId,
+          skew,
+          livenessMs,
+        }),
+      ),
+      Effect.provideService(Worker.Spawner, () => container),
+    );
+    const client: Client<Rpcs> = yield* RpcClient.make(group).pipe(
+      Effect.provideService(
+        RpcClient.Protocol,
+        withVersionSkew(protocol, skew),
+      ),
+    );
+    return client;
+  });
+
+/**
+ * One page's Worker RPC connection. Every message goes through the current
+ * controller, carrying the page's Build ID (from the meta tag `pwaHead()`
+ * renders). On a first visit, calls wait for the worker to take control.
+ * `make` fails at once when no worker ever will: the PWA is off in this
+ * build, or a hard reload left the page uncontrolled.
+ *
+ * - Version Skew: a worker of another Build ID refuses the connection, and
+ *   calls fail with `VersionSkew` until a new controller takes over. The app
+ *   may answer it with `usePwa().checkForUpdate`.
+ * - Worker restart: the browser may stop the worker at any time. A call made
+ *   while nothing was in flight wakes the new worker and succeeds. Calls in
+ *   flight then fail with `RpcClientError` (found at the next message, or
+ *   within the liveness interval), and the Worker Client connects again on its
+ *   own. A stream is never resumed where it stopped: Subscription Restart
+ *   means subscribing again (e.g. `Stream.retry`), and the handler starts
+ *   over from the current state, so it must emit everything a fresh
+ *   subscriber needs.
+ */
+export const WorkerClient = {
+  make,
+  layer: <Id, Rpcs extends Rpc.Any>(
+    tag: Context.Key<Id, Client<Rpcs>>,
+    group: RpcGroup.RpcGroup<Rpcs>,
+    options?: Options,
+  ): Layer.Layer<Id, WorkerError, Rpc.MiddlewareClient<Rpcs>> =>
+    Layer.effect(tag)(make(group, options)),
+};

package/src/pwa/rpc/client/index.ts

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

package/src/pwa/rpc/client/page-environment.ts

@@ -0,0 +1,88 @@
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { WorkerError, WorkerSpawnError } from 'effect/workers/WorkerError';
+import { BUILD_ID_META_NAME, BuildId } from '../../shared/build/index.js';
+
+const spawnError = (message: string) =>
+  new WorkerError({ reason: new WorkerSpawnError({ message }) });
+
+const decodeBuildId = Schema.decodeUnknownOption(BuildId);
+
+/** The page's Build ID, from the meta tag `pwaHead()` renders. */
+export const pageBuildId: Effect.Effect<BuildId, WorkerError> = Effect.suspend(
+  () => {
+    const content = globalThis.document
+      ?.querySelector<HTMLMetaElement>(`meta[name="${BUILD_ID_META_NAME}"]`)
+      ?.getAttribute('content');
+    return Option.match(decodeBuildId(content), {
+      onSome: Effect.succeed,
+      onNone: () =>
+        Effect.fail(
+          spawnError(
+            `Worker RPC needs the Build ID meta tag (${BUILD_ID_META_NAME}); render pwaHead() in the document head`,
+          ),
+        ),
+    });
+  },
+);
+
+/** `navigator.serviceWorker`, where the browser offers it. */
+export const serviceWorkerContainer: Effect.Effect<
+  ServiceWorkerContainer,
+  WorkerError
+> = Effect.suspend(() => {
+  const container = globalThis.navigator?.serviceWorker;
+  return container === undefined
+    ? Effect.fail(
+        spawnError(
+          'Worker RPC needs service workers (a secure context in a supporting browser)',
+        ),
+      )
+    : Effect.succeed(container);
+});
+
+/**
+ * Fails at once when no service worker will ever control this page, instead
+ * of letting calls wait for a controller forever:
+ * - the PWA is off in this build (the Kill Switch, or `vite dev` without
+ *   `dev: true`), so nothing registers;
+ * - an active worker exists but does not control the page after `graceMs`
+ *   (a hard reload bypasses it until the next normal load).
+ * On a first visit (nothing active yet) calls wait for the worker to take over.
+ */
+export const controllerComing = (options: {
+  readonly enabled: boolean;
+  readonly container: ServiceWorkerContainer;
+  readonly graceMs: number;
+}): Effect.Effect<void, WorkerError> =>
+  Effect.gen(function* () {
+    const { enabled, container, graceMs } = options;
+    if (!enabled) {
+      return yield* Effect.fail(
+        spawnError(
+          'Worker RPC has no service worker: the PWA is off in this build (the Kill Switch, or vite dev without dev: true)',
+        ),
+      );
+    }
+    if (container.controller !== null) return;
+    const registration = yield* Effect.tryPromise(() =>
+      container.getRegistration(),
+    ).pipe(Effect.orElseSucceed(() => undefined));
+    const active = registration?.active ?? null;
+    if (active === null || registration?.installing !== null) return;
+    const controlled = yield* Effect.callback<boolean>((resume) => {
+      const onChange = () => resume(Effect.succeed(true));
+      container.addEventListener('controllerchange', onChange);
+      return Effect.sync(() =>
+        container.removeEventListener('controllerchange', onChange),
+      );
+    }).pipe(Effect.timeoutOption(graceMs), Effect.map(Option.isSome));
+    if (!controlled && container.controller === null) {
+      return yield* Effect.fail(
+        spawnError(
+          'No service worker controls this page (a hard reload bypasses it); reload the page normally',
+        ),
+      );
+    }
+  });