@hezzlgames/sdk 1.1.0

package/hezzl-sdk.js

@@ -0,0 +1,767 @@
+/**
+ * Hezzl Games SDK — договор игры с игровым центром.
+ *
+ * Один файл без зависимостей. Кладётся в папку игры и подключается
+ * до её кода:
+ *
+ *     <script src="hezzl-sdk.js"></script>
+ *
+ * С нашего домена его не подключают: игра обязана работать по прямой
+ * ссылке и без сети, а обращения на сторонние домены запрещены
+ * требованиями. Обновление SDK приезжает вместе с новой сборкой игры.
+ *
+ * Что он берёт на себя:
+ *   — разбор настроек из адреса;
+ *   — проверку источника сообщений и разговор с центром;
+ *   — рукопожатие и определение, есть ли центр рядом;
+ *   — хранилище: через центр, а без него — своё, с префиксом;
+ *   — дисциплину частоты сообщений;
+ *   — валюту центра: баланс, товары, покупку, списание и кошелёк;
+ *   — window.HezzlGame для игр на нашем домене.
+ *
+ * Полные требования — docs/GAME-REQUIREMENTS.md. Ссылки на разделы
+ * в комментариях ведут туда.
+ */
+(function (root) {
+  'use strict';
+
+  var SDK = 1;                                   /* версия протокола, раздел 3.2 */
+  var VERSION = '1.1.0';                         /* версия пакета @hezzlgames/sdk; растёт на каждый выпуск */
+  var ACK_WAIT = 700;                            /* сколько ждём ответа центра, 3.8 */
+  var BUDGET = 10;                               /* сообщений в секунду, 3.4 */
+  var SCORE_GAP = 1000;                          /* не чаще раза в секунду, 3.4 */
+
+  /* Команды, которые центр может прислать. Имена — из таблицы 3.1
+     и ниоткуда больше: синонимов у них нет. */
+  var COMMANDS = ['mute', 'haptics', 'pause', 'resume', 'restart',
+                  'setlang', 'settheme', 'setaccent'];
+
+  /* Сообщения центра, которые командами не являются: он их шлёт сам,
+     а не в ответ, и в supports игры они не попадают (3.1). */
+  /* signincancelled — ответ на signin, когда человек закрыл экран, так
+     и не войдя. Без него молчание центра неотличимо от «ещё думает»,
+     и игра остаётся с кнопкой ожидания, которая никогда не погаснет. */
+  var NOTICES = ['signedin', 'signedout', 'signincancelled', 'profile',
+                 'balance', 'walletclosed'];
+
+  /* Просьбы, на которые центр отвечает сообщением того же имени (3.8).
+     Ответ узнаётся по rid; без rid — как ответ на последнюю просьбу
+     того же типа. balance и wallet центр шлёт и сам, без просьбы:
+     тогда это уведомление, и оно уходит в обработчик игры. */
+  var ANSWERED = ['auth', 'profile', 'balance', 'goods', 'buy', 'spend', 'wallet'];
+
+  /* Сколько ждём ответа. Обычная просьба — пять секунд. Денежная —
+     дольше: центр ходит на сервер, а потом ещё и разговаривает
+     с человеком. На время разговора срок снимается вовсе (hold). */
+  var ASK_WAIT = 5000;
+  var MONEY_WAIT = 30000;
+
+  /* Соответствие имени умения методу window.HezzlGame. Выводится
+     по правилу «то же имя в camelCase», кроме двух случаев: звук
+     и вибрация названы по предмету, а методы у них сеттеры. */
+  var METHOD = {
+    mute: 'setMuted', haptics: 'setHaptics',
+    pause: 'pause', resume: 'resume', restart: 'restart',
+    setlang: 'setLang', settheme: 'setTheme', setaccent: 'setAccent'
+  };
+
+  var game = null;                               /* что игра сказала о себе в init */
+  var handlers = {};                             /* её обработчики */
+  var listeners = {};                            /* подписки через Hezzl.on */
+  var centre = null;                             /* окно центра, если мы в кадре */
+  var mode = 'unknown';                          /* unknown | centre | standalone */
+  var centreCan = [];                            /* что умеет центр, из ack */
+  var started = false;                           /* звали ли ready */
+  var waiting = [];                              /* команды, пришедшие до готовности */
+  var pending = {};                              /* просьбы, ждущие ответа, по rid */
+  var afterMode = [];                            /* что отложено до определения режима */
+  var purse = null;                              /* последнее известное о валюте центра, 7.9 */
+  var debug = false;
+
+  /* ── мелочи ──────────────────────────────────────────────────────── */
+
+  function has(list, one) {
+    for (var i = 0; i < list.length; i++) if (list[i] === one) return true;
+    return false;
+  }
+
+  function note() {
+    /* В собранной игре отладочного вывода быть не должно (раздел 38):
+       консоль в кадре общая с центром. Включается только явно. */
+    if (!debug || !root.console || !console.info) return;
+    try { console.info.apply(console, ['[hezzl-sdk]'].concat([].slice.call(arguments))); } catch (e) {}
+  }
+
+  function warn(what) {
+    if (!root.console || !console.warn) return;
+    try { console.warn('[hezzl-sdk] ' + what); } catch (e) {}
+  }
+
+  function rid() {
+    return 'r' + Math.random().toString(36).slice(2, 10);
+  }
+
+  /* ── настройки из адреса ─────────────────────────────────────────── */
+
+  /* Отсутствие параметра — осмысленный ответ, а не упущение (раздел 2):
+     человек оставил настройку на «Системе». Поэтому пустая строка,
+     а не подставленное значение по умолчанию. */
+  function fromUrl() {
+    var q = {};
+    try {
+      var raw = root.location.search.replace(/^\?/, '').split('&');
+      for (var i = 0; i < raw.length; i++) {
+        var pair = raw[i].split('=');
+        if (!pair[0]) continue;
+        q[decodeURIComponent(pair[0]).toLowerCase()] = decodeURIComponent((pair[1] || '').replace(/\+/g, ' '));
+      }
+    } catch (e) {}
+
+    var lang = q.lang === 'ru' || q.lang === 'en' ? q.lang : '';
+    var theme = q.theme === 'light' || q.theme === 'dark' ? q.theme : '';
+    var accent = /^[0-9a-f]{6}$/i.test(q.accent || '') ? q.accent.toLowerCase() : '';
+    /* Метка партнёра уходит в базу игры и в отчёт по комиссии (раздел 2).
+       Это ровно тот путь, по которому в отчёт попадает чужой текст, —
+       проверяем маской до того, как отдать игре. */
+    var ref = /^[A-Za-z0-9_-]{1,32}$/.test(q.ref || '') ? q.ref : '';
+
+    return {
+      lang: lang,
+      theme: theme,
+      accent: accent,
+      muted: q.muted === '1',
+      haptics: q.haptics === '0' ? false : true,
+      ref: ref
+    };
+  }
+
+  var settings = fromUrl();
+
+  /* ── отправка ────────────────────────────────────────────────────── */
+
+  /* Ведро на десять сообщений в секунду (3.4). Игра, шлющая событие
+     на каждый ход в каскаде, создаёт очередь, которую центр разгребает
+     между кадрами; лишнее отбрасываем здесь, а не там. */
+  var spent = [];
+
+  function affordable() {
+    var now = Date.now();
+    while (spent.length && now - spent[0] > 1000) spent.shift();
+    if (spent.length >= BUDGET) return false;
+    spent.push(now);
+    return true;
+  }
+
+  function post(type, payload, extra) {
+    if (!centre) return false;
+    var msg = {
+      source: 'hezzl-game',
+      sdk: SDK,
+      game: game ? game.id : '',
+      version: game ? game.version : '',
+      type: type,
+      payload: payload || {}
+    };
+    if (extra) for (var key in extra) if (extra.hasOwnProperty(key)) msg[key] = extra[key];
+    try {
+      /* Адрес получателя не сужаем: центр бывает и на нашем домене,
+         и внутри страницы партнёра (3.2). Поэтому в сообщениях нет
+         ничего личного — только про игру. */
+      centre.postMessage(msg, '*');
+      note('->', type, payload);
+      return true;
+    } catch (e) { return false; }
+  }
+
+  function send(type, payload, extra) {
+    if (!affordable()) { note('пропущено по лимиту:', type); return false; }
+    return post(type, payload, extra);
+  }
+
+  /* ── счёт ────────────────────────────────────────────────────────── */
+
+  var lastScoreAt = 0;
+  var heldScore = null;
+  var scoreTimer = null;
+
+  function flushScore() {
+    if (scoreTimer) { clearTimeout(scoreTimer); scoreTimer = null; }
+    if (!heldScore) return;
+    lastScoreAt = Date.now();
+    send('score', heldScore);
+    heldScore = null;
+  }
+
+  /* ── приём ───────────────────────────────────────────────────────── */
+
+  function dispatch(name, data) {
+    var fn = handlers[name];
+    var subs = listeners[name] || [];
+    var value = valueOf(name, data);
+    if (fn) { try { fn(value, data); } catch (e) { warn('обработчик ' + name + ' упал: ' + e); } }
+    for (var i = 0; i < subs.length; i++) {
+      try { subs[i](value, data); } catch (e) { warn('подписка ' + name + ' упала: ' + e); }
+    }
+  }
+
+  /* Первым доводом отдаём то, ради чего команду и прислали: флаг,
+     язык, цвет. Целое сообщение остаётся вторым — на случай полей,
+     которых сегодня нет. */
+  function valueOf(name, data) {
+    if (name === 'mute') return !!data.muted;
+    if (name === 'haptics') return !!data.enabled;
+    if (name === 'setlang') return data.lang;
+    if (name === 'settheme') return data.theme;
+    if (name === 'setaccent') return data.accent;
+    if (name === 'signedin') return data.userId;
+    if (name === 'profile') return data.profile || null;
+    if (name === 'balance' || name === 'walletclosed') {
+      return typeof data.amount === 'number' ? data.amount : null;
+    }
+    return undefined;
+  }
+
+  function handle(name, data) {
+    /* Неизвестный тип игнорируется молча (3.3): протокол будет расти,
+       и игра, падающая на незнакомом сообщении, сломается на следующем
+       обновлении центра. */
+    if (name === 'ack') { settle(data); return; }
+
+    if (has(ANSWERED, name)) { answer(name, data); return; }
+
+    if (name === 'storage') { storageAnswer(data); return; }
+
+    if (!has(COMMANDS, name) && !has(NOTICES, name)) return;
+
+    /* Команда может прийти раньше, чем игра готова (3.3). Складываем
+       в очередь: молча терять нельзя. */
+    if (!started) { waiting.push([name, data]); return; }
+    dispatch(name, data);
+  }
+
+  /* Ответ на просьбу. Сначала — кому он адресован, потом — что в нём
+     нового для всех: баланс мог измениться, кошелёк мог закрыться. */
+  function answer(name, data) {
+    var wait = data.rid ? pending[data.rid] : lastPending(name);
+
+    if (wait && data.hold) {
+      /* Центр занят разговором с человеком: подтверждает списание,
+         показал кошелёк, поднял вход. Срок ожидания снимаем — ответ
+         придёт, когда человек решит, а решает он не за пять секунд. */
+      if (wait.timer) { clearTimeout(wait.timer); wait.timer = null; }
+      wait.hold = data.hold;
+      note('центр держит', name, 'по причине', data.hold);
+      return;
+    }
+
+    var changed = remember(data);
+
+    if (wait) {
+      delete pending[wait.rid];
+      if (wait.timer) clearTimeout(wait.timer);
+      if (data.ok === false) wait.reject(refuseWith(data));
+      else wait.resolve(data);
+    }
+
+    /* Ответа никто не ждал — значит центр прислал сам: человек
+       вошёл, переименовался или сменил картинку (7.8); пополнил
+       баланс в кошельке или получил награду за задание (7.9). */
+    if (name === 'profile') notify('profile', data);
+    if (name === 'wallet') notify('walletclosed', data);
+    if (name === 'balance' ? (!wait || changed) : changed) notify('balance', data);
+  }
+
+  /* Уведомление может прийти раньше готовности, как и команда (3.3):
+     складываем, не теряем. */
+  function notify(name, data) {
+    if (!started) { waiting.push([name, data]); return; }
+    dispatch(name, data);
+  }
+
+  /* Что известно о валюте центра: ключ, название, значок — из ack;
+     сумма — из каждого ответа, где она есть. Возвращает, изменилась
+     ли сумма: по этому игра получает уведомление balance один раз,
+     а не на каждое сообщение. */
+  function remember(data) {
+    if (!data) return false;
+    var before = purse ? purse.amount : null;
+    if (data.currency && typeof data.currency === 'object') {
+      purse = purse || { amount: null };
+      for (var key in data.currency) {
+        if (data.currency.hasOwnProperty(key) && key !== 'amount') purse[key] = data.currency[key];
+      }
+    }
+    if (typeof data.amount === 'number') {
+      purse = purse || {};
+      purse.amount = data.amount;
+    }
+    return !!purse && purse.amount !== before;
+  }
+
+  function lastPending(type) {
+    /* Ответ без rid обрабатывается как ответ на последнюю просьбу того
+       же типа (3.8). */
+    var found = null;
+    for (var key in pending) {
+      if (!pending.hasOwnProperty(key)) continue;
+      if (pending[key].type === type && (!found || pending[key].at > found.at)) found = pending[key];
+    }
+    return found;
+  }
+
+  /* Вне браузера — сборка, тесты, серверный рендер — слушать нечего:
+     пакет должен импортироваться, а не падать на первой строке. */
+  if (typeof root.addEventListener === 'function') root.addEventListener('message', function (event) {
+    /* Две проверки, и первая обязательна отдельно от второй (3.2).
+       Условие «parent !== window && source !== parent» при прямом заходе
+       вырождается в false и пропускает любое сообщение от любого скрипта
+       на странице — то есть защита отключается ровно там, ради чего
+       писалась. */
+    if (root.parent === root) return;
+    if (event.source !== root.parent) return;
+
+    var data = event.data;
+    if (!data || typeof data.type !== 'string') return;
+    if (data.type.indexOf('hezzl:') !== 0) return;
+    note('<-', data.type, data);
+    handle(data.type.slice(6), data);
+  });
+
+  /* ── рукопожатие ─────────────────────────────────────────────────── */
+
+  var ackTimer = null;
+
+  function settle(data) {
+    if (mode !== 'unknown') return;
+    if (ackTimer) { clearTimeout(ackTimer); ackTimer = null; }
+    mode = 'centre';
+    centreCan = (data && data.centreSupports) || [];
+    /* Валюта центра описывается в рукопожатии (7.9): игра рисует
+       значок и название до первого обращения за балансом. */
+    if (data) remember({ currency: data.currency });
+    note('центр рядом, умеет:', centreCan.join(', '));
+    drain();
+  }
+
+  function alone(why) {
+    if (mode !== 'unknown') return;
+    if (ackTimer) { clearTimeout(ackTimer); ackTimer = null; }
+    mode = 'standalone';
+    centre = null;
+    centreCan = [];
+    note('центра рядом нет:', why);
+    drain();
+  }
+
+  function drain() {
+    var queue = afterMode;
+    afterMode = [];
+    for (var i = 0; i < queue.length; i++) queue[i]();
+  }
+
+  /* ── хранилище ───────────────────────────────────────────────────── */
+
+  /* Отказ типизирован (7.6): игра ветвится по reason, а не по разбору
+     строки. Значения ровно четыре. */
+  function refuse(reason, why) {
+    var error = new Error(why || reason);
+    error.reason = reason;
+    return error;
+  }
+
+  /* Отказ центра по денежной просьбе: причина в error, рядом — сколько
+     на балансе и сколько не хватило, чтобы игра сказала человеку
+     число, а не «недостаточно». */
+  function refuseWith(data) {
+    var error = refuse(data.error || 'unknown', data.message);
+    if (typeof data.amount === 'number') error.amount = data.amount;
+    if (typeof data.need === 'number') error.need = data.need;
+    return error;
+  }
+
+  function prefix() {
+    return 'hezzl.' + (game && game.id ? game.id : 'game') + '.';
+  }
+
+  function local() {
+    try {
+      var probe = root.localStorage;
+      probe.setItem('hezzl.probe', '1');
+      probe.removeItem('hezzl.probe');
+      return probe;
+    } catch (e) { return null; }
+  }
+
+  function quotaish(e) {
+    /* У переполнения разные имена в разных браузерах, а у Safari
+       в приватном режиме — свой код. Отличать его от прочих отказов
+       обязательно: на квоту игра отвечает освобождением места, а на
+       недоступность — сообщением человеку. */
+    if (!e) return false;
+    return e.name === 'QuotaExceededError'
+        || e.name === 'NS_ERROR_DOM_QUOTA_REACHED'
+        || e.code === 22 || e.code === 1014;
+  }
+
+  var storeWaiting = {};                         /* запросы к центру, по rid */
+
+  function storageAnswer(data) {
+    var wait = data.rid && storeWaiting[data.rid];
+    if (!wait) return;
+    delete storeWaiting[data.rid];
+    if (data.error) wait.reject(refuse(data.error, data.message));
+    else wait.resolve(data.value === undefined ? null : data.value);
+  }
+
+  function viaCentre(op, key, value, opts) {
+    return new Promise(function (resolve, reject) {
+      var id = rid();
+      storeWaiting[id] = { resolve: resolve, reject: reject };
+      var payload = { op: op, key: key };
+      if (value !== undefined) payload.value = value;
+      if (opts) {
+        payload.sync = !!opts.sync;
+        if (opts.schema !== undefined) payload.schema = opts.schema;
+      }
+      if (!post('storage', payload, { rid: id })) {
+        delete storeWaiting[id];
+        reject(refuse('unavailable', 'центр не принял запрос'));
+        return;
+      }
+      /* Ответа может не быть — центр старой версии или ушёл. Ждать
+         вечно нельзя: игра держит на этом промисе загрузку прогресса. */
+      setTimeout(function () {
+        if (!storeWaiting[id]) return;
+        delete storeWaiting[id];
+        reject(refuse('unknown', 'центр не ответил'));
+      }, 5000);
+    });
+  }
+
+  function viaLocal(op, key, value) {
+    return new Promise(function (resolve, reject) {
+      var box = local();
+      if (!box) { reject(refuse('unavailable', 'хранилище недоступно')); return; }
+      var full = prefix() + key;
+      try {
+        if (op === 'get') {
+          var raw = box.getItem(full);
+          resolve(raw === null ? null : JSON.parse(raw));
+        } else if (op === 'set') {
+          box.setItem(full, JSON.stringify(value));
+          resolve();
+        } else if (op === 'remove') {
+          box.removeItem(full);
+          resolve();
+        } else if (op === 'keys') {
+          var out = [], mark = prefix();
+          for (var i = 0; i < box.length; i++) {
+            var name = box.key(i);
+            if (name && name.indexOf(mark) === 0) out.push(name.slice(mark.length));
+          }
+          resolve(out);
+        }
+      } catch (e) {
+        if (quotaish(e)) reject(refuse('quota', 'место кончилось'));
+        else if (e instanceof SyntaxError) reject(refuse('invalid', 'сохранение повреждено'));
+        else reject(refuse('unknown', String(e && e.message || e)));
+      }
+    });
+  }
+
+  function storage(op, key, value, opts) {
+    if (op !== 'keys' && (typeof key !== 'string' || !key)) {
+      return Promise.reject(refuse('invalid', 'ключ должен быть непустой строкой'));
+    }
+    /* До рукопожатия хранилище уже работает (7.2): вызовы копятся
+       и разрешаются, как только известен режим. Игра не ждёт ack,
+       чтобы прочитать прогресс, — иначе первые 700 мс уходят
+       в ожидание, а бюджет первого кадра их не предусматривает. */
+    if (mode === 'unknown') {
+      return new Promise(function (resolve, reject) {
+        afterMode.push(function () {
+          storage(op, key, value, opts).then(resolve, reject);
+        });
+      });
+    }
+    if (mode === 'centre' && has(centreCan, 'storage')) return viaCentre(op, key, value, opts);
+    return viaLocal(op, key, value);
+  }
+
+  /* ── window.HezzlGame ────────────────────────────────────────────── */
+
+  /* Для игр на нашем домене центр проверяет умение свойством, не
+     дожидаясь рукопожатия (3.7). Имена методов — из таблицы 3.1. */
+  function expose() {
+    /* sdk в объекте — не украшение. По нему центр отличает игру,
+       собранную на этой библиотеке, от игры со своим объектом того же
+       имени: у Hezzl Merge, например, HezzlGame есть, а ready она
+       не шлёт, и ждать его от неё нельзя. */
+    var api = { sdk: SDK, id: game.id, version: game.version, supports: supports() };
+    for (var i = 0; i < COMMANDS.length; i++) {
+      var name = COMMANDS[i];
+      if (!handlers[name]) continue;
+      api[METHOD[name]] = (function (which) {
+        return function (arg) {
+          var data = {};
+          if (which === 'mute') data.muted = !!arg;
+          else if (which === 'haptics') data.enabled = !!arg;
+          else if (which === 'setlang') data.lang = arg;
+          else if (which === 'settheme') data.theme = arg;
+          else if (which === 'setaccent') data.accent = arg;
+          dispatch(which, data);
+        };
+      })(name);
+    }
+    root.HezzlGame = api;
+  }
+
+  /* Умения выводим из того, что игра действительно обрабатывает.
+     Объявить mute и не реализовать его нельзя по построению —
+     а это самое частое расхождение между манифестом и поведением. */
+  function supports() {
+    var out = [];
+    for (var i = 0; i < COMMANDS.length; i++) {
+      if (handlers[COMMANDS[i]]) out.push(COMMANDS[i]);
+    }
+    return out;
+  }
+
+  /* ── просьбы ─────────────────────────────────────────────────────── */
+
+  function ask(type, payload, money) {
+    return new Promise(function (resolve, reject) {
+      if (mode === 'standalone') { reject(refuse('unavailable', 'центра рядом нет')); return; }
+      var id = rid();
+      var wait = { rid: id, type: type, at: Date.now(), resolve: resolve, reject: reject, timer: null, hold: '' };
+      pending[id] = wait;
+      /* Денежные просьбы идут мимо ведра (3.4): человек нажал «купить»,
+         и потерять это нажатие из-за всплеска score — худший размен.
+         От злоупотребления защищает не ведро, а подтверждение
+         в центре (7.9). */
+      if (!(money ? post : send)(type, payload, { rid: id })) {
+        delete pending[id];
+        reject(refuse('unavailable', 'сообщение не ушло'));
+        return;
+      }
+      wait.timer = setTimeout(function () {
+        if (!pending[id]) return;
+        delete pending[id];
+        reject(refuse('unknown', 'центр не ответил'));
+      }, money ? MONEY_WAIT : ASK_WAIT);
+    });
+  }
+
+  /* ── валюта центра ───────────────────────────────────────────────── */
+
+  /* Денежная просьба (7.9). До рукопожатия откладывается, как
+     хранилище: игра вправе спросить баланс сразу после init. Центр
+     без валюты отказывает сразу и типизированно — кнопку магазина
+     игра при этом не показывает вовсе, см. can('balance'). */
+  function ledger(type, payload) {
+    if (mode === 'unknown') {
+      return new Promise(function (resolve, reject) {
+        afterMode.push(function () { ledger(type, payload).then(resolve, reject); });
+      });
+    }
+    if (mode === 'centre' && !has(centreCan, 'balance')) {
+      return Promise.reject(refuse('unavailable', 'у центра нет валюты'));
+    }
+    return ask(type, payload, true);
+  }
+
+  function wholeNumber(value) {
+    return typeof value === 'number' && isFinite(value) && value > 0 && Math.floor(value) === value;
+  }
+
+  function goodKey(value) {
+    if (wholeNumber(value)) return value;
+    if (typeof value === 'string' && /^[A-Za-z0-9_.-]{1,64}$/.test(value)) return value;
+    return null;
+  }
+
+  /* ── наружу ──────────────────────────────────────────────────────── */
+
+  var Hezzl = {
+    sdk: SDK,
+    version: VERSION,
+    settings: settings,
+
+    /**
+     * Рассказать о себе. Зовётся один раз, до ready.
+     *   id, version   — как в манифесте hezzl.json
+     *   modes         — ключи из реестра 20.1
+     *   orientation   — portrait | landscape | any
+     *   on            — обработчики команд центра
+     */
+    init: function (about) {
+      if (game) { warn('init уже был'); return Hezzl; }
+      about = about || {};
+      if (!about.id) warn('не задан id игры — он нужен в каждом сообщении и в префиксе хранилища');
+      game = {
+        id: about.id || '',
+        version: about.version || '0.0.0',
+        modes: about.modes || [],
+        orientation: about.orientation || 'any'
+      };
+      debug = !!about.debug;
+      var on = about.on || {};
+      for (var name in on) {
+        if (on.hasOwnProperty(name) && typeof on[name] === 'function') handlers[name] = on[name];
+      }
+
+      centre = root.parent && root.parent !== root ? root.parent : null;
+      if (!centre) alone('открыты напрямую');
+      expose();
+      return Hezzl;
+    },
+
+    /** Игра приняла ввод. После этого центр гасит заставку (раздел 5). */
+    ready: function (extra) {
+      if (started) return Hezzl;
+      if (!game) { warn('ready до init'); return Hezzl; }
+      started = true;
+
+      var payload = {
+        supports: supports(),
+        modes: game.modes,
+        lang: settings.lang || '',
+        orientation: game.orientation,
+        sdkVersion: VERSION                    /* какой пакет собран в игру — видно в статистике */
+      };
+      if (extra) for (var key in extra) if (extra.hasOwnProperty(key)) payload[key] = extra[key];
+      send('ready', payload);
+
+      if (centre && mode === 'unknown') {
+        /* Ответа нет за 700 мс — считаем, что центра рядом нет либо он
+           старой версии (3.8). Игра при этом уже работает: ждать
+           рукопожатия, чтобы принимать ввод, нельзя. */
+        ackTimer = setTimeout(function () { alone('ack не пришёл'); }, ACK_WAIT);
+      }
+
+      var queue = waiting;
+      waiting = [];
+      for (var i = 0; i < queue.length; i++) dispatch(queue[i][0], queue[i][1]);
+      return Hezzl;
+    },
+
+    /** centre | standalone | unknown */
+    mode: function () { return mode; },
+
+    /** Умеет ли центр это: share, support, exit, auth, profile, storage, balance. */
+    can: function (what) { return mode === 'centre' && has(centreCan, what); },
+
+    /** Подписка на команду центра сверх той, что задана в init.on. */
+    on: function (name, fn) {
+      (listeners[name] = listeners[name] || []).push(fn);
+      return Hezzl;
+    },
+
+    /**
+     * Порядок настройки: адрес → своя сохранённая → определение
+     * по браузеру (раздел 2). Пишется в каждой игре и в каждой
+     * ошибается, поэтому лежит здесь.
+     */
+    resolve: function (name, saved, fallback) {
+      if (settings[name]) return settings[name];
+      if (saved) return saved;
+      return typeof fallback === 'function' ? fallback() : fallback;
+    },
+
+    /* события, раздел 3.4 */
+    gameStart: function (about) { send('game_start', about || {}); },
+    milestone: function (what, value) { send('milestone', { what: what, value: value }); },
+    levelComplete: function (about) { send('level_complete', about || {}); },
+    levelFailed: function (about) { send('level_failed', about || {}); },
+
+    score: function (value, about) {
+      var payload = { score: value };
+      if (about) for (var key in about) if (about.hasOwnProperty(key)) payload[key] = about[key];
+      heldScore = payload;
+      var since = Date.now() - lastScoreAt;
+      if (since >= SCORE_GAP) { flushScore(); return; }
+      /* Не чаще раза в секунду, но и не терять последнее: держим
+         значение и отправляем хвостом. */
+      if (!scoreTimer) scoreTimer = setTimeout(flushScore, SCORE_GAP - since);
+    },
+
+    gameOver: function (about) {
+      /* Финальный счёт — исключение из ограничения частоты (3.4).
+         Иначе центр покажет предпоследний результат, а человек свой
+         настоящий, и разойдутся они на самом заметном для него числе. */
+      flushScore();
+      send('gameover', about || {});
+    },
+
+    /* просьбы, раздел 3.5 */
+    share: function (about) { send('share', about || {}); },
+    support: function (about) { send('support', about || {}); },
+    exit: function () { send('exit', {}); },
+    signin: function () { send('signin', {}); },
+    auth: function () { return ask('auth', {}); },
+    profile: function (need) { return ask('profile', { need: need || ['name', 'avatar'] }); },
+
+    error: function (code, message, fatal) {
+      /* Отказы шлём мимо ведра: они редки, и потерять их из-за
+         всплеска обычных событий — худший размен. */
+      post('error', { code: code, message: message || '', fatal: !!fatal });
+    },
+
+    /* валюта центра, раздел 7.9 */
+
+    /** Последнее известное о валюте: { key, title, icon, amount } или null. */
+    currency: function () { return purse; },
+
+    /** Сколько у человека валюты центра. Ответ: { signedIn, amount, currency }. */
+    balance: function () { return ledger('balance', {}); },
+
+    /** Товары этой игры с ценами, как они заведены у нас. Ответ: { goods: [...] }. */
+    goods: function () { return ledger('goods', {}); },
+
+    /**
+     * Купить товар из нашего каталога за валюту центра (кейс с сервером).
+     * Центр сам спросит подтверждение и сам покажет кошелёк, если
+     * не хватает; опция wallet: false отменяет второе.
+     * Ответ: { goodId, amount, award, issued }; отказ — по reason.
+     */
+    buy: function (goodId, opts) {
+      var key = goodKey(goodId);
+      if (key === null) return Promise.reject(refuse('invalid', 'goodId — целое число или короткая строка'));
+      opts = opts || {};
+      return ledger('buy', { goodId: key, wallet: opts.wallet !== false });
+    },
+
+    /**
+     * Списать валюту центра за то, что игра выдаёт сама (кейс без
+     * сервера). item — что куплено, для подтверждения и отчёта.
+     * Ответ: { amount, spent }; отказ — по reason.
+     */
+    spend: function (amount, opts) {
+      if (!wholeNumber(amount)) return Promise.reject(refuse('invalid', 'amount — целое число больше нуля'));
+      opts = opts || {};
+      var payload = { amount: amount, item: typeof opts.item === 'string' ? opts.item.slice(0, 80) : '', wallet: opts.wallet !== false };
+      return ledger('spend', payload);
+    },
+
+    /**
+     * Открыть кошелёк центра: где взять валюту. Разрешается, когда
+     * человек его закроет: { amount, bought }.
+     */
+    wallet: function (opts) {
+      opts = opts || {};
+      var payload = {};
+      if (wholeNumber(opts.need)) payload.need = opts.need;
+      if (typeof opts.reason === 'string') payload.reason = opts.reason.slice(0, 80);
+      return ledger('wallet', payload);
+    },
+
+    storage: {
+      get: function (key) { return storage('get', key); },
+      set: function (key, value, opts) { return storage('set', key, value, opts); },
+      remove: function (key) { return storage('remove', key); },
+      keys: function () { return storage('keys'); }
+    }
+  };
+
+  root.Hezzl = Hezzl;
+})(typeof globalThis !== 'undefined' ? globalThis : this);