@dxtmisha/wiki 0.57.3 → 0.57.6

package/src/media/functional/ui-figma/about/about.vi.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI Figma/! Giới thiệu về thư viện'/>
+
+# Hệ sinh thái UI Figma
+
+Hệ thống `UI Figma` là một cơ sở hạ tầng toàn diện để phát triển các plugin Figma. Nó được thiết kế để xóa bỏ rào cản giữa "phía Mã" (backend của plugin) và "phía UI" (frontend), cung cấp khả năng tương tác liền mạch, quản lý dữ liệu phản hồi và định kiểu dữ liệu đầy đủ.
+
+Hệ sinh thái được xây dựng trên kiến trúc ba tầng, trong đó mỗi lớp xử lý một phần cụ thể trong vòng đời của plugin.
+
+## Ba tầng tương tác
+
+### 1. Cốt lõi giao tiếp (@dxtmisha/figma)
+Gói cơ bản xác định các giao thức tương tác. Nó bao gồm:
+- Các hằng số loại tin nhắn.
+- Các kiểu dữ liệu và giao diện dùng chung.
+- Các lớp trình nhắn tin trừu tượng để tiêu chuẩn hóa việc trao đổi dữ liệu.
+- Các tiện ích để định tuyến tin nhắn giữa UI và sandbox của Figma.
+
+### 2. Logic Plugin (@dxtmisha/figma-code)
+Một gói chạy trong môi trường thực thi của Figma (Sandbox). Đây là "bộ não" của plugin, có quyền truy cập trực tiếp vào Figma API:
+- **Phân tích phần tử**: Các lớp `FigmaItem` và `FigmaFrame` để khám phá sâu cấu trúc tài liệu.
+- **Lưu trữ dữ liệu**: `FigmaStorage` để làm việc với PluginData (lưu trữ dữ liệu trực tiếp trong tệp `.fig`).
+- **Xuất dữ liệu**: Các công cụ để tự động tạo ảnh chụp màn hình và xuất tài sản.
+- **Đồng bộ hóa**: Các lớp `FigmaTopLevelFrames` và `FigmaFramesSelected` để chuyển trạng thái tài liệu hiện tại sang UI.
+
+### 3. Giao diện phản hồi (@dxtmisha/figma-ref)
+Một gói để phát triển giao diện người dùng bằng Vue 3. Nó chuyển đổi các phản hồi bất đồng bộ từ plugin thành các tham chiếu phản hồi (composables) thuận tiện:
+- **Kho lưu trữ phản hồi**: `useFigmaStorage` và `useFigmaClientStorage` để liên kết dữ liệu tức thì giữa UI và bộ nhớ Figma.
+- **Trình quan sát**: `useFigmaUiFrames` để tự động cập nhật danh sách các frame có sẵn.
+- **Quản lý lựa chọn**: `useFigmaUiSelected` để liên kết các phần tử được chọn trong UI với vùng lựa chọn hoạt động trong Figma.
+
+## Các tính năng của hệ thống
+
+**Tương tác liền mạch**
+Các nhà phát triển không còn cần phải quản lý thủ công các lệnh gọi `postMessage` và trình lắng nghe sự kiện. Hệ thống tự động xử lý việc định tuyến và xác thực kiểu dữ liệu.
+
+**Tính phản hồi có sẵn**
+Sử dụng Vue Composition API cho phép bạn xây dựng giao diện plugin dễ dàng như các ứng dụng web tiêu chuẩn, với dữ liệu tự động được lưu trữ bền vững trong tài liệu Figma.
+
+**An toàn kiểu dữ liệu**
+Tất cả các tin nhắn và cấu trúc dữ liệu đều được định kiểu nghiêm ngặt, loại bỏ lỗi khi chuyển dữ liệu giữa các môi trường biệt lập (UI và Sandbox).
+
+## Tại sao nên sử dụng hệ sinh thái này?
+
+- **Tốc độ phát triển**: Nền tảng có sẵn cho các tác vụ điển hình (lựa chọn, cài đặt, ảnh chụp màn hình).
+- **Kiến trúc sạch**: Phân tách rõ ràng các mối quan tâm giữa logic nghiệp vụ và giao diện người dùng.
+- **Khả năng mở rộng**: Dễ dàng thêm các tính năng mới nhờ cấu trúc mô-đun và mô hình Messenger.
+
+## Git
+
+[https://github.com/dxtmisha/dxt-ui/tree/main/packages/figma](https://github.com/dxtmisha/dxt-ui/tree/main/packages/figma)

package/src/media/functional/ui-figma/frames/frames.en.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/# UI Figma/# Working with Frames'/>
+
+# Working with Frames
+
+The library provides tools for managing the list of frames on the current Figma page and tracking selected elements. This allows you to build complex navigation interfaces and bulk selection systems within your plugin.
+
+## Backend (Backend / plugin/code.ts)
+
+For automatic frame data synchronization, the corresponding handlers must be initialized on the plugin side.
+
+### Initialization
+```typescript
+import { FigmaTopLevelFrames, FigmaFramesSelected } from '@dxtmisha/figma-code'
+
+// Activate listeners for frame list and selection management
+FigmaTopLevelFrames.send()
+FigmaFramesSelected.send()
+```
+
+## Interface (UI / Iframe)
+
+Data about all frames on the page and tools for managing the plugin's internal selection list are available in the interface.
+
+### Page Frame List (Vue)
+Allows you to retrieve a list of all frames and sections at the root of the current page with screenshots.
+
+```typescript
+import { useFigmaUiFrames } from '@dxtmisha/figma-ref'
+
+const { frames, loading } = useFigmaUiFrames()
+
+/* frames.value contains a list of objects:
+  {
+    id: string,
+    name: string,
+    image: Uint8Array | string // JPG screenshot
+  }
+*/
+```
+
+### Plugin Selected Elements (Vue)
+A mechanism for tracking and modifying the list of "selected" elements within the plugin's interface. This state is preserved globally at the plugin session level.
+
+```typescript
+import { useFigmaUiSelected } from '@dxtmisha/figma-ref'
+
+const { 
+  selected,       // List of selected frame IDs
+  isSelected,     // Check function: isSelected(id)
+  toggleSelected, // Toggle function: toggleSelected(id, boolean)
+} = useFigmaUiSelected()
+
+// Example usage:
+const active = isSelected('1:123')
+const toggle = () => toggleSelected('1:123', !active.value)
+```

package/src/media/functional/ui-figma/frames/frames.ru.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI Figma/# Работа с фреймами'/>
+
+# Работа с фреймами
+
+Библиотека предоставляет инструменты для управления списком фреймов на текущей странице Figma и отслеживания выбранных элементов. Это позволяет строить сложные интерфейсы навигации и системы массового выбора внутри плагина.
+
+## Бэкенд (Backend / plugin/code.ts)
+
+Для автоматической синхронизации данных о фреймах необходимо инициализировать соответствующие обработчики на стороне плагина.
+
+### Инициализация
+```typescript
+import { FigmaTopLevelFrames, FigmaFramesSelected } from '@dxtmisha/figma-code'
+
+// Активация слушателей списка фреймов и управления выбором
+FigmaTopLevelFrames.send()
+FigmaFramesSelected.send()
+```
+
+## Интерфейс (UI / Iframe)
+
+В интерфейсе доступны данные о всех фреймах страницы и инструменты для управления внутренним списком выбора плагина.
+
+### Список фреймов страницы (Vue)
+Позволяет получить список всех фреймов и секций в корне текущей страницы со скриншотами.
+
+```typescript
+import { useFigmaUiFrames } from '@dxtmisha/figma-ref'
+
+const { frames, loading } = useFigmaUiFrames()
+
+/* frames.value содержит список объектов:
+  {
+    id: string,
+    name: string,
+    image: Uint8Array | string // Скриншот JPG
+  }
+*/
+```
+
+### Выбранные элементы плагина (Vue)
+Механизм для отслеживания и изменения списка «выбранных» элементов внутри интерфейса плагина. Это состояние сохраняется глобально на уровне сессии плагина.
+
+```typescript
+import { useFigmaUiSelected } from '@dxtmisha/figma-ref'
+
+const { 
+  selected,       // Список ID выбранных фреймов
+  isSelected,     // Функция проверки: isSelected(id)
+  toggleSelected, // Функция переключения: toggleSelected(id, boolean)
+} = useFigmaUiSelected()
+
+// Пример использования:
+const active = isSelected('1:123')
+const toggle = () => toggleSelected('1:123', !active.value)
+```

package/src/media/functional/ui-figma/frames/frames.vi.mdx

@@ -0,0 +1,58 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI Figma/# Làm việc với Frame'/>
+
+# Làm việc với Frame
+
+Thư viện cung cấp các công cụ để quản lý danh sách các frame trên trang Figma hiện tại và theo dõi các phần tử được chọn. Điều này cho phép bạn xây dựng các giao diện điều hướng phức tạp và hệ thống chọn hàng loạt bên trong plugin của mình.
+
+## Backend (Backend / plugin/code.ts)
+
+Để đồng bộ hóa dữ liệu frame tự động, các trình xử lý tương ứng phải được khởi tạo ở phía plugin.
+
+### Khởi tạo
+```typescript
+import { FigmaTopLevelFrames, FigmaFramesSelected } from '@dxtmisha/figma-code'
+
+// Kích hoạt trình lắng nghe cho danh sách frame và quản lý vùng chọn
+FigmaTopLevelFrames.send()
+FigmaFramesSelected.send()
+```
+
+## Giao diện (UI / Iframe)
+
+Dữ liệu về tất cả các frame trên trang và các công cụ để quản lý danh sách vùng chọn nội bộ của plugin có sẵn trong giao diện.
+
+### Danh sách Frame của trang (Vue)
+Cho phép bạn lấy danh sách tất cả các frame và section tại thư mục gốc của trang hiện tại kèm theo ảnh chụp màn hình.
+
+```typescript
+import { useFigmaUiFrames } from '@dxtmisha/figma-ref'
+
+const { frames, loading } = useFigmaUiFrames()
+
+/* frames.value chứa danh sách các đối tượng:
+  {
+    id: string,
+    name: string,
+    image: Uint8Array | string // Ảnh chụp màn hình JPG
+  }
+*/
+```
+
+### Các phần tử được chọn trong Plugin (Vue)
+Một cơ chế để theo dõi và sửa đổi danh sách các phần tử "được chọn" trong giao diện của plugin. Trạng thái này được duy trì trên toàn cầu ở cấp độ phiên plugin.
+
+```typescript
+import { useFigmaUiSelected } from '@dxtmisha/figma-ref'
+
+const { 
+  selected,       // Danh sách ID các frame được chọn
+  isSelected,     // Hàm kiểm tra: isSelected(id)
+  toggleSelected, // Hàm chuyển đổi: toggleSelected(id, boolean)
+} = useFigmaUiSelected()
+
+// Ví dụ sử dụng:
+const active = isSelected('1:123')
+const toggle = () => toggleSelected('1:123', !active.value)
+```

package/src/media/functional/ui-figma/messenger/messenger.en.mdx

@@ -0,0 +1,67 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/# UI Figma/# Messenger System'/>
+
+# Working with Messages (Messenger)
+
+The messaging mechanism is the central link in the architecture of Figma plugins. Since the "Code Side" (Sandbox) and the "Interface Side" (UI) run in isolated environments, any interaction between them requires the use of the `postMessage` system.
+
+The library simplifies this process by providing standardized messengers and automatic routing.
+
+## Initialization and Security
+
+Figma plugins operate in an environment where multiple plugins can be active simultaneously. To prevent message conflicts and ensure that your UI only processes data from your specific plugin, the library uses the `FigmaPostCode` system.
+
+Both the **Backend** and the **Interface** must be initialized with the same unique identifier (typically the `id` from your `manifest.json`) before using the messengers.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import manifest from '../manifest.json'
+
+// Must be called on both sides (Code and UI)
+FigmaPostCode.set(manifest.id)
+```
+
+## Backend (Backend / plugin/code.ts)
+
+On the code side, the `FigmaPluginMessenger` class is used to subscribe to events and send data to the UI.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import { FigmaPluginMessenger } from '@dxtmisha/figma-code'
+import manifest from '../manifest.json'
+
+// 1. Initialize identification
+FigmaPostCode.set(manifest.id)
+
+// 2. Work with the messenger
+const messenger = FigmaPluginMessenger.getInstance()
+
+messenger.add('my-action', (data) => {
+  console.log('Data received:', data)
+  messenger.post('my-action', { status: 'success' })
+})
+```
+
+## Interface (UI / Iframe)
+
+In the interface, the mirror class `FigmaUiMessenger` is used for interaction with the backend.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import { FigmaUiMessenger } from '@dxtmisha/figma'
+import manifest from '../manifest.json'
+
+// 1. Initialize identification (same ID as backend)
+FigmaPostCode.set(manifest.id)
+
+// 2. Work with the messenger
+const messenger = FigmaUiMessenger.getInstance()
+
+messenger.post('my-action', { payload: 'hello' })
+
+messenger.add('my-action', (result) => {
+  console.log('Result:', result)
+})
+```
+

package/src/media/functional/ui-figma/messenger/messenger.ru.mdx

@@ -0,0 +1,67 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI Figma/# Система мессенджеров'/>
+
+# Работа с сообщениями (Messenger)
+
+Механизм сообщений — центральное звено архитектуры Figma-плагинов. Поскольку «сторона кода» (Sandbox) и «сторона интерфейса» (UI) работают в изолированных средах, любое взаимодействие между ними требует использования системы `postMessage`.
+
+Библиотека упрощает этот процесс, предоставляя стандартизированные мессенджеры и автоматическую маршрутизацию.
+
+## Инициализация и безопасность
+
+Плагины Figma работают в среде, где одновременно могут быть активны несколько плагинов. Чтобы предотвратить конфликты сообщений и гарантировать, что ваш UI обрабатывает данные только от вашего конкретного плагина, библиотека использует систему `FigmaPostCode`.
+
+Обе стороны (**Бэкенд** и **Интерфейс**) должны быть инициализированы одним и тем же уникальным идентификатором (обычно это `id` из вашего `manifest.json`) перед использованием мессенджеров.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import manifest from '../manifest.json'
+
+// Необходимо вызвать на обеих сторонах (Code и UI)
+FigmaPostCode.set(manifest.id)
+```
+
+## Бэкенд (Backend / plugin/code.ts)
+
+На стороне кода используется класс `FigmaPluginMessenger` для подписки на события и отправки данных в UI.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import { FigmaPluginMessenger } from '@dxtmisha/figma-code'
+import manifest from '../manifest.json'
+
+// 1. Инициализация идентификации
+FigmaPostCode.set(manifest.id)
+
+// 2. Работа с мессенджером
+const messenger = FigmaPluginMessenger.getInstance()
+
+messenger.add('my-action', (data) => {
+  console.log('Данные получены:', data)
+  messenger.post('my-action', { status: 'success' })
+})
+```
+
+## Интерфейс (UI / Iframe)
+
+В интерфейсе используется зеркальный класс `FigmaUiMessenger` для взаимодействия с бэкендом.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import { FigmaUiMessenger } from '@dxtmisha/figma'
+import manifest from '../manifest.json'
+
+// 1. Инициализация идентификации (тот же ID, что и в бэкенде)
+FigmaPostCode.set(manifest.id)
+
+// 2. Работа с мессенджером
+const messenger = FigmaUiMessenger.getInstance()
+
+messenger.post('my-action', { payload: 'hello' })
+
+messenger.add('my-action', (result) => {
+  console.log('Результат:', result)
+})
+```
+

package/src/media/functional/ui-figma/messenger/messenger.vi.mdx

@@ -0,0 +1,67 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI Figma/# Hệ thống Messenger'/>
+
+# Làm việc với tin nhắn (Messenger)
+
+Cơ chế gửi tin nhắn là mắt xích trung tâm trong kiến trúc của các plugin Figma. Vì "Phía Mã" (Sandbox) và "Phía Giao diện" (UI) chạy trong các môi trường biệt lập, nên bất kỳ tương tác nào giữa chúng đều yêu cầu sử dụng hệ thống `postMessage`.
+
+Thư viện đơn giản hóa quy trình này bằng cách cung cấp các messenger tiêu chuẩn hóa và định tuyến tự động.
+
+## Khởi tạo và Bảo mật
+
+Các plugin Figma hoạt động trong môi trường có thể có nhiều plugin cùng hoạt động. Để ngăn chặn xung đột tin nhắn và đảm bảo UI của bạn chỉ xử lý dữ liệu từ plugin cụ thể của mình, thư viện sử dụng hệ thống `FigmaPostCode`.
+
+Cả **Backend** và **Giao diện** phải được khởi tạo với cùng một mã định danh duy nhất (thường là `id` từ `manifest.json` của bạn) trước khi sử dụng messenger.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import manifest from '../manifest.json'
+
+// Phải được gọi ở cả hai phía (Code và UI)
+FigmaPostCode.set(manifest.id)
+```
+
+## Backend (Backend / plugin/code.ts)
+
+Về phía mã, lớp `FigmaPluginMessenger` được sử dụng để đăng ký các sự kiện và gửi dữ liệu đến UI.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import { FigmaPluginMessenger } from '@dxtmisha/figma-code'
+import manifest from '../manifest.json'
+
+// 1. Khởi tạo định danh
+FigmaPostCode.set(manifest.id)
+
+// 2. Làm việc với messenger
+const messenger = FigmaPluginMessenger.getInstance()
+
+messenger.add('my-action', (data) => {
+  console.log('Dữ liệu đã nhận:', data)
+  messenger.post('my-action', { status: 'success' })
+})
+```
+
+## Giao diện (UI / Iframe)
+
+Trong giao diện, lớp gương `FigmaUiMessenger` được sử dụng để tương tác với backend.
+
+```typescript
+import { FigmaPostCode } from '@dxtmisha/figma'
+import { FigmaUiMessenger } from '@dxtmisha/figma'
+import manifest from '../manifest.json'
+
+// 1. Khởi tạo định danh (cùng ID với backend)
+FigmaPostCode.set(manifest.id)
+
+// 2. Làm việc với messenger
+const messenger = FigmaUiMessenger.getInstance()
+
+messenger.post('my-action', { payload: 'hello' })
+
+messenger.add('my-action', (result) => {
+  console.log('Kết quả:', result)
+})
+```
+

package/src/media/functional/ui-figma/selection/selection.en.mdx

@@ -0,0 +1,65 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/# UI Figma/# Frame Selection'/>
+
+# Working with Selection
+
+The selection system provides a connection between the Figma canvas and the plugin interface. It allows the application to react to user actions in the editor and manage focus programmatically.
+
+## Backend (Backend / plugin/code.ts)
+
+On the plugin's code side, it is necessary to initialize synchronization mechanisms and, if needed, use functions for programmatic focus.
+
+#### Initialization
+Call one of the functions depending on the required level of control:
+
+- **`setupFrameSelection()`** — Recommended. Sets up bidirectional communication (tracking + programmatic selection from the UI).
+- **`makeFigmaFrameSelection()`** — Sets up only tracking of changes on the Figma canvas (Backend -> UI).
+
+```typescript
+import { setupFrameSelection } from '@dxtmisha/figma-code'
+
+// Called once during plugin startup
+setupFrameSelection()
+```
+
+#### Programmatic Management
+If you need to select an object and focus the camera on it directly from the backend code:
+
+```typescript
+import { toFrameSelection } from '@dxtmisha/figma-code'
+
+await toFrameSelection('12:34')
+```
+
+## Interface (UI / Iframe)
+
+Tools for retrieving current selection data and commanding changes from the plugin interface.
+
+#### Reactive Usage (Vue)
+The most convenient way is through the `useFigmaFrameSelection` composable.
+
+```typescript
+import { useFigmaFrameSelection } from '@dxtmisha/figma-ref'
+
+const { 
+  selection,    // List of selected frames (ComputedRef)
+  setSelection, // Method to change selection: setSelection(id)
+  loading       // Loading state
+} = useFigmaFrameSelection()
+```
+
+#### Direct Control (JavaScript)
+If you are not using Vue, you can send a command or manually subscribe to changes:
+
+```typescript
+import { sendFrameSelection, fetchFrameSelection } from '@dxtmisha/figma'
+
+// Change selection
+sendFrameSelection('12:34')
+
+// Subscribe to changes manually
+fetchFrameSelection((selection) => {
+  console.log('Current selection:', selection)
+})
+```

package/src/media/functional/ui-figma/selection/selection.ru.mdx

@@ -0,0 +1,65 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI Figma/# Работа с выделением'/>
+
+# Работа с выделением
+
+Система выделения обеспечивает связь между холстом Figma и интерфейсом плагина. Она позволяет приложению реагировать на действия пользователя в редакторе и управлять фокусом программно.
+
+## Бэкенд (Backend / plugin/code.ts)
+
+На стороне кода плагина необходимо инициализировать механизмы синхронизации и, при необходимости, использовать функции для программного фокуса.
+
+#### Инициализация
+Вызовите одну из функций в зависимости от требуемого уровня контроля:
+
+- **`setupFrameSelection()`** — Рекомендуется. Настраивает двустороннюю связь (отслеживание + программное выделение из UI).
+- **`makeFigmaFrameSelection()`** — Настраивает только отслеживание изменений на холсте Figma (Backend -> UI).
+
+```typescript
+import { setupFrameSelection } from '@dxtmisha/figma-code'
+
+// Вызывается один раз при старте плагина
+setupFrameSelection()
+```
+
+#### Программное управление
+Если нужно выделить объект и сфокусировать на нем камеру прямо из кода бэкенда:
+
+```typescript
+import { toFrameSelection } from '@dxtmisha/figma-code'
+
+await toFrameSelection('12:34')
+```
+
+## Интерфейс (UI / Iframe)
+
+Инструменты для получения данных о текущем выделении и подачи команд на его изменение из интерфейса плагина.
+
+#### Реактивное использование (Vue)
+Самый удобный способ работы через композитор `useFigmaFrameSelection`.
+
+```typescript
+import { useFigmaFrameSelection } from '@dxtmisha/figma-ref'
+
+const { 
+  selection,    // Список выделенных фреймов (ComputedRef)
+  setSelection, // Метод для смены выделения: setSelection(id)
+  loading       // Состояние загрузки
+} = useFigmaFrameSelection()
+```
+
+#### Прямое управление (JavaScript)
+Если вы не используете Vue, можно отправить команду или вручную подписаться на изменения:
+
+```typescript
+import { sendFrameSelection, fetchFrameSelection } from '@dxtmisha/figma'
+
+// Сменить выделение
+sendFrameSelection('12:34')
+
+// Подписаться на изменения вручную
+fetchFrameSelection((selection) => {
+  console.log('Текущее выделение:', selection)
+})
+```

package/src/media/functional/ui-figma/selection/selection.vi.mdx

@@ -0,0 +1,65 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI Figma/# Quản lý vùng chọn'/>
+
+# Quản lý vùng chọn
+
+Hệ thống vùng chọn cung cấp sự kết nối giữa canvas Figma và giao diện plugin. Nó cho phép ứng dụng phản ứng với các hành động của người dùng trong trình chỉnh sửa và quản lý tiêu điểm theo chương trình.
+
+## Backend (Backend / plugin/code.ts)
+
+Về phía mã của plugin, cần phải khởi tạo các cơ chế đồng bộ hóa và, nếu cần, sử dụng các hàm để lấy nét theo chương trình.
+
+#### Khởi tạo
+Gọi một trong các hàm tùy thuộc vào mức độ kiểm soát yêu cầu:
+
+- **`setupFrameSelection()`** — Được khuyến nghị. Thiết lập giao tiếp hai chiều (theo dõi + chọn theo chương trình từ UI).
+- **`makeFigmaFrameSelection()`** — Chỉ thiết lập theo dõi các thay đổi trên canvas Figma (Backend -> UI).
+
+```typescript
+import { setupFrameSelection } from '@dxtmisha/figma-code'
+
+// Được gọi một lần khi khởi động plugin
+setupFrameSelection()
+```
+
+#### Quản lý theo chương trình
+Nếu bạn cần chọn một đối tượng và lấy nét camera vào đối tượng đó trực tiếp từ mã backend:
+
+```typescript
+import { toFrameSelection } from '@dxtmisha/figma-code'
+
+await toFrameSelection('12:34')
+```
+
+## Giao diện (UI / Iframe)
+
+Các công cụ để lấy dữ liệu vùng chọn hiện tại và ra lệnh thay đổi từ giao diện plugin.
+
+#### Sử dụng phản hồi (Vue)
+Cách thuận tiện nhất là thông qua `useFigmaFrameSelection` composable.
+
+```typescript
+import { useFigmaFrameSelection } from '@dxtmisha/figma-ref'
+
+const { 
+  selection,    // Danh sách các frame được chọn (ComputedRef)
+  setSelection, // Phương thức thay đổi vùng chọn: setSelection(id)
+  loading       // Trạng thái tải
+} = useFigmaFrameSelection()
+```
+
+#### Điều khiển trực tiếp (JavaScript)
+Nếu bạn không sử dụng Vue, bạn có thể gửi lệnh hoặc đăng ký thay đổi thủ công:
+
+```typescript
+import { sendFrameSelection, fetchFrameSelection } from '@dxtmisha/figma'
+
+// Thay đổi vùng chọn
+sendFrameSelection('12:34')
+
+// Đăng ký thay đổi thủ công
+fetchFrameSelection((selection) => {
+  console.log('Vùng chọn hiện tại:', selection)
+})
+```