evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/evomeme-native-bridge-sdk/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: evomeme-native-bridge-sdk
+description: Integrate native capabilities such as camera, microphone, gyroscope, and vibration through the NativeBridge SDK inside the evomeme platform host. Web API fallback is prohibited; SDK calls and permission requests must be initiated synchronously as soon as the game loads. Use when an H5 game needs the above native capabilities, file access, client identity, or migration from an old bridge.
+---
+
+# evomeme-native-bridge-sdk
+
+## NativeBridge Native Capability Rules (Hard Requirements)
+
+Whenever a game involves camera, microphone, gyroscope, or vibration capabilities, `evomeme-native-bridge-sdk` must be used to complete the integration.
+
+1. Camera capabilities must be called through NativeBridge methods such as `camera.pickImage`, `camera.takePhoto`, `camera.preview.start`, `camera.preview.stop`, `camera.microphone.start`, and `camera.microphone.stop`.
+2. Microphone volume or recording-related input must be implemented through `microphone.startMeter`, `microphone.stopMeter`, and the `microphone.level` event.
+3. Gyroscope input must be implemented through `gyro.start`, `gyro.stop`, and the `gyro.data` event.
+4. Vibration feedback must be implemented through the `vibrate` method.
+
+### Web Capability Fallback Is Prohibited
+
+**Camera, microphone, gyroscope, and vibration must all use only the NativeBridge SDK; using browser Web APIs for any fallback or parallel implementation is prohibited.**
+
+Prohibited items include but are not limited to:
+
+- `navigator.mediaDevices.getUserMedia` / `enumerateDevices` (camera, microphone)
+- `DeviceOrientationEvent` / `DeviceMotionEvent` / `deviceorientation` (gyroscope)
+- `navigator.vibrate` (vibration)
+- Self-wrapped dual-path logic such as "fall back to Web if the SDK fails"
+- Depending on browser-simulated results such as the SDK's internal `web-media-stream` / `web-media-stream-fallback` as the normal gameplay path
+
+When the SDK is unavailable, `invoke` fails, or permission is denied: clearly tell the user they need to play / authorize inside the **evomeme platform host**, and **do not** silently switch to a Web implementation to pretend the capability is available.
+
+### Timeliness Must Be Guaranteed (Request on Load)
+
+When using NativeBridgeSDK, **you must initiate the required SDK calls and permission-related requests as soon as the game has just loaded and is still foregrounded and interactive**, ensuring the authorization flow occurs in the current session visible to the user.
+
+It is **prohibited** to defer permission requests until:
+
+- after the game has entered the background, the page has changed, or a modal covers the main interface;
+- after a long-running asynchronous process (asset loading, network request, level generation) completes and then "make up" the request;
+- inside a delayed callback after the user has left the current game context.
+
+Otherwise this will occur: **the game is already in the background, and only then does the host show an asynchronous permission authorization prompt**, which will seriously confuse the user (they will not know which app is asking for permission or why a prompt suddenly appears).
+
+Recommended practice:
+
+1. Obtain the bridge at the earliest startup stage (see "Step 1" below).
+2. If gameplay depends on camera / microphone / gyroscope / vibration, call the corresponding `invoke` (or the host-agreed permission precheck method) **immediately** after the first screen becomes interactive; do not wait until the player reaches a certain level to request permission for the first time.
+3. Keep the game foregrounded while the permission prompt is shown; do not assume the capability is available before authorization is granted.
+
+## Overview
+
+Use this skill when an H5 game inside the **evomeme platform host** (usually an RN WebView) needs to call native capabilities. Business code must depend only on the unified SDK:
+
+```js
+const bridge = window.NativeBridge || window.NativeBridgeSDK;
+```
+
+Do not directly call `window.ReactNativeWebView`, `postMessage`, or host-private objects in game business code.  
+For camera, microphone, gyroscope, and vibration: **recognize only the SDK, not browser Web APIs.**
+
+If the repository contains `html/native-bridge-sdk.js` or an equivalent SDK implementation file, read that implementation first and treat the implementation as authoritative; if the implementation file does not exist, use the protocol conventions in this skill as the integration baseline. Do not rewrite the host-side bridge out of thin air, and do not impersonate the bridge with Web APIs.
+
+## When to Use This Skill
+
+This skill must be used when any of the following requirements appear:
+
+- The game needs native capabilities such as camera, microphone, gyroscope, vibration, file reading/writing, username, client information, and so on.
+- Keywords such as `NativeBridge`, `NativeBridgeSDK`, `ReactNativeWebView`, `rn-webview`, `bridge.invoke`, or `gyro.start` appear in the code.
+- Old direct host calls or old Web API device calls need to be migrated to unified `NativeBridge` SDK calls.
+
+This skill **does not target** a goal where the above four device capability categories are fully usable in a "pure browser"; the target runtime environment is the evomeme platform host.
+
+## Stable API
+
+Use only the following public API:
+
+```ts
+interface NativeBridge {
+  version: string;
+  invoke<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  on(eventName: string, handler: (payload: unknown) => void): () => void;
+  off(eventName: string, handler: (payload: unknown) => void): void;
+  isAvailable(method: string): boolean;
+  getRuntime(): { host: "rn-webview" | "browser"; version: string };
+  reportReady(payload?: Record<string, unknown>): Record<string, unknown>;
+  dispose(): void;
+}
+```
+
+Obtain the bridge first during integration:
+
+```js
+function getNativeBridge() {
+  return window.NativeBridge || window.NativeBridgeSDK || null;
+}
+```
+
+If `getNativeBridge()` is `null`: do not switch to Web APIs to implement camera/microphone/gyroscope/vibration; instead, indicate that the environment is unsupported and disable gameplay branches that depend on these capabilities.
+
+## Method List
+
+Method names must match exactly, word for word; do not rewrite them to camelCase or old names.
+
+| Type | Method |
+| --- | --- |
+| General capabilities | `bridge.ping`, `ping`, `vibrate`, `getUsername`, `getClientInfo` |
+| Camera and microphone | `camera.pickImage`, `camera.takePhoto`, `camera.preview.start`, `camera.preview.stop`, `camera.microphone.start`, `camera.microphone.stop`, `microphone.startMeter`, `microphone.stopMeter` |
+| File capabilities | `fs.readText`, `fs.writeText`, `fs.list` |
+| Sensor capabilities | `gyro.start`, `gyro.stop` |
+
+Important parameters and returns:
+
+- `vibrate({ style })`: `style` may be `light | medium | heavy`.
+- `gyro.start({ interval })`: `interval` defaults to `100`, in ms; `{ x, y, z, ts }` is pushed through `gyro.data`.
+- `microphone.startMeter()`: returns `{ started: true }`; `{ level, ts }` is pushed through `microphone.level`.
+- `camera.preview.start()` / `camera.microphone.start()`: follow the host SDK return value; **do not** implement gameplay based on browser `MediaStream` assumptions, and **do not** use Web media stream fallback.
+- `fs.readText({ path }) -> { path, text }`.
+- `fs.writeText({ path, text }) -> { path, bytes }`.
+- `fs.list() -> { files: string[] }`.
+
+## Event List
+
+Subscribe only to events supported by the current SDK:
+
+| Event | payload |
+| --- | --- |
+| `camera.state` | `{ state: "started" | "stopped", ts, source? }` |
+| `camera.microphone.state` | `{ state: "started" | "stopped", ts }` |
+| `microphone.level` | `{ level, ts }` |
+| `gyro.data` | `{ x, y, z, ts }` |
+
+The current SDK does not have a `microphone.state` event. Do not subscribe to or trigger this event name.
+
+## Runtime Differences
+
+### rn-webview (Target Environment)
+
+- `invoke` is sent by the SDK through `ReactNativeWebView.postMessage(JSON.stringify(message))` as `{ id, type: "invoke", method, params }`.
+- The host returns `{ id, ok: true, result }` or `{ id, ok: false, error }`.
+- The SDK receives host events as `{ type: "event", event, payload }`.
+- The `invoke` timeout threshold is `15000ms`; timeout throws `TIMEOUT`.
+- `isAvailable(method)` is always `true` in the RN runtime, and does not mean the host definitely implements that capability; `invoke` failures must still be handled.
+
+### browser (Non-Target Full Environment)
+
+- **Web APIs must not** be used to provide usable implementations for camera, microphone, gyroscope, or vibration.
+- If `getRuntime().host === "browser"` is detected, or the bridge is missing: disable gameplay related to the above four capability categories, and prompt the user to open it inside the evomeme platform.
+- If `fs.*` is not injected by the host, it may be shown as unavailable; do not forge device sensor data just to make it "playable."
+
+## Integration Workflow
+
+### Step 1: Initialize the bridge and initiate permission-related calls on load (timeliness)
+
+When the game starts and is still foregrounded, immediately get the bridge and runtime, and `invoke` the capabilities needed by gameplay **as early as possible** (triggering the host permission prompt), to avoid background asynchronous authorization.
+
+```js
+const bridge = getNativeBridge();
+const runtime = bridge?.getRuntime?.();
+
+if (!bridge || runtime?.host === "browser") {
+  // Disable camera/microphone/gyroscope/vibration-related gameplay; prompt the user to play inside the evomeme platform
+} else {
+  // Whichever capabilities gameplay needs, initiate the corresponding invoke at this stage (or at the immediately following first-screen interactive moment)
+  // Example: await bridge.invoke("gyro.start", { interval: 100 });
+  // Example: await bridge.invoke("microphone.startMeter");
+  // Prohibited: placing the first permission request after a long-running asynchronous task completes
+}
+
+bridge?.reportReady?.({ scene: "game-main", host: runtime?.host || "unknown" });
+```
+
+`reportReady` is used to notify the host that "the game is interactive." It should be called once after core resources have loaded and the first screen is operable; **permission-related `invoke` calls must not be deliberately scheduled after the user has already left the foreground.**
+
+### Step 2: Wrap safe calls (no Web fallback)
+
+Every `invoke` must use `try/catch` and branch by `error.code`. Bare calls are prohibited. On failure, return a clear "unavailable" state, and **do not** internally call Web APIs instead.
+
+```js
+async function invokeNative(method, params) {
+  const bridge = getNativeBridge();
+  if (!bridge) {
+    return { ok: false, reason: "NO_BRIDGE" };
+  }
+
+  try {
+    const result = await bridge.invoke(method, params);
+    return { ok: true, result };
+  } catch (error) {
+    switch (error?.code) {
+      case "UNAVAILABLE":
+      case "PERMISSION_DENIED":
+      case "TIMEOUT":
+      case "CANCELLED":
+        return { ok: false, reason: error.code, error };
+      default:
+        console.warn("[NativeBridge]", method, error);
+        return { ok: false, reason: error?.code || "UNKNOWN", error };
+    }
+  }
+}
+```
+
+Error codes that must be recognized:
+
+- `UNAVAILABLE`
+- `PERMISSION_DENIED`
+- `INVALID_PARAMS`
+- `INTERNAL_ERROR`
+- `TIMEOUT`
+- `CANCELLED`
+- `NOT_FOUND`
+
+### Step 3: Subscribe to events and save unregister functions
+
+All cancel-subscription functions returned by `on` must be saved, and must be called on React unmount, scene shutdown, or page destruction.
+
+```js
+const nativeDisposers = [];
+
+function subscribeGyro(onData) {
+  const bridge = getNativeBridge();
+  if (!bridge) return;
+  nativeDisposers.push(bridge.on("gyro.data", onData));
+}
+
+function cleanupNativeBridge() {
+  while (nativeDisposers.length) {
+    const off = nativeDisposers.pop();
+    try { off && off(); } catch (_) {}
+  }
+}
+```
+
+### Step 4: Product behavior when a capability is unavailable (not Web fallback)
+
+When SDK / permission fails:
+
+- Clear UI copy must explain that platform authorization is required or that it must be opened inside evomeme.
+- Alternative gameplay that **does not depend on device sensors** may be provided (such as pure touch-control levels), but this is not "using Web APIs to simulate gyroscope/camera."
+- Do not use `getUserMedia` / `deviceorientation` / `navigator.vibrate` to fill the gap.
+
+### Step 5: Stop started capabilities on teardown
+
+When the page or game scene is destroyed, first stop started capabilities, then unsubscribe events, and finally call `dispose`.
+
+```js
+async function destroyNativeBridgeFeatures() {
+  const bridge = getNativeBridge();
+  if (!bridge) return;
+
+  await bridge.invoke("gyro.stop").catch(() => {});
+  await bridge.invoke("microphone.stopMeter").catch(() => {});
+  await bridge.invoke("camera.preview.stop").catch(() => {});
+  await bridge.invoke("camera.microphone.stop").catch(() => {});
+
+  cleanupNativeBridge();
+  bridge.dispose?.();
+}
+```
+
+## Configuration Integration Constraints
+
+- `/public/config.json` remains the configuration source for game assets, colors, values, copy, and adjustable parameters (for 2D, see `../phaser-2d-game/references/file-structure.md`; for 3D, see `../threejs-3d-game/references/file-structure.md`); NativeBridge only provides runtime capabilities and does not replace config.
+- Do not write temporary objects returned by native capabilities into `config.json` (for example, media stream objects).
+- Touchscreen operation on mobile must not be broken in order to integrate the bridge.
+- Business logic that directly depends on `window.ReactNativeWebView` must not appear in code. If the host must be detected, do so only through `bridge.getRuntime()`.
+- Direct Web API calls for camera/microphone/gyroscope/vibration must not appear in code.
+
+## Acceptance Checklist
+
+After completing NativeBridge integration, check each item:
+
+- H5 business code only calls `window.NativeBridge || window.NativeBridgeSDK`.
+- Method names and event names exactly match the lists in this skill.
+- **Request on load**: permission / startup-class `invoke` calls that depend on native capabilities occur while the game is foregrounded during the loading stage, with no path where "permission pops up only in the background."
+- **No Web fallback**: the project has no implementation using `getUserMedia` / `deviceorientation` / `navigator.vibrate`, and similar APIs, to replace the above four capability categories.
+- Every `invoke` has explicit error handling and can handle `UNAVAILABLE`, `PERMISSION_DENIED`, and `TIMEOUT`.
+- Every event subscription has unregister logic.
+- Started `gyro`, microphone, and camera preview are stopped on teardown.
+- When the bridge is missing or the host is not the platform host, related capabilities are disabled and the user is prompted, instead of switching to browser APIs.
+
+## Example Trigger Requests
+
+- "Make this H5 game call the gyroscope inside evomeme / RN WebView to control the character."
+- "Integrate NativeBridge camera preview and microphone volume events; permissions must be requested on load."
+- "Migrate old ReactNativeWebView.postMessage or getUserMedia calls to the SDK, with no Web fallback."
+- "Add vibration feedback to the game, using only NativeBridge."

package/dist/skills/en-US/evomeme-native-bridge-sdk/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "evomemeNative Bridge SDK"
+  short_description: "Integrate camera, microphone, gyroscope, and vibration into platform games through the native bridge"
+  default_prompt: "Please use $evomeme-native-bridge-sdk to integrate the required mobile native capabilities for my platform game, and handle permissions, exceptions, and teardown flow."
+
+policy:
+  allow_implicit_invocation: true
+

package/dist/skills/en-US/evomeme-tos-upload/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: evomeme-tos-upload
+description: Upload supported local images, audio, video, or common 3D models to evomemeTOS through evomeme_upload_game_asset, and obtain a public asset_url after content review passes.
+---
+
+# evomeme-tos-upload
+
+## Purpose
+
+Upload supported local images, audio, video, or common 3D models to evomemeTOS and obtain a publicly accessible `asset_url`.
+
+- Call the primary MCP (`evomeme`) tool **`evomeme_upload_game_asset`**; plugin_client selects the image/model synchronous interface or the unified audio/video interface based on the file extension, submits the original bytes, and the server uploads them to TOS. A link is returned only after the content safety review passes.
+- Do not write AK/SK manually, do not forge CDN URLs, and do not put binaries directly into the source repository.
+
+The only allowed extensions are:
+
+- Images: PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, GIF, ICO, HEIC
+- Audio: MP3, WAV, AAC, WMA, OGG, M4A, AMR
+- Video: AVI, FLV, MP4, MPG, ASF, WMV, MOV, WMA, RMVB, RM, FLASH, TS, M3U8
+- Models: GLB, GLTF, FBX, OBJ, STL (when there are external texture or buffer files, packaging as GLB first is recommended)
+
+Fonts, archives, and other types not listed are prohibited from upload. WMA is handled as audio. Images and models undergo synchronous review; audio and video undergo asynchronous polling review.
+
+## Upload Workflow
+
+Must already be logged in to EvoMeme. For upload and submission rules, see `../evomeme-cloud-fs/SKILL.md`; after authentication fails, then follow `../evomeme-login/SKILL.md`.
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `local_path` | yes | Absolute local file path or a path relative to the MCP cwd |
+| `folder` | no | TOS directory prefix |
+| `extension` | no | Extension override |
+
+On success, the tool returns a publicly accessible `asset_url`.
+
+Use this upload workflow when local images / audio and video / common 3D models need a public URL; unlisted types are not supported.
+
+## Non-Negotiables
+
+- Prefer `evomeme_upload_game_asset`; do not upload with ad-hoc credential scripts.
+- Do not write TOS/AK/SK or bearer tokens into skill reports.
+- evomemeMCP tool names always use the `evomeme_` prefix; for submission, see `../evomeme-cloud-fs/SKILL.md`; for generation summaries, see `../game-director/SKILL.md`.
+
+## References
+
+- Cloud file system: `../evomeme-cloud-fs/SKILL.md`
+- evomeme entry point: `../game-director/SKILL.md`

package/dist/skills/en-US/evomeme-tos-upload/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "evomemeTOS Upload"
+  short_description: "Upload local game assets to object storage and return publicly accessible asset links"
+  default_prompt: "Please use $evomeme-tos-upload to upload this local game asset and provide me with the returned public link."
+

package/dist/skills/en-US/evomeme-ui/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: evomeme-ui
+description: Define WebView container adaptation, UI layout, and multi-size acceptance requirements for evomeme platform games. MUST be read when developing any game intended to run, launch, or be published on evomeme, and followed when creating or modifying HUDs, menus, dialogs, touch regions, Canvas dimensions, or responsive layouts.
+---
+
+# evomeme Game UI and Responsive Layout
+
+## Required Reading
+
+For any game intended to run, launch, or be published on evomeme, MUST read this skill before starting development, migration, or modification. Follow it when building game UI, changing layouts, or addressing responsive adaptation; do not postpone adaptation until publication.
+
+This skill defines platform container and layout constraints. Follow [`evomeme-game-maker`](../evomeme-game-maker/SKILL.md) for overall project requirements, and use [`game-ui`](../game-ui/SKILL.md) for UI style, information hierarchy, or concept design. For evomeme games, this skill governs dimension sources, safe-area handling, and responsive acceptance checks.
+
+## Host Container Contract
+
+**The game runs inside the available WebView area already calculated by the App. A "full-screen" game fills that area.**
+
+1. Base layout on the game container's live `clientWidth`, `clientHeight`, or `ResizeObserver` measurements. MUST NOT calculate game height from the phone's full screen height.
+2. MUST NOT subtract the App Tab Bar, game information and action area, or phone safe areas again. MUST NOT use the native host's `3.75rem`, `4.5rem`, or `8.25rem` values in the game's web layout.
+3. The game root, render canvas, and background MUST fill the WebView container. MUST NOT preserve the design ratio with fixed-aspect-ratio containers, black borders, or uniform shrinking of the entire game frame.
+4. Backgrounds may be cropped or extended. Core characters, HUDs, text, buttons, and gameplay hit regions MUST remain visible and usable. Do not position key content solely using fixed absolute coordinates relative to the design draft's screen edges.
+5. When the container changes size, recalculate the layout, camera or playable area, Canvas rendering dimensions, and touch coordinate mapping. Layout overflow MUST NOT create page scrollbars.
+6. The native App's dynamic NativeWind `rem` does not automatically propagate into the WebView. Web CSS `rem` depends on the page's root font size. Use CSS px for logical dimensions, not the device's physical resolution.
+
+Read [`references/host-layout.md`](references/host-layout.md) when you need the native deduction formula, the 402px design baseline, or the full estimated device matrix. These references are for design and testing only; MUST NOT use them to hardcode game height at runtime.
+
+## Design and Layout
+
+Use **402×646 CSS px** as the primary design baseline. Typical WebView width-to-height ratios are approximately **1:1.60–1:1.78**, with an extreme short-screen case around **1:1.40**. These are test references, not runtime size limits.
+
+- First ensure that core gameplay, primary buttons, and essential text fit short containers. Use additional height for background extension, spacing, or playable area.
+- Position HUDs, menus, dialogs, and touch regions using container-relative anchors, relative layout, or responsive constraints. They must remain visible and clickable when content length changes.
+- The game may have internal visual padding and touch spacing, but MUST NOT subtract phone safe areas already handled by the host under the guise of safe-area adaptation.
+- Handle background cropping separately from critical content. Do not crop characters, buttons, or hit regions to make the background fill the container.
+- Use the same container dimensions for the full-screen background, DOM UI, game camera, and input coordinates. Avoid scaling the scene while leaving buttons or hit regions at old coordinates.
+
+## Base Web Page Styles
+
+Set a mobile viewport, for example:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+```
+
+Propagate dimensions from the WebView through every parent to the game root. The `#root` and `#game-root` selectors below should match the project's actual mount nodes. Any additional wrappers must preserve the height chain.
+
+```css
+html,
+body,
+#root {
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  margin: 0;
+  overflow: hidden;
+}
+
+#game-root {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+
+#game-root canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+  touch-action: none;
+}
+```
+
+MUST NOT deduct the host layout again with formulas such as `100vh - App bar heights - safe-area-inset`. Use `overflow: hidden` to control page scrolling, not to conceal critical content overflowing the container.
+
+## Synchronizing Canvas and Engine Dimensions
+
+Observe the game container instead of reading window dimensions only once at startup. The example below illustrates the separation between logical and rendering dimensions. `resizeGameLayout` represents the project's actual layout update function and must update the UI, playable area, and input mapping.
+
+```js
+const container = document.querySelector('#game-root');
+const canvas = container.querySelector('canvas');
+
+const observer = new ResizeObserver(([entry]) => {
+  const { width, height } = entry.contentRect;
+  if (width <= 0 || height <= 0) return;
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+  canvas.width = Math.round(width * dpr);
+  canvas.height = Math.round(height * dpr);
+
+  // Logical layout uses CSS px; the rendering buffer uses dimensions multiplied by DPR.
+  resizeGameLayout(width, height, dpr);
+});
+
+observer.observe(container);
+// Call observer.disconnect() when the component unmounts or the scene is destroyed.
+```
+
+For Phaser, Three.js, or other engines, implement equivalent behavior through the engine's existing resize, camera, and pixel-ratio APIs. Avoid managing the canvas a second time outside the engine. With native Canvas 2D, restore drawing transforms and state after changing canvas width or height. Consider capping DPR to prevent excessively large rendering buffers on high-resolution devices.
+
+## Required Responsive Acceptance Checks
+
+Validate at least these three **game container sizes**. Do not subtract host UI from these heights again:
+
+| Test purpose | Container size (CSS px) | Key checks |
+| --- | --- | --- |
+| Minimum usable height | 375×524 | Core gameplay, HUDs, dialogs, and primary controls do not overflow or become obscured |
+| Standard design baseline | 402×646 | Main visuals, information hierarchy, and interaction flows are complete |
+| Tall Android screen | 412×732 | Background extension, vertical layout, and touch coordinates remain correct |
+
+Browser or embedded-container simulation is acceptable during development. Before delivery, verify the main states using the actual production `dist/` build and cover at least one container size change while the game is running.
+
+- [ ] The root container, Canvas, and background always fill the WebView without black borders or uncovered areas.
+- [ ] Layout does not use the phone's full screen height, enforce a fixed aspect ratio, or subtract native bars and safe areas again.
+- [ ] Key characters, buttons, text, HUDs, and hit regions remain fully visible at all three sizes.
+- [ ] Start, gameplay, pause, results, and any other main interfaces provided by the game remain operable.
+- [ ] After scaling or resizing, the UI, rendered scene, and touch hit regions remain aligned.
+- [ ] The page has no unintended scrollbars, and clipping does not conceal overflowing critical content.
+
+At delivery, report the sizes, interface states, and results actually verified. If real-device or host WebView validation was not possible, state that limitation; do not describe browser simulation as real-device acceptance testing.

package/dist/skills/en-US/evomeme-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "evomeme UI"
+  short_description: "Adapt evomeme game UI to responsive WebView containers"
+  default_prompt: "Use $evomeme-ui to implement UI and responsive adaptation for a game intended for evomeme, and verify all three game container sizes."

package/dist/skills/en-US/evomeme-ui/references/host-layout.md

@@ -0,0 +1,69 @@
+# Native Host Layout and WebView Size Reference
+
+This reference is adapted from the project's Game WebView Multi-Device Sizing Specification. Use it to understand the design baseline, estimate available space, and establish a test matrix. At runtime, the game must always use live container measurements. Do not move the native formulas below into the web page and subtract the same heights again.
+
+## The 402px Design Baseline and Native rem
+
+The App's design baseline width is 402px, where `1rem = 16`. These design dimensions correspond to React Native's logical layout units, dp, rather than the device's physical pixels.
+
+The native layer adjusts NativeWind rem in `app/_layout.tsx` according to the device window's logical width `W`:
+
+```text
+Scale S = W / 402
+Native 1rem = 16 × W / 402
+```
+
+| Window width W | Native 1rem (approximately) |
+| ---: | ---: |
+| 360 | 14.33 |
+| 375 | 14.93 |
+| 393 | 15.64 |
+| 402 | 16.00 |
+| 430 | 17.11 |
+
+CSS rem inside the WebView depends on the web page's own root font size, typically 16 CSS px by default. It does not inherit the dynamic NativeWind rem above.
+
+## Estimating the Game Area in the Native Layer
+
+```text
+H_game ≈ H_window - safeTop - safeBottom - 8.25rem
+```
+
+| Native region | NativeWind size | Logical height at the 402px baseline |
+| --- | --- | ---: |
+| Tab Bar body | h-13 / 3.25rem | 52 |
+| Tab Bar top and bottom spacing | py-1 × 2 / 0.5rem | 8 |
+| Complete Tab Bar | 3.75rem | 60 |
+| Game information and action area | h-18 / 4.5rem | 72 |
+| Total fixed deduction | 8.25rem | 132 |
+
+Because native rem scales with width:
+
+```text
+Fixed height deduction = 8.25 × 16 × W / 402
+                       = 132 × W / 402
+                       ≈ 0.32836W
+
+Estimated WebView width = W
+Estimated WebView height ≈ H - safeTop - safeBottom - 0.32836W
+```
+
+For W values of 360, 375, 393, 402, and 430, the fixed height deductions are approximately 118.2, 123.1, 129.0, 132, and 141.2 logical units, respectively. The host has already applied these deductions; the game simply fills the WebView.
+
+## Estimated Device Matrix
+
+The representative devices and assumed safe areas below come from the original specification. They are not device-detection rules. OS versions, display scaling, orientation changes, and Android vendor implementations may introduce differences of approximately 5–15px. Actual available dimensions must still be measured.
+
+| Representative device | Logical screen size | Assumed safe areas (top/bottom) | Estimated WebView size | Width-to-height ratio |
+| --- | --- | --- | --- | --- |
+| iPhone SE 2/3 | 375×667 | 20 / 0 | 375×524 | 1:1.40 |
+| iPhone 13 mini | 360×780 | 50 / 34 | 360×578 | 1:1.61 |
+| iPhone 12/13/14 | 390×844 | 47 / 34 | 390×635 | 1:1.63 |
+| iPhone 14 Pro / 15 | 393×852 | 59 / 34 | 393×630 | 1:1.60 |
+| iPhone 16 Pro / 17 | 402×874 | 62 / 34 | 402×646 | 1:1.61 |
+| iPhone Plus / Pro Max | 430×932 | 59 / 34 | 430×698 | 1:1.62 |
+| Compact Android | 360×800 | 24 / 24 | 360×634 | 1:1.76 |
+| Standard Android | 384×832 | 24 / 24 | 384×658 | 1:1.71 |
+| Large-screen Android | 412×915 | 24 / 24 | 412×732 | 1:1.78 |
+
+The original specification estimates an overall range of approximately 1:1.40–1:1.78. Modern iPhones are mainly around 1:1.60–1:1.63, and mainstream Android devices around 1:1.70–1:1.78. Use 375×524 as the minimum-height reference, 402×646 as the primary design reference, and 412×732 as the tall-screen reference. Continue responding to container changes even when actual dimensions fall outside this range.