import { Annotations } from "./internal/annotations.js";
import { Mode, Parser } from "./internal/parser.js";

//#region src/annotation-state.d.ts

/**
 * Shared targets for annotation-view proxies.
 *
 * Maps a proxy returned by {@link withAnnotationView} back to its original
 * target object.
 *
 * @internal
 */
declare const annotationViewTargets: WeakMap<object, object>;
/**
 * Unwraps an annotation-view proxy to its original target object.
 *
 * @param value The candidate value that may be an annotation-view proxy.
 * @returns The original target object when the input is a tracked
 *          annotation-view proxy; otherwise the input value unchanged.
 * @internal
 */
declare function unwrapAnnotationView<T>(value: T): T;
/**
 * Creates an annotation-aware proxy without changing the target shape.
 *
 * @param state The object state to expose through an annotation-aware view.
 * @param annotations The annotations to surface through the proxy.
 * @returns A proxy over the unwrapped target object that reports the supplied
 *          annotations while preserving the target's structural behavior.
 * @since 1.0.0
 */
declare function withAnnotationView<T extends object>(state: T, annotations: Annotations): T;
/**
 * Removes Optique's internal primitive-state annotation wrapper when present.
 *
 * @param state The parser state to normalize.
 * @returns The wrapped primitive sentinel when the input is an injected
 *          annotation wrapper; otherwise the original input unchanged.
 * @internal
 */
declare function normalizeInjectedAnnotationState<T>(state: T): T;
/**
 * Removes Optique's internal annotation carriers from a delegated state.
 *
 * This unwraps primitive-state annotation wrappers, tracked delegated clones,
 * and annotation-view proxies used for object states.
 *
 * @param state The delegated state to normalize.
 * @returns The original underlying state value.
 * @internal
 */
declare function normalizeDelegatedAnnotationState<T>(state: T): T;
/**
 * Returns whether the given state uses an internal delegated annotation carrier.
 *
 * @param state The candidate state to inspect.
 * @returns `true` when the state is an injected primitive wrapper, a tracked
 *          delegated clone, or an annotation-view proxy.
 * @internal
 */
declare function hasDelegatedAnnotationCarrier(state: unknown): boolean;
interface NestedNormalizationEntry {
  clone: object | undefined;
  createClone: () => object;
  finalized: boolean;
  result: object;
  preferCloneOnRead: boolean;
}
/**
 * Recursively removes delegated annotation carriers from plain-object, array,
 * and built-in collection structures.
 *
 * Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
 * delegated carrier is found below them. Other non-plain objects are unwrapped
 * at the top level and then preserved as-is to avoid mutating or reconstructing
 * class instances.
 *
 * @param value The candidate value to normalize.
 * @param seen Tracks already-normalized objects so cyclic values keep their
 *             shape.
 * @returns The original value when no delegated carriers are present, or a
 *          normalized clone with delegated carriers removed.
 * @internal
 */
declare function normalizeNestedDelegatedAnnotationState<T>(value: T, seen?: WeakMap<object, NestedNormalizationEntry>, preferPendingClone?: boolean): T;
/**
 * Creates a short-lived delegated state that exposes the parent's annotations
 * regardless of the child state's runtime shape.
 *
 * Primitive and nullish states use `injectAnnotations()`, clone-based object
 * delegation is tracked so it can be normalized back out later, and non-plain
 * objects use an annotation-view proxy so class invariants such as private
 * fields remain intact.
 *
 * @param parentState The state carrying the annotations to delegate.
 * @param childState The child state that should observe those annotations.
 * @returns A delegated child state that exposes the parent's annotations.
 * @internal
 */
declare function getDelegatedAnnotationState<TState>(parentState: unknown, childState: TState): TState;
/**
 * Returns whether a state is still at the initial sentinel after normalizing
 * Optique's injected annotation wrapper.
 *
 * This treats plain `undefined` and annotation-wrapped `undefined` the same.
 *
 * @param state The parser state to inspect.
 * @returns `true` when the normalized state is still `undefined`;
 *          otherwise `false`.
 * @internal
 */
declare function isAnnotationWrappedInitialState(state: unknown): boolean;
/**
 * Propagates parent annotations into a child parse state when the child parser
 * explicitly opts into parent annotation inheritance.
 *
 * @param parentState The parent parser state that may carry annotations.
 * @param childState The child parse state that may receive inherited
 *                   annotations.
 * @param parser The child parser whose inheritance marker controls whether
 *               wrapper injection is allowed.
 * @returns The original child state when no injection is needed or possible,
 *          or an annotation-injected child state that preserves the original
 *          sentinel or object shape when inheritance applies.
 * @internal
 */
declare function getWrappedChildParseState<TState>(parentState: unknown, childState: TState, parser: Parser<Mode, unknown, unknown>): TState;
/**
 * Propagates parent annotations into a child state while preserving the child
 * state's shape for parsers that do not opt into full wrapper injection.
 *
 * @param parentState The parent parser state that may carry annotations.
 * @param childState The child state that may receive inherited annotations.
 * @param parser The child parser whose inheritance marker controls whether
 *               full wrapper injection is allowed.
 * @returns The original child state when no wrapping is needed, an
 *          annotation-injected child state when inheritance applies, or an
 *          annotation-view proxy that preserves the child's object shape.
 * @internal
 */
declare function getWrappedChildState<TState>(parentState: unknown, childState: TState, parser: Parser<Mode, unknown, unknown>): TState;
/**
 * Reconciles object-owned child state with parent annotations using the same
 * shared object-state inheritance rule across parser families.
 *
 * @param parentState The parent parser state that may carry annotations.
 * @param childState The object-owned child state to reconcile.
 * @returns The original child state when no reconciliation is needed, or a
 *          child state with inherited annotations when the object state should
 *          carry the parent's annotations.
 * @internal
 */
declare function reconcileObjectChildState<TState>(parentState: unknown, childState: TState): TState;
//#endregion
export { annotationViewTargets, getDelegatedAnnotationState, getWrappedChildParseState, getWrappedChildState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeInjectedAnnotationState, normalizeNestedDelegatedAnnotationState, reconcileObjectChildState, unwrapAnnotationView, withAnnotationView };