import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.cjs";
import { Mode, Parser } from "./internal/parser.cjs";
import { withAnnotationView } from "./annotation-state.cjs";
import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.cjs";

//#region src/extension.d.ts

/**
 * Stable trait flags for custom parser extensions.
 *
 * @since 1.0.0
 */
interface ParserTraits {
  /**
   * Whether parent-state annotations should be injected into rebuilt child
   * states instead of relying on structural inheritance.
   */
  readonly inheritsAnnotations?: true;
  /**
   * Whether a missing CLI state can still complete from a source-backed
   * fallback such as config or environment data.
   */
  readonly completesFromSource?: true;
  /**
   * Whether annotation-only primitive states should count as completable only
   * when they come from a nested source-bound parser.
   */
  readonly requiresSourceBinding?: true;
}
/**
 * Suggest-time runtime node used to seed dependency-aware completion.
 *
 * @since 1.0.0
 */
interface SuggestNode {
  /** Path from the root parser to this node. */
  readonly path: readonly PropertyKey[];
  /** The parser whose dependency metadata should be inspected. */
  readonly parser: Parser<Mode, unknown, unknown>;
  /** Current parser state for this node. */
  readonly state: unknown;
  /** Whether this node reflects explicit input consumption. */
  readonly matched?: boolean;
  /** Snapshotted default dependency values for derived parsers. */
  readonly defaultDependencyValues?: readonly unknown[];
}
/**
 * Public view of a parser's source capability metadata.
 *
 * @since 1.0.0
 */
type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unknown> = NonNullable<NonNullable<Parser<M, TValue, TState>["dependencyMetadata"]>["source"]>;
/**
 * Defines stable extension traits on a parser object.
 *
 * @param parser The parser object to annotate.
 * @param traits Traits to enable.
 * @throws {TypeError} If a trait property cannot be defined on `parser`.
 * @since 1.0.0
 */
declare function defineTraits(parser: object, traits: ParserTraits): void;
/**
 * Reads the stable extension traits defined on a parser object.
 *
 * @param parser The parser object to inspect.
 * @returns The enabled traits.  Returns an empty object when none are set.
 * @since 1.0.0
 */
declare function getTraits(parser: object): ParserTraits;
/**
 * Delegates suggest-time runtime nodes to an inner parser while preserving an
 * outer parser's own source metadata node.
 *
 * @param innerParser The wrapped parser that owns the underlying nodes.
 * @param outerParser The outer parser that may contribute its own source node.
 * @param state The outer parser state.
 * @param path The parser path within the parse tree.
 * @param innerState The state to use when collecting inner nodes.
 * @param position Whether the outer node is appended or prepended.
 * @returns The composed runtime nodes.
 * @since 1.0.0
 */
declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, position?: "append" | "prepend"): readonly SuggestNode[];
/**
 * Maps the source capability of a parser's dependency metadata while
 * preserving any derived or transform capabilities unchanged.
 *
 * @param parser The parser whose source metadata should be transformed.
 * @param mapSource Function that transforms the source capability.
 * @returns The dependency metadata with its source capability transformed when
 *          present; otherwise the original dependency metadata, or
 *          `undefined` when the parser has no dependency metadata.
 * @since 1.0.0
 */
declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
//#endregion
export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };