@driftengine/package 3.61.0 → 3.61.2

package/ios/DriftHost/SchemeHandler.swift

@@ -0,0 +1,130 @@
+import Foundation
+import WebKit
+
+/// Serves the game out of the app bundle over a scheme that is an origin.
+///
+/// **`file://` is not an origin**, and a game loaded from one fails to import its own modules —
+/// which reads as a broken build rather than as a missing origin. A custom scheme handled here is
+/// one, and it costs no listening socket inside a game.
+///
+/// **The host is `localhost`, and that is the whole of why this is a secure context.**
+///
+/// A custom scheme is *not* trustworthy to WebKit on its own. What rescues this one is the host:
+/// W3C's "is origin potentially trustworthy" decides on the **host** before it considers any
+/// scheme beyond https — step 4 returns trustworthy for a host in `127.0.0.0/8` or `::1/128`, and
+/// step 5 for a host of `localhost`, and **neither step mentions the scheme**. So
+/// `drift://localhost/…` is a secure context and `drift://app/…` is not, and the two differ by six
+/// characters.
+///
+/// **Do not confuse this with the other well-known custom-scheme problem, which is real and is not
+/// this one.** An `https://` page cannot fetch a subresource from a custom scheme — WebKit blocks
+/// it as mixed content — and the workaround written up for that is `_registerURLSchemeAsSecure:`,
+/// a private selector on `WKProcessPool` that risks a review rejection. That is a question about a
+/// custom scheme used as a *subresource origin underneath an https document*. This is a question
+/// about the *document's own* origin, and the answers are different. Nothing private is used here,
+/// and nothing needs to be.
+///
+/// This is what Capacitor has shipped on iOS for years — `capacitor://localhost`, with their own
+/// documentation recommending the hostname stay `localhost` precisely because it "allows the use of
+/// Web APIs that would otherwise require a secure context". Millions of installed applications are
+/// the evidence; no device here was needed to read it.
+///
+/// **So there is no loopback server**, which was the alternative this was going to cost: a
+/// listening socket inside a game, a port that can be taken, and a permission prompt on some
+/// platforms.
+///
+/// **The containment check is not optional.** A scheme handler that resolves a path and serves it
+/// is a filesystem the page can walk, so every request is resolved and then checked to be inside
+/// the bundle root — the same rule the desktop shell's `resolveWithinRoot` enforces.
+final class SchemeHandler: NSObject, WKURLSchemeHandler {
+    static let scheme = "drift"
+
+    /// The reserved prefix the packager's own assets are served under.
+    ///
+    /// One host rather than two, unlike the desktop shell's `app` and `shell`: a second host would
+    /// not be `localhost`, and would therefore not be a secure context. A path prefix costs
+    /// nothing and keeps the whole application on the one origin that is trustworthy.
+    static let shellPrefix = "/__drift/"
+
+    private let root: URL
+    private let shell: URL
+
+    init(root: URL, shell: URL) {
+        self.root = root.standardizedFileURL
+        self.shell = shell.standardizedFileURL
+    }
+
+    func webView(_ webView: WKWebView, start task: WKURLSchemeTask) {
+        guard let url = task.request.url else {
+            task.didFailWithError(URLError(.badURL))
+            return
+        }
+
+        let path = url.path.isEmpty || url.path == "/" ? "/index.html" : url.path
+        let shellAsset = path.hasPrefix(Self.shellPrefix)
+        let base = shellAsset ? shell : root
+        let relative = shellAsset ? String(path.dropFirst(Self.shellPrefix.count - 1)) : path
+        let resolved = base.appendingPathComponent(relative).standardizedFileURL
+
+        // A prefix check on the string alone accepts a sibling directory whose name starts with
+        // the root's; the separator is what makes this a directory check.
+        guard resolved.path == base.path || resolved.path.hasPrefix(base.path + "/") else {
+            task.didFailWithError(URLError(.noPermissionsToReadFile))
+            return
+        }
+
+        guard let data = try? Data(contentsOf: resolved) else {
+            task.didFailWithError(URLError(.fileDoesNotExist))
+            return
+        }
+
+        let response = HTTPURLResponse(
+            url: url,
+            statusCode: 200,
+            httpVersion: "HTTP/1.1",
+            headerFields: [
+                "Content-Type": Self.contentType(for: resolved.pathExtension.lowercased()),
+                "Content-Length": String(data.count),
+                // The same policy the desktop shell serves: everything a game does is allowed and
+                // a script from somewhere else is not.
+                "Content-Security-Policy":
+                    "default-src 'self' drift: blob: data:; "
+                    + "script-src 'self' drift: blob: 'unsafe-inline' 'wasm-unsafe-eval'; "
+                    + "style-src 'self' drift: 'unsafe-inline'; "
+                    + "img-src 'self' drift: blob: data: https:; "
+                    + "media-src 'self' drift: blob: data: https:; "
+                    + "connect-src 'self' drift: blob: data: https: wss:",
+            ]
+        )!
+
+        task.didReceive(response)
+        task.didReceive(data)
+        task.didFinish()
+    }
+
+    func webView(_ webView: WKWebView, stop task: WKURLSchemeTask) {
+        // Nothing is held between start and finish, so there is nothing to cancel.
+    }
+
+    /// **A wrong type is a silent load failure**, not a wrong picture: a module served as anything
+    /// but JavaScript is refused by the loader, and an SVG served as bytes renders as a broken
+    /// image — which is exactly how the desktop shell's splash failed once.
+    static func contentType(for ext: String) -> String {
+        switch ext {
+        case "html": return "text/html; charset=utf-8"
+        case "js", "mjs": return "text/javascript; charset=utf-8"
+        case "css": return "text/css; charset=utf-8"
+        case "json": return "application/json; charset=utf-8"
+        case "wasm": return "application/wasm"
+        case "svg": return "image/svg+xml"
+        case "png": return "image/png"
+        case "jpg", "jpeg": return "image/jpeg"
+        case "webp": return "image/webp"
+        case "ktx2": return "image/ktx2"
+        case "ogg": return "audio/ogg"
+        case "mp3": return "audio/mpeg"
+        case "wav": return "audio/wav"
+        default: return "application/octet-stream"
+        }
+    }
+}

package/ios/DriftHost/ViewController.swift

@@ -0,0 +1,126 @@
+import UIKit
+import WebKit
+
+/// One view controller, one `WKWebView`, and nothing else.
+///
+/// **The renderer here is WebKit and there is no choice about that.** Apple requires it for
+/// anything that browses the web, so a bundled Chromium is not an option on this platform — which
+/// is also why the engine's WebGL2 baseline matters: what the device offers is what the game gets,
+/// and the acceptance probe decides whether WebGPU is among it.
+///
+/// **The bridge is injected at document start**, before the game's own scripts, the same timing
+/// the desktop preload and Android's document-start script have. Everything readable synchronously
+/// goes in as a literal; see `HostBridge` for why that is not a shortcut but the only shape this
+/// platform allows.
+final class ViewController: UIViewController, WKNavigationDelegate, WKUIDelegate {
+    private var web: WKWebView!
+    private var bridge: HostBridge!
+
+    override var prefersStatusBarHidden: Bool { true }
+    override var prefersHomeIndicatorAutoHidden: Bool { true }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        guard let root = Bundle.main.url(forResource: "www", withExtension: nil) else {
+            assertionFailure("the game was not copied into the bundle; see ios.ts")
+            return
+        }
+        let shell = Bundle.main.url(forResource: "shell", withExtension: nil) ?? root
+
+        bridge = HostBridge(controller: self)
+
+        let configuration = WKWebViewConfiguration()
+        configuration.setURLSchemeHandler(
+            SchemeHandler(root: root, shell: shell), forURLScheme: SchemeHandler.scheme)
+        // A game's own audio is not an autoplaying advert, and the engine's mixer starts on the
+        // first input anyway — so the gesture requirement only ever delays the first sound.
+        configuration.allowsInlineMediaPlayback = true
+        configuration.mediaTypesRequiringUserActionForPlayback = []
+
+        let content = configuration.userContentController
+        content.addScriptMessageHandler(bridge, contentWorld: .page, name: HostBridge.name)
+        content.addUserScript(WKUserScript(
+            source: "globalThis.__driftHostState = \(bridge.stateJson());",
+            injectionTime: .atDocumentStart,
+            forMainFrameOnly: true
+        ))
+        if let shim = Bundle.main.url(forResource: "drift-shim", withExtension: "js"),
+           let source = try? String(contentsOf: shim, encoding: .utf8) {
+            content.addUserScript(WKUserScript(
+                source: source, injectionTime: .atDocumentStart, forMainFrameOnly: true))
+        } else {
+            // Loud rather than silent: the game runs and believes it is in a plain browser, which
+            // is a defined state and a surprising one to debug from the outside.
+            NSLog("[drift] the bridge shim is missing from the bundle; the game has no host")
+        }
+
+        web = WKWebView(frame: view.bounds, configuration: configuration)
+        web.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        web.navigationDelegate = self
+        web.uiDelegate = self
+        // A game is not a document: rubber-banding at its edges reads as the whole screen coming
+        // loose, and the scroll view is the only thing that does it.
+        web.scrollView.bounces = false
+        web.scrollView.isScrollEnabled = false
+        web.isOpaque = false
+        web.backgroundColor = .black
+        view.backgroundColor = .black
+        view.addSubview(web)
+
+        /*
+         * **`localhost`, not `app`.** The host is what makes this a secure context — see the note
+         * in `SchemeHandler` — and the difference between the two is `crossOriginIsolated`,
+         * `SharedArrayBuffer`, the wake lock, and everything else gated on one.
+         */
+        web.load(URLRequest(url: URL(string: "\(SchemeHandler.scheme)://localhost/index.html")!))
+    }
+
+    override func viewWillTransition(to size: CGSize, with coordinator: UIViewControllerTransitionCoordinator) {
+        super.viewWillTransition(to: size, with: coordinator)
+        // A rotation changes what the injected state says, and a bridge reading a stale object
+        // would report the previous orientation for the rest of the session.
+        coordinator.animate(alongsideTransition: nil) { [weak self] _ in
+            guard let self else { return }
+            self.web.evaluateJavaScript(
+                "Object.assign(globalThis.__driftHostState ?? {}, \(self.bridge.stateJson()))")
+        }
+    }
+
+    /// A link to the outside opens in Safari, never inside the game.
+    ///
+    /// The same rule the desktop shell follows: their browser has their session, their bookmarks
+    /// and a way back, and an in-app view is a browser nobody is maintaining. Only `http`, `https`
+    /// and `mailto` leave at all.
+    func webView(
+        _ webView: WKWebView,
+        decidePolicyFor action: WKNavigationAction,
+        decisionHandler: @escaping (WKNavigationActionPolicy) -> Void
+    ) {
+        guard let url = action.request.url else {
+            decisionHandler(.cancel)
+            return
+        }
+        if url.scheme == SchemeHandler.scheme {
+            decisionHandler(.allow)
+            return
+        }
+        if ["http", "https", "mailto"].contains(url.scheme ?? "") {
+            UIApplication.shared.open(url)
+        }
+        decisionHandler(.cancel)
+    }
+
+    /// `target="_blank"` arrives here rather than as a navigation, and goes the same way out.
+    func webView(
+        _ webView: WKWebView,
+        createWebViewWith configuration: WKWebViewConfiguration,
+        for action: WKNavigationAction,
+        windowFeatures: WKWindowFeatures
+    ) -> WKWebView? {
+        if let url = action.request.url, ["http", "https", "mailto"].contains(url.scheme ?? "") {
+            UIApplication.shared.open(url)
+        }
+        return nil
+    }
+}

package/ios/project.yml

@@ -0,0 +1,57 @@
+# The Xcode project, described rather than committed.
+#
+# The `__DRIFT_*__` placeholders are substituted by `src/ios.ts` when it stages a copy — plain text
+# replacement rather than Xcode build settings, so what XcodeGen reads is a finished spec and there
+# is one place a wrong value could come from.
+#
+# A `.xcodeproj` is a generated artefact with absolute paths and a merge conflict in every pull
+# request; XcodeGen turns this file into one at build time, and `drift-package bootstrap
+# --target=ios` fetches XcodeGen itself. Every value the packager substitutes is a placeholder
+# here, and the defaults are visibly placeholders rather than plausible.
+name: DriftHost
+options:
+  bundleIdPrefix: dev.driftengine
+  deploymentTarget:
+    # 15 is where WKWebView's modern JavaScript and WebGL2 are dependable. WebGPU arrives at 26
+    # and the engine's acceptance probe decides whether it is usable, per target.
+    iOS: '15.0'
+  createIntermediateGroups: true
+
+settings:
+  base:
+    PRODUCT_NAME: __DRIFT_APP_NAME__
+    MARKETING_VERSION: __DRIFT_VERSION_NAME__
+    CURRENT_PROJECT_VERSION: __DRIFT_VERSION_CODE__
+    # Signing is decided by the build, not by this file: an unsigned archive is what a sideload
+    # tool re-signs, and a team id turns automatic signing back on.
+    CODE_SIGN_STYLE: Automatic
+    DEVELOPMENT_TEAM: __DRIFT_TEAM_ID__
+    TARGETED_DEVICE_FAMILY: '1,2'
+
+targets:
+  DriftHost:
+    type: application
+    platform: iOS
+    sources:
+      - path: DriftHost
+      # Written into the staging copy by the packager: the game, and the bridge shim beside it.
+      - path: www
+        type: folder
+        optional: true
+      - path: drift-shim.js
+        optional: true
+    info:
+      path: DriftHost/Info.plist
+      properties:
+        CFBundleDisplayName: __DRIFT_APP_NAME__
+        CFBundleIdentifier: __DRIFT_APP_ID__
+        UILaunchScreen: {}
+        # A game is landscape or portrait as it likes; the host locks nothing, and
+        # `ScreenPresentation.lockOrientation` reports iOS's refusal rather than hiding it.
+        UISupportedInterfaceOrientations:
+          - UIInterfaceOrientationPortrait
+          - UIInterfaceOrientationLandscapeLeft
+          - UIInterfaceOrientationLandscapeRight
+        UIRequiresFullScreen: true
+        UIStatusBarHidden: true
+        UIViewControllerBasedStatusBarAppearance: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/package",
-  "version": "3.61.0",
+  "version": "3.61.2",
   "description": "Builds an installable application from a game built on the engine",
   "license": "Apache-2.0",
   "type": "module",
@@ -21,6 +21,11 @@
     "!src/**/*.test.ts",
     "!src/**/*.test.mjs",
     "!src/**/__snapshots__",
+    "bin",
+    "android",
+    "ios",
+    "assets",
+    "scripts",
     "README.md",
     "LICENSE",
     "NOTICE"
@@ -30,7 +35,7 @@
     "drift-package": "bin/drift-package.mjs"
   },
   "peerDependencies": {
-    "@driftengine/core": "3.61.0",
+    "@driftengine/core": "3.61.2",
     "steamworks.js": ">=0.4.0"
   },
   "dependencies": {

package/scripts/build-macos.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# Build the macOS artifacts on a Mac.
+#
+# **This is not the only route any more.** A Mac target cross-builds from Linux, where the packager
+# ad-hoc signs it with rcodesign and archives it with `zip -y`. What that route cannot produce is a
+# .dmg — hdiutil is macOS only — so this script is what makes one, and what signs with a real
+# Developer ID. `drift-package doctor` prints which of the two a machine is on.
+#
+# The signing mode is decided by `planSigning` from the environment and printed by the build. With
+# no certificate this is an **ad-hoc** signature, which is the minimum that runs: Apple Silicon's
+# loader refuses an unsigned binary outright. A .dmg built that way still carries the quarantine
+# flag when downloaded, and the first launch is refused until `xattr -dr com.apple.quarantine`
+# clears it — which is the reason to buy a Developer ID eventually, and not a reason to wait.
+#
+#   ./build-macos.sh --project ~/work/game
+#   CSC_LINK=~/certs/developer-id.p12 CSC_KEY_PASSWORD=... ./build-macos.sh --project .
+#   APPLE_ID=... APPLE_APP_SPECIFIC_PASSWORD=... APPLE_TEAM_ID=... ./build-macos.sh --project .
+
+set -euo pipefail
+
+PROJECT=""
+TARGET="mac-arm64"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project) PROJECT="$2"; shift 2 ;;
+    --target)  TARGET="$2";  shift 2 ;;
+    -h|--help) sed -n '2,16p' "$0"; exit 0 ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$PROJECT" ] || { echo "--project is required" >&2; exit 2; }
+[ -f "$PROJECT/drift.package.json" ] || {
+  echo "no drift.package.json in $PROJECT; that file is what a build is configured from" >&2
+  exit 1
+}
+
+command -v node >/dev/null || { echo "node is not on PATH" >&2; exit 1; }
+command -v codesign >/dev/null || {
+  echo "codesign is missing: install the Xcode command line tools with xcode-select --install" >&2
+  exit 1
+}
+
+# See the note in build-windows.ps1: an Electron-based terminal exports this, and it turns the
+# artifact into one that cannot find Electron.
+unset ELECTRON_RUN_AS_NODE
+
+cd "$PROJECT"
+npm ci
+npx drift-package doctor
+npx drift-package build --target="$TARGET"
+
+echo
+echo "Artifacts:"
+find "out/$TARGET" -maxdepth 1 -type f -print
+
+# Said again at the end, because the interesting line scrolled past twenty minutes ago.
+if [ -z "${CSC_LINK:-}${CSC_NAME:-}" ]; then
+  cat <<'EOF'
+
+This build is ad-hoc signed. It runs here. A copy downloaded through a browser will be refused by
+Gatekeeper until the person clears the quarantine flag:
+
+    xattr -dr com.apple.quarantine "/Applications/<the app>.app"
+
+A Developer ID certificate in CSC_LINK removes that, and notarisation credentials remove it for
+everybody rather than for the people willing to run a command.
+EOF
+fi