@quicktvui/ai 1.0.0

package/rules/AGENTS.md

@@ -0,0 +1,456 @@
+# AGENTS.md - QuickTVUI AI Development Guide
+
+> Drop this file into any QuickTVUI project root. Works with OpenAI Codex and other AI tools.
+
+## 🔴 CRITICAL: SOURCE OF TRUTH & NO HALLUCINATION
+
+**AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
+
+1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+2.  **Official Docs**: https://quicktvui.com (390+ docs)
+3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git (Core library + samples)
+4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
+5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git (Complete video app)
+
+**STRICT RULES:**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
+- **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
+- **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
+- **REFERENCE FIRST**: Search for component usages in the linked repositories if unsure.
+
+## Project Scaffolding (CRITICAL)
+
+When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vue project structure. Instead, follow these exact steps:
+1. **Clone Template**: `git clone https://github.com/quicktvui/quicktvui-template.git <project-name>`
+2. **Clean Git**: `cd <project-name> && rm -rf .git`
+3. **Update Config**: Read `package.json`, modify the `"name"` to `<project-name>`, and reset `"version"` to `"1.0.0"`.
+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).
+
+## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
+
+AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:
+
+1.  **Media Playback Architecture**:
+    *   **NEVER** use HTML5 `<video>`, `<audio>`, or `qt-web-view` for media.
+    *   **Best Practice**: You MUST prioritize using **`es-player-manager`** wrapping `es-video-player` or `es-audio-player`. The manager handles playlists, window sizing (full/small), and focus. Using the base player alone leads to missing logic.
+2.  **List Components (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**:
+    *   You MUST set `listenBoundEvent="true"` and listen to `@item-bind`.
+    *   The "Loading More" template `type` **MUST** be `1002`. The "End of List" template `type` **MUST** be `1003`.
+3.  **Zero HTML & Zero DOM**:
+    *   **This is NOT a browser.** It compiles to Hippy Native Android Views.
+    *   **Banned Tags**: Standard HTML tags (`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>`) will **CRASH** the app. Use only `div`, `span`, or `qt-*` tags.
+    *   **Banned APIs**: `window`, `document`, `e.preventDefault()`, `alert()` do not exist. Use `useESLocalStorage()` for storage and `useESToast()` for alerts.
+4.  **Strict CSS Subset**:
+    *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
+    *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
+
+## Overview
+
+QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
+
+## Example Repositories
+
+- https://github.com/quicktvui/quicktvui.git — Core library + samples
+- https://github.com/quicktvui/es-vue3.git — Cross-platform framework + samples
+- https://github.com/quicktvui/hellotv.git — Complete video app (best practice)
+- Online docs: https://quicktvui.com
+
+## CRITICAL RULES (Read First — Violations Will Cause Runtime Failures)
+
+### Function Naming (Framework matches by exact name — wrong name = never called)
+
+- Back key handler MUST be named `onBackPressed` — NOT `onBack`, `goBack`, `handleBack`
+- Key events MUST be named `onKeyDown` / `onKeyUp` — NOT `handleKeyDown`, `onKeyPress`
+- Lifecycle MUST be named `onESCreate` / `onESResume` / `onESDestroy` etc. — exact names only
+- ALL these functions MUST be defined in `setup()` AND returned in `return { }`
+
+### Every Page MUST Include (Checklist)
+
+- `onESCreate(params)` — page lifecycle entry, MUST define and return
+- `onBackPressed()` — back key handler, MUST define and return (usually calls `router.back()`)
+- At least one element with `:autofocus="true"` — otherwise no focus, remote control won't work
+- Root element size: `width: 1920px; height: 1080px`
+
+### Component Names (Must be exact — no HTML tag substitutes)
+
+- Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
+- Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
+- Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
+- Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
+
+### STRICT COMPONENT NAMING (CRITICAL)
+
+**Do NOT hallucinate or use standard web tags. The following mapping is MANDATORY:**
+
+| Mandatory Tag | Forbidden (Do NOT use)             |
+| ------------- | ---------------------------------- |
+| `<qt-image>`  | `<qt-img>`, `<img>`                |
+| `<qt-text>`   | `<p>`, `<h1>`~`<h6>`, `<label>`    |
+| `<qt-button>` | `<button>`                         |
+| `<div>`       | `<section>`, `<main>`, `<article>` |
+| `<span>`      | `<p>`, `<label>`                   |
+
+### CSS Rules (This is NOT standard Web CSS)
+
+- **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
+- **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
+- **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.
+- **CRITICAL: Static styles MUST be in `<style>` (kebab-case), Dynamic styles MUST be in `:style` attributes.**
+- **CRITICAL: NO `-webkit-font-smoothing: antialiased;`**. This is not supported.
+- **CRITICAL: ONLY use `div` and `span` for standard tags.** Do NOT use `p`, `h1-h6`, `section`, etc.
+- **`<style>` = kebab-case, `<template>` tag attributes = camelCase.** Do NOT mix them up.
+
+WRONG — DO NOT write camelCase in `<style>`:
+
+```css
+/* WRONG! camelCase in <style> will NOT work */
+.item {
+  backgroundcolor: #333;
+  fontsize: 28px;
+  focusbackgroundcolor: #0066ff;
+}
+```
+
+CORRECT — `<style>` must use kebab-case for ALL properties:
+
+```css
+/* CORRECT */
+.item {
+  background-color: #333;
+  font-size: 28px;
+  focus-background-color: #0066ff;
+}
+```
+
+CORRECT — `<template>` tag attributes use camelCase:
+
+```vue
+<div :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
+```
+
+Other CSS rules:
+
+- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- Only use properties listed in "Supported Style Properties" section below
+- Do NOT use `<style scoped>` (unreliable in native rendering)
+- Only `px` units (no %, auto, vh, vw, rem, em). No CSS shorthand.
+
+### clipChildren / clipPadding (MANDATORY for TV — without these, focusScale gets clipped)
+
+Android clips child views outside parent bounds by default. When using `focusScale`, the enlarged item gets cut off.
+
+**Rules:**
+- Any container with `focusScale` children MUST set `:clipChildren="false"`
+- List components (`qt-list-view`, `qt-waterfall`, `qt-grid-view`) MUST set both `:clipChildren="false"` and `:clipPadding="false"`
+- Written as camelCase attributes in `<template>`
+
+```vue
+<div :clipChildren="false">
+  <div :focusable="true" :focusScale="1.1">...</div>
+</div>
+<qt-list-view :clipChildren="false" :clipPadding="false" />
+```
+
+### Import Sources
+
+- `defineComponent` from `vue` — NOT from `@vue/runtime-core`
+- Router: `useESRouter` from `@extscreen/es3-router`
+- Native modules from `@extscreen/es3-core`
+
+---
+
+## Supported Style Properties (Complete List)
+
+Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
+
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+
+### Layout & Size
+
+`width`, `height`, `left`, `top`, `overflow`, `direction`, `z-index`, `visibility`, `opacity`, `transform`
+
+### Background
+
+`background-color`, `background-image`, `background-position-x`, `background-position-y`, `background-size`, `linear-gradient`
+
+### Border
+
+`border-color`, `border-style`, `border-width`, `border-radius`, `border-top-color/style/width`, `border-bottom-color/style/width`, `border-left-color/style/width`, `border-right-color/style/width`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-left-radius`, `border-bottom-right-radius`
+
+### Shadow
+
+`shadow-color`, `shadow-offset`, `shadow-offset-x`, `shadow-offset-y`, `shadow-opacity`, `shadow-radius`
+
+### Text
+
+`color`, `text`, `text-align`, `text-align-vertical`, `font-size`, `font-family`, `font-style`, `font-weight`, `fake-bold`, `letter-spacing`, `line-height`, `line-spacing-extra`, `line-spacing-multiplier`, `number-of-lines`, `ellipsize-mode`, `enable-scale`, `break-strategy`, `text-decoration-color/line/style`, `text-shadow-color/offset/radius`, `vertical-align`
+
+### Image
+
+`src`, `resize-mode`, `tint-color`, `tint-color-blend-mode`, `cap-insets`, `default-source`
+
+### Focus State
+
+`focus-background-color`, `focus-color`, `select-color`, `select-background-color`, `enable-focus-border`, `focus-border`, `focus-border-width`, `focus-border-color`, `focus-border-color-string`, `focus-border-style`, `focus-border-radius`, `focus-border-top-left-radius`, `focus-border-top-right-radius`, `focus-border-bottom-right-radius`, `focus-border-bottom-left-radius`, `focus-border-type`, `enable-black-border`
+
+### Input & Other
+
+`caret-color`, `placeholderTextColor`, `blur`
+
+## Focus System (Core)
+
+TV has no mouse/touch. Users navigate with remote control directional keys.
+
+```vue
+<div :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
+  <qt-text text="Button" :duplicateParentState="true" />
+</div>
+<div :autofocus="true" :focusable="true"></div>
+<qt-list-view :autofocusPosition="5"></qt-list-view>
+```
+
+Focus CSS extensions:
+
+```css
+.item {
+  focus-background-color: black;
+  focus-color: white;
+  focus-border-radius: 5px;
+  focus-border-width: 3px;
+  focus-border-color: red;
+  enable-focus-border: true;
+  enable-black-border: true;
+  select-background-color: blue;
+  select-color: yellow;
+}
+```
+
+Focus direction: `:nextFocusName="{down:'listC', right:'listB'}"`, `:blockFocusDirections="['left','right']"`, `:descendantFocusability="2"` (disable subtree focus)
+
+## Router & Lifecycle
+
+```typescript
+// routes.ts
+const routes = [
+  { path: "/index", name: "index", component: index },
+  { path: "/detail", name: "detail", component: detail },
+];
+
+// main.ts
+import { createESRouter } from "@extscreen/es3-router";
+const router = createESRouter({
+  main: "index",
+  error: "error",
+  limit: 10,
+  routes,
+});
+
+// Navigation
+const router = useESRouter();
+router.push({ name: "detail", params: { id: "123" } });
+router.back();
+```
+
+Page lifecycle (only route-declared components, NO async):
+
+```
+onESCreate(params) → onESStart() → onESResume() → onESPause() → onESStop() → onESDestroy()
+```
+
+## Key Events
+
+```typescript
+// In setup(), must return these functions
+function onKeyDown(keyEvent) {
+  /* keyEvent.keyCode, keyEvent.action */
+}
+function onBackPressed() {
+  router.back();
+}
+return { onKeyDown, onBackPressed };
+```
+
+Key codes: DPAD_UP(19), DPAD_DOWN(20), DPAD_LEFT(21), DPAD_RIGHT(22), DPAD_CENTER(23), ENTER(66), BACK(4), MENU(82)
+
+## Common Components
+
+| Component      | Purpose          | Key Props                                                                   |
+| -------------- | ---------------- | --------------------------------------------------------------------------- |
+| qt-button      | Button           | text, size, focusable, focusScale, disabled, round                          |
+| qt-text        | Text             | text, fontSize, textColor, focusColor, gravity, lines, duplicateParentState |
+| qt-image       | Image            | src, focusable, enableFade, resizeMode                                      |
+| qt-input       | Input            | hintText, textColor, textSize, strokeWidth, strokeColor                     |
+| qt-waterfall   | Waterfall list   | enablePlaceholder, blockFocusDirections, autofocusPosition                  |
+| qt-list-view   | List             | autofocusPosition, blockFocusDirections                                     |
+| qt-grid-view   | Grid             | autofocusPosition                                                           |
+| qt-tabs        | Tabs             | defaultIndex, itemList                                                      |
+| qt-card        | Card             | load(), reload(), requestCardFocus()                                        |
+| qt-seek-bar    | Seek bar         | progress, range, seekBarMode                                                |
+| qt-dialog      | Dialog           | Global or route-based                                                       |
+| qt-row         | Horizontal flex  | flex-direction: row                                                         |
+| qt-column      | Vertical flex    | flex-direction: column                                                      |
+| qt-scroll-view | Scroll container | -                                                                           |
+| qt-animation   | Animation        | alpha/rotation/scale/translation                                            |
+
+## Native Modules
+
+All from `@extscreen/es3-core`:
+
+```typescript
+// Storage
+const storage = useESLocalStorage();
+await storage.putString("key", "value");
+await storage.getString("key", "default");
+
+// Toast
+const toast = useESToast();
+toast.showToast("message");
+
+// Device
+const device = useESDevice();
+device.getScreenWidth() / device.getScreenHeight();
+
+// Network
+const network = useESNetwork();
+network.isNetworkConnected();
+
+// Audio
+const audio = useESAudio();
+audio.getStreamMusicVolume();
+
+// Event Bus
+const bus = useESEventBus();
+bus.on("event", callback);
+bus.emit("event", data);
+```
+
+## Minimal Page Template
+
+```vue
+<template>
+  <div class="page">
+    <div
+      class="item"
+      :focusable="true"
+      :focusScale="1.1"
+      :enableFocusBorder="true"
+      :autofocus="true"
+      @click="onClick"
+    >
+      <qt-text text="Hello TV" :duplicateParentState="true" class="text" />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent } from "vue";
+import { useESRouter } from "@extscreen/es3-router";
+export default defineComponent({
+  setup() {
+    const router = useESRouter();
+    function onESCreate(params) {}
+    function onClick() {}
+    function onBackPressed() {
+      router.back();
+    }
+    return { onESCreate, onClick, onBackPressed };
+  },
+});
+</script>
+
+<style>
+.page {
+  width: 1920px;
+  height: 1080px;
+  background-color: #000000;
+}
+.item {
+  width: 300px;
+  height: 100px;
+  background-color: #333;
+  focus-background-color: #0066ff;
+}
+.text {
+  width: 300px;
+  height: 100px;
+  font-size: 28px;
+  color: #fff;
+}
+</style>
+```
+
+## Detail Page Template (with params + back key)
+
+```vue
+<template>
+  <div class="detail-page">
+    <qt-text class="detail-title" :text="title" gravity="center" />
+    <div
+      class="detail-back-btn"
+      :focusable="true"
+      :focusScale="1.1"
+      :enableFocusBorder="true"
+      :autofocus="true"
+      @click="onBackPressed"
+    >
+      <qt-text
+        text="Back"
+        :duplicateParentState="true"
+        class="detail-back-text"
+        gravity="center"
+      />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, ref } from "vue";
+import { useESRouter } from "@extscreen/es3-router";
+export default defineComponent({
+  setup() {
+    const router = useESRouter();
+    const title = ref("Detail");
+    function onESCreate(params) {
+      if (params && params.title) title.value = params.title;
+    }
+    function onBackPressed() {
+      router.back();
+    }
+    return { title, onESCreate, onBackPressed };
+  },
+});
+</script>
+
+<style>
+.detail-page {
+  width: 1920px;
+  height: 1080px;
+  background-color: #1a1a1a;
+  align-items: center;
+  justify-content: center;
+}
+.detail-title {
+  width: 600px;
+  height: 80px;
+  font-size: 48px;
+  color: #ffffff;
+  margin-bottom: 40px;
+}
+.detail-back-btn {
+  width: 240px;
+  height: 70px;
+  background-color: #333;
+  focus-background-color: #0066ff;
+  border-radius: 35px;
+}
+.detail-back-text {
+  width: 240px;
+  height: 70px;
+  font-size: 26px;
+  color: #ffffff;
+}
+</style>
+```