@opetope/runtime 0.1.0

package/docs/releases.md

@@ -0,0 +1,78 @@
+# Publishing a release
+
+The five packages share one version: Core, Runtime, React, Devtools and Lint. Before 1.0, use a minor changeset
+for a breaking change and a patch changeset for a compatible fix. Run `npm run changeset`; the version workflow
+opens a release PR. Review its changelogs and exact peer versions before merging.
+
+## Published artifacts
+
+The npm packages ship minified ESM (`minify: true`, `keepNames: false`), TypeScript declarations (`.d.ts`), and
+source maps containing the original sources in `sourcesContent` (D254). Minification targets smaller uncompressed
+JavaScript; tarball size and the consuming application's final bundle must be measured separately.
+
+Reflected `fn.name` and `constructor.name` are not stable API. Explicit declaration IDs, public `error.name` and
+`error.code` values, and `instanceof` checks against exported error classes retain their contract. Source-map-aware
+tools can locate the original TypeScript; the shipped maps expose those sources, so minification does not conceal
+implementation code.
+
+## Acceptance
+
+From a clean checkout of the reviewed commit, using the pinned Node/npm toolchain:
+
+```sh
+npm ci
+npx playwright install --with-deps chromium firefox webkit
+npm run check
+```
+
+CI and release acceptance use the official Playwright image, pinned by version and digest to match the locked
+Playwright dependency. Update the dependency, image tag and digest together. The local commands above install
+browsers and their platform dependencies without requiring that image.
+
+`ci:pack` creates five real tarballs and installs them in isolated consumers. It verifies all export entries,
+NodeNext/Bundler declarations, renderer and headless paths, Lint without runtime packages, maps and shipped links. React/React DOM and their type packages are installed separately at `19.0.0` and at the contributor toolchain versions; both renderer/Devtools consumers also run on Node `20.19.0`.
+Its accepted manifest and archives are in `.cache/release/`. Preserve this exact directory until publication
+finishes. `pack-local` prepares archives for development and does not mark them accepted for release.
+
+The Git commit and archive checksums must match at publication. Do not edit or rebuild the packages after
+acceptance. The publish script rejects an unaccepted manifest, another commit or a dirty checkout.
+
+## First release and authentication
+
+Authenticate interactively with `npm login` using an account allowed to publish in `@opetope`. For the first release,
+publish the accepted set:
+
+```sh
+node tooling/release/publish.mjs --version 0.1.0
+```
+
+The script publishes exact archives with lifecycle scripts disabled. Release candidates use `next`; stable
+versions first use `candidate`. It checks existing versions before writing and resumes a partial publication only
+when the already-published integrity matches. It never overwrites versions or changes `latest`.
+
+After the first package versions exist, configure each package's npm trusted publisher with owner `telchardev`,
+repository `opetope`, workflow `release.yml`, and permission for direct `npm publish`. The workflow uses a
+GitHub-hosted runner and OIDC. No permanent npm write token is needed. This repository is private, so provenance
+is disabled. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+For subsequent releases, dispatch **Release** from the reviewed `main` commit and provide its exact version. The
+workflow repeats acceptance and publishes those same archives. Pushes to `main` prepare release PRs; they do not
+publish arbitrary commits. Enable GitHub Actions' permission to create PRs in the repository settings.
+
+## Registry acceptance and promotion
+
+Install the complete version set from the registry in a clean application with no workspace/source overrides and
+run its build, type, integration and browser checks. Check the lockfile's registry URLs and integrity. Only then
+promote a stable set, using interactive npm authentication:
+
+```sh
+npm dist-tag add @opetope/core@0.1.0 latest
+npm dist-tag add @opetope/runtime@0.1.0 latest
+npm dist-tag add @opetope/react@0.1.0 latest
+npm dist-tag add @opetope/devtools@0.1.0 latest
+npm dist-tag add @opetope/lint@0.1.0 latest
+```
+
+Replace `0.1.0` with the accepted stable version. Verify all five tags before updating applications. Neither
+package publication nor tag promotion is atomic. OIDC authenticates publish operations; tag management requires
+separate account authentication. Keep a record of the accepted commit, archive checksums and registry checks.

package/docs/releases.ru.md

@@ -0,0 +1,78 @@
+# Публикация релиза
+
+Пять пакетов используют общую версию: Core, Runtime, React, Devtools и Lint. До 1.0 для breaking change выбирайте
+minor changeset, для совместимого исправления — patch. `npm run changeset` описывает изменение; workflow версий
+создаёт release PR. Перед merge проверьте changelog и точные версии peers.
+
+## Содержимое пакетов
+
+npm-пакеты поставляют минифицированный ESM (`minify: true`, `keepNames: false`), декларации TypeScript (`.d.ts`) и
+source maps с исходниками в `sourcesContent` (D254). Цель минификации — уменьшить несжатый JavaScript; размер tarball
+и итогового бандла приложения-потребителя измеряются отдельно.
+
+Значения `fn.name` и `constructor.name`, полученные через рефлексию, не являются стабильным API. Явные ID деклараций,
+публичные значения `error.name` и `error.code`, а также проверки `instanceof` с экспортируемыми классами ошибок
+сохраняют контракт. Инструменты с поддержкой source maps могут показать исходный TypeScript; карты поставляют эти
+исходники, поэтому минификация не скрывает реализацию.
+
+## Приёмка
+
+В чистом checkout проверенного commit с закреплёнными Node/npm:
+
+```sh
+npm ci
+npx playwright install --with-deps chromium firefox webkit
+npm run check
+```
+
+CI и release acceptance используют официальный образ Playwright, закреплённый по версии и digest в соответствии
+с версией Playwright в lockfile. Обновляйте зависимость, тег образа и digest вместе. Локальные команды выше
+устанавливают браузеры и нужные системе зависимости без необходимости использовать этот образ.
+
+`ci:pack` создаёт пять настоящих tarballs и устанавливает их в изолированных потребителях. Проверяются все export
+entries, типы NodeNext/Bundler, renderer и headless пути, Lint без runtime-пакетов, maps и ссылки документов. React/React DOM и их типы устанавливаются отдельно в версии `19.0.0` и версиях contributor toolchain; оба renderer/Devtools consumer также исполняются на Node `20.19.0`.
+Принятый manifest и архивы лежат в `.cache/release/`. Сохраните этот каталог до окончания публикации.
+`pack-local` готовит архивы для разработки, но не отмечает их принятыми для релиза.
+
+При публикации должны совпасть Git commit и контрольные суммы. После приёмки не меняйте и не пересобирайте
+пакеты. Скрипт отклоняет непринятый manifest, другой commit и грязное рабочее дерево.
+
+## Первый выпуск и аутентификация
+
+Выполните интерактивный `npm login` под аккаунтом с правом публикации в `@opetope`. Для первого выпуска опубликуйте
+принятый набор:
+
+```sh
+node tooling/release/publish.mjs --version 0.1.0
+```
+
+Скрипт отправляет точные архивы с отключёнными lifecycle scripts. RC используют `next`, stable сначала использует
+`candidate`. До записи скрипт проверяет существующие версии; частичную публикацию можно продолжить только при
+совпадении integrity уже опубликованного содержимого. Версии не перезаписываются, `latest` не меняется.
+
+После появления первых версий настройте для каждого пакета npm trusted publisher: owner `telchardev`, repository
+`opetope`, workflow `release.yml`, разрешение прямого `npm publish`. Workflow использует GitHub-hosted runner и
+OIDC без постоянного npm write token. Репозиторий приватный, поэтому provenance выключен.
+См. [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+Для последующих релизов запустите **Release** вручную из проверенного commit в `main`, указав точную версию.
+Workflow повторяет приёмку и публикует эти же архивы. Push в `main` готовит release PR, но не публикует произвольные
+commits. В настройках репозитория разрешите GitHub Actions создавать PR.
+
+## Приёмка registry и продвижение
+
+Установите весь набор из registry в чистое приложение без workspace/source overrides. Пройдите build, type,
+integration и browser проверки. Проверьте registry URLs и integrity lockfile. Только затем продвигайте stable
+набор с интерактивной npm-аутентификацией:
+
+```sh
+npm dist-tag add @opetope/core@0.1.0 latest
+npm dist-tag add @opetope/runtime@0.1.0 latest
+npm dist-tag add @opetope/react@0.1.0 latest
+npm dist-tag add @opetope/devtools@0.1.0 latest
+npm dist-tag add @opetope/lint@0.1.0 latest
+```
+
+Подставьте принятую stable версию вместо `0.1.0`. До обновления приложения проверьте все пять тегов. Публикация
+пакетов и продвижение тегов не атомарны. OIDC аутентифицирует publish; управление тегами требует отдельной
+аутентификации аккаунта. Сохраните commit, контрольные суммы архивов и результаты проверки registry.