@hexah/skin-sdk

Publiczny, wersjonowany kontrakt SDK skórek Hexah — stałe i typy, na których deweloperzy budują własne podstrony (ekrany szablonu) i motywy, bez dostępu do kodu gry.

Pakiet jest celowo „chudy": zawiera wyłącznie kontrakt (zero implementacji, zero importów z aplikacji, brak Reacta i kroku budowania). Implementacje read-modeli, usług platformy i prymitywów UI dostarcza aplikacja-host w runtime przez Module Federation (shareScope).

Instalacja

npm install --save-dev @hexah/skin-sdk
# peer-y dostarcza host w runtime; instalujesz je u siebie do builda/typowania:
npm install react react-dom jotai next @mui/material @mui/icons-material

Co dostajesz

import { SCREEN_KEYS, SLOT_KEYS, DEFAULT_TEMPLATE, SKIN_API_VERSION } from '@hexah/skin-sdk'

• SCREEN_KEYS — klucze ekranów, pod które rejestrujesz komponenty skórki.
• SLOT_KEYS — klucze slotów (ciężkie fragmenty renderowane przez hosta; rozmieszczasz je).
• DEFAULT_TEMPLATE — szablon bazowy (fallback).
• SKIN_API_VERSION — wersja kontraktu, którą deklaruje skórka (host odrzuca niezgodny major).
• Typy JSDoc: ReportListItem, ReportListView, ReportListResult, Pagination, SkinScreenProps.

Hooki danych (per strona gry)

| Strona | Hook | | --- | --- | | Aktualności / Kurier | useArticles | | Harold (GPT) | useGptThreads | | Operacje | useTales | | Metropolia | useTown | | Frakcje | useGuild | | Kolonie | useVillages | | Zgłoszenia | useReports | | Konfiguracja | useSettings | | Zaopatrzenie | useShop | | Profil | useAccountProfile |

Stan i usługi

Read-modele stanu: useShard, useShardUser, useCharacter, useAccount, usePageData, useOnlineCharacters. Usługi: useSnackbar, useDialog, useGamePageShell. Sloty hosta: useSlots() + SLOT_KEYS. Prymitywy UI: PageBox, HexahChip, DataList, HexahPagination, AngularPanel, StandardButton, RoundAvatar, HexahCharacterSection.

Wszystko paczka udostępnia jako typowane atrapy — dają podpowiedzi w edytorze, a realne implementacje dostarcza host w runtime (Module Federation, shareScope). Atrapa wywołana poza hostem rzuca jasny błąd: skórka działa wyłącznie wewnątrz aplikacji Hexah. Bundler skórki dzieli te paczki z import: false, więc atrapy nigdy nie trafiają do bundla.

Tworzenie skórki

Najszybciej wystartujesz przez scaffolder:

npm create @hexah/skin moja-skorka     # albo: npx @hexah/create-skin moja-skorka

Wygenerowany projekt zawiera gotowy build (rspack + Module Federation), przykładowy ekran i instrukcję podłączenia do środowiska testowego Hexah.

Wersjonowanie

SKIN_API_VERSION (semver): major = zmiana łamiąca powierzchnię, minor = dodanie zgodne wstecz, patch = bez zmiany powierzchni. Skórka deklaruje wersję w configu; host odrzuca niezgodny major.