@ryuzaki13/react-foundation-lib 1.4.0 → 1.4.2

package/src/docs/pureUtilities.mdx

@@ -1,96 +0,0 @@
-import { Meta } from "@storybook/addon-docs/blocks";
-
-<Meta title="Foundation Lib/Чистые utilities и contracts" />
-
-# Чистые utilities и contracts
-
-Эти API не создают global state и обычно не требуют React. Они полезны в entity/feature code, если задача остаётся предметно-независимой. Не переносите в них доменные правила только ради повторного использования.
-
-## Коллекции, порядок и ограниченная история
-
-```ts
-import { arrayGroupBy, arrayUniqueBy, moveArrayItem } from "@ryuzaki13/react-foundation-lib/array";
-import { pushBoundedCopyStackItem } from "@ryuzaki13/react-foundation-lib/bounded-copy-stack";
-```
-
-| API                                                                    | Поведение                                                                                                  |
-| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `arrayGroupBy`, `arrayGroupByToArray`, `arrayToMap`                    | Группируют/индексируют по полю объекта. `arrayToMap` оставляет первое значение ключа.                      |
-| `arrayUniqueBy`, `arrayDeduplicate`                                    | Immutable deduplication с сохранением первого встретившегося значения/порядка.                             |
-| `filterAndDeduplicateIds`, `appendMissingIds`, `pickExistingMapValues` | Helpers для stable id lists и ordered Map values.                                                          |
-| `arraysEqual`                                                          | Строго сравнивает длину, порядок и значения по `===`.                                                      |
-| `moveItem`, `moveArrayItem`, `moveArrayItemByIndex`                    | Возвращают новую переставленную коллекцию; invalid indices не мутируют input.                              |
-| `normalizeObjects`, `normalizeStringArray`, `addUnique`                | Explicit canonicalization для внешней/сохранённой структуры — не вызывайте её внутри literal draft setter. |
-
-`pushBoundedCopyStackItem(stack, input, options?)` добавляет/поднимает item по `fingerprint` и ограничивает размер (default `DEFAULT_BOUNDED_COPY_STACK_SIZE = 3`). `getBoundedCopyStackCandidates` фильтрует готовый stack predicate-ом. `BoundedCopyStackItem`, `BoundedCopyStackPushInput`, `BoundedCopyStackOptions` и `BoundedCopyStackPushResult` описывают его serializable contract.
-
-## Значения, шкалы и календарные сегменты
-
-```ts
-import { parseDateSegmentMask, indexedSegmentsToDate } from "@ryuzaki13/react-foundation-lib/date-segments";
-import { snapNumberScaleValue } from "@ryuzaki13/react-foundation-lib/number-scale";
-import { resolveRangeOutputValue } from "@ryuzaki13/react-foundation-lib/range-output";
-```
-
-| Entry point         | Основной API                                                                                                                                                                                                                                                                                                             |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `date-segments`     | `parseDateSegmentMask`, `isEditableDateSegment`, `dateToIndexedSegmentValues`, `areAllDateSegmentsEmpty`, `indexedSegmentsToDate`. `indexedSegmentsToDate` строго отвергает невозможную дату/время; `DateMaskSegment` описывает editable/literal segments.                                                               |
-| `number-scale`      | `resolveNumberScaleBounds`, `clampNumberScaleValue`, `normalizeNumberScaleStep`, `prepareNumberScaleMarks`, `snapNumberScaleValueToStep`, `snapNumberScaleValueToMarks`, `snapNumberScaleValue`, `valueToNumberScalePercent`, `percentToNumberScaleValue`, `percentToSnappedNumberScaleValue`, `offsetNumberScaleValue`. |
-| `currency`          | `resolveCurrencyModeFromODataParameters` и `resolveCurrencyAwareLabel`; это label policy по wrapped OData parameters, не currency formatter.                                                                                                                                                                             |
-| `range-output`      | `readRangeOutputValueFallback` и `resolveRangeOutputValue`; подставляет fallback только для `null` открытой границы и не меняет исходный UI range.                                                                                                                                                                       |
-| `presets`           | `normalizePresetIds`, `resolvePresetOptionsByIds`, `getPresetOption`, `PresetOption`; помогает на save/restore boundary для известного набора IDs.                                                                                                                                                                       |
-| `string-comparison` | `compareStrings(left, right)` использует fixed Russian numeric/case-insensitive collation с deterministic fallback.                                                                                                                                                                                                      |
-
-Для date/number UI formatting используйте `formatters`, а не `number-scale`/`currency`.
-
-## Clone, строки, keyboard и trees
-
-```ts
-import { cn, deepCloneWithoutFunctions, deepCopyWithoutFunctions, stableStringify } from "@ryuzaki13/react-foundation-lib/utils";
-```
-
-| API                                                                                                  | Контракт                                                                                                                                                            |
-| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `cn(...args)`                                                                                        | Собирает className из строк и conditional object. `classNames` — deprecated alias; новый код использует `cn`.                                                       |
-| `stableStringify(value)`                                                                             | JSON-like stable serialization с сортировкой object keys — для key/comparison, не как универсальный persistence format.                                             |
-| `deepCopyWithoutFunctions(value, options?)`                                                          | Копирует Date, arrays и plain objects, поддерживает cycles; функции пропускает. Unsupported object бросает `TypeError`. Предназначен для serializable plain config. |
-| `deepCloneWithoutFunctions(value, options?)`                                                         | Расширенный clone: Date, RegExp, Map, Set, cycles, sparse arrays и optional prototype. Функции пропускает.                                                          |
-| `createLazyComponent`, `childrenCount`                                                               | React-adjacent helpers для stable lazy component и correct children count.                                                                                          |
-| `keyboardActivationKeys`, `isKeyboardActivationKey`, `handleKeyboardActivation`                      | Keyboard activation contract для custom control.                                                                                                                    |
-| `getRovingFocusTargetIndex`, `findFirstEnabledIndex`, `findLastEnabledIndex`, `findNextEnabledIndex` | Pure navigation для listbox/select с disabled/wrap.                                                                                                                 |
-| `deepCopyNodes`, `deepCopyTree`                                                                      | Копирование tree nodes с standard/custom children field.                                                                                                            |
-| `toBase64`, `encodeBase64`, `logError`                                                               | Unicode-safe base64 и centralised error logging.                                                                                                                    |
-
-Clone не является нормализацией: он создаёт независимую структуру в пределах собственного contract и не должен применять trim, defaults, deduplication или reorder к пользовательскому draft. Для plain serializable config используйте `deepCopyWithoutFunctions`, а не `structuredClone`.
-
-## Runtime guards и базовые типы
-
-```ts
-import { asRecord, isRecord, isSafe, readPositiveInteger } from "@ryuzaki13/react-foundation-lib/validators";
-import type { BaseType, RangeType, RowRecord, State } from "@ryuzaki13/react-foundation-lib/types";
-```
-
-| API                                                 | Когда использовать                                                         |
-| --------------------------------------------------- | -------------------------------------------------------------------------- |
-| `isSafe`                                            | Убирает только `null`/`undefined` из union.                                |
-| `isObject`, `isRecord`, `asRecord`, `isPlainObject` | Narrow unknown external value до object/record; array не считается record. |
-| `readPositiveInteger`                               | Возвращает positive integer или `undefined` без unsafe cast.               |
-| `validateUrl`                                       | Возвращает validation result для строки URL.                               |
-| `IMAGE_EXTENSIONS`, `isImageExtension`              | Проверка расширения без учёта регистра; не MIME/security validation.       |
-| `isDomReference`                                    | Floating UI reference → DOM `Element` guard.                               |
-
-`State`, `AbapBoolean`, `Primitive`, `BaseType`, `ArrayType`, `ObjectType`, `InputType`, `RangeType`, `RowRecord`, `isBaseType` — общие low-level contracts. Не используйте `RowRecord` как модель конкретной доменной сущности.
-
-## Идентификаторы, HTTP, XML, SEO и form errors
-
-| Entry point       | API                                                                                                                                                                 |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `crypto`          | `hashString`, `hashString128`, `hashString128Base64Url`, `stringToElementId`, `uuidv4`. Hash служит для stable client key, не криптографической защиты.             |
-| `session-storage` | `getSessionStorageId(key, createId?)` — scoped browser-tab id; не authentication token.                                                                             |
-| `http`            | `createNoStoreHeaders(init?)` создаёт Headers с no-store; `createTextHttpResponse(options)` создаёт text `Response`.                                                |
-| `xml`             | `escapeXmlValue`, `buildXmlFields`, `getXmlTagText` для небольших XML fragments. Не применяйте regex helper как универсальный XML parser для untrusted complex XML. |
-| `seo`             | `createSeoHead(options)`, `createRouteHead(type, path, params)` создают `meta`, `links`, JSON-LD `scripts`; host router/head owner решает, как применить результат. |
-| `form`            | `readFirstFormError(errors?)` выбирает первое readable error message из unknown error array.                                                                        |
-| `error`           | `createMissingContextErrorMessage`, `createMissingContextError` формируют единообразную ошибку отсутствующего React Provider.                                       |
-
-`fingerprint` и `notifications` описаны на странице Runtime/state, потому что имеют browser/global lifecycle.

package/src/docs/runtimeAndState.mdx

@@ -1,155 +0,0 @@
-import { Meta } from "@storybook/addon-docs/blocks";
-
-<Meta title="Foundation Lib/Runtime, state и diagnostics" />
-
-# Runtime, state и diagnostics
-
-Этот раздел содержит инфраструктурные API, которые создаются в composition root host-приложения. Они не должны подключаться из каждой feature: persistence, BroadcastChannel, notifications и error reporting имеют глобальный lifecycle и приватные данные.
-
-## `query-client`: TanStack Query инфраструктура
-
-```ts
-import {
-	configureQueryPersistenceProjectAdapter,
-	createQueryClient,
-	installReactQueryBroadcast,
-	installSessionScopedQueryReset,
-	persistedQueryMeta,
-	resetSessionScopedQueries,
-	sessionScopedQueryMeta
-} from "@ryuzaki13/react-foundation-lib/query-client";
-```
-
-### Composition root
-
-1. До создания `QueryClient` вызовите `configureQueryPersistenceProjectAdapter` при необходимости задать application-specific `persistenceBuster` и `resolveSystemIdentifier`.
-2. Создайте один `QueryClient` через `createQueryClient({ onQueryError?, onMutationError? })`.
-3. В browser bootstrap установите sync/reset channels и обязательно сохраните их `cleanup` для shutdown/tests.
-
-```ts
-configureQueryPersistenceProjectAdapter({
-	persistenceBuster: "host-v1",
-	resolveSystemIdentifier: () => "host-production"
-});
-
-const queryClient = createQueryClient({
-	onQueryError: (error, query) => reportQueryError(error, query)
-});
-
-const broadcast = installReactQueryBroadcast(queryClient, {
-	queriesChannel: "host-query-cache",
-	eventsChannel: "host-query-events"
-});
-const sessionReset = installSessionScopedQueryReset(queryClient, {
-	channelName: "host-session-reset"
-});
-
-// teardown: broadcast.cleanup(); sessionReset.cleanup();
-```
-
-### Persistence, session scope и broadcast
-
-| API                                                      | Когда использовать                                                                                                |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `persistedQueryMeta`                                     | `meta` query только для публичных, serializable данных, которым разрешено переживать restart.                     |
-| `sessionScopedQueryMeta`                                 | `meta` query, чей результат зависит от текущей server session/role. Такой query никогда не сохраняется.           |
-| `shouldPersistQuery(query)`                              | Predicate persistence: true лишь для `persist: true` без `sessionScoped`.                                         |
-| `createIndexedDbQueryStorage(options?)`                  | Создаёт async IndexedDB storage либо `undefined`, если API недоступен.                                            |
-| `createReactQueryPersister()`                            | Создаёт TanStack persister с 90-дневным max age или `undefined`.                                                  |
-| `installReactQueryBroadcast(queryClient, channels)`      | Синхронизирует Query cache и explicit invalidate/set events между вкладками; возвращает `{ broadcast, cleanup }`. |
-| `broadcastCacheEvent(event)` / `setBroadcastFn(fn)`      | Imperative bridge для explicit cache event. Настраивается один раз в composition root.                            |
-| `resetSessionScopedQueries(queryClient, { broadcast? })` | Отменяет, очищает и refetches active session-scoped queries после логина, логаута или смены роли.                 |
-| `installSessionScopedQueryReset(...)`                    | Рассылает только команду reset, не query data; возвращает cleanup.                                                |
-
-Не отмечайте query обоими meta-флагами. Не кладите в persisted/broadcast cache tokens, персональные данные без принятой политики, DOM nodes, функции или class instances.
-
-### Оптимистичная мутация
-
-`onMutateOptimistic`, `onErrorOptimistic`, `onSuccessOptimistic`, `onSettledOptimistic` — low-level helpers для одного известного cache key. `onMutateOptimistic` сначала отменяет запросы, сохраняет `previous`, затем применяет patch. Контекст обязательно передаётся в `onError` для rollback.
-
-```ts
-useMutation({
-	mutationFn: updateTodo,
-	onMutate: (input) => onMutateOptimistic(queryClient, todoKey, (old) => patchTodo(old, input)),
-	onError: (_error, _input, context) => onErrorOptimistic(queryClient, todoKey, context),
-	onSettled: () => onSettledOptimistic(queryClient, todoKey, { refetchType: "active" })
-});
-```
-
-`OnSettledOptimisticOptions.refetchType` defaults to `"none"`. Не применяйте helper к непонятно широкому key: cache strategy должен владеть entity/feature, а не shared infrastructure.
-
-## `error-report`: безопасный diagnostic draft
-
-```ts
-import {
-	captureQueryErrorReport,
-	captureRuntimeErrorReport,
-	getErrorReportDrafts,
-	installErrorReportBrowserBreadcrumbs,
-	setErrorReportRuntimeErrorReporter,
-	setErrorReportTransportErrorReporter
-} from "@ryuzaki13/react-foundation-lib/error-report";
-```
-
-Пакет подготавливает, sanitizes и локально сохраняет diagnostic draft. Он **не** отправляет отчёт в backend сам: transport/delivery принадлежит соответствующему API-пакету или host integration.
-
-| Группа API       | Контракт                                                                                                                                                                                        |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Environment      | `isErrorReportingEnabled`, `getErrorReportEnvironment`, `getErrorReportClientEnvironment` дают browser/non-dev gate и минимальный runtime context.                                              |
-| Safe values      | `createDiagnosticValue`, `createDataShape`, `sanitizeDetail`, `createErrorInfo` превращают `unknown` в serializable diagnostic form. Не передавайте секреты даже в sanitizing API.              |
-| Breadcrumbs      | `addErrorReportBreadcrumb`, `getErrorReportBreadcrumbs`, `clearErrorReportBreadcrumbs`, `installErrorReportBrowserBreadcrumbs`. Установка browser listener возвращает cleanup.                  |
-| Capture          | `captureQueryErrorReport`, `captureMutationErrorReport`, `captureRuntimeErrorReport` создают `ErrorReportDraft` с query/mutation/runtime diagnostics.                                           |
-| Drafts           | `captureErrorReportDraft`, `getErrorReportDraft`, `getErrorReportDrafts`, `updateErrorReportDraft` управляют локальными draft.                                                                  |
-| Reporting bridge | `setErrorReportRuntimeErrorReporter` + `reportRuntimeError`; `setErrorReportTransportErrorReporter`, `reportTransportError`, `suppressTransportErrorReport`, `isTransportErrorReportScheduled`. |
-| Diagnostics      | `collectQueryDiagnostics`, `collectMutationDiagnostics`, `collectQueryClientDiagnostics`, `collectPersistedQueryDiagnostics`.                                                                   |
-
-### Подключение reporter-а
-
-```ts
-setErrorReportRuntimeErrorReporter(async (error, context) => {
-	const draft = captureRuntimeErrorReport(error, context, queryClient);
-	// Передайте draft в owner transport только после собственной privacy policy.
-	await deliverDiagnosticDraft(await draft);
-});
-```
-
-`ErrorReportPayload`, `ErrorReportDraft`, `ErrorReportBreadcrumb`, `ErrorReportErrorInfo`, `ErrorReportSafeValue` и context types — публичные contracts для typed delivery. Runtime capture в браузере coalesces одинаковые ошибки на коротком окне, чтобы flood не создавал много draft. Не дублируйте transport report: `capture*` корректно вызывает `suppressTransportErrorReport` для исходной ошибки.
-
-## `notifications`: global imperative facade
-
-```ts
-import { bindNotifications, createNotificationsStore, notify } from "@ryuzaki13/react-foundation-lib/notifications";
-```
-
-```ts
-const notificationsStore = createNotificationsStore();
-const unbind = bindNotifications(notificationsStore);
-
-notify.success("Сохранено");
-const progress = notify.progress("Загрузка…");
-progress.success("Готово");
-
-// teardown composition root: unbind();
-```
-
-| API                                       | Назначение                                                                                                     |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `createNotificationsStore()`              | Создаёт Zustand store с max 6 items и timer cleanup. Вызов только в browser-compatible UI composition.         |
-| `bindNotifications(store)`                | Связывает единственный store с imperative `notify`; возвращает unbind. До bind любой `notify.*` бросает Error. |
-| `notify.push/upsert/update/dismiss/clear` | Imperative actions над `NotificationPushInput`/`NotificationUpdatePatch`.                                      |
-| `notify.success/info/warning/error`       | Удобные typed shortcuts.                                                                                       |
-| `notify.progress(message, opts?)`         | Возвращает `{ id, update, success, error, dismiss }` для долгой операции.                                      |
-
-`Notification`, `NotificationAction`, `NotificationType`, `NotificationTone`, `NotificationId` описывают данные, а не UI rendering. UI owner подписывается на `NotificationsStoreApi` и отвечает за accessibility/визуал.
-
-## OData collection preferences, session и fingerprint
-
-```ts
-import { odataCollectionConfig, useODataCollectionStore } from "@ryuzaki13/react-foundation-lib/odata";
-import { getSessionStorageId } from "@ryuzaki13/react-foundation-lib/session-storage";
-import { getClientFingerprint } from "@ryuzaki13/react-foundation-lib/fingerprint";
-```
-
-`odataCollectionConfig` даёт selectors для общих UI-defaults (`maxVisibleItems`, min search lengths, debounce); `useODataCollectionStore` даёт state и setters. Это клиентские предпочтения, не backend data и не metadata cache.
-
-`getSessionStorageId(key, createId?)` возвращает стабильный ID одной вкладки из `sessionStorage`; при storage failure всё равно вернёт новый ID. `getClientFingerprint()` асинхронно возвращает fingerprint или `null`, если библиотека/API недоступны. Не используйте fingerprint как authentication/authorization credential.

package/src/file/README.md

@@ -1,289 +0,0 @@
-# Библиотека чтения файлов
-
-Библиотека для безопасного чтения файлов на клиенте через `FileReader` API с валидацией, поддержкой отмены и строгой типизацией.
-
-## Структура
-
-```
-src/shared/lib/file/
-├── read-file/          — универсальное чтение любых файлов
-│   ├── types.ts
-│   ├── readFile.ts
-│   └── index.ts
-├── image/              — чтение изображений (надстройка над read-file)
-│   ├── types.ts
-│   ├── readImageFile.ts
-│   └── index.ts
-└── index.ts
-```
-
-Все экспорты доступны через `@/shared/lib`.
-
----
-
-## `readFile` — чтение любых файлов
-
-Универсальная функция для чтения файлов. Поддерживает два режима: `data-url` (по умолчанию) и `array-buffer`.
-
-### Сигнатуры
-
-```ts
-// Чтение как Data URL (по умолчанию)
-readFile(file: File, opts?: { mode?: "data-url"; ... }): Promise<ReadFileAsDataUrlResult>
-
-// Чтение как ArrayBuffer
-readFile(file: File, opts: { mode: "array-buffer"; ... }): Promise<ReadFileAsArrayBufferResult>
-```
-
-### Опции (`ReadFileOptions`)
-
-| Параметр      | Тип                            | По умолчанию | Описание                           |
-| ------------- | ------------------------------ | ------------ | ---------------------------------- |
-| `mode`        | `"data-url" \| "array-buffer"` | `"data-url"` | Режим чтения файла                 |
-| `allowedMime` | `readonly string[]`            | —            | Список разрешённых MIME-типов      |
-| `maxBytes`    | `number`                       | —            | Максимальный размер файла в байтах |
-| `signal`      | `AbortSignal`                  | —            | Сигнал для отмены операции         |
-
-### Результат
-
-**`ReadFileAsDataUrlResult`** (при `mode: "data-url"`):
-
-| Поле      | Тип          | Описание                      |
-| --------- | ------------ | ----------------------------- |
-| `mode`    | `"data-url"` | Дискриминант режима           |
-| `meta`    | `FileMeta`   | Метаданные файла              |
-| `dataUrl` | `string`     | Содержимое в формате Data URL |
-| `file`    | `File`       | Исходный объект `File`        |
-
-**`ReadFileAsArrayBufferResult`** (при `mode: "array-buffer"`):
-
-| Поле     | Тип              | Описание               |
-| -------- | ---------------- | ---------------------- |
-| `mode`   | `"array-buffer"` | Дискриминант режима    |
-| `meta`   | `FileMeta`       | Метаданные файла       |
-| `buffer` | `ArrayBuffer`    | Бинарное содержимое    |
-| `file`   | `File`           | Исходный объект `File` |
-
-**`FileMeta`** — метаданные файла:
-
-| Поле           | Тип      | Описание                               |
-| -------------- | -------- | -------------------------------------- |
-| `mime`         | `string` | MIME-тип файла                         |
-| `size`         | `number` | Размер в байтах                        |
-| `name`         | `string` | Имя файла                              |
-| `lastModified` | `number` | Время последнего изменения (timestamp) |
-
-### Примеры
-
-**Чтение PDF-файла как Data URL для предпросмотра:**
-
-```ts
-import { readFile, ReadFileError } from "@/shared/lib";
-
-async function handlePdfUpload(file: File) {
-  try {
-    const result = await readFile(file, {
-      allowedMime: ["application/pdf"],
-      maxBytes: 50 * 1024 * 1024, // 50 МБ
-    });
-
-    // result.mode === "data-url" (тип сужен автоматически)
-    console.log(result.meta.name);   // "document.pdf"
-    console.log(result.meta.size);   // 1234567
-    previewIframe.src = result.dataUrl;
-  } catch (error) {
-    if (error instanceof ReadFileError) {
-      console.error(error.code, error.message);
-    }
-  }
-}
-```
-
-**Чтение файла как ArrayBuffer для отправки на сервер:**
-
-```ts
-import { readFile } from "@/shared/lib";
-
-async function uploadDocument(file: File) {
-  const result = await readFile(file, {
-    mode: "array-buffer",
-    maxBytes: 100 * 1024 * 1024, // 100 МБ
-  });
-
-  // result.buffer: ArrayBuffer (тип сужен автоматически)
-  await fetch("/api/upload", {
-    method: "POST",
-    body: result.buffer,
-    headers: { "Content-Type": result.meta.mime },
-  });
-}
-```
-
-**Чтение с поддержкой отмены:**
-
-```ts
-import { readFile } from "@/shared/lib";
-
-const controller = new AbortController();
-
-// Отмена через 5 секунд
-setTimeout(() => controller.abort(), 5000);
-
-const result = await readFile(file, {
-  signal: controller.signal,
-});
-```
-
-**Чтение без ограничений (любой файл):**
-
-```ts
-import { readFile } from "@/shared/lib";
-
-const result = await readFile(file);
-// result.meta.mime — реальный MIME-тип файла
-// result.dataUrl — Data URL для любого типа
-```
-
----
-
-## `readImageFile` — чтение изображений
-
-Надстройка над `readFile` для работы с изображениями. Добавляет:
-
-- Проверку что файл является изображением (`image/*`)
-- Типизацию `allowedMime` на `ImageMime` (только image-типы)
-- Автоматическое извлечение размеров изображения (`dimensions`) в режиме `data-url`
-
-### Сигнатуры
-
-```ts
-// Чтение как Data URL с размерами (по умолчанию)
-readImageFile(file: File, opts?: { mode?: "data-url"; ... }): Promise<ReadImageAsDataUrlResult>
-
-// Чтение как ArrayBuffer
-readImageFile(file: File, opts: { mode: "array-buffer"; ... }): Promise<ReadImageAsArrayBufferResult>
-```
-
-### Опции (`ReadImageOptions`)
-
-| Параметр      | Тип                            | По умолчанию | Описание                           |
-| ------------- | ------------------------------ | ------------ | ---------------------------------- |
-| `mode`        | `"data-url" \| "array-buffer"` | `"data-url"` | Режим чтения файла                 |
-| `allowedMime` | `readonly ImageMime[]`         | —            | Разрешённые image MIME-типы        |
-| `maxBytes`    | `number`                       | —            | Максимальный размер файла в байтах |
-| `signal`      | `AbortSignal`                  | —            | Сигнал для отмены операции         |
-
-**`ImageMime`** — допустимые значения:
-`"image/png"`, `"image/jpeg"`, `"image/webp"`, `"image/gif"`, `"image/svg+xml"`, `"image/avif"`
-
-### Результат
-
-**`ReadImageAsDataUrlResult`** расширяет `ReadFileAsDataUrlResult`:
-
-| Поле         | Тип                | Описание                         |
-| ------------ | ------------------ | -------------------------------- |
-| `mode`       | `"data-url"`       | Дискриминант режима              |
-| `meta`       | `FileMeta`         | Метаданные файла                 |
-| `dataUrl`    | `string`           | Содержимое в формате Data URL    |
-| `file`       | `File`             | Исходный объект `File`           |
-| `dimensions` | `ImageDimensions?` | Ширина и высота изображения (px) |
-
-**`ReadImageAsArrayBufferResult`** — идентичен `ReadFileAsArrayBufferResult`.
-
-### Примеры
-
-**Загрузка фото с ограничениями:**
-
-```ts
-import { readImageFile, ReadImageError } from "@/shared/lib";
-
-async function selectPhoto(file: File) {
-  try {
-    const result = await readImageFile(file, {
-      allowedMime: ["image/jpeg", "image/png", "image/webp"],
-      maxBytes: 10 * 1024 * 1024, // 10 МБ
-    });
-
-    console.log(result.dimensions); // { width: 1920, height: 1080 }
-    preview.src = result.dataUrl;
-  } catch (error) {
-    if (error instanceof ReadImageError) {
-      switch (error.code) {
-        case "NOT_AN_IMAGE":
-          alert("Выберите изображение");
-          break;
-        case "MIME_NOT_ALLOWED":
-          alert("Формат не поддерживается");
-          break;
-        case "FILE_TOO_LARGE":
-          alert("Файл слишком большой");
-          break;
-      }
-    }
-  }
-}
-```
-
-**Чтение изображения как ArrayBuffer:**
-
-```ts
-import { readImageFile } from "@/shared/lib";
-
-const result = await readImageFile(file, { mode: "array-buffer" });
-// result.buffer: ArrayBuffer
-// dimensions не извлекаются в этом режиме
-```
-
----
-
-## Обработка ошибок
-
-### `ReadFileError`
-
-Базовый класс ошибок для `readFile`.
-
-| Код                | Когда возникает                                      |
-| ------------------ | ---------------------------------------------------- |
-| `NO_FILE`          | Файл не передан                                      |
-| `MIME_NOT_ALLOWED` | MIME-тип файла не входит в `allowedMime`             |
-| `FILE_TOO_LARGE`   | Размер файла превышает `maxBytes`                    |
-| `READ_ABORTED`     | Чтение прервано через `AbortSignal` или `FileReader` |
-| `READ_FAILED`      | Ошибка `FileReader` при чтении                       |
-
-### `ReadImageError`
-
-Класс ошибок для `readImageFile`. Наследует все коды из `ReadFileErrorCode` и добавляет:
-
-| Код                   | Когда возникает                                            |
-| --------------------- | ---------------------------------------------------------- |
-| `NOT_AN_IMAGE`        | MIME-тип файла не начинается с `image/`                    |
-| `IMAGE_DECODE_FAILED` | Не удалось декодировать изображение для получения размеров |
-
-### Пример обработки ошибок
-
-```ts
-import { readFile, ReadFileError } from "@/shared/lib";
-
-try {
-  const result = await readFile(file, { maxBytes: 5 * 1024 * 1024 });
-} catch (error) {
-  if (error instanceof ReadFileError) {
-    // error.code — строковый код ошибки
-    // error.message — описание на русском
-    // error.cause — оригинальная ошибка (если есть)
-    console.error(`[${error.code}] ${error.message}`);
-  }
-}
-```
-
----
-
-## Утилиты
-
-Экспортируются из `read-file` для переиспользования в надстройках:
-
-| Функция                       | Описание                                                             |
-| ----------------------------- | -------------------------------------------------------------------- |
-| `buildMeta(file)`             | Извлекает `FileMeta` из объекта `File`                               |
-| `assertNotAborted(signal?)`   | Бросает `ReadFileError("READ_ABORTED")` если сигнал отменён          |
-| `attachAbort(signal, reader)` | Привязывает `AbortSignal` к `FileReader`, возвращает функцию отписки |