gamekit777 0.1.6 → 0.1.8

package/dev-host/DevShell.svelte

@@ -6,13 +6,17 @@
      默认服务端是本地表模型：浏览器里就地建表、按权重抽行、restore 还原——
      和真平台同一条路，restore 契约违反在这里就会被拦下。
 
-     机台的样子和玩家站点的对局页是同一份：同一套类名（.cab / .panel-col / .stage / .bar），
-     样式全部来自共享的 theme.css，舞台也是同一块 900×771 的逻辑画面整体缩放。
+     机台的样子和玩家站点的对局页是同一份：同一套类名（.cab / .panel-col / .stage / .bar，
+     手机是 .cab.mobile / .hud-top / .hud-bottom / .sheet），样式全部来自共享的 theme.css，
+     舞台也是同一块逻辑画面整体缩放（桌面 900×771，手机 450×H）。
      只有游戏的挂载方式不同——那边是 sandbox iframe，这边直接挂进 .gameframe 这个 div。
+     .stage > .gameframe 不进任何 {#if}：切布局只换它的兄弟节点，游戏实例不重挂。
      开发专用的东西（历史、校验、公平证、赔率、定点复现）放在机台下面，不挤进机台里。 */
   import { onMount } from 'svelte';
-  import { STAGE_H, STAGE_W, type GameInstance, type GameModule } from '../sdk/index.ts';
-  import { preloadGame } from '../runtime/index.ts';
+  import { NO_INSETS, STAGE_H, STAGE_W, safeInsetsOf, type GameInstance, type GameModule, type StageFit, type StageLayout } from '../sdk/index.ts';
+  import { createLoadMeter, preloadGame } from '../runtime/index.ts';
+  import { fade } from 'svelte/transition';
+  import { observeStage } from './layout.ts';
   import { createPlatform, type HistoryEntry, type PlatformOf } from './platform.svelte.ts';
   import type { PlatformServer } from './platform-server.ts';
   import type { LocalServer } from './local.ts';
@@ -20,7 +24,7 @@
   import SchemaFields from './SchemaFields.svelte';
   import Field from './Field.svelte';
 
-  let { game, title, note, embedded = false, server, onSaveCase, onPlatform }: {
+  let { game, title, note, embedded = false, server, onSaveCase, onPlatform, layout = 'desktop', simSafe }: {
     game: GameModule<C, O>;
     title?: string;
     note?: string;
@@ -32,19 +36,29 @@
     onSaveCase?: (h: HistoryEntry, title: string) => Promise<string>;
     /** 平台实例建好了交出去。studio 的总线要拿它驱动预览（MCP 的 preview_* 工具） */
     onPlatform?: (p: PlatformOf<C, O>) => void;
+    /** 初始布局。之后由 p.setLayout 切 */
+    layout?: StageLayout;
+    /** 模拟真机的刘海 / home 指示条（屏幕像素）。iframe 里 env(safe-area-inset-*) 恒为 0，studio 预览靠这个模拟 */
+    simSafe?: { top: number; bottom: number };
   } = $props();
 
   /* 只取初始值是故意的：一个平台实例对应一个游戏，换游戏应当整个重挂
      （外面用 {#key game} 包住），而不是让平台在运行中换掉脚下的逻辑 */
   // svelte-ignore state_referenced_locally
-  const p = createPlatform<C, O>(game, server);
+  const p = createPlatform<C, O>(game, server, { layout });
   setPlatform(p);
   // svelte-ignore state_referenced_locally
   onPlatform?.(p);
 
   let stage = $state<HTMLElement>();
   let frame = $state<HTMLElement>();
+  let hudTop = $state<HTMLElement>();
+  let hudBottom = $state<HTMLElement>();
+  let probe = $state<HTMLElement>();
+  let betDlg = $state<HTMLDialogElement>();
+  let menuDlg = $state<HTMLDialogElement>();
   let inst = $state<GameInstance<O> | null>(null);
+  const mobile = $derived(p.layout === 'mobile');
   // svelte-ignore state_referenced_locally
   let betText = $state((p.bet / 100).toFixed(2));
   let tab = $state<'history' | 'fair' | 'proof' | 'pay' | 'skins' | 'replay'>('history');
@@ -60,33 +74,92 @@
   const local = $derived(p.server as Partial<LocalServer<C, O>>);
   const tableStats = $derived(p.tableMode ? local.table?.(p.tableMode)?.stats ?? null : null);
 
+  /* 遮罩比就绪多留一拍，让 100% 真的被看见再淡出；outro 期间块内更新会被暂停，所以不能靠 phase 直接切 */
+  let veil = $state(true);
+  $effect(() => {
+    if (p.game.phase === 'loading') return;
+    const t = setTimeout(() => { veil = false; }, 220);
+    return () => clearTimeout(t);
+  });
+
+  /* 舞台 + 安全区 → 游戏。fit 由 observeStage 给，HUD 的高度自己量；
+     两者任一变化都重发一次，setStage 去重，真变了才叫游戏 resize() */
+  let lastFit: StageFit | null = null;
+  const publishStage = (): void => {
+    if (!lastFit || !frame) return;
+    /* 安全区 = HUD 的遮挡（其 padding 已含系统安全区 / 模拟刘海）+ 左右的系统安全区（探针读 env） */
+    const cs = probe ? getComputedStyle(probe) : null;
+    const safe = lastFit.layout === 'mobile'
+      ? safeInsetsOf(lastFit, {
+          top: hudTop?.offsetHeight ?? 0, bottom: hudBottom?.offsetHeight ?? 0,
+          left: cs ? parseFloat(cs.paddingLeft) || 0 : 0, right: cs ? parseFloat(cs.paddingRight) || 0 : 0,
+        })
+      : NO_INSETS;
+    const changed = p.setStage({ layout: lastFit.layout, width: lastFit.width, height: lastFit.height, safe });
+    frame.dataset.layout = lastFit.layout;
+    frame.style.setProperty('--gk-safe-top', `${safe.top}px`);
+    frame.style.setProperty('--gk-safe-right', `${safe.right}px`);
+    frame.style.setProperty('--gk-safe-bottom', `${safe.bottom}px`);
+    frame.style.setProperty('--gk-safe-left', `${safe.left}px`);
+    if (changed) inst?.resize();
+  };
+  /* HUD 只在手机布局里存在，元素换了观察器跟着换 */
+  $effect(() => {
+    const els = [hudTop, hudBottom].filter((e): e is HTMLElement => !!e);
+    const ro = new ResizeObserver(publishStage);
+    for (const e of els) ro.observe(e);
+    addEventListener('resize', publishStage);
+    publishStage();
+    return () => { ro.disconnect(); removeEventListener('resize', publishStage); };
+  });
+  $effect(() => {
+    if (!betDlg) return;
+    if (betOpen && !betDlg.open) betDlg.showModal();
+    else if (!betOpen && betDlg.open) betDlg.close();
+  });
+  $effect(() => {
+    if (!menuDlg) return;
+    if (menuOpen && !menuDlg.open) menuDlg.showModal();
+    else if (!menuOpen && menuDlg.open) menuDlg.close();
+  });
+  let betOpen = $state(false);
+  let menuOpen = $state(false);
+  const toggleAuto = (): void => { menuOpen = false; if (p.autoActive) p.stopAuto(); else void p.startAuto(); };
+
   onMount(() => {
     let live = true;
     let off: (() => void) | undefined;
     let handle: GameInstance<O> | undefined;
 
-    /* 和玩家站点的 GameFrame 同一条缩放规则：容器 CSS 尺寸恒为 STAGE_W×STAGE_H，
-       按舞台宽度算一个倍率。舞台自己是黄金比例，高度自然对得上。
-       观察的是舞台而不是窗口：机台在窄屏下会重排，同样的窗口宽度可能对应两种舞台宽度 */
-    const fit = (): void => {
-      const w = stage?.clientWidth ?? 0;
-      if (frame && w > 0) frame.style.transform = `scale(${w / STAGE_W})`;
-    };
-    const ro = new ResizeObserver(fit);
-    ro.observe(stage!);
-    fit();
+    /* 和玩家站点的 GameFrame 同一条缩放规则（dev-host 的 observeStage）：容器 CSS 尺寸恒为逻辑分辨率，
+       桌面按舞台宽算倍率，手机两个方向都看。第一次 fit 同步发生在这里，早于下面的 mount，
+       所以游戏 mount 时 host.stage 已经是对的 */
+    const fitter = observeStage({
+      stage: stage!, frame: frame!, layout: () => p.layout,
+      onFit: (f) => { lastFit = f; publishStage(); },
+    });
 
     void (async () => {
       // 先和服务端握手：余额、种子承诺、注额区间都在那边
       await p.init();
       /* 资源在平台这一侧预加载：进度画在机台上，游戏的 mount 假定 critical 已到齐。
          图片句柄挂在 pre 上活到卸载——opaque origin 下没有落盘缓存，这份就是唯一一份 */
-      const pre = await preloadGame(game.assets, { onProgress: (x) => p.setLoadProgress(x.ratio) });
-      if (!live) return;
-      const i = await game.mount(p.host(), frame!);
-      if (!live) { i.destroy(); return; }
+      const meter = createLoadMeter({ onChange: (r) => p.setLoadProgress(r) });
+      let i: GameInstance<O>;
+      try {
+        const pre = await Promise.race([preloadGame(game.assets, { onProgress: (x) => meter.real(x.ratio) }), meter.timeout()]);
+        if (!live) return;
+        i = await Promise.race([game.mount(p.host(), frame!), meter.timeout()]);
+        if (!live) { i.destroy(); return; }
+        pre.prefetchLazy();
+      } catch (e) {
+        p.err = e instanceof Error ? e.message : String(e);
+        return;
+      } finally {
+        meter.stop();
+      }
+      p.setLoadProgress(1);
       handle = i; inst = i;
-      pre.prefetchLazy();
       off = i.status.subscribe(s => p.setGameStatus(s));
       p.bindGame({ present: (r, rate) => i.present(r, rate ? { rate } : undefined), status: () => p.game });
     })();
@@ -105,7 +178,7 @@
 
     return () => {
       live = false;
-      ro.disconnect();
+      fitter.dispose();
       document.removeEventListener('keydown', onKey);
       off?.();
       handle?.destroy();
@@ -133,8 +206,8 @@
   };
 </script>
 
-<div class="shell" class:embedded>
-  {#if !embedded}
+<div class="shell" class:embedded class:mobile>
+  {#if !embedded && !mobile}
     <header class="top">
       <span class="brand big">GameKit</span>
       <span class="dim small">参考平台</span>
@@ -148,7 +221,8 @@
     </div>
   {/if}
 
-  <div class="cab" data-mode={p.mode}>
+  <div class="cab" class:mobile data-mode={p.mode}>
+    {#if !mobile}
     <!-- 左：下注与参数 -->
     <section class="panel-col">
       <div class="panel-inner">
@@ -179,75 +253,111 @@
                    onchange={e => { p.autoRounds = Math.max(0, parseInt(e.currentTarget.value, 10) || 0);
                                     e.currentTarget.value = String(p.autoRounds); }} />
           </Field>
-          <button class="cta cash" type="button" disabled={!p.ready0 || !p.spec.autoplay}
-                  onclick={() => p.autoActive ? p.stopAuto() : p.startAuto()}>
-            {#if p.autoActive}停止<span class="n">（{p.autoLeft}）</span>{:else if p.spec.autoplay}开始自动{:else}这个游戏不支持自动{/if}
-          </button>
-        {:else if p.game.busy}
-          <button class="cta" type="button" disabled={!p.game.canSkip} onclick={() => inst?.skip()}>
-            {p.game.canSkip ? '直接看结果' : '进行中'}
-          </button>
-        {:else}
-          <button class="cta" type="button" disabled={!p.canBet} onclick={() => p.playOne()}>
-            下注 <span class="n">{money(p.bet)}</span>
-          </button>
         {/if}
+        {@render cta()}
 
         {#if p.err}<p class="err small">{p.err}</p>{/if}
 
         <hr />
         <!-- 只有这一块滚：注额和下注按钮得一直够得着，参数再多也不该把它们顶出视野 -->
         <div class="params">
-          <SchemaFields />
-          {#each p.issues as i (i.field)}
-            <p class="bad small">{Object.values(i.message)[0]}</p>
-          {/each}
-          {#if p.tableMode}
-            <p class="hint">表 <span class="mono">{p.tableMode}</span>{#if tableStats} · 实算 RTP {(tableStats.computedRtpPpm / 1e4).toFixed(2)}% · 命中 {(tableStats.hitRatePpm / 1e4).toFixed(2)}% · 最大 {(tableStats.maxPayoutCenti / 100).toFixed(2)}x{:else if !p.remote} · 第一注时就地建表{/if}</p>
-          {/if}
+          {@render params()}
         </div>
       </div>
     </section>
+    {/if}
 
-    <!-- 右：游戏画布。容器尺寸恒为逻辑分辨率，onMount 里按舞台宽度整体缩放 -->
-    <section class="stage" style="--ratio:{STAGE_W}/{STAGE_H}" bind:this={stage}>
+    <!-- 游戏画布。容器尺寸恒为逻辑分辨率，observeStage 按布局整体缩放。不进 {#if}：切布局不重挂游戏 -->
+    <section class="stage" class:ready={!veil} style="--ratio:{STAGE_W}/{STAGE_H}" bind:this={stage}>
       <div class="gameframe" bind:this={frame} style="width:{STAGE_W}px;height:{STAGE_H}px"></div>
-      {#if p.game.phase === 'loading'}
-        <div class="loading">
-          <p>{p.loadProgress === null ? '正在装载游戏…' : `加载资源… ${Math.round(p.loadProgress * 100)}%`}</p>
-          {#if p.loadProgress !== null}<span class="loadbar"><i style="width:{p.loadProgress * 100}%"></i></span>{/if}
+      {#if veil}
+        <div class="loading" out:fade={{ duration: 180 }}>
+          <p>加载资源… {Math.round(p.loadProgress * 100)}%</p>
+          <span class="loadbar"><i style="width:{p.loadProgress * 100}%"></i></span>
         </div>
       {/if}
     </section>
 
+    {#if !mobile}
     <!-- 底：全机台的设置条 -->
     <footer class="bar">
       <div class="tg">
-        <button type="button" aria-pressed={p.view.turbo}
-                onclick={() => p.setView({ turbo: !p.view.turbo })}>
-          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M13 2 4 14h7l-1 8 9-12h-7z" /></svg>
-          快速模式
-        </button>
-        <button type="button" aria-pressed={p.view.sound}
-                onclick={() => p.setView({ sound: !p.view.sound })}>
-          {#if p.view.sound}
-            <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 9v6h4l5 4V5L8 9zM17 8a5 5 0 0 1 0 8" /></svg>
-          {:else}
-            <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 9v6h4l5 4V5L8 9zM17 10l4 4M21 10l-4 4" /></svg>
-          {/if}
-          音效
-        </button>
-        <label class="seed">客户端种子
-          <input bind:value={p.clientSeed} disabled={p.autoActive} /></label>
-        {#if p.server.refill}
-          <button type="button" onclick={() => p.refill()}>重置余额</button>
-        {/if}
+        {@render toggles()}
       </div>
       <span class="brand">GameKit</span>
     </footer>
+    {:else}
+    <!-- 手机：HUD 叠在画布上下两端，被盖住的部分经 host.stage.safe 告诉游戏。
+         底栏和玩家站点同一副样子：假输入框 / 圆形下注键 / 设置齿轮 -->
+    <i class="sysprobe" bind:this={probe} aria-hidden="true"></i>
+    <div class="hud hud-top" bind:this={hudTop} style:padding-top={simSafe ? `${simSafe.top + 8}px` : undefined}>
+      <span class="grow"></span>
+      <span class="bal">{money(p.balance)}</span>
+    </div>
+    <div class="hud hud-bottom" class:away={p.game.busy && !p.autoActive} bind:this={hudBottom} style:padding-bottom={simSafe ? `${simSafe.bottom + 12}px` : undefined}>
+      {#if p.err}<p class="err small">{p.err}</p>{/if}
+      <div class="hud-bar">
+        <button type="button" class="fakeinp" aria-label="注额" disabled={!p.canBet} onclick={() => betOpen = true}>
+          <span class="coin" aria-hidden="true"></span>
+          <b>{money(p.bet)}</b>
+          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 20h4L18 10l-4-4L4 16z" /></svg>
+        </button>
+        {#if p.autoActive}
+          <button type="button" class="playbtn stop" aria-label="停止自动" onclick={() => p.stopAuto()}><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="6" y="6" width="12" height="12" rx="2" /></svg></button>
+        {:else if p.game.busy}
+          <button type="button" class="playbtn" aria-label="直接看结果" disabled={!p.game.canSkip} onclick={() => inst?.skip()}><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M5 5v14l9-7zM16 5h3v14h-3z" /></svg></button>
+        {:else}
+          <button type="button" class="playbtn" aria-label="下注" disabled={!p.canBet} onclick={() => p.playOne()}><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M8 5v14l11-7z" /></svg></button>
+        {/if}
+        <button type="button" class="gearbtn" aria-label="设置" onclick={() => menuOpen = true}>
+          <svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="3" /><path d="M12 2v3M12 19v3M2 12h3M19 12h3M4.9 4.9l2.1 2.1M17 17l2.1 2.1M4.9 19.1L7 17M17 7l2.1-2.1" /></svg>
+        </button>
+      </div>
+    </div>
+
+    <dialog class="sheet" bind:this={betDlg} onclose={() => betOpen = false}>
+      <h3>注额</h3>
+      <div class="body">
+        <div class="inp">
+          <span class="coin" aria-hidden="true"></span>
+          <input aria-label="注额" inputmode="decimal" bind:value={betText} onchange={commitBet} disabled={!p.canBet} />
+          <button type="button" aria-label="减半" disabled={!p.canBet} onclick={() => scaleBet(0.5)}>½</button>
+          <button type="button" aria-label="加倍" disabled={!p.canBet} onclick={() => scaleBet(2)}>2×</button>
+        </div>
+        <p class="hint">区间 {money(p.limits.min)}–{money(p.limits.max)}，步长 {money(p.limits.step)}</p>
+        <button type="button" class="ghostbtn" onclick={() => betOpen = false}>完成</button>
+      </div>
+    </dialog>
+    <dialog class="sheet" bind:this={menuDlg} onclose={() => menuOpen = false}>
+      <h3>设置</h3>
+      <div class="body">
+        <p class="small" style="margin:0">本场 <b class="num" class:win={p.pnl > 0} class:bad={p.pnl < 0}>{signed(p.pnl)}</b></p>
+        <div class="tg">
+          {@render toggles()}
+        </div>
+        <h3>参数</h3>
+        {@render params()}
+        <h3>自动</h3>
+        <Field>
+          {#snippet label()}<label for="rounds-m">自动局数</label>{/snippet}
+          {#snippet accent()}<span>0 = 不限</span>{/snippet}
+          <input id="rounds-m" type="number" min="0" max="1000" disabled={p.autoActive}
+                 value={p.autoActive ? p.autoLeft : p.autoRounds}
+                 onchange={e => { p.autoRounds = Math.max(0, parseInt(e.currentTarget.value, 10) || 0);
+                                  e.currentTarget.value = String(p.autoRounds); }} />
+        </Field>
+        <button class="cta cash" type="button" disabled={!p.ready0 || !p.spec.autoplay} onclick={toggleAuto}>
+          {#if p.autoActive}停止<span class="n">（{p.autoLeft}）</span>{:else if p.spec.autoplay}开始自动{:else}这个游戏不支持自动{/if}
+        </button>
+        <button type="button" class="ghostbtn" onclick={() => menuOpen = false}>关闭</button>
+      </div>
+    </dialog>
+    {/if}
   </div>
 
-  <!-- 机台下面：开发者要看的东西。玩家站点这里放的是最近对局和这局用哪张表 -->
+  <!-- 机台下面：开发者要看的东西。玩家站点这里放的是最近对局和这局用哪张表。
+       嵌进 studio 时不渲染：预览只留机台，历史 / case / 表都在 studio 页面右侧和 MCP 里 -->
+  {#if !embedded}
   <section class="panel dev">
     <div class="tabs" role="tablist">
       <button role="tab" aria-selected={tab === 'history'} onclick={() => tab = 'history'}>历史 {p.history.length}</button>
@@ -326,8 +436,58 @@
       <p class="hint">{p.spec.slug} · 目标 RTP {(p.spec.rtp * 100).toFixed(2)}%</p>
     {/if}
   </section>
+  {/if}
 </div>
 
+{#snippet cta()}
+  {#if p.mode === 'auto'}
+    <button class="cta cash" type="button" disabled={!p.ready0 || !p.spec.autoplay}
+            onclick={() => p.autoActive ? p.stopAuto() : p.startAuto()}>
+      {#if p.autoActive}停止<span class="n">（{p.autoLeft}）</span>{:else if p.spec.autoplay}开始自动{:else}这个游戏不支持自动{/if}
+    </button>
+  {:else if p.game.busy}
+    <button class="cta" type="button" disabled={!p.game.canSkip} onclick={() => inst?.skip()}>
+      {p.game.canSkip ? '直接看结果' : '进行中'}
+    </button>
+  {:else}
+    <button class="cta" type="button" disabled={!p.canBet} onclick={() => p.playOne()}>
+      下注 <span class="n">{money(p.bet)}</span>
+    </button>
+  {/if}
+{/snippet}
+
+{#snippet params()}
+  <SchemaFields />
+  {#each p.issues as i (i.field)}
+    <p class="bad small">{Object.values(i.message)[0]}</p>
+  {/each}
+  {#if p.tableMode}
+    <p class="hint">表 <span class="mono">{p.tableMode}</span>{#if tableStats} · 实算 RTP {(tableStats.computedRtpPpm / 1e4).toFixed(2)}% · 命中 {(tableStats.hitRatePpm / 1e4).toFixed(2)}% · 最大 {(tableStats.maxPayoutCenti / 100).toFixed(2)}x{:else if !p.remote} · 第一注时就地建表{/if}</p>
+  {/if}
+{/snippet}
+
+{#snippet toggles()}
+  <button type="button" aria-pressed={p.view.turbo}
+          onclick={() => p.setView({ turbo: !p.view.turbo })}>
+    <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M13 2 4 14h7l-1 8 9-12h-7z" /></svg>
+    快速模式
+  </button>
+  <button type="button" aria-pressed={p.view.sound}
+          onclick={() => p.setView({ sound: !p.view.sound })}>
+    {#if p.view.sound}
+      <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 9v6h4l5 4V5L8 9zM17 8a5 5 0 0 1 0 8" /></svg>
+    {:else}
+      <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 9v6h4l5 4V5L8 9zM17 10l4 4M21 10l-4 4" /></svg>
+    {/if}
+    音效
+  </button>
+  <label class="seed">客户端种子
+    <input bind:value={p.clientSeed} disabled={p.autoActive} /></label>
+  {#if p.server.refill}
+    <button type="button" onclick={() => p.refill()}>重置余额</button>
+  {/if}
+{/snippet}
+
 <style>
   /* 只写这一页自己的布局。机台、表单、按钮的样式全在共享的 theme.css 里 */
   .shell { width: min(1200px, calc(100% - 32px)); margin: 0 auto; padding-bottom: 48px; }
@@ -336,10 +496,16 @@
   /* 嵌入时 iframe 的视口就是机台那一栏的宽度，studio 把它缩到 1000 以下很常见（1440 的屏就会），
      但机台不该因此切成窄屏的上下堆叠——它在 studio 里始终是一台横着的机器。
      把 theme.css 里窄屏媒体查询改掉的那几条按宽屏写回来 */
-  .shell.embedded .cab { grid-template-columns: 304px minmax(0, 1fr); grid-template-areas: "panel stage" "bar bar"; }
-  .shell.embedded .panel-col { min-height: 0; }
-  .shell.embedded .panel-inner { position: absolute; overflow: hidden; }
-  .shell.embedded .params { flex: 1; min-height: 0; overflow-y: auto; padding-right: 4px; }
+  .shell.embedded .cab:not(.mobile) { grid-template-columns: 304px minmax(0, 1fr); grid-template-areas: "panel stage" "bar bar"; }
+  .shell.embedded .cab:not(.mobile) .panel-col { min-height: 0; }
+  .shell.embedded .cab:not(.mobile) .panel-inner { position: absolute; overflow: hidden; }
+  .shell.embedded .cab:not(.mobile) .params { flex: 1; min-height: 0; overflow-y: auto; padding-right: 4px; }
+  /* 手机机台顶满整个视口：它自己就是那台手机的屏幕，开发面板在它下面 */
+  .shell.mobile { width: 100%; padding-bottom: 16px; }
+  .shell.mobile .dev { margin: 16px 12px 0; }
+  .sheet .body .tg { align-items: stretch; }
+  .sheet .body .tg > button { display: flex; align-items: center; gap: 8px; border: 1px solid var(--line); background: var(--field); border-radius: 12px; min-height: 42px; padding: 0 12px; font-weight: 700; color: var(--dim); }
+  .sheet .body .tg svg { width: 17px; height: 17px; fill: none; stroke: currentColor; stroke-width: 1.8; stroke-linecap: round; stroke-linejoin: round; }
   /* 和玩家站点的 game.html 一样：游戏根元素撑满整块逻辑画面，由游戏自己在里面排版。
      不撑的话根元素按内容高度长，超出 771 的那一截会被舞台裁掉，而且很不显眼 */
   /* 写成 .stage > .gameframe 是为了压过 theme.css 里同名的 display:block */
@@ -364,6 +530,5 @@
   .skins { display: grid; grid-template-columns: repeat(auto-fill, minmax(56px, 1fr)); gap: 8px; }
   .skins button { border: 0; background: none; padding: 0; border-radius: 12px; overflow: hidden; line-height: 0; }
   .skins img { width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: 12px; opacity: .55; transition: opacity .15s; }
-  .skins button[aria-pressed="true"] img { opacity: 1; box-shadow: 0 0 0 2px var(--accent-ink); }
   .skins span { display: block; font-size: 12px; padding: 8px 4px; line-height: 1.2; background: var(--field); border-radius: 12px; }
 </style>

package/dev-host/index.ts

@@ -4,5 +4,6 @@ export * from './local.ts';
 export * from './remote.ts';
 export * from './platform.svelte.ts';
 export * from './context.svelte.ts';
+export * from './layout.ts';
 export { runDevShell, type RunOptions } from './run.ts';
 export { ensureHostFonts } from './fonts.ts';

package/dev-host/layout.ts

@@ -0,0 +1,80 @@
+/* 布局判定与舞台缩放。玩家站点的 GameFrame 与参考平台的 DevShell 都走这里，
+   两处只剩「谁是容器、谁是画面」的差别。 */
+import { fitStage, type StageFit, type StageLayout } from '../sdk/index.ts';
+
+/** 竖屏窄屏才算手机；横屏手机沿用桌面机台的堆叠布局 */
+export const MOBILE_QUERY = '(max-width: 600px) and (orientation: portrait)';
+
+const LAYOUTS = new Set<string>(['desktop', 'mobile']);
+
+/** 惰性读 matchMedia：这个模块会被 node 测试 import，模块顶层不能碰它 */
+export function detectLayout(mm: ((q: string) => { matches: boolean }) | undefined = globalThis.matchMedia): StageLayout {
+  try { return mm?.(MOBILE_QUERY).matches ? 'mobile' : 'desktop'; } catch { return 'desktop'; }
+}
+
+/** `?layout=mobile` 这种显式指定；没写或写错返回 null */
+export function layoutFromSearch(search: string): StageLayout | null {
+  const v = new URLSearchParams(search).get('layout');
+  return v && LAYOUTS.has(v) ? (v as StageLayout) : null;
+}
+
+/** `?safe=47,34`：studio 模拟刘海与 home 指示条，iframe 里 env(safe-area-inset-*) 恒为 0 */
+export function safeFromSearch(search: string): { top: number; bottom: number } | null {
+  const v = new URLSearchParams(search).get('safe');
+  if (!v) return null;
+  const [t = '0', b = '0'] = v.split(',');
+  const top = Number(t), bottom = Number(b);
+  return Number.isFinite(top) && Number.isFinite(bottom) ? { top, bottom } : null;
+}
+
+/**
+ * 让 `frame`（游戏容器：CSS 尺寸恒为逻辑分辨率）在 `stage` 里按布局整体缩放。
+ *
+ * 桌面：`.stage` 的形状由 CSS aspect-ratio 决定，只看它的宽。
+ * 手机：`.stage` 的父元素（`.cab.mobile`）是整块屏幕，两个方向都看，算出的显式尺寸写回 `.stage`，
+ * 由 CSS 把它居中。观察的是这两个元素而不是窗口——机台重排时同样的窗口宽度可能对应两种舞台宽度。
+ */
+export function observeStage(o: {
+  stage: HTMLElement;
+  frame: HTMLElement;
+  layout: () => StageLayout;
+  onFit?: (fit: StageFit) => void;
+}): { refit(): void; dispose(): void } {
+  let last: StageFit | null = null;
+  /* .stage 自己也在被观察：写它的尺寸只能在观察回调之外（下面的 rAF），且值没变就不写，
+     否则每次重排都报一条 ResizeObserver loop——studio 会把它当控制台报错交给 AI */
+  const size = (w: string, h: string): void => {
+    if (o.stage.style.width !== w) o.stage.style.width = w;
+    if (o.stage.style.height !== h) o.stage.style.height = h;
+  };
+  const refit = (): void => {
+    const layout = o.layout();
+    const box = o.stage.parentElement;
+    let fit: StageFit;
+    if (layout === 'mobile' && box) {
+      fit = fitStage('mobile', box.clientWidth, box.clientHeight);
+      size(`${fit.width * fit.scale}px`, `${fit.height * fit.scale}px`);
+    } else {
+      size('', '');
+      fit = fitStage('desktop', o.stage.clientWidth, o.stage.clientHeight);
+    }
+    if (!(fit.scale > 0) || !isFinite(fit.scale)) return;
+    o.frame.style.width = `${fit.width}px`;
+    o.frame.style.height = `${fit.height}px`;
+    o.frame.style.transform = `scale(${fit.scale})`;
+    if (last && last.layout === fit.layout && last.width === fit.width && last.height === fit.height
+      && last.scale === fit.scale && last.x === fit.x && last.y === fit.y) return;
+    last = fit;
+    o.onFit?.(fit);
+  };
+  let raf = 0;
+  const schedule = (): void => {
+    if (raf) return;
+    raf = requestAnimationFrame(() => { raf = 0; refit(); });
+  };
+  const ro = new ResizeObserver(schedule);
+  ro.observe(o.stage);
+  if (o.stage.parentElement) ro.observe(o.stage.parentElement);
+  refit();
+  return { refit, dispose: () => { ro.disconnect(); if (raf) cancelAnimationFrame(raf); } };
+}

package/dev-host/platform.svelte.ts

@@ -6,8 +6,9 @@
    状态用 runes 写（这是个 Svelte 宿主），交给游戏的是框架中立的 Readable。
    换成 React 宿主时这一层换成 useSyncExternalStore，游戏侧零改动。 */
 import {
-  defaultsOf, writable,
-  type GameDefinition, type GameStatus, type Host, type Readable, type RoundResult, type ViewSettings, type WalletView,
+  DESKTOP_STAGE, defaultsOf, writable,
+  type GameDefinition, type GameStatus, type Host, type Readable, type RoundResult, type StageInfo, type StageLayout,
+  type ViewSettings, type WalletView,
 } from '../sdk/index.ts';
 import { localServer } from './local.ts';
 import { DEFAULT_LIMITS, type Check, type PlatformServer, type PlayInput } from './platform-server.ts';
@@ -48,6 +49,7 @@ export interface PlayOptions {
  */
 export function createPlatform<C, O>(
   spec: GameDefinition<C, O>, server: PlatformServer<C, O> = localServer({ spec }),
+  opts: { layout?: StageLayout } = {},
 ) {
   let api: GameApi<O> | null = null;
   const defaults = defaultsOf(spec.schema);
@@ -61,6 +63,7 @@ export function createPlatform<C, O>(
   });
   const walletStore = writable<WalletView>({ balance: 0, currency: 'CNY', decimals: 2 });
   const jackpotStore = writable<{ v: number | null }>({ v: null });
+  const stageStore = writable<StageInfo>(DESKTOP_STAGE);
 
   class Platform {
     config = $state<C>(defaults);
@@ -95,10 +98,14 @@ export function createPlatform<C, O>(
     clientSeed = $state('player-local');
     /** 游戏交回来的状态 */
     game = $state<GameStatus>({ phase: 'loading', busy: false, canBet: false, canSkip: false, canEditConfig: false });
-    /** 资源预加载进度 0..1。平台侧的加载器写，游戏不知道有这回事；null = 代码还没下完 */
-    loadProgress = $state<number | null>(null);
+    /** 机台上的加载进度 0..1。平台侧的表写，游戏不知道有这回事 */
+    loadProgress = $state(0);
     /** 本地服务端已加载的表（mode 名） */
     tableModes = $state<string[]>([]);
+    /** 机台的布局。切换只改机台的兄弟节点和缩放，游戏实例不重挂 */
+    layout = $state<StageLayout>(opts.layout ?? 'desktop');
+    /** 交给游戏的舞台的只读副本，机台渲染用；真值在 stageStore 里 */
+    stage = $state<StageInfo>(DESKTOP_STAGE);
 
     readonly spec = spec;
     readonly server = server;
@@ -139,6 +146,17 @@ export function createPlatform<C, O>(
     bindGame(a: GameApi<O>): void { api = a; }
     setGameStatus(s: GameStatus): void { this.game = s; }
     setLoadProgress(ratio: number): void { this.loadProgress = ratio; }
+    setLayout(l: StageLayout): void { this.layout = l; }
+    /** 机台量好了舞台与安全区，写给游戏。传进来的对象会被原样交出去，调用方给的是字面量 */
+    setStage(info: StageInfo): boolean {
+      const cur = stageStore.get();
+      if (cur.layout === info.layout && cur.width === info.width && cur.height === info.height
+        && cur.safe.top === info.safe.top && cur.safe.bottom === info.safe.bottom
+        && cur.safe.left === info.safe.left && cur.safe.right === info.safe.right) return false;
+      stageStore.set(info);
+      this.stage = info;
+      return true;
+    }
 
     host(): Host<C> {
       return {
@@ -146,6 +164,7 @@ export function createPlatform<C, O>(
         view: viewStore,
         wallet: walletStore,
         jackpot: { get: () => jackpotStore.get().v, subscribe: (run) => jackpotStore.subscribe((s) => run(s.v)) } as Readable<number | null>,
+        stage: stageStore,
         audio: { context: () => audioCtx(), volume: () => this.view.volume },
         locale: 'zh-CN',
         requestConfig: (p) => { this.requestConfig(p); },

package/dev-host/run.ts

@@ -5,11 +5,12 @@
    （Record<string, unknown>），于是每个游戏的 dev.ts 都得写一次强转。
    包在这里，强转只出现一次，游戏侧的调用是类型安全的。 */
 import { mount } from 'svelte';
-import type { GameModule } from '../sdk/index.ts';
+import type { GameModule, StageLayout } from '../sdk/index.ts';
 import type { PlatformServer } from './platform-server.ts';
 import type { HistoryEntry, PlatformOf } from './platform.svelte.ts';
 import DevShell from './DevShell.svelte';
 import { ensureHostFonts } from './fonts.ts';
+import { detectLayout, layoutFromSearch, safeFromSearch } from './layout.ts';
 import './theme.css';
 
 export interface RunOptions<C = object, O = unknown> {
@@ -25,6 +26,10 @@ export interface RunOptions<C = object, O = unknown> {
   server?: PlatformServer<C, O>;
   onSaveCase?: (h: HistoryEntry, title: string) => Promise<string>;
   onPlatform?: (p: PlatformOf<C, O>) => void;
+  /** 初始布局。不传：`?layout=` 说了算，没说就按窗口判 */
+  layout?: StageLayout;
+  /** 模拟真机的刘海与 home 指示条（屏幕像素），加进 HUD 的内边距。不传：`?safe=top,bottom` */
+  simSafe?: { top: number; bottom: number };
 }
 
 export function runDevShell<C extends object, O>(
@@ -41,6 +46,8 @@ export function runDevShell<C extends object, O>(
       server: o.server as unknown as PlatformServer<object, unknown> | undefined,
       onSaveCase: o.onSaveCase,
       onPlatform: o.onPlatform as unknown as ((p: PlatformOf<object, unknown>) => void) | undefined,
+      layout: o.layout ?? layoutFromSearch(location.search) ?? detectLayout(),
+      simSafe: o.simSafe ?? safeFromSearch(location.search) ?? undefined,
     }
   });
 }