@quicktvui/web-cli 1.0.0-beta.1

package/README.md

@@ -0,0 +1,185 @@
+# @quicktvui/web-cli
+
+QuickTVUI Web 开发服务器 CLI 工具，零配置启动 Web 渲染开发环境。
+
+## 安装
+
+```bash
+npm install @quicktvui/web-cli --save-dev
+# 或
+yarn add @quicktvui/web-cli --dev
+# 或
+pnpm add @quicktvui/web-cli -D
+```
+
+## 使用
+
+### 基本用法
+
+```bash
+# 安装后直接运行
+npx qt-web-dev
+
+# 或在 package.json 中添加脚本
+{
+  "scripts": {
+    "web:dev": "qt-web-dev"
+  }
+}
+```
+
+### 命令行选项
+
+```
+用法: qt-web-dev [options]
+
+选项:
+  -p, --port <port>     开发服务器端口 (默认: 39001)
+  -c, --config <path>   自定义 webpack 配置文件路径
+  -o, --open            自动打开浏览器
+  -h, --help            显示帮助信息
+
+示例:
+  qt-web-dev
+  qt-web-dev --port 8080
+  qt-web-dev --config ./my.webpack.js
+```
+
+## 入口文件检测规则
+
+CLI 会自动检测项目入口，优先级如下：
+
+### 1. webMain 配置（推荐）
+
+如果 `package.json` 中配置了 `webMain`，直接使用该入口：
+
+```json
+{
+  "main": "./src/main.ts",
+  "webMain": "./src/main-web.js"
+}
+```
+
+### 2. 本地 src/web 目录
+
+如果没有 `webMain` 但存在 `src/web/index.js`，CLI 会：
+- 使用 `src/web` 目录作为 Web 渲染器
+- 自动包装 `main` 指定的入口文件
+
+### 3. @quicktvui/web-renderer 包
+
+如果以上都不满足，CLI 会：
+- 使用 `@quicktvui/web-renderer` 包作为渲染器
+- 自动包装 `main` 指定的入口文件
+
+## 项目结构示例
+
+### 方式一：独立 webMain 入口（推荐）
+
+```
+project/
+├── package.json        # 配置 webMain
+├── src/
+│   ├── main.ts         # 原生入口
+│   ├── main-web.js     # Web 入口（自定义初始化逻辑）
+│   └── web/            # Web 渲染器
+│       ├── index.js
+│       ├── core/
+│       └── components/
+└── ...
+```
+
+```json
+// package.json
+{
+  "main": "./src/main.ts",
+  "webMain": "./src/main-web.js"
+}
+```
+
+### 方式二：零配置模式
+
+```
+project/
+├── package.json        # 无需配置 webMain
+├── src/
+│   ├── main.ts         # 主入口
+│   └── web/            # Web 渲染器（CLI 自动检测）
+│       ├── index.js
+│       └── core/
+└── ...
+```
+
+### 方式三：使用 web-renderer 包
+
+```
+project/
+├── package.json
+├── src/
+│   └── main.ts         # 主入口
+└── ...
+```
+
+```json
+// package.json
+{
+  "dependencies": {
+    "@quicktvui/web-renderer": "^1.0.0"
+  }
+}
+```
+
+## 内置功能
+
+### 自动代理
+
+CLI 内置代理功能，解决开发环境跨域问题：
+
+```
+/proxy/{protocol}/{host}{path}
+
+示例:
+/proxy/https/api.example.com/users
+  -> https://api.example.com/users
+```
+
+### 自动检测路径别名
+
+自动读取 `jsconfig.json` 或 `tsconfig.json` 中的路径配置：
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@components/*": ["src/components/*"]
+    }
+  }
+}
+```
+
+### OpenSSL 兼容
+
+自动检测 OpenSSL 版本，对于 OpenSSL 3.x 自动添加 `--openssl-legacy-provider` 参数。
+
+## 自定义 Webpack 配置
+
+如需自定义配置，可通过 `--config` 指定：
+
+```bash
+qt-web-dev --config ./webpack.config.js
+```
+
+自定义配置会完全替换内置配置。
+
+## 技术栈
+
+- Vue 3 + TypeScript
+- Webpack 5
+- vue-loader
+- @extscreen/es3-vue-css-loader
+
+## License
+
+MIT

package/bin/qt-web-dev.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * QuickTVUI Web Dev CLI
+ * 启动 web 开发服务器，无需手动配置入口文件
+ */
+
+const path = require('path')
+const fs = require('fs')
+const signale = require('signale')
+const minimist = require('minimist')
+const { exec } = require('shelljs')
+
+// 解析命令行参数
+const args = minimist(process.argv.slice(2), {
+  string: ['port', 'config'],
+  boolean: ['help', 'open'],
+  alias: {
+    p: 'port',
+    c: 'config',
+    h: 'help',
+    o: 'open',
+  },
+  default: {
+    port: 39001,
+    open: false,
+  },
+})
+
+// 显示帮助信息
+if (args.help) {
+  console.log(`
+QuickTVUI Web Dev CLI
+
+Usage:
+  qt-web-dev [options]
+
+Options:
+  -p, --port <port>     开发服务器端口 (默认: 39001)
+  -c, --config <path>   自定义 webpack 配置文件路径
+  -o, --open            自动打开浏览器
+  -h, --help            显示帮助信息
+
+Examples:
+  qt-web-dev
+  qt-web-dev --port 8080
+  qt-web-dev --config ./my.webpack.js
+
+特点:
+  - 自动检测项目入口，优先使用 webMain
+  - 若无 webMain，自动使用 src/web 或 @quicktvui/web-renderer 包
+  - 零配置启动 web 开发服务器
+  `)
+  process.exit(0)
+}
+
+async function main() {
+  signale.pending('正在启动 QuickTVUI Web 开发服务器...')
+
+  // 查找项目根目录
+  const projectRoot = findProjectRoot()
+  if (!projectRoot) {
+    signale.error('无法找到项目根目录')
+    process.exit(1)
+  }
+
+  signale.info(`项目根目录: ${projectRoot}`)
+
+  // 读取 package.json
+  let pkg = {}
+  try {
+    pkg = require(path.join(projectRoot, 'package.json'))
+  } catch (e) {}
+
+  // 检测入口文件
+  let mainEntry
+  let entryType
+
+  if (pkg.webMain) {
+    // 项目已有 webMain，直接使用
+    mainEntry = pkg.webMain
+    entryType = 'webmain'
+    signale.info(`主入口: ${mainEntry} (webMain)`)
+  } else if (fs.existsSync(path.join(projectRoot, 'src/web/index.js'))) {
+    // 有 src/web 目录，使用 entry-local.js 包装 main
+    mainEntry = pkg.main || './src/main.ts'
+    entryType = 'local'
+    signale.info(`主入口: ${mainEntry}`)
+    signale.info(`Web 渲染器: src/web (本地)`)
+  } else {
+    // 使用 @quicktvui/web-renderer 包
+    mainEntry = pkg.main || './src/main.ts'
+    entryType = 'package'
+    signale.info(`主入口: ${mainEntry}`)
+    signale.info(`Web 渲染器: @quicktvui/web-renderer (包)`)
+  }
+
+  const mainEntryPath = path.resolve(projectRoot, mainEntry)
+
+  // 获取 webpack 配置
+  let webpackConfigPath
+  if (args.config) {
+    webpackConfigPath = path.resolve(projectRoot, args.config)
+  } else {
+    webpackConfigPath = path.resolve(__dirname, '../lib/webpack.config.js')
+  }
+
+  // 设置环境变量
+  process.env.NODE_ENV = 'development'
+  process.env.QUICKTVUI_PROJECT_ROOT = projectRoot
+  process.env.QUICKTVUI_MAIN_ENTRY = mainEntryPath
+  process.env.QUICKTVUI_ENTRY_TYPE = entryType
+  process.env.QUICKTVUI_PORT = String(args.port)
+
+  // 检测 OpenSSL 版本
+  const needLegacyProvider = checkOpenSSLVersion(process.versions.openssl)
+  let nodeOptions = ''
+  if (needLegacyProvider) {
+    nodeOptions = '--openssl-legacy-provider'
+    signale.warn(`检测到 OpenSSL ${process.versions.openssl}，已添加 --openssl-legacy-provider`)
+  }
+
+  // 构建 webpack 命令
+  const webpackArgs = ['serve', `--config "${webpackConfigPath}"`, `--port ${args.port}`, '--color']
+  if (args.open) webpackArgs.push('--open')
+
+  const envPrefix = nodeOptions ? `NODE_OPTIONS="${nodeOptions}" ` : ''
+  const webpackCmd = `${envPrefix}npx webpack ${webpackArgs.join(' ')}`
+
+  signale.pending(`执行: ${webpackCmd}`)
+
+  const result = exec(webpackCmd, { stdio: 'inherit' })
+  if (result.code !== 0) {
+    signale.error('启动开发服务器失败')
+    process.exit(1)
+  }
+}
+
+function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = startDir
+  while (currentDir !== path.dirname(currentDir)) {
+    if (fs.existsSync(path.join(currentDir, 'package.json'))) {
+      return currentDir
+    }
+    currentDir = path.dirname(currentDir)
+  }
+  return null
+}
+
+function checkOpenSSLVersion(version) {
+  if (!version) return false
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version)
+  if (!match) return false
+  return parseInt(match[1], 10) >= 3
+}
+
+main().catch((err) => {
+  signale.error('启动失败:', err)
+  process.exit(1)
+})

package/lib/entry-local.js

@@ -0,0 +1,214 @@
+/**
+ * @quicktvui/web-cli - 本地入口文件
+ * 使用项目本地的 src/web 目录
+ *
+ * 路径变量通过 webpack DefinePlugin 注入（预计算完整路径）
+ */
+
+console.log('[Web Renderer] === Starting initialization (local) ===')
+
+// 路径变量已通过 webpack DefinePlugin 注入
+const projectRoot = __QUICKTVUI_PROJECT_ROOT__
+const mainEntry = __QUICKTVUI_MAIN_ENTRY__
+
+// 1. 初始化 asyncLocalStorage
+const { initAsyncLocalStorage } = require(__QUICKTVUI_MODULE_ASYNC_LOCAL_STORAGE__)
+initAsyncLocalStorage()
+
+// 2. 初始化自动代理
+const { initAutoProxy } = require(__QUICKTVUI_MODULE_AUTO_PROXY__)
+initAutoProxy()
+
+// 3. 初始化全局组件注册
+global.__WEB_COMPONENTS__ = global.__WEB_COMPONENTS__ || {}
+
+// 4. 设置 SceneBuilder
+const { setupSceneBuilder } = require(__QUICKTVUI_MODULE_SCENE_BUILDER__)
+setupSceneBuilder()
+
+// 5. 创建 Web 引擎
+const { createWebEngine, startWebEngine, APP_NAME } = require(__QUICKTVUI_MODULE_WEB_ENGINE__)
+const engine = createWebEngine()
+
+// 6. 应用所有补丁
+const { applyAllPatches } = require(__QUICKTVUI_MODULE_PATCHES__)
+applyAllPatches(engine)
+
+// 7. 初始化 TV 焦点管理器
+const { TVFocusManager } = require(__QUICKTVUI_MODULE_TV_FOCUS_MANAGER__)
+const focusManager = new TVFocusManager()
+global.__TV_FOCUS_MANAGER__ = focusManager
+console.log('[Web Renderer] TVFocusManager initialized')
+
+// 8. 注入全局 CSS
+const styleEl = document.createElement('style')
+styleEl.id = 'web-platform-reset'
+styleEl.textContent = `
+  /* Web-Android Layout Compatibility Reset */
+  #app, #app * { align-items: flex-start; }
+  [style*="align-items"] { align-items: var(--align-items, center) !important; }
+`
+document.head.appendChild(styleEl)
+console.log('[Web Renderer] Global CSS reset injected')
+
+// 9. 设置 appRegister 代理
+setupAppRegisterProxy()
+
+// 主入口文件已通过 webpack 多入口配置加载，无需在此处 require
+
+// 10. 启动引擎
+console.log('[Web Renderer] Starting engine...')
+startWebEngine(engine, APP_NAME)
+console.log('[Web Renderer] === Initialization complete ===')
+
+// ============================================================================
+// 辅助函数
+// ============================================================================
+
+let lifecycleSetupDone = false
+
+function setupAppRegisterProxy() {
+  global.__GLOBAL__ = global.__GLOBAL__ || {}
+  const appRegister = {}
+
+  global.__GLOBAL__.appRegister = new Proxy(appRegister, {
+    set(target, appName, appEntry) {
+      console.log('[Web Renderer] App registering:', appName)
+
+      const originalRun = appEntry.run
+      if (typeof originalRun === 'function') {
+        appEntry.run = function (superProps) {
+          console.log('[Web Renderer] App starting:', appName)
+          const normalizedProps = normalizeSuperProps(superProps)
+          const result = originalRun.call(this, normalizedProps)
+          setupLifecycleAndGuards()
+          return result
+        }
+      }
+
+      target[appName] = appEntry
+      return true
+    },
+    get(target, prop) {
+      return target[prop]
+    },
+  })
+
+  console.log('[Web Renderer] AppRegister proxy installed')
+}
+
+function normalizeSuperProps(superProps) {
+  if (!superProps) return superProps
+  const result = { ...superProps }
+
+  if (result.location) {
+    const location = result.location
+    if (typeof location === 'string') {
+      if (location !== '/') {
+        result.path = location
+      }
+      delete result.location
+    } else if (typeof location === 'object') {
+      if (location.name) {
+        result.name = location.name
+      } else if (location.path) {
+        result.path = location.path
+      }
+      delete result.location
+    }
+  }
+
+  return result
+}
+
+function setupLifecycleAndGuards() {
+  if (lifecycleSetupDone) return
+
+  setTimeout(() => {
+    const app = findVueApp()
+    const router = findVueRouter(app)
+
+    if (app) {
+      const { setupPageLifecycle } = require(__QUICKTVUI_MODULE_PAGE_LIFECYCLE__)
+      setupPageLifecycle(app)
+      console.log('[Web Renderer] Page lifecycle setup complete')
+    }
+
+    if (router) {
+      global.__ES_ROUTER__ = router
+      addMainRouteRedirect(router)
+
+      const { setupRouterGuard, setupBrowserBackInterceptor } = require(
+        __QUICKTVUI_MODULE_PAGE_LIFECYCLE__
+      )
+      setupRouterGuard(router)
+      setupBrowserBackInterceptor()
+      console.log('[Web Renderer] Router guard setup complete')
+    }
+
+    lifecycleSetupDone = true
+  }, 150)
+}
+
+function findVueApp() {
+  const rootEl = document.getElementById('root')
+  if (rootEl?.__vue_app__) return rootEl.__vue_app__
+
+  const appEl = document.getElementById('app')
+  if (appEl?.__vue_app__) return appEl.__vue_app__
+
+  if (typeof __webpack_require__ !== 'undefined') {
+    try {
+      const cache = __webpack_require__.c
+      for (const moduleId in cache) {
+        const module = cache[moduleId]
+        if (!module) continue
+        const exports = module.exports || module
+        if (exports && typeof exports === 'object') {
+          if (exports.app && typeof exports.app.use === 'function') return exports.app
+          if (exports.default?.app && typeof exports.default.app.use === 'function')
+            return exports.default.app
+        }
+      }
+    } catch (e) {}
+  }
+
+  return null
+}
+
+function findVueRouter(app) {
+  if (!app) return null
+
+  const router = app.config?.globalProperties?.$router
+  if (router && typeof router.push === 'function') return router
+
+  const provides = app._context?.provides
+  if (provides) {
+    for (const key of Object.keys(provides)) {
+      const val = provides[key]
+      if (val && typeof val.push === 'function' && typeof val.beforeEach === 'function') {
+        return val
+      }
+    }
+  }
+
+  return null
+}
+
+function addMainRouteRedirect(router) {
+  if (!router) return
+
+  const mainRouteName = router.options?.main
+  if (!mainRouteName) return
+
+  const routes = router.options?.routes || []
+  const hasRootPath = routes.some((r) => r.path === '/')
+
+  if (!hasRootPath) {
+    router.addRoute({
+      path: '/',
+      redirect: { name: mainRouteName },
+    })
+    console.log('[Web Renderer] Added "/" redirect to main route:', mainRouteName)
+  }
+}

package/lib/entry-package.js

@@ -0,0 +1,16 @@
+// @quicktvui/web-cli - web entry (package)
+// 此文件由 CLI 自动加载，使用 @quicktvui/web-renderer 包
+// 主入口路径通过 __QUICKTVUI_MAIN_ENTRY__ 注入
+
+console.log('[Web Renderer] === Starting initialization ===')
+
+import { initWebRenderer, startWebRenderer } from '@quicktvui/web-renderer'
+
+initWebRenderer()
+
+console.log('[Web Renderer] Importing main module...')
+import(__QUICKTVUI_MAIN_ENTRY__)
+
+console.log('[Web Renderer] Starting engine...')
+startWebRenderer()
+console.log('[Web Renderer] === Initialization complete ===')

package/lib/index.js

@@ -0,0 +1,166 @@
+/**
+ * QuickTVUI Web CLI
+ * 主入口 - 提供编程接口
+ */
+
+const path = require('path')
+const fs = require('fs')
+
+const pkg = require('../package.json')
+
+/**
+ * 查找项目根目录
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let currentDir = startDir
+  while (currentDir !== path.dirname(currentDir)) {
+    if (fs.existsSync(path.join(currentDir, 'package.json'))) {
+      return currentDir
+    }
+    currentDir = path.dirname(currentDir)
+  }
+  return null
+}
+
+/**
+ * 检测 web renderer 类型
+ */
+function detectWebRendererType(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'src/web/index.js'))) {
+    return 'local'
+  }
+  try {
+    const projectPkg = require(path.join(projectRoot, 'package.json'))
+    const deps = { ...projectPkg?.dependencies, ...projectPkg?.devDependencies }
+    if (deps['@quicktvui/web-renderer']) {
+      return 'package'
+    }
+  } catch (e) {}
+  return 'package'
+}
+
+/**
+ * 生成 web 入口内容
+ */
+function generateWebEntryContent(projectRoot, mainEntry) {
+  const mainPath =
+    './' + path.relative(projectRoot, path.resolve(projectRoot, mainEntry)).replace(/\\/g, '/')
+  const type = detectWebRendererType(projectRoot)
+
+  if (type === 'local') {
+    return getLocalEntryContent(mainPath)
+  }
+  return getPackageEntryContent(mainPath)
+}
+
+function getLocalEntryContent(mainPath) {
+  return `// @quicktvui/web-cli - auto-generated entry (local)
+console.log('[Web Renderer] === Starting initialization ===')
+
+import { initAsyncLocalStorage } from '../src/web/core/asyncLocalStorage'
+initAsyncLocalStorage()
+
+import { initAutoProxy } from '../src/web/core/autoProxy'
+initAutoProxy()
+
+global.__WEB_COMPONENTS__ = global.__WEB_COMPONENTS__ || {}
+
+import { setupSceneBuilder } from '../src/web/core/SceneBuilder'
+setupSceneBuilder()
+
+import { createWebEngine, startWebEngine, APP_NAME } from '../src/web'
+const engine = createWebEngine()
+
+import { applyAllPatches } from '../src/web/core/patches'
+applyAllPatches(engine)
+
+import { TVFocusManager } from '../src/web/core/TVFocusManager'
+const focusManager = new TVFocusManager()
+global.__TV_FOCUS_MANAGER__ = focusManager
+
+setupAppRegisterProxy()
+
+console.log('[Web Renderer] Importing main module...')
+import '${mainPath}'
+
+console.log('[Web Renderer] Starting engine...')
+startWebEngine(engine, APP_NAME)
+console.log('[Web Renderer] === Initialization complete ===')
+
+function setupAppRegisterProxy() {
+  global.__GLOBAL__ = global.__GLOBAL__ || {}
+  const appRegister = {}
+  let lifecycleDone = false
+  global.__GLOBAL__.appRegister = new Proxy(appRegister, {
+    set(t, name, entry) {
+      const run = entry.run
+      if (typeof run === 'function') {
+        entry.run = function(p) {
+          const r = run.call(this, normalize(p))
+          setupLifecycle()
+          return r
+        }
+      }
+      t[name] = entry
+      return true
+    },
+    get(t, p) { return t[p] }
+  })
+}
+
+function normalize(p) {
+  if (!p) return p
+  const r = { ...p }
+  if (r.location) {
+    if (typeof r.location === 'string') {
+      if (r.location !== '/') r.path = r.location
+      delete r.location
+    } else if (typeof r.location === 'object') {
+      if (r.location.name) r.name = r.location.name
+      else if (r.location.path) r.path = r.location.path
+      delete r.location
+    }
+  }
+  return r
+}
+
+function setupLifecycle() {
+  if (lifecycleDone) return
+  lifecycleDone = true
+  setTimeout(() => {
+    const app = document.getElementById('root')?.__vue_app__ || document.getElementById('app')?.__vue_app__
+    const router = app?.config?.globalProperties?.$router
+    if (router) {
+      global.__ES_ROUTER__ = router
+      if (router.options?.main && !router.options?.routes?.some(r => r.path === '/')) {
+        router.addRoute({ path: '/', redirect: { name: router.options.main } })
+      }
+    }
+  }, 150)
+}
+`
+}
+
+function getPackageEntryContent(mainPath) {
+  return `// @quicktvui/web-cli - auto-generated entry (package)
+console.log('[Web Renderer] === Starting initialization ===')
+
+import { initWebRenderer, startWebRenderer } from '@quicktvui/web-renderer'
+
+initWebRenderer()
+
+console.log('[Web Renderer] Importing main module...')
+import '${mainPath}'
+
+console.log('[Web Renderer] Starting engine...')
+startWebRenderer()
+console.log('[Web Renderer] === Initialization complete ===')
+`
+}
+
+module.exports = {
+  version: pkg.version,
+  findProjectRoot,
+  detectWebRendererType,
+  generateWebEntryContent,
+}

package/lib/webpack.config.js

@@ -0,0 +1,306 @@
+/**
+ * QuickTVUI Web CLI - 内置 Webpack 配置
+ * 使用固定入口文件，通过 DefinePlugin 注入主入口路径
+ */
+
+const path = require('path')
+const fs = require('fs')
+
+// 从环境变量获取配置
+const projectRoot = process.env.QUICKTVUI_PROJECT_ROOT || process.cwd()
+const mainEntry = process.env.QUICKTVUI_MAIN_ENTRY || path.resolve(projectRoot, 'src/main.ts')
+const entryType = process.env.QUICKTVUI_ENTRY_TYPE || 'package'
+const port = parseInt(process.env.QUICKTVUI_PORT || '39001', 10)
+
+// 尝试加载项目的 package.json
+let pkg = {}
+try {
+  pkg = require(path.join(projectRoot, 'package.json'))
+} catch (e) {}
+
+/**
+ * 自动检测项目路径别名
+ */
+function detectAlias() {
+  const alias = {
+    '@': path.resolve(projectRoot, 'src'),
+    // 使用本地打包的 es3-router
+    '@extscreen/es3-router':
+      '/Volumes/WD/Users/chendd/Documents/huan/es/es-vue3/packages/ESRouter/dist/index.js',
+  }
+
+  const jsconfigPath = path.join(projectRoot, 'jsconfig.json')
+  const tsconfigPath = path.join(projectRoot, 'tsconfig.json')
+  const configPath = fs.existsSync(tsconfigPath) ? tsconfigPath : jsconfigPath
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const config = require(configPath)
+      const paths = config.compilerOptions?.paths || {}
+      for (const [key, value] of Object.entries(paths)) {
+        if (Array.isArray(value) && value[0]) {
+          const aliasKey = key.replace('/*', '')
+          const aliasValue = path.resolve(
+            projectRoot,
+            config.compilerOptions?.baseUrl || '.',
+            value[0].replace('/*', '')
+          )
+          alias[aliasKey] = aliasValue
+        }
+      }
+    } catch (e) {}
+  }
+
+  return alias
+}
+
+/**
+ * 检测 resolve modules
+ */
+function detectModules() {
+  const modules = []
+  const projectNodeModules = path.join(projectRoot, 'node_modules')
+  if (fs.existsSync(projectNodeModules)) {
+    modules.push(projectNodeModules)
+  }
+  const cwdNodeModules = path.join(process.cwd(), 'node_modules')
+  if (fs.existsSync(cwdNodeModules) && !modules.includes(cwdNodeModules)) {
+    modules.push(cwdNodeModules)
+  }
+  return modules
+}
+
+/**
+ * 检测 CSS loader 类型
+ */
+function detectCSSLoader() {
+  try {
+    require.resolve('@extscreen/es3-vue-css-loader', { paths: [projectRoot] })
+    return '@extscreen/es3-vue-css-loader'
+  } catch (e) {}
+  try {
+    require.resolve('vue-style-loader', { paths: [projectRoot] })
+    return 'vue-style-loader'
+  } catch (e) {}
+  return 'style-loader'
+}
+
+const cssLoader = detectCSSLoader()
+
+// 根据类型选择入口文件
+let entryFiles
+
+if (entryType === 'webmain') {
+  // 直接使用 webMain 作为入口
+  entryFiles = ['regenerator-runtime/runtime', mainEntry]
+} else if (entryType === 'local') {
+  // 使用 entry-local.js + main 入口
+  const entryLocalFile = path.resolve(__dirname, 'entry-local.js')
+  entryFiles = ['regenerator-runtime/runtime', entryLocalFile, mainEntry]
+} else {
+  // 使用 entry-package.js + main 入口
+  const entryPackageFile = path.resolve(__dirname, 'entry-package.js')
+  entryFiles = ['regenerator-runtime/runtime', entryPackageFile, mainEntry]
+}
+
+module.exports = {
+  mode: 'development',
+  bail: true,
+
+  devServer: {
+    port,
+    hot: true,
+    liveReload: true,
+    proxy: [
+      {
+        context: ['/proxy'],
+        target: 'http://placeholder',
+        changeOrigin: true,
+        secure: false,
+        router: (req) => {
+          const match = req.url.match(/^\/proxy\/(https?)\/([^/]+)(\/.*)?$/)
+          if (match) {
+            return `${match[1]}://${match[2]}`
+          }
+          return 'http://placeholder'
+        },
+        pathRewrite: (path, req) => {
+          const match = path.match(/^\/proxy\/(https?)\/[^/]+(\/.*)?$/)
+          if (match) {
+            return match[2] || '/'
+          }
+          return path
+        },
+        onProxyReq: (proxyReq, req, res) => {
+          console.log(
+            `[AutoProxy] ${req.method} ${req.url} -> ${proxyReq.getHeader('host')}${proxyReq.path}`
+          )
+        },
+      },
+    ],
+    static: {
+      directory: path.join(projectRoot, 'public'),
+      publicPath: '/',
+    },
+    client: {
+      overlay: { errors: true, warnings: false },
+    },
+  },
+
+  watchOptions: {
+    aggregateTimeout: 1500,
+    poll: 1000,
+    ignored: /node_modules/,
+  },
+
+  devtool: 'source-map',
+
+  // 多入口配置：先加载初始化代码，再加载主入口
+  entry: {
+    index: entryFiles,
+  },
+
+  output: {
+    filename: 'index.bundle.js',
+    path: path.resolve(projectRoot, './dist/web/'),
+    strictModuleExceptionHandling: true,
+    globalObject: '(0, eval)("this")',
+  },
+
+  plugins: [
+    new (require('vue-loader').VueLoaderPlugin)(),
+    new (require('html-webpack-plugin'))({
+      inject: true,
+      scriptLoading: 'blocking',
+      template: path.resolve(__dirname, '../templates/web-renderer.html'),
+      title: pkg.name || 'QuickTVUI Web',
+    }),
+    // 注入主入口路径和项目根目录，以及预计算的模块路径
+    new (require('webpack').DefinePlugin)({
+      __QUICKTVUI_PROJECT_ROOT__: JSON.stringify(projectRoot),
+      __QUICKTVUI_MAIN_ENTRY__: JSON.stringify(mainEntry),
+      // 预计算 src/web 模块路径（浏览器环境无法使用 path 模块）
+      __QUICKTVUI_MODULE_ASYNC_LOCAL_STORAGE__: JSON.stringify(
+        path.join(projectRoot, 'src/web/core/asyncLocalStorage')
+      ),
+      __QUICKTVUI_MODULE_AUTO_PROXY__: JSON.stringify(
+        path.join(projectRoot, 'src/web/core/autoProxy')
+      ),
+      __QUICKTVUI_MODULE_SCENE_BUILDER__: JSON.stringify(
+        path.join(projectRoot, 'src/web/core/SceneBuilder')
+      ),
+      __QUICKTVUI_MODULE_WEB_ENGINE__: JSON.stringify(path.join(projectRoot, 'src/web')),
+      __QUICKTVUI_MODULE_PATCHES__: JSON.stringify(path.join(projectRoot, 'src/web/core/patches')),
+      __QUICKTVUI_MODULE_TV_FOCUS_MANAGER__: JSON.stringify(
+        path.join(projectRoot, 'src/web/core/TVFocusManager')
+      ),
+      __QUICKTVUI_MODULE_PAGE_LIFECYCLE__: JSON.stringify(
+        path.join(projectRoot, 'src/web/core/pageLifecycle')
+      ),
+      process: JSON.stringify({
+        env: { NODE_ENV: 'development' },
+        browser: true,
+        version: '',
+        versions: {},
+      }),
+      __PLATFORM__: JSON.stringify('web'),
+      __DEV__: JSON.stringify(true),
+    }),
+  ],
+
+  module: {
+    rules: [
+      // Vue 文件
+      {
+        test: /\.vue$/,
+        use: [
+          {
+            loader: 'vue-loader',
+            options: { compilerOptions: { whitespace: 'condense' } },
+          },
+          'scope-loader',
+        ],
+      },
+      // TypeScript 文件
+      {
+        test: /\.ts$/,
+        use: [
+          {
+            loader: 'ts-loader',
+            options: { appendTsSuffixTo: [/\.vue$/], transpileOnly: true },
+          },
+        ],
+      },
+      // JavaScript 文件
+      {
+        test: /\.js$/,
+        exclude: /node_modules/,
+        use: [
+          {
+            loader: 'babel-loader',
+            options: {
+              sourceType: 'unambiguous',
+              presets: [['@babel/preset-env', { targets: { chrome: 57, ios: 9 } }]],
+              plugins: [
+                ['@babel/plugin-proposal-class-properties'],
+                ['@babel/plugin-proposal-decorators', { legacy: true }],
+                ['@babel/plugin-transform-runtime', { regenerator: true }],
+              ],
+            },
+          },
+        ],
+      },
+      // CSS (直接使用 es3-vue-css-loader，不通过 css-loader)
+      { test: /\.css$/, use: [cssLoader] },
+      // Less
+      { test: /\.less$/, use: [cssLoader, 'less-loader'] },
+      // Sass/SCSS
+      { test: /\.scss$/, use: [cssLoader, 'sass-loader'] },
+      { test: /\.sass$/, use: [cssLoader, 'sass-loader'] },
+      // 图片
+      {
+        test: /\.(png|jpe?g|gif|webp|svg)$/i,
+        type: 'asset',
+        parser: { dataUrlCondition: { maxSize: 10000 } },
+        generator: { filename: 'assets/[name].[hash:8][ext]' },
+      },
+      // 字体
+      {
+        test: /\.(woff2?|eot|ttf|otf)$/i,
+        type: 'asset/resource',
+        generator: { filename: 'fonts/[name].[hash:8][ext]' },
+      },
+      // 音频
+      {
+        test: /\.(mp3|wav|ogg|m4a)$/i,
+        type: 'asset/resource',
+        generator: { filename: 'audio/[name].[hash:8][ext]' },
+      },
+    ],
+  },
+
+  resolve: {
+    extensions: ['.web.js', '.web.ts', '.web.vue', '.js', '.vue', '.json', '.ts'],
+    modules: detectModules(),
+    fallback: {
+      fs: false,
+      path: false,
+      crypto: false,
+      stream: false,
+      http: false,
+      https: false,
+      zlib: false,
+    },
+    alias: detectAlias(),
+  },
+
+  performance: { hints: false },
+
+  // 忽略 entry-local.js 中动态 require 的警告（这是预期行为）
+  ignoreWarnings: [/Critical dependency: the request of a dependency is an expression/],
+
+  cache: {
+    type: 'filesystem',
+    buildDependencies: { config: [__filename] },
+  },
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@quicktvui/web-cli",
+  "version": "1.0.0-beta.1",
+  "description": "CLI tool for QuickTVUI web development - zero configuration",
+  "author": "QuickTVUI Team",
+  "license": "Apache-2.0",
+  "bin": {
+    "qt-web-dev": "./bin/qt-web-dev.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin",
+    "lib",
+    "templates"
+  ],
+  "keywords": [
+    "quicktvui",
+    "web",
+    "cli",
+    "tv",
+    "hippy"
+  ],
+  "dependencies": {
+    "minimist": "^1.2.8",
+    "shelljs": "^0.10.0",
+    "signale": "^1.4.0"
+  },
+  "peerDependencies": {
+    "webpack": "^5.0.0",
+    "webpack-cli": "^5.0.0",
+    "webpack-dev-server": "^4.0.0",
+    "vue-loader": "^17.0.0",
+    "html-webpack-plugin": "^5.0.0",
+    "@babel/core": "^7.0.0",
+    "babel-loader": "^9.0.0",
+    "ts-loader": "^9.4.0",
+    "css-loader": "^6.0.0",
+    "extscreen-router": ">=3.0.1"
+  },
+  "peerDependenciesMeta": {
+    "less-loader": { "optional": true },
+    "sass-loader": { "optional": true },
+    "sass": { "optional": true },
+    "less": { "optional": true }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/templates/web-renderer.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title><%= htmlWebpackPlugin.options.title || 'QuickTVUI Web' %></title>
+  <script>
+    // TV dimensions - MUST be set before web-renderer loads
+    const TV_WIDTH = 1920;
+    const TV_HEIGHT = 1080;
+    
+    // Store original values for scale calculation
+    const _originalInnerWidth = window.innerWidth;
+    const _originalInnerHeight = window.innerHeight;
+    
+    // Override innerWidth/innerHeight getters
+    Object.defineProperty(window, 'innerWidth', {
+      get: function() { return TV_WIDTH; },
+      configurable: true
+    });
+    Object.defineProperty(window, 'innerHeight', {
+      get: function() { return TV_HEIGHT; },
+      configurable: true
+    });
+    // Override devicePixelRatio
+    Object.defineProperty(window, 'devicePixelRatio', {
+      get: function() { return 1; },
+      configurable: true
+    });
+    
+    console.log('[Polyfill] Overridden window dimensions to', TV_WIDTH, 'x', TV_HEIGHT);
+    
+    // Initialize focus styles storage
+    window.__TV_FOCUS_STYLES__ = {};
+  </script>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    html, body {
+      width: 100%;
+      height: 100%;
+      overflow: hidden;
+      background-color: #1a1a1a;
+    }
+    #app {
+      width: 1920px !important;
+      height: 1080px !important;
+      transform-origin: top left;
+      background-color: #26292F;
+    }
+    /* 返回按钮样式 */
+    #web-back-btn {
+      position: fixed;
+      z-index: 99999;
+      width: 48px;
+      height: 48px;
+      background: rgba(255, 255, 255, 0.1);
+      border: 2px solid rgba(255, 255, 255, 0.3);
+      border-radius: 50%;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: all 0.2s ease;
+      backdrop-filter: blur(10px);
+    }
+    #web-back-btn:hover {
+      background: rgba(255, 255, 255, 0.2);
+      border-color: rgba(255, 255, 255, 0.5);
+      transform: scale(1.1);
+    }
+    #web-back-btn:active {
+      transform: scale(0.95);
+    }
+    #web-back-btn svg {
+      width: 24px;
+      height: 24px;
+      fill: none;
+      stroke: rgba(255, 255, 255, 0.8);
+      stroke-width: 2;
+      stroke-linecap: round;
+      stroke-linejoin: round;
+    }
+    /* Force all direct children of #app to be 1920x1080 */
+    #app > * {
+      width: 1920px !important;
+      height: 1080px !important;
+      position: relative !important;
+      overflow: hidden !important;
+    }
+    /* TV Focus styles */
+    [focusable="true"], [data-focusable="true"] {
+      cursor: pointer;
+      transition: transform 0.15s ease, box-shadow 0.15s ease;
+    }
+    [focusable="true"].focused, [data-focusable="true"].focused {
+      transform: scale(1.05);
+      box-shadow: 0 0 20px rgba(76, 175, 80, 0.5);
+      z-index: 100;
+    }
+  </style>
+  <script>
+    // Fix #app dimensions immediately when DOM is ready
+    function fixAppDimensions() {
+      var app = document.getElementById('app');
+      if (app) {
+        app.style.setProperty('width', TV_WIDTH + 'px', 'important');
+        app.style.setProperty('height', TV_HEIGHT + 'px', 'important');
+        console.log('[Polyfill] Fixed #app dimensions to', TV_WIDTH, 'x', TV_HEIGHT);
+      }
+    }
+    
+    document.addEventListener('DOMContentLoaded', fixAppDimensions);
+    window.addEventListener('load', fixAppDimensions);
+    
+    // Scale the app to fit the viewport
+    function scaleApp() {
+      var app = document.getElementById('app');
+      if (app) {
+        app.style.setProperty('width', TV_WIDTH + 'px', 'important');
+        app.style.setProperty('height', TV_HEIGHT + 'px', 'important');
+        
+        var scaleX = _originalInnerWidth / TV_WIDTH;
+        var scaleY = _originalInnerHeight / TV_HEIGHT;
+        var scale = Math.min(scaleX, scaleY);
+        app.style.transform = 'scale(' + scale + ')';
+        var offsetX = (_originalInnerWidth - TV_WIDTH * scale) / 2;
+        var offsetY = (_originalInnerHeight - TV_HEIGHT * scale) / 2;
+        app.style.marginLeft = offsetX + 'px';
+        app.style.marginTop = offsetY + 'px';
+
+        // 更新返回按钮位置，相对于 #app 左上角
+        var btn = document.getElementById('web-back-btn');
+        if (btn) {
+          var btnSize = 48 * scale;
+          var btnMargin = 20 * scale;
+          btn.style.width = btnSize + 'px';
+          btn.style.height = btnSize + 'px';
+          btn.style.left = (offsetX + btnMargin) + 'px';
+          btn.style.top = (offsetY + btnMargin) + 'px';
+        }
+      }
+    }
+    window.addEventListener('load', scaleApp);
+    window.addEventListener('resize', scaleApp);
+  </script>
+</head>
+<body>
+  <div id="app"></div>
+  <!-- Web 返回按钮 - 动态定位 -->
+  <button id="web-back-btn" title="返回">
+    <svg viewBox="0 0 24 24">
+      <polyline points="15 18 9 12 15 6"></polyline>
+    </svg>
+  </button>
+  <script>
+    // 返回按钮点击事件
+    document.getElementById('web-back-btn').addEventListener('click', function() {
+      var focusManager = window.__TV_FOCUS_MANAGER__;
+      if (focusManager && typeof focusManager.dispatchBackPressed === 'function') {
+        focusManager.dispatchBackPressed({ key: 'Escape', keyCode: 4 });
+      }
+    });
+  </script>
+</body>
+</html>