package dev.photosync.mcapi.capture;

import java.nio.file.Path;
import java.util.concurrent.CompletableFuture;

/**
 * Takes a screenshot on demand -- the automatic capture timer's only way into
 * the game.
 *
 * <p>Deliberately not routed through vanilla's own screenshot call. Going
 * straight to the framebuffer lets the adapter choose the file name, which is
 * what makes the configurable suffix possible, and it keeps automatic captures
 * out of the {@link ScreenshotBus} path that the mixin owns -- so the origin of
 * a file is known by construction rather than guessed from its name.
 */
public interface ScreenshotService {

    /** Where the game keeps screenshots. Created if it does not exist. */
    Path directory();

    /**
     * Captures the current frame.
     *
     * <p>Safe to call from any thread; the grab itself is moved onto the render
     * thread. The future completes once the PNG is on disk, or fails if there is
     * no frame to capture or the write failed.
     *
     * @param fileNameSuffix inserted before the extension, e.g. {@code "_auto"}
     */
    CompletableFuture<Path> capture(String fileNameSuffix);
}
