figma-ai-plugin/KNOWLEDGE.md

Knowledge — Figma AI Plugin

Копилка находок и решений по проекту. Не наступай на грабли дважды. Пополняется по ходу разработки. Формат: проблема → решение (+ контекст/ссылка). Hermes имеет право править и дополнять этот файл самостоятельно (см. IDEA.md).

Сборка / окружение

TypeScript 7.x ломает @create-figma-plugin/build

• Симптом: TypeError: Cannot read properties of undefined (reading 'getCurrentDirectory') при build-figma-plugin.
• Причина: build-figma-plugin ожидает ts.sys, которого нет в TS 7.
• Решение: зафиксировать typescript на ~5.6.3 в package.json devDependencies.
• Ссылка: package.json

tsconfig: не оверрайдить jsx на react-jsx

• Симптом: error TS5089: Option 'jsxFactory' cannot be specified when option 'jsx' is 'react-jsx'.
• Причина: базовый @create-figma-plugin/tsconfig уже задаёт jsx: react + jsxFactory: h.
• Решение: в проектном tsconfig только extends + добавляем lib/types. Не трогать jsx/jsxFactory. Preact h уже импортируется в ui.tsx.
• Ссылка: tsconfig.json

Text muted не существует — используй Muted

• Симптом: Property 'muted' does not exist on type ... Text.
• Решение: для приглушённого текста брать компонент <Muted> из @create-figma-plugin/ui, а не проп muted у <Text>.
• Ссылка: src/ui.tsx

Плагин не запускается в Figma — нет папки build/ на Matebook

• Симптом: плагин не открывается / Figma молча ничего не делает при Run (ошибка не всегда видна).
• Причина: manifest.json указывает main: build/main.js и ui: build/ui.js, но в скопированной на Matebook папке папки build/ нет (старая команда синхронизации исключала её через --exclude build).
• Решение: пересобрать на VPS (npm run build) и залить на Matebook ВЕСЬ проект вместе с build/ — исключать только node_modules и .git (они для запуска в Figma не нужны, Figma исполняет собранные build/*.js). После распаковки проверить наличие build/main.js и build/ui.js.
• Ссылка: IDEA.md (раздел «Рабочий флоу», шаг 4), этот файл (раздел синхронизации через tar).

Рабочий флоу (VPS → Matebook → Figma)

Копия на Matebook через tar (rsync/scp с пробелами в пути падают)

• Симптом: rsync: command not found (на Windows), scp: ambiguous target (пробел в пути).
• Решение:
  1. На VPS: npm run build (обязательно — иначе нет папки build/)
  2. На VPS: tar czf /tmp/x.tar.gz --exclude node_modules --exclude .git . ← build/ НЕ исключать!
  3. scp /tmp/x.tar.gz risow@10.200.201.5:D:/x.tar.gz
  4. На Matebook (PowerShell): Set-Location 'D:/Figma Plugins/figma-ai-plugin'; tar xzf 'D:/x.tar.gz'
• Ловушка: старая команда исключала --exclude build → в папке плагина на Matebook не было build/, и Figma не находила build/main.js/build/ui.js → плагин не запускался. См. gotcha «Плагин не запускается — нет build/».
• Ссылка: IDEA.md (раздел «Рабочий флоу»)

Gitea push через токен в URL

• Симптом: could not read Username при git push (нет credential helper).
• Решение: remote как http://<TOKEN>:@<host>/admin/figma-ai-plugin.git. Токен должен иметь scope write:repository (без write:user создать репо нельзя — создавать через basic auth admin-ом).
• Ссылка: IDEA.md, Gitea http://x1qnvk08zec2u5cx6yh5iexh.155.212.186.39.sslip.io/admin/figma-ai-plugin

Ресурсы (не терять)

• UI Storybook: https://yuanqing.github.io/create-figma-plugin/ui/
• Figma Plugin API docs: https://www.figma.com/plugin-docs/
• Исходный плагин «AI assistant» (движок): D:\YandexDisk\Figma Plugins DEVs\AI assistant (Matebook)