@driftengine/core 3.61.0

package/src/host/lifecycle.ts

@@ -0,0 +1,63 @@
+/**
+ * Focus, and the end of the process.
+ *
+ * The engine needs to know when it stopped being looked at — a paused simulation, a muted mixer —
+ * and a shell additionally needs to be told to close. **A browser cannot close its own tab**, so
+ * `requestQuit` warns rather than silently doing nothing: a silent no-op reads as a working call,
+ * which is the failure `AGENTS.md` names where an unimplemented capability returns a plausible
+ * answer instead of a defined one.
+ *
+ * Every subscription returns its own unsubscribe. Nothing here is called per frame.
+ */
+export interface Lifecycle {
+  /**
+   * Whether `requestQuit` will actually end the process.
+   *
+   * **This is what an exit button should be drawn from.** A browser cannot close its own tab and
+   * iOS applications do not exit programmatically, so a menu that always shows Exit has a button
+   * that does nothing on two of the platforms a game ships to — and a game that instead branches
+   * on "am I in a shell" has hard-coded an assumption that stops being true. Ask the capability.
+   */
+  readonly canQuit: boolean;
+  onFocusChange(handler: (focused: boolean) => void): () => void;
+  /**
+   * The shell is closing and the game may finish what it is doing.
+   *
+   * A shell calls the handler on a window-close request and waits; a browser never calls it,
+   * because a tab closing gives nothing that can be waited on.
+   */
+  onQuitRequest(handler: () => void): () => void;
+  requestQuit(): void;
+}
+
+export class BrowserLifecycle implements Lifecycle {
+  /** False: no page may close the tab it is in. An exit button here is a button that lies. */
+  readonly canQuit = false;
+
+  onFocusChange(handler: (focused: boolean) => void): () => void {
+    const focused = (): void => handler(true);
+    const blurred = (): void => handler(false);
+    window.addEventListener('focus', focused);
+    window.addEventListener('blur', blurred);
+    return () => {
+      window.removeEventListener('focus', focused);
+      window.removeEventListener('blur', blurred);
+    };
+  }
+
+  /**
+   * A browser is never asked to quit, so this handler is never called here.
+   *
+   * The unsubscribe is real rather than the handler being rejected: a consumer registers the
+   * same handler on both platforms and must be able to drop it on both, and code that has to
+   * ask which platform it is on has lost the point of the seam.
+   */
+  onQuitRequest(handler: () => void): () => void {
+    void handler;
+    return () => undefined;
+  }
+
+  requestQuit(): void {
+    console.warn('[driftengine] requestQuit: a browser cannot close its own tab; a shell can');
+  }
+}

package/src/host/platformServices.ts

@@ -0,0 +1,23 @@
+/**
+ * A store's own features: achievements, presence, and whatever a platform adds to them.
+ *
+ * **Opt-in, and there is deliberately no default implementation.** A consumer that never asks for
+ * an achievement must not acquire a store SDK, must not ship one to a browser, and must not have
+ * to explain one in a privacy policy. That is the same promise SDF text makes, and it is the
+ * reason this interface has no `BrowserPlatformServices` beside it: there is nothing honest for
+ * one to do.
+ *
+ * A consumer that wants these supplies them from its shell. A consumer that does not passes
+ * nothing and the engine never calls them.
+ *
+ * **Both methods return nothing and neither may throw.** An achievement that fails to unlock is
+ * not a reason for a frame to stop, and a store that is offline is an ordinary state — an
+ * implementation that wants to report a failure logs it.
+ *
+ * **What would make this wrong** is a platform feature the engine itself needs in order to draw,
+ * which none of these is.
+ */
+export interface PlatformServices {
+  unlockAchievement(id: string): void;
+  setRichPresence(text: string): void;
+}

package/src/host/screen.ts

@@ -0,0 +1,134 @@
+/**
+ * What a phone has instead of a window.
+ *
+ * A handset has no window mode, no window size a game may choose and no second display, so
+ * `DisplayControl` has almost nothing to offer it. What it has instead is an **orientation** it
+ * may rotate out of, a **safe area** that a notch, a camera cut-out or a gesture bar has taken
+ * from the screen, and a **screen that wants to sleep** while somebody is holding a controller
+ * rather than touching the glass. Those are the three, and they are here rather than folded into
+ * the display seam because a desktop shell has no use for any of them.
+ *
+ * **Every one of them can be refused, and each says so.** iOS will not lock an orientation at
+ * all; Android will not lock one outside fullscreen; a browser with no Wake Lock API cannot keep
+ * a screen awake. A game that is told `false` can lay itself out for either orientation, or warn,
+ * or carry on — what it cannot do is find out later from a player.
+ *
+ * Not a hot path: a layout reads the safe area on a resize, not on a frame.
+ */
+export type ScreenOrientation = 'portrait' | 'landscape';
+
+/** Logical pixels the platform has taken from each edge. Zero where it has taken nothing. */
+export interface SafeAreaInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+
+export interface ScreenPresentation {
+  orientation(): ScreenOrientation;
+  /** `null` unlocks. `false` where the platform refused, which iOS always does. */
+  lockOrientation(orientation: ScreenOrientation | null): Promise<boolean>;
+  safeArea(): SafeAreaInsets;
+  /** `false` where the platform has no wake lock, or refused this one. */
+  keepAwake(on: boolean): Promise<boolean>;
+}
+
+/** The four properties the style below defines, read back through the cascade. */
+const INSET_PROPERTIES = ['top', 'right', 'bottom', 'left'] as const;
+
+/** Marks the one style element this installs, so a second instance does not add another. */
+const STYLE_ID = 'drift-safe-area';
+
+interface WakeLockSentinel {
+  release(): Promise<void>;
+}
+
+export class BrowserScreenPresentation implements ScreenPresentation {
+  private held: WakeLockSentinel | null = null;
+
+  /**
+   * Installs one stylesheet, once, and that is the only side effect in this file.
+   *
+   * `env(safe-area-inset-*)` cannot be read from script directly — it is only valid inside a CSS
+   * declaration — so the values are copied into custom properties on the root element and read
+   * back through `getComputedStyle`. The alternative is a hidden probe element whose padding is
+   * measured, which costs a layout on every read and a node in every consumer's tree.
+   */
+  constructor() {
+    try {
+      if (document.getElementById?.(STYLE_ID) != null) return;
+      const style = document.createElement('style');
+      style.setAttribute('id', STYLE_ID);
+      style.textContent = `:root{${INSET_PROPERTIES.map(
+        (edge) => `--drift-safe-${edge}:env(safe-area-inset-${edge},0px)`,
+      ).join(';')}}`;
+      document.head.appendChild(style);
+    } catch {
+      /* No document, or a head that will not take a child. The insets then read zero, which is
+         the same answer a platform with no cut-out gives, and is never worth failing a boot for. */
+    }
+  }
+
+  orientation(): ScreenOrientation {
+    const type = window.screen?.orientation?.type;
+    if (typeof type === 'string') return type.startsWith('portrait') ? 'portrait' : 'landscape';
+    /* No orientation API: every desktop browser, and iOS Safari for most of its life. The shape
+       of the window is the same answer the platform would have given. */
+    return window.innerHeight >= window.innerWidth ? 'portrait' : 'landscape';
+  }
+
+  async lockOrientation(orientation: ScreenOrientation | null): Promise<boolean> {
+    const screen = window.screen?.orientation as
+      { lock?: (o: string) => Promise<void>; unlock?: () => void } | undefined;
+    if (screen === undefined) return false;
+    try {
+      if (orientation === null) {
+        screen.unlock?.();
+        return true;
+      }
+      if (typeof screen.lock !== 'function') return false;
+      await screen.lock(orientation);
+      return true;
+    } catch {
+      /* iOS refuses outright; Android refuses outside fullscreen. Both are ordinary. */
+      return false;
+    }
+  }
+
+  safeArea(): SafeAreaInsets {
+    const read = (edge: (typeof INSET_PROPERTIES)[number]): number => {
+      try {
+        const raw = getComputedStyle(document.documentElement).getPropertyValue(
+          `--drift-safe-${edge}`,
+        );
+        const value = Number.parseFloat(raw);
+        return Number.isFinite(value) ? value : 0;
+      } catch {
+        return 0;
+      }
+    };
+    return { top: read('top'), right: read('right'), bottom: read('bottom'), left: read('left') };
+  }
+
+  async keepAwake(on: boolean): Promise<boolean> {
+    const wakeLock = (
+      navigator as { wakeLock?: { request(kind: string): Promise<WakeLockSentinel> } }
+    ).wakeLock;
+    try {
+      if (!on) {
+        if (this.held === null) return true;
+        await this.held.release();
+        this.held = null;
+        return true;
+      }
+      if (wakeLock === undefined) return false;
+      this.held = await wakeLock.request('screen');
+      return true;
+    } catch {
+      /* A lock is dropped whenever the page is hidden, and re-requesting it is the caller's
+         business. A failure here is not worth a throw. */
+      return false;
+    }
+  }
+}