@quicktvui/ai 1.1.6 → 1.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai",
-  "version": "1.1.6",
+  "version": "1.1.12",
   "description": "QuickTVUI AI 开发规范与脚手架注入工具",
   "main": "index.js",
   "scripts": {
@@ -20,4 +20,4 @@
     "type": "git",
     "url": "https://github.com/quicktvui/quicktvui-template.git"
   }
-}
+}

package/rules/.claude/commands/create-component.md

@@ -1,3 +1,8 @@
+---
+name: create-component.md
+version: 1.1.12
+---
+
 # 创建 QuickTVUI 组件
 
 按照框架规范创建一个新的 QuickTVUI 组件。

package/rules/.claude/commands/create-page.md

@@ -1,3 +1,8 @@
+---
+name: create-page.md
+version: 1.1.12
+---
+
 # 创建 TV 页面
 
 根据用户需求，创建一个 QuickTVUI TV 页面。

package/rules/.claude/commands/create-project.md

@@ -1,3 +1,8 @@
+---
+name: create-project.md
+version: 1.1.12
+---
+
 # 创建 QuickTVUI 项目
 
 根据用户提供的项目名称，创建一个全新的 QuickTVUI 快应用项目。

package/rules/.claude/commands/lookup-api.md

@@ -1,3 +1,8 @@
+---
+name: lookup-api.md
+version: 1.1.12
+---
+
 # 查询 QuickTVUI 组件 API
 
 根据用户提到的组件名称，查找并展示其 API。

package/rules/.claude/commands/lookup-css.md

@@ -1,3 +1,8 @@
+---
+name: lookup-css.md
+version: 1.1.12
+---
+
 # 查询 QuickTVUI CSS 属性
 
 根据用户的 CSS/布局需求，提供 QuickTVUI 兼容的写法。

package/rules/.clinerules

@@ -1,3 +1,8 @@
+---
+name: .clinerules
+version: 0.6.1
+---
+
 # .clinerules - QuickTVUI AI Development Guide
 
 > Drop this file into any QuickTVUI project root. Works with Cline/Roo-Code.
@@ -77,6 +82,15 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+
+## Game Loop & Timer Constraints (CRITICAL)
+
+- For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+- `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+- All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+- Do NOT create orphan loops/timers without a cancellation path.
+- In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
+
 ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
 
 AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:

package/rules/.cursorrules

@@ -1,3 +1,8 @@
+---
+name: .cursorrules
+version: 0.6.1
+---
+
 # .cursorrules - QuickTVUI AI Development Guide
 
 > Drop this file into any QuickTVUI project root. Works with Cursor.
@@ -77,6 +82,15 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+
+## Game Loop & Timer Constraints (CRITICAL)
+
+- For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+- `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+- All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+- Do NOT create orphan loops/timers without a cancellation path.
+- In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
+
 ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
 
 AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:

package/rules/.github/copilot-instructions.md

@@ -1,3 +1,8 @@
+---
+name: copilot-instructions.md
+version: 1.1.12
+---
+
 # copilot-instructions.md - QuickTVUI AI Development Guide
 
 > Works with GitHub Copilot.
@@ -43,6 +48,15 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
 4. **Install Deps**: `yarn install`
 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
 
+
+## Game Loop & Timer Constraints (CRITICAL)
+
+- For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+- `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+- All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+- Do NOT create orphan loops/timers without a cancellation path.
+- In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
+
 ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
 
 AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:

package/rules/.windsurfrules

@@ -1,3 +1,8 @@
+---
+name: .windsurfrules
+version: 0.6.1
+---
+
 # .windsurfrules - QuickTVUI AI Development Guide
 
 > Drop this file into any QuickTVUI project root. Works with Windsurf.
@@ -77,6 +82,15 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+
+## Game Loop & Timer Constraints (CRITICAL)
+
+- For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+- `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+- All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+- Do NOT create orphan loops/timers without a cancellation path.
+- In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
+
 ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
 
 AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:

package/rules/AGENTS.md

@@ -1,3 +1,8 @@
+---
+name: AGENTS.md
+version: 1.1.12
+---
+
 # AGENTS.md - QuickTVUI AI Development Guide
 
 > Drop this file into any QuickTVUI project root. Works with OpenAI Codex and other AI tools.
@@ -58,8 +63,38 @@ Hard requirements:
 - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
 - AI MUST discover and use existing `quicktvui-ai-cli` commands first (`quicktvui-ai --help`, `quicktvui-ai <command> --help`) for env/device/runtime/run-to-TV operations.
 - If a required step has no corresponding `quicktvui-ai-cli` command, AI MUST explicitly state the CLI gap first, then use a manual fallback workflow.
+- If only one device is connected, AI MUST NOT enforce TV/phone distinction.
 - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
-- AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
+- In multi-device mode, AI MUST distinguish TV-like vs phone/tablet targets, and ask confirmation before continuing with non-TV targets.
+- Emulator targets are treated as TV-like devices.
+- AI MUST NOT auto-download/create Google emulator in setup flow. If no device is available, ask user to install/start emulator manually (recommended: https://mumu.163.com) and then reconnect.
+- Runtime APK download source policy (MANDATORY):
+  - Prefer `http://hub.quicktvui.com/repository/maven-files/` first.
+  - If hub download fails, fallback ONLY to trusted repositories:
+    - `https://gitee.com/quicktvui/quicktvui-runtime-apk`
+    - `https://github.com/quicktvui/quicktvui-runtime-apk`
+  - Metadata entry priority:
+    1) `https://gitee.com/quicktvui/quicktvui-runtime-apk/raw/main/manifests/latest.json`
+    2) `https://raw.githubusercontent.com/quicktvui/quicktvui-runtime-apk/main/manifests/latest.json`
+  - Channel policy:
+    - Default `release`.
+    - If `latest-release.json` has `status: pending` or no usable version, fallback to `debug`.
+    - If user explicitly requests `debug`/`release`, use the requested channel.
+  - Metadata and download flow:
+    1) Read `latest.json` and resolve channel manifest path.
+    2) Read `latest-release.json` or `latest-debug.json`.
+    3) Extract `repo_path` and `sha256`.
+    4) Build URL: `<base>/<repo_path>`, base is:
+       - Gitee: `https://gitee.com/quicktvui/quicktvui-runtime-apk/raw/main`
+       - GitHub: `https://raw.githubusercontent.com/quicktvui/quicktvui-runtime-apk/main`
+    5) Download APK and verify SHA256 before install.
+    6) Install with `adb install -r <apk_file>`.
+- Game Loop & Timer Constraints (CRITICAL):
+  - For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+  - `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+  - All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+  - Do NOT create orphan loops/timers without a cancellation path.
+  - In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
 - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
 - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
 - Recommended check commands:

package/rules/AI_HANDOFF.md

@@ -1,3 +1,8 @@
+---
+name: AI_HANDOFF.md
+version: 1.1.12
+---
+
 # QuickTVUI AI 集成 - 工作交接文档
 
 > 本文档记录了为 QuickTVUI 框架搭建 AI 辅助开发体系的完整过程，供后续 AI 接手改进。

package/rules/CLAUDE.md

@@ -1,3 +1,8 @@
+---
+name: CLAUDE.md
+version: 1.1.12
+---
+
 # QuickTVUI - AI 开发指南
 
 > 本文件可放入任何 QuickTVUI 项目根目录，AI 工具会自动加载。
@@ -58,8 +63,38 @@ Hard requirements:
 - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
 - AI MUST discover and use existing `quicktvui-ai-cli` commands first (`quicktvui-ai --help`, `quicktvui-ai <command> --help`) for env/device/runtime/run-to-TV operations.
 - If a required step has no corresponding `quicktvui-ai-cli` command, AI MUST explicitly state the CLI gap first, then use a manual fallback workflow.
+- If only one device is connected, AI MUST NOT enforce TV/phone distinction.
 - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
-- AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
+- In multi-device mode, AI MUST distinguish TV-like vs phone/tablet targets, and ask confirmation before continuing with non-TV targets.
+- Emulator targets are treated as TV-like devices.
+- AI MUST NOT auto-download/create Google emulator in setup flow. If no device is available, ask user to install/start emulator manually (recommended: https://mumu.163.com) and then reconnect.
+- Runtime APK download source policy (MANDATORY):
+  - Prefer `http://hub.quicktvui.com/repository/maven-files/` first.
+  - If hub download fails, fallback ONLY to trusted repositories:
+    - `https://gitee.com/quicktvui/quicktvui-runtime-apk`
+    - `https://github.com/quicktvui/quicktvui-runtime-apk`
+  - Metadata entry priority:
+    1) `https://gitee.com/quicktvui/quicktvui-runtime-apk/raw/main/manifests/latest.json`
+    2) `https://raw.githubusercontent.com/quicktvui/quicktvui-runtime-apk/main/manifests/latest.json`
+  - Channel policy:
+    - Default `release`.
+    - If `latest-release.json` has `status: pending` or no usable version, fallback to `debug`.
+    - If user explicitly requests `debug`/`release`, use the requested channel.
+  - Metadata and download flow:
+    1) Read `latest.json` and resolve channel manifest path.
+    2) Read `latest-release.json` or `latest-debug.json`.
+    3) Extract `repo_path` and `sha256`.
+    4) Build URL: `<base>/<repo_path>`, base is:
+       - Gitee: `https://gitee.com/quicktvui/quicktvui-runtime-apk/raw/main`
+       - GitHub: `https://raw.githubusercontent.com/quicktvui/quicktvui-runtime-apk/main`
+    5) Download APK and verify SHA256 before install.
+    6) Install with `adb install -r <apk_file>`.
+- Game Loop & Timer Constraints (CRITICAL):
+  - For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+  - `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+  - All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+  - Do NOT create orphan loops/timers without a cancellation path.
+  - In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
 - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
 - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
 - Recommended check commands:

package/rules/GEMINI.md

@@ -1,3 +1,8 @@
+---
+name: GEMINI.md
+version: 1.1.12
+---
+
 # GEMINI.md - QuickTVUI AI 开发指南
 
 > 放入任何 QuickTVUI 项目根目录，Gemini CLI / Gemini Code Assist 自动加载。
@@ -50,8 +55,38 @@ Hard requirements:
 - Do NOT skip adb device detection, runtime install/config, or server host configuration when preparing TV run.
 - AI MUST discover and use existing `quicktvui-ai-cli` commands first (`quicktvui-ai --help`, `quicktvui-ai <command> --help`) for env/device/runtime/run-to-TV operations.
 - If a required step has no corresponding `quicktvui-ai-cli` command, AI MUST explicitly state the CLI gap first, then use a manual fallback workflow.
+- If only one device is connected, AI MUST NOT enforce TV/phone distinction.
 - If multiple devices are connected, AI MUST ask user to choose target serial and MUST NOT silently pick one.
-- AI MUST verify the selected device is TV-like (`leanback`/`television` feature or TV characteristics). For phone/tablet devices, AI MUST ask user confirmation before continuing.
+- In multi-device mode, AI MUST distinguish TV-like vs phone/tablet targets, and ask confirmation before continuing with non-TV targets.
+- Emulator targets are treated as TV-like devices.
+- AI MUST NOT auto-download/create Google emulator in setup flow. If no device is available, ask user to install/start emulator manually (recommended: https://mumu.163.com) and then reconnect.
+- Runtime APK download source policy (MANDATORY):
+  - Prefer `http://hub.quicktvui.com/repository/maven-files/` first.
+  - If hub download fails, fallback ONLY to trusted repositories:
+    - `https://gitee.com/quicktvui/quicktvui-runtime-apk`
+    - `https://github.com/quicktvui/quicktvui-runtime-apk`
+  - Metadata entry priority:
+    1) `https://gitee.com/quicktvui/quicktvui-runtime-apk/raw/main/manifests/latest.json`
+    2) `https://raw.githubusercontent.com/quicktvui/quicktvui-runtime-apk/main/manifests/latest.json`
+  - Channel policy:
+    - Default `release`.
+    - If `latest-release.json` has `status: pending` or no usable version, fallback to `debug`.
+    - If user explicitly requests `debug`/`release`, use the requested channel.
+  - Metadata and download flow:
+    1) Read `latest.json` and resolve channel manifest path.
+    2) Read `latest-release.json` or `latest-debug.json`.
+    3) Extract `repo_path` and `sha256`.
+    4) Build URL: `<base>/<repo_path>`, base is:
+       - Gitee: `https://gitee.com/quicktvui/quicktvui-runtime-apk/raw/main`
+       - GitHub: `https://raw.githubusercontent.com/quicktvui/quicktvui-runtime-apk/main`
+    5) Download APK and verify SHA256 before install.
+    6) Install with `adb install -r <apk_file>`.
+- Game Loop & Timer Constraints (CRITICAL):
+  - For game pages with continuous motion, `requestAnimationFrame` or fixed-tick loops (`setInterval`) MUST have explicit start/stop ownership.
+  - `requestAnimationFrame` IDs MUST be stored in a registry variable (for example `rafId`/`activeRafIds`) and canceled on lifecycle exit (`onESPause`, `onESStop`, `onESDestroy`, and unmount hooks).
+  - All `setTimeout`/`setInterval` IDs MUST be registered in a unified timer registry, and reclaimed via one cleanup function (定时器注册表统一回收), then called from every exit path (game over, route leave, lifecycle pause/destroy).
+  - Do NOT create orphan loops/timers without a cancellation path.
+  - In background or non-playing states, loops MUST pause or run at reduced frequency to avoid wasted CPU.
 - If runtime already exists on target device, AI MUST ask whether to reinstall/reset runtime before run.
 - Before runtime launch, AI MUST verify the target runtime package exposes runtime-launch activity capability (expected activity: `eskit.sdk.core.ui.BrowserProxyActivity` with `android.intent.action.VIEW` + `esapp` scheme).
 - Recommended check commands: