@hexah/skin-sdk 0.2.0

package/LICENSE

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

@@ -0,0 +1,47 @@
+# @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 **host** w runtime (docelowo przez Module Federation; lokalnie w
+repo: `frontend/common/skin-sdk/{runtime,ui,slots}.js`).
+
+## Instalacja
+
+```bash
+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
+
+```js
+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`.
+
+Read-modele/usługi (`useReports`, `useSnackbar`, `useDialog`, `useShard`…), prymitywy UI
+(`PageBox`, `HexahChip`, `DataList`…) i `useSlots()` paczka udostępnia jako **typowane atrapy**
+(`runtime-stubs.js`) — 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.
+
+## Wersjonowanie
+
+`SKIN_API_VERSION` (semver): **major** = zmiana łamiąca powierzchnię, **minor** = dodanie
+zgodne wstecz, **patch** = bez zmiany powierzchni.
+
+## Dokumentacja
+
+- Przewodnik dewelopera skórek: `docs/skin-sdk/README.md`
+- Reguły: `docs/skin-sdk/SKIN_SDK_AI_RULES.md`
+- Granica publiczne/prywatne: `docs/skin-sdk/inventory-publicznego-api.md`

package/index.js

@@ -0,0 +1,117 @@
+"use strict";
+
+/**
+ * @hexah/skin-sdk — KONTRAKT (publiczne, wersjonowane API skórek)
+ *
+ * Jedyne źródło prawdy powierzchni, na której deweloperzy skórek budują własne podstrony,
+ * BEZ dostępu do kodu gry. Tu żyją wyłącznie stałe i typy (JSDoc) — zero implementacji,
+ * zero importów z aplikacji. Implementacje read-modeli/usług/prymitywów dostarcza host
+ * w runtime (in-repo: `frontend/common/skin-sdk/{runtime,ui,slots}.js`; docelowo przez
+ * Module Federation). Pakiet jest czystym CJS (interop z ESM frontu i `require` serwera),
+ * bez Reacta i bez kroku budowania.
+ *
+ * Granica publiczne/prywatne: patrz docs/skin-sdk/inventory-publicznego-api.md (sekcja F)
+ * oraz docs/skin-sdk/SKIN_SDK_AI_RULES.md.
+ */
+
+/**
+ * Wersja kontraktu SDK. Skórka deklaruje, na jakiej wersji działa; host odrzuca niezgodny
+ * major. Bump: major = zmiana łamiąca powierzchnię, minor = dodanie zgodne wstecz,
+ * patch = bez zmiany powierzchni.
+ */
+const SKIN_API_VERSION = "0.2.0";
+
+/** Domyślny szablon, gdy motyw nie ma własnego wariantu wizualnego. */
+const DEFAULT_TEMPLATE = "medieval";
+
+/**
+ * Klucze ekranów, pod które szablon (skórka) dostarcza komponenty prezentacyjne.
+ * Musi pokrywać się z `frontend/common/templates/templateResolution.js` — pilnuje tego
+ * test dryfu (`frontend/tests/unit/skinSdkPackageDrift.test.js`).
+ */
+const SCREEN_KEYS = Object.freeze({
+  ARTICLE: "article",
+  KURIER: "kurier",
+  KURIER_REDAKCJA: "kurierRedakcja",
+  KURIER_SKRZYNKA: "kurierSkrzynka",
+  GPT_LIST: "gptList",
+  GPT_THREAD: "gptThread",
+  REPORT: "report",
+  REPORT_DETAIL: "reportDetail",
+  ARTICLE_DETAIL: "articleDetail",
+});
+
+/**
+ * Klucze slotów — fragmenty z logiką/danymi renderowane przez HOST. Skórka dostaje je
+ * jako gotowe komponenty (przez `useSlots()`) i tylko rozmieszcza; nie ma dostępu do
+ * ich wnętrza ani do kodu gry.
+ * @see docs/skin-sdk/inventory-publicznego-api.md sekcja F (b)
+ */
+const SLOT_KEYS = Object.freeze({
+  GAME_PAGE: "gamePage",
+  ISSUE_RICH_CONTENT: "issueRichContent",
+  ISSUE_STATS: "issueStats",
+  ARTICLE_COMMENTS: "articleComments",
+  WORLD_MAP: "worldMap",
+  ARTICLE_ISSUE_GRID: "articleIssueGrid",
+});
+
+/**
+ * @typedef {object} ReportListItem — wiersz listy zgłoszeń (read-model, bez wewnętrznych pól).
+ * @property {number} id
+ * @property {number} issueNumber
+ * @property {string} title
+ * @property {'open'|'closed'} state
+ * @property {string|null} issueType
+ * @property {boolean} isNew
+ * @property {boolean} hasNewComments
+ * @property {boolean} plannedForImplementation
+ * @property {number} voteScore
+ * @property {number} commentsCount
+ * @property {number} subscribersCount
+ * @property {string} githubCreatedAt
+ * @property {{ user?: { username?: string, documentId?: string } }} [shardUser]
+ * @property {string} [githubAuthor]
+ */
+
+/**
+ * @typedef {object} ReportListView — filtry/widok listy zgłoszeń.
+ * @property {number} [page]
+ * @property {string} [search]
+ * @property {'all'|'open'|'closed'} [state]
+ * @property {'all'|'Bug'|'Feature'|'Pytanie'} [type]
+ * @property {boolean} [mine]
+ * @property {boolean} [planned]
+ */
+
+/**
+ * @typedef {object} Pagination
+ * @property {number} page
+ * @property {number} pageSize
+ * @property {number} total
+ * @property {number} pageCount
+ */
+
+/**
+ * @typedef {object} ReportListResult
+ * @property {ReportListItem[]} issues
+ * @property {Pagination} pagination
+ */
+
+/**
+ * Kontrakt propsów ekranu skórki (komponent zarejestrowany pod `SCREEN_KEYS`).
+ * Sloty (gotowe komponenty hosta) przychodzą w `slots`.
+ * @typedef {object} SkinScreenProps
+ * @property {Record<string, import('react').ComponentType<object>>} [slots]
+ */
+
+// Typowane atrapy runtime (hooki/UI/sloty/utile) — implementacje dostarcza host w runtime.
+const runtimeStubs = require("./runtime-stubs");
+
+module.exports = {
+  SKIN_API_VERSION,
+  DEFAULT_TEMPLATE,
+  SCREEN_KEYS,
+  SLOT_KEYS,
+  ...runtimeStubs,
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hexah/skin-sdk",
+  "version": "0.2.0",
+  "description": "Publiczny, wersjonowany kontrakt SDK skórek Hexah (stałe + typy). Implementacje dostarcza host w runtime.",
+  "main": "index.js",
+  "types": "index.js",
+  "license": "MIT",
+  "author": "Hexah Team <kontakt@hexah.pl>",
+  "homepage": "https://github.com/Kroniki-Fallathanu/hexah/tree/develop/packages/skin-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kroniki-Fallathanu/hexah.git",
+    "directory": "packages/skin-sdk"
+  },
+  "keywords": [
+    "hexah",
+    "skin",
+    "sdk",
+    "module-federation"
+  ],
+  "files": [
+    "index.js",
+    "runtime-stubs.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/runtime-stubs.js

@@ -0,0 +1,142 @@
+"use strict";
+
+/**
+ * @hexah/skin-sdk — STUBY RUNTIME (typy dla deweloperów skórek)
+ *
+ * Hooki, prymitywy UI i sloty NIE są implementowane w paczce — dostarcza je HOST w runtime
+ * przez Module Federation (shareScope, klucz `@hexah/skin-sdk` → barrel `@/common/skin-sdk`).
+ * Tu żyją wyłącznie **typowane atrapy**: dają deweloperowi skórki podpowiedzi w edytorze i
+ * pozwalają zbudować skórkę względem stabilnej powierzchni. Atrapa wywołana POZA hostem rzuca
+ * jasny błąd (skórka działa tylko wewnątrz hosta). Bundler skórki dzieli te paczki z
+ * `import: false`, więc atrapy nigdy nie trafiają do bundla — w runtime używana jest
+ * implementacja hosta.
+ *
+ * Zgodność tej powierzchni z barrelem hosta pilnuje test dryfu
+ * (`frontend/tests/unit/skinSdkPackageDrift.test.js`).
+ */
+
+/**
+ * Tworzy typowaną atrapę „dostarczane przez host". Wywołanie poza hostem rzuca.
+ * @param {string} name
+ * @returns {(...args: unknown[]) => never}
+ */
+function hostProvided(name) {
+  return function hostProvidedStub() {
+    throw new Error(
+      `@hexah/skin-sdk: „${name}" dostarcza host w runtime (Module Federation). ` +
+        `Nie wywołuj/nie renderuj go poza hostem — skórka działa wyłącznie wewnątrz aplikacji Hexah.`,
+    );
+  };
+}
+
+/* ---------- Read-modele (host) ---------- */
+/** @returns {object|null} Aktywny shard (świat). */
+const useShard = hostProvided("useShard");
+/** @returns {object|null} Shard-user (konto na shardzie). */
+const useShardUser = hostProvided("useShardUser");
+/** @returns {object|null} Aktywna postać. */
+const useCharacter = hostProvided("useCharacter");
+/** @returns {object|null} Konto gracza. */
+const useAccount = hostProvided("useAccount");
+/** @returns {object|null} Dane strony (powłoka). */
+const usePageData = hostProvided("usePageData");
+/** @returns {Array} Postacie online na shardzie. */
+const useOnlineCharacters = hostProvided("useOnlineCharacters");
+
+/* ---------- Usługi platformy (host) ---------- */
+/** @returns {{ notify: (messages: Array<{severity:string,message:string}>) => void }} */
+const useSnackbar = hostProvided("useSnackbar");
+/** @returns {{ open: (config: object) => void, close: () => void }} */
+const useDialog = hostProvided("useDialog");
+/**
+ * @returns {{
+ *   list: (data: import('./index').ReportListView & { pageSize?: number, callback: (r:any)=>void }) => void,
+ *   markAllRead: (callback: (r:any)=>void) => void,
+ *   setIssueNotification: (next: boolean, callback: (r:any)=>void) => void,
+ * }}
+ */
+const useReports = hostProvided("useReports");
+/** @param {{ title?: string }} shell Ustawia tytuł/powłokę strony. @returns {void} */
+const useGamePageShell = hostProvided("useGamePageShell");
+
+/* ---------- Sloty (host) ---------- */
+/** Provider slotów hosta (host montuje go sam; skórka go nie używa). */
+const SlotsProvider = hostProvided("SlotsProvider");
+/** @returns {Record<string, import('react').ComponentType<object>>} Mapa slotów hosta. */
+const useSlots = hostProvided("useSlots");
+
+/* ---------- Prymitywy UI (host) ---------- */
+/** @type {import('react').ComponentType<object>} */
+const PageBox = hostProvided("PageBox");
+/** @type {import('react').ComponentType<object>} */
+const HexahCharacterSection = hostProvided("HexahCharacterSection");
+/** @type {import('react').ComponentType<object>} */
+const AngularPanel = hostProvided("AngularPanel");
+/** @type {import('react').ComponentType<object>} */
+const StandardButton = hostProvided("StandardButton");
+/** @type {import('react').ComponentType<object>} */
+const RoundAvatar = hostProvided("RoundAvatar");
+/** @type {import('react').ComponentType<object>} */
+const DataList = hostProvided("DataList");
+/** @type {import('react').ComponentType<object>} */
+const HexahChip = hostProvided("HexahChip");
+/** @type {import('react').ComponentType<object>} */
+const HexahPagination = hostProvided("HexahPagination");
+/** @type {import('react').ComponentType<object>} */
+const HexahPaginationItem = hostProvided("HexahPaginationItem");
+
+/* ---------- Nawigacja / utile (host) ---------- */
+/** @returns {string} */
+const buildReportListHref = hostProvided("buildReportListHref");
+/** @returns {string} */
+const buildReportDetailHref = hostProvided("buildReportDetailHref");
+/** @returns {string} */
+const buildReportBackHref = hostProvided("buildReportBackHref");
+/** @returns {number} */
+const parseReportListPage = hostProvided("parseReportListPage");
+/** @returns {'all'|'open'|'closed'} */
+const parseReportStateFilter = hostProvided("parseReportStateFilter");
+/** @returns {string} */
+const parseReportTypeFilter = hostProvided("parseReportTypeFilter");
+/** @returns {boolean} */
+const parseReportMineFilter = hostProvided("parseReportMineFilter");
+/** @returns {boolean} */
+const parseReportPlannedFilter = hostProvided("parseReportPlannedFilter");
+/** @returns {object} sx dla chipa stanu zgłoszenia */
+const getStateChipSx = hostProvided("getStateChipSx");
+/** @returns {object} sx dla chipa typu zgłoszenia */
+const getIssueTypeChipSx = hostProvided("getIssueTypeChipSx");
+
+module.exports = {
+  useShard,
+  useShardUser,
+  useCharacter,
+  useAccount,
+  usePageData,
+  useOnlineCharacters,
+  useSnackbar,
+  useDialog,
+  useReports,
+  useGamePageShell,
+  SlotsProvider,
+  useSlots,
+  PageBox,
+  HexahCharacterSection,
+  AngularPanel,
+  StandardButton,
+  RoundAvatar,
+  DataList,
+  HexahChip,
+  HexahPagination,
+  HexahPaginationItem,
+  buildReportListHref,
+  buildReportDetailHref,
+  buildReportBackHref,
+  parseReportListPage,
+  parseReportStateFilter,
+  parseReportTypeFilter,
+  parseReportMineFilter,
+  parseReportPlannedFilter,
+  getStateChipSx,
+  getIssueTypeChipSx,
+};