spritehatch-mcp 0.1.0__tar.gz

spritehatch_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpriteHatch
+
+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.

spritehatch_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: spritehatch-mcp
+Version: 0.1.0
+Summary: MCP server for SpriteHatch: AI agents generate 2D game sprites, animations, effects, items, UI, scenes and tilesets and export them for Godot, Unity, GameMaker and RPG Maker.
+Author: SpriteHatch
+License-Expression: MIT
+Project-URL: Homepage, https://spritehatch.com
+Project-URL: Documentation, https://spritehatch.com/docs/mcp
+Keywords: mcp,model-context-protocol,ai-agents,game-development,sprites,pixel-art,animation,gamedev
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pillow>=10
+Dynamic: license-file
+
+# SpriteHatch MCP
+
+Lets AI agents (Claude Code, Cursor, Codex, Windsurf…) make 2D game assets with [SpriteHatch](https://spritehatch.com)
+and bring them into the game: characters, monsters, animations, abilities with separate effect layers, effects, items,
+UI, parallax scenes and tilesets, exported for Godot, Unity, GameMaker, RPG Maker or plain sprite sheets.
+
+The server teaches the agent which tool fits each need and guards the user's credits:
+
+- `spritehatch_guide` (free) turns a game need ("the dragon breathes fire at the player") into the right recipe, with
+  costs and pitfalls. The same decision rules are sent to the agent when it connects.
+- Quality, art style and image engine are the user's choice: when the request does not say, the tool returns the
+  options (with costs) for the agent to ask, or shows a form in clients that support it. Image engines are known only by
+  their product names.
+- Effects that stay on the body (a charge-up) are drawn into the character animation; what flies to a target becomes
+  separate effects the game moves. The animation plan is shown exactly as it will be generated (prompt, ending, beats)
+  and can be corrected before paying.
+- Session budget and approval: spending above the approval limit since the last approval asks the user (MCP elicitation,
+  or a one-time `confirm_token` the agent only sends after asking), so splitting a request does not get around it. A
+  prompt the client declines on its own is not taken as the user's answer. Failed jobs are refunded and give the budget
+  back; the same request failing twice stops.
+- Effects are checked for frames cut by the canvas edge and empty frames; a bad ending can be redone from a frame.
+- Animations are judged for free after generation; the agent may improve one at most once on its own, then shows the
+  user.
+- Results come back as preview images, and exports come with a manifest (frame size, pivot, clips, ability timeline)
+  the agent can wire into code.
+
+Requires a SpriteHatch API key (Pro or Studio plan): app → avatar → **My account and statement** → **API keys**.
+
+## Local (stdio): files go straight into your game project
+
+```sh
+# Claude Code
+claude mcp add spritehatch -e SPRITEHATCH_API_KEY=sg_live_... -- uvx spritehatch-mcp
+```
+
+Other clients (Cursor, Windsurf, Codex…), in their MCP config:
+
+```json
+{
+  "mcpServers": {
+    "spritehatch": {
+      "command": "uvx",
+      "args": ["spritehatch-mcp"],
+      "env": { "SPRITEHATCH_API_KEY": "sg_live_..." }
+    }
+  }
+}
+```
+
+| Variable | Default | |
+|---|---|---|
+| `SPRITEHATCH_API_KEY` | — | Required. |
+| `SPRITEHATCH_BUDGET` | `300` | Credits this session may spend. |
+| `SPRITEHATCH_CONFIRM_ABOVE` | `60` | Single requests above this need the user's approval. `0` = always ask. |
+| `SPRITEHATCH_EXPORT_DIR` | `spritehatch-assets` | Where `export_asset` writes when no folder is given. |
+| `SPRITEHATCH_URL` | `https://spritehatch.com` | API address. |
+
+## Hosted (streamable HTTP): nothing to install
+
+```sh
+claude mcp add --transport http spritehatch https://spritehatch.com/mcp \
+  --header "Authorization: Bearer sg_live_..." --header "X-SpriteHatch-Budget: 300"
+```
+
+Optional headers: `X-SpriteHatch-Budget`, `X-SpriteHatch-Confirm-Above`. The hosted server cannot read or write the
+agent's disk: reference images go as https URLs or base64, and exports come back as 30-minute download links.
+
+Run it yourself: `spritehatch-mcp --http --host 0.0.0.0 --port 7870` with `SPRITEHATCH_URL` pointing at the API and
+`SPRITEHATCH_MCP_PUBLIC_URL` set to this server's public address (for the download links). Health check: `GET /health`.
+
+## Tools
+
+| Need | Tool |
+|---|---|
+| Not sure what to make | `spritehatch_guide` (free) |
+| Account, credits, session budget | `get_account` |
+| Projects and style kit (pixel art, height, 2/4/8 directions, palette) | `list_projects`, `setup_project` |
+| What already exists | `list_assets`, `get_asset`, `get_preview` |
+| New character/monster, from text or an image | `create_character`, `choose_candidate` |
+| Outfit, color, armor, elite version, rarity | `add_skin` |
+| Top-down / isometric views | `add_directions` |
+| Body animation (effects on the body included) | `plan_animation` (free) → `generate_animation`, `review_animation` (free), `improve_animation` |
+| Attack or power that emits something | charge animation + `create_vfx` (best control), or `create_ability` (automatic) |
+| Standalone effect, projectile, impact | `create_vfx`, `improve_vfx` |
+| Pick which kept version is used | `use_version` |
+| Item, weapon, prop, icon | `create_item` |
+| Buttons, bars, panels | `create_ui`, `add_ui_states` |
+| Side-scroller background | `create_scene`, `add_parallax_layers` |
+| Tilesets / maps | `create_tileset` |
+| Fix a detail | `edit_asset`, `apply_edit` |
+| Wait for generation | `wait_for_jobs` |
+| Take it to the game | `export_asset` |
+
+Resource `spritehatch://guide` has the full guide; prompts `make_game_character` and `add_attack_with_effect` start the
+two most common flows.
+
+## Development
+
+Tests live in the main repository: `.venv/bin/python scripts/check_mcp.py` runs the real API, queue, billing and
+exports with a simulated GPU, through both transports.

spritehatch_mcp-0.1.0/README.md

@@ -0,0 +1,100 @@
+# SpriteHatch MCP
+
+Lets AI agents (Claude Code, Cursor, Codex, Windsurf…) make 2D game assets with [SpriteHatch](https://spritehatch.com)
+and bring them into the game: characters, monsters, animations, abilities with separate effect layers, effects, items,
+UI, parallax scenes and tilesets, exported for Godot, Unity, GameMaker, RPG Maker or plain sprite sheets.
+
+The server teaches the agent which tool fits each need and guards the user's credits:
+
+- `spritehatch_guide` (free) turns a game need ("the dragon breathes fire at the player") into the right recipe, with
+  costs and pitfalls. The same decision rules are sent to the agent when it connects.
+- Quality, art style and image engine are the user's choice: when the request does not say, the tool returns the
+  options (with costs) for the agent to ask, or shows a form in clients that support it. Image engines are known only by
+  their product names.
+- Effects that stay on the body (a charge-up) are drawn into the character animation; what flies to a target becomes
+  separate effects the game moves. The animation plan is shown exactly as it will be generated (prompt, ending, beats)
+  and can be corrected before paying.
+- Session budget and approval: spending above the approval limit since the last approval asks the user (MCP elicitation,
+  or a one-time `confirm_token` the agent only sends after asking), so splitting a request does not get around it. A
+  prompt the client declines on its own is not taken as the user's answer. Failed jobs are refunded and give the budget
+  back; the same request failing twice stops.
+- Effects are checked for frames cut by the canvas edge and empty frames; a bad ending can be redone from a frame.
+- Animations are judged for free after generation; the agent may improve one at most once on its own, then shows the
+  user.
+- Results come back as preview images, and exports come with a manifest (frame size, pivot, clips, ability timeline)
+  the agent can wire into code.
+
+Requires a SpriteHatch API key (Pro or Studio plan): app → avatar → **My account and statement** → **API keys**.
+
+## Local (stdio): files go straight into your game project
+
+```sh
+# Claude Code
+claude mcp add spritehatch -e SPRITEHATCH_API_KEY=sg_live_... -- uvx spritehatch-mcp
+```
+
+Other clients (Cursor, Windsurf, Codex…), in their MCP config:
+
+```json
+{
+  "mcpServers": {
+    "spritehatch": {
+      "command": "uvx",
+      "args": ["spritehatch-mcp"],
+      "env": { "SPRITEHATCH_API_KEY": "sg_live_..." }
+    }
+  }
+}
+```
+
+| Variable | Default | |
+|---|---|---|
+| `SPRITEHATCH_API_KEY` | — | Required. |
+| `SPRITEHATCH_BUDGET` | `300` | Credits this session may spend. |
+| `SPRITEHATCH_CONFIRM_ABOVE` | `60` | Single requests above this need the user's approval. `0` = always ask. |
+| `SPRITEHATCH_EXPORT_DIR` | `spritehatch-assets` | Where `export_asset` writes when no folder is given. |
+| `SPRITEHATCH_URL` | `https://spritehatch.com` | API address. |
+
+## Hosted (streamable HTTP): nothing to install
+
+```sh
+claude mcp add --transport http spritehatch https://spritehatch.com/mcp \
+  --header "Authorization: Bearer sg_live_..." --header "X-SpriteHatch-Budget: 300"
+```
+
+Optional headers: `X-SpriteHatch-Budget`, `X-SpriteHatch-Confirm-Above`. The hosted server cannot read or write the
+agent's disk: reference images go as https URLs or base64, and exports come back as 30-minute download links.
+
+Run it yourself: `spritehatch-mcp --http --host 0.0.0.0 --port 7870` with `SPRITEHATCH_URL` pointing at the API and
+`SPRITEHATCH_MCP_PUBLIC_URL` set to this server's public address (for the download links). Health check: `GET /health`.
+
+## Tools
+
+| Need | Tool |
+|---|---|
+| Not sure what to make | `spritehatch_guide` (free) |
+| Account, credits, session budget | `get_account` |
+| Projects and style kit (pixel art, height, 2/4/8 directions, palette) | `list_projects`, `setup_project` |
+| What already exists | `list_assets`, `get_asset`, `get_preview` |
+| New character/monster, from text or an image | `create_character`, `choose_candidate` |
+| Outfit, color, armor, elite version, rarity | `add_skin` |
+| Top-down / isometric views | `add_directions` |
+| Body animation (effects on the body included) | `plan_animation` (free) → `generate_animation`, `review_animation` (free), `improve_animation` |
+| Attack or power that emits something | charge animation + `create_vfx` (best control), or `create_ability` (automatic) |
+| Standalone effect, projectile, impact | `create_vfx`, `improve_vfx` |
+| Pick which kept version is used | `use_version` |
+| Item, weapon, prop, icon | `create_item` |
+| Buttons, bars, panels | `create_ui`, `add_ui_states` |
+| Side-scroller background | `create_scene`, `add_parallax_layers` |
+| Tilesets / maps | `create_tileset` |
+| Fix a detail | `edit_asset`, `apply_edit` |
+| Wait for generation | `wait_for_jobs` |
+| Take it to the game | `export_asset` |
+
+Resource `spritehatch://guide` has the full guide; prompts `make_game_character` and `add_attack_with_effect` start the
+two most common flows.
+
+## Development
+
+Tests live in the main repository: `.venv/bin/python scripts/check_mcp.py` runs the real API, queue, billing and
+exports with a simulated GPU, through both transports.

spritehatch_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spritehatch-mcp"
+version = "0.1.0"
+description = "MCP server for SpriteHatch: AI agents generate 2D game sprites, animations, effects, items, UI, scenes and tilesets and export them for Godot, Unity, GameMaker and RPG Maker."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "SpriteHatch" }]
+requires-python = ">=3.11"
+dependencies = ["mcp>=2.3,<3", "pillow>=10"]
+keywords = ["mcp", "model-context-protocol", "ai-agents", "game-development", "sprites", "pixel-art", "animation", "gamedev"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Games/Entertainment",
+    "Topic :: Multimedia :: Graphics",
+]
+
+[project.urls]
+Homepage = "https://spritehatch.com"
+Documentation = "https://spritehatch.com/docs/mcp"
+
+[project.scripts]
+spritehatch-mcp = "spritehatch_mcp.__main__:main"
+
+[tool.setuptools]
+packages = ["spritehatch_mcp"]

spritehatch_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spritehatch_mcp-0.1.0/spritehatch_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""SpriteHatch MCP server: lets AI agents generate 2D game assets with SpriteHatch and bring them into the game."""
+__version__ = '0.1.0'

spritehatch_mcp-0.1.0/spritehatch_mcp/__main__.py

@@ -0,0 +1,26 @@
+"""spritehatch-mcp            → local server over stdio (Claude Code, Cursor, Codex…); needs SPRITEHATCH_API_KEY.
+spritehatch-mcp --http     → hosted server (streamable HTTP); each request brings its key in the Authorization header."""
+import argparse
+import os
+
+from .server import Config, build
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog='spritehatch-mcp', description='SpriteHatch MCP server')
+    parser.add_argument('--http', action='store_true', help='serve over streamable HTTP (hosted mode) instead of stdio')
+    parser.add_argument('--host', default=os.environ.get('SPRITEHATCH_MCP_HOST', '127.0.0.1'))
+    parser.add_argument('--port', type=int, default=int(os.environ.get('SPRITEHATCH_MCP_PORT', '7870')))
+    args = parser.parse_args()
+    if args.http:
+        config = Config.from_env('hosted')
+        build(config).run('streamable-http', host=args.host, port=args.port, streamable_http_path='/mcp')
+    else:
+        config = Config.from_env('local')
+        if not config.api_key:
+            parser.exit(2, 'SPRITEHATCH_API_KEY is not set. Create a key in SpriteHatch > My account > API keys.\n')
+        build(config).run('stdio')
+
+
+if __name__ == '__main__':
+    main()

spritehatch_mcp-0.1.0/spritehatch_mcp/api.py

@@ -0,0 +1,84 @@
+"""Async client for the SpriteHatch HTTP API (the same API documented at /docs/api).
+
+Every call carries the customer's API key (`Authorization: Bearer sg_live_…`), so ownership, plan limits (API = Pro and
+Studio) and credit charging stay where they already are: in the SpriteHatch server. This module only translates HTTP
+failures into errors an agent can act on.
+"""
+from __future__ import annotations
+
+import httpx2 as httpx   # the HTTP client the MCP SDK already ships (httpx fork)
+
+# HTTP status → stable code + what the agent should do. The server's `detail` text is still in Portuguese.
+ERRORS = {
+    0: ('unreachable', 'Could not reach SpriteHatch. Check SPRITEHATCH_URL and the network, then try again.'),
+    400: ('invalid_request', 'The request was rejected; fix the arguments described in `detail`.'),
+    401: ('invalid_api_key', 'The API key is missing, wrong or deleted. The user creates one in SpriteHatch > My account > '
+                             'API keys and sets SPRITEHATCH_API_KEY (local) or the Authorization header (hosted).'),
+    402: ('insufficient_credits', 'Not enough credits. Tell the user the cost and balance; do not retry.'),
+    403: ('not_allowed', 'The plan does not include the API/MCP (Pro and Studio do), or this action needs the web app.'),
+    404: ('not_found', 'The asset, project or job does not exist or belongs to another account. Use list_assets / list_projects.'),
+    409: ('busy_or_changed', 'The asset is not ready yet, another generation on the same animation is running, or the '
+                            'version changed. Call wait_for_jobs, then try again.'),
+    422: ('invalid_request', 'Some argument has the wrong type or is out of range.'),
+    502: ('upstream_error', 'A payment/upstream service failed. Try again later.'),
+    504: ('timeout', 'SpriteHatch took too long to answer. Try again; generation jobs keep running on the server.'),
+    503: ('service_unavailable', 'A SpriteHatch service (vision planner or judge) is temporarily unavailable. Try again later.'),
+}
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, detail: str):
+        self.status = status
+        self.detail = detail
+        self.code, self.hint = ERRORS.get(status, ('server_error', 'Unexpected server error. Try again later.'))
+        super().__init__(f'{self.code} ({status}): {detail}')
+
+    def as_dict(self) -> dict:
+        return {'error': self.code, 'status': self.status, 'detail': self.detail, 'what_to_do': self.hint}
+
+
+class Api:
+    def __init__(self, base_url: str, key: str, timeout: float = 60.0):
+        if not key:
+            raise ApiError(401, 'Nenhuma chave de API configurada.')
+        self.base_url = base_url.rstrip('/')
+        self._client = httpx.AsyncClient(base_url=self.base_url, timeout=timeout, follow_redirects=True,
+                                         headers={'Authorization': f'Bearer {key}', 'User-Agent': 'spritehatch-mcp'})
+
+    async def __aenter__(self) -> Api:
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self._client.aclose()
+
+    async def _send(self, method: str, path: str, **kwargs) -> httpx.Response:
+        try:
+            response = await self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException:
+            raise ApiError(504, 'O servidor demorou para responder.')
+        except httpx.HTTPError as error:
+            raise ApiError(0, f'Não foi possível falar com o SpriteHatch em {self.base_url}: {error}')
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get('detail')
+            except ValueError:
+                detail = None
+            if not isinstance(detail, str):
+                detail = str(detail or response.text[:300] or response.reason_phrase)
+            raise ApiError(response.status_code, detail)
+        return response
+
+    async def get(self, path: str, **params):
+        return (await self._send('GET', path, params={k: v for k, v in params.items() if v is not None})).json()
+
+    async def post(self, path: str, body: dict | None = None, *, data: dict | None = None, files: dict | None = None):
+        if files is not None:
+            return (await self._send('POST', path, data=data or {}, files=files)).json()
+        return (await self._send('POST', path, json=body or {})).json()
+
+    async def patch(self, path: str, body: dict):
+        return (await self._send('PATCH', path, json=body)).json()
+
+    async def get_bytes(self, path: str, **params) -> tuple[bytes, httpx.Headers]:
+        response = await self._send('GET', path, params={k: v for k, v in params.items() if v is not None})
+        return response.content, response.headers

spritehatch_mcp-0.1.0/spritehatch_mcp/files.py

@@ -0,0 +1,185 @@
+"""Files in and out: reference images the agent passes, and exports it takes home.
+
+Local (stdio) mode reads images from disk and unpacks exports into the game project. Hosted mode cannot touch the
+agent's disk, so it accepts URLs/base64 and serves each export from a short-lived link.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import io
+import ipaddress
+import json
+import re
+import secrets
+import socket
+import time
+import zipfile
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx2 as httpx   # the HTTP client the MCP SDK already ships (httpx fork)
+
+MAX_IMAGE = 15 * 1024 * 1024
+LINK_TTL = 30 * 60
+
+
+async def load_image(ref: str, allow_paths: bool) -> tuple[str, bytes]:
+    """`ref` is a local path (local mode only), an http(s) URL, a data URL or raw base64 → (filename, bytes)."""
+    ref = ref.strip()
+    if ref.startswith(('http://', 'https://')):
+        if not allow_paths:   # hosted: never fetch the server's own network (SSRF); redirects are checked hop by hop
+            await _public_only(ref)
+        async with httpx.AsyncClient(timeout=30, follow_redirects=allow_paths) as client:
+            response = await client.get(ref)
+            hops = 0
+            while not allow_paths and response.is_redirect and hops < 3:
+                ref = str(response.next_request.url) if response.next_request else ''
+                await _public_only(ref)
+                response = await client.get(ref)
+                hops += 1
+        if response.status_code >= 400:
+            raise ValueError(f'Could not download the reference image ({response.status_code}).')
+        data, name = response.content, Path(ref.split('?')[0]).name or 'reference.png'
+    elif ref.startswith('data:'):
+        data, name = _b64(ref.split(',', 1)[-1]), 'reference.png'
+    elif allow_paths and (Path(ref).expanduser().exists()):
+        path = Path(ref).expanduser()
+        data, name = path.read_bytes(), path.name
+    elif re.fullmatch(r'[A-Za-z0-9+/=\s]{200,}', ref):
+        data, name = _b64(ref), 'reference.png'
+    elif allow_paths:
+        raise ValueError(f'Reference image not found: {ref}')
+    else:
+        raise ValueError('The hosted server cannot read local files: pass the image as an https URL or base64/data URL.')
+    if len(data) > MAX_IMAGE:
+        raise ValueError('The reference image is larger than 15 MB.')
+    return name, data
+
+
+async def _public_only(url: str) -> None:
+    host = urlparse(url).hostname
+    if not host:
+        raise ValueError('Invalid image URL.')
+    try:
+        infos = await asyncio.get_running_loop().getaddrinfo(host, None)
+    except socket.gaierror:
+        raise ValueError(f'Could not resolve {host}.')
+    for info in infos:
+        address = ipaddress.ip_address(info[4][0])
+        if not address.is_global:
+            raise ValueError('The image URL must be a public address.')
+
+
+def _b64(text: str) -> bytes:
+    try:
+        return base64.b64decode(re.sub(r'\s+', '', text), validate=True)
+    except (binascii.Error, ValueError):
+        raise ValueError('The reference image is not valid base64.')
+
+
+def manifest(zip_bytes: bytes, target: str) -> dict:
+    """What the agent needs to wire the export into code, read from the files inside the zip."""
+    out: dict = {'files': [], 'clips': {}, 'notes': []}
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as archive:
+        names = [n for n in archive.namelist() if not n.endswith('/')]
+        out['files'] = names[:60] + ([f'... {len(names) - 60} more'] if len(names) > 60 else [])
+        for name in names:
+            if not name.endswith('.json'):
+                continue
+            try:
+                data = json.loads(archive.read(name))
+            except ValueError:
+                continue
+            if not isinstance(data, dict):
+                continue
+            meta = data.get('meta') if isinstance(data.get('meta'), dict) else None
+            if meta and 'clips' in meta:   # character atlas (TexturePacker hash + clips)
+                out['atlas'] = name
+                out['image'] = meta.get('image')
+                out['cell'] = meta.get('cell')
+                out['pixel_art'] = bool(meta.get('pixel'))
+                out['clips'] = {k: {f: v.get(f) for f in ('animation', 'direction', 'fps', 'loop', 'frames')}
+                                for k, v in meta['clips'].items()}
+            elif str(data.get('schema', '')).startswith('sprite-ability'):
+                out['ability'] = {k: data.get(k) for k in (
+                    'schema', 'name', 'mode', 'gesture', 'effects', 'anchors', 'release', 'speed', 'speed_units', 'effect_scale',
+                    'effect_scale_units', 'emission_lead_ms', 'emission_fade_ms', 'projectile_grow_ms', 'stream_duration_ms',
+                    'projectile_facing', 'anchor_space', 'target_height', 'cell') if data.get(k) is not None}
+                out['ability_file'] = name
+            elif 'frames' in data and 'blend' in data:   # standalone effect
+                out['effect'] = {k: data.get(k) for k in ('name', 'frame_size', 'fps', 'loop', 'blend', 'pivot')}
+                out['effect']['frame_count'] = len(data.get('frames') or [])
+            elif name.endswith('tiles.json') or 'tiles' in data:
+                out['tileset'] = {k: data.get(k) for k in ('tile', 'tile_size', 'mode', 'columns', 'order', 'bits') if k in data}
+            elif 'layers' in data:
+                out['scene'] = {'layers': data.get('layers')}
+        for doc in ('COMPOSITION.txt', 'README.txt', 'STREAM.txt'):
+            hit = next((n for n in names if n.endswith(doc)), None)
+            if hit:
+                out['notes'].append({'file': hit, 'text': archive.read(hit).decode('utf-8', 'replace')[:1800]})
+    out['how_to_use'] = HOW_TO.get(target, HOW_TO['atlas'])
+    if 'ability' in out:
+        out['how_to_use'] += ' ' + HOW_TO['ability']
+    return out
+
+
+HOW_TO = {
+    'godot': 'Godot 4: the .tres is a SpriteFrames resource; assign it to an AnimatedSprite2D and play("<animation>_<direction>"). '
+             'Offset the sprite so the pivot (cell.pivot, at the feet) sits on the node origin.',
+    'unity': 'Unity: copy the folder into Assets/. The Editor/SpriteGeneratorImporter.cs script slices the sheet with the foot '
+             'pivot and creates one AnimationClip per row (looping clips have loopTime on). Point filtering for pixel art.',
+    'gamemaker': 'GameMaker: import each spr_*_stripN.png with "Import Strip Image"; N is the frame count. Set the origin '
+                 'to the pivot from the atlas JSON.',
+    'rpgmaker': 'RPG Maker: copy $<name>.png into img/characters (3×4 walk sheet).',
+    'atlas': 'Generic: <name>.png + <name>.json (TexturePacker hash). meta.clips lists every animation_direction with fps, '
+             'loop and frame names; every frame has the same cell size and a normalized pivot at the feet.',
+    'strips': 'One horizontal PNG strip per animation_direction; frame width = cell.width.',
+    'frames': 'One PNG per frame, in folders per animation_direction.',
+    'gif': 'GIF previews only (not for the game).',
+    'ability': 'Ability: play the gesture; start the emission effect emission_lead_ms before gesture.release_frame at the '
+               'anchor for the current direction (normalized in the gesture cell); at the release frame spawn the '
+               'projectile (or stream) at effect_scale × target_height and move it at speed × target_height px/s facing '
+               'right (mirror for W); on hit play impact once. Collision and damage are game code. See COMPOSITION.txt.',
+}
+
+
+class LinkStore:
+    """Hosted mode: exports are kept in memory for 30 minutes behind an unguessable link."""
+
+    def __init__(self):
+        self._files: dict[str, tuple[str, bytes, float]] = {}
+
+    def put(self, filename: str, data: bytes) -> str:
+        now = time.time()
+        self._files = {k: v for k, v in self._files.items() if v[2] > now}
+        while sum(len(v[1]) for v in self._files.values()) + len(data) > 256 * 1024 * 1024 and self._files:
+            self._files.pop(next(iter(self._files)))
+        token = secrets.token_urlsafe(24)
+        self._files[token] = (filename, data, now + LINK_TTL)
+        return token
+
+    def get(self, token: str) -> tuple[str, bytes] | None:
+        item = self._files.get(token)
+        if not item or item[2] < time.time():
+            return None
+        return item[0], item[1]
+
+
+def unpack(zip_bytes: bytes, dest: Path) -> list[str]:
+    dest.mkdir(parents=True, exist_ok=True)
+    root = dest.resolve()
+    written = []
+    with zipfile.ZipFile(io.BytesIO(zip_bytes)) as archive:
+        for member in archive.infolist():
+            target = (dest / member.filename).resolve()
+            if not target.is_relative_to(root):   # zip slip
+                continue
+            if member.is_dir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(archive.read(member))
+            written.append(str(target))
+    return written