@ryuzaki13/react-foundation-lib 2.15.0 → 2.17.0

package/README.md

@@ -89,6 +89,7 @@ npm run pack:dry-run
 | Tree table преобразования                                                   | [`tree-table`](./src/tree-table/index.ts), документация в общем справочнике [`table/README.mdx`](./src/table/README.mdx), тесты в [`tree-table`](./src/tree-table)                                                                  |
 | Excel export                                                                | [`excel`](./src/excel/index.ts), подробный README: [`excel/README.mdx`](./src/excel/README.mdx), тесты: [`excel.test.ts`](./src/excel/excel.test.ts), [`tableExport.test.ts`](./src/excel/tableExport.test.ts)                      |
 | FileReader, изображения, base64 Blob                                        | [`file`](./src/file/index.ts), [`binary`](./src/binary/index.ts)                                                                                                                                                                    |
+| Проверка серверного пути внутри root, ошибки отсутствующего файла            | [`file-system`](./src/file-system/index.ts), Node.js API: [`file-system/README.mdx`](./src/file-system/README.mdx)                                                                                                                   |
 | DOM overlay, portal, focus, download                                        | [`dom`](./src/dom/index.ts), тест: [`dom.test.tsx`](./src/dom/dom.test.tsx)                                                                                                                                                         |
 | Debounce/throttle, DnD sensors, search params, listbox                      | [`hooks`](./src/hooks/index.ts), подробный README: [`hooks/README.mdx`](./src/hooks/README.mdx), [`utils/keyboard.ts`](./src/utils/keyboard.ts)                                                                                     |
 | Breakpoints, media queries и responsive props                               | [`media`](./src/media/index.ts), подробный README: [`media/README.mdx`](./src/media/README.mdx), тест: [`media.test.ts`](./src/media/media.test.ts)                                                                                 |
@@ -118,6 +119,7 @@ npm run pack:dry-run
 | `/error-report`        | [`error-report/README.mdx`](./src/error-report/README.mdx)                     |
 | `/excel`               | [`excel/README.mdx`](./src/excel/README.mdx)                                   |
 | `/file`                | [`file/README.mdx`](./src/file/README.mdx)                                     |
+| `/file-system`         | [Node.js: пути внутри хранилища](./src/file-system/README.mdx)                 |
 | `/fingerprint`         | [`fingerprint/README.mdx`](./src/fingerprint/README.mdx)                       |
 | `/form`                | [`form/README.mdx`](./src/form/README.mdx)                                     |
 | `/formatters`          | [`formatters/README.mdx`](./src/formatters/README.mdx) и его предметные README |
@@ -528,10 +530,11 @@ Pipeline — runtime форматирования ячейки. Он прини
 | API              | Поведение                                                                      |
 | ---------------- | ------------------------------------------------------------------------------ |
 | `binaryToBlob`   | Base64/data URL/raw binary string -> `Blob`; валидирует пустые и битые данные. |
+| `getBase64DecodedSize` | Проверяет стандартный Base64 и считает размер без декодирования; неверная форма -> `null`, пустая строка -> `0`. |
 | `detectMimeType` | MIME по filename, data URL, byte signature, fallback `application/pdf`.        |
 | `useBinaryFile`  | Hook: base64 string -> `{ blob, mime }` или error; object URL не создает.      |
 
-Тест: [`binaryToBlob.test.ts`](./src/binary/binaryToBlob.test.ts).
+Тесты: [`binaryToBlob.test.ts`](./src/binary/binaryToBlob.test.ts), [`getBase64DecodedSize.test.ts`](./src/binary/getBase64DecodedSize.test.ts).
 
 ### `xml`
 

package/dist/binary/getBase64DecodedSize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Проверяет стандартную Base64-форму и считает байты без декодирования или создания Buffer/Blob.
+ * Невалидный payload возвращает null, пустая строка — 0; допустимый размер определяет вызывающий контракт.
+ * Data URL, whitespace, URL-safe алфавит и отсутствующий padding здесь не нормализуются.
+ */
+export declare function getBase64DecodedSize(value: string): number | null;
+//# sourceMappingURL=getBase64DecodedSize.d.ts.map

package/dist/binary/getBase64DecodedSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getBase64DecodedSize.d.ts","sourceRoot":"","sources":["../../src/binary/getBase64DecodedSize.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMjE"}

package/dist/binary/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./binaryToBlob";
+export { getBase64DecodedSize } from "./getBase64DecodedSize";
 export * from "./useBinaryFile";
 //# sourceMappingURL=index.d.ts.map

package/dist/binary/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/binary/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/binary/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,cAAc,iBAAiB,CAAC"}

package/dist/binary/index.js

@@ -99,10 +99,15 @@ var i = "application/octet-stream", a = "application/pdf", o = /^data:([^,]*);ba
 		if (n) return n;
 	}
 	return a;
-};
+}, y = /[^A-Za-z0-9+/=]/;
+function b(e) {
+	if (e.length % 4 != 0 || y.test(e)) return null;
+	let t = e.endsWith("==") ? 2 : +!!e.endsWith("="), n = e.indexOf("=");
+	return n !== -1 && n !== e.length - t ? null : Math.floor(e.length * 3 / 4) - t;
+}
 //#endregion
 //#region src/binary/useBinaryFile.ts
-function y(i) {
+function x(i) {
 	let [a, o] = r(null), [s, c] = r(null), l = n((e) => o(e)), u = n((e) => c(e));
 	return t(() => {
 		if (i) try {
@@ -121,6 +126,6 @@ function y(i) {
 	};
 }
 //#endregion
-export { _ as binaryToBlob, v as detectMimeType, y as useBinaryFile };
+export { _ as binaryToBlob, v as detectMimeType, b as getBase64DecodedSize, x as useBinaryFile };
 
 //# sourceMappingURL=index.js.map

package/dist/binary/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/binary/binaryToBlob.ts","../../src/binary/useBinaryFile.ts"],"sourcesContent":["const DEFAULT_BLOB_MIME_TYPE = \"application/octet-stream\";\nconst DEFAULT_DOCUMENT_MIME_TYPE = \"application/pdf\";\nconst BASE64_DATA_URL_PATTERN = /^data:([^,]*);base64,([\\s\\S]*)$/i;\n\nconst MIME_TYPE_BY_EXTENSION: Record<string, string> = {\n\tbmp: \"image/bmp\",\n\tcsv: \"text/csv\",\n\tdoc: \"application/msword\",\n\tdocx: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n\tgif: \"image/gif\",\n\tjpeg: \"image/jpeg\",\n\tjpg: \"image/jpeg\",\n\tjson: \"application/json\",\n\tpdf: \"application/pdf\",\n\tpng: \"image/png\",\n\tppt: \"application/vnd.ms-powerpoint\",\n\tpptx: \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n\tsvg: \"image/svg+xml\",\n\ttif: \"image/tiff\",\n\ttiff: \"image/tiff\",\n\ttxt: \"text/plain\",\n\twebp: \"image/webp\",\n\txls: \"application/vnd.ms-excel\",\n\txlsx: \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n\txml: \"application/xml\",\n\tzip: \"application/zip\"\n};\n\nconst normalizeBase64 = (value: string): string => {\n\tconst normalized = value.replace(/\\s/g, \"\").replace(/-/g, \"+\").replace(/_/g, \"/\");\n\tconst paddingRest = normalized.length % 4;\n\n\tif (paddingRest === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {\n\t\tthrow new Error(\"Некорректный формат base64\");\n\t}\n\n\treturn paddingRest === 0 ? normalized : `${normalized}${\"=\".repeat(4 - paddingRest)}`;\n};\n\nconst getBase64RawPayload = (binaryData: string): { data: string; mimeType: string | null } => {\n\tconst dataUrlMatch = binaryData.match(BASE64_DATA_URL_PATTERN);\n\n\tif (!dataUrlMatch) {\n\t\treturn { data: binaryData, mimeType: null };\n\t}\n\n\tconst [, rawMimeType, rawData] = dataUrlMatch;\n\tconst mimeType = rawMimeType.split(\";\")[0].trim();\n\n\treturn {\n\t\tdata: rawData,\n\t\tmimeType: mimeType || null\n\t};\n};\n\nconst getBase64Payload = (binaryData: string): { data: string; mimeType: string | null } => {\n\tconst payload = getBase64RawPayload(binaryData);\n\n\treturn {\n\t\tdata: normalizeBase64(payload.data),\n\t\tmimeType: payload.mimeType\n\t};\n};\n\nconst getDataUrlMimeType = (binaryData: string): string | null => {\n\tconst dataUrlMatch = binaryData.match(BASE64_DATA_URL_PATTERN);\n\n\tif (!dataUrlMatch) {\n\t\treturn null;\n\t}\n\n\tconst mimeType = dataUrlMatch[1].split(\";\")[0].trim();\n\n\treturn mimeType || null;\n};\n\nconst decodeBase64ToBytes = (binaryData: string): Uint8Array => {\n\tconst { data } = getBase64Payload(binaryData);\n\tconst binaryString = atob(data);\n\tconst byteArray = new Uint8Array(binaryString.length);\n\n\tfor (let index = 0; index < binaryString.length; index++) {\n\t\tbyteArray[index] = binaryString.charCodeAt(index);\n\t}\n\n\treturn byteArray;\n};\n\nconst binaryStringToBytes = (binaryData: string): Uint8Array => {\n\tconst byteArray = new Uint8Array(binaryData.length);\n\n\tfor (let index = 0; index < binaryData.length; index++) {\n\t\tbyteArray[index] = binaryData.charCodeAt(index);\n\t}\n\n\treturn byteArray;\n};\n\nconst copyBytesToArrayBuffer = (byteArray: Uint8Array): ArrayBuffer => {\n\tconst buffer = new ArrayBuffer(byteArray.byteLength);\n\tconst view = new Uint8Array(buffer);\n\n\tview.set(byteArray);\n\n\treturn buffer;\n};\n\nconst decodeHeaderFromBase64 = (binaryData: string): string | null => {\n\ttry {\n\t\tconst { data } = getBase64RawPayload(binaryData);\n\t\tconst headerData = data.slice(0, 128);\n\t\tconst binaryString = atob(normalizeBase64(headerData));\n\n\t\treturn binaryString;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\nconst detectMimeTypeBySignature = (binaryData: string): string | null => {\n\tconst header = decodeHeaderFromBase64(binaryData);\n\n\tif (!header) {\n\t\treturn null;\n\t}\n\n\tconst bytes = new Uint8Array(header.length);\n\n\tfor (let index = 0; index < header.length; index++) {\n\t\tbytes[index] = header.charCodeAt(index);\n\t}\n\n\tif (bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) {\n\t\treturn \"application/pdf\";\n\t}\n\n\tif (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {\n\t\treturn \"image/jpeg\";\n\t}\n\n\tif (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {\n\t\treturn \"image/png\";\n\t}\n\n\tif (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {\n\t\treturn \"image/gif\";\n\t}\n\n\tif (bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46) {\n\t\treturn \"image/webp\";\n\t}\n\n\tif (bytes[0] === 0x50 && bytes[1] === 0x4b) {\n\t\treturn \"application/zip\";\n\t}\n\n\tconst textHeader = header\n\t\t.replace(/^\\uFEFF/, \"\")\n\t\t.trimStart()\n\t\t.slice(0, 16);\n\n\tif (textHeader.startsWith(\"<?xml\") || textHeader.startsWith(\"<\")) {\n\t\treturn \"application/xml\";\n\t}\n\n\treturn null;\n};\n\n/**\n * Преобразует base64 или бинарную строку в Blob.\n *\n * Data URL с префиксом `data:*;base64,` поддерживается, сам URL здесь не создаётся.\n */\nexport const binaryToBlob = (binaryData: string, mimeType: string = DEFAULT_BLOB_MIME_TYPE, isBase64 = true): Blob => {\n\tif (!binaryData) {\n\t\tthrow new Error(\"Не переданы бинарные данные\");\n\t}\n\n\ttry {\n\t\tconst byteArray = isBase64 ? decodeBase64ToBytes(binaryData) : binaryStringToBytes(binaryData);\n\n\t\tif (byteArray.length === 0) {\n\t\t\tthrow new Error(\"После преобразования не осталось данных\");\n\t\t}\n\n\t\treturn new Blob([copyBytesToArrayBuffer(byteArray)], { type: mimeType.trim() || DEFAULT_BLOB_MIME_TYPE });\n\t} catch (error) {\n\t\tif (error instanceof Error) {\n\t\t\tthrow error;\n\t\t}\n\t\tthrow new Error(\"Некорректный формат бинарных данных\");\n\t}\n};\n\n/**\n * Определяет MIME-тип по имени файла, data URL или сигнатуре base64-данных.\n *\n * Если определить тип не удалось, используется PDF: большинство документов в этом контуре приходят именно так.\n */\nexport const detectMimeType = (fileName?: string, binaryData?: string): string => {\n\tif (fileName) {\n\t\tconst extension = fileName.toLowerCase().split(\".\").pop();\n\n\t\tif (extension && MIME_TYPE_BY_EXTENSION[extension]) {\n\t\t\treturn MIME_TYPE_BY_EXTENSION[extension];\n\t\t}\n\t}\n\n\tif (binaryData) {\n\t\tconst dataUrlMimeType = getDataUrlMimeType(binaryData);\n\n\t\tif (dataUrlMimeType) {\n\t\t\treturn dataUrlMimeType;\n\t\t}\n\n\t\tconst signatureMimeType = detectMimeTypeBySignature(binaryData);\n\n\t\tif (signatureMimeType) {\n\t\t\treturn signatureMimeType;\n\t\t}\n\t}\n\n\treturn DEFAULT_DOCUMENT_MIME_TYPE;\n};\n","import { useEffect, useEffectEvent, useState } from \"react\";\n\nimport { logError } from \"../utils\";\n\nimport { binaryToBlob, detectMimeType } from \"./binaryToBlob\";\n\nexport function useBinaryFile(bin: string | undefined) {\n\tconst [entry, setEntry] = useState<{ blob: Blob; mime: string } | null>(null);\n\tconst [error, setError] = useState<string | null>(null);\n\n\tconst updateEntry = useEffectEvent((data: { blob: Blob; mime: string } | null) => setEntry(data));\n\tconst updateError = useEffectEvent((error: string | null) => setError(error));\n\n\tuseEffect(() => {\n\t\tif (bin) {\n\t\t\ttry {\n\t\t\t\tconst mime = detectMimeType(undefined, bin);\n\t\t\t\tconst blob = binaryToBlob(bin, mime, true);\n\n\t\t\t\tupdateEntry({ blob, mime });\n\t\t\t\tupdateError(null);\n\t\t\t} catch (e) {\n\t\t\t\tlogError(e);\n\n\t\t\t\tupdateError(String(e));\n\t\t\t\tupdateEntry(null);\n\t\t\t}\n\t\t} else {\n\t\t\tupdateEntry(null);\n\t\t\tupdateError(null);\n\t\t}\n\t}, [bin]);\n\n\treturn { data: entry, error };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/binary/binaryToBlob.ts","../../src/binary/getBase64DecodedSize.ts","../../src/binary/useBinaryFile.ts"],"sourcesContent":["const DEFAULT_BLOB_MIME_TYPE = \"application/octet-stream\";\nconst DEFAULT_DOCUMENT_MIME_TYPE = \"application/pdf\";\nconst BASE64_DATA_URL_PATTERN = /^data:([^,]*);base64,([\\s\\S]*)$/i;\n\nconst MIME_TYPE_BY_EXTENSION: Record<string, string> = {\n\tbmp: \"image/bmp\",\n\tcsv: \"text/csv\",\n\tdoc: \"application/msword\",\n\tdocx: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n\tgif: \"image/gif\",\n\tjpeg: \"image/jpeg\",\n\tjpg: \"image/jpeg\",\n\tjson: \"application/json\",\n\tpdf: \"application/pdf\",\n\tpng: \"image/png\",\n\tppt: \"application/vnd.ms-powerpoint\",\n\tpptx: \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n\tsvg: \"image/svg+xml\",\n\ttif: \"image/tiff\",\n\ttiff: \"image/tiff\",\n\ttxt: \"text/plain\",\n\twebp: \"image/webp\",\n\txls: \"application/vnd.ms-excel\",\n\txlsx: \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n\txml: \"application/xml\",\n\tzip: \"application/zip\"\n};\n\nconst normalizeBase64 = (value: string): string => {\n\tconst normalized = value.replace(/\\s/g, \"\").replace(/-/g, \"+\").replace(/_/g, \"/\");\n\tconst paddingRest = normalized.length % 4;\n\n\tif (paddingRest === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {\n\t\tthrow new Error(\"Некорректный формат base64\");\n\t}\n\n\treturn paddingRest === 0 ? normalized : `${normalized}${\"=\".repeat(4 - paddingRest)}`;\n};\n\nconst getBase64RawPayload = (binaryData: string): { data: string; mimeType: string | null } => {\n\tconst dataUrlMatch = binaryData.match(BASE64_DATA_URL_PATTERN);\n\n\tif (!dataUrlMatch) {\n\t\treturn { data: binaryData, mimeType: null };\n\t}\n\n\tconst [, rawMimeType, rawData] = dataUrlMatch;\n\tconst mimeType = rawMimeType.split(\";\")[0].trim();\n\n\treturn {\n\t\tdata: rawData,\n\t\tmimeType: mimeType || null\n\t};\n};\n\nconst getBase64Payload = (binaryData: string): { data: string; mimeType: string | null } => {\n\tconst payload = getBase64RawPayload(binaryData);\n\n\treturn {\n\t\tdata: normalizeBase64(payload.data),\n\t\tmimeType: payload.mimeType\n\t};\n};\n\nconst getDataUrlMimeType = (binaryData: string): string | null => {\n\tconst dataUrlMatch = binaryData.match(BASE64_DATA_URL_PATTERN);\n\n\tif (!dataUrlMatch) {\n\t\treturn null;\n\t}\n\n\tconst mimeType = dataUrlMatch[1].split(\";\")[0].trim();\n\n\treturn mimeType || null;\n};\n\nconst decodeBase64ToBytes = (binaryData: string): Uint8Array => {\n\tconst { data } = getBase64Payload(binaryData);\n\tconst binaryString = atob(data);\n\tconst byteArray = new Uint8Array(binaryString.length);\n\n\tfor (let index = 0; index < binaryString.length; index++) {\n\t\tbyteArray[index] = binaryString.charCodeAt(index);\n\t}\n\n\treturn byteArray;\n};\n\nconst binaryStringToBytes = (binaryData: string): Uint8Array => {\n\tconst byteArray = new Uint8Array(binaryData.length);\n\n\tfor (let index = 0; index < binaryData.length; index++) {\n\t\tbyteArray[index] = binaryData.charCodeAt(index);\n\t}\n\n\treturn byteArray;\n};\n\nconst copyBytesToArrayBuffer = (byteArray: Uint8Array): ArrayBuffer => {\n\tconst buffer = new ArrayBuffer(byteArray.byteLength);\n\tconst view = new Uint8Array(buffer);\n\n\tview.set(byteArray);\n\n\treturn buffer;\n};\n\nconst decodeHeaderFromBase64 = (binaryData: string): string | null => {\n\ttry {\n\t\tconst { data } = getBase64RawPayload(binaryData);\n\t\tconst headerData = data.slice(0, 128);\n\t\tconst binaryString = atob(normalizeBase64(headerData));\n\n\t\treturn binaryString;\n\t} catch {\n\t\treturn null;\n\t}\n};\n\nconst detectMimeTypeBySignature = (binaryData: string): string | null => {\n\tconst header = decodeHeaderFromBase64(binaryData);\n\n\tif (!header) {\n\t\treturn null;\n\t}\n\n\tconst bytes = new Uint8Array(header.length);\n\n\tfor (let index = 0; index < header.length; index++) {\n\t\tbytes[index] = header.charCodeAt(index);\n\t}\n\n\tif (bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46) {\n\t\treturn \"application/pdf\";\n\t}\n\n\tif (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {\n\t\treturn \"image/jpeg\";\n\t}\n\n\tif (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {\n\t\treturn \"image/png\";\n\t}\n\n\tif (bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46) {\n\t\treturn \"image/gif\";\n\t}\n\n\tif (bytes[0] === 0x52 && bytes[1] === 0x49 && bytes[2] === 0x46 && bytes[3] === 0x46) {\n\t\treturn \"image/webp\";\n\t}\n\n\tif (bytes[0] === 0x50 && bytes[1] === 0x4b) {\n\t\treturn \"application/zip\";\n\t}\n\n\tconst textHeader = header\n\t\t.replace(/^\\uFEFF/, \"\")\n\t\t.trimStart()\n\t\t.slice(0, 16);\n\n\tif (textHeader.startsWith(\"<?xml\") || textHeader.startsWith(\"<\")) {\n\t\treturn \"application/xml\";\n\t}\n\n\treturn null;\n};\n\n/**\n * Преобразует base64 или бинарную строку в Blob.\n *\n * Data URL с префиксом `data:*;base64,` поддерживается, сам URL здесь не создаётся.\n */\nexport const binaryToBlob = (binaryData: string, mimeType: string = DEFAULT_BLOB_MIME_TYPE, isBase64 = true): Blob => {\n\tif (!binaryData) {\n\t\tthrow new Error(\"Не переданы бинарные данные\");\n\t}\n\n\ttry {\n\t\tconst byteArray = isBase64 ? decodeBase64ToBytes(binaryData) : binaryStringToBytes(binaryData);\n\n\t\tif (byteArray.length === 0) {\n\t\t\tthrow new Error(\"После преобразования не осталось данных\");\n\t\t}\n\n\t\treturn new Blob([copyBytesToArrayBuffer(byteArray)], { type: mimeType.trim() || DEFAULT_BLOB_MIME_TYPE });\n\t} catch (error) {\n\t\tif (error instanceof Error) {\n\t\t\tthrow error;\n\t\t}\n\t\tthrow new Error(\"Некорректный формат бинарных данных\");\n\t}\n};\n\n/**\n * Определяет MIME-тип по имени файла, data URL или сигнатуре base64-данных.\n *\n * Если определить тип не удалось, используется PDF: большинство документов в этом контуре приходят именно так.\n */\nexport const detectMimeType = (fileName?: string, binaryData?: string): string => {\n\tif (fileName) {\n\t\tconst extension = fileName.toLowerCase().split(\".\").pop();\n\n\t\tif (extension && MIME_TYPE_BY_EXTENSION[extension]) {\n\t\t\treturn MIME_TYPE_BY_EXTENSION[extension];\n\t\t}\n\t}\n\n\tif (binaryData) {\n\t\tconst dataUrlMimeType = getDataUrlMimeType(binaryData);\n\n\t\tif (dataUrlMimeType) {\n\t\t\treturn dataUrlMimeType;\n\t\t}\n\n\t\tconst signatureMimeType = detectMimeTypeBySignature(binaryData);\n\n\t\tif (signatureMimeType) {\n\t\t\treturn signatureMimeType;\n\t\t}\n\t}\n\n\treturn DEFAULT_DOCUMENT_MIME_TYPE;\n};\n","const INVALID_BASE64_CHARACTER_PATTERN = /[^A-Za-z0-9+/=]/;\n\n/**\n * Проверяет стандартную Base64-форму и считает байты без декодирования или создания Buffer/Blob.\n * Невалидный payload возвращает null, пустая строка — 0; допустимый размер определяет вызывающий контракт.\n * Data URL, whitespace, URL-safe алфавит и отсутствующий padding здесь не нормализуются.\n */\nexport function getBase64DecodedSize(value: string): number | null {\n\tif (value.length % 4 !== 0 || INVALID_BASE64_CHARACTER_PATTERN.test(value)) return null;\n\tconst paddingLength = value.endsWith(\"==\") ? 2 : value.endsWith(\"=\") ? 1 : 0;\n\tconst firstPaddingIndex = value.indexOf(\"=\");\n\tif (firstPaddingIndex !== -1 && firstPaddingIndex !== value.length - paddingLength) return null;\n\treturn Math.floor((value.length * 3) / 4) - paddingLength;\n}\n","import { useEffect, useEffectEvent, useState } from \"react\";\n\nimport { logError } from \"../utils\";\n\nimport { binaryToBlob, detectMimeType } from \"./binaryToBlob\";\n\nexport function useBinaryFile(bin: string | undefined) {\n\tconst [entry, setEntry] = useState<{ blob: Blob; mime: string } | null>(null);\n\tconst [error, setError] = useState<string | null>(null);\n\n\tconst updateEntry = useEffectEvent((data: { blob: Blob; mime: string } | null) => setEntry(data));\n\tconst updateError = useEffectEvent((error: string | null) => setError(error));\n\n\tuseEffect(() => {\n\t\tif (bin) {\n\t\t\ttry {\n\t\t\t\tconst mime = detectMimeType(undefined, bin);\n\t\t\t\tconst blob = binaryToBlob(bin, mime, true);\n\n\t\t\t\tupdateEntry({ blob, mime });\n\t\t\t\tupdateError(null);\n\t\t\t} catch (e) {\n\t\t\t\tlogError(e);\n\n\t\t\t\tupdateError(String(e));\n\t\t\t\tupdateEntry(null);\n\t\t\t}\n\t\t} else {\n\t\t\tupdateEntry(null);\n\t\t\tupdateError(null);\n\t\t}\n\t}, [bin]);\n\n\treturn { data: entry, error };\n}\n"],"mappings":"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"}

package/dist/file-system/fileSystemTypes.d.ts

@@ -0,0 +1,10 @@
+/** Определяет, какую существующую часть пути дополнительно проверить через Node.js realpath. */
+export type PathRealpathMode = "none" | "parent" | "target";
+/** Root принадлежит серверной конфигурации; сегменты обозначают только путь внутри него. */
+export type ResolvePathInsideRootOptions = Readonly<{
+    rootPath: string;
+    pathSegments: readonly string[];
+    /** По умолчанию проверяется существующий target, включая символические ссылки. */
+    realpathMode?: PathRealpathMode;
+}>;
+//# sourceMappingURL=fileSystemTypes.d.ts.map

package/dist/file-system/fileSystemTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileSystemTypes.d.ts","sourceRoot":"","sources":["../../src/file-system/fileSystemTypes.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D,4FAA4F;AAC5F,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,kFAAkF;IAClF,YAAY,CAAC,EAAE,gBAAgB,CAAC;CAChC,CAAC,CAAC"}

package/dist/file-system/index.d.ts

@@ -0,0 +1,4 @@
+export { type PathRealpathMode, type ResolvePathInsideRootOptions } from "./fileSystemTypes";
+export { isFileSystemNotFoundError } from "./isFileSystemNotFoundError";
+export { resolvePathInsideRoot } from "./resolvePathInsideRoot";
+//# sourceMappingURL=index.d.ts.map

package/dist/file-system/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/file-system/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/file-system/index.js

@@ -0,0 +1,37 @@
+import { i as e } from "../chunks/isRecord-DXDTW-jA.js";
+import { realpath as t } from "node:fs/promises";
+import { dirname as n, isAbsolute as r, relative as i, resolve as a, sep as o } from "node:path";
+//#region src/file-system/isFileSystemNotFoundError.ts
+function s(t) {
+	return e(t) ? t.code === "ENOENT" || t.code === "ENOTDIR" : !1;
+}
+//#endregion
+//#region src/file-system/resolvePathInsideRoot.ts
+function c(e) {
+	let t = e.trim();
+	if (!t) throw Error("Корневая папка хранилища не задана.");
+	return a(t);
+}
+function l(e, t) {
+	let n = i(e, t);
+	return n === "" || n !== ".." && !n.startsWith(`..${o}`) && !r(n);
+}
+async function u(e, r, i) {
+	let a;
+	try {
+		a = await t(e);
+	} catch (e) {
+		throw Error("Корневая папка хранилища недоступна.", { cause: e });
+	}
+	let o = i === "parent" ? n(r) : r, s = await t(o);
+	if (!l(a, s)) throw Error("Путь выходит за пределы корневой папки хранилища.");
+}
+async function d({ rootPath: e, pathSegments: t, realpathMode: n = "target" }) {
+	let r = c(e), i = a(r, ...t);
+	if (!l(r, i)) throw Error("Путь выходит за пределы корневой папки хранилища.");
+	return n !== "none" && await u(r, i, n), i;
+}
+//#endregion
+export { s as isFileSystemNotFoundError, d as resolvePathInsideRoot };
+
+//# sourceMappingURL=index.js.map

package/dist/file-system/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/file-system/isFileSystemNotFoundError.ts","../../src/file-system/resolvePathInsideRoot.ts"],"sourcesContent":["import { isRecord } from \"../validators\";\n\n/** Отличает отсутствующий путь от ошибок доступа и I/O, которые вызывающий код обязан обработать отдельно. */\nexport function isFileSystemNotFoundError(error: unknown): boolean {\n\tif (!isRecord(error)) return false;\n\treturn error.code === \"ENOENT\" || error.code === \"ENOTDIR\";\n}\n","import { type PathRealpathMode, type ResolvePathInsideRootOptions } from \"./fileSystemTypes\";\n\nimport { realpath } from \"node:fs/promises\";\nimport { dirname, isAbsolute, relative, resolve, sep } from \"node:path\";\n\nfunction resolveStorageRoot(rootPath: string): string {\n\tconst normalizedRootPath = rootPath.trim();\n\tif (!normalizedRootPath) {\n\t\tthrow new Error(\"Корневая папка хранилища не задана.\");\n\t}\n\treturn resolve(normalizedRootPath);\n}\n\nfunction isResolvedPathInsideRoot(rootPath: string, candidatePath: string): boolean {\n\tconst relativePath = relative(rootPath, candidatePath);\n\t// Проверяется сегмент родителя, а не префикс имени: '..metadata' является допустимым файлом внутри root.\n\treturn relativePath === \"\" || (relativePath !== \"..\" && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath));\n}\n\nasync function assertRealPathInsideRoot(\n\trootPath: string,\n\tcandidatePath: string,\n\trealpathMode: Exclude<PathRealpathMode, \"none\">\n): Promise<void> {\n\tlet realRootPath: string;\n\ttry {\n\t\trealRootPath = await realpath(rootPath);\n\t} catch (error) {\n\t\tthrow new Error(\"Корневая папка хранилища недоступна.\", { cause: error });\n\t}\n\tconst pathForRealCheck = realpathMode === \"parent\" ? dirname(candidatePath) : candidatePath;\n\tconst realCandidatePath = await realpath(pathForRealCheck);\n\tif (!isResolvedPathInsideRoot(realRootPath, realCandidatePath)) {\n\t\tthrow new Error(\"Путь выходит за пределы корневой папки хранилища.\");\n\t}\n}\n\n/**\n * Нормализует абсолютный путь и запрещает выход за доверенный root.\n * 'target' проверяет существующий файл, 'parent' — каталог перед созданием файла,\n * 'none' выполняет только лексическую проверку и не защищает от символических ссылок.\n * Проверка не открывает файл: защиту от смены пути между проверкой и I/O обеспечивает вызывающий код.\n */\nexport async function resolvePathInsideRoot({\n\trootPath,\n\tpathSegments,\n\trealpathMode = \"target\"\n}: ResolvePathInsideRootOptions): Promise<string> {\n\tconst resolvedRootPath = resolveStorageRoot(rootPath);\n\tconst resolvedCandidatePath = resolve(resolvedRootPath, ...pathSegments);\n\tif (!isResolvedPathInsideRoot(resolvedRootPath, resolvedCandidatePath)) {\n\t\tthrow new Error(\"Путь выходит за пределы корневой папки хранилища.\");\n\t}\n\tif (realpathMode !== \"none\") {\n\t\tawait assertRealPathInsideRoot(resolvedRootPath, resolvedCandidatePath, realpathMode);\n\t}\n\treturn resolvedCandidatePath;\n}\n"],"mappings":";;;;AAGA,SAAgB,EAA0B,GAAyB;CAElE,OADK,EAAS,CAAK,IACZ,EAAM,SAAS,YAAY,EAAM,SAAS,YADpB;AAE9B;;;ACDA,SAAS,EAAmB,GAA0B;CACrD,IAAM,IAAqB,EAAS,KAAK;CACzC,IAAI,CAAC,GACJ,MAAU,MAAM,qCAAqC;CAEtD,OAAO,EAAQ,CAAkB;AAClC;AAEA,SAAS,EAAyB,GAAkB,GAAgC;CACnF,IAAM,IAAe,EAAS,GAAU,CAAa;CAErD,OAAO,MAAiB,MAAO,MAAiB,QAAQ,CAAC,EAAa,WAAW,KAAK,GAAK,KAAK,CAAC,EAAW,CAAY;AACzH;AAEA,eAAe,EACd,GACA,GACA,GACgB;CAChB,IAAI;CACJ,IAAI;EACH,IAAe,MAAM,EAAS,CAAQ;CACvC,SAAS,GAAO;EACf,MAAU,MAAM,wCAAwC,EAAE,OAAO,EAAM,CAAC;CACzE;CACA,IAAM,IAAmB,MAAiB,WAAW,EAAQ,CAAa,IAAI,GACxE,IAAoB,MAAM,EAAS,CAAgB;CACzD,IAAI,CAAC,EAAyB,GAAc,CAAiB,GAC5D,MAAU,MAAM,mDAAmD;AAErE;AAQA,eAAsB,EAAsB,EAC3C,aACA,iBACA,kBAAe,YACkC;CACjD,IAAM,IAAmB,EAAmB,CAAQ,GAC9C,IAAwB,EAAQ,GAAkB,GAAG,CAAY;CACvE,IAAI,CAAC,EAAyB,GAAkB,CAAqB,GACpE,MAAU,MAAM,mDAAmD;CAKpE,OAHI,MAAiB,UACpB,MAAM,EAAyB,GAAkB,GAAuB,CAAY,GAE9E;AACR"}

package/dist/file-system/isFileSystemNotFoundError.d.ts

@@ -0,0 +1,3 @@
+/** Отличает отсутствующий путь от ошибок доступа и I/O, которые вызывающий код обязан обработать отдельно. */
+export declare function isFileSystemNotFoundError(error: unknown): boolean;
+//# sourceMappingURL=isFileSystemNotFoundError.d.ts.map

package/dist/file-system/isFileSystemNotFoundError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isFileSystemNotFoundError.d.ts","sourceRoot":"","sources":["../../src/file-system/isFileSystemNotFoundError.ts"],"names":[],"mappings":"AAEA,8GAA8G;AAC9G,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGjE"}

package/dist/file-system/resolvePathInsideRoot.d.ts

@@ -0,0 +1,9 @@
+import { type ResolvePathInsideRootOptions } from "./fileSystemTypes";
+/**
+ * Нормализует абсолютный путь и запрещает выход за доверенный root.
+ * 'target' проверяет существующий файл, 'parent' — каталог перед созданием файла,
+ * 'none' выполняет только лексическую проверку и не защищает от символических ссылок.
+ * Проверка не открывает файл: защиту от смены пути между проверкой и I/O обеспечивает вызывающий код.
+ */
+export declare function resolvePathInsideRoot({ rootPath, pathSegments, realpathMode }: ResolvePathInsideRootOptions): Promise<string>;
+//# sourceMappingURL=resolvePathInsideRoot.d.ts.map

package/dist/file-system/resolvePathInsideRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvePathInsideRoot.d.ts","sourceRoot":"","sources":["../../src/file-system/resolvePathInsideRoot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAqC7F;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,EAC3C,QAAQ,EACR,YAAY,EACZ,YAAuB,EACvB,EAAE,4BAA4B,GAAG,OAAO,CAAC,MAAM,CAAC,CAUhD"}

package/dist/virtualizer/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./useFetchNextPageEffect";
+export { useFetchNextPageEffect } from "./useFetchNextPageEffect";
+export { type UseFetchNextPageEffectOptions } from "./useFetchNextPageEffectTypes";
 //# sourceMappingURL=index.d.ts.map

package/dist/virtualizer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/virtualizer/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/virtualizer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,KAAK,6BAA6B,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/virtualizer/index.js

@@ -1,16 +1,28 @@
 import { useEffect as e, useRef as t } from "react";
 //#region src/virtualizer/useFetchNextPageEffect.ts
-function n({ virtualItems: n, currentItemsCount: r, fetchNextPage: i, hasNextPage: a }) {
-	let o = t(!1);
-	e(() => {
-		!n.length || !r || n[n.length - 1].index >= r - 1 && a && !o.current && (o.current = !0, i?.().finally(() => {
-			o.current = !1;
+function n({ virtualItems: n, currentItemsCount: r, fetchNextPage: i, hasNextPage: a, onError: o }) {
+	let s = t(!1), c = t(null), l = t(!1);
+	e(() => (l.current = !0, () => {
+		l.current = !1;
+	}), []), e(() => {
+		(!a || c.current !== r) && (c.current = null), !(!n.length || !r || !a || s.current || c.current === r) && n[n.length - 1].index >= r - 1 && (s.current = !0, Promise.resolve().then(i).then(() => {
+			s.current = !1;
+		}, async (e) => {
+			c.current = r;
+			try {
+				l.current && o ? await o(e) : console.error("Не удалось загрузить следующую страницу виртуализированного списка.", e);
+			} catch (t) {
+				console.error("Не удалось обработать ошибку дозагрузки виртуализированного списка.", e, t);
+			} finally {
+				s.current = !1;
+			}
 		}));
 	}, [
 		n,
 		r,
 		a,
-		i
+		i,
+		o
 	]);
 }
 //#endregion

package/dist/virtualizer/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\nimport { VirtualItem } from \"@tanstack/react-virtual\";\n\nexport function useFetchNextPageEffect({\n\tvirtualItems,\n\tcurrentItemsCount,\n\tfetchNextPage,\n\thasNextPage\n}: {\n\tvirtualItems: VirtualItem[];\n\tcurrentItemsCount: number;\n\thasNextPage: boolean;\n\tfetchNextPage: () => Promise<unknown>;\n}) {\n\tconst fetchingRef = useRef(false);\n\n\tuseEffect(() => {\n\t\tif (!virtualItems.length || !currentItemsCount) return;\n\t\tconst lastVirtual = virtualItems[virtualItems.length - 1];\n\n\t\tif (lastVirtual.index >= currentItemsCount - 1 && hasNextPage && !fetchingRef.current) {\n\t\t\tfetchingRef.current = true;\n\t\t\tfetchNextPage?.().finally(() => {\n\t\t\t\tfetchingRef.current = false;\n\t\t\t});\n\t\t}\n\t}, [virtualItems, currentItemsCount, hasNextPage, fetchNextPage]);\n}\n"],"mappings":";;AAIA,SAAgB,EAAuB,EACtC,iBACA,sBACA,kBACA,kBAME;CACF,IAAM,IAAc,EAAO,EAAK;CAEhC,QAAgB;EACX,CAAC,EAAa,UAAU,CAAC,KACT,EAAa,EAAa,SAAS,EAEnD,CAAY,SAAS,IAAoB,KAAK,KAAe,CAAC,EAAY,YAC7E,EAAY,UAAU,IACtB,IAAgB,CAAC,CAAC,cAAc;GAC/B,EAAY,UAAU;EACvB,CAAC;CAEH,GAAG;EAAC;EAAc;EAAmB;EAAa;CAAa,CAAC;AACjE"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"sourcesContent":["import { useEffect, useRef } from \"react\";\n\nimport { type UseFetchNextPageEffectOptions } from \"./useFetchNextPageEffectTypes\";\n\n/**\n * Достигнутый край запускает одну дозагрузку. Отказ не превращается в detached\n * rejection и не повторяется из-за новых virtual items при каждом scroll/render.\n */\nexport function useFetchNextPageEffect({\n\tvirtualItems,\n\tcurrentItemsCount,\n\tfetchNextPage,\n\thasNextPage,\n\tonError\n}: UseFetchNextPageEffectOptions): void {\n\tconst fetchingRef = useRef(false);\n\tconst failedItemsCountRef = useRef<number | null>(null);\n\tconst mountedRef = useRef(false);\n\n\tuseEffect(() => {\n\t\tmountedRef.current = true;\n\t\treturn () => {\n\t\t\t// Transport принадлежит caller и не отменяется; поздний отказ остаётся\n\t\t\t// диагностикой, но уже не вызывает callback размонтированного UI.\n\t\t\tmountedRef.current = false;\n\t\t};\n\t}, []);\n\n\tuseEffect(() => {\n\t\t// Новые данные либо явное выключение pagination разрешают следующую\n\t\t// попытку. Identity callback и видимого диапазона не являются retry.\n\t\tif (!hasNextPage || failedItemsCountRef.current !== currentItemsCount) failedItemsCountRef.current = null;\n\t\tif (\n\t\t\t!virtualItems.length ||\n\t\t\t!currentItemsCount ||\n\t\t\t!hasNextPage ||\n\t\t\tfetchingRef.current ||\n\t\t\tfailedItemsCountRef.current === currentItemsCount\n\t\t)\n\t\t\treturn;\n\t\tconst lastVirtual = virtualItems[virtualItems.length - 1];\n\n\t\tif (lastVirtual.index >= currentItemsCount - 1) {\n\t\t\tfetchingRef.current = true;\n\t\t\t// Начало через Promise охватывает и синхронный throw transport callback.\n\t\t\t// Обе ветки завершения обработаны: finally не создаёт второй rejected Promise.\n\t\t\tvoid Promise.resolve()\n\t\t\t\t.then(fetchNextPage)\n\t\t\t\t.then(\n\t\t\t\t\t() => {\n\t\t\t\t\t\tfetchingRef.current = false;\n\t\t\t\t\t},\n\t\t\t\t\tasync (error: unknown) => {\n\t\t\t\t\t\tfailedItemsCountRef.current = currentItemsCount;\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tif (mountedRef.current && onError) await onError(error);\n\t\t\t\t\t\t\telse console.error(\"Не удалось загрузить следующую страницу виртуализированного списка.\", error);\n\t\t\t\t\t\t} catch (reporterError: unknown) {\n\t\t\t\t\t\t\tconsole.error(\"Не удалось обработать ошибку дозагрузки виртуализированного списка.\", error, reporterError);\n\t\t\t\t\t\t} finally {\n\t\t\t\t\t\t\tfetchingRef.current = false;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t);\n\t\t}\n\t}, [virtualItems, currentItemsCount, hasNextPage, fetchNextPage, onError]);\n}\n"],"mappings":";;AAQA,SAAgB,EAAuB,EACtC,iBACA,sBACA,kBACA,gBACA,cACuC;CACvC,IAAM,IAAc,EAAO,EAAK,GAC1B,IAAsB,EAAsB,IAAI,GAChD,IAAa,EAAO,EAAK;CAW/B,AATA,SACC,EAAW,UAAU,UACR;EAGZ,EAAW,UAAU;CACtB,IACE,CAAC,CAAC,GAEL,QAAgB;EAGf,CAAI,CAAC,KAAe,EAAoB,YAAY,OAAmB,EAAoB,UAAU,OAEpG,GAAC,EAAa,UACd,CAAC,KACD,CAAC,KACD,EAAY,WACZ,EAAoB,YAAY,MAGb,EAAa,EAAa,SAAS,EAEnD,CAAY,SAAS,IAAoB,MAC5C,EAAY,UAAU,IAGtB,QAAa,QAAQ,CAAC,CACpB,KAAK,CAAa,CAAC,CACnB,WACM;GACL,EAAY,UAAU;EACvB,GACA,OAAO,MAAmB;GACzB,EAAoB,UAAU;GAC9B,IAAI;IACH,AAAI,EAAW,WAAW,IAAS,MAAM,EAAQ,CAAK,IACjD,QAAQ,MAAM,uEAAuE,CAAK;GAChG,SAAS,GAAwB;IAChC,QAAQ,MAAM,uEAAuE,GAAO,CAAa;GAC1G,UAAU;IACT,EAAY,UAAU;GACvB;EACD,CACD;CAEH,GAAG;EAAC;EAAc;EAAmB;EAAa;EAAe;CAAO,CAAC;AAC1E"}

package/dist/virtualizer/useFetchNextPageEffect.d.ts

@@ -1,8 +1,7 @@
-import { VirtualItem } from "@tanstack/react-virtual";
-export declare function useFetchNextPageEffect({ virtualItems, currentItemsCount, fetchNextPage, hasNextPage }: {
-    virtualItems: VirtualItem[];
-    currentItemsCount: number;
-    hasNextPage: boolean;
-    fetchNextPage: () => Promise<unknown>;
-}): void;
+import { type UseFetchNextPageEffectOptions } from "./useFetchNextPageEffectTypes";
+/**
+ * Достигнутый край запускает одну дозагрузку. Отказ не превращается в detached
+ * rejection и не повторяется из-за новых virtual items при каждом scroll/render.
+ */
+export declare function useFetchNextPageEffect({ virtualItems, currentItemsCount, fetchNextPage, hasNextPage, onError }: UseFetchNextPageEffectOptions): void;
 //# sourceMappingURL=useFetchNextPageEffect.d.ts.map

package/dist/virtualizer/useFetchNextPageEffect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFetchNextPageEffect.d.ts","sourceRoot":"","sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,wBAAgB,sBAAsB,CAAC,EACtC,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,EAAE;IACF,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,QAcA"}
+{"version":3,"file":"useFetchNextPageEffect.d.ts","sourceRoot":"","sources":["../../src/virtualizer/useFetchNextPageEffect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAEnF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,EACtC,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,OAAO,EACP,EAAE,6BAA6B,GAAG,IAAI,CAoDtC"}

package/dist/virtualizer/useFetchNextPageEffectTypes.d.ts

@@ -0,0 +1,11 @@
+import { type VirtualItem } from "@tanstack/react-virtual";
+/** Дозагрузка не владеет данными и retry: caller передаёт состояние своей пагинации. */
+export type UseFetchNextPageEffectOptions = Readonly<{
+    virtualItems: readonly VirtualItem[];
+    currentItemsCount: number;
+    hasNextPage: boolean;
+    fetchNextPage: () => Promise<unknown>;
+    /** Ошибка передаётся один раз; без callback остаётся явная console-диагностика. */
+    onError?: (error: unknown) => void | Promise<void>;
+}>;
+//# sourceMappingURL=useFetchNextPageEffectTypes.d.ts.map

package/dist/virtualizer/useFetchNextPageEffectTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetchNextPageEffectTypes.d.ts","sourceRoot":"","sources":["../../src/virtualizer/useFetchNextPageEffectTypes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,wFAAwF;AACxF,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACpD,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,mFAAmF;IACnF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ryuzaki13/react-foundation-lib",
-	"version": "2.15.0",
+	"version": "2.17.0",
 	"description": "Reusable React and TypeScript foundation utilities, hooks, and primitives.",
 	"license": "MIT",
 	"author": "Ryuzaki13",
@@ -97,6 +97,10 @@
 			"types": "./dist/file/index.d.ts",
 			"import": "./dist/file/index.js"
 		},
+		"./file-system": {
+			"types": "./dist/file-system/index.d.ts",
+			"import": "./dist/file-system/index.js"
+		},
 		"./fingerprint": {
 			"types": "./dist/fingerprint/index.d.ts",
 			"import": "./dist/fingerprint/index.js"

package/src/binary/README.mdx

@@ -4,7 +4,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 # Работа с бинарными данными
 
-Модуль `binary` преобразует строковое бинарное содержимое в браузерный `Blob`, определяет предполагаемый MIME-тип документа и предоставляет React hook для типового сценария «base64 → `{ blob, mime }`».
+Модуль `binary` преобразует строковое бинарное содержимое в браузерный `Blob`, определяет предполагаемый MIME-тип документа и предоставляет React hook для типового сценария «base64 → `{ blob, mime }`». Отдельная pure function `getBase64DecodedSize` проверяет стандартный Base64 payload и считает размер без декодирования в browser или server runtime.
 
 Основной сценарий:
 
@@ -20,6 +20,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 - [Назначение и границы модуля](#назначение-и-границы-модуля)
 - [Импорт](#импорт)
+- [`getBase64DecodedSize`](#getbase64decodedsize)
 - [Минимальные понятия](#минимальные-понятия)
 - [Как выбрать API](#как-выбрать-api)
 - [Быстрый старт](#быстрый-старт)
@@ -44,7 +45,8 @@ import { Meta } from "@storybook/addon-docs/blocks";
 - нормализует пробелы, URL-safe алфавит и отсутствующий base64 padding;
 - создаёт `Blob`;
 - предполагает MIME по имени файла, объявлению data URL или небольшой сигнатуре;
-- предоставляет React hook для base64-данных.
+- предоставляет React hook для base64-данных;
+- проверяет стандартную Base64-форму и считает размер без выделения decoded buffer через `getBase64DecodedSize`.
 
 ### Чего модуль не делает
 
@@ -75,7 +77,7 @@ import { Meta } from "@storybook/addon-docs/blocks";
 Импортируйте API только из опубликованного subpath `/binary`:
 
 ```ts
-import { binaryToBlob, detectMimeType, useBinaryFile } from "@ryuzaki13/react-foundation-lib/binary";
+import { binaryToBlob, detectMimeType, getBase64DecodedSize, useBinaryFile } from "@ryuzaki13/react-foundation-lib/binary";
 ```
 
 Корневой импорт пакета не поддерживается:
@@ -112,6 +114,27 @@ npm install react react-dom
 
 В тестовой или серверной среде эти Web APIs могут отсутствовать либо вести себя иначе. Наличие похожих globals в конкретной версии Node.js не превращает browser contract в гарантированный server API.
 
+`getBase64DecodedSize` использует только строки и числа. Эта функция подходит для client-safe или server request validation и не вызывает browser API, React hooks, `Buffer` или Node.js imports. Существующий barrel `/binary` по-прежнему экспортирует React hook, поэтому его peer-контракт сохраняется.
+
+## `getBase64DecodedSize`
+
+```ts
+function getBase64DecodedSize(value: string): number | null;
+
+getBase64DecodedSize("AA=="); // 1 байт
+getBase64DecodedSize("AAE="); // 2 байта
+getBase64DecodedSize("QUJD"); // 3 байта
+getBase64DecodedSize(""); // 0
+getBase64DecodedSize("AA"); // null: отсутствует padding
+getBase64DecodedSize("AAA\n"); // null: перенос строки недопустим
+```
+
+Принимается стандартный алфавит `A–Z`, `a–z`, `0–9`, `+`, `/`, длина должна быть кратна четырём. Один или два символа `=` допустимы только в конце; неверный алфавит, положение или количество padding возвращают `null`. Пустая строка является корректной формой с размером `0`; domain contract отдельно решает, разрешён ли пустой файл.
+
+Функция не нормализует whitespace, Base64URL, data URL или отсутствующий padding. Она проверяет форму и вычисляет количество decoded bytes, не декодируя содержимое и не проверяя canonical pad bits, MIME или формат файла. В отличие от browser `binaryToBlob`, это узкий API для проверки строгого transport payload до выделения decoded buffer. Ограничение длины входного HTTP body и лимит размера файла остаются у вызывающей boundary.
+
+Время работы — `O(n)` по длине строки, дополнительная память — `O(1)`. Тесты: [`getBase64DecodedSize.test.ts`](./getBase64DecodedSize.test.ts).
+
 ## Минимальные понятия
 
 ### Байт
@@ -1307,11 +1330,12 @@ npm run test -- src/binary/binaryToBlob.test.ts
 import { binaryToBlob, detectMimeType, useBinaryFile } from "@ryuzaki13/react-foundation-lib/binary";
 ```
 
-| API              | Вход                            | Результат         | Ошибка                                   |
-| ---------------- | ------------------------------- | ----------------- | ---------------------------------------- |
-| `binaryToBlob`   | Строка, MIME, base64/raw флаг   | Непустой `Blob`   | Выбрасывает `Error`/browser decode error |
-| `detectMimeType` | Filename и/или base64/data URL  | MIME string       | Не выбрасывает; fallback PDF             |
-| `useBinaryFile`  | Base64/data URL или `undefined` | `{ data, error }` | Логирует и возвращает строку ошибки      |
+| API                    | Вход                            | Результат         | Ошибка                                           |
+| ---------------------- | ------------------------------- | ----------------- | ------------------------------------------------ |
+| `binaryToBlob`         | Строка, MIME, base64/raw флаг   | Непустой `Blob`   | Выбрасывает `Error`/browser decode error         |
+| `getBase64DecodedSize` | Стандартный Base64 payload      | Количество байтов | `null` для неверной формы; `0` для пустой строки |
+| `detectMimeType`       | Filename и/или base64/data URL  | MIME string       | Не выбрасывает; fallback PDF                     |
+| `useBinaryFile`        | Base64/data URL или `undefined` | `{ data, error }` | Логирует и возвращает строку ошибки              |
 
 ### Defaults
 

package/src/file-system/README.mdx

@@ -0,0 +1,64 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Foundation Lib/API/File System" />
+
+# Пути внутри серверного файлового хранилища
+
+`@ryuzaki13/react-foundation-lib/file-system` — отдельный Node.js entrypoint для проверки путей перед серверным I/O. Он использует `node:fs/promises` и `node:path`; его нельзя импортировать в browser graph или изоморфный route loader.
+
+Модуль выделен из проверок хранилища современного приложения. Он не знает доменную сущность, пользователя, БД, environment variables или способ публикации файла. Browser API чтения выбранного `File` остаётся в отдельном `/file`.
+
+## Public API
+
+```ts
+import {
+	isFileSystemNotFoundError,
+	resolvePathInsideRoot,
+	type PathRealpathMode,
+	type ResolvePathInsideRootOptions
+} from "@ryuzaki13/react-foundation-lib/file-system";
+
+const options = {
+	rootPath: "/srv/private-files",
+	pathSegments: ["documents", "file.pdf"],
+	realpathMode: "parent"
+} satisfies ResolvePathInsideRootOptions;
+
+const filePath = await resolvePathInsideRoot(options);
+```
+
+`resolvePathInsideRoot(options)` возвращает `Promise<string>` с нормализованным абсолютным путём. Относительный `rootPath` разрешается от `process.cwd()`, внешние пробелы удаляются, пустая конфигурация отвергается. `pathSegments` принимает readonly-массив. Сам root считается допустимым target, а выход через `..`, абсолютный путь вне root или соседний каталог с похожим именем отвергается.
+
+| `PathRealpathMode`      | Назначение и условия                                                                                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `target` — по умолчанию | Root и target должны существовать. `realpath` проверяет, что фактический target после разрешения символических ссылок остаётся внутри фактического root.                      |
+| `parent`                | Root и непосредственный родитель target должны существовать. Режим нужен перед созданием нового файла; сам target может отсутствовать. Проверяется фактический путь родителя. |
+| `none`                  | Только лексическая нормализация и проверка границ. Root и target могут отсутствовать. Символические ссылки не проверяются.                                                    |
+
+Функция возвращает нормализованный исходный путь, а не заменяет его результатом `realpath`. Символическая ссылка внутри root разрешена, если проверяемый фактический путь остаётся внутри root; доверенный root тоже может быть символической ссылкой.
+
+## Ошибки и граница I/O
+
+Пустой root, недоступный root и выход за границы приводят к rejected promise. Ошибка доступа к root сохраняет исходную ошибку в `Error.cause`; ошибки `realpath` target или parent передаются вызывающему коду без замены.
+
+`isFileSystemNotFoundError(error: unknown): boolean` распознаёт `ENOENT` и `ENOTDIR`. Ошибки доступа, диска или произвольный текст с названием кода не считаются отсутствующим файлом:
+
+```ts
+try {
+	await resolvePathInsideRoot({ rootPath: "/srv/private-files", pathSegments: ["documents", "file.pdf"] });
+} catch (error) {
+	if (isFileSystemNotFoundError(error)) {
+		// Здесь вызывающий сценарий выбирает состояние отсутствующего файла.
+	} else {
+		throw error;
+	}
+}
+```
+
+Проверка пути не открывает файл, не создаёт каталог и не устанавливает filesystem lock. Между проверкой и I/O путь может измениться. Режим `parent` также не проверяет существующий target symlink. Вызывающий storage adapter выбирает безопасные open flags, контролирует владельца каталогов и выполняет фактическое чтение или запись.
+
+Загрузка байтов, checksum, MIME validation, staging, публикация, удаление, транзакции и компенсация принадлежат соответствующим владельцам. Этот модуль предоставляет только проверку границ пути и распознавание отсутствующего пути.
+
+## Проверки
+
+Тесты используют реальные временные каталоги и символические ссылки: относительный root, dot-сегменты, абсолютные пути, соседние каталоги, parent/target, недоступный root и системные ошибки. Type-test проверяет публичные сигнатуры и readonly-массив сегментов.

package/src/virtualizer/README.mdx

@@ -36,16 +36,18 @@ useFetchNextPageEffect({
 	virtualItems,
 	currentItemsCount,
 	fetchNextPage,
-	hasNextPage
+	hasNextPage,
+	onError
 });
 ```
 
-| Поле                | Значение                             |
-| ------------------- | ------------------------------------ |
-| `virtualItems`      | Текущий массив `VirtualItem[]`       |
-| `currentItemsCount` | Число реально загруженных data items |
-| `hasNextPage`       | Есть ли следующая server page        |
-| `fetchNextPage`     | Stable функция, возвращающая Promise |
+| Поле                | Значение                                                            |
+| ------------------- | ------------------------------------------------------------------- |
+| `virtualItems`      | Текущий массив `readonly VirtualItem[]`                             |
+| `currentItemsCount` | Число реально загруженных data items                                |
+| `hasNextPage`       | Есть ли следующая server page                                       |
+| `fetchNextPage`     | Stable функция, возвращающая Promise                                |
+| `onError`           | Необязательный callback `(error: unknown) => void \| Promise<void>` |
 
 Hook ничего не возвращает.
 
@@ -81,25 +83,41 @@ Trigger происходит строго на последнем загруже
 
 ## Защита от параллельного fetch
 
-Внутренний `useRef(false)` устанавливается до вызова и сбрасывается в `.finally()`:
+Внутренний single-flight ref устанавливается до вызова и сбрасывается после
+успеха либо завершения обработки ошибки:
 
 ```text
 idle ── trigger ──► fetchingRef=true
                        │
                  Promise pending
                        │
-             resolve или reject
+        resolve или завершение onError
                        ▼
                  fetchingRef=false
 ```
 
 Защита действует только внутри одного mounted hook instance. TanStack Query также должен владеть дедупликацией/network state.
 
-Если `fetchNextPage` отклоняет Promise, hook не добавляет `.catch`; rejection может стать unhandled. Передавайте функцию с принятой error policy или wrapper, который корректно обрабатывает ожидаемую ошибку.
+## Ошибки и повторная попытка
+
+Promise rejection и синхронный throw `fetchNextPage` передаются в `onError`
+один раз. Hook ожидает async callback; его собственный отказ также обрабатывается.
+Без `onError`, при отказе самого callback либо после unmount исходная ошибка
+остаётся в явной `console.error`-диагностике с контекстом дозагрузки. Hook не
+создаёт дополнительный unhandled Promise rejection и не решает, как показывать
+ошибку пользователю: это остаётся у владельца Query и UI.
+
+После отказа hook не пытается загрузить ту же страницу при каждом scroll/render.
+Неудачная попытка привязана к `currentItemsCount`: новое количество загруженных
+строк либо явное выключение `hasNextPage` и последующее включение разрешают новую
+попытку. Смена identity `fetchNextPage`, `onError` или `virtualItems` не является
+retry. Изменение данных без изменения количества само по себе latch не снимает;
+явная ручная retry-команда остаётся у владельца Query. Интервалов и собственной
+retry-policy в hook нет.
 
 ## Referential stability
 
-Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `fetchNextPage`.
+Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `fetchNextPage`, `onError`.
 
 - Используйте значение virtualizer как предусмотрено его API.
 - Не создавайте лишний async callback с новой identity без причины.
@@ -110,7 +128,9 @@ Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `
 
 Сам hook не читает `window`, но является React effect и не выполняет fetch во время server render. В browser effect запускается после commit.
 
-При unmount Promise не отменяется. Abort/cancel должен быть реализован query/transport owner. `fetchingRef` больше не влияет после удаления hook instance.
+При unmount Promise не отменяется. Abort/cancel должен быть реализован query/transport owner.
+Поздний отказ не вызывает `onError` размонтированного UI, но остаётся в явной
+console-диагностике. Уже начатый async `onError` не отменяется, его отказ не теряется.
 
 ## Типичные ошибки
 
@@ -118,17 +138,20 @@ Effect зависит от `virtualItems`, `currentItemsCount`, `hasNextPage`, `
 - Включить client-side sorting/filtering одной страницы при server-side модели.
 - Добавить фиктивный loader row в `currentItemsCount`.
 - Ожидать preload заранее — trigger находится на самом конце.
-- Передать rejecting Promise без error handling.
+- Ожидать, что hook сам покажет Query-ошибку или автоматически повторит failed page.
 - Выполнять fetch прямо в row render вместо effect.
 - Использовать изменяемый index как domain identity строки.
 
 ## API
 
 ```ts
-function useFetchNextPageEffect(args: {
-	virtualItems: VirtualItem[];
+type UseFetchNextPageEffectOptions = Readonly<{
+	virtualItems: readonly VirtualItem[];
 	currentItemsCount: number;
 	hasNextPage: boolean;
 	fetchNextPage: () => Promise<unknown>;
-}): void;
+	onError?: (error: unknown) => void | Promise<void>;
+}>;
+
+function useFetchNextPageEffect(options: UseFetchNextPageEffectOptions): void;
 ```