# Playground

**Repository Path**: rri_opensource/playground

## Basic Information

- **Project Name**: Playground
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2026-02-20
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Previewer Web Service

A web service for running HarmonyOS applications.

## Prerequisites

### Python 3.9+
- Ensure Python 3.9 or higher is installed

### Node.js and npm
- Node.js and npm are required for frontend compilation

## Installation

### 1. Clone the repository
```bash
git clone https://gitee.com/rri_opensource/playground.git
cd playground
```

### 2. Install Python dependencies
```bash
pip install fastapi websockets python-multipart uvicorn pillow aiohttp aiofiles aiosqlite
```

### 3. Install Node.js dependencies and build frontend
```bash
npm install
npm run compile
```

## Configuration

Modify the configuration file located at `config.json` according to your environment. Below is a simplified example based on the actual configuration structure:

```json
{
  "configs": [
    {
      "id": "master_20260216",
      "date": "Feb 16, 2026",
      "branch": "master branch",
      "compile_cmd": "RUN_DIR=$(pwd)/../tools ./arkcompiler.sh master {in_file} {out_file} {language}",
      "compile_dir": ".",
      "run_cmd": "RUN_DIR=$(pwd)/../../.. PREV_DIR=$RUN_DIR/previewer/common/bin PANDA_HOME=$PREV_DIR/module/panda LD_LIBRARY_PATH=.:$PREV_DIR:$PREV_DIR/module:$PREV_DIR/module/panda/linux_host_tools/lib ./Previewer {need_debug} -hap {hap} -lws {port} -sid {sid} -s {pipe} -refresh region -cpm false -device {device_type} -shape rect -sd {density} -or {width} {height} -cr {width} {height} -n entry -av ACE_2_0 -pm Stage -l zh_CN -cm {theme} -o {orientation}",
      "run_dir": "../tools/previewer/common/bin",
      "web_port": 5054,
      "support_languages": ["static", "dynamic"]
    }
  ],
  "web_host": "0.0.0.0",
  "web_port": 5000,
  "session_timeout": 600,
  "sessions_root": "/tmp/web_runner_sessions",
  "devices": {
    "phone": { "width": 1080, "height": 2340, "density": 480, "defaultOrientation": "portrait" },
    "tablet": { "width": 1600, "height": 2560, "density": 400, "defaultOrientation": "landscape" },
    "wearable": { "width": 466, "height": 466, "density": 320, "defaultOrientation": "portrait" },
    "car": { "width": 1080, "height": 1920, "density": 320, "defaultOrientation": "landscape" },
    "tv": { "width": 1080, "height": 1920, "density": 320, "defaultOrientation": "landscape" },
    "2in1": { "width": 1600, "height": 2560, "density": 240, "defaultOrientation": "landscape" }
  }
}
```

**Key configuration options:**
- `configs`: List of run configurations (each with its own compiler and runner settings)
- `web_host`: Host address for the web interface
- `web_port`: Default port for the web interface (individual configs may override with their own `web_port`)
- `session_timeout`: Timeout for closing Previewer sessions (in seconds)
- `sessions_root`: Temporary folder for storing received files
- `devices`: Device profile definitions (screen dimensions, density, default orientation)

**Note:** The service uses a SQLite database (`playground.db`) to store session information. The database is automatically created in the project root if it does not exist.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `BLUEZONE` | Set to `true` or `1` to enable AI-powered features (UI3Chat and Explain). When unset or `false`, these features are hidden from users and their API endpoints return 403. Use this in restricted environments where external AI tools are prohibited. |
| `DEEPSEEK_API_KEY` | API key for DeepSeek/OpenRouter (used by Explain feature) |
| `GLM_API_KEY` | API key for GLM provider (used by UI3Chat) |

## Running the Service

Follow these steps to run the service:

1. **Install Node.js dependencies and build frontend:**
   ```bash
   npm install
   npm run compile
   ```

2. **Start the frontend web service:**
   ```bash
   ./run_service_local.sh
   ```
   Once running, access the web interface at [http://localhost:5000](http://localhost:5000).

3. **Start workers:**
   ```bash
   ./run_service_local.sh <worker_config>
   ```
   Replace `<worker_config>` with the configuration identifier (e.g., `master_20260216`). Multiple workers can be started with different configurations.

### Usage
1. Select a `.hap` file or write your own code
2. Click "Run" to start the Previewer session

## ArkUI3 STF Playground

Configs with `"bridge_type": "stf"` (e.g. `arkui3_master`) use the STF (Smart Testing Framework) bridge to run ArkUI3 applications. Unlike the Previewer-based configs, the STF playground compiles user code from the editor on every Run and streams rendered frames back over WebSocket using binary frames.

### Architecture

```
Browser Editor
     |  (code on Run)
     v
web_service.py  --save--> arkui3/arktsx/demo/src/ets/playground.ets
     |  (npm run compile:playground)
     v
build/playground.abc
     |  (npm run run:playground)
     v
ArkUI3 headless app  <--STF WebSocket-->  web_service.py  <--ws-->  Browser
```

**Key components:**
- `STFBridge` class in `web_service.py` — manages the STF WebSocket server, binary frame streaming, and the child ArkUI3 process
- `arktsconfig.playground.json` — compiler config for single-file playground compilation (same dependency paths as the demo)
- `playground.ets` — source file that gets overwritten with user code before each compile

### Run flow

1. **Save**: User code from the editor is written to `arkui3/arktsx/demo/src/ets/playground.ets`
2. **Compile**: `npm run compile:playground` produces `build/playground.abc`
3. **Start**: `npm run run:playground` launches the app in headless mode with STF enabled
4. **Stream**: The bridge polls screenshots at ~30 FPS and sends them as binary frames to the browser

### Stop / Re-run flow

- **Stop**: Kills the child process (SIGTERM then SIGKILL), closes the STF WebSocket, cancels frame polling
- **Re-run**: Stops the old bridge, saves new code, recompiles, starts fresh — no stale state

### E2E Test

With the server running:

```bash
python3 test_e2e_stf.py --port 5000
```

The test verifies: session creation, WebSocket connection, code compilation, frame rendering, input event injection, spam-free logs, and clean stop with no leftover frames.

### Known Issues

- **Response latency**: Screenshot polling introduces ~200-500ms delay per frame depending on app rendering complexity. Clicks reach the app instantly (fire-and-forget), but the visual update is delayed until the next screenshot is captured, encoded, and streamed. A push-based frame mechanism (app streams frames on change rather than bridge polling) would eliminate most of this latency.

## Development

### Type Checking
```bash
npm run type-check
```

### Linting
```bash
npm run lint
```

### Code Formatting
```bash
npm run format
```

### Building Frontend
```bash
npm run compile
# or
npm run build
```

### Installing New Dependencies
```bash
npm install <package>
```

## Configuration Files

- `tsconfig.json`: TypeScript configuration
- `.eslintrc.json`: ESLint rules
- `.prettierrc`: Code formatting rules
- `.eslintignore` / `.prettierignore`: Ignored files

## License

See [LICENSE](LICENSE) file for details.