/**
 * Archive-specific text utilities.
 *
 * This module provides text encoding/decoding for ZIP archives:
 * - CP437 (IBM Code Page 437) for legacy DOS-era ZIP files
 * - Unified ZIP string decoding with extra field support
 *
 * For common UTF-8 utilities, import from @stream/shared.
 *
 * @module
 */
import type { ZipExtraFields } from "../zip-spec/zip-extra-fields.js";
/**
 * Decode a Uint8Array as CP437 (IBM Code Page 437).
 *
 * This is the correct encoding for ZIP file names/comments when the UTF-8
 * flag (bit 11) is not set, per PKWARE APPNOTE.
 *
 * @param bytes - The bytes to decode
 * @returns The decoded string
 */
export declare function decodeCp437(bytes: Uint8Array): string;
/**
 * Encode a string as CP437 (IBM Code Page 437).
 *
 * Characters not representable in CP437 are replaced with '?'.
 */
export declare function encodeCp437(value: string): Uint8Array;
export interface ZipStringCodec {
    /** Human-readable encoding name (optional, for debugging). */
    name?: string;
    /** Encode a string into raw bytes for ZIP headers. */
    encode(value: string): Uint8Array;
    /** Decode raw ZIP bytes into a string. */
    decode(bytes: Uint8Array): string;
    /** Whether to set the UTF-8 flag in ZIP headers (default depends on encoding). */
    useUtf8Flag?: boolean;
    /** Whether to include Unicode extra fields for non-UTF-8 encodings. */
    useUnicodeExtraFields?: boolean;
}
export type ZipStringEncoding = "utf-8" | "cp437" | ZipStringCodec;
export declare function resolveZipStringCodec(encoding?: ZipStringEncoding): ZipStringCodec;
/**
 * Encode an optional ZIP string using the specified encoding.
 * Returns a shared empty buffer when the input is empty/undefined.
 */
export declare function encodeZipString(value?: string, encoding?: ZipStringEncoding): Uint8Array;
/**
 * Encode an optional ZIP string using a pre-resolved codec.
 */
export declare function encodeZipStringWithCodec(value: string | undefined, codec: ZipStringCodec): Uint8Array;
/**
 * Decode a ZIP entry string (file name or comment) with proper encoding.
 *
 * Order of preference:
 * 1. If UTF-8 flag (bit 11) is set, decode as UTF-8
 * 2. If Unicode Extra Field is present and CRC32 matches original bytes, use it
 * 3. Otherwise, decode as CP437 (IBM Code Page 437)
 *
 * @param bytes - Raw bytes from the ZIP entry
 * @param flags - General purpose bit flags (or null)
 * @param unicodeInfo - Parsed Unicode Extra Field info (unicodePath or unicodeComment)
 * @returns Decoded string
 */
export declare function decodeZipString(bytes: Uint8Array, flags: number | null, unicodeInfo?: {
    version: number;
    originalCrc32: number;
    unicodeValue: string;
}, fallbackDecoder?: Pick<ZipStringCodec, "decode">): string;
/**
 * Decode a ZIP entry path with full extra field support.
 *
 * Convenience wrapper around `decodeZipString` for file paths.
 *
 * @param pathBytes - Raw path bytes from the ZIP entry
 * @param flags - General purpose bit flags (or null)
 * @param extraFields - Parsed extra fields (may contain unicodePath)
 * @returns Decoded path string
 */
export declare function decodeZipPath(pathBytes: Uint8Array, flags: number | null, extraFields?: ZipExtraFields, fallbackDecoder?: Pick<ZipStringCodec, "decode">): string;
/**
 * Decode a ZIP entry comment with full extra field support.
 *
 * Convenience wrapper around `decodeZipString` for comments.
 *
 * @param commentBytes - Raw comment bytes from the ZIP entry
 * @param flags - General purpose bit flags (or null)
 * @param extraFields - Parsed extra fields (may contain unicodeComment)
 * @returns Decoded comment string
 */
export declare function decodeZipComment(commentBytes: Uint8Array, flags: number | null, extraFields?: ZipExtraFields, fallbackDecoder?: Pick<ZipStringCodec, "decode">): string;
/**
 * Convert a Uint8Array to an ArrayBuffer suitable for Web Crypto API.
 * This handles views that may be backed by SharedArrayBuffer or ArrayBuffer with non-zero offset.
 */
export declare function toArrayBuffer(data: Uint8Array): ArrayBuffer;