@quicktvui/ai 1.0.0

package/rules/.windsurfrules

@@ -0,0 +1,367 @@
+# .windsurfrules - QuickTVUI AI Development Guide
+
+> Drop this file into any QuickTVUI project root. Works with Windsurf.
+
+## 🔴 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
+3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
+4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
+5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
+
+**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)
+
+**`<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: 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.
+- **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)
+
+- 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"`
+
+```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>