@hoardodile/host 0.0.0

package/dist/image-Dx2Be3Bj.d.ts

@@ -0,0 +1,168 @@
+import { Readable } from 'node:stream';
+import { ProbeResult, ImageInfo } from '@hoardodile/sdk-types';
+import * as sharp from 'sharp';
+
+/**
+ * Header window read before handing bytes to the injected image prober.
+ * Shared with the host's sharp-backed probes so both sides feed the same
+ * bounded window (JPEG SOF markers live in the first KBs; 256KB covers
+ * even EXIF-bloated JPEGs).
+ */
+declare const PROBE_HEADER_BYTES: number;
+type ExtractProgress = {
+    /** Entries materialized so far (skipped cached files count too). */
+    readonly done: number;
+    readonly total: number;
+};
+
+type ResolveFfprobeDeps = {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override for tests so they never hit the real module. */
+    readonly loadStatic?: () => string | undefined;
+};
+/**
+ * Resolve the absolute path to `ffprobe` for this host.
+ *
+ * Precedence:
+ *   1. The `FFPROBE_PATH` env var.
+ *   2. `@derhuerst/ffprobe-static` via lazy `createRequire` — the
+ *      installer package stays out of the host tarball.
+ *   3. A bare command name, letting operators with ffprobe on PATH run
+ *      the CLI or server directly.
+ */
+declare function resolveFfprobePath(deps?: ResolveFfprobeDeps): string;
+type FfprobeStream = {
+    readonly codec_type?: unknown;
+    readonly codec_name?: unknown;
+    readonly width?: unknown;
+    readonly height?: unknown;
+    readonly sample_rate?: unknown;
+    readonly channels?: unknown;
+    readonly disposition?: unknown;
+    readonly tags?: unknown;
+};
+type FfprobeFormat = {
+    readonly duration?: unknown;
+    readonly bit_rate?: unknown;
+    readonly tags?: unknown;
+};
+type FfprobePayload = {
+    readonly streams?: readonly FfprobeStream[];
+    readonly format?: FfprobeFormat;
+};
+
+/**
+ * The unified audio/video probe behind `ResourceAPI.probe`: one ffprobe
+ * pass answers both "which family is this" and "what are its
+ * parameters", the way ffprobe itself reports media (`format` plus a
+ * `streams` array) instead of asking the caller to guess the family
+ * first.
+ *
+ * Container formats that carry either kind (Ogg, Matroska, ISO-BMFF)
+ * are settled here: the stream layout decides, not the extension and
+ * not the container MIME.
+ */
+type AvProbeOptions = {
+    /** MIME type from content sniffing; carried into the result. */
+    readonly mime: string;
+    /**
+     * ffmpeg `-f` container name. Required for stream sources (a pipe
+     * has no filename for ffprobe to key off); ignored for paths.
+     */
+    readonly inputFormat?: string;
+};
+/**
+ * Classify an ffprobe payload into a {@link ProbeResult}. A real video
+ * stream wins; otherwise an audio stream decides; a payload with
+ * neither is a decode failure.
+ */
+declare function avResultFromPayload(payload: FfprobePayload, mime: string): ProbeResult;
+/**
+ * Probe an audio/video source with ffprobe. Never rejects: a missing
+ * binary, an unreadable container or a source ffprobe cannot demux all
+ * resolve to `{ kind: "unknown", reason: "failed" }`.
+ */
+declare function probeAvMedia(source: string | Readable, opts: AvProbeOptions): Promise<ProbeResult>;
+
+/**
+ * Max zip entry size read into memory for thumb synthesis. Larger
+ * entries are materialized to disk before sharp/ffmpeg runs.
+ */
+declare const THUMB_BUFFER_MAX_BYTES: number;
+/**
+ * Image probing via sharp. sharp is loaded lazily and declared as an
+ * optional peer dependency: the host package stays free of native
+ * binaries, and consumers that never probe images (the browser-side mock,
+ * dependency-light CI installs) never pull it in. When sharp is missing,
+ * probe calls fail loudly instead of degrading silently.
+ */
+type SharpModule = typeof sharp;
+declare function loadSharp(): Promise<SharpModule>;
+type ImageSourceProbe = {
+    readonly width: number;
+    readonly height: number;
+    readonly animated: boolean;
+};
+
+/** True when `ext` names a format that can carry animation. */
+declare function isAnimatedCandidateExt(ext: string): boolean;
+type ImageMetadataInput = string | Buffer | Readable | {
+    readonly openStream: () => Promise<Readable>;
+    /**
+     * Optional byte-range read into the underlying source (e.g. a
+     * zip entry slice). When present, metadata probes read
+     * {@link PROBE_HEADER_BYTES} from the start instead of
+     * streaming the whole entry — libvips reads the ENTIRE file
+     * for metadata from a non-seekable stream, but only the header
+     * from a buffer.
+     */
+    readonly readRange?: (start: number, end: number) => Promise<Buffer>;
+};
+/**
+ * Narrow a Node stream into sharp's readable input without assertion.
+ * Async because the sharp module itself is loaded lazily.
+ *
+ * sharp's constructor rejects `sharp(stream, opts)` — for stream input
+ * the input options must be passed AS the first argument (a plain object
+ * of input parameters like `pages`/`animated`) and the readable piped
+ * into the resulting Duplex.
+ */
+declare function sharpFromReadable(stream: Readable, options?: sharp.SharpOptions): Promise<sharp.Sharp>;
+/**
+ * Sharp options for image thumb/probe reads. Enables sequential read for
+ * large JPEGs on disk so libvips can shrink-on-load during resize.
+ */
+declare function sharpImageInputOpts(input: string | Buffer, ext: string, pages: number, animated?: boolean): sharp.SharpOptions;
+/**
+ * True when a shallow `{ pages: 1 }` metadata read is not enough to
+ * decide animation and the full multi-page scan is required.
+ */
+declare function needsFullAnimationScan(meta: Pick<sharp.Metadata, "width" | "height" | "pages" | "pageHeight">, ext: string): boolean;
+/**
+ * Read image metadata with layered animation detection: static sources
+ * stop after a single-page read; animated containers escalate to
+ * `{ pages: -1 }` only when the shallow probe signals multi-frame input.
+ */
+declare function readImageMetadata(input: ImageMetadataInput, ext: string): Promise<{
+    readonly meta: sharp.Metadata;
+    readonly animated: boolean;
+}>;
+/**
+ * Probe an image path or buffer and return pixel dimensions plus whether
+ * the source is animated. Probe failures return `undefined`.
+ */
+declare function probeImageSource(input: ImageMetadataInput, extHint?: string): Promise<ImageSourceProbe | undefined>;
+/**
+ * Probe an image source and return its pixel dimensions. Probe failures
+ * return `undefined` so callers can treat "not yet probed" and "probe
+ * failed" the same way.
+ */
+declare function probeImage(source: ImageMetadataInput): Promise<ImageInfo | undefined>;
+/**
+ * True when the image has more than one frame (animated GIF / WebP / APNG /
+ * AVIF). Uses layered detection so static JPEG/PNG avoid a full-frame scan.
+ * Errors are coerced to `false`.
+ */
+declare function probeAnimatedImage(source: ImageMetadataInput): Promise<boolean>;
+
+export { type AvProbeOptions as A, type ExtractProgress as E, type FfprobePayload as F, type ImageMetadataInput as I, PROBE_HEADER_BYTES as P, THUMB_BUFFER_MAX_BYTES as T, probeAvMedia as a, type ImageSourceProbe as b, avResultFromPayload as c, probeAnimatedImage as d, probeImage as e, resolveFfprobePath as f, sharpImageInputOpts as g, isAnimatedCandidateExt as i, loadSharp as l, needsFullAnimationScan as n, probeImageSource as p, readImageMetadata as r, sharpFromReadable as s };