feat: standalone mode

docs/ru/reference.md

@@ -32,6 +32,9 @@ svg-sprites [options] <config-file-or-directory>
 
 | Среда | Mode |
 |---|---|
+| Static HTML / собственная публикация | `standalone` |
+| Standalone + Vite | `standalone@vite` |
+| Standalone + Webpack 5 | `standalone@webpack` |
 | React + Vite | `react@vite` |
 | React + Webpack 5 | `react@webpack` |
 | Next.js App Router + Turbopack | `next@app/turbopack` |
@@ -45,7 +48,7 @@ Config-файл может иметь любое имя и расширение
 
 Доступны `--mode`, `--name`, `--description`, `--input-folder`, повторяемый `--input-file`, а также пары `--remove-size`/`--no-remove-size`, `--replace-colors`/`--no-replace-colors`, `--add-transition`/`--no-add-transition` и `--generated-notice`/`--no-generated-notice`. Переданные transform-флаги перекрывают отдельные поля, а хотя бы один `--input-file` заменяет весь массив `inputFiles` из config.
 
-Mode должен соответствовать сборщику приложения. Генератор создаёт разный способ подключения SVG asset для Vite и сборщиков, совместимых с Webpack Asset Modules.
+Mode должен соответствовать способу публикации приложения. Bare `standalone` оставляет публичный URL приложению; Vite и Webpack modes генерируют bundler-specific подключение SVG asset.
 
 ## Единая конфигурация
 
@@ -105,7 +108,7 @@ file-manager → FileManagerIcon
 
 ## Generated-модуль
 
-После генерации каталог спрайта выглядит так:
+После генерации React- или Next.js-каталог спрайта выглядит так:
 
 ```text
 app-icons/
@@ -140,6 +143,19 @@ app-icons/
 | `.svg-sprite/*.d.ts` | TypeScript-декларации соответствующих JS-модулей |
 | `.svg-sprite/state.json` | Mode, версия контракта и список управляемых файлов |
 
+Standalone-контракты не создают каталог `react/`. Bare `standalone` содержит только
+runtime asset и deployment-neutral manifest data:
+
+```text
+.svg-sprite/
+├── state.json
+├── sprite.svg
+└── svg-sprite.manifest.json
+```
+
+`standalone@vite` и `standalone@webpack` дополнительно создают `index.*`,
+`icon-data.*` и resolved `svg-sprite.manifest.*`.
+
 Генератор перезаписывает и удаляет только файлы со своим marker. Если в managed-пути находится пользовательский файл, генерация завершается ошибкой. Корневой `index.ts` генератору не принадлежит; при необходимости создайте пользовательский barrel:
 
 ```ts
@@ -235,7 +251,7 @@ editor-icons    → EditorIcon    → иконки редактора
 
 ## Форматы и способы отображения
 
-React- и Next.js-режимы создают формат `stack`.
+Все текущие modes создают формат `stack`.
 
 | Формат | `<svg><use>` | `<img>` | CSS background |
 |---|---:|---:|---:|
@@ -253,6 +269,17 @@ React- и Next.js-режимы создают формат `stack`.
 
 Способ получения `spriteUrl` зависит от сборщика.
 
+Static HTML после публикации `.svg-sprite/sprite.svg` приложением:
+
+```html
+<svg aria-hidden="true">
+  <use href="/assets/icons.svg#search"></use>
+</svg>
+```
+
+Standalone Vite/Webpack предоставляет generated `getIconsIconHref()` и mapping
+внутренних IDs. Не конструируйте fragment из небезопасного имени файла вручную.
+
 Vite:
 
 ```ts
@@ -306,12 +333,15 @@ Mask не сохраняет исходные цвета, gradients и разл
 
 ## Assets и кеширование
 
-Generated-компонент передаёт SVG сборщику как отдельный asset:
+Generated component или standalone facade передаёт SVG сборщику как отдельный asset:
 
 - Vite использует статический импорт с `?no-inline`;
 - Webpack 5, Turbopack и Next.js используют `new URL(..., import.meta.url)`;
 - SVG path-данные не сериализуются в generated JavaScript.
 
+Bare `standalone` не участвует в asset pipeline: приложение само копирует или
+публикует `sprite.svg` и отвечает за URL, версионирование и cache policy.
+
 При стандартном именовании assets сборщик добавляет content hash:
 
 ```text
@@ -401,7 +431,7 @@ fill="var(--icon-color-3, #129d9d)"
 import { SpriteViewer } from '@gromlab/svg-sprites/react'
 ```
 
-Он принимает готовые manifests, массив lazy loaders или record формата `import.meta.glob`.
+Он принимает готовые React/Next manifests, массив lazy loaders или record формата `import.meta.glob`. Текущий Viewer не загружает standalone manifests; для standalone будет отдельный viewer-контракт.
 
 Vite:
 
@@ -488,6 +518,7 @@ CI должен устанавливать development dependencies и выпо
 - `Refusing to overwrite a user file`: в managed-пути находится файл без generated marker.
 - Иконка не меняет цвет: используйте `<svg><use>` или generated-компонент и проверьте `replaceColors`.
 - Webpack выдаёт неверный URL: проверьте Asset Modules, `output.publicPath` и SVG loaders.
+- Static sprite возвращает 404: проверьте post-generation copy или server alias и не передавайте filesystem `spritePath` в HTML.
 - Viewer не видит спрайт: проверьте путь к `.svg-sprite/svg-sprite.manifest.js` и выполните генерацию до запуска приложения.
 - Build и mode не совпадают: используйте target, соответствующий фактическому сборщику.