pagecraft-block-ssr

⚡ Этот скилл — для вызова через тул Skill(pagecraft-block-ssr), не через Read .../SKILL.md. Если ты сюда попал через Read — остановись, вызови Skill(pagecraft-block-ssr). Содержимое то же, но система правильно учтёт делегирование.

PageCraft SSR

Серверные данные для блоков. Когда блок должен показывать данные, приходящие с сервера (не из полей props.*, а из реальных источников — товары, корзина, избранное, отзывы), его схема объявляет bindingSlots, и шаблон обращается к ним через data.*.

Этот скилл — про локальную работу со снимком SSR-реестра: проверка типов, сборка стабов для preview, сравнение зафиксированных привязок блока с актуальным состоянием. Сам реестр забирается из API скиллом pagecraft-api.

Жизненный цикл

1.  sync-meta              ← pagecraft-api (стянуть свежий blocks/_meta/)
2.  get-data-result-types  ← найти подходящий resultType
    get-data-sources       ← найти подходящие источники
3.  Добавить bindingSlots в schema.json блока
4.  build-stubs <block>    ← собрать data-stubs.json + заморозить bindings_snapshot
5.  preview / итерация
6.  check-bindings <block> ← при возврате к блоку — проверить drift

Важно: скрипты этого скилла читают только локальный blocks/_meta/. В API сами не ходят. Перед SSR-работой (или после паузы в несколько дней) — прогнать pagecraft-api/scripts/sync-meta.js.

Скрипты

Скрипт	Что делает
scripts/meta-local.js	Локальные утилиты: readMeta, readMetaOrFail, findResultType, findSource, hashOf, buildBindingsSnapshot, diffBindings. Не вызывается напрямую
scripts/get-data-result-types.js	Список или один resultType. Флаги: --schema / --stub / --resolved
scripts/get-data-sources.js	Список или один source. Флаг --result-type <id> фильтрует
scripts/build-stubs.js	Собрать data-stubs.json для preview + заморозить bindings_snapshot в block.json
scripts/check-bindings.js	Сравнить bindings_snapshot блока с локальным _meta/. Exit 1 при drift'е

Если snapshot отсутствует

readMetaOrFail падает с явной инструкцией:

Локальный snapshot blocks/_meta/ не найден. Сначала запусти:
  node .claude/skills/pagecraft-api/scripts/sync-meta.js

Это сознательный контракт: pagecraft-block-ssr не делает сетевых вызовов. Если данные устарели — пользователь / оркестратор явно их обновляет через pagecraft-api.

bindingSlots — формат

В корне schema.json блока:

{
  "fields": [ ... ],
  "bindingSlots": {
    "products": {
      "resultType": "product_list",
      "allowedSources": ["catalog.products", "catalog.favorits"],
      "default": "catalog.products"
    }
  }
}

В шаблоне:

{% for product in data.products.items %}
  <h3>{{ product.name }}</h3>
{% endfor %}

Все источники одного слота обязаны возвращать одинаковый result_type_id — иначе SSR-рендер развалится при смене источника редактором.

Контекстные источники в allowedSources не перечисляются

У источника есть поле context — окружения, из которых он берёт данные (rubric, brand, product, search). Непустой context означает: источник отдаёт данные той сущности, которую сейчас показывают (rubrics.current — текущую рубрику, catalog.current_products — товары текущего листинга).

Такие источники в allowedSources не кладутся: блок не знает, на документ какого вида его поставят, а редактор предлагает их сам — по совпадению resultType слота и окружений, которые даёт вид документа (GET /api/v1/page-types, поле contexts). Один и тот же блок так работает и на шаблоне рубрики (данные из контекста), и на странице (данные из явного источника) без правок схемы.

Практика: allowedSources заполняется источниками с пустым context; контекстный источник в схеме упоминать не нужно, достаточно правильного resultType слота.

Полный формат с разворачиванием $ref/$stub, чек-лист SSR-блока — references/ssr-block.md.

Что не делает этот скилл

• Не ходит в API. Любое обращение к серверу — через pagecraft-api.
• Не создаёт блоки и не определяет поля — это pagecraft-schema-block.
• Не валидирует структуру schema.json — pagecraft-schema-block (validate-schema.js).
• Не публикует блок — pagecraft-block-publish.

Типичные ошибки

• «Result type X not in _meta» — реестр устарел. Прогнать pagecraft-api/scripts/sync-meta.js, повторить.
• Источники в allowedSources с разными result_type_id — недопустимо. Все источники одного слота должны соответствовать его resultType. Использовать get-data-sources.js --result-type X для проверки.
• bindings_snapshot не записан — build-stubs.js ещё не запускался для этого блока. Запустить.
• drift при check-bindings — кто-то изменил resultType / source upstream. Поправить шаблон под новую схему → пересобрать стабы → коммит.