openpencil/README.th.md
Kayshen Xu 8472d4ac04 V0.5.0 (#67)
* docs: add image search & generation design spec and implementation plan

- Spec: dual-source image search (Openverse + Wikimedia), multi-provider image generation
- Plan: 16 tasks covering types, server endpoints, settings UI, property panel, auto-search pipeline, MCP integration

* feat(types): add image service types and imagePrompt to ImageNode

* feat(server): add image service API key validation endpoint

Adds POST /api/ai/image-service-test that validates credentials for
openverse (client_credentials), openai/custom (Bearer + /v1/models),
gemini (API key + v1beta/models), and replicate (Bearer + /v1/models).

* feat(server): add multi-provider image generation endpoint

* feat(server): add dual-source image search endpoint (Openverse + Wikimedia)

POST /api/ai/image-search searches freely-licensed images via Openverse
with automatic fallback to Wikimedia Commons on 429 rate-limit responses.
Supports optional OAuth credentials for authenticated Openverse requests.

* feat(store): add imageSearchStatuses to canvas store for runtime status tracking

* feat(store): add image generation config and Openverse OAuth to agent settings

* feat(editor): add Images tab to agent settings dialog

Adds Popover primitive, ImagesPage component with Image Search (Openverse OAuth, test) and Image Generation (provider select, API key, model, base URL) sections, and wires them into the settings dialog sidebar.

* feat(panels): add image search popover with Openverse/Wikimedia results grid

* feat(panels): add image generate popover with multi-provider support

* feat(panels): add Search and Generate buttons to image property section

* feat(ai): update prompts to use imagePrompt instead of src for image nodes

* feat(ai): add auto-search pipeline with Openverse/Wikimedia fallback

* feat(ai): trigger auto image search after design generation completes

* feat(mcp): implement G() operation for image search in batch design DSL

Adds the G(parent, mode, prompt) operation to batch_design DSL that creates
an image node and optionally fetches a real image URL via the image-search
API when mode is "search". Converts executeLine to async to support the
network call.

* feat(mcp): auto-fill images after design refinement in layered pipeline

* feat(ai): split imageSearchQuery and imagePrompt for search vs generation

- ImageNode now has both imageSearchQuery (short keywords for search)
  and imagePrompt (long description for AI image generation)
- AI prompts instruct LLM to generate both fields
- Search pipeline and popovers use imageSearchQuery
- Generate popover uses imagePrompt
- Server-side simplifySearchQuery kept as fallback for manual input

* fix(ai): hook auto image search into orchestrator completion path

The primary generation path uses executeOrchestration -> insertStreamingNode,
not applyNodesToCanvas/animateNodesToCanvas. Added scanAndFillImages call
to orchestrator.ts after all sub-agents complete. Added debug logging.
Removed plan/spec docs from git.

* style(editor): remove provider names from image search ready status

* fix(panels): clean up image gen error display and settings UI

- Parse API error response to show concise message instead of raw JSON
- Limit error text to 2 lines with line-clamp
- Fix image gen test button sending wrong service name
- Inline Image Search ready indicator with section header
- Remove debug logging from image search pipeline

* style(panels): allow up to 4 lines for image gen error message

* fix: avoid 1-frame delay when resizing canvas (#60)

rAF callbacks run before ResizeObserver in the same frame.
Scheduling render in ResizeObserver via rAF defers it to the next frame.

Invoke render() synchronously to leverage ResizeObserver's pre-paint timing
and ensure immediate visual update.

* feat(electron): implement desktop application structure and auto-updater

- Introduced a new Electron desktop application with a structured directory for apps and packages.
- Added auto-updater functionality to manage application updates seamlessly.
- Created a comprehensive menu system for the desktop app.
- Implemented logging capabilities for better debugging and error tracking.
- Configured build settings for various platforms (macOS, Windows, Linux) using electron-builder.
- Established TypeScript configurations for both the desktop and web applications.
- Integrated Vite for the web application with support for React and Tailwind CSS.
- Added icons and assets for the desktop application.

* chore: update package versions to 0.5.0 across all package.json files and add pre-commit hook for version synchronization

- Bumped version to 0.5.0 in package.json files for the main project, desktop app, web app, and all packages.
- Introduced a pre-commit hook to automatically sync version numbers from branch names to all package.json files.

* chore: update package versions to 0.5.0 and refactor Skia components

- Bumped version to 0.5.0 in bun.lock and all relevant package.json files.
- Refactored Skia components to utilize shared functionality from @zseven-w/pen-renderer, including image loading, hit testing, and path utilities.
- Removed redundant code and improved modularity by re-exporting necessary functions and classes from the renderer package.

* fix(panels): handle string fill values in icon nodes (#61)

AI-generated icon/path nodes may have fill stored as a raw string
instead of a PenFill[] array, causing "Cannot use 'in' operator"
crash when selecting the node in the property panel.

* chore: update documentation and project structure for monorepo organization

- Added a new version bump command to synchronize all package.json files.
- Updated the project structure to reflect a monorepo setup with organized workspaces for apps and packages.
- Enhanced README files in multiple languages to include the new structure and commands.
- Adjusted image paths in documentation to point to the correct locations for the desktop application.

* feat(ai): incremental image search and improved image generation prompts

- Refactor image search from batch post-generation to incremental queue:
  enqueueImageForSearch() triggers as each image node is inserted during
  streaming, so images appear progressively instead of all at once after
  generation completes. scanAndFillImages() remains as a final sweep.
- Update imagePrompt guidance to avoid "transparent background" and
  similar phrases that many models cannot reliably produce.
- Pass node width/height from image panel to generation endpoint for
  aspect-ratio-aware output (Gemini aspect ratio mapping, OpenAI size
  selection, Replicate dimensions).

* feat(ai): multi-profile image generation config and cleaner error messages

- Support multiple image generation profiles with active selection;
  first configured profile becomes default. Old single-config migrated
  automatically on hydrate.
- Fix Gemini aspect ratio: move to generationConfig.imageConfig per API spec.
- Extract clean error messages from provider JSON responses (Gemini
  error.message, OpenAI error.message, Replicate detail) instead of
  returning raw JSON text.
- Remove destructive client-side regex that mangled error display.

* feat(design-md): integrate design system panel and functionality

- Added a new DesignMdPanel component for managing design system specifications.
- Implemented functionality to toggle the design system panel in the editor layout and toolbar.
- Introduced new commands for importing, exporting, and auto-generating design.md content.
- Updated AI chat handlers to utilize design.md data for enhanced design generation.
- Enhanced localization support for design system features across multiple languages.

* perf(canvas): skip draw calls for nodes outside the viewport (#64)

Add viewport culling in render() to avoid issuing CanvasKit draw calls
  for off-screen nodes. A 64px screen-space buffer is kept around the
  viewport edges so nearby nodes are pre-rendered, preventing pop-in
  during fast panning.

* feat(utils): enhance Windows process spawning for CLI scripts

- Updated the buildSpawnClaudeCodeProcess function to handle .cmd and .ps1 scripts appropriately.
- Implemented PowerShell invocation for .ps1 files and ensured safe defaults for .cmd and .exe files.
- Improved handling of command execution to avoid limitations of cmd.exe.

* feat(ai): add support for Gemini CLI integration

- Extended the AI provider options to include 'gemini' across various components and APIs.
- Implemented functions for generating, validating, and connecting to the Gemini CLI.
- Added Gemini-specific error handling and model fetching logic.
- Updated UI components to display Gemini as a selectable provider with appropriate icons and labels.
- Enhanced localization support for Gemini-related features in multiple languages.

* feat(editor): warn before closing with unsaved changes

Intercept window/tab close when isDirty is true:
- Electron: native dialog with Save / Don't Save / Cancel
- Web: beforeunload handler + confirm on New/Open actions
- i18n: close-confirm strings for all 15 locales

* feat(ipc): extract IPC handlers to a dedicated module

- Moved IPC dialog handling and updater functions from main.ts to ipc-handlers.ts for better organization and maintainability.
- Implemented file open/save dialogs, theme setting, and preferences management through IPC.
- Enhanced updater functionality with state management and auto-update settings.
- Improved code structure by separating concerns, making it easier to manage IPC-related logic.

* feat(docs): update CLAUDE documentation and add new files for desktop and web apps

- Enhanced CLAUDE.md with detailed module documentation references for `packages/` and `apps/`.
- Updated `pen-core` description to include clone utilities in `pen-core`.
- Added new documentation files for the desktop and web applications, outlining their structure, components, and functionalities.
- Included IPC handler details in the desktop app documentation for better clarity on file dialogs and theme synchronization.

* feat(docker): add Gemini CLI support and update documentation

- Introduced a new Docker build stage for the Gemini CLI, allowing users to install and run it.
- Updated the Dockerfile to include the installation of the Gemini CLI alongside existing CLI tools.
- Enhanced README files in multiple languages to document the new `openpencil-gemini` image variant.
- Added Gemini CLI connection instructions to the main README for better user guidance.

* feat(docs): add Gemini CLI connection instructions to multiple language READMEs

- Updated README files in German, Spanish, French, Hindi, Indonesian, Japanese, Korean, Portuguese, Russian, Thai, Turkish, Vietnamese, and both Traditional and Simplified Chinese to include connection instructions for the Gemini CLI.
- Enhanced documentation to improve user guidance for connecting the Gemini CLI in agent settings.

* perf(renderer): replace count-based text cache limits with memory-based eviction (#66)

previous limits (PARA_CACHE_MAX=200, TEXT_CACHE_MAX=300) were too small
  for scenes with many nodes, causing constant cache churn and paragraph
  rebuilds every frame, which dropped FPS significantly during canvas pan.

  - switch to byte-budget limits (64 MB paragraphs, 256 MB bitmaps)
  - bitmap size measured exactly as cw*ch*4; paragraph WASM heap estimated
    as content.length*64+4096
  - eviction uses Map insertion order (FIFO) instead of a separate string[]
    array, replacing O(n) array.shift() with O(1) Map.entries().next()
  - evict before insert so the budget check includes the incoming entry

---------

Co-authored-by: Fini <fini.yang@gmail.com>
Co-authored-by: leinaldo <60176594+leinaldo@users.noreply.github.com>
2026-03-22 09:44:04 +08:00

19 KiB

OpenPencil

OpenPencil

เครื่องมือออกแบบเวกเตอร์โอเพนซอร์สที่ขับเคลื่อนด้วย AI ตัวแรกของโลก
ทีม Agent ทำงานพร้อมกัน • Design-as-Code • MCP Server ในตัว • ปัญญาหลายโมเดล

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

Stars License CI Discord


OpenPencil — คลิกเพื่อดูวิดีโอสาธิต

คลิกที่รูปภาพเพื่อดูวิดีโอสาธิต


ทำไมต้อง OpenPencil

🎨 Prompt → Canvas

อธิบาย UI ใดก็ได้ด้วยภาษาธรรมชาติ ดูมันปรากฏบน Canvas ไม่จำกัดขนาดแบบเรียลไทม์พร้อม animation แบบ streaming แก้ไขดีไซน์ที่มีอยู่โดยเลือกองค์ประกอบแล้วพิมพ์สนทนา

🤖 ทีม Agent ทำงานพร้อมกัน

Orchestrator แบ่งหน้าที่ซับซ้อนออกเป็น sub-task เชิงพื้นที่ AI agent หลายตัวทำงานในส่วนต่าง ๆ พร้อมกัน — hero, features, footer — ทั้งหมด streaming แบบขนาน

🧠 ปัญญาหลายโมเดล

ปรับตัวตามความสามารถของแต่ละโมเดลโดยอัตโนมัติ Claude ได้ prompt เต็มรูปแบบพร้อม thinking; GPT-4o/Gemini ปิด thinking; โมเดลขนาดเล็ก (MiniMax, Qwen, Llama) ได้ prompt แบบย่อเพื่อผลลัพธ์ที่เสถียร

🔌 MCP Server

ติดตั้งได้ด้วยคลิกเดียวใน Claude Code, Codex, Gemini, OpenCode, Kiro หรือ Copilot CLIs ออกแบบจาก terminal ของคุณ — อ่าน สร้าง และแก้ไขไฟล์ .op ผ่าน agent ที่รองรับ MCP

📦 Design-as-Code

ไฟล์ .op เป็น JSON — อ่านได้โดยมนุษย์, Git-friendly, เปรียบเทียบความแตกต่างได้ Design variables สร้าง CSS custom properties ส่งออกโค้ดเป็น React + Tailwind หรือ HTML + CSS

🖥️ ใช้งานได้ทุกที่

เว็บแอป + เดสก์ท็อปแบบ native บน macOS, Windows และ Linux ผ่าน Electron อัปเดตอัตโนมัติจาก GitHub Releases เชื่อมโยงไฟล์ .op — ดับเบิลคลิกเพื่อเปิด

เริ่มต้นอย่างรวดเร็ว

# ติดตั้ง dependencies
bun install

# เริ่ม dev server ที่ http://localhost:3000
bun --bun run dev

หรือรันเป็นแอปพลิเคชัน Desktop:

bun run electron:dev

ข้อกำหนดเบื้องต้น: Bun >= 1.0 และ Node.js >= 18

Docker

มี image หลายรูปแบบให้เลือก — เลือกแบบที่เหมาะกับความต้องการของคุณ:

Image ขนาด รวม
openpencil:latest ~226 MB เว็บแอปเท่านั้น
openpencil-claude:latest + Claude Code CLI
openpencil-codex:latest + Codex CLI
openpencil-opencode:latest + OpenCode CLI
openpencil-copilot:latest + GitHub Copilot CLI
openpencil-gemini:latest + Gemini CLI
openpencil-full:latest ~1 GB เครื่องมือ CLI ทั้งหมด

รัน (เว็บเท่านั้น):

docker run -d -p 3000:3000 ghcr.io/zseven-w/openpencil:latest

รันพร้อม AI CLI (เช่น Claude Code):

AI chat ต้องใช้การเข้าสู่ระบบ OAuth ของ Claude CLI ใช้ Docker volume เพื่อเก็บรักษา session การเข้าสู่ระบบ:

# ขั้นตอนที่ 1 — เข้าสู่ระบบ (ครั้งเดียว)
docker volume create openpencil-claude-auth
docker run -it --rm \
  -v openpencil-claude-auth:/root/.claude \
  ghcr.io/zseven-w/openpencil-claude:latest claude login

# ขั้นตอนที่ 2 — เริ่มต้น
docker run -d -p 3000:3000 \
  -v openpencil-claude-auth:/root/.claude \
  ghcr.io/zseven-w/openpencil-claude:latest

Build ในเครื่อง:

# พื้นฐาน (เว็บเท่านั้น)
docker build --target base -t openpencil .

# พร้อม CLI เฉพาะตัว
docker build --target with-claude -t openpencil-claude .

# เต็มรูปแบบ (CLI ทั้งหมด)
docker build --target full -t openpencil-full .

การออกแบบที่ขับเคลื่อนด้วย AI

จาก Prompt สู่ UI

  • ข้อความเป็นดีไซน์ — อธิบายหน้า แล้วสร้างขึ้นบน Canvas แบบเรียลไทม์พร้อม animation แบบ streaming
  • Orchestrator — แบ่งหน้าที่ซับซ้อนออกเป็น sub-task เชิงพื้นที่เพื่อการสร้างแบบขนาน
  • การแก้ไขดีไซน์ — เลือกองค์ประกอบ แล้วอธิบายการเปลี่ยนแปลงด้วยภาษาธรรมชาติ
  • Vision input — แนบ screenshot หรือ mockup เพื่อใช้เป็นข้อมูลอ้างอิงในการออกแบบ

รองรับหลาย Agent

Agent วิธีตั้งค่า
Claude Code ไม่ต้องตั้งค่า — ใช้ Claude Agent SDK พร้อม local OAuth
Codex CLI เชื่อมต่อใน Agent Settings (Cmd+,)
OpenCode เชื่อมต่อใน Agent Settings (Cmd+,)
GitHub Copilot copilot login จากนั้นเชื่อมต่อใน Agent Settings (Cmd+,)
Gemini CLI เชื่อมต่อใน Agent Settings (Cmd+,)

โปรไฟล์ความสามารถของโมเดล — ปรับ prompt, โหมด thinking และ timeout ตามระดับโมเดลโดยอัตโนมัติ โมเดลระดับเต็ม (Claude) ได้ prompt ครบถ้วน; โมเดลระดับมาตรฐาน (GPT-4o, Gemini, DeepSeek) ปิด thinking; โมเดลระดับพื้นฐาน (MiniMax, Qwen, Llama, Mistral) ได้ prompt แบบ nested-JSON ที่ย่อลงเพื่อความเสถียรสูงสุด

MCP Server

  • MCP Server ในตัว — ติดตั้งได้ด้วยคลิกเดียวใน Claude Code / Codex / Gemini / OpenCode / Kiro / Copilot CLIs
  • ตรวจจับ Node.js อัตโนมัติ — หากไม่ได้ติดตั้ง จะสำรองไปใช้ HTTP transport และเริ่ม MCP HTTP server โดยอัตโนมัติ
  • การทำ Design automation จาก terminal: อ่าน สร้าง และแก้ไขไฟล์ .op ผ่าน agent ที่รองรับ MCP
  • Layered design workflowdesign_skeletondesign_contentdesign_refine สำหรับดีไซน์หลายส่วนที่มีความละเอียดสูงขึ้น
  • Segmented prompt retrieval — โหลดเฉพาะความรู้ด้านดีไซน์ที่ต้องการ (schema, layout, roles, icons, planning ฯลฯ)
  • รองรับหลายหน้า — สร้าง เปลี่ยนชื่อ เรียงลำดับ และทำซ้ำหน้าผ่าน MCP tools

การสร้างโค้ด

  • React + Tailwind CSS, HTML + CSS, CSS Variables
  • Vue, Svelte, Flutter, SwiftUI, Jetpack Compose, React Native

ฟีเจอร์

Canvas และการวาด

  • Canvas ไม่จำกัดขนาดพร้อม pan, zoom, smart alignment guides และ snapping
  • Rectangle, Ellipse, Line, Polygon, Pen (Bezier), Frame, Text
  • การดำเนินการบูลีน — รวม ลบ ตัดกัน พร้อมแถบเครื่องมือตามบริบท
  • ตัวเลือก Icon (Iconify) และนำเข้ารูปภาพ (PNG/JPEG/SVG/WebP/GIF)
  • Auto-layout — แนวตั้ง/แนวนอนพร้อม gap, padding, justify, align
  • เอกสารหลายหน้าพร้อมการนำทางด้วย tab

Design System

  • Design variables — color, number, string tokens พร้อมการอ้างอิง $variable
  • รองรับหลาย theme — หลาย axis แต่ละ axis มี variants (Light/Dark, Compact/Comfortable)
  • ระบบ Component — component ที่นำกลับมาใช้ใหม่ได้พร้อม instance และ override
  • CSS sync — สร้าง custom properties อัตโนมัติ, var(--name) ในผลลัพธ์โค้ด

นำเข้าจาก Figma

  • นำเข้าไฟล์ .fig โดยคงไว้ซึ่ง layout, fills, strokes, effects, text, images และ vectors

Desktop App

  • รองรับ macOS, Windows และ Linux แบบ native ผ่าน Electron
  • เชื่อมโยงไฟล์ .op — ดับเบิลคลิกเพื่อเปิด, single-instance lock
  • อัปเดตอัตโนมัติจาก GitHub Releases
  • เมนูแอปพลิเคชันและ file dialog แบบ native

Tech Stack

Frontend React 19 · TanStack Start · Tailwind CSS v4 · shadcn/ui
Canvas CanvasKit/Skia (WASM, GPU-accelerated)
State Zustand v5
Server Nitro
Desktop Electron 35
AI Anthropic SDK · Claude Agent SDK · OpenCode SDK · Copilot SDK
Runtime Bun · Vite 7
รูปแบบไฟล์ .op — ใช้ JSON, อ่านได้โดยมนุษย์, Git-friendly

โครงสร้างโปรเจกต์

openpencil/
├── apps/
│   ├── web/                 TanStack Start web app
│   │   ├── src/
│   │   │   ├── canvas/      CanvasKit/Skia engine — การวาด, sync, layout
│   │   │   ├── components/  React UI — editor, panels, shared dialogs, icons
│   │   │   ├── services/ai/ AI chat, orchestrator, การสร้างดีไซน์, streaming
│   │   │   ├── stores/      Zustand — canvas, document, pages, history, AI
│   │   │   ├── mcp/         MCP server tools สำหรับการเชื่อมต่อ CLI ภายนอก
│   │   │   ├── hooks/       Keyboard shortcuts, file drop, Figma paste
│   │   │   └── uikit/       ระบบ component kit ที่นำกลับมาใช้ใหม่ได้
│   │   └── server/
│   │       ├── api/ai/      Nitro API — streaming chat, generation, validation
│   │       └── utils/       Claude CLI, OpenCode, Codex, Copilot wrappers
│   └── desktop/             Electron desktop app
│       ├── main.ts          Window, Nitro fork, native menu, auto-updater
│       ├── ipc-handlers.ts  ไดอะล็อกไฟล์เนทีฟ, ซิงค์ธีม, การตั้งค่า IPC
│       └── preload.ts       IPC bridge
├── packages/
│   ├── pen-types/           Type definitions สำหรับ PenDocument model
│   ├── pen-core/            Document tree ops, layout engine, variables
│   ├── pen-codegen/         Code generators (React, HTML, Vue, Flutter, ...)
│   ├── pen-figma/           Figma .fig file parser และ converter
│   ├── pen-renderer/        Standalone CanvasKit/Skia renderer
│   └── pen-sdk/             Umbrella SDK (re-exports ทุก package)
└── .githooks/               Pre-commit version sync จาก branch name

คีย์ลัด

คีย์ การทำงาน คีย์ การทำงาน
V เลือก Cmd+S บันทึก
R Rectangle Cmd+Z เลิกทำ
O Ellipse Cmd+Shift+Z ทำซ้ำ
L Line Cmd+C/X/V/D คัดลอก/ตัด/วาง/ทำซ้ำ
T Text Cmd+G จัดกลุ่ม
F Frame Cmd+Shift+G ยกเลิกการจัดกลุ่ม
P Pen tool Cmd+Shift+E ส่งออก
H Hand (pan) Cmd+Shift+C Code panel
Del ลบ Cmd+Shift+V Variables panel
[ / ] เรียงลำดับ Cmd+J AI chat
ลูกศร เลื่อน 1px Cmd+, Agent settings
Cmd+Alt+U รวมบูลีน Cmd+Alt+S ลบบูลีน
Cmd+Alt+I ตัดกันบูลีน

Scripts

bun --bun run dev          # Dev server (port 3000)
bun --bun run build        # Production build
bun --bun run test         # รันการทดสอบ (Vitest)
npx tsc --noEmit           # ตรวจสอบ type
bun run bump <version>     # Sync version ในทุก package.json
bun run electron:dev       # Electron dev
bun run electron:build     # Electron package

การมีส่วนร่วม

ยินดีต้อนรับการมีส่วนร่วมทุกรูปแบบ! ดู CLAUDE.md สำหรับรายละเอียดสถาปัตยกรรมและรูปแบบโค้ด

  1. Fork และ clone
  2. ตั้งค่า version sync: git config core.hooksPath .githooks
  3. สร้าง branch: git checkout -b feat/my-feature
  4. รันการตรวจสอบ: npx tsc --noEmit && bun --bun run test
  5. Commit ด้วย Conventional Commits: feat(canvas): add rotation snapping
  6. เปิด PR เข้า main

Roadmap

  • Design variables และ tokens พร้อม CSS sync
  • ระบบ Component (instances และ overrides)
  • การสร้างดีไซน์ด้วย AI พร้อม orchestrator
  • การเชื่อมต่อ MCP server พร้อม layered design workflow
  • รองรับหลายหน้า
  • นำเข้า Figma .fig
  • Boolean operations (union, subtract, intersect)
  • โปรไฟล์ความสามารถหลายโมเดล
  • ปรับโครงสร้างเป็น monorepo พร้อม package ที่นำกลับมาใช้ใหม่ได้
  • การแก้ไขร่วมกัน
  • ระบบปลั๊กอิน

ผู้มีส่วนร่วม

Contributors

ชุมชน

Discord เข้าร่วม Discord ของเรา — ถามคำถาม แชร์ดีไซน์ เสนอฟีเจอร์

Star History

Star History Chart

สัญญาอนุญาต

MIT — Copyright (c) 2026 ZSeven-W