@lark-apaas/coding-registry-buildless 0.1.5-alpha.20260717102042 → 0.1.5

package/components/design-canvas.jsx

@@ -29,10 +29,9 @@
 // suppress the card chrome and let the artboard size to its content:
 //   <DCArtboard chromeless><IOSDevice>…</IOSDevice></DCArtboard>
 //
-// On mobile (UA-detected) the canvas is browse-only: one-finger drag pans
-// (starting on artboards too), two-finger pinch zooms, the zoom control is
-// hidden, and drag-reorder / inline-rename are disabled. Tap on an artboard
-// label still opens the focus overlay.
+// On mobile devices the canvas automatically becomes a browse-only surface
+// (touch pan/zoom, editing disabled). This needs NO authoring changes:
+// never add custom touch handling or mobile-specific layouts.
 /* END USAGE */
 
 const DC = {
@@ -45,10 +44,11 @@ const DC = {
   font: '-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif',
 };
 
-// ── 移动端判定：复刻主仓 @apaas-ai/global-states isMobile() 的 UA 语义
-// （跨域产物 iframe 无法 import 该包，同 deck-stage 的先例）。刻意不用视口
-// 断点——桌面工作台的预览 iframe 本身就窄，视口宽度会把桌面预览误判成移动端。
-// 启动时一次性判定，不随 resize 抖动。
+// Mirrors the host platform's isMobile() (UA regex + iPad maxTouchPoints);
+// the product iframe is cross-origin, so the shared helper can't be imported.
+// Deliberately NOT viewport-based: the desktop workbench shows canvases in a
+// narrow preview iframe that a width breakpoint would misread as mobile.
+// Evaluated once at load. Keep the regex in sync with deck-stage.js's copy.
 const DC_MOBILE_UA_RE = /(phone|pad|pod|iPhone|iPod|ios|iPad|Android|Mobile|BlackBerry|IEMobile|MQQBrowser|JUC|Fennec|wOSBrowser|BrowserNG|WebOS|Symbian|Windows Phone)/i;
 const dcIsMobile = typeof navigator !== 'undefined' &&
   (DC_MOBILE_UA_RE.test(navigator.userAgent) ||
@@ -112,14 +112,14 @@ if (typeof document !== 'undefined' && !document.getElementById('dc-styles')) {
     // Mobile is browse-only: kill text selection + iOS long-press callout
     // inside the canvas. iOS interprets a drag over selectable TEXT as a
     // selection gesture and steals the pointer (pointercancel) — touch-action
-    // only suppresses native pan/zoom, not selection — so text-dense
-    // artboards became un-pannable while image-heavy ones panned fine.
+    // only suppresses native pan/zoom, not selection, so a drag
+    // starting on selectable text never reaches the pan.
     '.dc-mobile, .dc-mobile *{-webkit-user-select:none;user-select:none;-webkit-touch-callout:none}',
     // Prototype content routinely carries inner scrollers (the device/window
     // frames all have overflow:auto bodies). On iOS a touch starting inside a
     // scrollable element is consumed by THAT scroller (native scroll attempt
-    // + pointercancel), so pans could never start on those artboards while
-    // plain-HTML cards panned fine. Mobile canvas is browse-only: kill native
+    // + pointercancel), so a pan could
+    // never start there. Mobile canvas is browse-only: kill native
     // touch handling on everything inside the cards so gestures always reach
     // the viewport state machine. Desktop (no .dc-mobile) keeps inner scroll.
     '.dc-mobile [data-dc-slot] *{touch-action:none !important}',
@@ -740,9 +740,9 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
     const touches = new Map(); // pointerId -> last {x, y}
     let mobMode = null;        // null | 'tap' | 'pan' | 'pinch'
     let tapStart = null;       // down point for slop arbitration
-    let pinchDist = 0;         // last-applied finger distance (rAF 帧粒度)
+    let pinchDist = 0;         // finger distance as of the last applied frame
     let pinchMid = null;       // last-applied midpoint
-    let panApplied = null;     // 单指 pan 最近一次已应用的触点位置
+    let panApplied = null;     // pointer position as of the last applied pan frame
     const MOB_SLOP = 9;        // px of travel before a tap becomes a pan
 
     // First two insertion-ordered touches define the pinch; a third finger is
@@ -758,7 +758,7 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
         mobMode = 'tap';
         tapStart = { x: e.clientX, y: e.clientY };
       } else if (touches.size === 2) {
-        mobFlushNow(); // 单指 pan 有待应用的帧则先落账，再切 pinch 基准
+        mobFlushNow(); // apply any pending pan frame before rebasing as a pinch
         mobMode = 'pinch';
         const g = pinchGeom();
         pinchDist = g.d;
@@ -766,11 +766,13 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
         try { vp.setPointerCapture(e.pointerId); } catch {}
       }
     };
-    // ── rAF 合帧：move 事件只更新触点坐标，几何应用每帧至多一次。
-    // 高刷屏/快速捏合时 pointermove 频率可远超渲染帧率，逐事件全量跑
-    // zoomAt/apply（布局读写 + 样式失效 + postMessage）会以超过引擎回收
-    // 节奏的速度制造 WebKit 堆垃圾——真机快速捏合表现为内存持续攀升
-    // （vmmap 定位在 WebKit Malloc；帧率化应用后实测完全回收）。
+    // rAF-coalesced application: move handlers only record pointer
+    // positions; geometry is applied at most once per frame. pointermove can
+    // far outrun the render rate (120Hz touch sampling, fast pinches), and
+    // running the full zoomAt/apply per event creates engine-heap garbage
+    // faster than mobile WebKit reclaims it — which reads as unbounded
+    // memory growth on device. Only the last position per frame can ever
+    // be painted anyway.
     let mobRaf = 0;
     const mobFlushFrame = () => {
       mobRaf = 0;
@@ -811,7 +813,7 @@ function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
       if (mobMode === 'pan' || mobMode === 'pinch') mobSchedule();
     };
     const onTouchUp = (e) => {
-      mobFlushNow(); // 抬指前把最后一个待应用帧落账，避免尾部位移丢失
+      mobFlushNow(); // apply the pending frame first so the gesture tail isn't lost
       if (!touches.delete(e.pointerId)) return;
       try { vp.releasePointerCapture(e.pointerId); } catch {}
       if (touches.size === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-registry-buildless",
-  "version": "0.1.5-alpha.20260717102042",
+  "version": "0.1.5",
   "description": "Miaoda registry (buildless runtime) — shadcn-style copy-in SDKs (globals + CDN-pinned, browser Babel) for buildless static HTML stacks",
   "type": "module",
   "files": [

package/scripts/deck-stage.js

@@ -12,9 +12,8 @@
  *      hidden while presenting / in preview / on narrow / noscale / no-rail.
  *  (b) keyboard navigation — ←/→, PgUp/PgDn, Space, Home/End, number keys.
  *      On touch devices, tapping the left/right half of the stage goes
- *      prev/next (desktop / presenting mode; mobile browse mode scrolls
- *      instead — see (g)) — taps on links, buttons and other interactive
- *      slide content are left alone.
+ *      prev/next (not in mobile browse mode — see (g)) — taps on links,
+ *      buttons and other interactive slide content are left alone.
  *  (c) press R to reset to slide 0.
  *  (d) auto-scaling — inner canvas is a fixed design size (default 1920×1080)
  *      scaled with `transform: scale()` to fit the viewport, letterboxed.
@@ -35,18 +34,10 @@
  *      (≤640px), and via the `no-rail` attribute. Rail mutations dispatch
  *      a `deckchange`
  *      CustomEvent on the element: detail = {action, from, to, slide}.
- *  (g) mobile — on mobile UA (mirrors the host platform's isMobile()
- *      semantics: UA regex + iPad maxTouchPoints, never viewport width),
- *      browse mode renders slides as a vertical card stream (12px margin,
- *      8px gap, 8px radius) with native scrolling; a per-card page badge
- *      fades in while scrolling (16|20×12, ink 20% bg, fixed 8px digits)
- *      and fades out 2s after scrolling stops. Presenting mode
- *      (miaoda:deck:presenting) rotates the stage 90° (CSS pseudo-
- *      landscape, no orientation.lock): tap left/right third to navigate,
- *      tap center to toggle the controls overlay (back button +
- *      filmstrip; auto-hides after 3s). The back button exits presenting
- *      and posts miaoda:deck:presenting-dismissed to the parent.
- *      Desktop behaviour is unchanged.
+ *  (g) mobile — on mobile devices the same deck automatically renders as
+ *      a scrollable vertical card list (browse) and a rotated fullscreen
+ *      presenting mode. This needs NO authoring changes: never hand-roll
+ *      mobile/responsive slide layouts. Desktop behaviour is unchanged.
  *
  * Slides are HIDDEN, not unmounted. Non-active slides stay in the DOM with
  * `visibility: hidden` + `opacity: 0`, so their state (videos, iframes,
@@ -129,20 +120,21 @@
   // Slide-authored controls that should keep a tap instead of it navigating.
   const INTERACTIVE_SEL = 'a[href], button, input, select, textarea, summary, label, video[controls], audio[controls], [role="button"], [onclick], [tabindex]:not([tabindex^="-"]), [contenteditable]:not([contenteditable="false" i])';
 
-  // ── 移动端（复刻主仓 @apaas-ai/global-states isMobile() 的 UA 语义；
-  //    跨域产物 iframe 无法 import 该包）。刻意不用视口断点：桌面工作台的
-  //    预览 iframe 本身就窄，视口宽度会把桌面预览误判成移动端。
-  //    mode=desktop 逃生阀只作用于壳层自身 location、不透传到本 iframe，不实现。
+  // Mirrors the host platform's isMobile() (UA regex + iPad maxTouchPoints);
+  // the product iframe is cross-origin, so the shared helper can't be
+  // imported. Deliberately NOT viewport-based: the desktop workbench renders
+  // decks in a narrow preview iframe that a width breakpoint would misread
+  // as mobile. Keep the regex in sync with design-canvas.jsx's copy.
   const MOBILE_UA_RE = /(phone|pad|pod|iPhone|iPod|ios|iPad|Android|Mobile|BlackBerry|IEMobile|MQQBrowser|JUC|Fennec|wOSBrowser|BrowserNG|WebOS|Symbian|Windows Phone)/i;
   const isMobileUA = () =>
     MOBILE_UA_RE.test(navigator.userAgent) ||
     (/iPad|Tab|Tablet/i.test(navigator.userAgent) && !!navigator.maxTouchPoints && navigator.maxTouchPoints > 1);
-  // 移动端视觉常量（Figma node 2965:32138 / 2965:32047 / 2965:34386 已确认）
-  const MOB_MARGIN = 12;        // 竖排卡片页边距
-  const MOB_GAP = 8;            // 卡片间距
-  const MOB_RADIUS = 8;         // 卡片圆角
-  const MOB_BADGE_IDLE_MS = 2000;  // 滚动停止 → 徽标淡出（UX 确认 2s）
-  const MOB_UI_HIDE_MS = 3000;     // 播放控件层自动收起
+  // Mobile visual metrics (values from the platform's mobile design spec).
+  const MOB_MARGIN = 12;           // card-stream edge margin
+  const MOB_GAP = 8;               // gap between cards
+  const MOB_RADIUS = 8;            // card corner radius
+  const MOB_BADGE_IDLE_MS = 2000;  // scroll idle before the page badge fades
+  const MOB_UI_HIDE_MS = 3000;     // presenting controls auto-hide
 
   const pad2 = (n) => String(n).padStart(2, '0');
 
@@ -408,7 +400,7 @@
     .rail[data-presenting] + .rail-resize,
     .rail[data-user-hidden] + .rail-resize { display: none; }
 
-    /* ── 移动端竖排浏览 ─────────────────────────────────────── */
+    /* ── Mobile browse: vertical card stream ── */
     :host([data-mobile-list]) .stage {
       display: block;
       overflow-y: auto;
@@ -435,11 +427,12 @@
        (The equivalent rule further down lives inside @media print only.) */
     :host([data-mobile-list]) ::slotted([data-deck-skip]) { display: none !important; }
 
-    /* ── 移动端播放：CSS 旋转伪横屏（不依赖 orientation.lock）────
-       只在设备物理竖屏时旋转；用户顺势把手机转成横屏（系统自动旋转）
-       后，视口本身已是横屏，再叠 90° 会让画面侧躺——此时退化为常规
-       full-bleed 适配，_fitMobilePresent/_mobPresentZone 同步按
-       orientation 分支换轴。 */
+    /* ── Mobile presenting: CSS pseudo-landscape (no orientation.lock) ──
+       Rotate only while the device is physically portrait. Once the user
+       turns the phone (system auto-rotate) the viewport itself is landscape,
+       and stacking another 90° would render slides sideways — so landscape
+       falls back to a plain full-bleed fit. _fitMobilePresent and
+       _mobPresentZone branch on the same orientation test. */
     :host([data-mobile-present]) .stage { background: #000; }
     @media (orientation: portrait) {
       :host([data-mobile-present]) .stage {
@@ -452,7 +445,7 @@
       }
     }
 
-    /* ── 移动端页码徽标（规格：Figma 2965:32047）────────────── */
+    /* ── Mobile page badge ── */
     .mob-badges { display: none; }
     :host([data-mobile-list]) .mob-badges {
       display: block;
@@ -478,7 +471,7 @@
     }
     :host([data-mob-scrolling]) .mob-badge { opacity: 1; }
 
-    /* ── 移动端播放控件层（规格：Figma 2965:34386）──────────── */
+    /* ── Mobile presenting controls (back button + filmstrip) ── */
     .mob-ui { display: none; }
     :host([data-mobile-present][data-mob-ui]) .mob-ui {
       display: block;
@@ -514,7 +507,8 @@
       display: flex;
       gap: 8px;
       padding: 10px 16px calc(10px + env(safe-area-inset-bottom));
-      /* 透明浮在 slide 上（验收对齐设计稿）——缩略图自带白底+描边已足够区分 */
+      /* Transparent: thumbnails carry their own white frames, and a solid
+         strip would blanket the slide behind the overlay. */
       background: transparent;
       overflow-x: auto;
     }
@@ -540,7 +534,7 @@
       font-size: 12px;
       line-height: 20px;
       font-weight: 500;
-      /* 条带透明、底衬通常是播放态黑底/slide 内容——页码用白色（对齐设计稿） */
+      /* The strip floats over the (dark) presenting stage — numbers must be light. */
       color: rgba(255, 255, 255, 0.9);
     }
     .mob-strip .mthumb[data-current] .mnum { color: #336DF4; }
@@ -1044,7 +1038,7 @@
       this._onMobScroll = this._onMobScroll.bind(this);
       stage.addEventListener('scroll', this._onMobScroll, { passive: true });
 
-      // 移动竖排的逐页定位规则（::slotted(:nth-child(i))），_fitMobileList 重建。
+      // Per-slide placement rules for the mobile card stream; rebuilt by _fitMobileList().
       this._mobStyle = document.createElement('style');
 
       this._mobBadges = document.createElement('div');
@@ -1472,8 +1466,9 @@
       this._prevIndex = curr;
     }
 
-    // 移动端两种呈现互斥：竖排浏览（list）/ 旋转横屏播放（present）。
-    // noscale / _snthumb（导出与演讲者缩略图捕获）必须保持桌面几何。
+    // The two mobile presentations are mutually exclusive. noscale and
+    // _snthumb are capture modes whose output must keep desktop geometry,
+    // so they opt out of both.
     _syncMobileMode() {
       const eligible = this._mobile && !this.hasAttribute('noscale') && !this._snthumb;
       this.toggleAttribute('data-mobile-list', eligible && !this._presenting);
@@ -1483,9 +1478,9 @@
     _fitMobileList() {
       const dw = this.designWidth, dh = this.designHeight;
       const vw = window.innerWidth;
-      this._mobLastVw = vw; // _onResize 高度变化跳过的基线
+      this._mobLastVw = vw; // baseline for _onResize's height-only skip
       const stage = this._canvas.parentElement;
-      // 清掉桌面 _fit 写过的 inset 内联值
+      // Clear the stage inset the desktop _fit() wrote inline.
       if (stage) { stage.style.left = '0'; stage.style.right = '0'; stage.style.top = '0'; stage.style.bottom = '0'; }
       this.removeAttribute('data-windowed');
       const cardW = vw - 2 * MOB_MARGIN;
@@ -1504,15 +1499,17 @@
           ' inset: auto !important; top: 0 !important; left: 0 !important;' +
           ' width: ' + dw + 'px !important; height: ' + dh + 'px !important;' +
           ' transform: translate(' + MOB_MARGIN + 'px, ' + y + 'px) scale(' + s + ') !important;' +
-          // 圆角/描边随 scale 反向放大，落地后视觉为 8px / 0.5px
+          // Radius/border are pre-divided by the scale so the slide's transform
+          // lands them at 8px / 0.5px on screen.
           ' border-radius: ' + (MOB_RADIUS / s) + 'px; overflow: hidden !important;' +
           ' border: ' + (0.5 / s) + 'px solid #DEE0E3; }'
         );
         cards.push({ slide, i, y, h: cardH });
         y += cardH + MOB_GAP;
       });
-      // 竖排规则只作用于屏幕媒体——print 的 ::slotted 分页规则特异性更低，
-      // 否则每页会带着列表位移/缩放进入打印流。
+      // Screen-only: these per-slide rules out-specify the print block's
+      // ::slotted reset, so unwrapped they would drag the card-stream
+      // transforms into the paginated print output.
       this._mobStyle.textContent = '@media screen {\n' + rules.join('\n') + '\n}';
       this._canvas.style.transform = 'none';
       this._canvas.style.width = vw + 'px';
@@ -1520,8 +1517,8 @@
       this._mobCards = cards;
       this._mobScale = s;
 
-      // 徽标：每卡片左下角内 6px；宽度按位数 16/16/20。布局是确定性的，
-      // 直接按 _mobCards 几何摆放，无需 IntersectionObserver。
+      // Badge geometry is fully determined by _mobCards, so badges are laid
+      // out directly — no IntersectionObserver needed.
       this._mobBadges.textContent = '';
       cards.forEach((c, ordinal) => {
         const b = document.createElement('div');
@@ -1540,7 +1537,8 @@
     _onMobScroll() {
       if (!this.hasAttribute('data-mobile-list') || !this._mobCards || !this._mobCards.length) return;
 
-      // 徽标显隐：程序化滚动也算"滚动"，两种来源都给可见性反馈。
+      // Programmatic scrolls count as scrolling too — either source means
+      // "the position is changing", which is what the badge signals.
       this.setAttribute('data-mob-scrolling', '');
       clearTimeout(this._mobScrollIdleTimer);
       this._mobScrollIdleTimer = setTimeout(
@@ -1552,16 +1550,18 @@
         const stage = this._canvas.parentElement;
         const top = stage.scrollTop;
         const moved = this._mobLastTop == null ? Infinity : Math.abs(top - this._mobLastTop);
-        this._mobLastTop = top; // 抑制期间也持续跟踪位置
+        this._mobLastTop = top; // keep tracking even while suppressed
         if (this._mobProgUntil && performance.now() < this._mobProgUntil) {
-          // 程序化滚动事件流仍在到达：续期窗口，动画多长都盖得住；
-          // 事件停止 120ms 后窗口自然过期，之后才恢复用户滚动反推。
+          // Events are still streaming from a programmatic scroll: extend
+          // the window so any animation length is covered. It expires 120ms
+          // after the stream stops; user scrolls then resume inference.
           this._mobProgUntil = Math.max(this._mobProgUntil, performance.now() + 120);
           return;
         }
-        if (moved < 1) return; // 无真实位移（合成事件/终点回调）不反推
-        // 纯视口中心公式在卡片高 < 半视口时到不了首/末页（卡片高 ~= 0.5625 * 宽,
-        // 竖屏视口高通常远大于宽的一半），两端改用 clamp，中段维持视口中心语义。
+        if (moved < 1) return; // no real displacement (synthetic/terminal event)
+        // A pure viewport-centre rule can never select the first/last page:
+        // 16:9 cards are far shorter than half a portrait viewport, so their
+        // centring targets clamp. Clamp at the extremes, centre in between.
         const max = stage.scrollHeight - stage.clientHeight;
         let cur;
         if (max <= 0 || stage.scrollTop <= 1) {
@@ -1577,8 +1577,8 @@
         }
         if (cur.i !== this._index) {
           this._index = cur.i;
-          // 广播走现有内核：hash 同步 + slide-changed + slidechange 事件。
-          // data-deck-active 的切换在竖排 CSS 下无视觉副作用。
+          // Broadcast through the existing core (hash + slide-changed +
+          // slidechange). data-deck-active toggling is visually inert here.
           this._applyIndex({ broadcast: true, reason: 'api' });
         }
       });
@@ -1589,14 +1589,14 @@
       if (!card) return;
       const stage = this._canvas.parentElement;
       const top = Math.max(0, card.y - Math.max(0, (stage.clientHeight - card.h) / 2));
-      // 程序化滚动期间抑制 _onMobScroll 的反推——goto/deep-link 已直接设定
-      // _index，多张边缘卡片的居中目标会被 clamp 到同一个 scrollTop，
-      // 反推无法区分它们对应哪一页，故导航直接落 index、反推只处理真实
-      // 用户位移。
+      // Suppress scroll-position inference while a programmatic scroll is
+      // in flight: goto/deep-link already set _index directly, and the
+      // centring targets of several edge cards clamp to the same scrollTop,
+      // so the position alone cannot tell those pages apart.
       this._mobProgUntil = performance.now() + (smooth ? 800 : 200);
-      // 目标位置立为基线：即便这次 scrollTo 因目标已等于当前位置（如居中
-      // 目标 clamp 到 0）而不产生真实 scroll 事件，_mobLastTop 也不会停留
-      // 在 null——避免之后任意一次无位移事件被当成"首次滚动"误判有位移。
+      // Seed the baseline with the target: a scrollTo that lands where the
+      // stage already is fires no scroll event, and a null baseline would
+      // make the next no-op event read as a real first displacement.
       this._mobLastTop = top;
       stage.scrollTo({ top, behavior: smooth ? 'smooth' : 'auto' });
     }
@@ -1607,9 +1607,9 @@
       this.removeAttribute('data-windowed');
       this._canvas.style.width = this.designWidth + 'px';
       this._canvas.style.height = this.designHeight + 'px';
-      // 物理竖屏：CSS 旋转 90°，stage 逻辑尺寸 = (innerHeight × innerWidth)；
-      // 物理横屏（用户顺势转了手机）：不旋转，按真实视口常规适配。
-      // CSS 侧由 @media (orientation) 同步分支。
+      // Portrait: the stage is CSS-rotated, so its logical size is the
+      // swapped viewport. Landscape (user physically rotated): no rotation,
+      // plain fit. The CSS branches on the same orientation query.
       const portrait = window.innerHeight >= window.innerWidth;
       const lw = portrait ? window.innerHeight : window.innerWidth;
       const lh = portrait ? window.innerWidth : window.innerHeight;
@@ -1669,10 +1669,10 @@
     }
 
     _onResize() {
-      // 竖排列表几何只依赖视口宽度。移动浏览器地址栏收起/展开只改高度，
-      // 若照常全量 refit（重建规则/徽标 + 无条件回中当前页），用户滚动中
-      // 会被可见地"拽"一下——纯高度变化直接跳过。宽度变化（旋转/分屏）
-      // 照常走完整 refit。
+      // Card-stream geometry depends only on viewport width, and mobile
+      // browser URL bars fire height-only resizes as they collapse/expand —
+      // a full refit would rebuild everything and yank the list back to the
+      // current page mid-scroll. Width changes (rotate/split) refit as usual.
       if (this.hasAttribute('data-mobile-list')) {
         if (this._mobLastVw === window.innerWidth) return;
         this._mobLastVw = window.innerWidth;
@@ -1774,7 +1774,7 @@
         if (n === this._stage) break;
         if (n.matches && n.matches(INTERACTIVE_SEL)) return;
       }
-      // 竖排浏览是滚动列表，tap 不翻页（spec 决策 #5）
+      // Mobile browse is a scroll list — taps must not navigate.
       if (this.hasAttribute('data-mobile-list')) return;
       e.preventDefault();
       if (this.hasAttribute('data-mobile-present')) {
@@ -1791,12 +1791,13 @@
       this._advance(e.clientX < mid ? -1 : 1, 'tap');
     }
 
-    // rotate(90deg) 后视觉横屏的 x 轴对应视口 y 轴。方向以真机/仿真实测为准：
-    // 若实测发现 prev/next 颠倒，翻转此处的比较符（保持单点修改）。
+    // After rotate(90deg) the visual-landscape x axis maps onto viewport y
+    // (direction confirmed on device; if prev/next ever read reversed, flip
+    // these comparisons — single point of change).
     _mobPresentZone(e) {
       const rect = this._stage.getBoundingClientRect();
-      // 物理竖屏 = stage 被 CSS 旋转 90°，视觉横屏 x 轴对应视口 y 轴；
-      // 物理横屏 = 无旋转，直接用视口 x 轴。与 _fitMobilePresent 同分支。
+      // Portrait = stage is rotated, visual x comes from viewport y;
+      // landscape = no rotation, viewport x directly. Same branch as the fit.
       const portrait = window.innerHeight >= window.innerWidth;
       const x = portrait
         ? (e.clientY - rect.top) / Math.max(1, rect.height)
@@ -1810,9 +1811,11 @@
       this.toggleAttribute('data-mob-ui', on);
       clearTimeout(this._mobUiTimer);
       if (!on) return;
-      // 从隐藏态唤出才全量重建（吸收直编/重排/skip 变化——strip 是静态
-      // 快照、不接 _liveObserver 刷新管线）；已展开时的调用（缩略图点击/
-      // 翻页重置计时）只同步高亮，避免高频路径 O(页数) 重建。
+      // Rebuild only when opening from hidden: the strip is a static
+      // snapshot outside _liveObserver's refresh pipeline, so reopening is
+      // what absorbs slide edits/reorders/skips. Calls while already open
+      // (thumbnail taps resetting the timer) only re-highlight — rebuilding
+      // on that hot path would clone every slide per tap.
       if (!wasOpen || !this._mobUi) {
         if (this._mobUi) { this._mobUi.remove(); this._mobUi = null; }
         this._buildMobUi();
@@ -1822,9 +1825,10 @@
     }
 
     _buildMobUi() {
-      // 移动 viewer 语境 host 可能从不发 rail-enabled，author-CSS 快照
-      // （_enableRail 才建）不存在时缩略图克隆会裸渲染——此处兜底建一次。
-      // _snapshotAuthorCss 可重入且带 generation guard。
+      // A pure-viewer host may never send rail-enabled, so the author-CSS
+      // snapshot (normally built by _enableRail) can be missing and the
+      // clones would render unstyled — build it here as a fallback.
+      // _snapshotAuthorCss is re-entrant and generation-guarded.
       if (!this._adoptedSheet && this._authorCss == null) this._snapshotAuthorCss();
       const ui = document.createElement('div');
       ui.className = 'mob-ui export-hidden';
@@ -1860,19 +1864,19 @@
           t.addEventListener('click', (ev) => {
             ev.stopPropagation();
             this._go(e2.i, 'click');
-            this._toggleMobUi(true); // 重置自动收起计时，保持控件层可见
+            this._toggleMobUi(true); // reset the auto-hide timer, keep the overlay up
           });
           strip.appendChild(t);
-          // 复用 _materialize 的克隆管线（media 熄火、canvas 快照、custom
-          // element 中性化）：它会自建 host/shadow 并直接挂进 entry.frame，
-          // 所以这里不需要再手工搭 host——只需在其后把统一走 _thumbScale
-          // （rail 宽度）算出的缩放，改写成本条带 132px 专属的缩放。
+          // _materialize provides the full clone pipeline (media neutralised,
+          // canvas snapshots) and mounts a host into entry.frame itself — but
+          // it scales clones by the rail's _thumbScale, so rewrite the
+          // transform for this strip's fixed 132px frames.
           const entry = { slide: e2.slide, frame, host: null, clone: null };
           this._materialize(entry);
           if (entry.clone) entry.clone.style.transform = 'scale(' + (132 / this.designWidth) + ')';
           return { el: t, i: e2.i };
         });
-      // 控件层内任何点击不冒泡成翻页 tap
+      // Clicks inside the overlay must not bubble into tap navigation.
       ui.addEventListener('click', (e) => e.stopPropagation());
       ui.append(back, strip);
       this._stage.appendChild(ui);
@@ -1926,13 +1930,14 @@
     _go(i, reason = 'api') {
       if (!this._slides.length) return;
       const clamped = Math.max(0, Math.min(this._slides.length - 1, i));
-      // 竖排浏览：导航直接落 index（与桌面语义一致），滚动只是视觉跟随；
-      // 不再依赖 _onMobScroll 从滚动位置反推——多张边缘卡片的居中滚动目标
-      // 会被 clamp 到同一个 scrollTop，反推无法区分它们是哪一页。
+      // Mobile browse: navigation sets _index directly (desktop parity) and
+      // the scroll is only a visual follow. Inferring the page back from the
+      // scroll position is unreliable here — edge cards' centring targets
+      // clamp to the same scrollTop.
       if (this.hasAttribute('data-mobile-list')) {
         const changed = clamped !== this._index;
         this._index = clamped;
-        // 同页 goto 不重复广播（与桌面分支语义一致），但仍需重新居中滚动。
+        // Same-page goto doesn't rebroadcast (desktop parity) but still recentres.
         if (changed) this._applyIndex({ broadcast: true, reason });
         this._mobScrollTo(clamped, true);
         return;