@primafuture/contrib-kit-react 1.0.0

package/src/resolved-contributions.ts

@@ -0,0 +1,895 @@
+import * as contribKitCore from "@primafuture/contrib-kit-core";
+import * as react from "react";
+
+import * as adapterConfiguration from "./internal/adapter-configuration.js";
+import * as adapterContext from "./internal/adapter-context.js";
+import * as adapterRegistryBridge from "./internal/adapter-registry-bridge.js";
+import * as adapterRegistryProtocol from "./internal/adapter-registry-protocol.js";
+import * as adapterScope from "./internal/adapter-scope.js";
+import * as outletCommitLease from "./internal/outlet-commit-lease.js";
+import * as outletInput from "./internal/outlet-input.js";
+import * as publicInputCapture from "./internal/public-input-capture.js";
+import * as resolvedContributionsQuery from "./internal/resolved-contributions-query.js";
+import * as reactAdapterDiagnostics from "./react-adapter-diagnostics.js";
+import * as reactAdapterError from "./react-adapter-error.js";
+import type * as reactExtensionPoint from "./react-extension-point.js";
+
+/** Empty klasifikace úspěšného resolved view. @public */
+export type ExtensionOutletEmptyReason = "noRegistrations" | "excludedByPolicy";
+
+/**
+ * Frozen synchronní výsledek jednoho render-time Core query.
+ *
+ * @public
+ */
+export type ResolvedContributionsState<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> =
+	| {
+		/** Rozlišuje úspěšný resolved view od failure. */
+		readonly status: "resolved";
+		/** Frozen normalized contributions v přesném Core pořadí. */
+		readonly contributions: readonly contribKitCore.RegisteredContribution<Point>[];
+		/** Důvod prázdného výsledku nebo null pro neprázdnou kolekci. */
+		readonly emptyReason: ExtensionOutletEmptyReason | null;
+	}
+	| {
+		/** Rozlišuje resolve failure od úspěšného empty view. */
+		readonly status: "failed";
+		/** Sdílená frozen prázdná tuple bez stale příspěvků. */
+		readonly contributions: readonly [];
+		/** Frozen bezpečný error event připravený pro UI i sink. */
+		readonly error: import("./react-adapter-diagnostics.js").ReactAdapterErrorEvent;
+	};
+
+/**
+ * Read-once vstup synchronního resolved hooku.
+ *
+ * @public
+ */
+export interface UseResolvedContributionsOptions<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> {
+	/** Point-specific context předaný Core resolution pipeline. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Exact canonical React extension point. */
+	readonly point: Point;
+	/** Lokální pure context projector; null zruší inherited projector. */
+	readonly projectContext?: (
+		(context: contribKitCore.ExtensionPointContext<Point>) => unknown
+	) | null | undefined;
+	/** Explicitní registry s předností před nearest providerem. */
+	readonly registry?: contribKitCore.ExtensionRegistry | undefined;
+	/** Lokální diagnostic sink; null obnoví bezpečný package fallback. */
+	readonly sink?: import("./react-adapter-diagnostics.js").ReactAdapterSink | null | undefined;
+}
+
+/**
+ * Frozen návrat synchronního resolved hooku.
+ *
+ * @public
+ */
+export interface UseResolvedContributionsResult<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+> {
+	/** Aktuální frozen resolved nebo failed stav. */
+	readonly state: ResolvedContributionsState<Point>;
+	/** Stabilní lokální invalidace bez Core commitu. */
+	refresh(): void;
+}
+
+/** Úspěšný read-once hook capture bez committed resource. */
+interface CapturedResolvedHook<Point extends reactExtensionPoint.AnyReactExtensionPoint> {
+	/** Rozlišuje validní capture od synchronní configuration chyby. */
+	readonly kind: "captured";
+	/** Exact point zachycený jako první známé options pole. */
+	readonly point: Point;
+	/** Exact context zachycený jako druhé známé options pole. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Fresh read-once protocol používaný render query. */
+	readonly protocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot;
+	/** Scope provideru nebo consumer-local scope mimo provider. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Provider nebo standalone generation vlastnící committed bridge. */
+	readonly generation: adapterScope.AdapterScopeGeneration;
+	/** Efektivní hook-local diagnostická konfigurace. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Zda committed lifecycle musí vlastnit consumer-local scope owner lease. */
+	readonly standalone: boolean;
+}
+
+/** Validní input, jehož registry již odmítá novou práci. */
+interface UnavailableResolvedHook<Point extends reactExtensionPoint.AnyReactExtensionPoint> {
+	/** Rozlišuje business failure od configuration throw. */
+	readonly kind: "unavailable";
+	/** Exact point potřebný pro bezpečný failed event. */
+	readonly point: Point;
+	/** Exact context dostupný případnému pure projector callbacku. */
+	readonly context: contribKitCore.ExtensionPointContext<Point>;
+	/** Efektivní config i bez vzniku external-store bindingu. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+	/** Scope-local diagnostic ledger. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Exact structural registry identity i po odmítnutí nové práce. */
+	readonly rawRegistry: object;
+	/** Provider generation, pokud unavailable query běží uvnitř provideru. */
+	readonly generation: adapterScope.AdapterScopeGeneration | undefined;
+	/** Přesná unavailable chyba z úplného protocol capture. */
+	readonly cause: reactAdapterError.ReactAdapterError;
+}
+
+/** Synchronní configuration failure držená do zavolání všech React hooks. */
+interface FailedResolvedHookCapture {
+	/** Rozlišuje throw větev od public failed state. */
+	readonly kind: "configurationFailure";
+	/** Přesný accessor nebo shape cause. */
+	readonly cause: unknown;
+}
+
+/** Jeden úplný hook capture výsledek. */
+type ResolvedHookCapture<Point extends reactExtensionPoint.AnyReactExtensionPoint> =
+	| CapturedResolvedHook<Point>
+	| UnavailableResolvedHook<Point>
+	| FailedResolvedHookCapture;
+
+/** Jeden read-once capture doplněný o consumer-specific čistá data. */
+interface ResolvedHookCaptureEnvelope<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+	Payload,
+> {
+	/** Registry/query capture sdílený public hookem a outletem. */
+	readonly captured: ResolvedHookCapture<Point>;
+	/** Čistý vstup konkrétního consumeru bez resource identity. */
+	readonly payload: Payload;
+}
+
+/** Capture factory volaná uvnitř stabilního pořadí React hooks. */
+type ResolvedHookCaptureFactory<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+	Payload,
+> = (
+	parent: adapterContext.AdapterContextValue | undefined,
+	localScope: adapterScope.AdapterScopeRuntime,
+	checkpoint: () => void,
+) => ResolvedHookCaptureEnvelope<Point, Payload>;
+
+/** Interní binding, který outletu zpřístupní přesně stejnou query a scope autoritu. */
+export interface OutletResolvedContributionsBinding<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+> {
+	/** Read-once outlet input použitý query i rendererem. */
+	readonly input: outletInput.CapturedOutletInput<Point>;
+	/** Public frozen resolved výsledek stejného render attemptu. */
+	readonly result: UseResolvedContributionsResult<Point>;
+	/** Opaque query attempt pro committed callback deduplikaci. */
+	readonly attempt: resolvedContributionsQuery.ResolvedQueryAttempt<Point>;
+	/** Scope-local owner bridge, diagnostik a commit leases. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Active generation nutná pro membership commit lease. */
+	readonly generation: adapterScope.AdapterScopeGeneration | undefined;
+	/** Exact raw registry reference tvořící první osu membership identity. */
+	readonly rawRegistry: object;
+	/** Ověří, že render attempt je právě committed a commandově current. */
+	readonly isCurrent: () => boolean;
+	/** Render-time authority checkpoint pro atomickou outlet projection. */
+	readonly checkpoint: () => void;
+	/** Commit-owned outlet identita, dostupná až po autoritativním mountu. */
+	readonly outletLease: outletCommitLease.OutletCommitLease | undefined;
+	/** True při serveru a prvním hydration renderu nad společným sentinel snapshotem. */
+	readonly serverSnapshot: boolean;
+}
+
+/** Stable external-store fallback pro configuration a unavailable větve. */
+const EMPTY_EXTERNAL_STORE: adapterScope.AdapterExternalStoreBinding = Object.freeze({
+	/** Resource-free subscribe vracející idempotentní no-op. */
+	subscribe(): contribKitCore.Unsubscribe {
+		/** Resource-free unsubscribe fallback. */
+		function unsubscribe(): void {
+			// Bez validního registry protocolu nevznikla žádná resource.
+		}
+		return unsubscribe;
+	},
+	/** Konstantní client snapshot bez host reads. */
+	getSnapshot(): adapterRegistryProtocol.AdapterRegistrySnapshotToken {
+		return "disposed:0";
+	},
+	/** Konstantní server snapshot sdílený s normálním bridgem. */
+	getServerSnapshot(): "contrib-kit-react:server" {
+		return "contrib-kit-react:server";
+	},
+	/** Neexistující bridge nemůže mít committed fault. */
+	readFault(): undefined {
+		return undefined;
+	},
+	/** Fallback pouze splní interní structural interface. */
+	readRegistryState(): "disposed" {
+		return "disposed";
+	},
+});
+
+/** Poslední referenčně stabilní external-store binding jednoho hooku. */
+interface ExternalStoreCache {
+	/** Scope identity owning bridge mapu. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Scope generation použitá při materializaci bindingu. */
+	readonly generation: adapterScope.AdapterScopeGeneration;
+	/** Raw registry reference; zachycené metody zůstávají v bindingu. */
+	readonly rawRegistry: object;
+	/** Registry ID chrání proti in-place identity změně structural fake. */
+	readonly registryId: string;
+	/** Exact canonical point reference. */
+	readonly point: contribKitCore.AnyExtensionPoint;
+	/** Pure nebo committed external-store closures. */
+	readonly binding: adapterScope.AdapterExternalStoreBinding;
+}
+
+/** Mutable control stabilní refresh closure bez stale render capture. */
+interface ResolvedHookControl {
+	/** Určuje, zda uniklý refresh ještě smí naplánovat React update. */
+	mounted: boolean;
+	/** Poslední committed scope. */
+	scope?: adapterScope.AdapterScopeRuntime;
+	/** Poslední committed generation pro lifecycle gate. */
+	generation?: adapterScope.AdapterScopeGeneration;
+	/** Standalone unavailable větev nemá aktivovatelnou generation. */
+	allowWithoutGeneration: boolean;
+}
+
+/** Committed authority jednoho render attemptu a command epochy. */
+interface CommittedResolvedAttempt {
+	/** Exact query attempt lokální právě committed renderu. */
+	readonly attempt: resolvedContributionsQuery.ResolvedQueryAttempt<reactExtensionPoint.AnyReactExtensionPoint>;
+	/** Command epoch platná při effect setupu. */
+	readonly commandEpoch: number;
+	/** Scope-local diagnostic ledger owning token. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Efektivní sink konfigurace daného attemptu. */
+	readonly configuration: adapterConfiguration.AdapterScopeConfiguration;
+}
+
+/** Vytvoří resource-free consumer-local scope jako lazy React state. */
+function createConsumerScope(): adapterScope.AdapterScopeRuntime {
+	return new adapterScope.AdapterScopeRuntime();
+}
+
+/** Ověří, že point může bezpečně sloužit jako exact WeakMap capability key. */
+function requirePointObject<Point extends reactExtensionPoint.AnyReactExtensionPoint>(
+	value: unknown,
+): Point {
+	if (typeof value !== "object" || value === null) {
+		throw new reactAdapterError.ReactAdapterError(
+			"REACT_INVALID_ARGUMENT",
+			"options.point must be a non-null object.",
+			{ details: { field: "options.point", phase: "configuration" } },
+		);
+	}
+	return value as Point;
+}
+
+/** Rozpozná unavailable query failure, která patří do public failed state. */
+function isUnavailableProtocolError(
+	cause: unknown,
+): cause is reactAdapterError.ReactAdapterError {
+	return cause instanceof reactAdapterError.ReactAdapterError
+		&& cause.code === "REACT_REGISTRY_UNAVAILABLE"
+		&& cause.details.phase === "resolve";
+}
+
+/**
+ * Zachytí structural registry protocol pro již read-once point/context/config vstup.
+ */
+function captureResolvedRegistry<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	point: Point,
+	context: contribKitCore.ExtensionPointContext<Point>,
+	registry: unknown,
+	configuration: adapterConfiguration.AdapterScopeConfiguration,
+	parent: adapterContext.AdapterContextValue | undefined,
+	localScope: adapterScope.AdapterScopeRuntime,
+	checkpoint: () => void,
+): ResolvedHookCapture<Point> {
+	const scope = parent?.scope ?? localScope;
+	let protocol: adapterRegistryProtocol.AdapterRegistryProtocolSnapshot;
+	try {
+		protocol = adapterRegistryProtocol.captureAdapterRegistryProtocol(registry, checkpoint);
+	} catch (cause: unknown) {
+		if (isUnavailableProtocolError(cause)) {
+			return Object.freeze({
+				kind: "unavailable",
+				point,
+				context,
+				configuration,
+				scope,
+				rawRegistry: registry as object,
+				generation: parent?.generation,
+				cause,
+			});
+		}
+		throw cause;
+	}
+
+	const generation = parent?.generation
+		?? adapterScope.createAdapterScopeGeneration(protocol, configuration);
+	return Object.freeze({
+		kind: "captured",
+		point,
+		context,
+		protocol,
+		scope,
+		generation,
+		configuration,
+		standalone: parent === undefined,
+	});
+}
+
+/** Zachytí hook options v přesném veřejném pořadí bez partial publication. */
+function captureResolvedHook<Point extends reactExtensionPoint.AnyReactExtensionPoint>(
+	options: UseResolvedContributionsOptions<Point>,
+	parent: adapterContext.AdapterContextValue | undefined,
+	localScope: adapterScope.AdapterScopeRuntime,
+	checkpoint: () => void,
+): ResolvedHookCapture<Point> {
+	const source = publicInputCapture.requireInputObject(options, "options");
+	const pointValue = publicInputCapture.readInputProperty(
+		source,
+		"point",
+		"options.point",
+		checkpoint,
+	);
+	const context = publicInputCapture.readInputProperty(
+		source,
+		"context",
+		"options.context",
+		checkpoint,
+	) as contribKitCore.ExtensionPointContext<Point>;
+	const registryValue = publicInputCapture.readInputProperty(
+		source,
+		"registry",
+		"options.registry",
+		checkpoint,
+	);
+	const sinkValue = publicInputCapture.readInputProperty(
+		source,
+		"sink",
+		"options.sink",
+		checkpoint,
+	);
+	const projectContextValue = publicInputCapture.readInputProperty(
+		source,
+		"projectContext",
+		"options.projectContext",
+		checkpoint,
+	);
+	const point = requirePointObject<Point>(pointValue);
+	const patch = adapterConfiguration.captureAdapterConfigurationPatch(
+		sinkValue,
+		undefined,
+		projectContextValue,
+		checkpoint,
+	);
+	const configuration = adapterConfiguration.resolveAdapterScopeConfiguration(
+		parent?.generation.configuration,
+		patch,
+	);
+	const registry = adapterConfiguration.resolveAdapterRegistryInput(
+		registryValue,
+		parent?.generation.defaultProtocol.rawRegistry,
+	);
+	return captureResolvedRegistry(
+		point,
+		context,
+		registry,
+		configuration,
+		parent,
+		localScope,
+		checkpoint,
+	);
+}
+
+/** Zachytí outlet props jednou a připraví query nad stejným config/scope vstupem. */
+function captureOutletResolvedHook<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	props: object,
+	parent: adapterContext.AdapterContextValue | undefined,
+	localScope: adapterScope.AdapterScopeRuntime,
+	checkpoint: () => void,
+): ResolvedHookCaptureEnvelope<Point, outletInput.CapturedOutletInput<Point>> {
+	const input = outletInput.captureOutletInput<Point>(
+		props,
+		parent?.generation.defaultProtocol.rawRegistry,
+		parent?.generation.configuration,
+		checkpoint,
+	);
+	const captured = captureResolvedRegistry(
+		input.point,
+		input.context,
+		input.registry,
+		input.configuration,
+		parent,
+		localScope,
+		checkpoint,
+	);
+	return Object.freeze({ captured, payload: input });
+}
+
+/** Vrátí stabilní binding a zachová první committed method capture bridge. */
+function resolveExternalStoreBinding(
+	captured: CapturedResolvedHook<reactExtensionPoint.AnyReactExtensionPoint>,
+	cacheRef: react.MutableRefObject<ExternalStoreCache | undefined>,
+): adapterScope.AdapterExternalStoreBinding {
+	const cached = cacheRef.current;
+	if (cached !== undefined
+		&& cached.scope === captured.scope
+		&& cached.rawRegistry === captured.protocol.rawRegistry
+		&& cached.registryId === captured.protocol.registryId
+		&& cached.point === captured.point
+		&& adapterScope.isSameAdapterScopeGeneration(cached.generation, captured.generation)) {
+		return cached.binding;
+	}
+
+	const binding = captured.scope.createExternalStore(
+		captured.generation,
+		captured.protocol,
+		captured.point,
+	);
+	cacheRef.current = Object.freeze({
+		scope: captured.scope,
+		generation: captured.generation,
+		rawRegistry: captured.protocol.rawRegistry,
+		registryId: captured.protocol.registryId,
+		point: captured.point,
+		binding,
+	});
+	return binding;
+}
+
+/** Ověří committed autoritu po každém sink callbacku. */
+function isCommittedAttemptCurrent(
+	authority: CommittedResolvedAttempt,
+	committedRef: react.MutableRefObject<CommittedResolvedAttempt | undefined>,
+	commandEpochRef: react.MutableRefObject<number>,
+): boolean {
+	return committedRef.current === authority
+		&& commandEpochRef.current === authority.commandEpoch;
+}
+
+/** Výsledek společného hook enginu včetně outlet-only committed autority. */
+interface ResolvedHookEngineResult<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+	Payload,
+> {
+	/** Consumer-specific read-once payload. */
+	readonly payload: Payload;
+	/** Public frozen result sdílený hookem i outletem. */
+	readonly result: UseResolvedContributionsResult<Point>;
+	/** Exact query attempt current renderu. */
+	readonly attempt: resolvedContributionsQuery.ResolvedQueryAttempt<Point>;
+	/** Scope owning bridge a committed diagnostics. */
+	readonly scope: adapterScope.AdapterScopeRuntime;
+	/** Current generation; unavailable standalone capture ji nemá. */
+	readonly generation: adapterScope.AdapterScopeGeneration | undefined;
+	/** Exact raw registry reference pro membership identity. */
+	readonly rawRegistry: object;
+	/** Committed-attempt authority probe pro následné outlet effecty. */
+	readonly isCurrent: () => boolean;
+	/** Current render authority probe bez committed side effectu. */
+	readonly checkpoint: () => void;
+	/** Optional commit-owned outlet lease sdílená všemi memberships. */
+	readonly outletLease: outletCommitLease.OutletCommitLease | undefined;
+	/** True pouze pro server nebo první hydration render nad konstantním snapshotem. */
+	readonly serverSnapshot: boolean;
+}
+
+/** Optional engine požadavek na commit-owned outlet identitu. */
+interface ResolvedHookCommitOwner {
+	/** Render-pure opaque outlet token. */
+	readonly token: outletCommitLease.OutletInstanceToken;
+}
+
+/** Commit observer používaný pouze public outletem po sink effectu. */
+type ResolvedHookCommitObserver<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+	Payload,
+> = (result: ResolvedHookEngineResult<Point, Payload>) => void;
+
+/**
+ * Sdílí Hook pořadí, external-store bridge a query mezi public hookem a outletem.
+ */
+function useResolvedContributionsEngine<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+	Payload,
+>(
+	captureFactory: ResolvedHookCaptureFactory<Point, Payload>,
+	commitOwner?: ResolvedHookCommitOwner,
+	commitObserver?: ResolvedHookCommitObserver<Point, Payload>,
+): ResolvedHookEngineResult<Point, Payload> {
+	const parent = adapterContext.useAdapterContext();
+	const [localScope] = react.useState(createConsumerScope);
+	const [, forceRefresh] = react.useReducer(
+		/** Monotonicky posune pouze hook-local render command. */
+		function incrementRefreshEpoch(value: number): number {
+			return value + 1;
+		},
+		0,
+	);
+	const renderSerialRef = react.useRef(0);
+	const commandEpochRef = react.useRef(0);
+	const controlRef = react.useRef<ResolvedHookControl>({
+		mounted: false,
+		allowWithoutGeneration: false,
+	});
+	const committedRef = react.useRef<CommittedResolvedAttempt | undefined>(undefined);
+	const storeCacheRef = react.useRef<ExternalStoreCache | undefined>(undefined);
+	const [outletLease, setOutletLease] = react.useState<
+		outletCommitLease.OutletCommitLease | undefined
+	>(undefined);
+	const [refresh] = react.useState(
+		/** Vytvoří právě jednu referenčně stabilní refresh capability. */
+		function createRefresh(): () => void {
+			/** Invaliduje předchozí command autoritu před React update schedulingem. */
+			function refreshResolvedContributions(): void {
+				const control = controlRef.current;
+				if (!control.mounted) {
+					return;
+				}
+				if (!control.allowWithoutGeneration
+					&& (control.scope === undefined
+						|| control.generation === undefined
+						|| !control.scope.isGenerationActive(control.generation))) {
+					return;
+				}
+				commandEpochRef.current += 1;
+				forceRefresh();
+			}
+			return refreshResolvedContributions;
+		},
+	);
+
+	renderSerialRef.current += 1;
+	const renderSerial = renderSerialRef.current;
+	const renderCommandEpoch = commandEpochRef.current;
+	/** Ukončí reentrantně stale capture nebo query bez dalšího public Getu. */
+	function checkpointRenderAuthority(): void {
+		if (renderSerialRef.current !== renderSerial
+			|| commandEpochRef.current !== renderCommandEpoch) {
+			throw new reactAdapterError.ReactAdapterError(
+				"REACT_ADAPTER_DISPOSED",
+				"The resolved contribution render attempt is no longer current.",
+				{ details: { field: "hook.render", phase: "lifecycle" } },
+			);
+		}
+	}
+
+	let captured: ResolvedHookCapture<Point>;
+	let payload: Payload | undefined;
+	try {
+		const envelope = captureFactory(parent, localScope, checkpointRenderAuthority);
+		captured = envelope.captured;
+		payload = envelope.payload;
+	} catch (cause: unknown) {
+		captured = Object.freeze({ kind: "configurationFailure", cause });
+	}
+
+	const externalStore = captured.kind === "captured"
+		? resolveExternalStoreBinding(
+			captured as CapturedResolvedHook<reactExtensionPoint.AnyReactExtensionPoint>,
+			storeCacheRef,
+		)
+		: EMPTY_EXTERNAL_STORE;
+	let renderAttempt: resolvedContributionsQuery.ResolvedQueryAttempt<Point> | undefined;
+	let renderConfiguration: adapterConfiguration.AdapterScopeConfiguration | undefined;
+	let renderScope: adapterScope.AdapterScopeRuntime | undefined;
+	let renderGeneration: adapterScope.AdapterScopeGeneration | undefined;
+	let renderStandalone = false;
+	const outletRegistryIdentity = captured.kind === "captured"
+		? captured.protocol.rawRegistry
+		: captured.kind === "unavailable"
+			? captured.rawRegistry
+			: undefined;
+
+	react.useEffect(
+		/** Standalone hook vlastní scope epochu pouze po React commitu. */
+		function acquireStandaloneScope(): void | (() => void) {
+			if (!renderStandalone || renderGeneration === undefined || renderScope === undefined) {
+				return undefined;
+			}
+			return renderScope.acquireOwner(renderGeneration);
+		},
+		[captured.kind === "captured" ? captured.scope : undefined,
+			captured.kind === "captured" ? captured.generation : undefined,
+			captured.kind === "captured" ? captured.standalone : false],
+	);
+
+	react.useEffect(
+		/** Publikuje pouze committed attempt autoritu a synchronně ji invaliduje při cleanupu. */
+		function commitResolvedAttempt(): () => void {
+			if (renderAttempt === undefined || renderScope === undefined) {
+				return function cleanupMissingAttempt(): void {
+					// Configuration failure nemá committed autoritu k invalidaci.
+				};
+			}
+			const authority: CommittedResolvedAttempt = Object.freeze({
+				attempt: renderAttempt as resolvedContributionsQuery.ResolvedQueryAttempt<
+					reactExtensionPoint.AnyReactExtensionPoint
+				>,
+				commandEpoch: commandEpochRef.current,
+				scope: renderScope,
+				configuration: renderConfiguration
+					?? adapterConfiguration.EMPTY_ADAPTER_SCOPE_CONFIGURATION,
+			});
+			committedRef.current = authority;
+			controlRef.current = {
+				mounted: true,
+				scope: renderScope,
+				...(renderGeneration === undefined ? {} : { generation: renderGeneration }),
+				allowWithoutGeneration: renderGeneration === undefined,
+			};
+			/** Zneplatní uniklé command capability před resource effect cleanupem. */
+			function cleanupCommittedAttempt(): void {
+				if (committedRef.current !== authority) {
+					return;
+				}
+				committedRef.current = undefined;
+				controlRef.current.mounted = false;
+				commandEpochRef.current += 1;
+			}
+			return cleanupCommittedAttempt;
+		},
+	);
+
+	react.useEffect(
+		/** Doručí secondary a primary diagnostiku pouze jednou pro committed attempt. */
+		function reportCommittedResolveFailure(): void {
+			const authority = committedRef.current;
+			if (authority === undefined
+				|| authority.attempt !== renderAttempt
+				|| renderAttempt?.primaryDiagnostic === undefined
+				|| !authority.scope.claimDiagnosticAttempt(renderAttempt.token)) {
+				return;
+			}
+
+			if (renderAttempt.secondaryDiagnostic !== undefined) {
+				reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+					renderAttempt.secondaryDiagnostic,
+					authority.configuration,
+				);
+				if (!isCommittedAttemptCurrent(authority, committedRef, commandEpochRef)) {
+					return;
+				}
+			}
+			reactAdapterDiagnostics.reportReactAdapterDiagnostic(
+				renderAttempt.primaryDiagnostic,
+				authority.configuration,
+			);
+		},
+	);
+
+	react.useEffect(
+		/** Přidělí outlet ID až po committed query autoritě a active scope epoše. */
+		function acquireOutletCommitLease(): void | (() => void) {
+			if (commitOwner === undefined
+				|| renderGeneration === undefined
+				|| renderScope === undefined
+				|| renderAttempt?.state.status !== "resolved"
+				|| committedRef.current?.attempt !== renderAttempt) {
+				return undefined;
+			}
+			const lease = renderScope.acquireCommitLease(
+				renderGeneration,
+				"outlet",
+				commitOwner.token,
+			);
+			setOutletLease(lease);
+			/** Synchronous cleanup zneplatní ID před další scope/outlet prací. */
+			function releaseOutletCommitLease(): void {
+				lease.release();
+			}
+			return releaseOutletCommitLease;
+		},
+		[commitOwner?.token, outletRegistryIdentity, renderScope, renderGeneration],
+	);
+
+	react.useEffect(
+		/** Doručí outlet observer až po committed authority, sinku a lease effectu. */
+		function notifyCommittedResolvedObserver(): void {
+			const attempt = renderAttempt;
+			const scope = renderScope;
+			if (commitObserver === undefined
+				|| attempt === undefined
+				|| scope === undefined
+				|| payload === undefined) {
+				return;
+			}
+			const authority = committedRef.current;
+			if (authority === undefined
+				|| authority.attempt !== attempt
+				|| !isCommittedAttemptCurrent(authority, committedRef, commandEpochRef)) {
+				return;
+			}
+			const rawRegistry = captured.kind === "captured"
+				? captured.protocol.rawRegistry
+				: captured.kind === "unavailable"
+					? captured.rawRegistry
+					: undefined;
+			if (rawRegistry === undefined) {
+				return;
+			}
+			const committedAuthority: CommittedResolvedAttempt = authority;
+			/** Ověří tutéž authority i po user-observable callback seamu. */
+			function isCurrent(): boolean {
+				return isCommittedAttemptCurrent(
+					committedAuthority,
+					committedRef,
+					commandEpochRef,
+				);
+			}
+			const result: UseResolvedContributionsResult<Point> = Object.freeze({
+				state: attempt.state,
+				refresh,
+			});
+			try {
+				commitObserver(Object.freeze({
+					payload,
+					result,
+					attempt,
+					scope,
+					generation: renderGeneration,
+					rawRegistry,
+					isCurrent,
+					checkpoint: checkpointRenderAuthority,
+					outletLease,
+					serverSnapshot,
+				}));
+			} catch {
+				// Interní observer musí vlastní host callback chyby bezpečně normalizovat.
+			}
+		},
+	);
+
+	const externalStoreSnapshot = react.useSyncExternalStore(
+		externalStore.subscribe,
+		externalStore.getSnapshot,
+		externalStore.getServerSnapshot,
+	);
+	const serverSnapshot = externalStoreSnapshot === adapterRegistryBridge.ADAPTER_SERVER_SNAPSHOT;
+
+	if (captured.kind === "configurationFailure") {
+		throw captured.cause;
+	}
+
+	renderConfiguration = captured.configuration;
+	renderScope = captured.scope;
+	if (captured.kind === "captured") {
+		renderGeneration = captured.generation;
+		renderStandalone = captured.standalone;
+		const bridgeFault = externalStore.readFault();
+		renderAttempt = resolvedContributionsQuery.queryResolvedContributions({
+			protocol: captured.protocol,
+			point: captured.point,
+			context: captured.context,
+			configuration: captured.configuration,
+			...(bridgeFault === undefined ? {} : { bridgeFault }),
+			checkpoint: checkpointRenderAuthority,
+		});
+	} else {
+		renderAttempt = resolvedContributionsQuery.createFailedResolvedQueryAttempt(
+			captured.cause,
+			captured.point,
+			captured.context,
+			captured.configuration,
+			checkpointRenderAuthority,
+		);
+	}
+
+	const attempt = renderAttempt;
+	const scope = renderScope;
+	if (attempt === undefined || scope === undefined || payload === undefined) {
+		throw new reactAdapterError.ReactAdapterError(
+			"REACT_ADAPTER_DISPOSED",
+			"The resolved contribution render attempt did not produce a complete binding.",
+			{ details: { field: "hook.binding", phase: "lifecycle" } },
+		);
+	}
+	const rawRegistry = captured.kind === "captured"
+		? captured.protocol.rawRegistry
+		: captured.rawRegistry;
+	const result: UseResolvedContributionsResult<Point> = Object.freeze({
+		state: attempt.state,
+		refresh,
+	});
+	/** Ověří exact attempt po jeho committed effectu a command epoch gate. */
+	function isCurrent(): boolean {
+		const authority = committedRef.current;
+		return authority !== undefined
+			&& authority.attempt === attempt
+			&& isCommittedAttemptCurrent(authority, committedRef, commandEpochRef);
+	}
+	return Object.freeze({
+		payload,
+		result,
+		attempt,
+		scope,
+		generation: renderGeneration,
+		rawRegistry,
+		isCurrent,
+		checkpoint: checkpointRenderAuthority,
+		outletLease,
+		serverSnapshot,
+	});
+}
+
+/**
+ * Synchronně promítne public Core katalog do React render state.
+ *
+ * @public
+ */
+export function useResolvedContributions<
+	Point extends import("./react-extension-point.js").AnyReactExtensionPoint,
+>(
+	options: UseResolvedContributionsOptions<Point>,
+): UseResolvedContributionsResult<Point> {
+	const engine = useResolvedContributionsEngine<Point, true>(
+		/** Zachytí public hook options uvnitř společného Hook-order-safe enginu. */
+		function capturePublicResolvedHook(parent, localScope, checkpoint) {
+			return Object.freeze({
+				captured: captureResolvedHook(options, parent, localScope, checkpoint),
+				payload: true as const,
+			});
+		},
+	);
+	return engine.result;
+}
+
+/**
+ * Interně promítne outlet props stejným subscriberem, query a committed autoritou.
+ */
+export function useResolvedContributionsForOutlet<
+	Point extends reactExtensionPoint.AnyReactExtensionPoint,
+>(
+	props: object,
+	commitObserver?: (
+		binding: OutletResolvedContributionsBinding<Point>,
+	) => void,
+): OutletResolvedContributionsBinding<Point> {
+	const [outletToken] = react.useState(outletCommitLease.createOutletInstanceToken);
+	const engine = useResolvedContributionsEngine<
+		Point,
+		outletInput.CapturedOutletInput<Point>
+	>(
+		/** Zachytí celý outlet vstup právě jednou v normativním pořadí. */
+		function captureOutletHook(parent, localScope, checkpoint) {
+			return captureOutletResolvedHook<Point>(props, parent, localScope, checkpoint);
+		},
+		{ token: outletToken },
+		commitObserver === undefined
+			? undefined
+			: function observeCommittedOutlet(engineResult): void {
+				commitObserver(Object.freeze({
+					input: engineResult.payload,
+					result: engineResult.result,
+					attempt: engineResult.attempt,
+					scope: engineResult.scope,
+					generation: engineResult.generation,
+					rawRegistry: engineResult.rawRegistry,
+					isCurrent: engineResult.isCurrent,
+					checkpoint: engineResult.checkpoint,
+					outletLease: engineResult.outletLease,
+					serverSnapshot: engineResult.serverSnapshot,
+				}));
+			},
+	);
+	return Object.freeze({
+		input: engine.payload,
+		result: engine.result,
+		attempt: engine.attempt,
+		scope: engine.scope,
+		generation: engine.generation,
+		rawRegistry: engine.rawRegistry,
+		isCurrent: engine.isCurrent,
+		checkpoint: engine.checkpoint,
+		outletLease: engine.outletLease,
+		serverSnapshot: engine.serverSnapshot,
+	});
+}