# Optional app support manifest

Package `hackemist-app.json` beside `index.html` to describe what the static app needs and which fallbacks it implements. It is optional, at most 16 KiB of UTF-8 JSON, and uses `schema_version: 1`. The platform validates closed fields, supported feature names and bounded lists. Duplicate JSON keys, duplicate list entries and non-finite JSON are rejected. An absent manifest preserves existing apps. Declarations are claims, never permission grants or proof of gameplay.

The [JSON schema](/docs/app-support.schema.json) documents the shared fields and bounds and is also exposed through MCP discovery. Server admission additionally checks cross-field rules, origin validity and duplicate JSON keys. The complete example below validates against it.

```json
{
  "schema_version": 1,
  "entrypoint": "index.html",
  "required_features": ["cloud_saves"],
  "optional_features": ["webgpu", "webgl2", "pointer_lock"],
  "device_targets": ["desktop", "phone", "tablet"],
  "input_controls": ["touch", "keyboard", "mouse"],
  "orientation": "any",
  "layout_mode": "responsive",
  "save_strategy": "sdk",
  "external_origins": []
}
```

Supported feature names are `webgl2`, `webgpu`, `workers`, `wasm`, `shared_memory`, `webxr`, `pointer_lock`, `service_workers`, `frames`, `forms`, `external_network`, `cloud_saves` and `multiplayer`. Use `required_features` only when the app cannot work without the feature. Use `optional_features` for enhancements with an implemented fallback. A feature cannot appear in both lists. `any_of` optionally contains up to four groups of two to four alternative feature names: `"any_of": [["webgpu", "webgl2"]]` means at least one alternative in that group is required. Omit that requirement when a 2D fallback works without either API.

`entrypoint` defaults to and must remain `index.html`. `device_targets` accepts `desktop`, `phone`, `tablet`, `tv`; `input_controls` accepts `touch`, `keyboard`, `mouse`, `gamepad`. `orientation` is `any`, `portrait` or `landscape`. `layout_mode` is `responsive`, `adaptive` or `fixed`. `save_strategy` is `none`, `local`, `browser_sync` or `sdk`. These describe the implementation and do not enable room/saving options or replace listing metadata. `external_origins` lists up to twenty exact HTTPS/WSS origins without paths, credentials, query, fragment or wildcards; each still needs the platform's separate approval and the backend's own authentication/CORS.

Detect APIs and actual adapter/context creation inside the app. Respect site switches, browser permissions and player gestures. Workers and shared-memory WASM require appropriate isolated hosting; shared memory also needs workers and cross-origin isolation. XR requires a compatible browser/device and consent. A platform grant cannot create a GPU adapter or fix a missing decoder. [The complete graphics fallback](/docs/graphics-example.md) checks actual WebGL 2 context creation, reports WebGPU adapter availability and offers a readable 2D fallback with bounded device-pixel ratio. [The complete save counter](/docs/progress-example.md) shows restore-before-play and deliberate recovery.

Build tools and application backends run outside Hackemist. Bundle static output, loaders, WASM and assets; keep provider secrets on your backend. See [browser hosting](/docs/hosting.md), [external connections](/docs/connections.md) and [the version contract](/docs/platform-contract.md).