npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@energy8platform/golem

v0.9.4

Published

AI-first 2D rigging for slot games: rig.json format, PixiJS v8 runtime, MCP tools and a browser editor

Readme

@energy8platform/golem — прототип AI-first риггинга для слотов

Документ (rig.json, формат v2) — источник истины. Агент работает через MCP, человек — через вьюер и редактор в браузере (npm run editor). Рантайм — PixiJS v8.

Поддержан рабочий процесс для персонажей в полный рост: утверждённый арт + скрытые дорисовки, плавное прохождение ключей, длинные IK-цепи, передача реквизита, запекание вторички, clipping, редактирование весов и проверяемые прозрачные кадры/MP4 60 fps. Что изменилось, как использовать и результаты проверок.

В 0.4 добавлен пилот параметрической мимики: независимые глаза, совместные формы «улыбка × открытие рта», ползунки и ключевые формы в редакторе, дорожки параметров и проверка сочетаний через реальный рендер. Устройство и API, воспроизводимый персонаж Milo.

В 0.5 добавлен редактор деталей и костей для встраиваемых превью: правки мышью, группы, отмена и отдельные JSON-поправки. Поправки костей применяются поверх параметрической мимики и сохраняются при смене анимации. Результаты объединения и проверок.

В 0.6 по официальным примерам Spine и Rive обновлены скиллы нарезки и анимации, исправлены импорт skins, linked meshes, кривые, преобразования и активные clipping-маски. Источники, результаты и ограничения проверки.

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-motion.ts       градиент/сглаживание/фиксация весов, attach-to-bone, запекание вторички
src/rig-quality.ts      проходные ключи, скорость петли, вторичка, порядок слоёв, ориентиры сменных рисунков
src/rig-gates.ts        пороги движения, контакты/пропорции, условия FX, реальные переходы AnimationState
src/rig-qa.ts           манифесты кадров с хешами исходных данных и проверкой полноты
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)

Установка

npm install
npx playwright install chromium     # один раз
npm run build:harness               # бандл для headless-рендера (после правок runtime/harness — повторить)
npm run typecheck
npm test

Шаг 1 — smoke без агента

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 в корне проекта):

{ "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-конфига):

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 и поиск внесённых дефектов) — отчёт.

Деформация картинки (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.

Состояния в игре

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:

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.

Правки мышью прямо в превью

Отдельный браузерный модуль @energy8platform/golem/interactive-editor подключается к RigPlayer: выбор по видимым пикселям, перемещение, масштаб по осям и углам, вращение, группы связанных деталей, отмена и JSON с правками. Подключение и ограничения. Полный редактор по-прежнему отвечает за кости, веса, IK и ключи анимации.

Настоящие данные

npm run verify:engine    # RigSymbol внутри SymbolCell из ../kitsune-wrath (KITSUNE_DIR=… для другого пути)

Символ из одной картинки, как это делает агент:

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"}'

Модуль e8-engine

golem — e8-row golem1 (@energy8platform/golem). Что даёт: тулы rig_* в MCP e8, node golem в сцене, вкладка редактора для rig.json в IDE, undo через историю golem. Риги лежат в assets/rigs/<name>/.

Node golem в игре, тулы rig_* и skills приходят со строкой golem1 бандла e8-base (проект без него добавляет ту же строку в e8.patch.yml). Строка в e8.yml добавляет вкладку редактора rig.json в IDE и мост undo:

- id: golem1
  name: '@energy8platform/golem'
  config: {}

Что изменилось после третьего прогона e8 (2026-10-13). rig_batch { path, ops: [{ tool, args }] } применяет несколько правок одним вызовом и одним шагом истории; упавшая или ничего не изменившая пачка rig.json не трогает. Провалы rig_run_gates называют, где: кость или слот, время, отрезок ключей (или ключевого предка). rig_export сам сравнивает упакованный риг с исходником и отвечает максимальной разницей пикселей по анимации — для этого он запускает Chromium: одноразовый скрипт вызывает closeTools() в конце или передаёт check: false. saveTo и framesDir (rig_render_preview, rig_verify_render) считаются от папки рига, недостающие папки создаются. rig_apply_preset отвечает диффом (verbose: true — полное описание рига). Ступенчатый сброс цикла — loop_step, а не мнимый loop_velocity. Проверка: docs/verification-2026-10-13.md.

Шаг 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 / видео

npm run viewer      # → http://localhost:8000/viewer.html
npm run export -- examples/hero/rig.json idle 24   # mp4 + gif через ffmpeg

Агенту по-прежнему отдаём контакт-лист (rig_render_preview) — видео вижн-модели не читают.

Редактор

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/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; длинные цепи через CCD), 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 мс.

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° и зеркалит сгиб.

Не поддержано или отличается при импорте Spine: linked mesh, clipping/bounding box/point attachments (пропускаются с предупреждением; собственные clipping-маски Golem задаются через slot.clip), скины сливаются в один с префиксом (переключения нет), 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 этого не видит, лечится очередью коммитов на клиенте.