@energy8platform/golem 0.1.0

package/README.md

@@ -0,0 +1,376 @@
+# @energy8platform/golem — прототип AI-first риггинга для слотов
+
+Документ (`rig.json`, формат v2) — источник истины. Агент работает через MCP, человек — через вьюер и редактор в браузере (`npm run editor`). Рантайм — PixiJS v8.
+
+```
+src/rig-format.ts       схема документа (zod) + семантическая валидация; v1: deform-треки, asset.frame (атлас)
+src/rig-anim.ts         чистая математика: easing, семплирование, Pose, аффинные матрицы костей, контуры слотов
+src/rig-deform.ts       3×3 деформер картинки: именованные параметры → смещения точек, биквадратичный патч, якобиан
+src/rig-constraints.ts  ограничения без решателя: кто кем управляет, цепь IK, знак сгиба, досягаемость, кривая по точкам
+src/rig-state.ts        AnimationState: base-цикл, очередь с приоритетами, overlay-слои (моргание), crossfade
+src/rig-runtime.ts      RigPlayer для PixiJS v8: Sprite или MeshPlane на слот, setPose, createTextures (атлас)
+src/rig-symbol.ts       RigSymbol — адаптер под SymbolView из @energy8platform/game-engine
+src/rig-presets.ts      пресеты: idle_breathing, weight_shift, win_bounce, anticipation_shake, blink, mouth_talk, dim, symbol_idle, symbol_win
+src/rig-tools.ts        операции над документом, импорт слоёв (swap/bone), createSymbol, replaceAsset, layerPrompt
+src/rig-check.ts        автокритика без рендера: out_of_canvas, static_track, loop_seam, deform_flip, patch_offset, motion_pop, …
+src/rig-history.ts      снимки .rig-history/, undo, структурный diff
+src/rig-atlas.ts        упаковка PNG-слоёв в atlas.png с экструзией краёв
+src/rig-templates.ts    rig_save_as_preset: шаблон из готовой анимации (треки относительно rest, кости по role, множители)
+src/preview/            renderPreview: headless Chromium → контакт-лист PNG (onion skin) для агента
+src/rig-api.ts          реестр инструментов — MCP, CLI и редактор регистрируют один список
+src/mcp-server.ts       MCP (stdio) поверх всего этого
+src/editor/             редактор: сервер (HTTP/SSE), сцена, гизмо, таймлайн, панели
+scripts/smoke.ts        прогон всей петли без агента + проверки меша/атласа/символа
+scripts/verify-mcp.ts   интеграционный маршрут через настоящий stdio MCP
+scripts/verify-engine.mjs  RigSymbol внутри настоящей SymbolCell движка (из соседнего проекта игры)
+scripts/rig-cli.ts      те же MCP-инструменты из shell: `npm run rig -- <tool> '<json>'`
+examples/hero/          тестовый персонаж из прямоугольников + layers.json
+examples/cashier/       настоящий персонаж (cashier.png) и список его анимаций anim.md
+ross/                   настоящий Spine-проект (json + atlas + ktx2) — оракул и демо импорта
+docs/superpowers/specs/ проектные решения этапа 2 (mesh, состояние, атлас, агентский UX)
+```
+
+## Установка
+
+```bash
+npm install
+npx playwright install chromium     # один раз
+npm run build:harness               # бандл для headless-рендера (после правок runtime/harness — повторить)
+npm run typecheck
+npm test
+```
+
+## Шаг 1 — smoke без агента
+
+```bash
+npm run smoke
+```
+Пишет `examples/hero/rig.json`, `examples/hero/out/{rest,idle,win,anticipation,win_onion}.png`,
+экспорт с атласом в `examples/hero/out/export/`, символ из одной картинки в `examples/symbol/`.
+Проверяет: непустой WebGL-кадр, различие кадров, **меш при нулевой деформации = спрайт (0 px)**,
+**рендер из атласа = рендер из файлов (0 px)** в том числе для деформированного торса, onion skin, `rig_check` без ошибок.
+
+Что должно быть видно глазами:
+- `rest.png` — персонаж собран, кости (оверлей) стоят в суставах, подписи `id (role)`.
+- `idle.png` — грудь дышит (меш, шея и пояс закреплены, голова не тянется), голова покачивается, руки чуть ходят.
+- `win.png` — два прыжка с затуханием, squash/stretch; `win_onion.png` — то же с призраком предыдущего кадра.
+- `examples/symbol/out/win.png` — pop масштаба и затухающее желе одной картинки.
+
+## Шаг 2 — петля с агентом
+
+Подключи MCP в Claude Code (`.mcp.json` в корне проекта):
+```json
+{ "mcpServers": { "rig": { "command": "npx", "args": ["tsx", "src/mcp-server.ts"], "cwd": "<абсолютный путь к rig>" } } }
+```
+
+Инструменты:
+
+| Группа | Инструменты |
+|---|---|
+| Документ | `rig_create`, `rig_create_symbol` (риг из одной картинки), `rig_set_meta` (имя, холст, notes, референс-подложка `reference`; `null` убирает подложку), `rig_get`, `rig_get_attachment` (одно вложение целиком — массивы `vertices`/`weights` для сырой правки), `rig_rename` (переименование кости/слота/attachment/ассета/ограничения с переписыванием всех ссылок; `presets.json` и `preset.params` анимаций не переписываются — ответ называет, где остался старый id), `rig_validate`, `rig_check` |
+| Ассеты | `rig_set_asset` (ассет из целой картинки или прямоугольника `frame` в ней — файлов-вырезок нет; переразметка кадра держит на месте исходный пиксель под центром картинки; меш при этом сохраняет старые uvs, инструмент называет его в ответе — перетрассируйте его заново (`rig_mesh_from_image`)), `rig_remove_asset` (отказ, пока ассет показан хоть одним attachment), `rig_place_asset` (слот + region + показ одним вызовом, `z = max + 1`) |
+| Слои | `rig_import_layers` (`layers.json`: `swap`, `bone`), `rig_replace_asset`, `rig_layer_prompt` (промпт перегенерации по провенансу) |
+| История | `rig_undo(steps)`, `rig_diff(steps)` — снимки в `.rig-history/` рядом с `rig.json` |
+| Скелет | `rig_add_bone` (`bind` сразу переносит слоты на новую кость, не сдвигая картинку), `rig_update_bone`, `rig_remove_bone` (слоты уходят к родителю тоже без сдвига), `rig_set_slot` (смена `bone` сохраняет мировое положение: regions пересчитываются в новой кости, взвешенные меши не трогаются), `rig_remove_slot`, `rig_set_draw_order` (список слоёв сзади наперёд одним вызовом, `z = index`) |
+| Поза и цель | `rig_get_pose` (обратная связь числами: мировые `x`,`y`,`angle`,`scaleX/Y` и локальные `x`,`y`,`rotation` по костям, показанное вложение и мировой bbox по слотам — без `animation` rest-поза, иначе поза в `t` со всеми применёнными ограничениями), `rig_set_goal` (кость в точку документа; под живым IK правка уходит на кость-цель ограничения, под transform/path — отказ), `rig_copy_tracks` (треки одних костей на другие пара за парой, сдвиг фазы, зеркало по x — знак меняют `x`, `rotation`, `shearX`, `shearY`, и лево-правым оно будет только при зеркальных системах родителей) |
+| Анимация | `rig_apply_preset` (встроенные и шаблоны), `rig_set_keys` (`merge`), `rig_set_tracks`, `rig_adjust_track` (amplitude / offset / timeScale), `rig_remove_animation` |
+| Шаблоны | `rig_save_as_preset` (анимация → шаблон в `presets.json`), `rig_list_presets` |
+| Вывод | `rig_render_preview` (`onionSkin`, `region` для crop/zoom, сводка `rig_check` по анимации), `rig_export` (атлас) |
+
+На риге с ключами `drawOrder` слот теперь можно добавить и удалить, не сломав валидацию: `rig_set_slot` дописывает новый
+слот в конец каждого ключа, `rig_remove_slot` вычёркивает из них старый. `rig_mesh_from_image` трассирует и framed-ассеты
+(кадр вырезается из листа в памяти); отказ остаётся только для `rotate`/`trim` экспортных атласов.
+
+Каждая мутация отвечает списком «changed:» (структурные операции — ещё и сводкой рига); невалидный результат не
+сохраняется, предыдущая версия уходит в историю. `rig_get verbose=true` показывает pivot/offset слотов и треки с диапазонами ключей.
+
+Те же инструменты из shell (для скриптов и для агентов без MCP-конфига):
+```bash
+npm run rig -- list                                          # все инструменты с параметрами
+npm run rig -- rig_check '{"path":"examples/hero/rig.json"}'
+npm run rig -- rig_render_preview '{"path":"…","animation":"idle","scale":0.4,"saveTo":"out/idle.png"}'
+```
+
+`npm run verify:mcp` проходит маршрут через настоящий stdio MCP: три задания README, deform-ключи с заведомым
+переворотом меша (`rig_check` обязан его найти), diff/undo, onion skin, символ с экспортом в атлас, шаблон из ручной
+анимации, `merge`/`verbose`/`region`. Журнал и превью — в `examples/hero/out/mcp/`.
+
+Слепая оценка двух агентов на риге cashier (задания из `anim.md` и поиск внесённых дефектов) — [отчёт](docs/agent-eval-2026-09-07.md).
+
+### Деформация картинки (mesh)
+
+Слот, у которого есть `deform`-трек, рендерится как `MeshPlane` 9×9 поверх 3×3 контрольных точек.
+Параметры безразмерные (доли размера картинки), все складываются:
+
+| prop | что делает | закреплено |
+|---|---|---|
+| `bulge` | средний ряд расходится по горизонтали (дыхание, пульс) | верх и низ |
+| `bend` | средний ряд сдвигается вбок (мягкий наклон, C-изгиб) | верх и низ |
+| `sway` | сдвиг ряда пропорционально расстоянию от pivot (волосы, наклон от опоры) | ряд pivot |
+| `squash` | сжатие к pivot по вертикали с расширением по горизонтали, не задевая детей | pivot |
+| `p<r><c>x`, `p<r><c>y` | прямое смещение точки в пикселях, ряды/колонки 0..2 сверху-слева | — |
+
+`|bend|,|sway| ≤ 1`, `|bulge|,|squash| ≤ 0.9`. Переворот треугольников (в том числе из-за overshoot easing между ключами)
+ловит `rig_check` как `deform_flip`. Обоснование и сравнение вариантов — в спеке этапа 2.
+
+### Свечение и VFX-слои
+
+`slot.blend`: `normal | add | multiply | screen` (в `layers.json` — поле `blend`). Слой свечения рисуется на чёрном и кладётся
+с `add`: чёрное исчезает, никаких «наклеек» с краями кожи; alpha-трек управляет силой свечения. Так делаются светящиеся глаза и
+подсветка пламени у символов. Превью рендерится на непрозрачном фоне внутри WebGL (как в игре), иначе аддитивный слой
+над пустотой давал бы чёрные прямоугольники; призрак onion skin кладётся сверху.
+
+### Шаблоны из ручных анимаций
+
+`rig_save_as_preset(animation, name, groups?)` сохраняет анимацию как шаблон: треки костей относительно rest и по `role`,
+масштаб как отношение, deform как есть. Параметры шаблона: `amplitude` (все относительные значения), `speed` (время) и
+именованные группы треков (`{"turn": ["bone.root.rotation"]}`) — каждая становится своим множителем. Применение на другом
+риге: `rig_apply_preset(preset: "<имя>", params)` — кости ищутся по роли, затем по id; чего нет в целевом риге, пропускается.
+Библиотека — `presets.json` рядом с рига или любой путь в `library`.
+
+### Состояния в игре
+
+```ts
+const player = new RigPlayer(doc, await createTextures(doc, src => loadTexture(base + src)), { mix: 0.15 });
+player.state.setBase("idle");                       // цикл
+player.state.setOverlay("eyes", "blink");           // независимый цикл поверх
+await player.state.play("win", { priority: 1 });    // прерывает idle, после завершения — обратно; промис всегда резолвится
+player.state.setBase("dim");                        // незацикленный base держит последнюю позу
+```
+`RigSymbol` (`src/rig-symbol.ts`) заворачивает это в `playIdle / playWin / showStatic / resize / setDim` — интерфейс
+`SymbolView` из `@energy8platform/game-engine` (≥ 0.43: `resize` принимает и `number`, и `{width, height}`), без
+зависимости от движка.
+
+### В игре
+
+Пакет публикуемый: `npm run build` собирает `dist/lib/` (esbuild по entry, `.d.ts` от tsc) и клиент редактора.
+Exports: `@energy8platform/golem/runtime` (браузер: `RigPlayer`, `RigSymbol`, `createTextures`, `parse`; `pixi.js` —
+peer, в игре должна быть одна копия), `/tools` (реестр инструментов), `/editor` (`startEditorServer`). Bin:
+
+```bash
+golem editor --root public/assets/rigs   # редактор над ригами игры; в шаблоне create-slot — `npm run rigs`
+```
+
+`--root` — папка ригов (список `open`, загрузки, `/rig/*`), сам `editor.html` и `dist/` отдаются из пакета.
+Движок подключает риги через `@energy8platform/game-engine/golem` (`loadRigs`, re-export'ы, compile-time контракт
+`RigSymbol` = `SymbolView`), а `defineGameConfig` вырезает `.rig-history/` из `vite build` — риги лежат прямо в
+`public/`, vite dev перезагружает игру на каждую запись редактора. Спека:
+`docs/superpowers/specs/2026-09-15-engine-integration-design.md`.
+
+### Настоящие данные
+
+```bash
+npm run verify:engine    # RigSymbol внутри SymbolCell из ../kitsune-wrath (KITSUNE_DIR=… для другого пути)
+```
+Символ из одной картинки, как это делает агент:
+```bash
+S=examples/symbol/rig.json
+npm run rig -- rig_create_symbol '{"path":"'$S'","image":"../hero/layers/head.png","name":"gem","margin":0.2}'
+for p in symbol_idle symbol_win dim; do npm run rig -- rig_apply_preset '{"path":"'$S'","preset":"'$p'"}'; done
+npm run rig -- rig_render_preview '{"path":"'$S'","animation":"win","fps":10,"onionSkin":true,"scale":0.5,"saveTo":"examples/symbol/out/win.png"}'
+```
+
+## Шаг 3 — слои (риск №1 закрыт)
+
+Спайк сегментации на `cashier.png` (артефакты удалены при чистке репозитория): вырезание из плоской картинки + bleed 6 px даёт чистый
+rest и микро-движение; большое движение (стакан ко рту) требует скрытых частей — их выгоднее **генерировать сразу по
+частям**. Маршрут для агента: `rig_layer_prompt(id)` → генерация своим инструментом на `#00FF00` → `rig_replace_asset(id, file)`.
+Патчи выражений (веки, рот) — `swap: true` в `layers.json`; несколько состояний одного места (`mouth_open_small`, `mouth_sip`)
+объединяются полем `slot: "mouth"` в один скрытый слот. Анимируются пресетами `blink` / `mouth_talk` и в игре идут как overlay
+(во вьюере — поле `overlays`).
+
+## Посмотреть анимацию живьём / GIF / видео
+
+```bash
+npm run viewer      # → http://localhost:8000/viewer.html
+npm run export -- examples/hero/rig.json idle 24   # mp4 + gif через ffmpeg
+```
+Агенту по-прежнему отдаём контакт-лист (`rig_render_preview`) — видео вижн-модели не читают.
+
+## Редактор
+
+```bash
+npm run editor            # → http://127.0.0.1:8765/editor.html?rig=examples/hero/rig.json
+npm run editor -- --watch # пересборка клиента при правках src/editor
+```
+
+Редактор и агент делят один `rig.json` и одну историю: каждая правка мышью — вызов того же инструмента из `src/rig-api.ts`
+(`rig_update_bone`, `rig_set_keys merge`, `rig_apply_preset`, …), сервер применяет его к актуальному файлу и делает снимок в
+`.rig-history/`. Правки агента через MCP появляются в редакторе сразу (сервер следит за файлом), `rig_undo` / `rig_redo`
+общие. Режимы как в Spine: **Setup** правит rest (drag сустава, поворот за конец кости, масштаб, рамка картинки), **Animate**
+пишет ключи на времени плейхеда (автоключ). Таймлайн — dopesheet: выбор, перенос и удаление ключей, длительность за правый
+край. Панель свойств: поля с ромбами ключей, easing — четырьмя числами и, у выделенного ключа, ещё и перетаскиваемой
+кривой в единичном квадрате (рисуется той же `ease()`, которой считает рантайм, так что картинка не может разойтись с
+воспроизведением; первое перетаскивание ручки переводит именованный ease в `bezier`, `step` рисуется ступенькой),
+слайдеры параметров пресета и amplitude/offset/timeScale трека с предпросмотром до отпускания.
+Спека: `docs/superpowers/specs/2026-09-08-editor-stage-a-design.md`.
+
+### Ручная сборка
+
+Риг собирается мышью с нуля, без CLI: `new` и `open` в верхней панели создают риг и переключаются на существующий.
+- `+ png` грузит картинки в папку рига; у каждой в списке файлов — кнопки `atlas`, `ref`, `whole`.
+- с пустым выделением панель свойств показывает форму документа: имя, холст, notes и поля подложки `reference` (`src`, `opacity`, `x`, `y`, `scale`).
+- режим `atlas` (клавиша `A`): `detect` с ползунками `gap`/`min area` предлагает прямоугольники, `snap` поджимает их по альфе, нажатие на пустом месте рисует новый прямоугольник, 8 ручек меняют размер, `Delete` убирает выделенные, `merge` объединяет несколько в один; имя прямоугольника (Enter) — это `rig_set_asset` с `frame`; предложенные прямоугольники живут только в памяти страницы и не переживают перезагрузку.
+- корзина ассетов — миниатюры; drag на холст или на строку кости кладёт ассет, двойной клик — в центр холста; уже размещённые притушены.
+- инструмент `B`: нажатие ставит сустав кости, перетаскивание — направление и длину; с выделенной частью она сама перепривязывается на новую кость.
+- строка слота, перетащенная на кость, и выбор `bone` в форме слота — оба сохраняют картинку на месте.
+- список **layers**: слои идут передними сверху; перетаскивание в Setup — `rig_set_draw_order`, в Animate — ступенчатый ключ `drawOrder` на плейхеде; поле `z` правится только в Setup.
+- по две ручки масштаба у кости и у картинки, Shift — равномерно (оба масштаба по отношению вдоль тянущейся оси), курсор каждой — по направлению её оси.
+- галочка `lock images`: клик по картинке выбирает её кость.
+- поле `id` у кости, слота, attachment, ассета и ограничения — редактируемое; Enter — это `rig_rename`.
+
+Спека: `docs/superpowers/specs/2026-09-11-editor-stage-e-authoring-design.md`.
+
+Каждый коммит редактора несёт версию документа, с которым он сделан (`mtimeMs:size`); если файл на диске успел
+измениться — правкой агента через MCP, другим процессом, — сервер отвечает 409 и актуальным документом вместо того,
+чтобы выполнить инструмент, а редактор подставляет пришедший документ и предупреждает статусом, не считая это своей
+ошибкой. Без версии в запросе (MCP, CLI, curl) поведение прежнее — агент не затронут. Запись `rig.json` атомарна
+(временный файл рядом, затем rename): раньше `writeFile` мог отдать параллельному читателю усечённый файл.
+
+Внутри одного процесса операции над одним путём рига выполняются последовательно; HTTP-проверка версии входит
+в ту же очередь. **Отдельные процессы MCP, CLI и редактора общей блокировки не имеют**: если они одновременно
+редактируют один файл, правки всё ещё могут потеряться. Пока назначайте одному ригу одного активного писателя.
+Результаты проверки и оставшиеся ограничения — в [аудите от 11 сентября 2026](docs/verification-2026-09-11.md).
+Спека: `docs/superpowers/specs/2026-09-09-editor-stage-d-design.md`.
+
+### Меши
+
+Агент: `rig_mesh_from_image {id, spacing, tolerance}` превращает region-attachment в меш по alpha картинки (контур + сетка +
+Делоне), `rig_auto_weights {id, bones?, radius?, maxInfluences}` раздаёт веса по расстоянию до костей — вершина берёт
+`maxInfluences` ближайших костей с весом `1/(d/radius + 1)²` (`radius` — масштаб спада в мировых пикселях; без параметра
+— `1`, то есть результат побайтово прежний; больше — влияние ровнее и захватывает дальние кости, меньше — жёстче и
+локальнее; жёсткого обрыва нет ни при каком радиусе — именно обрыв давал шов на середине конечности), `rig_set_mesh` /
+`rig_set_weights` пишут массивы целиком, `rig_set_keys` принимает массивы (deform `vertices`, drawOrder, color), `rig_check`
+ловит `mesh_fold` (ошибка, если свёрнуто ≥ 5 % площади меша, иначе предупреждение) и `weights_sum`. `npm run verify:mesh`
+собирает cashier из слоёв этими инструментами с параметрами по умолчанию и кладёт контакт-лист в
+`examples/cashier/out/auto-maxwin.png` рядом с авторским (`maxwin-reference.png`). Фикстуры кассира (`examples/cashier/rig.json`
+и `layers/`) локальные, в репозитории их нет: без них скрипт выходит с кодом 2 и называет недостающий файл
+(`npm run cashier:build` пересобирает их, если исходники на месте). Скрипт держит базовую линию `KNOWN_FOLDS`: на
+полностью сложенном локте в `maxwin` веса по расстоянию складывают меш (`upper_l`, `forearm_l`) — известное ограничение,
+разобрано в разделе 9 спеки, лечится кистью весов, поэтому выход 0; любая НОВАЯ ошибка — код 1, а если известная
+перестала падать, скрипт скажет «improved — update KNOWN_FOLDS».
+
+Редактор: у меша видны вершины и контур; drag вершины в Setup пишет `rig_set_mesh`, в Animate — ключ `deform.<id>.vertices`
+(такой трек кладётся на таймлайн как обычный: двойной клик ставит ключ с формой, которая уже видна в этот момент, ключи
+двигаются и удаляются); `W` — режим весов (только в Setup): тепловая карта выбранной кости, кисть (`[` `]` — радиус,
+Shift — убавить), `auto weights`, `to mesh` у региона.
+
+Спека: `docs/superpowers/specs/2026-09-08-editor-stage-b-meshes-design.md`.
+
+### Пути
+
+Агент: `rig_set_path_attachment {path, id, slot, points?, vertices?, weights?, closed?}` создаёт или заменяет PATH
+attachment — ровно одна из двух форм за вызов (минимум 2 опорные точки, 3 — для замкнутого пути). `points` — опорные
+точки в координатах документа: кривая строится заново по Catmull-Rom, поэтому у скинированного пути это рвёт веса и
+авторские касательные — форма для рисования пути с нуля. `vertices` / `weights` — сырые контрольные точки
+`[cPrev, p, cNext]` на узел (в пространстве кости слота, либо скинированные — список влияний на точку, как у
+`rig_set_weights`) — единственная форма, которая сохраняет веса и касательные, поэтому редактор коммитит правку
+существующего пути только ею. `rig_path_anchor {path, id, op: insert|remove, index, t?}` добавляет и убирает один узел:
+`insert` делит сегмент после `index` в параметре `t` (0..1, по умолчанию 0.5) де Кастельжо — кривая не меняет форму НИ В
+ОДНОЙ позе, потому что положение каждой новой контрольной точки в пространстве кости-влияния — это смесь исходных точек
+в ТОЙ ЖЕ кости с теми же коэффициентами де Кастельжо, а это тождество по матрицам костей; `remove` убирает тройку узла
+(форма меняется — это неизбежно). Обе операции пересчитывают `lengths` и отбрасывают deform-ключи, которым не подошла
+новая длина.
+
+Редактор правит взвешенные пути наравне с мешами — запрет из C снят. Узел тащится вместе с двумя касательными, ручки
+касательных показываются только у выделенного узла (иначе на пятиузловом `tail_path` их стало бы вдвое больше), клик
+рядом с кривой выбирает путь, `Ctrl`-клик вставляет узел в ближайшей точке параметра, `Delete` на узле — удаляет. Коммит
+идёт сырой формой `rig_set_path_attachment`, поэтому взвешенный путь остаётся взвешенным, а нетронутые касательные —
+авторскими: правка — это дельта в пространстве каждой кости-влияния (та же математика, которой `deformOffsetsFor`
+считает deform-ключ в Animate), а не переигрывание всех влияний из одной мировой точки — это схлопывает разброс между
+образами вершины в разных костях, а этот разброс и несёт анимацию (крошечный, 0.01 px, сдвиг узла в Setup у наивного
+пересчёта даёт в позе смещение до 489 px на меше `n_fur` и до 24 px на самом `tail_path`). В Animate путь пишет
+deform-ключи так же, как меш (`tail_path` в `ross` приходит из Spine с 17 такими треками).
+
+Спека: `docs/superpowers/specs/2026-09-09-editor-stage-d-design.md`.
+
+### Ограничения
+
+Агент: `rig_add_ik_chain {bone}` оснащает конечность одной командой — ставит кость-цель (`role: ik_target`, ребёнком
+корня, а не внутри цепи, иначе решатель тянул бы сам себя) в текущий конец цепи и IK `<bone>_ik` со знаком сгиба из
+текущей позы, так что от появления ограничения риг не шелохнётся; если двухкостная цепь дотянулась бы до самого
+корня, берётся одна кость, и инструмент об этом говорит. На свежеимпортированном риге это ДВА шага: кости из
+`rig_import_layers` нулевой длины и сидят в своих суставах, а цель встаёт в конец цепи — поэтому сначала
+
+```
+rig_update_bone {id: "leg_l", length: 60}     # столько, сколько кость реально занимает на картинке
+rig_add_ik_chain {bone: "leg_l"}              # → кость-цель leg_l_ik и IK; дальше позу задаёт она
+```
+
+(без длины одно-костный IK целился бы в собственное начало кости, и инструмент честно отказывается). После импорта
+Spine длины уже есть, и хватает второй строки. `rig_set_ik` / `rig_set_transform` / `rig_set_path` создают
+и правят ограничения (поля сливаются: `{id, mix}` правит только mix), `rig_remove_constraint` удаляет вместе с
+треками, `rig_set_path_attachment` строит и правит кривую пути (`rig_path_anchor` добавляет и убирает узел — раздел
+«Пути» выше). `rig_check` добавляет
+`constraint_dead` (все mix — 0 и ни один ключ их не поднимает), `constraint_cycle` (цель сидит на кости, которую это
+же ограничение пишет), `ik_unreachable` (цель за пределами досягаемости двухкостной цепи — она висит прямой; одинокая
+кость целится, а не тянется, и не считается) и `path_missing` (слот-цель никогда не показывает путь).
+
+Редактор: выделенное ограничение подсвечивает свои кости и ведёт пунктир от конца цепи к цели — к ромбу на
+кости-цели, у path — к ближайшей опорной точке кривой, которая тоже обводится. Кость, которой прямо сейчас управляет
+IK, тащить напрямую нельзя: жест перенаправляется на цель ограничения (`Alt` отключает перенаправление, ручка
+масштаба по-прежнему правит саму кость), а кость под transform или path отклоняется со статусом. «Прямо сейчас» —
+по значениям на плейхеде: ограничение, у которого на этом кадре все mix равны 0, решатель пропускает, и кость
+правится как обычная. Кривая пути рисуется у каждого показанного пути, опорные точки видны и тащатся у выделенного —
+как вершины меша, включая взвешенные, импортированные из Spine (раздел «Пути» выше). Числовые поля ограничения
+(`mix`, `softness`, у path ещё
+`position` и `spacing`) в Animate пишут обычные ключи на времени плейхеда. В дереве: «add ik chain» на кости,
+«add ik / transform / path» на заголовке группы (занятый id отклоняется: `rig_set_*` считает известный id патчем и
+переписал бы чужое ограничение), `Delete` удаляет ограничение вместе с его треками (о них спросит).
+
+Спека: `docs/superpowers/specs/2026-09-08-editor-stage-c-constraints-design.md`.
+
+## Шаг 4 — риг класса Spine: формат v2 и импорт настоящего Spine-проекта (ross)
+
+Инструмент больше не «двигает картинки»: документ v2 — это меши с весами костей, регионы, пути, shear и режимы наследования,
+ограничения IK (1–2 кости, softness/stretch/compress), transform (мировой и локальный, relative) и path (4 режима шага,
+3 режима поворота, замкнутые и открытые пути), треки деформации вершин, порядка отрисовки, цвета слота и миксов ограничений.
+Это своя реализация по документированной семантике Spine, не порт рантайма; spine-core используется только как оракул в тестах.
+
+Проверка на `ross/` (Spine 4.0: 163 кости, 116 слотов, 110 мешей, из них 49 взвешенных, 2 IK, 17 transform, 7 path,
+17 анимаций): в каждой анимации на 9 моментах времени все кости совпадают с spine-core лучше 0.01 px, вершины мешей и путей
+с deform-ключами лучше 0.05 px, attachments, порядок отрисовки и цвета совпадают точно (`tests/spine-import.test.ts`).
+Кадр (163 кости + 110 мешей + все ограничения) считается ~0.9 мс.
+
+```bash
+npm run rig -- rig_import_spine '{"path":"ross/rig.json","json":"ross.json"}'   # атлас и страница находятся сами; .ktx2 → PNG рядом с rig.json
+npm run rig -- rig_render_preview '{"path":"ross/rig.json","animation":"jump","fps":4,"scale":0.25,"saveTo":"ross/out/jump.png"}'
+npm run render:ross              # листы simple / jump / sitting в ross/out/
+npm run render:spine -- devil    # любой другой экспорт Spine: json + атлас из каталога, все анимации
+npm run spine:sweep              # невязки к spine-core по каждой анимации
+npm run ktx2 -- ross/ross.ktx2 ross/ross.png   # транскодер из three (devDependency), нужен только для KTX2
+```
+Импорт делает холст по объединению всех кадров всех анимаций (а не по setup-позе, иначе прыжок вылетает за край),
+выбрасывает треки, целиком равные setup-значению (Spine ключует всё подряд, они ничего не меняют), и переводит y-вверх
+в y-вниз сопряжением отражением. `rig_check` на таких ригах шумит меньше: постоянный трек с не-setup значением — это
+удержание позы (info), рывок ровно на stepped-ключе — авторский (info).
+
+Что пришлось воспроизвести, чтобы совпасть с оракулом: до первого ключа трека действует setup-значение (импортёр вставляет
+явный ключ); безье-кривые Spine — это 10 линейных отрезков (9 внутренних точек), не точная кривая; deform у взвешенных
+вершин — смещение на каждое влияние; у path-ограничения при `constantSpeed` длина меряется по уже деформированной кривой
+(4 хорды на кривую для суммы, 10 внутри), замкнутый путь заворачивает позицию, открытый продолжает касательные за концами;
+transform- и path-ограничения правят мировую матрицу и раскладываются обратно в локальные значения (иначе при неравномерном
+масштабе родителя поворот «уезжает»); двухкостный IK при отрицательном масштабе добавляет 180° и зеркалит сгиб.
+
+Не поддержано или отличается: linked mesh, clipping/bounding box/point attachments (пропускаются с предупреждением), скины
+сливаются в один с префиксом (переключения нет), physics 4.2 и sequence 4.1 нет, смешивание анимаций — наш `AnimationState`
+(кроссфейд поз), а не MixBlend-треки; в локальном режиме transform-ограничения масштаб смешивается линейно (spine-core делит
+на масштаб кости); IK у костей с нестандартным `inherit` приближённый.
+
+## Что дальше по коду
+- Редактор: кисть весов с учётом направления сгиба; режимы шага пути в UI сверх трёх имеющихся; кривая ease сразу для
+  нескольких выделенных ключей и её правка прямо на таймлайне (сейчас — только в панели свойств одного ключа).
+- Ручная сборка — вне объёма этапа (спека E §7): мультивыбор частей, перетаскивание подложки мышью, переименование
+  внутри `presets.json`, ключи `drawOrder` смещениями в духе Spine.
+- Агентский слой поверх v2: агент читает позу числами (`rig_get_pose`) и ставит кость в точку документа
+  (`rig_set_goal`, то же правило разрешения цели, что у драга в редакторе), а перенос треков между костями со
+  сдвигом фазы и зеркалом (`rig_copy_tracks`) делает вторую ногу цикла из первой. Пресетов движения это **не
+  добавляет** — библиотеки походок и параметризованных циклов по-прежнему нет; IK-пресеты (ходьба и прочие
+  циклы; `rig_add_ik_chain` — это оснастка, а не движение), пресеты на мешах и экспорт в Spine остаются впереди.
+- Многопользовательский режим: 409 защищает от затирания правки версией, которую клиент уже не держит, но не сливает
+  две одновременные правки — совместного редактирования пока нет.
+- Два долга версии записи, которых 409 не закрывает (спека D §7): версию успешного ответа `/api/tool/*` сервер берёт
+  `stat`-ом ПОСЛЕ того, как инструмент записал файл, поэтому чужая запись в это субмиллисекундное окно отдаст клиенту
+  версию чужих байт — закрывается, только если инструмент сам вернёт версию тех байт, которые записал он сам; и потеря
+  обновления при двух одновременных `mutate`, которые оба читают файл до того, как первый из них успел записать — 409
+  этого не видит, лечится очередью коммитов на клиенте.

package/bin/golem.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/lib/cli.js";