#ClickDeck Core Usage Guide

ClickDeck Core is a browser-based visual editor core module, integrated as a DevTools component within QuickUIDesign. This guide covers how to install, integrate, configure, and use ClickDeck Core in your projects.

#Installation

ClickDeck Core is built into QuickUIDesign and activates automatically in the development environment. To integrate it into your project:

# If using QuickUIDesign scaffold, ClickDeck Core is pre-configured
npm install
npm run dev

For manual integration, ensure the following dependencies are available in your project:

• TypeScript (strict mode)
• DOM API support (MutationObserver, FileReader, Canvas, Fullscreen API)
• localStorage for persistence

#Integration

#As a DevTools Component

ClickDeck Core is designed as a DevTools panel that integrates into your application's development environment:

import ClickDeckDevTools from '@dev/react/ClickDeckDevTools'
import { ClickDeckToggle } from '@/dev-tools/react/ClickDeckToggle'

// Integrate the DevTools component in your root component
<ClickDeckDevTools />
<ClickDeckToggle />

#Activation Methods

When first activated, the editor automatically initializes (creates Overlay, Panel, event listeners). The panel appears at the bottom-right by default and can be dragged anywhere.

#Basic Workflow

#Path A: Direct Style Editing (Quick Adjustments)

Best for lightweight style modifications (font size, color, spacing, alignment) with instant visual feedback.

1. Activate editor            → Alt+Shift+C or click the button
2. Select target element      → Hover to preview highlight, click to select
3. Adjust styles in panel     → Use the various style buttons
4. Optional: select more      → Repeat steps 2-3
5. Undo / Redo                → Use panel Undo/Redo (or Ctrl+Z / Ctrl+Shift+Z)
6. Close editor               → Alt+Shift+C or click Close

#Path B: Intent Annotation + AI Prompt Export (Complex Modifications)

Suitable for scenarios involving move, delete, custom operations, or when you need to describe specific intentions. This path does not directly modify the DOM; instead, it produces a structured AI Prompt for code generation tools.

1. Activate editor            → Alt+Shift+C
2. Click "Add suggestion"     → Enter selection mode
3. Drag to select area        → Release mouse to confirm
4. Edit intent draft          → Fill in operation description, mark operation type
5. Add multiple intents       → Repeat steps 2-4
6. Optional: direct edits     → Export as actual patches alongside intents
7. Click "Copy AI edit prompt" → Copy structured Prompt
8. Paste to AI                → Let code generation tools execute

#Element Selection

The panel header shows Selected: div.classname format description. Text elements (h1~h6, p, span, a, li, strong, em) become editable on click — you can type directly on the page.

#Style Adjustments

The panel's tool buttons dynamically switch based on the selected element type:

#Text Elements (h1-h6, p, span, a, li)

#Container Elements (div, section)

#Image Elements

#Undo / Redo

• Panel: Click Undo / Redo buttons in the History area
• Shortcuts: Ctrl+Z undo, Ctrl+Shift+Z redo
• Grouped Undo: Multiple style changes on the same element at the same time are grouped and undone/redone together
• Note: Shortcuts are disabled while editing text (to avoid interfering with native input undo)

#Exporting to AI Prompt

This is ClickDeck Core's signature capability. It merges direct style modifications and intent annotations into a single structured AI edit instruction.

#Export Flow

1. Complete page edits (style adjustments / intent annotations / text edits / image replacements)
2. Click "Copy AI edit prompt" button
3. Prompt preview window opens (supports English and Chinese)
4. Optionally edit the prompt text manually
5. Click "Copy" to clipboard
6. Paste to coding AI (Claude, Cursor, Copilot, etc.)
7. AI executes modifications per the task list

#Prompt Structure

A typical AI Prompt includes:

• Page context: URL, title, scope
• Execution TodoList: Tasks with targets and details
• Location hints: How to find elements in the DOM
• Global editing rules: Keep unrelated content unchanged
• Task Details: Individual patch descriptions and intent annotations
• Final alignment checklist: Visual comparison guide

#When to Use Which Approach

#AI Page Review

The panel provides three review prompts for AI to analyze pages before editing:

Usage: Click the button → Prompt copied to clipboard → Paste to an AI that can see the page (e.g., Gemini).

#Data Persistence

ClickDeck saves edit patches in localStorage using the key clickdeck:page-edits:v1:{origin}{pathname}{search}.

Restoring edits: When reopening the editor after a refresh, if unsaved edits are detected, the panel shows "Saved edits found (N)" with options:

• Restore — Re-apply all patches
• Clear — Discard saved edits

Note: Persisted patches only include serializable style and attribute modifications. Text content changes (ContentPatch) need DOM re-matching after deserialization. If the page structure changed since the last edit, some patches may not restore.

#Configuration & Customization

#Panel Position

The panel defaults to the bottom-right corner. It can be repositioned by dragging the title bar or the collapsed icon button.

#Panel Opacity

Click the "◐" button on the title bar to cycle opacity: 100% → 70% → 40%.

#Language Switching

Click the language button on the title bar to toggle between Chinese and English instantly.

#Architecture Overview

ClickDeck Core uses a layered architecture:

┌─────────────────────────────────────┐
│         Controller (Orchestrator)     │
├─────────────────────────────────────┤
│   Content Modules    │ Export Modules │
│  (Selection, Style,  │  (Prompt Gen,  │
│   History, Intent)   │   Serializer)  │
├─────────────────────────────────────┤
│     DOM API Layer (MutationObserver,  │
│     FileReader, Canvas, Fullscreen)   │
└─────────────────────────────────────┘

Key design decisions:

1. Non-destructive editing: All changes via inline styles + patch records, source files unchanged
2. "Soft Intent" mode: Intent edits produce AI Prompts rather than direct DOM manipulation
3. React compatible: MutationObserver detects and re-applies overridden changes
4. Progressive adjustments: Fixed increments instead of absolute values for rapid iteration

#Best Practices

1. Direct edit first, then intent — Let the panel handle what it can; intent annotations supplement the AI context
2. Be specific in intent text — Instead of "optimize this", write "increase font size, change color to blue, add bottom shadow"
3. Select precisely — Keep selection areas tight to avoid confusing the AI
4. Check the Prompt — Verify the task list is complete and location info is accurate before copying
5. One page at a time — Each Prompt handles one page's modifications; export separately for multi-page needs