@snack-kit/scripts 0.2.0 → 0.4.0

package/README.md

@@ -142,6 +142,19 @@ module.exports = (config) => {
 
 ## Changelog
 
+### 0.4.0
+
+- 修复：调试窗口 topbar 工具区样式细节优化
+- 修复：启动调试运行错误的问题
+- 修复：修复 core 依赖版本错误的问题
+
+### 0.3.0
+
+- 新增：调试窗口 topbar 视口尺寸切换（PC / Tablet / Mobile / 自定义），偏好持久化到 localStorage
+- 新增：调试窗口 topbar 内容区背景切换（默认 / 白色 / 深色 / 棋盘格透明检测）
+- 新增：调试窗口 topbar 内容区缩放控制（50% / 75% / 100% / 125% / 150%）
+- 新增：调试窗口 topbar 刷新模块按钮，强制重新 mount 当前模块
+
 ### 0.2.0
 
 - 新增：`MIGRATION.md` 迁移指南，说明从 `@para-snack/*` / `@paraview/*` 迁移到 `@snack-kit/*` 的完整步骤

package/config/webpack.dev.config.js

@@ -8,10 +8,10 @@ const path = require('path');
 const fs = require('fs-extra');
 const HtmlWebpackPlugin = require('html-webpack-plugin');
 const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin');
-const webpack = require('webpack');
 const { version } = require('../package.json');
 const { injectIndexFile } = require('../utils/package');
-const { createResolve, createModuleRules, createOptimization } = require('./webpack.shared');
+const { createResolve, createModuleRules, createOptimization, resolveProjectWebpack, resolveLoader, createPolyfillPlugins } = require('./webpack.shared');
+const webpack = resolveProjectWebpack();
 
 const packageJson = JSON.parse(process.env.PROJECT_PACKAGE_JSON);
 const snackConfig = JSON.parse(process.env.PROJECT_SNACK_CONFIG);
@@ -79,7 +79,8 @@ let conf = {
             template: templatePkgPath || path.join(templatePath, 'index.html')
         }),
         new webpack.HotModuleReplacementPlugin(),
-        new ReactRefreshWebpackPlugin()
+        new ReactRefreshWebpackPlugin(),
+        ...createPolyfillPlugins(webpack)
     ],
     module: {
         rules: createModuleRules({ withRefresh: true, withAsset: true })
@@ -87,6 +88,7 @@ let conf = {
     resolve: createResolve({
         template: path.join(__dirname, '../template')
     }),
+    resolveLoader,
     optimization: createOptimization(false, true),
     devServer: {
         open: true,

package/config/webpack.shared.js

@@ -6,11 +6,76 @@
 const path = require('path');
 const TerserPlugin = require('terser-webpack-plugin');
 
+/**
+ * 获取项目自身的 react/react-dom 路径。
+ * 优先使用宿主项目的 React（保持版本一致），若项目未安装则 fallback 到 snack-scripts 内置的 React 19。
+ *
+ * 同时始终提供 react-dom/client 的别名：
+ *   - React 18+  → 使用项目自身的 react-dom/client
+ *   - React 17   → 使用 scripts 内置 React 19 的 react-dom/client（仅供 webpack 静态解析使用，
+ *                  运行时因 major < 18 不会执行该分支，不影响实际行为）
+ * 这样可让 @snack-kit/core 中的动态 require('react-dom/client') 在所有 React 版本下都能
+ * 被 webpack 静态解析，避免产生 Critical dependency 警告。
+ */
+function resolveProjectReact() {
+    const projectPath = process.env.PROJECT_PATH;
+    const scriptsReactDomClient = path.resolve(__dirname, '../node_modules/react-dom/client.js');
+    const scriptsReact = path.resolve(__dirname, '../node_modules/react');
+    const scriptsReactDom = path.resolve(__dirname, '../node_modules/react-dom');
+    if (!projectPath) {
+        return { react: scriptsReact, reactDom: scriptsReactDom, reactDomClient: scriptsReactDomClient };
+    }
+    try {
+        const reactPkgPath = path.join(projectPath, 'node_modules/react/package.json');
+        const reactPkg = require(reactPkgPath);
+        const majorVersion = parseInt(reactPkg.version.split('.')[0], 10);
+        const projectReactDom = path.join(projectPath, 'node_modules/react-dom');
+        // React 18+ 项目：使用项目自身的 react-dom/client
+        // React 17  项目：使用 scripts 内置的 react-dom/client（运行时不会执行该分支）
+        const reactDomClient = majorVersion >= 18
+            ? path.join(projectReactDom, 'client.js')
+            : scriptsReactDomClient;
+        return {
+            react: path.join(projectPath, 'node_modules/react'),
+            reactDom: projectReactDom,
+            reactDomClient,
+        };
+    } catch (_) {
+        return { react: scriptsReact, reactDom: scriptsReactDom, reactDomClient: scriptsReactDomClient };
+    }
+}
+
+/**
+ * loader 解析配置：确保 webpack 能从 snack-scripts 自身 node_modules 找到 swc-loader 等 loader。
+ * 当 @snack-kit/scripts 以软链接方式安装时，其依赖不会被 npm hoist，需显式指定 loader 搜索路径。
+ */
+const resolveLoader = {
+    modules: [
+        path.resolve(__dirname, '../node_modules'),
+        'node_modules'
+    ]
+};
+
+/**
+ * 尝试解析 process/browser polyfill 路径。
+ * 优先从宿主项目查找，其次从 snack-scripts 自身查找，找不到返回 null。
+ */
+function resolveProcessBrowser() {
+    const searchPaths = [process.env.PROJECT_PATH, path.resolve(__dirname, '../')].filter(Boolean);
+    try {
+        return require.resolve('process/browser', { paths: searchPaths });
+    } catch (_) {
+        return null;
+    }
+}
+
 /**
  * 获取公共 resolve 配置
  * @param {object} extraAlias 额外的别名
  */
 function createResolve(extraAlias = {}) {
+    const { react, reactDom, reactDomClient } = resolveProjectReact();
+    const processBrowserPath = resolveProcessBrowser();
     return {
         extensions: ['.js', '.jsx', '.ts', '.tsx'],
         // 优先从 snack-scripts 自身 node_modules 解析（保证 template 文件能找到 @snack-kit/* 等依赖）
@@ -24,10 +89,26 @@ function createResolve(extraAlias = {}) {
             package: path.join(process.env.PROJECT_PATH, 'src/package'),
             assets: path.join(process.env.PROJECT_PATH, 'src/assets'),
             // @snack-kit/core 的 package.json module 字段路径有误，直接指向 cjs
-            '@snack-kit/core': path.resolve(__dirname, '../node_modules/@snack-kit/core/dist/cjs/index.js'),
-            // 强制 dev 模板使用 snack-scripts 自身的 react，避免项目中旧版 react 被命中
-            'react': path.resolve(__dirname, '../node_modules/react'),
-            'react-dom': path.resolve(__dirname, '../node_modules/react-dom'),
+            // 优先使用宿主项目安装的 @snack-kit/core，fallback 到 scripts 自身的（兼容 file: 软链）
+            '@snack-kit/core': (() => {
+                const projectCorePath = process.env.PROJECT_PATH
+                    ? path.join(process.env.PROJECT_PATH, 'node_modules/@snack-kit/core/dist/cjs/index.js')
+                    : null;
+                const scriptsCorePath = path.resolve(__dirname, '../node_modules/@snack-kit/core/dist/cjs/index.js');
+                if (projectCorePath) {
+                    try { require.resolve(projectCorePath); return projectCorePath; } catch (_) {}
+                }
+                return scriptsCorePath;
+            })(),
+            // 优先使用宿主项目自己的 react，保证 React 版本与项目一致（兼容 React 17/18/19）
+            // react/react-dom 使用目录别名（不加 $），使子路径（如 react/jsx-runtime）也走项目自身版本
+            // react-dom/client 比 react-dom 更长，enhanced-resolve 会优先匹配更具体的 key
+            'react-dom/client': reactDomClient,
+            'react': react,
+            'react-dom': reactDom,
+            // axios >= 1.x 使用子路径 import 'process/browser'，webpack 5 的 fallback 不处理子路径，
+            // 需显式 alias 保证可解析（@snack-kit/lib >= 0.7.0 起依赖新版 axios）
+            ...(processBrowserPath && { 'process/browser': processBrowserPath }),
 ...extraAlias
         }
     };
@@ -137,6 +218,33 @@ const filesystemCache = {
     allowCollectingMemory: true
 };
 
+/**
+ * 解析 webpack 模块，优先使用宿主项目的 webpack 实例。
+ * 保证 webpack config 文件与 webpack CLI 进程使用同一个 webpack 实例，
+ * 避免多实例导致的 instanceof 检查失败（Critical dependency / Compilation 错误）。
+ */
+function resolveProjectWebpack() {
+    const searchPaths = [process.env.PROJECT_PATH, __dirname].filter(Boolean);
+    try {
+        return require(require.resolve('webpack', { paths: searchPaths }));
+    } catch (_) {
+        return require('webpack');
+    }
+}
+
+/**
+ * 创建 process/Buffer polyfill 的 ProvidePlugin 配置（可选）。
+ * 若 process/browser 可解析，则自动注入，使项目代码中裸用的 `process` 全局变量可正常工作。
+ * 返回 plugin 实例数组，为空数组则表示无需注入。
+ */
+function createPolyfillPlugins(webpack) {
+    const processBrowserPath = resolveProcessBrowser();
+    if (!processBrowserPath) return [];
+    return [
+        new webpack.ProvidePlugin({ process: 'process/browser' })
+    ];
+}
+
 module.exports = {
     createResolve,
     createSwcRule,
@@ -144,5 +252,8 @@ module.exports = {
     createOptimization,
     filesystemCache,
     styleRule,
-    assetRule
+    assetRule,
+    resolveProjectWebpack,
+    resolveLoader,
+    createPolyfillPlugins
 };

package/config/webpack.snack.config.js

@@ -7,9 +7,9 @@
 const path = require('path');
 const fs = require('fs-extra');
 const minimist = require('minimist');
-const webpack = require('webpack');
 const { SnackPlugin, createExternals } = require('../utils/package');
-const { createResolve, createModuleRules, createOptimization, filesystemCache } = require('./webpack.shared');
+const { createResolve, createModuleRules, createOptimization, filesystemCache, resolveProjectWebpack, resolveLoader, createPolyfillPlugins } = require('./webpack.shared');
+const webpack = resolveProjectWebpack();
 
 const argv = minimist(process.argv.slice(2), { default: { mode: 'development' } });
 const isDevelopment = argv.mode === 'development';
@@ -50,7 +50,8 @@ let conf = {
             banner: 'if(typeof window!=="undefined"&&window.snackdefine){var define=window.snackdefine;}',
             raw: true
         }),
-        new SnackPlugin()
+        new SnackPlugin(),
+        ...createPolyfillPlugins(webpack)
     ],
     externals: {
         react: 'react',
@@ -63,6 +64,7 @@ let conf = {
         rules: createModuleRules({ withAsset: true })
     },
     resolve: createResolve(),
+    resolveLoader,
     optimization: createOptimization(isProduction)
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snack-kit/scripts",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "snack-cli package scripts Powered by Para FED",
   "bin": {
     "snack-scripts": "./bin/main.js"
@@ -35,7 +35,7 @@
     "@pmmmwh/react-refresh-webpack-plugin": "^0.5.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@snack-kit/core": "file:../core",
+    "@snack-kit/core": "^0.3.0",
     "@snack-kit/lib": "^0.6.0",
     "@swc/core": "^1.2.100",
     "babel-loader": "^9.1.3",

package/template/dev/App.tsx

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import React, { useState, useMemo, useEffect, useCallback } from 'react';
+import React, { useState, useMemo, useEffect, useCallback, useRef } from 'react';
 import logo from 'template/logo.svg';
 import Core from '@snack-kit/core';
 
@@ -24,8 +24,6 @@ const resolveRouter = (hash: string) => {
     return name ? { name, setting } : null;
 };
 
-// ─── Sidebar ──────────────────────────────────────────────────────────────────
-
 // ─── Theme Hook ───────────────────────────────────────────────────────────────
 
 const THEME_KEY = 'snack-dev-theme';
@@ -44,6 +42,78 @@ const useTheme = () => {
     return { dark, toggle };
 };
 
+// ─── Viewport Hook ────────────────────────────────────────────────────────────
+
+type ViewportPreset = 'pc' | 'tablet' | 'mobile' | 'custom';
+
+const VIEWPORT_PRESETS: { key: ViewportPreset; label: string; width: number | null }[] = [
+    { key: 'pc',     label: 'PC',     width: null },
+    { key: 'tablet', label: 'Tablet', width: 768  },
+    { key: 'mobile', label: 'Mobile', width: 375  },
+    { key: 'custom', label: '自定义', width: null },
+];
+
+const VIEWPORT_KEY = 'snack-dev-viewport';
+
+const useViewport = () => {
+    const saved = (() => { try { return JSON.parse(localStorage.getItem(VIEWPORT_KEY) || 'null'); } catch { return null; } })();
+    const [preset, setPreset] = useState<ViewportPreset>(saved?.preset || 'pc');
+    const [customWidth, setCustomWidth] = useState<number>(saved?.customWidth || 414);
+
+    useEffect(() => {
+        try { localStorage.setItem(VIEWPORT_KEY, JSON.stringify({ preset, customWidth })); } catch {}
+    }, [preset, customWidth]);
+
+    const width = useMemo(() => {
+        const p = VIEWPORT_PRESETS.find(x => x.key === preset);
+        if (!p) return null;
+        if (preset === 'custom') return customWidth;
+        return p.width;
+    }, [preset, customWidth]);
+
+    return { preset, setPreset, customWidth, setCustomWidth, width };
+};
+
+// ─── Background Hook ──────────────────────────────────────────────────────────
+
+type BgPreset = 'default' | 'white' | 'dark' | 'checker';
+
+const BG_PRESETS: { key: BgPreset; label: string; title: string }[] = [
+    { key: 'default', label: '默认', title: '跟随主题' },
+    { key: 'white',   label: '白色', title: '白色背景' },
+    { key: 'dark',    label: '深色', title: '深色背景' },
+    { key: 'checker', label: '棋盘', title: '透明检测' },
+];
+
+const BG_KEY = 'snack-dev-bg';
+
+const useBgPreset = () => {
+    const [bg, setBg] = useState<BgPreset>(() => {
+        try { return (localStorage.getItem(BG_KEY) as BgPreset) || 'default'; } catch { return 'default'; }
+    });
+    const set = useCallback((v: BgPreset) => {
+        setBg(v);
+        try { localStorage.setItem(BG_KEY, v); } catch {}
+    }, []);
+    return { bg, set };
+};
+
+// ─── Scale Hook ───────────────────────────────────────────────────────────────
+
+const SCALE_PRESETS = [50, 75, 100, 125, 150];
+const SCALE_KEY = 'snack-dev-scale';
+
+const useScale = () => {
+    const [scale, setScale] = useState<number>(() => {
+        try { return Number(localStorage.getItem(SCALE_KEY)) || 100; } catch { return 100; }
+    });
+    const set = useCallback((v: number) => {
+        setScale(v);
+        try { localStorage.setItem(SCALE_KEY, String(v)); } catch {}
+    }, []);
+    return { scale, set };
+};
+
 // ─── Sidebar ──────────────────────────────────────────────────────────────────
 
 const Sidebar = ({ projectPkg, version, packages, dark, onToggleTheme }: any) => {
@@ -228,12 +298,155 @@ const HomeView = ({ packages, mosuleMaps, onOpen }: any) => (
     </div>
 );
 
+// ─── Topbar Tools ─────────────────────────────────────────────────────────────
+
+/** 视口尺寸切换 */
+const ViewportToggle = ({ preset, setPreset, customWidth, setCustomWidth }: any) => {
+    const [editing, setEditing] = useState(false);
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const handleCustomClick = () => {
+        setPreset('custom');
+        setEditing(true);
+        setTimeout(() => inputRef.current?.select(), 0);
+    };
+
+    const handleInputBlur = () => setEditing(false);
+    const handleInputKeyDown = (e: React.KeyboardEvent) => {
+        if (e.key === 'Enter') (e.target as HTMLInputElement).blur();
+    };
+    const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+        const v = parseInt(e.target.value, 10);
+        if (!isNaN(v) && v > 0) setCustomWidth(v);
+    };
+
+    return (
+        <div className="sd-topbar__group">
+            <span className="sd-topbar__group-label">视口</span>
+            <div className="sd-topbar__seg">
+                {VIEWPORT_PRESETS.filter(p => p.key !== 'custom').map(p => (
+                    <button
+                        key={p.key}
+                        className={`sd-topbar__seg-btn ${preset === p.key ? 'sd-topbar__seg-btn--active' : ''}`}
+                        onClick={() => setPreset(p.key)}
+                        title={p.width ? `${p.width}px` : '全宽'}
+                    >
+                        {p.label}
+                    </button>
+                ))}
+                {preset === 'custom' && editing ? (
+                    <input
+                        ref={inputRef}
+                        className="sd-topbar__custom-input"
+                        type="number"
+                        min={1}
+                        defaultValue={customWidth}
+                        onChange={handleInputChange}
+                        onBlur={handleInputBlur}
+                        onKeyDown={handleInputKeyDown}
+                    />
+                ) : (
+                    <button
+                        className={`sd-topbar__seg-btn ${preset === 'custom' ? 'sd-topbar__seg-btn--active' : ''}`}
+                        onClick={handleCustomClick}
+                        title="自定义宽度"
+                    >
+                        {preset === 'custom' ? `${customWidth}px` : '自定义'}
+                    </button>
+                )}
+            </div>
+        </div>
+    );
+};
+
+/** 背景切换 */
+const BgToggle = ({ bg, set }: any) => (
+    <div className="sd-topbar__group">
+        <span className="sd-topbar__group-label">背景</span>
+        <div className="sd-topbar__seg">
+            {BG_PRESETS.map(p => (
+                <button
+                    key={p.key}
+                    className={`sd-topbar__seg-btn ${bg === p.key ? 'sd-topbar__seg-btn--active' : ''}`}
+                    onClick={() => set(p.key)}
+                    title={p.title}
+                >
+                    {p.key === 'checker' ? (
+                        <span className="sd-checker-icon" />
+                    ) : p.label}
+                </button>
+            ))}
+        </div>
+    </div>
+);
+
+/** 缩放控制 */
+const ScaleToggle = ({ scale, set }: any) => (
+    <div className="sd-topbar__group">
+        <span className="sd-topbar__group-label">缩放</span>
+        <div className="sd-topbar__seg">
+            {SCALE_PRESETS.map(v => (
+                <button
+                    key={v}
+                    className={`sd-topbar__seg-btn ${scale === v ? 'sd-topbar__seg-btn--active' : ''}`}
+                    onClick={() => set(v)}
+                >
+                    {v}%
+                </button>
+            ))}
+        </div>
+    </div>
+);
+
+/** 刷新模块 */
+const RefreshBtn = ({ onRefresh }: any) => (
+    <button className="sd-topbar__icon-btn" onClick={onRefresh} title="重新挂载模块">
+        <svg width="13" height="13" viewBox="0 0 13 13" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round">
+            <path d="M11.5 2.5A5.5 5.5 0 1 0 12 7"/>
+            <path d="M12 2.5V5.5H9"/>
+        </svg>
+    </button>
+);
+
+// ─── Pane Content Wrapper ─────────────────────────────────────────────────────
+
+const PaneContent = ({ width, scale, bg, children }: any) => {
+    const style: React.CSSProperties = {};
+    if (width) {
+        style.width = width;
+        style.margin = '0 auto';
+        style.flexShrink = 0;
+    }
+    if (scale !== 100) {
+        style.transform = `scale(${scale / 100})`;
+        style.transformOrigin = 'top left';
+        if (width) {
+            style.width = width;
+        }
+    }
+    return (
+        <div className={`sd-pane__content sd-pane__content--bg-${bg}`}>
+            <div style={style}>
+                {children}
+            </div>
+        </div>
+    );
+};
+
 // ─── Debug View ───────────────────────────────────────────────────────────────
 
 const DebugView = ({ arg, mosuleMaps, sdk, settingPanel, onBack, packages }: any) => {
     const mod = mosuleMaps[arg.name];
     const pkgInfo = packages.find((p: any) => p.name === arg.name);
 
+    // topbar 状态
+    const { preset, setPreset, customWidth, setCustomWidth, width } = useViewport();
+    const { bg, set: setBg } = useBgPreset();
+    const { scale, set: setScale } = useScale();
+    const [refreshKey, setRefreshKey] = useState(0);
+
+    const handleRefresh = useCallback(() => setRefreshKey(k => k + 1), []);
+
     const { Module, SettingFC, tips } = useMemo(() => {
         if (!mod) return { Module: null, SettingFC: null, tips: null };
 
@@ -264,7 +477,7 @@ const DebugView = ({ arg, mosuleMaps, sdk, settingPanel, onBack, packages }: any
             </div>
         );
         return { Module: ModuleFC, SettingFC: ModuleSettingFC, tips: warn };
-    }, [arg.name, arg.setting]);
+    }, [arg.name, arg.setting, refreshKey]);
 
     if (!mod) {
         return (
@@ -316,6 +529,22 @@ const DebugView = ({ arg, mosuleMaps, sdk, settingPanel, onBack, packages }: any
                         </button>
                     )}
                 </div>
+                <div className="sd-topbar__sep" />
+                {/* 工具区 */}
+                <div className="sd-topbar__tools">
+                    <ViewportToggle
+                        preset={preset}
+                        setPreset={setPreset}
+                        customWidth={customWidth}
+                        setCustomWidth={setCustomWidth}
+                    />
+                    <div className="sd-topbar__tool-sep" />
+                    <BgToggle bg={bg} set={setBg} />
+                    <div className="sd-topbar__tool-sep" />
+                    <ScaleToggle scale={scale} set={setScale} />
+                    <div className="sd-topbar__tool-sep" />
+                    <RefreshBtn onRefresh={handleRefresh} />
+                </div>
             </div>
 
             <div className="sd-debug__body">
@@ -326,9 +555,9 @@ const DebugView = ({ arg, mosuleMaps, sdk, settingPanel, onBack, packages }: any
                                 <svg width="8" height="9" viewBox="0 0 8 9" fill="currentColor"><path d="M0 0v9l8-4.5L0 0z"/></svg>
                                 主模块
                             </div>
-                            <div className="sd-pane__content">
-                                {Module && <Module />}
-                            </div>
+                            <PaneContent width={width} scale={scale} bg={bg}>
+                                {Module && <Module key={refreshKey} />}
+                            </PaneContent>
                         </div>
                         <div className="sd-pane__divider" />
                         <div className="sd-pane sd-pane--right">
@@ -336,17 +565,17 @@ const DebugView = ({ arg, mosuleMaps, sdk, settingPanel, onBack, packages }: any
                                 <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.2"><circle cx="5.5" cy="5.5" r="1.8"/><path d="M5.5.5v1M5.5 9.5v1M.5 5.5h1M9.5 5.5h1M2 2l.7.7M8.3 8.3l.7.7M2 9l.7-.7M8.3 2.7l.7-.7"/></svg>
                                 设置模块
                             </div>
-                            <div className="sd-pane__content">
+                            <PaneContent width={width} scale={scale} bg={bg}>
                                 {tips}
-                                {SettingFC && <SettingFC />}
-                            </div>
+                                {SettingFC && <SettingFC key={refreshKey} />}
+                            </PaneContent>
                         </div>
                     </>
                 ) : (
                     <div className="sd-pane sd-pane--full">
-                        <div className="sd-pane__content">
-                            {Module && <Module />}
-                        </div>
+                        <PaneContent width={width} scale={scale} bg={bg}>
+                            {Module && <Module key={refreshKey} />}
+                        </PaneContent>
                     </div>
                 )}
             </div>
@@ -392,4 +621,4 @@ const App = (props: Props) => {
     );
 };
 
-export default App;
+export default App;

package/template/dev/index.scss

@@ -581,6 +581,123 @@ button {
     }
 }
 
+// ─── Topbar Tools ─────────────────────────────────────────────────────────────
+
+.sd-topbar__tools {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    flex-shrink: 0;
+    overflow-x: auto;
+    min-width: 0;
+
+    &::-webkit-scrollbar { display: none; }
+}
+
+.sd-topbar__tool-sep {
+    width: 1px;
+    height: 14px;
+    background: var(--border);
+    flex-shrink: 0;
+}
+
+.sd-topbar__group {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+    flex-shrink: 0;
+}
+
+.sd-topbar__group-label {
+    font-size: 10px;
+    font-family: var(--font-mono);
+    color: var(--text-3);
+    letter-spacing: .04em;
+    white-space: nowrap;
+}
+
+.sd-topbar__seg {
+    display: flex;
+    align-items: center;
+    background: var(--bg-2);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-sm);
+    overflow: hidden;
+}
+
+.sd-topbar__seg-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 3px 8px;
+    font-size: 11px;
+    color: var(--text-2);
+    white-space: nowrap;
+    transition: background .12s, color .12s;
+    min-width: 32px;
+    line-height: 1;
+
+    &:hover { background: var(--bg-3); color: var(--text); }
+
+    &--active {
+        background: var(--bg-1);
+        color: var(--accent-a);
+        box-shadow: 0 0 0 1px rgba(71,218,181,.3) inset;
+    }
+
+    & + & {
+        border-left: 1px solid var(--border-soft);
+    }
+}
+
+.sd-topbar__custom-input {
+    width: 58px;
+    padding: 3px 6px;
+    font-size: 11px;
+    font-family: var(--font-mono);
+    color: var(--accent-a);
+    background: var(--bg-1);
+    border: none;
+    outline: none;
+    border-left: 1px solid var(--border-soft);
+    text-align: center;
+
+    &::-webkit-inner-spin-button,
+    &::-webkit-outer-spin-button { -webkit-appearance: none; }
+}
+
+.sd-topbar__icon-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 26px;
+    height: 26px;
+    border-radius: var(--radius-sm);
+    color: var(--text-3);
+    transition: background .15s, color .15s;
+    flex-shrink: 0;
+
+    &:hover {
+        background: var(--bg-2);
+        color: var(--accent-a);
+    }
+}
+
+// 棋盘格图标
+.sd-checker-icon {
+    display: inline-block;
+    width: 10px;
+    height: 10px;
+    background-image:
+        linear-gradient(45deg, var(--text-3) 25%, transparent 25%),
+        linear-gradient(-45deg, var(--text-3) 25%, transparent 25%),
+        linear-gradient(45deg, transparent 75%, var(--text-3) 75%),
+        linear-gradient(-45deg, transparent 75%, var(--text-3) 75%);
+    background-size: 5px 5px;
+    background-position: 0 0, 0 2.5px, 2.5px -2.5px, -2.5px 0;
+    border-radius: 1px;
+}
+
 // ─── Debug Body + Panes ───────────────────────────────────────────────────────
 
 .sd-debug__body {
@@ -625,6 +742,31 @@ button {
     flex: 1;
     overflow: auto;
     padding: 16px;
+    transition: background .2s;
+
+    // 背景模式
+    &--bg-default { background: var(--bg); }
+    &--bg-white   { background: #ffffff; }
+    &--bg-dark    { background: #1a1a1a; }
+    &--bg-checker {
+        background-color: #e0e0e0;
+        background-image:
+            linear-gradient(45deg, #bbb 25%, transparent 25%),
+            linear-gradient(-45deg, #bbb 25%, transparent 25%),
+            linear-gradient(45deg, transparent 75%, #bbb 75%),
+            linear-gradient(-45deg, transparent 75%, #bbb 75%);
+        background-size: 16px 16px;
+        background-position: 0 0, 0 8px, 8px -8px, -8px 0;
+
+        [data-theme="dark"] & {
+            background-color: #2a2a2a;
+            background-image:
+                linear-gradient(45deg, #333 25%, transparent 25%),
+                linear-gradient(-45deg, #333 25%, transparent 25%),
+                linear-gradient(45deg, transparent 75%, #333 75%),
+                linear-gradient(-45deg, transparent 75%, #333 75%);
+        }
+    }
 }
 
 // ─── Debug Error ─────────────────────────────────────────────────────────────