// generated by diplomat-tool
import type { IoType } from "./IoType.mjs"
import type { LayoutFunction } from "./LayoutFunction.mjs"
import type { NucleationError } from "./NucleationError.mjs"
import type { Schematic } from "./Schematic.mjs"
import type { SortStrategy } from "./SortStrategy.mjs"
import type { TypedCircuitExecutor } from "./TypedCircuitExecutor.mjs"
import type { pointer, codepoint } from "./diplomat-runtime.d.ts";



/**
 * High-level circuit builder. `build`/`build_validated` consume it
 * (PORTING rule 11). Regions are given as flat `[x,y,z,...]` positions
 * (see module notes).
 */
export class CircuitBuilder {
    /** @internal */
    get ffiValue(): pointer;
    /** @internal */
    constructor();


    /**
     * Create a builder for a schematic (cloned; no IO defined yet).
     */
    static create(schematic: Schematic): CircuitBuilder;

    /**
     * Create a builder pre-populated from Insign annotations.
     */
    static fromInsign(schematic: Schematic): CircuitBuilder;

    /**
     * Add an input with full control.
     */
    withInput(name: string, ioType: IoType, layout: LayoutFunction, regionPositions: Array<number>): void;

    /**
     * Add an input with full control and a custom sort strategy.
     */
    withInputSorted(name: string, ioType: IoType, layout: LayoutFunction, regionPositions: Array<number>, sort: SortStrategy): void;

    /**
     * Add an input with automatic layout inference.
     */
    withInputAuto(name: string, ioType: IoType, regionPositions: Array<number>): void;

    /**
     * Add an input with automatic layout inference and a custom sort.
     */
    withInputAutoSorted(name: string, ioType: IoType, regionPositions: Array<number>, sort: SortStrategy): void;

    /**
     * Add an output with full control.
     */
    withOutput(name: string, ioType: IoType, layout: LayoutFunction, regionPositions: Array<number>): void;

    /**
     * Add an output with full control and a custom sort strategy.
     */
    withOutputSorted(name: string, ioType: IoType, layout: LayoutFunction, regionPositions: Array<number>, sort: SortStrategy): void;

    /**
     * Add an output with automatic layout inference.
     */
    withOutputAuto(name: string, ioType: IoType, regionPositions: Array<number>): void;

    /**
     * Add an output with automatic layout inference and a custom sort.
     */
    withOutputAutoSorted(name: string, ioType: IoType, regionPositions: Array<number>, sort: SortStrategy): void;

    /**
     * Set simulation options.
     */
    withOptions(optimize: boolean, ioOnly: boolean): void;

    /**
     * Set the state mode ("stateless" | "stateful" | "manual").
     */
    withStateMode(mode: string): void;

    /**
     * Validate the configuration without consuming the builder.
     */
    validate(): void;

    /**
     * Build the executor. Consumes the builder.
     */
    build(): TypedCircuitExecutor;

    /**
     * Build the executor with validation. Consumes the builder.
     */
    buildValidated(): TypedCircuitExecutor;

    /**
     * Number of inputs defined so far (0 if the builder was consumed).
     */
    inputCount(): number;

    /**
     * Number of outputs defined so far (0 if the builder was consumed).
     */
    outputCount(): number;

    /**
     * Input names as a JSON array string.
     */
    inputNamesJson(): string;

    /**
     * Output names as a JSON array string.
     */
    outputNamesJson(): string;
}