H5 宿主界面与事件

适用版本：v0.2.1。本页前置为已有 SDK 实例及自己的页面容器。@starlight/sdk 是无界面核心包：openCenter()、showFloating()、hideFloating() 只发送事件，不创建 DOM、样式、浮球或弹窗。

仓库 apps/playground 是 React 参考 UI，包含登录、侧边中心、浮球、钱包、订单和客服；安装 .tgz 不会安装或自动挂载该应用。若复用参考实现，需要处理你的宿主 CSS、画布输入、滚动、触摸和生命周期。

最小事件适配

以下为可运行的原生 DOM 适配示例，页面应先提供这些元素。它展示事件连接方式，不是完整登录、订单或支付页面。

<button id="platform-orb" type="button" hidden>账号中心</button>
<dialog id="platform-dialog" aria-labelledby="platform-title">
  <h2 id="platform-title">账号中心</h2>
  <p id="platform-content"></p>
  <button id="platform-close" type="button">关闭</button>
</dialog>
<p id="platform-error" role="status"></p>

import { sdk } from './sdk';

const orb = document.querySelector<HTMLButtonElement>('#platform-orb')!;
const dialog = document.querySelector<HTMLDialogElement>('#platform-dialog')!;
const content = document.querySelector<HTMLParagraphElement>('#platform-content')!;
const close = document.querySelector<HTMLButtonElement>('#platform-close')!;
const error = document.querySelector<HTMLParagraphElement>('#platform-error')!;
const openHome = () => sdk.openCenter('home');
const closePanel = () => dialog.close();

const dispose = [
  sdk.on('floating', visible => { orb.hidden = !visible; }),
  sdk.on('center', ({ view }) => {
    content.textContent = view === 'login'
      ? '请在宿主登录表单完成登录。'
      : sdk.getSession() ? '已登录，可读取平台中心数据。' : '请先登录。';
    if (!dialog.open) dialog.showModal();
  }),
  sdk.on('session', session => {
    if (!session) { content.textContent = ''; dialog.close(); }
  }),
  sdk.on('error', problem => { error.textContent = problem.message; }),
];
orb.addEventListener('click', openHome);
close.addEventListener('click', closePanel);
sdk.showFloating();

export function unmountPlatformUI() {
  dispose.forEach(unsubscribe => unsubscribe());
  orb.removeEventListener('click', openHome);
  close.removeEventListener('click', closePanel);
  orb.hidden = true;
  dialog.close();
}

预期：调用 showFloating() 显示宿主按钮；点击后打开宿主对话框；hideFloating() 隐藏按钮。没有订阅器时，这些方法不会产生可见效果。

请求、取消与界面状态

中心数据由 await sdk.center() 获取，不能把 center 事件视为数据已加载。显示加载/空列表/错误/重试状态，并在切号、页面关闭或组件卸载后丢弃旧渲染结果。SDK 会拦截旧认证请求覆盖新会话，但宿主自己的动画、异步渲染及游戏后端请求也要做生命周期校验。

关闭尚在登录中的表单时调用 sdk.cancelLogin()，再关闭表单。关闭普通中心不等于退出；只在用户明确退出时执行 logout()。不要因中心请求断网就清掉 token。

嵌入游戏时必须处理的行为

场景	宿主责任
全屏 canvas	弹窗打开时暂停游戏相关按键/触摸，关闭后恢复，避免点击穿透
iframe	决定 SDK/UI 所在层级；浮球不能自动越过 iframe；跨窗口消息校验 origin 和结构
手机浏览器	安全区、软键盘、横竖屏、地址栏变化、触摸拖动和滚动冲突
键盘与辅助功能	可聚焦入口、对话框标题、Tab 焦点、Escape 关闭和关闭后的焦点返回
主题/样式	对接已有页面命名空间，避免全局 reset 覆盖宿主；不能假设包内有主题 API
弱网与支付返回	显示处理中/查询中，先查询原订单，不用动画完成作为付款成功依据

当前没有已发布的通用可注入 H5 UI 包，没有已验收 Unity WebGL/Cocos 桥接。成功验收应来自实际目标游戏与浏览器。继续查看 会话策略 与 API 参考。

客服列表应保留 tickets() 返回的 nextCursor 并提供加载更多；不要只展示默认首批 50 条就当作全部历史。自定义页面重试支付/权益动作时保存本次 requestId，再调用支持可选 ID 的对应方法。