@caperjs/core 0.2.1 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caperjs/core",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "title": "Caper",
   "description": "An opinionated HTML game framework built on PixiJS v8",
   "bin": {

package/src/core/Application.ts

@@ -1,6 +1,7 @@
 import { gsap } from 'gsap';
 import type {
   AppConfig,
+  CaperPWA,
   IApplication,
   IApplicationOptions,
   ICaperAutomation,
@@ -166,6 +167,24 @@ export class Application extends PIXIPApplication implements IApplication {
   public onPluginError = new Signal<
     (detail: { id: string; phase: 'initialize' | 'postInitialize'; error: unknown }) => void
   >();
+  /**
+   * Emitted when the browser offers its PWA install prompt, so a game can show its
+   * own in-pixi install UI.
+   *
+   * The browser usually fires this before the first scene exists, and signals do not
+   * replay — so UI that offers an install button must ALSO check `app.pwa?.canInstall`
+   * when it mounts. And `app.pwa.promptInstall()` only works from inside a user
+   * gesture, i.e. a button's click/tap handler, never a timer or a game event.
+   */
+  public onPwaInstallAvailable = new Signal<() => void>();
+  /**
+   * Emitted when a new build is waiting to take over. Call `app.pwa.applyUpdate()`
+   * to activate it — the page reloads once the new worker takes control.
+   *
+   * Use `pwa: { update: 'manual' }` in the vite preset to suppress caper's default
+   * DOM banner and present this in-game instead.
+   */
+  public onPwaUpdateAvailable = new Signal<() => void>();
   // plugins
   public readonly _plugins: Map<string, IPlugin> = new Map();
   // default plugins
@@ -201,6 +220,14 @@ export class Application extends PIXIPApplication implements IApplication {
     return this._env;
   }
 
+  /**
+   * The `Caper.pwa` facade, or undefined when the app was built without the vite
+   * preset's `pwa` option. See {@link CaperPWA} for the install/update timing rules.
+   */
+  get pwa(): CaperPWA | undefined {
+    return (globalThis as any).Caper?.pwa;
+  }
+
   get debugContainer(): PIXIContainer {
     if (!this._debugContainer) {
       this._debugContainer = new PIXIContainer();
@@ -749,6 +776,8 @@ export class Application extends PIXIPApplication implements IApplication {
       }
     }
 
+    this._connectPwaSignals();
+
     this.webEvents.onVisibilityChanged.connect((visible) => {
       if (visible) {
         this.audio.restore();
@@ -764,6 +793,28 @@ export class Application extends PIXIPApplication implements IApplication {
     await this.postInitialize();
   }
 
+  /**
+   * Republishes the `Caper.pwa` callbacks as app signals. The existing handlers are
+   * wrapped rather than replaced — clobbering them would cost `update: 'prompt'` its
+   * default banner, and an app that assigned an early handler its handler.
+   */
+  private _connectPwaSignals(): void {
+    const pwa = this.pwa;
+    if (!pwa) return;
+
+    const onCanInstall = pwa.onCanInstall;
+    pwa.onCanInstall = () => {
+      onCanInstall?.();
+      this.onPwaInstallAvailable.emit();
+    };
+
+    const onNeedRefresh = pwa.onNeedRefresh;
+    pwa.onNeedRefresh = () => {
+      onNeedRefresh?.();
+      this.onPwaUpdateAvailable.emit();
+    };
+  }
+
   /**
    * User-overridable post-initialization hook, invoked after all framework wiring is
    * complete. Override to perform app setup that depends on a fully initialized

package/src/core/create.ts

@@ -11,13 +11,42 @@ import { AppConfig } from './types';
 
 type App = AppTypeOverrides['App'];
 
-interface CaperPWA {
+/**
+ * The `Caper.pwa` facade installed by the vite preset's runtime snippet. Reachable
+ * from game code as `app.pwa`, which is `undefined` when the app was built without
+ * the `pwa` option.
+ *
+ * Two timing rules matter:
+ *
+ * - `beforeinstallprompt` often fires before any scene exists, and signals do not
+ *   replay. UI that offers an install button must check `app.pwa?.canInstall` when
+ *   it mounts AND connect to `app.onPwaInstallAvailable` for the later case.
+ * - Browsers only honour {@link CaperPWA.promptInstall} from inside a user gesture.
+ *   Call it from a click/tap handler — an overlay with an Install button. Calling it
+ *   from a timer, a scene transition, or a game-over event is silently ignored.
+ */
+export interface CaperPWA {
   readonly info: any;
   register: () => void;
   onRegisteredSW: (swScriptUrl: string) => void;
   offlineReady: () => void;
+  /** Called when a new build is waiting. Defaults to caper's update banner; assign to replace it. */
   onNeedRefresh?: () => void;
   onRegisterError?: (error: any) => void;
+
+  /** True once a new build is waiting to take over. */
+  updateAvailable: boolean;
+  /** Activate the waiting worker; the page reloads once it takes control. */
+  applyUpdate: () => void;
+
+  /** True once the browser has offered an install prompt to stash. */
+  canInstall: boolean;
+  /** Called when the browser offers the install prompt. */
+  onCanInstall?: () => void;
+  /** Called after the app is installed. */
+  onInstalled?: () => void;
+  /** Show the stashed install prompt. Resolves null when there is nothing to show. */
+  promptInstall: () => Promise<'accepted' | 'dismissed' | null>;
 }
 interface CaperGlobal {
   APP_NAME: string;

package/src/core/index.ts

@@ -1,5 +1,5 @@
 export * from './config';
-export { create, createContainer } from './create';
+export { create, createContainer, type CaperPWA } from './create';
 export * from './globals';
 export * from './interfaces';
 export * from './registries';

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated during the build process.
-export const version: string = '0.2.1';
+export const version: string = '0.2.2';
 export const pixiVersion: string = '8.19.0';