# Vue Canvas Engine

[![NPM Version](https://img.shields.io/npm/v/@iss-ai/vue-canvas-core.svg)](https://www.npmjs.com/package/@iss-ai/vue-canvas-core)
[![NPM Downloads](https://img.shields.io/npm/dt/@iss-ai/vue-canvas-core.svg)](https://www.npmjs.com/package/@iss-ai/vue-canvas-core)
[![License](https://img.shields.io/npm/l/@iss-ai/vue-canvas-core.svg)](https://github.com/iss-tools/vue-canvas-core/blob/main/LICENSE)

**A powerful JSON-driven low-code UI engine for dynamic dashboards and step-by-step presentations built on Vue 3.**

[English](./README.md) | [简体中文](./README.zh-CN.md)

---

## 🚀 Introduction

**Vue Canvas Engine** is a highly versatile, data-driven visualization sandbox. Rather than writing repetitive template code, you define your entire layout, UI components, and animations using a unified JSON schema. It is designed to act as a **Low-Code orchestration layer** that seamlessly renders native HTML elements alongside complex third-party UI libraries (like Element Plus, Ant Design Vue, etc.).

Whether you are building a static **Dashboard**, a highly interactive **Low-Code Editor**, or a cinematic **Presentation (PPT)**, this engine provides the foundational APIs, state management, and UI editor shell to make it happen.

## ✨ Core Features

- **JSON-Driven Architecture**: The canvas UI is entirely described by an array of objects (`CanvasElementData`). Modifying the JSON instantly reflects on the canvas.
- **Component Agnostic**: By leveraging Vue's dynamic `<component :is="...">` resolution, the engine can mount standard HTML tags (`div`, `span`, `img`) or any globally registered Vue component (`el-button`, `el-switch`). It automatically proxies `props`, `slots`, and `modelValue` for two-way binding.
- **PPT Presentation Mode**: Includes a built-in Timeline Controller. Elements can be assigned `enterStep` and `exitStep` properties. The engine integrates with `animate.css` and the HTML5 Audio API for cinematic transitions and sound effects as you progress through steps.
- **Interactive Editor Shell**: Ships with a ready-to-use editor wrapping the canvas. Features include:
  - Drag & Drop, Resizing, and Multi-selection.
  - Grouping / Ungrouping elements.
  - Infinite zooming & panning (Spacebar + Drag).
  - Configurable grid snapping and rulers.
  - Comprehensive Undo/Redo history system.
- **Exporting**: One-click export of your canvas artboards to JSON, high-resolution PNG, or PDF formats using `html2canvas` and `jsPDF`.
- **Internationalization (i18n)**: Out-of-the-box support for multiple languages (English and Chinese) in the editor UI, easily switchable via the `setLanguage` API.
- **AI-Agent Native**: Built from the ground up to be easily operated by Large Language Models (LLMs). Contains a suite of specialized prompts to generate JSON layouts from text or screenshots.

---

## 📦 Quick Start

### Installation

```bash
# Install dependencies
pnpm install

# Start the interactive visual playground (Sandbox)
pnpm dev
```

Visit `http://localhost:5173/` to see the Vue Canvas Sandbox in action.

- Click the **"Load PPT"** button on the top-right to experience the presentation mode with animations and sound.
- Use the right sidebar to configure element coordinates, props, styles, and animation lifecycles.

---

## 📚 Documentation & Architecture overview

The project contains a rich set of documentation located in the `docs/` and root directories.

### 1. Engine API & SDK (`docs/api-sdk.md`)

The [API SDK Documentation](./docs/api-sdk.md) provides an exhaustive look into the core data structures and exposed methods:

- **`CanvasElementData` Schema**: The contract defining every node on the canvas (id, type, x, y, width, height, props, slots, animation).
- **Core APIs**: `addElement`, `removeElement`, `updateElement`, `groupSelected`, `setPresentationMode`.
- **Event System**: Granular Vue event emissions like `@select`, `@element:move`, `@element:resize` for seamless synchronization with external sidebars.

### 2. AI Prompts & Agent Integration (`docs/ai/` & `SKILL.md`)

This engine is designed to be the ultimate UI renderer for AI Agents. We provide [pre-built AI prompt templates](./docs/ai/) to orchestrate UI generation:

- **Vision Extraction**:
  - `prompt-image-to-normal.md`: Instructs vision models to reverse-engineer an uploaded UI screenshot into a static `normal.json` layout.
  - `prompt-image-to-presentation.md`: Analyzes an image and extrapolates an animated, step-by-step `presentation.json`.
- **Component Scraping**:
  - `prompt-repo-to-components.md` & `prompt-url-to-components.md`: Directs Agents to scrape Github repos or official component documentations to generate a standard dictionary of available Vue components.
  - `prompt-html-to-component.md`: Converts messy Chrome DevTools `outerHTML` snippets into clean, sanitized Vue Canvas schemas.
- **Agent Manual**:
  - `AGENT.md`: A technical manual for autonomous AI coders explaining the reactivity rules, component injection patterns, and architectural boundaries of this engine.
- **Framework Integration**:
  - `SKILL.md`: A standard descriptor file allowing Dify, FastGPT, or other agentic frameworks to mount this repository as a native UI-generation skill.

---

## 🛠 Usage in your own Vue Project

While `playground/` acts as the development sandbox, the core package can be imported as a Vue library:

```vue
<template>
  <div style="width: 100vw; height: 100vh;">
    <CanvasEditor
      ref="editorRef"
      :initial-elements="myData"
      mode="edit"
      theme="dark"
      @select="handleSelect"
      @change="handleCanvasChange"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
import { CanvasEditor } from '@iss-ai/vue-canvas-core';

const editorRef = ref(null);
const myData = [
  {
    id: 'btn_1',
    type: 'el-button',
    x: 100,
    y: 100,
    props: { type: 'primary' },
    slots: { default: 'Click Me' },
  },
];

const handleSelect = selectedIds => {
  console.log('Selected elements:', selectedIds);
};
</script>
```

## 📄 License

This project is licensed under the **[GNU Affero General Public License v3.0 (AGPL-3.0)](./LICENSE)**.