@thunderclap-engine/host-capacitor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mandalorian007 / ThunderClap Gaming
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @thunderclap-engine/host-capacitor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The ThunderClap mobile host. A game's web build runs unchanged inside a Capacitor WebView on
+iOS or Android, and `createCapacitorHost()` fills the engine's `Host` interface
+(`@thunderclap-engine/engine/host`, D-041) from the Capacitor plugins the app installs. The package
+contains no game nouns, the engine never imports it, and it reaches the engine only through the
+engine's exports map (`pnpm check:boundaries`).
+
+It also never imports a `@capacitor/*` package. The plugins are the app's own: it installs the
+ones it wants and hands them in through `plugins`. `src/plugins.ts` types the slices this host
+calls by hand, so the package typechecks and tests here without Capacitor in the store (the repo
+installs offline), and the real plugin objects satisfy those types structurally.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `src/index.ts` | What a game imports: `createCapacitorHost`, `CapacitorHost`, `CapacitorHostOptions`, `HostBack`, the three facet factories, the plugin types |
+| `src/capacitor.ts` | `createCapacitorHost()` and `createAppLifecycle`, `createCapacitorHaptics`, `createPreferencesStorage` |
+| `src/plugins.ts` | `CapacitorPlugins` and the per-plugin types (`AppPlugin`, `BrowserPlugin`, `ClipboardPlugin`, `HapticsPlugin`, `PreferencesPlugin`, `ScreenOrientationPlugin`, `PluginListenerHandle`, `ListenerResult`, `AppState`, `BackButtonEvent`, `ImpactStyle`, `NotificationType`, `OrientationLockType`) |
+| `src/capacitor.test.ts` | Unit tests against fake plugins (Node, happy-dom) |
+
+## Using it from a game
+
+```ts
+import { Capacitor } from '@capacitor/core';
+import { App } from '@capacitor/app';
+import { Browser } from '@capacitor/browser';
+import { Clipboard } from '@capacitor/clipboard';
+import { Haptics } from '@capacitor/haptics';
+import { Preferences } from '@capacitor/preferences';
+import { ScreenOrientation } from '@capacitor/screen-orientation';
+import { createWebHost, setDefaultHost } from '@thunderclap-engine/engine/host';
+import { createCapacitorHost } from '@thunderclap-engine/host-capacitor';
+
+const host = Capacitor.isNativePlatform()
+  ? createCapacitorHost({ plugins: { App, Browser, Clipboard, Haptics, Preferences, ScreenOrientation } })
+  : createWebHost();
+setDefaultHost(host);
+if ('ready' in host) await host.ready; // Preferences read into the mirror; saves can open
+const ctx = await createGame({ root, title, host, save: (host) => createSaveStore({ ..., host }) });
+```
+
+Pass only the plugins the app installed; each missing one falls back to the `base` host (a web
+host over the WebView's window by default) or to a no-op.
+
+| `Host` member | With the plugin | Without it |
+|---|---|---|
+| `kind` | `'capacitor'` | |
+| `requestFrame` / `cancelFrame`, `embed` | the WebView's `requestAnimationFrame`, via `base` | |
+| `openExternal(url)` | `Browser.open` (an in-app sheet; every activation opens, `invalid` for a bad URL) | `base.openExternal` (`window.open`) |
+| `copyText(text)` | `Clipboard.write` → `'copied'`, `'manual'` on a rejection | `base.copyText` |
+| `clipboardWriteAllowed()` | `true` | `base`'s answer |
+| `fullscreen` | `available()` and the `active` getter false, `toggle()` resolves false; `toggle({ lockLandscape: true })` calls `ScreenOrientation.lock({ orientation: 'landscape' })` | the same, without the lock |
+| `storage` | `kind: 'preferences'`: a synchronous `StorageLike` over an in-memory mirror of `Preferences` (keys prefixed `tc:`), reads from the mirror, writes through in order; `open()` is null until `await host.ready` | `base.storage` (the WebView's `localStorage`) |
+| `lifecycle` | `App` `appStateChange` / `pause` / `resume`; starts `active`, corrected from `App.getState()` | `base.lifecycle` (document visibility) |
+| `haptics` | `Haptics.impact` (`LIGHT` / `MEDIUM` / `HEAVY`), `Haptics.notification`, `Haptics.vibrate`; `available()` true | `base.haptics` (`navigator.vibrate`) |
+| `safeArea` | `base.safeArea`: `env(safe-area-inset-*)` from the WebView (needs `viewport-fit=cover` in the page's viewport meta) | |
+| `window` | absent | |
+| `back` (this host only) | `{ watch(fn: (e: { canGoBack }) => void): () => void }` over `App` `backButton` | absent |
+| `ready` (this host only) | resolves when the Preferences mirror is loaded | resolves at once |
+
+Why Preferences for saves: a WebView's `localStorage` can be evicted by the OS under storage
+pressure and is not restored from a device backup; Preferences (`UserDefaults` / `SharedPreferences`)
+survive both. The mirror keeps `StorageLike` synchronous, as the save store expects; a write that
+the plugin rejects stays in the mirror and the next write still goes through.
+
+## Wrapping a game: ten lines of config
+
+```ts
+// capacitor.config.ts
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.mygame',
+  appName: 'My Game',
+  webDir: 'dist', // the game's web build (vite build)
+  server: { androidScheme: 'https' },
+  ios: { contentInset: 'never' }, // the page reaches under the notch; the host's safeArea pads the UI
+  android: { allowMixedContent: false },
+  plugins: { SplashScreen: { launchAutoHide: true } },
+};
+export default config;
+```
+
+```sh
+pnpm add @capacitor/core @capacitor/cli
+pnpm add @capacitor/app @capacitor/browser @capacitor/clipboard @capacitor/haptics @capacitor/preferences @capacitor/screen-orientation
+npx cap init                 # writes the config above if you do not already have one
+pnpm build                   # the game's web build into webDir
+npx cap add ios              # or: npx cap add android
+npx cap sync                 # copies webDir and the plugins into the native project
+npx cap open ios             # Xcode / Android Studio: run on a device
+```
+
+After each web build: `pnpm build && npx cap sync`. Keep `<meta name="viewport" content="...,
+viewport-fit=cover">` on the page so `env(safe-area-inset-*)` reports the notch; the engine's
+layout then pads its regions through `host.safeArea`.
+
+## The Android back button
+
+Registering any `backButton` listener turns off Capacitor's default (which leaves the app), so
+decide once, in the game, what back means:
+
+```ts
+host.back?.watch(({ canGoBack }) => {
+  if (ctx.stack.length > 1) ctx.stack.pop(); // close the top menu or panel first
+  else if (ctx.ui.modal.open) ctx.ui.modal.close();
+  else if (canGoBack) history.back(); // only if the game uses the WebView's history (most do not)
+  else void App.minimizeApp(); // or App.exitApp(); the host.lifecycle flush has already run
+});
+```
+
+On iOS there is no back button; the swipe-from-edge gesture is the WebView's history navigation,
+which a single-page game never has, so nothing is needed. `host.back` is `undefined` when
+`plugins.App` was not given.
+
+## Lifecycle on a phone
+
+`createGame` already watches `host.lifecycle`: on `background` it stops requesting frames and
+flushes the save; on `active` it starts again, then calls `hooks.lifecycle(state)`. A game that
+wants to autosave more than the store's debounced writes, or to pause its music, does it there:
+
+```ts
+ctx.hooks.lifecycle = (state) => {
+  if (state === 'background') { ctx.save?.flush(); music.stop(); }
+  else music.play('theme');
+};
+```
+
+iOS may terminate a backgrounded app at any time, so treat `background` as "the last chance to
+write"; the host's lifecycle fires it from `appStateChange`, which arrives before the WebView is
+frozen.
+
+## Checks
+
+`pnpm check:host-capacitor` from the repo root (typecheck, Biome, Vitest), also run by `pnpm check`.
+There is no e2e here: the facets are exercised against the web host on the engine's matrix
+(`e2e/host.spec.ts`, `harness/host.html`), and this host's plugin mapping is covered by the unit
+tests with fake plugins.

package/dist/capacitor.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The Capacitor host: `Host` (engine/host, D-041) for a game packaged as an iOS or Android app
+ * with Capacitor. The page is the game's web build in the platform WebView, so frames, the
+ * safe area and the fallbacks for everything else come from a web host (`base`); each Capacitor
+ * plugin the app hands in (`plugins`) replaces one facet: links open in the in-app browser,
+ * the clipboard and haptics go native, saves live in Preferences (which survive the WebView's
+ * storage being cleared), and the lifecycle follows the app's foreground state instead of the
+ * document's visibility. Nothing here imports a Capacitor package: the plugins are peers,
+ * typed by hand in plugins.ts.
+ */
+import { type Host, type HostHaptics, type HostLifecycle, type HostStorage } from '@thunderclap-engine/engine/host';
+import type { AppPlugin, BackButtonEvent, CapacitorPlugins, HapticsPlugin, PreferencesPlugin } from './plugins.js';
+export interface CapacitorHostOptions {
+    /** The Capacitor plugins the app installed. Each missing one falls back to `base`. */
+    plugins?: Partial<CapacitorPlugins>;
+    /** The host answering for everything a plugin does not. Default: `createWebHost({ win })`. */
+    base?: Host;
+    /** The WebView's window, for the default `base`. Default: the global `window`. */
+    win?: Window;
+}
+/** Android's hardware or gesture back. Present only when `plugins.App` was given. */
+export interface HostBack {
+    /**
+     * Calls `fn` on each back press. Registering any listener takes over the platform default
+     * (leaving the app), so a game that has nothing to close should call `App.exitApp()` itself.
+     * Returns unsubscribe.
+     */
+    watch(fn: (event: BackButtonEvent) => void): () => void;
+}
+export interface CapacitorHost extends Host {
+    readonly kind: 'capacitor';
+    /**
+     * Resolves once `storage.open()` can answer: the Preferences store has been read into the
+     * mirror. Until then `open()` returns null and the save store tries again on its next write.
+     * Resolves at once when there is no `Preferences` plugin (saves then use `base.storage`).
+     */
+    readonly ready: Promise<void>;
+    readonly back?: HostBack;
+}
+export declare function createCapacitorHost(opts?: CapacitorHostOptions): CapacitorHost;
+/**
+ * The app's foreground state as a `HostLifecycle`. `appStateChange` carries it; `pause` and
+ * `resume` are honoured too, for platforms that send only those. Starts `active` (the page is
+ * running) and corrects itself from `getState()`.
+ */
+export declare function createAppLifecycle(app: AppPlugin): HostLifecycle;
+/** `@capacitor/haptics` as a `HostHaptics`. Every call is fire-and-forget; a rejection is dropped. */
+export declare function createCapacitorHaptics(haptics: HapticsPlugin): HostHaptics;
+/**
+ * Preferences as a synchronous `StorageLike` (`kind: 'preferences'`): reads are served from an
+ * in-memory mirror loaded once from the plugin, writes update the mirror at once and reach the
+ * plugin in order behind a promise chain. `open()` returns null until the load finished (`ready`),
+ * so an early save-store write misses nothing: it retries on the next write.
+ */
+export declare function createPreferencesStorage(prefs: PreferencesPlugin): {
+    storage: HostStorage;
+    ready: Promise<void>;
+};

package/dist/capacitor.js

@@ -0,0 +1,209 @@
+/**
+ * The Capacitor host: `Host` (engine/host, D-041) for a game packaged as an iOS or Android app
+ * with Capacitor. The page is the game's web build in the platform WebView, so frames, the
+ * safe area and the fallbacks for everything else come from a web host (`base`); each Capacitor
+ * plugin the app hands in (`plugins`) replaces one facet: links open in the in-app browser,
+ * the clipboard and haptics go native, saves live in Preferences (which survive the WebView's
+ * storage being cleared), and the lifecycle follows the app's foreground state instead of the
+ * document's visibility. Nothing here imports a Capacitor package: the plugins are peers,
+ * typed by hand in plugins.ts.
+ */
+import { createWebHost, } from '@thunderclap-engine/engine/host';
+import { safeExternalUrl } from '@thunderclap-engine/engine/platform';
+/** Key under which every save key is kept in Preferences, so a `keys()` sweep finds only ours. */
+const PREFIX = 'tc:';
+export function createCapacitorHost(opts = {}) {
+    const plugins = opts.plugins ?? {};
+    const base = opts.base ?? createWebHost({ win: opts.win });
+    const { App, Browser, Clipboard, Haptics, Preferences, ScreenOrientation } = plugins;
+    const storage = Preferences ? createPreferencesStorage(Preferences) : null;
+    const host = {
+        kind: 'capacitor',
+        // The WebView is a page: frames come from its requestAnimationFrame via the base host.
+        requestFrame: (cb) => base.requestFrame(cb),
+        cancelFrame: (handle) => base.cancelFrame(handle),
+        get embed() {
+            return base.embed;
+        },
+        openExternal(url, o) {
+            if (!Browser)
+                return base.openExternal(url, o);
+            const href = safeExternalUrl(url);
+            if (!href)
+                return 'invalid';
+            // An in-app browser sheet has no popup blocker: every activation opens.
+            void Browser.open({ url: href }).catch(() => { });
+            return 'opened';
+        },
+        async copyText(text) {
+            if (!Clipboard)
+                return base.copyText(text);
+            try {
+                await Clipboard.write({ string: String(text) });
+                return 'copied';
+            }
+            catch {
+                return 'manual';
+            }
+        },
+        clipboardWriteAllowed: () => (Clipboard ? true : base.clipboardWriteAllowed()),
+        fullscreen: {
+            // A store app already fills the screen; there is nothing to enter or leave.
+            available: () => false,
+            active: false,
+            async toggle(o) {
+                if (o?.lockLandscape && ScreenOrientation) {
+                    try {
+                        await ScreenOrientation.lock({ orientation: 'landscape' });
+                    }
+                    catch {
+                        // Refused (a tablet policy, an unsupported platform): leave things as they were.
+                    }
+                }
+                return false;
+            },
+            watch: () => () => { },
+        },
+        storage: storage?.storage ?? base.storage,
+        ready: storage?.ready ?? Promise.resolve(),
+        lifecycle: App ? createAppLifecycle(App) : base.lifecycle,
+        haptics: Haptics ? createCapacitorHaptics(Haptics) : base.haptics,
+        safeArea: base.safeArea,
+        // No `window`: a phone app has no title bar or close box.
+    };
+    if (App) {
+        host.back = {
+            watch: (fn) => listen(App.addListener('backButton', fn)),
+        };
+    }
+    return host;
+}
+/** Subscribes through a Capacitor listener handle (direct or promised). Returns unsubscribe. */
+function listen(result) {
+    let removed = false;
+    const handle = Promise.resolve(result);
+    handle.catch(() => { });
+    return () => {
+        if (removed)
+            return;
+        removed = true;
+        void handle.then((h) => h.remove()).catch(() => { });
+    };
+}
+/**
+ * The app's foreground state as a `HostLifecycle`. `appStateChange` carries it; `pause` and
+ * `resume` are honoured too, for platforms that send only those. Starts `active` (the page is
+ * running) and corrects itself from `getState()`.
+ */
+export function createAppLifecycle(app) {
+    let state = 'active';
+    const watchers = new Set();
+    const set = (next) => {
+        if (next === state)
+            return;
+        state = next;
+        for (const fn of [...watchers])
+            fn(state);
+    };
+    let listening = false;
+    const listen = () => {
+        if (listening)
+            return;
+        listening = true;
+        app.addListener('appStateChange', (s) => set(s.isActive ? 'active' : 'background'));
+        app.addListener('pause', () => set('background'));
+        app.addListener('resume', () => set('active'));
+        app
+            .getState()
+            .then((s) => set(s.isActive ? 'active' : 'background'))
+            .catch(() => { });
+    };
+    return {
+        get state() {
+            return state;
+        },
+        watch(fn) {
+            listen();
+            watchers.add(fn);
+            return () => {
+                watchers.delete(fn);
+            };
+        },
+    };
+}
+const IMPACT = {
+    light: 'LIGHT',
+    medium: 'MEDIUM',
+    heavy: 'HEAVY',
+};
+const NOTIFICATION = {
+    success: 'SUCCESS',
+    warning: 'WARNING',
+    error: 'ERROR',
+};
+/** `@capacitor/haptics` as a `HostHaptics`. Every call is fire-and-forget; a rejection is dropped. */
+export function createCapacitorHaptics(haptics) {
+    const fire = (p) => {
+        p.catch(() => { });
+    };
+    return {
+        available: () => true,
+        impact: (style) => fire(haptics.impact({ style: IMPACT[style] ?? 'MEDIUM' })),
+        notification: (kind) => fire(haptics.notification({ type: NOTIFICATION[kind] ?? 'SUCCESS' })),
+        vibrate: (ms) => {
+            const duration = Math.max(0, Math.round(ms));
+            if (duration > 0)
+                fire(haptics.vibrate({ duration }));
+        },
+    };
+}
+/**
+ * Preferences as a synchronous `StorageLike` (`kind: 'preferences'`): reads are served from an
+ * in-memory mirror loaded once from the plugin, writes update the mirror at once and reach the
+ * plugin in order behind a promise chain. `open()` returns null until the load finished (`ready`),
+ * so an early save-store write misses nothing: it retries on the next write.
+ */
+export function createPreferencesStorage(prefs) {
+    const map = new Map();
+    let loaded = false;
+    let tail = Promise.resolve();
+    const enqueue = (op) => {
+        tail = tail.then(op, op).catch(() => { });
+    };
+    const ready = (async () => {
+        try {
+            const { keys } = await prefs.keys();
+            for (const key of keys) {
+                if (!key.startsWith(PREFIX))
+                    continue;
+                const { value } = await prefs.get({ key });
+                if (value !== null)
+                    map.set(key.slice(PREFIX.length), value);
+            }
+        }
+        catch {
+            // Unreadable: start empty rather than never becoming usable.
+        }
+        loaded = true;
+    })();
+    const mirror = {
+        getItem: (key) => map.get(key) ?? null,
+        setItem(key, value) {
+            const v = String(value);
+            map.set(key, v);
+            enqueue(() => prefs.set({ key: PREFIX + key, value: v }));
+        },
+        removeItem(key) {
+            map.delete(key);
+            enqueue(() => prefs.remove({ key: PREFIX + key }));
+        },
+        get length() {
+            return map.size;
+        },
+        key: (index) => [...map.keys()][index] ?? null,
+    };
+    return {
+        ready,
+        storage: { kind: 'preferences', open: () => (loaded ? mirror : null) },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@thunderclap-engine/host-capacitor`: the engine's `Host` for a Capacitor (iOS / Android) app.
+ * See README.md for the capacitor.config.ts recipe and the back-button guidance.
+ */
+export { type CapacitorHost, type CapacitorHostOptions, createAppLifecycle, createCapacitorHaptics, createCapacitorHost, createPreferencesStorage, type HostBack, } from './capacitor.js';
+export type { AppPlugin, AppState, BackButtonEvent, BrowserPlugin, CapacitorPlugins, ClipboardPlugin, HapticsPlugin, ImpactStyle, ListenerResult, NotificationType, OrientationLockType, PluginListenerHandle, PreferencesPlugin, ScreenOrientationPlugin, } from './plugins.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * `@thunderclap-engine/host-capacitor`: the engine's `Host` for a Capacitor (iOS / Android) app.
+ * See README.md for the capacitor.config.ts recipe and the back-button guidance.
+ */
+export { createAppLifecycle, createCapacitorHaptics, createCapacitorHost, createPreferencesStorage, } from './capacitor.js';

package/dist/plugins.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The slices of Capacitor's plugin APIs this host calls, written out by hand so the package
+ * compiles and tests without the `@capacitor/*` packages installed (they are optional peers the
+ * app installs and hands to `createCapacitorHost({ plugins })`). The shapes follow Capacitor 5+;
+ * the real plugin objects satisfy them structurally. `addListener` returns the handle directly
+ * in some versions and a promise of it in others, so both are accepted.
+ */
+export interface PluginListenerHandle {
+    remove(): Promise<void>;
+}
+export type ListenerResult = PluginListenerHandle | Promise<PluginListenerHandle>;
+export interface AppState {
+    isActive: boolean;
+}
+export interface BackButtonEvent {
+    /** True when the WebView has history to go back to. */
+    canGoBack: boolean;
+}
+/** `@capacitor/app`: the app's foreground state and Android's back button. */
+export interface AppPlugin {
+    getState(): Promise<AppState>;
+    addListener(event: 'appStateChange', fn: (state: AppState) => void): ListenerResult;
+    addListener(event: 'pause' | 'resume', fn: () => void): ListenerResult;
+    addListener(event: 'backButton', fn: (event: BackButtonEvent) => void): ListenerResult;
+    exitApp(): Promise<void>;
+}
+/** `@capacitor/browser`: an in-app browser sheet for external links. */
+export interface BrowserPlugin {
+    open(options: {
+        url: string;
+    }): Promise<void>;
+}
+/** `@capacitor/clipboard`. */
+export interface ClipboardPlugin {
+    write(options: {
+        string: string;
+    }): Promise<void>;
+}
+export type ImpactStyle = 'LIGHT' | 'MEDIUM' | 'HEAVY';
+export type NotificationType = 'SUCCESS' | 'WARNING' | 'ERROR';
+/** `@capacitor/haptics`. The enums are string-valued, so their literals are accepted. */
+export interface HapticsPlugin {
+    impact(options?: {
+        style: ImpactStyle;
+    }): Promise<void>;
+    notification(options?: {
+        type: NotificationType;
+    }): Promise<void>;
+    vibrate(options?: {
+        duration: number;
+    }): Promise<void>;
+}
+/** `@capacitor/preferences`: a string key-value store that survives app updates. */
+export interface PreferencesPlugin {
+    get(options: {
+        key: string;
+    }): Promise<{
+        value: string | null;
+    }>;
+    set(options: {
+        key: string;
+        value: string;
+    }): Promise<void>;
+    remove(options: {
+        key: string;
+    }): Promise<void>;
+    keys(): Promise<{
+        keys: string[];
+    }>;
+}
+export type OrientationLockType = 'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
+/** `@capacitor/screen-orientation`. */
+export interface ScreenOrientationPlugin {
+    lock(options: {
+        orientation: OrientationLockType;
+    }): Promise<void>;
+    unlock(): Promise<void>;
+}
+/**
+ * Every plugin the host can use, keyed by the name each package exports. Pass the ones the app
+ * installed; each missing one falls back to the base (web) host's answer or to a no-op.
+ */
+export interface CapacitorPlugins {
+    App: AppPlugin;
+    Browser: BrowserPlugin;
+    Clipboard: ClipboardPlugin;
+    Haptics: HapticsPlugin;
+    Preferences: PreferencesPlugin;
+    ScreenOrientation: ScreenOrientationPlugin;
+}

package/dist/plugins.js

@@ -0,0 +1,8 @@
+/**
+ * The slices of Capacitor's plugin APIs this host calls, written out by hand so the package
+ * compiles and tests without the `@capacitor/*` packages installed (they are optional peers the
+ * app installs and hands to `createCapacitorHost({ plugins })`). The shapes follow Capacitor 5+;
+ * the real plugin objects satisfy them structurally. `addListener` returns the handle directly
+ * in some versions and a promise of it in others, so both are accepted.
+ */
+export {};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@thunderclap-engine/host-capacitor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "ThunderClap's Capacitor host: createCapacitorHost() fills the engine's Host interface from Capacitor's plugins for an iOS or Android store app. It knows nothing about any game and has no dependencies; the @capacitor/* plugins are the app's own (not declared here: pnpm would try to install them), handed in through the plugins option.",
+  "license": "MIT",
+  "author": "ThunderClap",
+  "homepage": "https://github.com/Mandalorian007/thunderclap-engine/tree/main/packages/host-capacitor#readme",
+  "bugs": {
+    "url": "https://github.com/Mandalorian007/thunderclap-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mandalorian007/thunderclap-engine.git",
+    "directory": "packages/host-capacitor"
+  },
+  "keywords": [
+    "thunderclap",
+    "capacitor",
+    "ios",
+    "android",
+    "webgpu",
+    "game-engine"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@thunderclap-engine/engine": "^1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@types/node": "^26.6.6",
+    "@webgpu/types": "^0.1.74",
+    "happy-dom": "^21.0.4",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5",
+    "@thunderclap-engine/engine": "1.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm lint && pnpm test"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js"
 }