@ryuzaki13/react-foundation-ui 1.8.11 → 1.8.13

package/storybook-static/assets/README-_0Otw0eD.js

@@ -0,0 +1,448 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={a:`a`,code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation API/Adapters/Server Function`}),`
+`,(0,c.jsxs)(t.h1,{id:`server-function-adapters-через-ryuzaki13react-foundation-apiserver-fn`,children:[`Server-function adapters через `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/server-fn`})]}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль адаптирует функцию с публичной формой `,(0,c.jsx)(t.code,{children:`serverFn({ data })`}),` к query/mutation operation из `,(0,c.jsx)(t.a,{href:`../resource/README.mdx`,children:(0,c.jsx)(t.code,{children:`/resource`})}),`. Сам пакет не импортирует TanStack Start и не запускает сервер.`]}),`
+`,(0,c.jsx)(t.h2,{id:`модель`,children:`Модель`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`scope + args/input
+        │ buildData
+        ▼
+     { data }
+        │ serverFn или custom executor
+        ▼
+     response
+        │ optional transform
+        ▼
+ resource operation result
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Подходит любая async-функция такого контракта:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ServerFnTransport<TData, TResponse> = (
+	request: { data: TData }
+) => Promise<TResponse>;
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Название `,(0,c.jsx)(t.code,{children:`server-fn`}),` описывает типичный источник функции. Оно не гарантирует server-only выполнение и не создаёт security boundary.`]}),`
+`,(0,c.jsx)(t.p,{children:`Для начинающего разработчика:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`serverFn`}),` — transport function framework-а;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` — явный mapper application inputs в transport DTO;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`transform`}),` — mapper transport response в application result;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`resource operation — описание того, как generic `,(0,c.jsx)(t.code,{children:`/resource`}),` должен выполнить query/mutation.`]}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`React component
+    │ useResourceQuery/useResourceMutation
+    ▼
+resource descriptor
+    │ execute context
+    ▼
+server-fn adapter
+    │ { data }
+    ▼
+framework server function stub
+    │ network/server boundary framework-а
+    ▼
+server handler
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Этот package адаптирует только участок `,(0,c.jsx)(t.code,{children:`execute context → { data }`}),`. Он не реализует network protocol framework-а.`]}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	createServerFnMutationOperation,
+	createServerFnQueryOperation
+} from "@ryuzaki13/react-foundation-api/server-fn";
+
+import type {
+	ServerFnTransport,
+	ServerFnTransportExecutor,
+	ServerFnTransportExecutorContext,
+	ServerFnTransportRequest
+} from "@ryuzaki13/react-foundation-api/server-fn";
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Нужен `,(0,c.jsx)(t.code,{children:`@tanstack/react-query`}),`; созданные operations обычно подключаются через `,(0,c.jsx)(t.code,{children:`/resource`}),` или `,(0,c.jsx)(t.code,{children:`/persisted`}),` descriptor.`]}),`
+`,(0,c.jsx)(t.p,{children:`Пакет не имеет root import. Не импортируйте внутренний файл:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`// Правильно.
+import { createServerFnQueryOperation } from "@ryuzaki13/react-foundation-api/server-fn";
+
+// Неправильно.
+import { createServerFnQueryOperation } from "@ryuzaki13/react-foundation-api/src/server-fn/serverFn";
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`query-operation`,children:`Query operation`}),`
+`,(0,c.jsx)(t.p,{children:`Предположим, сгенерированная framework-функция принимает:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type LoadOrdersData = {
+	companyId: string;
+	search: string;
+};
+
+declare const loadOrdersServerFn: ServerFnTransport<
+	LoadOrdersData,
+	{ items: OrderDto[] }
+>;
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Adapter:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const searchOrdersOperation = createServerFnQueryOperation({
+	serverFn: loadOrdersServerFn,
+	buildData: (companyId: string, args: { search: string }) => ({
+		companyId,
+		search: args.search
+	}),
+	transform: (response) => response.items.map(mapOrderDto),
+	staleTime: 60_000,
+	gcTime: 5 * 60_000,
+	isEnabled: (companyId, args) => Boolean(companyId && args.search.trim())
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` получает валидный scope и query args. `,(0,c.jsx)(t.code,{children:`transform`}),` получает response и `,(0,c.jsx)(t.code,{children:`{ scope, args }`}),`; без transform result равен response.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Созданный объект соответствует `,(0,c.jsx)(t.code,{children:`ResourceQueryOperation`}),`:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`execute({ scope, args, client, signal })`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`isEnabled`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`staleTime`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[`optional `,(0,c.jsx)(t.code,{children:`gcTime`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-query-lifecycle`,children:`Полный query lifecycle`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`Resource проверяет scope/isEnabled
+          │
+          ▼
+operation.execute({ scope, args, client, signal })
+          │
+          ▼
+buildData(scope, args)
+          │
+          ▼
+executor(serverFn, { data }, { client, signal })
+          │
+          ▼
+server response
+          │
+          ├─ transform задан ──► transform(response, { scope, args })
+          └─ transform нет ────► response
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`buildData`}),` вызывается на каждом фактическом execute, а не при создании descriptor-а.`]}),`
+`,(0,c.jsx)(t.h3,{id:`scope-args-и-data--разные-вещи`,children:`Scope, args и data — разные вещи`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type Scope = string; // companyId
+type Args = { search: string; page: number };
+type Data = {
+	company: string;
+	query: string;
+	offset: number;
+};
+`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`buildData: (companyId, args) => ({
+	company: companyId,
+	query: args.search.trim(),
+	offset: args.page * 50
+})
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Не передавайте args как data автоматически: имена/форматы transport DTO могут отличаться, а scope часто должен попасть внутрь request.`}),`
+`,(0,c.jsx)(t.h3,{id:`isenabled`,children:(0,c.jsx)(t.code,{children:`isEnabled`})}),`
+`,(0,c.jsx)(t.p,{children:`Callback получает nullable scope, потому что hook может быть вызван до готовности route/form state:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isEnabled: (companyId, args) =>
+	Boolean(companyId && args.search.trim().length >= 2)
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Сам adapter просто сохраняет callback в operation. Проверку выполняет `,(0,c.jsx)(t.code,{children:`/resource`}),` при построении query options. Не вызывайте `,(0,c.jsx)(t.code,{children:`operation.execute`}),` вручную с invalid scope и не ожидайте, что `,(0,c.jsx)(t.code,{children:`isEnabled`}),` внутри остановит его.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`staletime-и-gctime`,children:[(0,c.jsx)(t.code,{children:`staleTime`}),` и `,(0,c.jsx)(t.code,{children:`gcTime`})]}),`
+`,(0,c.jsx)(t.p,{children:`Это hints TanStack Query lifecycle, а не transport timeout:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`staleTime`}),` — сколько snapshot считается fresh;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`gcTime`}),` — когда неактивный snapshot можно удалить;`]}),`
+`,(0,c.jsx)(t.li,{children:`они не прерывают network request;`}),`
+`,(0,c.jsx)(t.li,{children:`они не определяют server cache.`}),`
+`]}),`
+`,(0,c.jsx)(t.h3,{id:`transform-и-runtime-validation`,children:`Transform и runtime validation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`transform: (response, { scope, args }) => {
+	if (!response || !Array.isArray(response.items)) {
+		throw new Error("ServerFn response не содержит items");
+	}
+
+	return response.items.map((item) => mapOrderDto(item, scope, args));
+}
+`})}),`
+`,(0,c.jsx)(t.p,{children:`TypeScript generic не проверяет response framework-а. Если server/client могут иметь разные versions или endpoint получает внешние данные, выполняйте runtime validation.`}),`
+`,(0,c.jsxs)(t.p,{children:[`Ошибка `,(0,c.jsx)(t.code,{children:`buildData`}),`, executor или transform становится query error.`]}),`
+`,(0,c.jsx)(t.h2,{id:`mutation-operation`,children:`Mutation operation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`declare const saveOrderServerFn: ServerFnTransport<
+	{ companyId: string; order: SaveOrderDto },
+	{ order: OrderDto }
+>;
+
+const saveOrderOperation = createServerFnMutationOperation({
+	serverFn: saveOrderServerFn,
+	buildData: (companyId: string, input: SaveOrderInput) => ({
+		companyId,
+		order: mapSaveOrder(input)
+	}),
+	transform: (response) => mapOrderDto(response.order),
+	cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`transform`}),` получает `,(0,c.jsx)(t.code,{children:`{ scope, input }`}),`. `,(0,c.jsx)(t.code,{children:`cacheStrategy`}),` прикрепляется к operation и выполняется владельцем resource mutation после успешного ответа.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Mutation operation не имеет `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` в generic resource contract. Custom executor получает `,(0,c.jsx)(t.code,{children:`{ client }`}),` без signal.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-mutation-lifecycle`,children:`Полный mutation lifecycle`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`useResourceMutation(...).mutate(input)
+          │
+          ▼
+operation.execute({ scope, input, client })
+          │
+          ▼
+buildData(scope, input)
+          │
+          ▼
+executor(serverFn, { data }, { client })
+          │
+          ▼
+optional transform(response, { scope, input })
+          │
+          ▼
+resource применяет cacheStrategy
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Cache strategy выполняется только после успешного `,(0,c.jsx)(t.code,{children:`execute`}),`. Если `,(0,c.jsx)(t.code,{children:`transform`}),` бросил error, mutation считается failed и strategy не должна применяться.`]}),`
+`,(0,c.jsx)(t.h3,{id:`body-mapping-без-mutation-input-leakage`,children:`Body mapping без mutation input leakage`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type SaveOrderInput = {
+	localDraftId: string;
+	name: string;
+	amount: number;
+};
+
+buildData: (companyId, input) => ({
+	companyId,
+	order: {
+		name: input.name.trim(),
+		amount: input.amount
+	}
+})
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`localDraftId`}),` не уходит на server, если он не является частью transport contract.`]}),`
+`,(0,c.jsx)(t.h3,{id:`cache-strategy-выбирается-явно`,children:`Cache strategy выбирается явно`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`или точечный `,(0,c.jsx)(t.code,{children:`setQueryData`}),` strategy из `,(0,c.jsx)(t.code,{children:`/resource`}),`. Adapter только прикрепляет strategy к operation; выполняет её resource mutation layer.`]}),`
+`,(0,c.jsx)(t.p,{children:`Без strategy server mutation может успешно завершиться, но cached lists/details останутся stale.`}),`
+`,(0,c.jsx)(t.h2,{id:`подключение-к-resource-descriptor`,children:`Подключение к resource descriptor`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const ordersResource = createResourceDescriptor({
+	namespace: "sales",
+	resource: "orders",
+	operations: {
+		queries: { search: searchOrdersOperation },
+		mutations: { save: saveOrderOperation }
+	}
+});
+
+const query = useResourceQuery(
+	ordersResource,
+	"search",
+	companyId,
+	{ search }
+);
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`server-fn`}),` не экспортирует resource hooks повторно. Импортируйте их из `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-api/resource`}),`.`]}),`
+`,(0,c.jsx)(t.h3,{id:`полный-descriptor-example`,children:`Полный descriptor example`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	createResourceDescriptor,
+	useResourceMutation,
+	useResourceQuery
+} from "@ryuzaki13/react-foundation-api/resource";
+import {
+	createServerFnMutationOperation,
+	createServerFnQueryOperation
+} from "@ryuzaki13/react-foundation-api/server-fn";
+
+const ordersResource = createResourceDescriptor({
+	namespace: "sales",
+	resource: "orders",
+	operations: {
+		queries: {
+			search: createServerFnQueryOperation({
+				serverFn: loadOrdersServerFn,
+				buildData: (companyId: string, args: { search: string }) => ({
+					companyId,
+					search: args.search
+				}),
+				transform: (response) => response.items.map(mapOrderDto),
+				isEnabled: (scope, args) => Boolean(scope && args.search.trim())
+			})
+		},
+		mutations: {
+			save: createServerFnMutationOperation({
+				serverFn: saveOrderServerFn,
+				buildData: (companyId: string, input: SaveOrderInput) => ({
+					companyId,
+					order: mapSaveOrder(input)
+				}),
+				transform: (response) => mapOrderDto(response.order),
+				cacheStrategy: createInvalidateResourceScopeCacheStrategy()
+			})
+		}
+	}
+});
+
+function Orders({ companyId, search }: { companyId: string; search: string }) {
+	const orders = useResourceQuery(
+		ordersResource,
+		"search",
+		companyId,
+		{ search }
+	);
+
+	const save = useResourceMutation(
+		ordersResource,
+		"save",
+		companyId
+	);
+
+	// render loading/error/data and invoke save.mutate(input)
+}
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`custom-executor`,children:`Custom executor`}),`
+`,(0,c.jsx)(t.p,{children:`По умолчанию adapter вызывает только:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`serverFn({ data })
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`QueryClient`}),` и `,(0,c.jsx)(t.code,{children:`AbortSignal`}),` не передаются внутрь `,(0,c.jsx)(t.code,{children:`serverFn`}),`. Если transport/framework умеет использовать дополнительный context, задайте executor:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const executor: ServerFnTransportExecutor<Input, Output> = async (
+	serverFn,
+	request,
+	{ signal }
+) => {
+	if (signal?.aborted) throw signal.reason;
+	return serverFn(request);
+};
+
+const operation = createServerFnQueryOperation({
+	serverFn,
+	buildData,
+	executor
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Executor получает саму функцию, нормализованный request `,(0,c.jsx)(t.code,{children:`{ data }`}),` и `,(0,c.jsx)(t.code,{children:`{ client, signal? }`}),`. Он полезен для tracing, тестов и framework adapter-а. Не используйте его для бизнес-логики конкретной entity.`]}),`
+`,(0,c.jsx)(t.h3,{id:`default-executor`,children:`Default executor`}),`
+`,(0,c.jsxs)(t.p,{children:[`Без option `,(0,c.jsx)(t.code,{children:`executor`}),` фактически выполняется:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`await serverFn({ data });
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`client`}),` и `,(0,c.jsx)(t.code,{children:`signal`}),` доступны adapter layer, но не добавляются в transport data.`]}),`
+`,(0,c.jsx)(t.h3,{id:`tracing-executor`,children:`Tracing executor`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const tracingExecutor: ServerFnTransportExecutor<Input, Output> = async (
+	serverFn,
+	request,
+	context
+) => {
+	const startedAt = performance.now();
+
+	try {
+		if (context.signal?.aborted) {
+			throw context.signal.reason;
+		}
+
+		return await serverFn(request);
+	} finally {
+		console.debug("serverFn duration", performance.now() - startedAt);
+	}
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не логируйте `,(0,c.jsx)(t.code,{children:`request.data`}),` целиком: он может содержать personal/auth-sensitive fields.`]}),`
+`,(0,c.jsx)(t.h3,{id:`test-executor`,children:`Test executor`}),`
+`,(0,c.jsx)(t.p,{children:`Custom executor позволяет проверить request без real framework runtime:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const executor = vi.fn(async (_serverFn, request) => ({
+	items: [{ id: request.data.companyId }]
+}));
+
+const operation = createServerFnQueryOperation({
+	serverFn: vi.fn(),
+	buildData: (scope: string, args: { search: string }) => ({
+		companyId: scope,
+		search: args.search
+	}),
+	executor
+});
+`})}),`
+`,(0,c.jsx)(t.h2,{id:`security-boundary`,children:`Security boundary`}),`
+`,(0,c.jsxs)(t.p,{children:[`Public client type `,(0,c.jsx)(t.code,{children:`{ data }`}),` не означает, что data доверена. Server handler обязан повторно выполнить:`]}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`authentication;`}),`
+`,(0,c.jsx)(t.li,{children:`authorization на scope/entity/action;`}),`
+`,(0,c.jsx)(t.li,{children:`runtime schema validation;`}),`
+`,(0,c.jsx)(t.li,{children:`ограничения размера/частоты;`}),`
+`,(0,c.jsx)(t.li,{children:`sanitization перед DB/HTML/logs;`}),`
+`,(0,c.jsx)(t.li,{children:`безопасную обработку errors.`}),`
+`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-text`,children:`TypeScript type на client ≠ проверенный server input
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Не передавайте secrets server-а в `,(0,c.jsx)(t.code,{children:`buildData`}),`: этот mapper выполняется на client side operation boundary.`]}),`
+`,(0,c.jsx)(t.h2,{id:`query-cache-и-server-cache`,children:`Query cache и server cache`}),`
+`,(0,c.jsx)(t.p,{children:`Resource query key владеет identity client snapshot. ServerFn/framework может дополнительно кэшировать server response, но это другой слой.`}),`
+`,(0,c.jsx)(t.p,{children:`После mutation:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`resource cache strategy синхронизирует QueryClient;`}),`
+`,(0,c.jsx)(t.li,{children:`server-side invalidation управляется framework/backend;`}),`
+`,(0,c.jsx)(t.li,{children:`одно не заменяет другое.`}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`тестирование`,children:`Тестирование`}),`
+`,(0,c.jsx)(t.h3,{id:`query-operation-1`,children:`Query operation`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`it("строит { data } и преобразует response", async () => {
+	const serverFn = vi.fn(async ({ data }) => ({
+		items: [{ id: data.companyId }]
+	}));
+
+	const operation = createServerFnQueryOperation({
+		serverFn,
+		buildData: (scope: string, args: { search: string }) => ({
+			companyId: scope,
+			search: args.search
+		}),
+		transform: (response) => response.items
+	});
+
+	const result = await operation.execute({
+		scope: "1000",
+		args: { search: "test" },
+		client: queryClient,
+		signal: new AbortController().signal
+	});
+
+	expect(serverFn).toHaveBeenCalledWith({
+		data: { companyId: "1000", search: "test" }
+	});
+	expect(result).toEqual([{ id: "1000" }]);
+});
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Проверяйте:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`buildData получает scope и args/input;`}),`
+`,(0,c.jsxs)(t.li,{children:[`serverFn получает ровно `,(0,c.jsx)(t.code,{children:`{ data }`}),`;`]}),`
+`,(0,c.jsx)(t.li,{children:`transform context правильный;`}),`
+`,(0,c.jsx)(t.li,{children:`без transform response возвращается как есть;`}),`
+`,(0,c.jsx)(t.li,{children:`query executor видит signal;`}),`
+`,(0,c.jsx)(t.li,{children:`mutation executor не получает signal;`}),`
+`,(0,c.jsx)(t.li,{children:`errors mapper/executor/transform пробрасываются;`}),`
+`,(0,c.jsx)(t.li,{children:`cache strategy прикреплена к mutation operation;`}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`isEnabled`}),`, `,(0,c.jsx)(t.code,{children:`staleTime`}),`, `,(0,c.jsx)(t.code,{children:`gcTime`}),` сохранены в query operation.`]}),`
+`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`выполнять-serverfn-при-создании-operation`,children:`Выполнять serverFn при создании operation`}),`
+`,(0,c.jsx)(t.p,{children:`Factory должна получить функцию, а не Promise/result.`}),`
+`,(0,c.jsx)(t.h3,{id:`смешивать-transport-dto-и-domain-model`,children:`Смешивать transport DTO и domain model`}),`
+`,(0,c.jsxs)(t.p,{children:[`Используйте `,(0,c.jsx)(t.code,{children:`buildData`}),` и `,(0,c.jsx)(t.code,{children:`transform`}),` как явные boundaries.`]}),`
+`,(0,c.jsx)(t.h3,{id:`хранить-бизнес-логику-в-generic-executor`,children:`Хранить бизнес-логику в generic executor`}),`
+`,(0,c.jsx)(t.p,{children:`Executor — infrastructure wrapper. Entity mapping принадлежит operation/owner entity.`}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-cache-update-без-strategy`,children:`Ожидать cache update без strategy`}),`
+`,(0,c.jsx)(t.p,{children:`Mutation operation сама не угадывает затронутые queries.`}),`
+`,(0,c.jsxs)(t.h3,{id:`передавать-signal-внутрь--data-`,children:[`Передавать signal внутрь `,(0,c.jsx)(t.code,{children:`{ data }`})]}),`
+`,(0,c.jsx)(t.p,{children:`AbortSignal не сериализуемый business payload. Используйте executor/framework capability.`}),`
+`,(0,c.jsx)(t.h2,{id:`типичные-ошибки`,children:`Типичные ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`передавать-args-напрямую`,children:`Передавать args напрямую`}),`
+`,(0,c.jsxs)(t.p,{children:[`Неверно предполагать, что query args автоматически становятся data. Их явно преобразует `,(0,c.jsx)(t.code,{children:`buildData`}),`, потому что scope/args и transport DTO — разные контракты.`]}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-автоматическую-отмену`,children:`Ожидать автоматическую отмену`}),`
+`,(0,c.jsxs)(t.p,{children:[`Default executor не передаёт signal в функцию, поскольку её публичный contract содержит только `,(0,c.jsx)(t.code,{children:`{ data }`}),`. Отмена TanStack Query остановит дальнейшее использование результата на уровне query, но transport должен поддерживать abort отдельно.`]}),`
+`,(0,c.jsx)(t.h3,{id:`считать-функцию-доверенной`,children:`Считать функцию доверенной`}),`
+`,(0,c.jsx)(t.p,{children:`Если функция вызывается из browser bundle, её input контролирует пользователь. Backend обязан повторно проверить authentication, authorization и payload schema.`}),`
+`,(0,c.jsx)(t.h3,{id:`использовать-без-descriptor-а`,children:`Использовать без descriptor-а`}),`
+`,(0,c.jsxs)(t.p,{children:[`Factory возвращает operation, а не готовый React hook. Подключите её к resource/persisted descriptor или вызовите `,(0,c.jsx)(t.code,{children:`execute`}),` через корректный orchestration layer.`]}),`
+`,(0,c.jsx)(t.h2,{id:`faq`,children:`FAQ`}),`
+`,(0,c.jsx)(t.h3,{id:`обязательно-ли-использовать-tanstack-start`,children:`Обязательно ли использовать TanStack Start?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Нет. Подходит любая async function с contract `,(0,c.jsx)(t.code,{children:`({ data }) => Promise<response>`}),`.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`где-выполняется-builddata`,children:[`Где выполняется `,(0,c.jsx)(t.code,{children:`buildData`}),`?`]}),`
+`,(0,c.jsx)(t.p,{children:`На стороне, где выполняется resource operation, обычно в client bundle.`}),`
+`,(0,c.jsx)(t.h3,{id:`передаётся-ли-queryclient-в-serverfn`,children:`Передаётся ли QueryClient в serverFn?`}),`
+`,(0,c.jsx)(t.p,{children:`Нет. Только custom executor получает QueryClient как infrastructure context.`}),`
+`,(0,c.jsx)(t.h3,{id:`работает-ли-query-cancellation`,children:`Работает ли query cancellation?`}),`
+`,(0,c.jsx)(t.p,{children:`Signal доходит до executor. Default serverFn contract его не использует; реальный abort зависит от framework/custom executor.`}),`
+`,(0,c.jsx)(t.h3,{id:`почему-mutation-не-получает-signal`,children:`Почему mutation не получает signal?`}),`
+`,(0,c.jsxs)(t.p,{children:[`Таков generic `,(0,c.jsx)(t.code,{children:`ResourceMutationOperation`}),` contract. Если нужен abort, проектируйте отдельный controlled transport boundary.`]}),`
+`,(0,c.jsx)(t.h3,{id:`можно-ли-вернуть-domain-model-из-transform`,children:`Можно ли вернуть domain model из transform?`}),`
+`,(0,c.jsx)(t.p,{children:`Да. Generic result type будет выведен из transform.`}),`
+`,(0,c.jsx)(t.h2,{id:`полный-api`,children:`Полный API`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Export`}),(0,c.jsx)(t.th,{children:`Назначение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createServerFnQueryOperation`})}),(0,c.jsx)(t.td,{children:`Создаёт read operation, optional transform/lifetime/isEnabled`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`createServerFnMutationOperation`})}),(0,c.jsx)(t.td,{children:`Создаёт write operation, optional transform/cache strategy`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransport`})}),(0,c.jsxs)(t.td,{children:[`Контракт функции `,(0,c.jsx)(t.code,{children:`(request) => Promise`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportRequest`})}),(0,c.jsxs)(t.td,{children:[`Обёртка `,(0,c.jsx)(t.code,{children:`{ data }`})]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportExecutor`})}),(0,c.jsx)(t.td,{children:`Контракт custom execution`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ServerFnTransportExecutorContext`})}),(0,c.jsxs)(t.td,{children:[(0,c.jsx)(t.code,{children:`QueryClient`}),` и optional signal`]})]})]})]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};

package/storybook-static/assets/README-aw2Xu9xu.js

@@ -0,0 +1,158 @@
+import{n as e}from"./rolldown-runtime-DkW27tQK.js";import{n as t}from"./iframe-o7sH2IXC.js";import{i as n,r}from"./react-Bl2r1tuC.js";import{l as i,m as a}from"./blocks-BY40djCc.js";function o(e){let t={code:`code`,h1:`h1`,h2:`h2`,h3:`h3`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,table:`table`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,...n(),...e.components};return(0,c.jsxs)(c.Fragment,{children:[(0,c.jsx)(i,{title:`Foundation Lib/Browser/Three Scene`}),`
+`,(0,c.jsx)(t.h1,{id:`three-scene`,children:`Three Scene`}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль `,(0,c.jsx)(t.code,{children:`@ryuzaki13/react-foundation-lib/three-scene`}),` проверяет, можно ли безопасно показывать необязательную Three.js/WebGL-сцену, и помогает отключить её до конца браузерной сессии.`]}),`
+`,(0,c.jsx)(t.p,{children:`Модуль не импортирует Three.js, не создаёт renderer и не управляет canvas. Его задача — принять раннее решение: загружать тяжёлую 3D-сцену или показать облегчённую альтернативу.`}),`
+`,(0,c.jsx)(t.h2,{id:`когда-использовать`,children:`Когда использовать`}),`
+`,(0,c.jsx)(t.p,{children:`Подходит для декоративных и дополнительных сцен:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsx)(t.li,{children:`3D-фон страницы;`}),`
+`,(0,c.jsx)(t.li,{children:`визуализация, у которой есть обычная HTML-альтернатива;`}),`
+`,(0,c.jsx)(t.li,{children:`lazy import Three.js только на поддерживаемых устройствах;`}),`
+`,(0,c.jsx)(t.li,{children:`отключение повторных неудачных попыток WebGL в пределах вкладки.`}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`Для критически важного бизнес-сценария одной проверки поддержки недостаточно: renderer всё равно может завершиться ошибкой позже, например из-за потери контекста или нехватки памяти.`}),`
+`,(0,c.jsx)(t.h2,{id:`импорт`,children:`Импорт`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`import {
+	disableThreeSceneForSession,
+	isThreeSceneDisabledForSession,
+	isThreeSceneSupported,
+	threeSceneDefaultDisabledStorageKey,
+	useThreeSceneAvailability,
+	type ThreeSceneAvailability
+} from "@ryuzaki13/react-foundation-lib/three-scene";
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Для hook нужен React. Остальные функции работают напрямую с браузерными API.`}),`
+`,(0,c.jsx)(t.h2,{id:`быстрый-старт-с-react`,children:`Быстрый старт с React`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`import { lazy, Suspense } from "react";
+import { useThreeSceneAvailability } from "@ryuzaki13/react-foundation-lib/three-scene";
+
+const Scene = lazy(() => import("./Scene"));
+
+export function HeroVisual() {
+	const availability = useThreeSceneAvailability({
+		webGLVersion: "webgl2",
+		disableWhenReducedMotion: true
+	});
+
+	if (availability.status !== "available") {
+		return <img src="/hero.webp" alt="" />;
+	}
+
+	return (
+		<Suspense fallback={<img src="/hero.webp" alt="" />}>
+			<Scene />
+		</Suspense>
+	);
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`На первом клиентском рендере hook тоже возвращает `,(0,c.jsx)(t.code,{children:`unavailable/ssr`}),`. Проверка происходит в effect после hydration. Это сохраняет одинаковую начальную HTML-разметку на сервере и клиенте.`]}),`
+`,(0,c.jsx)(t.h2,{id:`модель-состояния`,children:`Модель состояния`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type ThreeSceneAvailabilityStatus = "pending" | "available" | "unavailable";
+
+type ThreeSceneUnavailableReason = "ssr" | "sessionDisabled" | "reducedMotion" | "webglUnsupported";
+
+type ThreeSceneAvailability = {
+	readonly status: ThreeSceneAvailabilityStatus;
+	readonly reason?: ThreeSceneUnavailableReason;
+};
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Текущий hook фактически возвращает `,(0,c.jsx)(t.code,{children:`available`}),` или `,(0,c.jsx)(t.code,{children:`unavailable`}),`; начальное состояние — `,(0,c.jsx)(t.code,{children:`unavailable`}),` с причиной `,(0,c.jsx)(t.code,{children:`ssr`}),`. Значение `,(0,c.jsx)(t.code,{children:`pending`}),` входит в общий тип, но hook сейчас его не устанавливает.`]}),`
+`,(0,c.jsx)(t.p,{children:`Причины:`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Причина`}),(0,c.jsx)(t.th,{children:`Значение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ssr`})}),(0,c.jsx)(t.td,{children:`Проверка ещё не выполнена в браузере либо код работает без DOM`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`sessionDisabled`})}),(0,c.jsxs)(t.td,{children:[`Сцена отключена в `,(0,c.jsx)(t.code,{children:`sessionStorage`}),` текущей вкладки`]})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`reducedMotion`})}),(0,c.jsx)(t.td,{children:`Пользователь предпочитает уменьшенное движение, а соответствующая опция включена`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`webglUnsupported`})}),(0,c.jsx)(t.td,{children:`Не удалось создать требуемый WebGL-контекст`})]})]})]}),`
+`,(0,c.jsx)(t.h2,{id:`isthreescenesupportedoptions`,children:(0,c.jsx)(t.code,{children:`isThreeSceneSupported(options?)`})}),`
+`,(0,c.jsx)(t.p,{children:`Синхронно проверяет создание WebGL-контекста на временном canvas.`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`isThreeSceneSupported(); // проверяет только WebGL 2
+isThreeSceneSupported({ webGLVersion: "webgl2" });
+isThreeSceneSupported({ webGLVersion: "webgl" });
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Доступны два режима:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`webgl2`}),` — принимает только контекст `,(0,c.jsx)(t.code,{children:`webgl2`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`webgl`}),` — пробует `,(0,c.jsx)(t.code,{children:`webgl2`}),`, затем `,(0,c.jsx)(t.code,{children:`webgl`}),` и `,(0,c.jsx)(t.code,{children:`experimental-webgl`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если контекст создан, функция по возможности вызывает расширение `,(0,c.jsx)(t.code,{children:`WEBGL_lose_context`}),`, чтобы освободить временный ресурс. При отсутствии `,(0,c.jsx)(t.code,{children:`document`}),`, ошибке браузера или невозможности создать контекст возвращается `,(0,c.jsx)(t.code,{children:`false`}),`.`]}),`
+`,(0,c.jsx)(t.p,{children:`Положительный результат означает только базовую поддержку контекста. Он не гарантирует нужные extensions, производительность GPU, объём памяти или успешную загрузку конкретной сцены.`}),`
+`,(0,c.jsx)(t.h2,{id:`отключение-на-время-сессии`,children:`Отключение на время сессии`}),`
+`,(0,c.jsx)(t.h3,{id:`ключ-по-умолчанию`,children:`Ключ по умолчанию`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:"threeSceneDefaultDisabledStorageKey;\n// `${__APP_ID__}:three-scene:disabled`\n"})}),`
+`,(0,c.jsxs)(t.p,{children:[`Пакет ожидает, что сборка приложения определит compile-time константу `,(0,c.jsx)(t.code,{children:`__APP_ID__`}),`. Она отделяет данные разных приложений на одном origin.`]}),`
+`,(0,c.jsx)(t.h3,{id:`disablethreesceneforsessionstoragekey`,children:(0,c.jsx)(t.code,{children:`disableThreeSceneForSession(storageKey?)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Записывает строку `,(0,c.jsx)(t.code,{children:`"1"`}),` в `,(0,c.jsx)(t.code,{children:`sessionStorage`}),`. Функция ничего не делает на сервере и молча игнорирует ошибки хранилища.`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`try {
+	await startScene();
+} catch (error) {
+	disableThreeSceneForSession();
+	showStaticFallback();
+}
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[(0,c.jsx)(t.code,{children:`sessionStorage`}),` живёт в пределах вкладки. Новая вкладка или новая сессия получает новую попытку.`]}),`
+`,(0,c.jsx)(t.h3,{id:`isthreescenedisabledforsessionstoragekey`,children:(0,c.jsx)(t.code,{children:`isThreeSceneDisabledForSession(storageKey?)`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Возвращает `,(0,c.jsx)(t.code,{children:`true`}),`, только если по ключу хранится точная строка `,(0,c.jsx)(t.code,{children:`"1"`}),`. На сервере возвращает `,(0,c.jsx)(t.code,{children:`true`}),`, чтобы сцена не пыталась стартовать без браузера. Если чтение storage бросает исключение, возвращается `,(0,c.jsx)(t.code,{children:`false`}),` — недоступность storage сама по себе не отключает WebGL.`]}),`
+`,(0,c.jsx)(t.h3,{id:`собственный-ключ`,children:`Собственный ключ`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`const storageKey = "dashboard:analytics-scene:disabled";
+
+disableThreeSceneForSession(storageKey);
+isThreeSceneDisabledForSession(storageKey);
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Одинаковый ключ нужно передавать и в hook.`}),`
+`,(0,c.jsx)(t.h2,{id:`usethreesceneavailabilityoptions`,children:(0,c.jsx)(t.code,{children:`useThreeSceneAvailability(options?)`})}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`type UseThreeSceneAvailabilityOptions = {
+	readonly disabledStorageKey?: string;
+	readonly disableWhenReducedMotion?: boolean;
+	readonly webGLVersion?: "webgl" | "webgl2";
+};
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Значения по умолчанию:`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`disabledStorageKey`}),` — `,(0,c.jsx)(t.code,{children:`threeSceneDefaultDisabledStorageKey`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`disableWhenReducedMotion`}),` — `,(0,c.jsx)(t.code,{children:`false`}),`;`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`webGLVersion`}),` — `,(0,c.jsx)(t.code,{children:`webgl2`}),`.`]}),`
+`]}),`
+`,(0,c.jsx)(t.p,{children:`После монтирования проверки выполняются в строгом порядке:`}),`
+`,(0,c.jsxs)(t.ol,{children:[`
+`,(0,c.jsx)(t.li,{children:`включённая политика reduced motion;`}),`
+`,(0,c.jsx)(t.li,{children:`флаг отключения в sessionStorage;`}),`
+`,(0,c.jsx)(t.li,{children:`поддержка требуемого WebGL;`}),`
+`,(0,c.jsxs)(t.li,{children:[`состояние `,(0,c.jsx)(t.code,{children:`available`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если WebGL не поддержан, hook автоматически записывает session-флаг. Следующие проверки в этой вкладке сразу получат `,(0,c.jsx)(t.code,{children:`sessionDisabled`}),` и не будут повторно создавать пробный контекст.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Hook повторяет вычисление, если меняются options или результат media query `,(0,c.jsx)(t.code,{children:`prefers-reduced-motion`}),`.`]}),`
+`,(0,c.jsx)(t.h2,{id:`reduced-motion`,children:`Reduced motion`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`const availability = useThreeSceneAvailability({
+	disableWhenReducedMotion: true
+});
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`При `,(0,c.jsx)(t.code,{children:`true`}),` сцена отключается для пользователя с настройкой `,(0,c.jsx)(t.code,{children:`prefers-reduced-motion: reduce`}),`. Сам session-флаг при этом не записывается: если пользователь изменит системную настройку, hook сможет пересчитать состояние.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Если 3D-сцена не содержит значимого движения или имеет собственный облегчённый режим, приложение может оставить опцию `,(0,c.jsx)(t.code,{children:`false`}),` и применить reduced-motion внутри renderer.`]}),`
+`,(0,c.jsx)(t.h2,{id:`восстановление-после-ошибки`,children:`Восстановление после ошибки`}),`
+`,(0,c.jsxs)(t.p,{children:[`Модуль не экспортирует `,(0,c.jsx)(t.code,{children:`enableThreeSceneForSession`}),`. Чтобы дать пользователю кнопку «Попробовать снова», приложение может удалить тот же ключ и перезагрузить/перемонтировать проверку:`]}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-ts`,children:`window.sessionStorage.removeItem(threeSceneDefaultDisabledStorageKey);
+window.location.reload();
+`})}),`
+`,(0,c.jsx)(t.p,{children:`Удаление storage и reload — решение приложения, потому что повторный запуск тяжёлой сцены должен быть явным пользовательским действием.`}),`
+`,(0,c.jsx)(t.h2,{id:`рекомендуемая-граница-загрузки`,children:`Рекомендуемая граница загрузки`}),`
+`,(0,c.jsx)(t.p,{children:`Не импортируйте тяжёлую сцену до проверки:`}),`
+`,(0,c.jsx)(t.pre,{children:(0,c.jsx)(t.code,{className:`language-tsx`,children:`// Хорошо: код сцены загружается отдельным chunk только при рендере Scene.
+const Scene = lazy(() => import("./Scene"));
+`})}),`
+`,(0,c.jsxs)(t.p,{children:[`Статический `,(0,c.jsx)(t.code,{children:`import Scene from "./Scene"`}),` загрузит Three.js даже если компонент затем вернёт fallback.`]}),`
+`,(0,c.jsxs)(t.p,{children:[`После `,(0,c.jsx)(t.code,{children:`available`}),` всё равно ставьте error boundary вокруг сцены. Runtime-ошибка renderer не меняет availability автоматически.`]}),`
+`,(0,c.jsx)(t.h2,{id:`ssr-и-hydration`,children:`SSR и hydration`}),`
+`,(0,c.jsxs)(t.ul,{children:[`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`isThreeSceneSupported`}),` на сервере возвращает `,(0,c.jsx)(t.code,{children:`false`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[(0,c.jsx)(t.code,{children:`isThreeSceneDisabledForSession`}),` на сервере возвращает `,(0,c.jsx)(t.code,{children:`true`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`hook начинает с детерминированного `,(0,c.jsx)(t.code,{children:`unavailable/ssr`}),`.`]}),`
+`,(0,c.jsxs)(t.li,{children:[`фактическая проверка выполняется только в `,(0,c.jsx)(t.code,{children:`useEffect`}),`.`]}),`
+`]}),`
+`,(0,c.jsxs)(t.p,{children:[`Поэтому сервер должен рендерить статический fallback. Не считайте начальную причину `,(0,c.jsx)(t.code,{children:`ssr`}),` окончательным отказом браузера.`]}),`
+`,(0,c.jsx)(t.h2,{id:`частые-ошибки`,children:`Частые ошибки`}),`
+`,(0,c.jsx)(t.h3,{id:`считать-webgl-проверку-benchmark`,children:`Считать WebGL-проверку benchmark`}),`
+`,(0,c.jsx)(t.p,{children:`Функция проверяет возможность создания контекста, но не измеряет FPS и не оценивает сложность сцены.`}),`
+`,(0,c.jsx)(t.h3,{id:`запускать-сцену-во-время-ssr`,children:`Запускать сцену во время SSR`}),`
+`,(0,c.jsxs)(t.p,{children:[`Canvas, sessionStorage и WebGL — browser-only API. Загружайте и запускайте renderer после `,(0,c.jsx)(t.code,{children:`availability.status === "available"`}),`.`]}),`
+`,(0,c.jsxs)(t.h3,{id:`не-определить-__app_id__`,children:[`Не определить `,(0,c.jsx)(t.code,{children:`__APP_ID__`})]}),`
+`,(0,c.jsx)(t.p,{children:`Значение участвует в ключе storage на этапе выполнения собранного кода. Сборщик потребителя должен заменить эту compile-time константу.`}),`
+`,(0,c.jsx)(t.h3,{id:`ожидать-автоматического-отключения-при-любой-runtime-ошибке`,children:`Ожидать автоматического отключения при любой runtime-ошибке`}),`
+`,(0,c.jsx)(t.p,{children:`Автоматический session-флаг ставится только при неуспешной первоначальной проверке WebGL. Ошибки загрузки ассетов и renderer приложение обрабатывает самостоятельно.`}),`
+`,(0,c.jsx)(t.h2,{id:`краткая-карта-api`,children:`Краткая карта API`}),`
+`,(0,c.jsxs)(t.table,{children:[(0,c.jsx)(t.thead,{children:(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.th,{children:`Экспорт`}),(0,c.jsx)(t.th,{children:`Назначение`})]})}),(0,c.jsxs)(t.tbody,{children:[(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`isThreeSceneSupported()`})}),(0,c.jsx)(t.td,{children:`Проверить возможность создать WebGL-контекст`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`disableThreeSceneForSession()`})}),(0,c.jsx)(t.td,{children:`Отключить сцену до конца сессии вкладки`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`isThreeSceneDisabledForSession()`})}),(0,c.jsx)(t.td,{children:`Прочитать session-флаг`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`threeSceneDefaultDisabledStorageKey`})}),(0,c.jsx)(t.td,{children:`Ключ storage с namespace приложения`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`useThreeSceneAvailability()`})}),(0,c.jsx)(t.td,{children:`Объединить WebGL, session и reduced-motion проверки в React`})]}),(0,c.jsxs)(t.tr,{children:[(0,c.jsx)(t.td,{children:(0,c.jsx)(t.code,{children:`ThreeSceneAvailability`})}),(0,c.jsx)(t.td,{children:`Тип результата availability`})]})]})]})]})}function s(e={}){let{wrapper:t}={...n(),...e.components};return t?(0,c.jsx)(t,{...e,children:(0,c.jsx)(o,{...e})}):o(e)}var c;function l(){return(l=e((()=>{c=t(),r(),a()})))()}l();export{s as default};