@rynt/extension-build 0.9.0

package/README.md

@@ -0,0 +1,151 @@
+# @rynt/extension-build
+
+Пресет **Vite** и утилиты упаковки для авторов расширений **Rynt Launcher**: ESM-бандл, host-shim’ы на `vue` и `@rynt/sdk/*`, манифест в `dist/`, архив **`.ryntextension`**.
+
+**Документация:** [https://docs.rynt.space](https://docs.rynt.space)  
+**SDK:** [`@rynt/sdk`](https://www.npmjs.com/package/@rynt/sdk)  
+**Создать проект:** [`@rynt/create-extension`](https://www.npmjs.com/package/@rynt/create-extension)
+
+---
+
+## Установка
+
+```bash
+npm install -D @rynt/extension-build @rynt/sdk vite vue @vitejs/plugin-vue typescript vue-tsc
+```
+
+Рекомендуется начать с шаблона:
+
+```bash
+npm create @rynt/create-extension@latest my-extension
+```
+
+---
+
+## Быстрый старт
+
+### `vite.config.ts`
+
+```ts
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ryntExtensionViteConfig } from '@rynt/extension-build';
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+
+export default ryntExtensionViteConfig({
+  root,
+  manifest: {
+    id: '@acme/my-extension',
+    name: 'My Extension',
+    description: 'Краткое описание',
+    icon: './assets/icon.png',
+    author: 'Your Name',
+    main: 'index.js',
+    engines: { rynt: '>=0.9.0' },
+    extensionApi: '1',
+  },
+});
+```
+
+Отдельный `manifest.json` в корне **не нужен**: после `vite build` лаунчер читает **`dist/manifest.json`**.
+
+### Entry `src/index.ts`
+
+```ts
+import { defineRyntExtension } from '@rynt/sdk/extension';
+
+export default defineRyntExtension((ctx) => {
+  // регистрация страниц, меню, реестров…
+});
+```
+
+### Скрипты в `package.json`
+
+```json
+{
+  "scripts": {
+    "build": "vite build && rynt-extension-pack",
+    "dev": "vite build --watch",
+    "typecheck": "vue-tsc -p tsconfig.json --noEmit"
+  }
+}
+```
+
+| Команда | Результат |
+|---------|-----------|
+| **`pnpm dev`** | watch-сборка + [Extension Dev Bridge](https://docs.rynt.space/extensions/dev-workflow) (hot reload в лаунчере) |
+| **`pnpm build`** | `dist/` + файл **`{id-slug}-{version}.ryntextension`** |
+
+---
+
+## Иконка
+
+В `manifest.icon` укажите **локальный путь** (PNG, JPG, WebP, SVG):
+
+```ts
+icon: './assets/icon.png',
+```
+
+При сборке растровая иконка масштабируется до **512×512** и попадает в `dist/icon.png`. SVG копируется как `dist/icon.svg`. URL и `data:` URI не изменяются.
+
+---
+
+## Host-shim’ы
+
+Расширение **не** тащит свой `vue` и не дублирует SDK: bare-импорты
+
+`vue`, `vue-router`, `@rynt/sdk`, `@rynt/sdk/extension`, …
+
+подменяются на шимы, которые берут модули с **`globalThis.__RYNT_EXTENSION_HOST_MODULES__`** в рантайме лаунчера.
+
+В коде расширения вызывайте привычные API (`usePageRegistry().register`, `defineRyntExtension`, импорт UI из `@rynt/sdk`) — **`extensionId`** для записей в реестр подставляется автоматически из **`manifest.id`** в Vite-конфиге.
+
+Подробнее: [модель реестров](https://docs.rynt.space/extensions/advanced/registry-model).
+
+---
+
+## Dev-режим (Extension Dev Bridge)
+
+1. В лаунчере: **Управление расширениями** → включить dev-hub (`127.0.0.1:39217`).
+2. В каталоге расширения: **`pnpm dev`**.
+3. После каждой пересборки расширение перерегистрируется в лаунчере.
+
+| Переменная | Описание |
+|------------|----------|
+| `RYNT_DEV=1` | явно включить bridge |
+| `RYNT_DEV_BRIDGE=0` | отключить |
+| `RYNT_LAUNCHER_DEV_HUB` | URL hub (по умолчанию `http://127.0.0.1:39217`) |
+
+Dev-версия с тем же `manifest.id` перекрывает установленную с диска.
+
+→ [Dev-режим в документации](https://docs.rynt.space/extensions/dev-workflow)
+
+---
+
+## CLI `rynt-extension-pack`
+
+Упаковывает содержимое **`dist/`** в **`.ryntextension`** (zip):
+
+- читает **`dist/manifest.json`**;
+- имя файла: **`{slug}-{version}.ryntextension`**, slug из `manifest.id`.
+
+Вызывается в скрипте `build` после `vite build`.
+
+---
+
+## TipTap в расширениях
+
+| Импорт | Поведение |
+|--------|-----------|
+| `@tiptap/core` | host-shim (один экземпляр с лаунчером) |
+| `@tiptap/extension-*` | в `dependencies` расширения, собирается в бандл |
+
+---
+
+## См. также
+
+- [Сборка и установка](https://docs.rynt.space/extensions/build-install)
+- [Сборка и упаковка (детали)](https://docs.rynt.space/extensions/build-pipeline)
+- [Манифест](https://docs.rynt.space/extensions/advanced/manifest)
+- [npm-пакеты экосистемы](https://docs.rynt.space/get-started/npm-packages)

package/bin/pack.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Упаковывает содержимое `dist/` в архив `.ryntextension` (включая `index.js`, стили и `manifest.json` из пресета).
+ * Запуск из каталога расширения после `vite build`.
+ */
+import archiver from 'archiver';
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { cwd } from 'node:process';
+
+const root = cwd();
+const distManifestPath = join(root, 'dist', 'manifest.json');
+if (!existsSync(distManifestPath)) {
+  console.error(
+    '[rynt-extension-pack] Нет dist/manifest.json — сначала vite build (манифест задаётся в ryntExtensionViteConfig({ manifest }))',
+  );
+  process.exit(1);
+}
+const manifestPath = distManifestPath;
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+
+function versionFromPackageJsonFile() {
+  const pkgPath = join(root, 'package.json');
+  if (!existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    const v = pkg?.version;
+    if (v == null) return null;
+    const s = String(v).trim();
+    return s.length > 0 ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+function manifestVersion(m) {
+  const v = m?.version;
+  if (typeof v === 'string' && v.trim()) return v.trim();
+  if (typeof v === 'number' && Number.isFinite(v)) return String(v);
+  return null;
+}
+
+const slug = String(manifest.id ?? manifest.name)
+  .replace(/^@/, '')
+  .replace(/[^a-zA-Z0-9._-]+/g, '-');
+const version =
+  manifestVersion(manifest) ?? versionFromPackageJsonFile() ?? '0.0.0';
+if (!manifestVersion(manifest)) {
+  console.warn(
+    '[rynt-extension-pack] В dist/manifest.json нет version — взято из package.json или 0.0.0. Пересоберите расширение (vite build), чтобы manifest был полным.',
+  );
+}
+const outName = `${slug}-${version}.ryntextension`;
+const outPath = join(root, outName);
+
+const distDir = join(root, 'dist');
+if (!statSync(distDir).isDirectory()) {
+  console.error('[rynt-extension-pack] Ожидалась директория dist/ — сначала выполните vite build');
+  process.exit(1);
+}
+
+const output = createWriteStream(outPath);
+const archive = archiver('zip', { zlib: { level: 9 } });
+
+archive.on('error', (err) => {
+  console.error('[rynt-extension-pack]', err);
+  process.exit(1);
+});
+
+output.on('close', () => {
+  console.info(`[rynt-extension-pack] ${outPath} (${archive.pointer()} bytes)`);
+});
+
+archive.pipe(output);
+
+/**
+ * @param {string} absDir
+ * @param {string} [zipPrefix]
+ */
+function addDirectoryRecursive(absDir, zipPrefix = '') {
+  for (const name of readdirSync(absDir)) {
+    const abs = join(absDir, name);
+    const rel = zipPrefix ? `${zipPrefix}/${name}` : name;
+    if (statSync(abs).isDirectory()) {
+      addDirectoryRecursive(abs, rel);
+    } else {
+      archive.append(createReadStream(abs), { name: rel });
+    }
+  }
+}
+
+addDirectoryRecursive(distDir);
+
+await archive.finalize();

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rynt/extension-build",
+  "version": "0.9.0",
+  "description": "Vite preset, host-shims and .ryntextension packer for Rynt Launcher extensions",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "rynt-extension-pack": "./bin/pack.mjs"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.1.11",
+    "@vitejs/plugin-vue": "^5.2.1",
+    "archiver": "^7.0.1",
+    "jimp": "^1.6.0",
+    "jiti": "^2.4.2",
+    "tailwindcss": "^4.1.11",
+    "vite": "^6.0.10",
+    "vue": "^3.5.13"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rynt/sdk": "workspace:^",
+    "@tiptap/core": "^3.20.4",
+    "rollup": "^4.50.1",
+    "typescript": "~5.7.2",
+    "vue-router": "^4.6.4"
+  },
+  "scripts": {
+    "gen-host-shims": "node ./scripts/write-host-shims.mjs",
+    "build": "tsc -p tsconfig.json",
+    "prepare": "pnpm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC"
+}

package/scripts/write-host-shims.mjs

@@ -0,0 +1,68 @@
+/**
+ * Генерирует `shims/*.host-shim.js`: реэкспорт с `globalThis.__RYNT_EXTENSION_HOST_MODULES__`.
+ *
+ * Запуск: `pnpm --filter @rynt/extension-build run gen-host-shims`
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import * as tiptapCore from '@tiptap/core';
+import * as vue from 'vue';
+import * as vueRouter from 'vue-router';
+
+/** @type {readonly string[]} */
+export const RYNT_EXTENSION_HOST_TIPTAP_SPECIFIERS = ['@tiptap/core'];
+
+const root = dirname(fileURLToPath(import.meta.url));
+const shimsDir = join(root, '..', 'shims');
+mkdirSync(shimsDir, { recursive: true });
+
+const banner = `/* eslint-disable -- generated by write-host-shims.mjs */\n`;
+
+const header = `${banner}
+const HOST = '__RYNT_EXTENSION_HOST_MODULES__';
+
+function registry() {
+  const r = globalThis[HOST];
+  if (!r) {
+    throw new Error(
+      '[rynt/extension-build] Missing globalThis.' +
+        HOST +
+        ' — call registerRyntExtensionHostModules() in the launcher before loading extensions.',
+    );
+  }
+  return r;
+}
+`;
+
+/**
+ * @param {string} fileBase
+ * @param {string} slot
+ * @param {Record<string, unknown>} mod
+ */
+function writeNamespaceShim(fileBase, slot, mod) {
+  const keys = Object.keys(mod).filter(
+    (k) => k !== '__esModule' && k !== 'default',
+  );
+  const lines = [
+    header,
+    `const $ = registry()['${slot}'];`,
+    `if (!$) {`,
+    `  throw new Error('[rynt/extension-build] Host did not register module ${slot}');`,
+    `}`,
+    '',
+    ...keys.map((k) => `export const ${k} = $.${k};`),
+    '',
+  ];
+  writeFileSync(join(shimsDir, `${fileBase}.host-shim.js`), lines.join('\n'));
+}
+
+writeNamespaceShim('vue', 'vue', vue);
+writeNamespaceShim('vue-router', 'vue-router', vueRouter);
+writeNamespaceShim('tiptap-core', '@tiptap/core', tiptapCore);
+
+console.info(
+  '[write-host-shims] wrote vue, vue-router, @tiptap/core →',
+  shimsDir,
+);

package/shims/rynt-sdk-extension.host-shim.js

@@ -0,0 +1,135 @@
+/* eslint-disable -- Rynt host bridge for `@rynt/sdk/extension` */
+const HOST = '__RYNT_EXTENSION_HOST_MODULES__';
+
+function registry() {
+  const r = globalThis[HOST];
+  if (!r) {
+    throw new Error(
+      '[rynt/extension-build] Missing globalThis.' +
+        HOST +
+        ' — call registerRyntExtensionHostModules() in the launcher before loading extensions.',
+    );
+  }
+  return r;
+}
+
+const $ = registry()['@rynt/sdk/extension'];
+if (!$) {
+  throw new Error(
+    '[rynt/extension-build] Host did not register @rynt/sdk/extension',
+  );
+}
+
+// ===== Plugin & Extension Definition =====
+export const defineRyntExtension = $.defineRyntExtension;
+export const defineStore = $.defineStore;
+
+// ===== Extension Expose =====
+export const extensionExposeRevision = $.extensionExposeRevision;
+export const getExtensionExpose = $.getExtensionExpose;
+export const useExtensionExpose = $.useExtensionExpose;
+
+// ===== Registry Management =====
+export const defineExtensionRegistry = $.defineExtensionRegistry;
+export const getExtensionRegistry = $.getExtensionRegistry;
+export const applyValidatedRyntContributesToManifest = $.applyValidatedRyntContributesToManifest;
+export const clearExtensionUiRegistries = $.clearExtensionUiRegistries;
+export const clearRegistryBucket = $.clearRegistryBucket;
+export const deleteRegistryItem = $.deleteRegistryItem;
+export const ensureCoreExtensionRegistries = $.ensureCoreExtensionRegistries;
+export const extensionRegistriesRevision = $.extensionRegistriesRevision;
+export const getCurrentExtensionId = $.getCurrentExtensionId;
+export const getRegistry = $.getRegistry;
+export const getRegistryEntryMeta = $.getRegistryEntryMeta;
+export const getRegistryItem = $.getRegistryItem;
+export const hasRegistryItem = $.hasRegistryItem;
+export const HOST_EXTENSION_ID = $.HOST_EXTENSION_ID;
+export const listRegistryEntries = $.listRegistryEntries;
+export const listRegistryKeys = $.listRegistryKeys;
+export const listRegistryValuesSorted = $.listRegistryValuesSorted;
+export const popExtensionScope = $.popExtensionScope;
+export const pushExtensionScope = $.pushExtensionScope;
+export const resetExtensionRegistries = $.resetExtensionRegistries;
+export const setRegistryItem = $.setRegistryItem;
+export const unregisterRegistryEntriesForExtension = $.unregisterRegistryEntriesForExtension;
+export const validateRyntManifestContributes = $.validateRyntManifestContributes;
+export const withExtensionScope = $.withExtensionScope;
+
+// ===== Builtin Registry Composables =====
+export const useExtensionNavRegistry = $.useExtensionNavRegistry;
+export const useExtensionPageRegistry = $.useExtensionPageRegistry;
+export const useExtensionShellRegistry = $.useExtensionShellRegistry;
+export const useExtensionSidebarRegistry = $.useExtensionSidebarRegistry;
+export const useExtensionUserStripRegistry = $.useExtensionUserStripRegistry;
+export const useLoaderRegistry = $.useLoaderRegistry;
+export const useModProviderRegistry = $.useModProviderRegistry;
+export const useThemeRegistry = $.useThemeRegistry;
+
+// ===== Extension Routing =====
+export const extensionRouteSlug = $.extensionRouteSlug;
+export const resolvedNavigationPath = $.resolvedNavigationPath;
+
+// ===== Launcher Entities =====
+export const registerLauncherEntity = $.registerLauncherEntity;
+export const clearLauncherEntityRegistry = $.clearLauncherEntityRegistry;
+export const RYNT_LAUNCHER_ENTITY_KEYS = $.RYNT_LAUNCHER_ENTITY_KEYS;
+
+// ===== Launcher Models =====
+export const useModel = $.useModel;
+export const RYNT_LAUNCHER_MODEL_KEYS = $.RYNT_LAUNCHER_MODEL_KEYS;
+
+// ===== Router Bridge =====
+export const attachExtensionRoutes = $.attachExtensionRoutes;
+export const detachExtensionRoutes = $.detachExtensionRoutes;
+export const syncExtensionRoutes = $.syncExtensionRoutes;
+
+// ===== Minecraft Loader =====
+export const BaseLoader = $.BaseLoader;
+export const loaderRegistry = $.loaderRegistry;
+
+// ===== Manifest & Extensions =====
+export const parseRyntManifestJson = $.parseRyntManifestJson;
+export const topoSortExtensions = $.topoSortExtensions;
+export const EXTENSION_API_VERSION = $.EXTENSION_API_VERSION;
+export const parseExtensionApiMajor = $.parseExtensionApiMajor;
+export const normalizeExtensionApiInManifest = $.normalizeExtensionApiInManifest;
+export const checkExtensionApi = $.checkExtensionApi;
+export const RYNT_EXTENSION_DISABLED_DIR_SUFFIX = $.RYNT_EXTENSION_DISABLED_DIR_SUFFIX;
+export const isRyntExtensionBundleDirDisabled = $.isRyntExtensionBundleDirDisabled;
+export const ryntExtensionBundleDirBaseLabel = $.ryntExtensionBundleDirBaseLabel;
+export const ryntExtensionBundleDisabledFolderName = $.ryntExtensionBundleDisabledFolderName;
+
+// ===== Mod Marketplace =====
+export const markModMarketplaceProvider = $.markModMarketplaceProvider;
+export const registerModMarketplaceProvider = $.registerModMarketplaceProvider;
+
+// ===== Entity Components =====
+export const EntityBuildCard = $.EntityBuildCard;
+export const EntityModItem = $.EntityModItem;
+export const EntityModListItem = $.EntityModListItem;
+export const EntityModManageItem = $.EntityModManageItem;
+export const EntityAccountAvatar = $.EntityAccountAvatar;
+export const EntityAccountCard = $.EntityAccountCard;
+export const EntityAccountItem = $.EntityAccountItem;
+export const EntityAccountItemMin = $.EntityAccountItemMin;
+export const EntityAccountListItem = $.EntityAccountListItem;
+export const EntityAuthProviderItem = $.EntityAuthProviderItem;
+export const EntityBuildListItem = $.EntityBuildListItem;
+export const EntityEventCard = $.EntityEventCard;
+export const EntityEventListItem = $.EntityEventListItem;
+export const EntityPostCard = $.EntityPostCard;
+export const EntityPostCardMin = $.EntityPostCardMin;
+export const EntityResourcepackItem = $.EntityResourcepackItem;
+export const EntityResourcepackListItem = $.EntityResourcepackListItem;
+export const EntityResourcepackManageItem = $.EntityResourcepackManageItem;
+export const EntityServerCard = $.EntityServerCard;
+export const EntityServerMemberItem = $.EntityServerMemberItem;
+export const EntityServerMemberManageItem = $.EntityServerMemberManageItem;
+export const EntityUserAvatar = $.EntityUserAvatar;
+export const EntityUserCurrent = $.EntityUserCurrent;
+export const EntityUserItem = $.EntityUserItem;
+export const EntityUserItemMin = $.EntityUserItemMin;
+export const EntityUserListItem = $.EntityUserListItem;
+export const EntityUserStatusDisplay = $.EntityUserStatusDisplay;
+export const EntityVersionListItem = $.EntityVersionListItem;
+export const EntityVersionListItemMin = $.EntityVersionListItemMin;

package/shims/rynt-sdk-host.host-shim.js

@@ -0,0 +1,33 @@
+/* eslint-disable -- Rynt host bridge for `@rynt/sdk/host` */
+const HOST = '__RYNT_EXTENSION_HOST_MODULES__';
+
+function registry() {
+  const r = globalThis[HOST];
+  if (!r) {
+    throw new Error(
+      '[rynt/extension-build] Missing globalThis.' +
+        HOST +
+        ' — call registerRyntExtensionHostModules() in the launcher before loading extensions.',
+    );
+  }
+  return r;
+}
+
+const $ = registry()['@rynt/sdk/host'];
+if (!$) {
+  throw new Error(
+    '[rynt/extension-build] Host did not register @rynt/sdk/host',
+  );
+}
+
+// ===== Extensions Initialization =====
+export const initializeRyntExtensions = $.initializeRyntExtensions;
+export const useRyntExtensionLoader = $.useRyntExtensionLoader;
+
+// ===== Launcher Model Registration =====
+export const registerModel = $.registerModel;
+export const clearLauncherModelRegistry = $.clearLauncherModelRegistry;
+
+// ===== Launcher Entity Registration =====
+export const registerLauncherEntity = $.registerLauncherEntity;
+export const clearLauncherEntityRegistry = $.clearLauncherEntityRegistry;

package/shims/rynt-sdk-models.host-shim.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Рантайм-модуль — `rynt-sdk-models.host-shim.js` (мост через `globalThis`).
+ * Объявления нужны редактору/vue-tsc: при alias Vite типы брались бы только из JS без `.d.ts`.
+ */
+import type {
+  LauncherModelApis,
+  RyntLauncherModelKey,
+} from '@rynt/sdk/extension';
+
+export declare function useModel<K extends RyntLauncherModelKey>(
+  key: K,
+): LauncherModelApis[K];

package/shims/rynt-sdk-registries.host-shim.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Рантайм-модуль — `rynt-sdk-registries.host-shim.js` (мост через `globalThis`).
+ */
+export * from '@rynt/sdk/extension/registries';

package/shims/rynt-sdk-session.host-shim.d.ts

@@ -0,0 +1,2 @@
+/** Рантайм-модуль — `rynt-sdk-session.host-shim.js` (мост через `globalThis`). */
+export declare function getSessionToken(): string | null;

package/shims/rynt-sdk-session.host-shim.js

@@ -0,0 +1,24 @@
+/* eslint-disable -- Rynt host bridge for `@rynt/sdk/session` */
+const HOST = '__RYNT_EXTENSION_HOST_MODULES__';
+
+function registry() {
+  const r = globalThis[HOST];
+  if (!r) {
+    throw new Error(
+      '[rynt/extension-build] Missing globalThis.' +
+        HOST +
+        ' — call registerRyntExtensionHostModules() in the launcher before loading extensions.',
+    );
+  }
+  return r;
+}
+
+const $ = registry()['@rynt/sdk/session'];
+if (!$) {
+  throw new Error(
+    '[rynt/extension-build] Host did not register @rynt/sdk/session',
+  );
+}
+
+// ===== Session Token =====
+export const getSessionToken = $.getSessionToken;