@fishka/seqio 0.3.0 → 0.5.0

package/dist/abif/index.d.ts

@@ -1,3 +1,5 @@
+declare function tagNameFromInt32(n: number): string;
+
 /**
  * Low-level ABIF file model: a flat list of directory entries with raw
  * payloads. Lossless round-trip is preserved: every entry (including unknown
@@ -7,10 +9,35 @@
 interface AbifFile {
     /** ABIF version, e.g. 101 for v1.01. */
     version: number;
+    /** The root directory (tdir) header, exactly as read — including any directory padding it declares. */
+    tdir: AbifDirectory;
     /** Directory entries in the original on-disk order. */
     entries: AbifEntry[];
     /** MacBinary preamble offset (128 if present, 0 otherwise). Preserved for diagnostics. */
     macBinaryOffset: number;
+    /**
+     * The 128-byte MacBinary preamble, verbatim — present only when {@link macBinaryOffset} is 128.
+     * Exposed so a raw reader can reproduce the wrapper, not just note that it existed.
+     */
+    macBinaryHeader?: Uint8Array;
+    /**
+     * Reserved header bytes [34..127] (94 bytes), verbatim. Usually zeros; exposed so a raw reader
+     * keeps the entire 128-byte header, not just magic/version/tdir.
+     */
+    headerReserved: Uint8Array;
+    /**
+     * Physical byte ranges not covered by the header, directory, or any entry payload — orphaned
+     * blocks left by editing tools, trailing padding, etc. Empty for a tightly-packed file. Exposed
+     * so a raw reader accounts for every byte; the chromatogram never depends on these.
+     */
+    unreferencedRanges: AbifByteRange[];
+}
+/** A contiguous run of file bytes at an absolute offset — used for {@link AbifFile.unreferencedRanges}. */
+interface AbifByteRange {
+    /** Absolute offset from the start of the file (includes any MacBinary preamble). */
+    offset: number;
+    /** The bytes in this range, verbatim. `bytes.length` is the range length. */
+    bytes: Uint8Array;
 }
 interface AbifEntry {
     /** 4-character tag name, e.g. "DATA", "PBAS". */
@@ -23,12 +50,75 @@ interface AbifEntry {
     elementType: number;
     /** Bytes per element. */
     elementSize: number;
-    /** Number of elements. */
+    /** Number of elements (reconciled: clamped to what the payload holds). */
     elementCount: number;
-    /** Raw payload bytes (length === elementCount * elementSize). */
+    /**
+     * Raw payload bytes. Length === the on-disk `dataSize` (the authoritative field), which for
+     * user/opaque types may differ from `elementCount * elementSize`.
+     */
     payload: Uint8Array;
     /** Opaque dataHandle field, usually 0. Preserved for round-trip. */
     dataHandle: number;
+    /**
+     * The directory fields exactly as they were on disk — present only when this entry was read from a
+     * file (absent for entries synthesized by setters/writeAbif). Lets consumers inspect the real record
+     * without our reconciliation, and lets writeAbif() reuse this entry's original directory slot/offset
+     * verbatim on an unmodified round-trip. Mutate entries only through upsertEntry() — it clears this
+     * field, since a hand-edited entry (payload/elementType/elementSize/elementCount set directly) can no
+     * longer be reproduced from its stale on-disk shape.
+     */
+    raw?: AbifEntryRaw;
+}
+/** A directory entry's on-disk fields, verbatim, before any reconciliation applied by {@link readAbif}. */
+interface AbifEntryRaw {
+    /** `elementCount` (numElements) as written on disk. */
+    elementCount: number;
+    /** `dataSize` field as written on disk, in bytes. */
+    dataSize: number;
+    /** External payload offset relative to the ABIF start, or -1 when the payload is inline. */
+    dataOffset: number;
+    /** Whether the payload was stored inline (declared dataSize ≤ 4). */
+    inline: boolean;
+    /**
+     * The 4 raw bytes of the dataOffset/data slot, verbatim. For an external entry these are the
+     * big-endian offset; for an inline entry they are the value bytes plus any padding/stale bytes
+     * beyond `dataSize` — exposed so a raw reader loses no structure.
+     */
+    dataOffsetBytes: Uint8Array;
+}
+/**
+ * The root directory (`tdir`) header — the header's own directory entry, describing the directory
+ * block. Its fields are exposed like any other raw entry so a raw reader never loses them, even when
+ * `rawEntryCount` desyncs from `dataSize`.
+ */
+interface AbifDirectory {
+    /** Effective number of entries actually read — equals `entries.length`. */
+    entryCount: number;
+    /** tdir `numElements` verbatim, before reconciliation; the authoritative on-disk entry count. */
+    rawEntryCount: number;
+    /** tdir `elementType` (1023). */
+    elementType: number;
+    /** tdir `tagNumber` (usually 1). */
+    tagNumber: number;
+    /** Bytes per directory entry (always 28). */
+    entrySize: number;
+    /**
+     * Directory block size in bytes, from the tdir `dataSize` field. May exceed `entryCount * 28`
+     * when the file carries directory padding / extra bytes.
+     */
+    dataSize: number;
+    /** File offset (relative to the ABIF start) where the directory block begins. */
+    dataOffset: number;
+    /** The 4 raw bytes of the tdir's dataOffset field, verbatim. */
+    dataOffsetBytes: Uint8Array;
+    /** tdir `dataHandle` field, usually 0. */
+    dataHandle: number;
+    /**
+     * The raw directory-padding bytes: everything from the end of the last entry to the end of the
+     * directory block (`dataSize - entryCount*28`). Usually zeros; exposed so a raw reader keeps the
+     * whole directory structure, not just the entries.
+     */
+    paddingBytes: Uint8Array;
 }
 interface ChannelSignals {
     A: number[];
@@ -36,6 +126,8 @@ interface ChannelSignals {
     G: number[];
     T: number[];
 }
+/** Spec-defined role of a DATA<n> tag — see {@link dataChannelRole}. */
+type AbifDataChannelRole = 'trace' | 'telemetry' | 'other';
 /** Per-base chromatogram view. */
 interface Chromatogram {
     /** Per-base peak position in sample points (from PLOC). */
@@ -47,7 +139,39 @@ interface Chromatogram {
     /** Average peak spacing (samples per base), from SPAC. */
     samplingRate?: number;
 }
-/** Basecalls extracted from PBAS/PCON/PLOC under the chosen version. */
+/**
+ * One basecall version exactly as the file stores it. ABIF numbers the
+ * PBAS/PCON/PLOC tags by version, and the spec fixes what each number means:
+ *
+ *   - version 2 (`role: 'called'`) — the sequence as produced by the basecaller.
+ *   - version 1 (`role: 'edited'`) — the sequence after user hand-editing.
+ *   - any other version (`role: 'unknown'`) — the spec only defines 1 and 2, so
+ *     a vendor/future PBAS3+ is surfaced without a claimed role.
+ *
+ * A file may carry either or both, and the two can differ in content and even in
+ * length (edits insert/delete bases). {@link parseAbif} exposes every version it
+ * finds via {@link ParsedAbif.baseCallVariants} — picking which one to show or
+ * export is the consumer's call, not the parser's.
+ */
+type AbifBaseCallRole = 'called' | 'edited' | 'unknown';
+interface AbifBaseCallVariant {
+    /** Tag number of the PBAS/PCON/PLOC this variant came from (1, 2, or a vendor number). */
+    version: number;
+    /** Spec-defined role by tag number: 2 = basecaller-called, 1 = user-edited, else unknown. */
+    role: AbifBaseCallRole;
+    /** Bases from PBAS<version> as stored — case preserved, trailing NULs stripped, not normalized. */
+    sequence: string;
+    /** Per-base Q-scores from PCON<version>; `[]` when that version has no PCON. */
+    confidences: number[];
+    /** Per-base peak positions (sample indices) from PLOC<version>; `[]` when absent. */
+    positions: number[];
+}
+/**
+ * Convenience pointer to the preferred basecall version — the called one (PBAS2)
+ * when present, else whatever single version the file has. This is a spec-role
+ * choice (called over edited), not a quality judgement; see
+ * {@link ParsedAbif.baseCallVariants} for every version the file actually carries.
+ */
 interface AbifBaseCalls {
     /** Called bases (uppercase). */
     sequence: string;
@@ -68,34 +192,37 @@ interface AbifMetadata {
     runDate?: string;
     runTime?: string;
     samplingRate?: number;
+    /**
+     * Value of the RevC1 flag: whether the file declares its sequence already
+     * reverse-complemented. undefined when the tag is absent. Reported as-is — the
+     * consumer decides what to do with it.
+     */
+    reverseComplemented?: boolean;
     comments: string[];
 }
 /**
- * Full chromatogram bundle: all DATA channels, plus FWO_-aware A/C/G/T views.
- *
- * The two block views are named after their on-disk tag number ranges. Their
- * semantic content varies by instrument:
- *
- *   - DATA1..4  — on modern KB-basecaller-aware instruments (3130, 3500,
- *                  3730) these are POST-PROCESSED traces (mobility-corrected,
- *                  baseline-subtracted, color-separated). Basecallers operate
- *                  on these. On older simpler instruments DATA1..4 IS the raw
- *                  fluorescence.
- *   - DATA9..12 — RAW fluorescence on instruments that produce both blocks.
- *                  Absent on instruments that only write DATA1..8.
- *
- * Use {@link hasProcessedTraces} (data9To12 present) to detect whether
- * DATA1..4 has already been processed and bypass your own baseline/color
- * steps accordingly.
+ * All DATA channels plus FWO_-aware A/C/G/T views of the two dye-trace blocks.
+ *
+ * The block views are named after their on-disk tag ranges — nothing more. Which
+ * block is "raw" and which is "analyzed / processed" is an instrument-and-tool
+ * convention that the ABIF file does NOT state, so this parser refuses to label
+ * it. The consumer that needs to tell them apart has the primitives to decide:
+ * the per-block sample counts (channel lengths) and the basecall peak positions
+ * ({@link AbifBaseCalls.positions}); e.g. positions that overflow one block's
+ * length can only belong to the other.
+ *
+ * Per the ABIF spec, DATA5..8 are instrument telemetry (voltage / current / power
+ * / temperature), NOT dye traces — see {@link dataChannelRole}. They live in
+ * {@link dataChannels} but are excluded from the A/C/G/T views.
  */
 interface AbifChromatogramBundle {
     /** FWO_ value (e.g. "GATC"). */
     baseOrder: string;
-    /** All DATA tags by tagNumber → trace. */
+    /** All DATA tags by tagNumber → trace (dye traces AND telemetry). */
     dataChannels: Record<number, number[]>;
-    /** DATA1..4 mapped to A/C/G/T by FWO_. Post-processed on newer instruments, raw on older. */
+    /** DATA1..4 mapped to A/C/G/T by FWO_. */
     data1To4: ChannelSignals;
-    /** DATA9..12 mapped to A/C/G/T by FWO_. Raw fluorescence; absent on older instruments. */
+    /** DATA9..12 mapped to A/C/G/T by FWO_; empty when the file has no 9..12 block. */
     data9To12: ChannelSignals;
 }
 /** Rich result from {@link parseAbif} — everything the typical viewer needs. */
@@ -107,7 +234,10 @@ interface ParsedAbif {
     dirEntryCount: number;
     metadata: AbifMetadata;
     chromatogram: AbifChromatogramBundle;
+    /** Preferred basecall version (called over edited); convenience over {@link baseCallVariants}. */
     baseCalls?: AbifBaseCalls;
+    /** Every basecall version the file carries (called and/or edited), in version order. */
+    baseCallVariants: AbifBaseCallVariant[];
     /** All directory entries with their decoded payloads (best-effort by type). */
     entries: AbifDirEntry[];
 }
@@ -119,9 +249,15 @@ interface AbifDirEntry {
     elementType: number;
     elementTypeName: string;
     elementSize: number;
+    /** Reconciled element count (clamped to the declared dataSize when it was smaller). */
     elementCount: number;
+    /** `numElements` exactly as written on disk, before reconciliation. */
+    rawElementCount: number;
+    /** `dataSize` as written on disk, in bytes (not recomputed). */
     dataSize: number;
+    /** External payload offset relative to the ABIF start, or -1 when the payload is inline. */
     dataOffset: number;
+    /** Whether the payload was stored inline (declared dataSize ≤ 4). */
     inline: boolean;
     decoded: AbifDecodedValue;
     preview: string;
@@ -161,14 +297,13 @@ type AbifDecodedValue = {
     value: Uint8Array;
 };
 
-declare function tagNameFromInt32(n: number): string;
-
 /**
- * Low-level ABIF reader/writer.
- *
- * Round-trip without loss: every directory entry (including unknown vendor
- * tags) is preserved as a raw payload (Uint8Array). The high-level layer
- * (view.ts, parser.ts) provides typed access on top of this.
+ * Raw layer: the ABIF byte<->struct codec. Every directory entry (including unknown
+ * vendor tags) is preserved as a raw payload (Uint8Array), and writeAbif() reproduces
+ * the original bytes exactly for an unmodified round-trip (see its own doc comment).
+ * The domain layer (view.ts, setters.ts, parser.ts, abif-op-*.ts) provides typed,
+ * format-aware access on top of this — this file knows nothing about what any tag
+ * means.
  *
  * ABIF file layout:
  *   [0..3]      "ABIF" magic
@@ -184,12 +319,14 @@ declare function tagNameFromInt32(n: number): string;
  *     8   2    elementType    (int16)
  *    10   2    elementSize    (int16)
  *    12   4    elementCount   (int32)
- *    16   4    dataSize       (int32; total payload bytes; spec says count*size)
+ *    16   4    dataSize       (int32; total payload bytes — authoritative; for
+ *                              well-formed entries equals count*size, but user/
+ *                              opaque types may differ, so we read by dataSize)
  *    20   4    dataOffset     (int32) OR inline data if dataSize <= 4
  *    24   4    dataHandle     (int32; usually 0)
  *
- * Inline rule (per ABIF spec): when count*size <= 4 the payload bytes are
- * stored directly in the dataOffset field (left-aligned, padded to 4 bytes).
+ * Inline rule (per ABIF spec): when the declared dataSize <= 4 the payload bytes
+ * are stored directly in the dataOffset field (left-aligned, padded to 4 bytes).
  *
  * MacBinary preamble: some ABIF files (older Mac-origin) start with a 128-byte
  * MacBinary header before the actual ABIF magic. We detect and skip it.
@@ -198,7 +335,13 @@ declare function tagNameFromInt32(n: number): string;
 declare const HEADER_SIZE = 128;
 declare const ENTRY_SIZE = 28;
 /**
- * Parse an ABIF file from raw bytes.
+ * Parse an ABIF file from raw bytes into its verbatim directory structure.
+ *
+ * This is the RAW source of truth: it reads the tdir header and every entry as
+ * stored — real dataSize, dataOffset, numElements (see `entry.raw`), the 4 inline
+ * bytes, and the tdir/directory metadata — and interprets nothing. For a
+ * high-level, opinionated view (typed channels, basecalls, metadata) layer
+ * {@link parseAbif} on top.
  *
  * Accepts Uint8Array (works in Node and the browser). Node's Buffer extends
  * Uint8Array, so `readAbif(buffer)` and `readAbif(new Uint8Array(arrayBuffer))`
@@ -211,15 +354,35 @@ declare function readAbif(bytes: Uint8Array): AbifFile;
 /**
  * Serialize an AbifFile back to a Uint8Array.
  *
- * Layout produced: header (128 B) + directory (N*28 B) + payload block.
- * External payloads are packed tightly in entry order. Inline payloads
- * (count*size <= 4) live entirely inside their directory entry.
+ * Byte-exact on an unmodified round-trip for well-formed records and the tolerated
+ * count/dataSize desyncs readAbif() accepts: readAbif() followed right back by
+ * writeAbif(), with nothing touched in between, reproduces the original bytes
+ * exactly (a MacBinary-wrapped input round-trips its ABIF payload byte-exact, but
+ * the preamble itself is never re-added — see the AGENTS.md note on why). The one
+ * exception is a genuinely invalid negative `dataSize`/`numElements` field (readAbif
+ * tolerates these defensively, falling back to a computed size, but never treats them
+ * as verbatim-eligible on write — see the byteLength check below) — such an entry
+ * round-trips meaning-lossless (correct payload/content) but its declared dataSize
+ * field gets normalized to the real payload length rather than reproducing the
+ * original garbage value.
  *
- * The output is not bit-identical to the input if the original had a different
- * physical layout (e.g. payloads before directory), but the *meaning*
- * round-trips: readAbif(writeAbif(f)) reproduces the same entries structurally.
+ * This works by keeping every entry whose payload size hasn't changed since it was
+ * read (`entry.raw` present — upsertEntry() clears it on any mutation — and
+ * `payload.byteLength === raw.dataSize`) at its exact original directory slot and
+ * file offset, writing the *original* on-disk numElements/dataSize/offset-or-inline-
+ * padding instead of the reconciled/current ones. A new or resized entry is appended
+ * past the highest byte offset still known to hold preserved content (every verbatim
+ * entry's span, the directory, and any unreferenced range); only its own directory
+ * record changes, so every other entry's bytes stay untouched. A resized/removed
+ * entry's *old* span is not itself reserved — nothing points at it anymore, so it is
+ * free to be reused by whatever gets appended next; the output is not padded out to
+ * the original file's true end.
  *
- * MacBinary preamble is not preserved by writeAbif.
+ * The directory is kept at its original file offset as long as the entry count
+ * didn't grow (removing entries just shortens it in place; the original directory
+ * padding is only reused when the count is exactly unchanged, since a shorter
+ * directory can't reuse padding sized for more entries). Only a growing entry count
+ * relocates the whole directory to freshly appended space.
  */
 declare function writeAbif(file: AbifFile): Uint8Array;
 /** Find an entry by name+number, or undefined. */
@@ -229,6 +392,11 @@ declare function findEntries(file: AbifFile, name: string): AbifEntry[];
 /**
  * Replace the payload of an existing entry, or append a new one.
  * elementType/elementSize/elementCount must be supplied for new entries.
+ *
+ * This is the required way to mutate an entry read from a file — it clears `.raw`
+ * on replacement so writeAbif() never reuses a now-stale on-disk shape. Setting
+ * `entry.payload`/`elementType`/`elementSize`/`elementCount` directly instead
+ * leaves `.raw` behind and can corrupt the written directory record.
  */
 declare function upsertEntry(file: AbifFile, name: string, number: number, payload: Uint8Array, defaults: {
     elementType: number;
@@ -237,78 +405,36 @@ declare function upsertEntry(file: AbifFile, name: string, number: number, paylo
 }): void;
 
 /**
- * High-level typed view over an AbifFile.
- *
- * Reading helpers that interpret the raw payloads of well-known tags. For
- * mutation helpers (setSequence, setConfidences, ...) see ./setters.
- */
-
-/** Get DATA<n> as a signed-int16 array, or undefined. */
-declare function getDataChannel(file: AbifFile, n: number): Int16Array | undefined;
-/**
- * Dye order, 4 ASCII chars (e.g. "GATC"). Defaults to "GATC" if FWO_ absent.
- *
- * GATC is the dye order produced by modern ABI 3730/3500 instruments and the
- * dominant default in the wild. Older "ACGT" defaults caused channel
- * mis-mapping on files where FWO_ is missing or malformed.
- */
-declare function getFwo(file: AbifFile): string;
-/**
- * True when the file carries BOTH DATA1..4 and DATA9..12. Newer ABI-style
- * instruments produce both: DATA1..4 is post-processed (mobility-corrected,
- * baseline-subtracted, color-separated) and DATA9..12 is raw fluorescence.
- * Older instruments produce only DATA1..4 (which IS the raw signal).
- *
- * Callers that re-process traces (basecallers) should detect this and bypass
- * their own baseline-subtraction / color-matrix steps when DATA1..4 is
- * already cleaned.
- */
-declare function hasProcessedTraces(file: AbifFile): boolean;
-/**
- * Map from base letter ("A"|"C"|"G"|"T") to the DATA tag number that holds
- * its RAW fluorescence channel.
- *
- * ABIF stores up to 12 DATA tags. KB-basecaller-aware instruments (3130, 3500,
- * ...) use DATA1..4 for processed traces and DATA9..12 for raw. Older / simpler
- * instruments produce only DATA1..8 where DATA1..4 ARE the raw traces.
- *
- * This helper always returns the DATA1..4 mapping (the convention used by
- * basecallers operating on raw signal). Use {@link hasProcessedTraces} to
- * detect whether DATA1..4 has been pre-processed and bypass baseline/color
- * steps accordingly.
+ * High-level "parse everything" wrapper around the raw + view layers.
  *
- * The dye-to-channel order within each block is given by FWO_. If
- * FWO_="GATC" then G→1, A→2, T→3, C→4.
- */
-declare function getRawChannelMap(file: AbifFile): Record<'A' | 'C' | 'G' | 'T', number>;
-/** Get PBAS sequence (prefer PBAS2 over PBAS1). undefined if neither present. */
-declare function getSequence(file: AbifFile): string | undefined;
-/**
- * Get per-base Phred-like quality scores (0..255 byte values, typically 0..60
- * for Sanger). Prefers PCON2 over PCON1.
+ * Returns a single ParsedAbif object with metadata, the FWO_-aware
+ * DATA1..4 / DATA9..12 channel split, basecalls, and decoded directory entries
+ * for diagnostics. Mirrors what typical viewers (chromatogram UIs, sample
+ * inspectors) need from a single file.
  *
- * PCON is declared in the ABIF spec as elementType=2 (char) but the byte
- * values ARE the Q-scores — we read raw bytes regardless of declared type.
+ * For round-trip authoring (basecallers), prefer {@link readAbif} +
+ * setters from ./setters which operate directly on the raw AbifFile.
  */
-declare function getConfidences(file: AbifFile): number[] | undefined;
+
 /**
- * Get peak scan positions (one per base). Prefers PLOC2 over PLOC1.
+ * Parse an ABIF file into a high-level view: metadata, channels, basecalls,
+ * and decoded directory entries.
  *
- * Read as UNSIGNED int16: PLOC indexes into the sample trace and is always
- * non-negative, but values > 32767 (long traces) would wrap to negative
- * if interpreted as signed.
- */
-declare function getPositions(file: AbifFile): number[] | undefined;
-/**
- * Get average peak spacing (samples per base), from SPAC/1.
+ * This is the INTERPRETING layer — it makes convenience choices (FWO_ → "GATC"
+ * fallback, derived samplingRate, preferred/upper-cased PBAS2 baseCalls). It is
+ * not the raw structural truth: for that use {@link readAbif}, which reads the
+ * directory verbatim (raw dataSize/offset/counts, tdir, inline bytes) and makes
+ * no interpretation. `parseAbif` builds on top of it.
  *
- * ABIF spec defines SPAC as float32 (elementType=7); some legacy files
- * mislabel it as long (type=5). Both are 4 bytes and on disk the payload
- * is always a 32-bit float, so we read as float regardless of declared type.
- *
- * Returns undefined if SPAC is absent or non-positive.
+ * Accepts ArrayBuffer or Uint8Array (Buffer in Node works too — it extends
+ * Uint8Array). The `fileName` argument is informational only; it's preserved
+ * in the result.
  */
-declare function getSamplingRate(file: AbifFile): number | undefined;
+declare function parseAbif(input: ArrayBuffer | Uint8Array, fileName?: string): ParsedAbif;
+/** True when any channel has at least one signal value. */
+declare function hasSignals(s: ChannelSignals): boolean;
+/** Length of the longest channel in a ChannelSignals bundle. */
+declare function channelMaxLength(s: ChannelSignals): number;
 
 /**
  * Mutation helpers for AbifFile: write PBAS/PCON/PLOC/SPAC and ensure DATA9..12
@@ -359,29 +485,90 @@ declare function averagePeakSpacing(positions: ArrayLike<number>): number;
 declare function ensureRawDataChannels(file: AbifFile): void;
 
 /**
- * High-level "parse everything" wrapper around the raw + view layers.
- *
- * Returns a single ParsedAbif object with metadata, the FWO_-aware
- * DATA1..4 / DATA9..12 channel split, basecalls, and decoded directory entries
- * for diagnostics. Mirrors what typical viewers (chromatogram UIs, sample
- * inspectors) need from a single file.
+ * High-level typed view over an AbifFile.
  *
- * For round-trip authoring (basecallers), prefer {@link readAbif} +
- * setters from ./setters which operate directly on the raw AbifFile.
+ * Reading helpers that interpret the raw payloads of well-known tags. For
+ * mutation helpers (setSequence, setConfidences, ...) see ./setters.
  */
 
+/** Get DATA<n> as a signed-int16 array, or undefined. */
+declare function getDataChannel(file: AbifFile, n: number): Int16Array | undefined;
 /**
- * Parse an ABIF file into a high-level view: metadata, channels, basecalls,
- * and decoded directory entries.
+ * Dye order, 4 ASCII chars (e.g. "GATC"). Defaults to "GATC" if FWO_ absent.
  *
- * Accepts ArrayBuffer or Uint8Array (Buffer in Node works too — it extends
- * Uint8Array). The `fileName` argument is informational only; it's preserved
- * in the result.
+ * GATC is the dye order produced by modern ABI 3730/3500 instruments and the
+ * dominant default in the wild. Older "ACGT" defaults caused channel
+ * mis-mapping on files where FWO_ is missing or malformed.
  */
-declare function parseAbif(input: ArrayBuffer | Uint8Array, fileName?: string): ParsedAbif;
-/** True when any channel has at least one signal value. */
-declare function hasSignals(s: ChannelSignals): boolean;
-/** Length of the longest channel in a ChannelSignals bundle. */
-declare function channelMaxLength(s: ChannelSignals): number;
+declare function getFwo(file: AbifFile): string;
+/**
+ * Whether an FWO_ string is a genuine dye order: a permutation of A/C/G/T with all
+ * four bases distinct. `"GATC"` passes; `"AAAA"` (regex-valid but degenerate) does
+ * not — mapping four channels through it would collapse them onto one base.
+ */
+declare function isFwoPermutation(fwo: string): boolean;
+/**
+ * Fact: the file carries a second dye-trace block, DATA9..12 (all four tags), in
+ * addition to DATA1..4. Reports presence only — it does NOT say which block is
+ * raw and which is analyzed/processed; that convention isn't stored in the file.
+ */
+declare function hasData9To12Block(file: AbifFile): boolean;
+/**
+ * Spec-defined role of a DATA<n> tag, limited to the numbers the ABIF spec names:
+ *
+ *   - `'trace'`     — dye-signal channels: DATA1..4 (raw dyes 1-4), DATA9..12
+ *                     (analyzed dyes 1-4), and the two optional 5th-dye blocks
+ *                     DATA105 (raw dye 5) and DATA205 (analyzed dye 5).
+ *   - `'telemetry'` — DATA5..8: instrument run telemetry (voltage, current,
+ *                     power, temperature), one value per scan — NOT dye signal.
+ *   - `'other'`     — any other DATA number. The spec does not enumerate higher
+ *                     extra-dye tags (106/206/…), so we don't claim a role for them.
+ *
+ * A fact from the ABIF specification, not an inference about content.
+ */
+declare function dataChannelRole(n: number): AbifDataChannelRole;
+/**
+ * Whether the file declares its sequence already reverse-complemented, from the
+ * RevC1 flag (int16, non-zero = true). undefined when RevC1 is absent. Reported
+ * as-is; the consumer decides how to act on it.
+ */
+declare function getReverseComplemented(file: AbifFile): boolean | undefined;
+/**
+ * Map from base letter ("A"|"C"|"G"|"T") to the DATA1..4 tag number that holds
+ * its channel, using the dye order declared by FWO_. If FWO_="GATC" then
+ * G→1, A→2, T→3, C→4.
+ *
+ * This follows the file's own FWO_ declaration for the DATA1..4 block; it makes
+ * no claim about whether that block is raw or processed.
+ */
+declare function getChannelMap(file: AbifFile): Record<'A' | 'C' | 'G' | 'T', number>;
+/** Get PBAS sequence (prefer PBAS2 over PBAS1). undefined if neither present. */
+declare function getSequence(file: AbifFile): string | undefined;
+/**
+ * Get per-base Phred-like quality scores (0..255 byte values, typically 0..60
+ * for Sanger). Prefers PCON2 over PCON1.
+ *
+ * PCON is declared in the ABIF spec as elementType=2 (char) but the byte
+ * values ARE the Q-scores — we read raw bytes regardless of declared type.
+ */
+declare function getConfidences(file: AbifFile): number[] | undefined;
+/**
+ * Get peak scan positions (one per base). Prefers PLOC2 over PLOC1.
+ *
+ * Read as UNSIGNED int16: PLOC indexes into the sample trace and is always
+ * non-negative, but values > 32767 (long traces) would wrap to negative
+ * if interpreted as signed.
+ */
+declare function getPositions(file: AbifFile): number[] | undefined;
+/**
+ * Get average peak spacing (samples per base), from SPAC/1.
+ *
+ * ABIF spec defines SPAC as float32 (elementType=7); some legacy files
+ * mislabel it as long (type=5). Both are 4 bytes and on disk the payload
+ * is always a 32-bit float, so we read as float regardless of declared type.
+ *
+ * Returns undefined if SPAC is absent or non-positive.
+ */
+declare function getSamplingRate(file: AbifFile): number | undefined;
 
-export { type AbifBaseCalls, type AbifChromatogramBundle, type AbifDecodedValue, type AbifDirEntry, type AbifEntry, type AbifFile, type AbifMetadata, type ChannelSignals, type Chromatogram, ENTRY_SIZE, HEADER_SIZE, type ParsedAbif, averagePeakSpacing, channelMaxLength, ensureRawDataChannels, findEntries, findEntry, getConfidences, getDataChannel, getFwo, getPositions, getRawChannelMap, getSamplingRate, getSequence, hasProcessedTraces, hasSignals, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif };
+export { type AbifBaseCallRole, type AbifBaseCallVariant, type AbifBaseCalls, type AbifByteRange, type AbifChromatogramBundle, type AbifDataChannelRole, type AbifDecodedValue, type AbifDirEntry, type AbifDirectory, type AbifEntry, type AbifEntryRaw, type AbifFile, type AbifMetadata, type ChannelSignals, type Chromatogram, ENTRY_SIZE, HEADER_SIZE, type ParsedAbif, averagePeakSpacing, channelMaxLength, dataChannelRole, ensureRawDataChannels, findEntries, findEntry, getChannelMap, getConfidences, getDataChannel, getFwo, getPositions, getReverseComplemented, getSamplingRate, getSequence, hasData9To12Block, hasSignals, isFwoPermutation, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif };