Карта стандартов

Карта стандартов показывает все стандарты Framework, их версии и то, на что каждый опирается. По карте видно, какие требования действуют для вашего компонента: каждый следующий уровень добавляет требования и не отменяет предыдущие.

Уровни стандартов

Читайте таблицу снизу вверх по уровням: уровень 1 задаёт форму, уровень 5 — самые конкретные требования.

Переиздания без новых требований. Стандарт закрепляет то, на что опирается, по версии и хешу (см. Закрепление по хешу), поэтому новое издание опоры переиздаёт всю цепочку над ней. Recipe 1.1.0 принимает имена форматов без версии (см. Recipe (simai.composition-recipe)). Составной компонент закрепил новый lock-файл Recipe и вышел изданием 1.0.3. Динамический составной компонент (1.0.3) и порт хоста (1.0.4) переизданы, потому что каждый наследует (extends) предыдущий по хешу. Пакет компонентов (1.1.1) переиздан, потому что ссылается (references) на эти издания по хешу. Требования ни в одном из них не изменились. Фрагмент интерфейса 1.0.2 закрепляет схему описания фрагмента 1.2.0, которая принимает тип значения по имени без версии, и требование closed-value-types называет типы без версии; остальные требования те же (см. Фрагмент интерфейса). Прежние издания хранятся в истории исходников Framework (contracts/standards/history/).

Форматы данных и их старшие версии. Старшая версия формата равна старшей версии стандарта, который его определяет (см. Имена и версии).

Где записана версия, зависит от формата. Квитанция пакета записывает имя в поле schema_id, а версию — в schema_version. Форматы композиции (Recipe, документ, входы, перечень зависимостей), журнал изменений и framework.lock.json пакета, описание фрагмента и манифест эффекта несут старшую версию в самой метке schema ("simai.framework.product-package-source-lock.v1") и отдельного поля schema_version не имеют. Такую метку пишут точно, как в примерах (см. Имена и версии).

Порты хоста и их текущие версии. Все изданные версии лежат в поставке ui в distr/core/contracts/ports/<порт>/<версия>/ (см. Объявление порта); текущая — последняя изданная:

Компоненты этих портов поставляет пакет larena (см. Пакеты компонентов продуктов); порты и наборы проверок входят в поставку Framework.

Машиночитаемые копии на сайте документации:

Копии берутся из закреплённого выпуска при каждой сборке сайта: схема манифеста — действующее издание 2.5.0, порты — все версии, которые поставляет выпуск.

Версии стандартов, форматов и портов руководство называет только в этих таблицах; остальной текст называет их по имени.

Действующие версии — в исходниках Framework (contracts/standards/); сайт документации публикует конверты в /ai/standards/ (Машиночитаемые источники).

Профили продуктов в карту не входят. Роли полей, типы представлений, устройство запроса к хранилищу — вопросы конкретного продукта. Такие профили описываются поверх стандартов в документации продукта; Framework о продуктах не знает.

Recipe (simai.composition-recipe)

Стандарт Recipe — правила сборки страницы: как из шаблонов, фрагментов, мест вставки, выбора вариантов и объявленных входов получить проверенный документ композиции (Document). На этих правилах держатся и сервер, и браузер: одна и та же запись даёт одну и ту же страницу.

Грамматику самого дерева — какие бывают узлы, как они вкладываются, какие у узла слоты и в каком порядке они отрисовываются — задают схема Document (simai.composition.document) и манифест типа. Recipe описывает, как это дерево собирается.

Recipe издаётся нормативным комплектом, а не одним файлом:

• схемы Recipe, входных данных и зависимостей;
• ограничения (limits.json);
• проверенные примеры;
• lock-файл, хеш которого покрывает каждый нормативный файл комплекта.

Изменение любого файла комплекта сразу видно по хешу.

Издание 1.1.0 принимает имена форматов без версии: схемы Recipe, манифеста шаблона, входов и перечня зависимостей принимают и прежнюю метку simai.composition.<имя>.v1, и имя simai.composition.<имя> с "schema_version": 1, а профиль канонизации называется simai.recipe.canonical-json.v1 или simai.recipe.canonical-json. Рецепт в прежней форме даёт те же байты Document и те же digest, что и в издании 1.0.1; рецепт без версии в имени даёт Document и перечень зависимостей без версии в имени. Подробно — в Где взять спецификацию.

Комплект лежит в исходниках Framework (src/core/contracts/composition-recipe-v1/), в поставке ui (distr/core/contracts/composition-recipe-v1/) и на сайте документации; ИИ находит его в индексе по идентификатору urn:simai:framework:composition-recipe:specification.

Требования к слотам, порядку и глубине вложенности составных компонентов (Составной компонент (simai.composite-component)) сформулированы в терминах грамматики композиции. Подробно Recipe и Document описаны в Три представления страницы: Recipe, Document и HTML, Шаблоны, вставки и варианты и Где взять спецификацию.

Манифест Smart-компонента (simai.smart-component-manifest)

Манифест Smart-компонента — контракт одного компонента. Он описывает: входные свойства со схемой, методы, события, состояния, доступность, владение данными, безопасность, готовность, происхождение вплоть до хешей файлов исходника и указания для ИИ.

Схема манифеста закрытая: поле, которого в ней нет, не принимается. Поэтому манифест пригоден для машинного чтения и для проверки в гейте владельца. Версию схемы называет поле x-simai-version, действующая версия — в карте стандартов (см. Уровни стандартов). Схема лежит в исходниках Framework (contracts/schema/smart-component-manifest.v2.schema.json); машиночитаемая копия на сайте — в таблице выше. Все Smart-компоненты Framework описаны манифестом версии 2. Манифест — опора составного компонента и место, где компонент объявляет свой порт хоста.

Манифест обязательно содержит разделы schema_version, id, version, title, summary, kind, reuse_mode, lifecycle, tags, capabilities, custom_element, composition, inputs, methods, events, state, persistence, ownership, security, accessibility, presentation, adapter, artifacts, readiness, compatibility, provenance и ai_guidance; форму каждого задаёт схема.

• id Smart-компонента начинается с smart.: у компонентов Framework это smart. и имя папки (smart.buttons в distr/smart/buttons/).
• custom_element — тег с дефисом (sf-button).
• readiness.level — один из уровней inventoried, described, runnable, composable, exportable, accepted, host-required и список проверок required_checks.

Устройство манифеста описано в Манифест.

Составной компонент (simai.composite-component)

Стандарт составного компонента задаёт внешнюю сторону компонента, собранного из других компонентов: таблицы с панелью и меню, административного меню, редактора страницы. Он покрывает состав, слоты, вид, серверную разметку и подхват, поведение без скриптов и доступность. Работу с данными приложения задаёт следующий стандарт (Динамический составной компонент (simai.dynamic-composite-component)).

Требования:

Опоры стандарта: Recipe (simai.composition-recipe) и схема манифеста Smart-компонента (simai.smart-component-manifest) — замороженная копия той версии схемы, на которой стандарт издан; обе закреплены по версии и хешу.

Стандарт рамочный: имена событий, классы и ширины колонок — документация конкретного компонента. Требования проверяются вручную: автор компонента показывает, чем выполнено каждое; соответствие доказывают конкретные компоненты, а не стандарт. Уровень «следует» означает, что отступление объясняют в документации компонента.

Динамический составной компонент (simai.dynamic-composite-component)

Стандарт динамического составного компонента задаёт границу между составным компонентом и приложением, когда компонент показывает записи, сохраняет настройки и просит выполнить действия. Он наследует стандарт составного компонента целиком и отвечает на вопросы: кто чем владеет, как компонент просит, как приложение отвечает, что происходит при конфликте.

Роли полей, типы представлений и модель запроса — профиль продукта поверх этого стандарта, а не он сам. Проверка ручная: автор компонента показывает, чем выполнено каждое требование.

Как это выглядит в компоненте — см. Связь с приложением: порты хоста и намерения.

Порт хоста (simai.composite-host-port)

Стандарт порта хоста делает сам стык между динамическим компонентом и приложением предметом договора. Стык объявлен, версионирован и проверяется набором проверок, поэтому изменение компонента не обнаруживается приложением только по поломке.

Стандарт наследует динамический составной компонент целиком. Проверка автоматическая у владельца: гейт сверяет объявление порта со схемой, байты порта — с закреплёнными в манифесте, намерения — с событиями, отпечаток набора — с самим набором, а эталонный хост проходит весь набор.

Порты и наборы проверок описаны в Порты и наборы проверок.

Фрагмент интерфейса (simai.interface-fragment)

Стандарт фрагмента интерфейса описывает страницу, собранную из составных компонентов, которые обновляют друг друга через объявленные контракты, и оболочку, у которой область содержимого меняется без полной загрузки страницы. Фрагмент — составной компонент с одним портом хоста, поставленный в именованную область страницы. Стандарт наследует порт хоста целиком; доступ к данным, права и ответы областей остаются за продуктом, а описание фрагмента, типы значений, маршруты и навигация по областям — за Framework.

Проверка ручная: автор фрагмента показывает, чем выполнено каждое требование. Форму описания и значения проверяет Framework (SF.Composition.checkFragmentDescriptor по закреплённой схеме описания 1.2.0 и проверки типов значений). Маршруты между фрагментами задаёт комплект Composition Routing 1.1.0: он сравнивает типы по имени без версии и записывает обе формы имён в контрольном примере fixtures/value-type-names.json.

Как устроены описание и страница из фрагментов — см. Фрагменты интерфейса; типы значений — Типы значений маршрутов; навигация по областям — Навигация по областям страницы.

Правила взаимодействия (simai.interaction-rules)

Стандарт правил взаимодействия задаёт, как любой Smart-компонент — простой или составной — загружается, говорит с другими компонентами и рисует: одно действие — одна отрисовка, пять состояний со скелетоном для загрузки и sf-empty-state для остальных, ожидание вместо «недоступно», свойства вниз и события вверх, маршруты между соседями, настройки вида через SF.Preferences, лёгкая разметка для повторов, ресурсы вместе и один раз, устойчивая геометрия, уменьшение движения, изоляция сбоев, работа без кадров анимации и проверка каждого правила в сборке. Стандарт сквозной: он относится ко всем компонентам и составным компонентам и не наследует другие стандарты. Восемнадцать требований с пояснениями — на странице Правила взаимодействия компонентов.

Разработка с ИИ (simai.ai-development)

Стандарт разработки с ИИ задаёт, как агент работает над Framework и с ним: сначала читает машинные контракты, пользуется только публичной поверхностью, не правит сгенерированное, закрепляет точные выпуски, обновляется по журналу изменений, называет форматы без версий, подключает порты по их наборам проверок, проверяет видимое в браузере и сдаёт работу доказательствами. Стандарт сквозной и не наследует другие. Шестнадцать требований с пояснениями — на странице Разработка с ИИ.

Фоновый эффект (simai.effect)

Стандарт фонового эффекта задаёт анимированный фон в одной области страницы: манифест effect.json с типизированными настройками в границах, один модуль с mount, update, pause, resume и destroy, неподвижный кадр при уменьшении движения, покой в скрытой вкладке, отсутствие сетевых запросов, чистое уничтожение, чужие эффекты в изолированном фрейме и набор проверок перед показом в списке. Издание 1.1.0 содержит двадцать требований и использует (uses) схему манифеста эффекта 1.2.0; на правила взаимодействия оно опирается в части движения и сбоев. Требования о теме и окнах:

Как написать, подключить и проверить эффект и все требования — на странице Фоновые эффекты.

Жизненный цикл изменений (simai.change-lifecycle)

Стандарт жизненного цикла изменений задаёт, как публичное имя уходит из Framework, не ломая проекты. Он сквозной: применяется не к виду компонента, а ко всем публичным именам Framework — компонентам, утилитам, токенам.

Сроки записаны в политике contracts/lifecycle-policy.json, изменения — в журнале contracts/changes/journal.json.

Как этим пользоваться в проекте — два этапа, календарь удалений, продление, журнал и инструмент sf-upgrade — описано в Жизненный цикл изменений и совместимость и Как обновить проект; у Smart-компонентов — в Ошибки и диагностика.

Пакет компонентов (simai.component-package)

Стандарт пакета компонентов задаёт, как владелец продукта или сторонний автор расширяет Framework набором своих Smart-компонентов, в том числе составных. Он покрывает устройство папки пакета, закрепление ревизии Framework, правило и манифест каждого компонента, имена, воспроизводимую сборку с квитанцией, поставку, объявление на странице, лицензию и доверие к коду пакета. Владелец стандарта — Framework; стандарт лежит в исходниках Framework (contracts/standards/simai.component-package/<версия>/).

Связи с другими стандартами (см. Связи между стандартами):

• uses — манифест Smart-компонента (simai.smart-component-manifest), замороженная копия схемы 2.5.0 — той же, что действует для компонентов Framework;
• references — simai.composite-component, simai.dynamic-composite-component, simai.composite-host-port и simai.change-lifecycle, каждый по версии и хешу. Их требования действуют для компонентов пакета так, как изданы, и в этом стандарте не повторяются.

Стандарт не наследует ни одного требования (extends у него нет): он относится к отдельному виду — пакету компонентов.

Издания. Действующее издание — 1.1.1. С издания 1.1.0 стандарт закрепляет схему манифеста 2.5.0, поэтому манифест компонента пакета объявляет те же поля, что и компоненты Framework, в том числе presentation.skeleton и персональный вид. Издание 1.1.1 только обновляет хеши изданий, на которые стандарт ссылается (см. Переиздания без новых требований). Требования во всех изданиях те же, что в 1.0.0. Издание 1.0.0 закрепляло схему 2.2.0, хотя компоненты Framework, а значит и пакет, построенный на них, уже объявляли поля до 2.5.0. Издания 1.0.0 и 1.1.0 остались в истории: их байты хранятся в исходниках Framework (contracts/standards/history/simai.component-package/<версия>/), а сайт документации публикует только действующее издание.

Требование framework-lock-form проверяется машинно (equals), остальные показывает автор пакета (manual).

О требовании own-element-prefix: новые элементы пакета получают префикс владельца (shop-catalog), поэтому будущий элемент Framework не займёт их имя. Loader это поддерживает: он загружает любой тег, который перечислен в правиле пакета, а тег без префикса sf- может занять только правило пакета (см. Пакеты компонентов). Компонент, перенесённый из Framework в пакет, сохраняет имя с sf-, пока его не переименуют через жизненный цикл изменений. В манифесте компонента пакета custom_element называет тег с префиксом владельца, а id начинается с smart. (см. Разделы манифеста).

О требовании tests-travel-with-package: тесты лежат в tests/ папки пакета и запускаются в дереве, где исходники Framework закреплённой ревизии соединены с src/, tests/ и docs/ пакета, — том же, из которого собирается пакет (см. Пакеты компонентов продуктов). sf-build их не запускает: пакет запускает их сам стандартным исполнителем Node — node --test с файлами tests/*.test.mjs в этом дереве. Так делает пакет larena: его scripts/test.mjs раскладывает дерево и запускает в нём свои тесты и общие проверки Framework.

Как устроен, собирается и подключается пакет — см. Пакеты компонентов продуктов, Сборка пакета: sf-build и Пакеты компонентов.

Имена и версии

Имя стандарта, формата данных или порта не содержит версии. Версия меняется с каждым изданием, имя остаётся прежним, поэтому тексты, документы и ссылки, которые называют имя, при выпуске не правятся.

Правила:

• Стандарт — id без версии и version отдельно, полная версия <старшая>.<младшая>.<исправление> (см. Конверт). Пример: simai.composite-host-port.
• Формат данных — имя в поле schema (simai.<имя>) без версии и старшая версия отдельно, в поле schema_version, целым числом. Совместимое добавление её не меняет, поэтому сохранённые файлы ради него не переписываются.
• Старшая версия формата равна старшей версии стандарта, который его определяет. Стандарт simai.composition-recipe определяет simai.composition.document, и старшие версии у них совпадают (см. Уровни стандартов).
• Тексты называют только имя. Версия записана в поле самого файла, в карте стандартов (см. Уровни стандартов) и в записи о выпуске (см. Выпуск и запись о выпуске). Где требование зависит от версии, текст говорит «по версии и хешу» или «новая старшая версия», не называя номер.
• Путь может содержать версию там, где рядом лежат несколько версий: contracts/standards/<id>/<version>/, distr/core/contracts/ports/<порт>/<версия>/, закреплённые копии в pinned/. В тексте такой путь записывается с подстановкой <версия>.

Форматы со старшей версией в самой метке (всего 40 меток) переходят на пару schema и schema_version путём, описанным ниже: запись журнала format-names-without-version (совместимость до 2026-12-01). Каждый читатель Framework, sf-build и читатель файла закрепления Larena принимают обе формы — simai.<имя>.v<n> и simai.<имя> с schema_version рядом, поэтому документ в любой из них читается одинаково.

Писатели Framework выпускают форму без версии: документы композиции ("schema": "simai.composition.document", "schema_version": 1), манифесты типов, портов и редакторов композиции, виды полей, реестры типов, портов и манифестов редакторов, журнал изменений (simai.change-journal) и файлы данных поставки — публичные переменные, уведомления о стороннем коде и другие. Документ, собранный из рецепта, берёт форму рецепта: рецепт с версией в метке даёт simai.composition.document.v1. С версией в метке пишутся реестр контрактов Smart-компонентов, порты хоста и их наборы проверок, закрепления контрактов возможностей и рецептов, lock-файл и примеры комплекта Recipe (рецепт с версией в метке даёт те же digest), а также форматы продуктов и инструментов: описание фрагмента (simai.interface-fragment.v1), манифест эффекта (simai.effect.v1), файл закрепления пакета (simai.framework.product-package-source-lock.v1) и файл настроек sf-build (simai.sf-build.config.v1). Примеры документации записаны в той форме, в которой их пишет Framework.

Типы значений маршрутов называются без версии (record-removed); метка с версией (record-removed.v1) называет тот же тип и читается до 2026-12-01 (запись журнала value-types-without-version). Манифест sf-table, выходы <sf-page-host> и ключи SF.Composition.VALUE_TYPES записаны метками с версией, поэтому их байты и digest не меняются (см. Имя типа).

Обе формы разбирает модуль Framework core/js/composition/schema-name.mjs (в поставке — рядом с модулями композиции): readSchema() сводит simai.<имя>.v<n> и simai.<имя> с schema_version к одному {name, version}, а schemaFields() выдаёт писателю новую форму.

Несовместимое изменение формата проходит жизненный цикл изменений (см. Жизненный цикл изменений и совместимость и Как обновить проект):

1. Совместимость. Читатели принимают обе формы, писатели выпускают новую; журнал изменений получает запись об изменении формата (см. Журнал изменений).
2. Перевод проекта. sf-upgrade переписывает данные проекта в новую форму, при несовместимом изменении — преобразователем (см. Инструмент sf-upgrade).
3. Удаление. Старая форма удаляется на плановой чистке по календарю (см. Календарь).

Новый формат сразу использует пару schema и schema_version.

Смотрите также

• Форма стандарта: Standard Contract — форма, в которой записан каждый стандарт.
• Порты и наборы проверок — порты и наборы проверок.
• Составные компоненты–Манифест — составные компоненты, порты хоста и манифест на практике.
• Пакеты компонентов продуктов и Пакеты компонентов — пакет компонентов на практике.
• Жизненный цикл изменений и совместимость–Как обновить проект — жизненный цикл изменений и обновление проекта; там же — смена формата данных (Имена и версии).
• Recipe, документ и HTML — Composition Recipe и Document.