@jbrowse/cigar-utils 4.1.14

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2020] [Evolutionary Software Foundation]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,167 @@
+# @jbrowse/cigar-utils
+
+Pure CIGAR / MD / mismatch parsers and types — no rendering or framework deps
+
+<!-- API_DOCS_START -->
+
+## API
+
+Auto-generated from `#api` JSDoc tags in this package. Do not edit by hand.
+
+### buildReadVsRefFeatures
+
+Decompose one alignment record plus its SA tag into the segments of the split
+read, ordered along the read. The layer above `featurizeSA`: it folds the record
+itself in as one more segment, in the same normalized read coordinate space the
+SA entries are put in, and pairs each segment with a `mate` describing its span
+on the read.
+
+This is what the "read vs ref" launchers (linear synteny + dotplot) draw against
+a synthetic read assembly, and what the alignments feature-detail widget lists
+split-read junctions from.
+
+`getCanonicalRefName` resolves each segment's refName against the reference
+assembly's aliases: a BAM whose header says `chr1` against a FASTA whose refName
+is `1` otherwise yields regions no track can be opened on. Optional only because
+a caller may not have the assembly in hand; pass it when you do.
+
+```js
+// type signature
+(feature: ReadVsRefInput, getCanonicalRefName?: ((refName: string) => string | undefined) | undefined) => ReadVsRefFeatures
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/buildReadVsRefFeatures.ts)
+
+### featurizeSAEntries
+
+featurizeSA over pre-split entries (see splitSA). Lets a caller filter the
+entries first — e.g. deduplicating the records repeated across a split read's
+segments — without paying to split and rejoin the tag around the filter.
+
+```js
+// type signature
+(entries: string[], id: string, strand: number | undefined, readName: string | undefined, normalize?: boolean | undefined) => {…}[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### getLength
+
+Length of the read sequence (sum of all ops except D/N).
+
+```js
+// type signature
+(cigar: string) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### getLengthOnRef
+
+Length the read spans on the reference (sum of M/=/X/D/N ops).
+
+```js
+// type signature
+(cigar: string) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### getMismatches
+
+Computes the list of mismatches (SNVs, indels, clips, skips) for a read from its
+CIGAR, optional MD tag, sequence, reference, and quality.
+
+```js
+// type signature
+(cigar?: string | undefined, md?: string | undefined, seq?: string | undefined, ref?: string | undefined, qual?: Uint8Array<ArrayBufferLike> | undefined) => Mismatch[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### getNextRefPos
+
+Maps read-sequence positions to reference-sequence positions via the CIGAR,
+invoking the callback for each. Handles both packed Uint32Array and unpacked
+number[] CIGAR formats.
+
+**Driven by the POSITIONS, not by the read bases.** This used to run an inner
+loop over every base an op spans, testing `positions[currPos] === readPos + j` —
+so it was O(read length) to find something O(positions) in size. On the full
+extent of `200x.longread.mod.bam` that is 43.7 Mbp of read sequence scanned to
+place 0.84M modification calls. Within one op the read-to-reference offset is a
+constant, so each position's answer is one addition and the ops only have to be
+walked once: O(positions + ops).
+`plugins/alignments/benches/cigarWalkShape.bench.ts` prices it at **1.17x on the
+whole per-read modification pipeline**, of which this walk is 45%.
+
+**1.17x is the whole of it, and does not grow on a cleaner alignment.** The
+first reading of that gap was that the op loop caps it — these reads carry 7,000
+ops apiece, and neither shape avoids the op loop. `cigarOpDensity.bench.ts`
+sweeps op density over a 5,000x range and the ratio stays between 1.10x and
+1.18x, so that reading was wrong: what this phase is bound by is the per-CALL
+work both shapes share — the callback, the ML lookup, the compare, the write —
+not the traversal that differs. Changing how the scan is shaped therefore has a
+low ceiling here, however lopsided the iteration counts look.
+
+`positions` must be ASCENDING, which every caller's producer guarantees. The one
+behaviour that changed with the shape: a REPEATED position used to be dropped
+and to block every position after it (the per-base loop could match at most one
+position per base offset), and now emits once per occurrence.
+
+```js
+// type signature
+(cigarOps: ArrayLike<number>, positions: number[], callback: (ref: number, idx: number) => void) => void
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/getNextRefPos.ts)
+
+### parseCigar
+
+Parses a CIGAR string to an alternating `[length, op, ...]` string array.
+
+```js
+// type signature
+(s?: string) => string[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### parseCigar2
+
+Parses a CIGAR string to a packed number array where each value is
+`(length << 4) | opIndex`.
+
+```js
+// type signature
+(s?: string) => number[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### parseCigar2Typed
+
+Same encoding as `parseCigar2` but writes into a packed `Uint32Array` — matches
+the NUMERIC_CIGAR format that BAM/CRAM adapters emit, so consumers can use a
+single typed-array code path.
+
+```js
+// type signature
+(s?: string) => Uint32Array<ArrayBuffer>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+### splitSA
+
+The `;`-separated alignment records of an SA tag, empties dropped — the input
+`featurizeSAEntries` expects.
+
+```js
+// type signature
+(SA: string) => string[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
+
+<!-- API_DOCS_END -->

package/esm/bamSeqDecoder.d.ts

@@ -0,0 +1,3 @@
+export declare const SEQRET = "=ACMGRSVTWYHKDBN";
+export declare const SEQRET_NUMERIC_DECODER: Uint8Array<ArrayBuffer>;
+export declare const CHAR_FROM_CODE: string[];

package/esm/bamSeqDecoder.js

@@ -0,0 +1,10 @@
+// BAM 4-bit encoded sequence lookup table
+export const SEQRET = '=ACMGRSVTWYHKDBN';
+// Numeric decoder - returns char codes directly (lowercase for case-insensitive comparison)
+// '=' = 61, 'a' = 97, 'c' = 99, 'm' = 109, 'g' = 103, 'r' = 114, 's' = 115, 'v' = 118,
+// 't' = 116, 'w' = 119, 'y' = 121, 'h' = 104, 'k' = 107, 'd' = 100, 'b' = 98, 'n' = 110
+export const SEQRET_NUMERIC_DECODER = new Uint8Array([
+    61, 97, 99, 109, 103, 114, 115, 118, 116, 119, 121, 104, 107, 100, 98, 110,
+]);
+// Pre-computed char lookup for ASCII codes (avoids String.fromCharCode in hot loops)
+export const CHAR_FROM_CODE = Array.from({ length: 128 }, (_, i) => String.fromCharCode(i));

package/esm/bamSeqEncoder.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pack a SEQ string into BAM's 4-bit-per-base encoding, two bases per byte with
+ * the first base in the high nibble — the layout `@gmod/bam`'s `forEachMismatchNumeric` reads
+ * via `(byte >> ((1 - (i & 1)) << 2)) & 0xf`. Lets a text source (SAM, a
+ * PSL-derived alignment) drive the same zero-allocation mismatch walk that
+ * BAM's own packed sequence does.
+ */
+export declare function encodeSeqNumeric(seq: string): Uint8Array<ArrayBuffer>;

package/esm/bamSeqEncoder.js

@@ -0,0 +1,33 @@
+import { SEQRET } from './bamSeqDecoder.js';
+// char code -> 4-bit nibble, the inverse of SEQRET. Unrecognized characters
+// (including lowercase, IUPAC codes we don't list, and '.') land on 'N' (15),
+// which the mismatch walk compares equal to nothing.
+const NIBBLE_FROM_CHAR_CODE = (() => {
+    const table = new Uint8Array(128).fill(15);
+    for (let i = 0; i < SEQRET.length; i++) {
+        const code = SEQRET.charCodeAt(i);
+        table[code] = i;
+        table[code | 0x20] = i;
+    }
+    return table;
+})();
+/**
+ * Pack a SEQ string into BAM's 4-bit-per-base encoding, two bases per byte with
+ * the first base in the high nibble — the layout `@gmod/bam`'s `forEachMismatchNumeric` reads
+ * via `(byte >> ((1 - (i & 1)) << 2)) & 0xf`. Lets a text source (SAM, a
+ * PSL-derived alignment) drive the same zero-allocation mismatch walk that
+ * BAM's own packed sequence does.
+ */
+export function encodeSeqNumeric(seq) {
+    const out = new Uint8Array((seq.length + 1) >> 1);
+    for (let i = 0; i < seq.length; i += 2) {
+        const hiCode = seq.charCodeAt(i);
+        const hi = hiCode < 128 ? NIBBLE_FROM_CHAR_CODE[hiCode] : 15;
+        // the odd base of a final unpaired byte reads as '=' (0), which is what a
+        // BAM's own trailing nibble holds
+        const loCode = i + 1 < seq.length ? seq.charCodeAt(i + 1) : -1;
+        const lo = loCode < 0 ? 0 : loCode < 128 ? NIBBLE_FROM_CHAR_CODE[loCode] : 15;
+        out[i >> 1] = (hi << 4) | lo;
+    }
+    return out;
+}

package/esm/buildReadVsRefFeatures.d.ts

@@ -0,0 +1,57 @@
+export interface ReadVsRefMate {
+    refName: string;
+    start: number;
+    end: number;
+    syntenyId: number;
+    uniqueId: string;
+}
+export interface ReadVsRefFeature {
+    refName: string;
+    start: number;
+    end: number;
+    strand: number;
+    CIGAR: string;
+    clipLengthAtStartOfRead: number;
+    uniqueId: string;
+    seqLength?: number;
+    syntenyId: number;
+    mate: ReadVsRefMate;
+    [key: string]: unknown;
+}
+export interface ReadVsRefInput {
+    uniqueId: string;
+    refName: string;
+    start: number;
+    end: number;
+    CIGAR?: string;
+    flags?: number;
+    strand?: number;
+    name?: string;
+    seq?: string;
+    tags?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ReadVsRefFeatures {
+    features: ReadVsRefFeature[];
+    totalLength: number;
+    readName: string;
+    seq: string | undefined;
+}
+/**
+ * #api
+ * Decompose one alignment record plus its SA tag into the segments of the split
+ * read, ordered along the read. The layer above `featurizeSA`: it folds the
+ * record itself in as one more segment, in the same normalized read coordinate
+ * space the SA entries are put in, and pairs each segment with a `mate`
+ * describing its span on the read.
+ *
+ * This is what the "read vs ref" launchers (linear synteny + dotplot) draw
+ * against a synthetic read assembly, and what the alignments feature-detail
+ * widget lists split-read junctions from.
+ *
+ * `getCanonicalRefName` resolves each segment's refName against the reference
+ * assembly's aliases: a BAM whose header says `chr1` against a FASTA whose
+ * refName is `1` otherwise yields regions no track can be opened on. Optional
+ * only because a caller may not have the assembly in hand; pass it when you do.
+ */
+export declare function buildReadVsRefFeatures(feature: ReadVsRefInput, getCanonicalRefName?: (refName: string) => string | undefined): ReadVsRefFeatures;

package/esm/buildReadVsRefFeatures.js

@@ -0,0 +1,66 @@
+import { featurizeSA, getClip, getLength, getLengthSansClipping, } from './mismatchParser.js';
+import { SAM_FLAG_SUPPLEMENTARY } from './samFlags.js';
+/**
+ * #api
+ * Decompose one alignment record plus its SA tag into the segments of the split
+ * read, ordered along the read. The layer above `featurizeSA`: it folds the
+ * record itself in as one more segment, in the same normalized read coordinate
+ * space the SA entries are put in, and pairs each segment with a `mate`
+ * describing its span on the read.
+ *
+ * This is what the "read vs ref" launchers (linear synteny + dotplot) draw
+ * against a synthetic read assembly, and what the alignments feature-detail
+ * widget lists split-read junctions from.
+ *
+ * `getCanonicalRefName` resolves each segment's refName against the reference
+ * assembly's aliases: a BAM whose header says `chr1` against a FASTA whose
+ * refName is `1` otherwise yields regions no track can be opened on. Optional
+ * only because a caller may not have the assembly in hand; pass it when you do.
+ */
+export function buildReadVsRefFeatures(feature, getCanonicalRefName) {
+    const { CIGAR: cigar = '', flags = 0, strand, name: readName = '', seq, tags, uniqueId, } = feature;
+    const SA = tags?.SA;
+    const suppAlns = featurizeSA(typeof SA === 'string' ? SA : undefined, uniqueId, strand, readName, true);
+    // getClip(cigar, 1), not getClip(cigar, strand): `normalize` puts every SA
+    // entry in the *query's reference orientation*, so the record itself has to be
+    // measured in that frame too. Measuring it in the read's own 5'->3' frame
+    // reads the clip off the far end of a reverse-strand CIGAR, which drops the
+    // primary into the wrong place along the read and mis-sorts the segments.
+    const clipLengthAtStartOfRead = getClip(cigar, 1);
+    const primary = {
+        ...feature,
+        clipLengthAtStartOfRead,
+        strand: 1,
+        mate: {
+            refName: readName,
+            start: clipLengthAtStartOfRead,
+            end: clipLengthAtStartOfRead + getLengthSansClipping(cigar),
+        },
+    };
+    // A supplementary CIGAR covers only its own slice of the read, so its own
+    // length is the read length only when the aligner emitted the clipping ops.
+    // SA[0] is the primary by convention. `?? cigar` covers a supplementary with
+    // no SA tag at all, which has nothing better to measure against.
+    const totalLength = getLength((flags & SAM_FLAG_SUPPLEMENTARY ? suppAlns[0]?.CIGAR : undefined) ?? cigar);
+    const features = [primary, ...suppAlns]
+        .sort((a, b) => a.clipLengthAtStartOfRead - b.clipLengthAtStartOfRead)
+        // syntenyId is assigned after the sort so it also reads as the segment's
+        // index along the read; the mate shares it, which is how the synteny
+        // renderer pairs the two sides of one alignment.
+        .map((f, idx) => ({
+        ...f,
+        refName: getCanonicalRefName?.(f.refName) ?? f.refName,
+        syntenyId: idx,
+        mate: { ...f.mate, syntenyId: idx, uniqueId: `${f.uniqueId}_mate` },
+    }));
+    return {
+        features,
+        totalLength,
+        readName,
+        // Only hand back bases that line up with the read coordinate system the
+        // synthetic assembly is built in. A hard-clipped supplementary's SEQ is its
+        // own slice, and the sequence track would show it at the wrong offset with
+        // nothing marking it as partial; no sequence beats a wrong one.
+        seq: seq && seq.length >= totalLength ? seq : undefined,
+    };
+}

package/esm/cigarConstants.d.ts

@@ -0,0 +1,11 @@
+export declare const CIGAR_M = 0;
+export declare const CIGAR_I = 1;
+export declare const CIGAR_D = 2;
+export declare const CIGAR_N = 3;
+export declare const CIGAR_S = 4;
+export declare const CIGAR_H = 5;
+export declare const CIGAR_P = 6;
+export declare const CIGAR_EQ = 7;
+export declare const CIGAR_X = 8;
+export declare const CIGAR_M_EQ_MASK = 129;
+export declare const CIGAR_INDEL_MASK = 14;

package/esm/cigarConstants.js

@@ -0,0 +1,15 @@
+// CIGAR operation indices from BAM spec (used in packed Uint32Array format: len<<4|op)
+export const CIGAR_M = 0;
+export const CIGAR_I = 1;
+export const CIGAR_D = 2;
+export const CIGAR_N = 3;
+export const CIGAR_S = 4;
+export const CIGAR_H = 5;
+export const CIGAR_P = 6;
+export const CIGAR_EQ = 7;
+export const CIGAR_X = 8;
+// Bitmask for CIGAR operation categories (use with: (1 << op) & MASK)
+// Alignment match ops (M=0, ==7) — may contain mismatches, need MD tag
+export const CIGAR_M_EQ_MASK = 0b10000001; // (1<<0)|(1<<7) = 129
+// Indel ops (I=1, D=2, N=3) — each consumes only one axis (a gap on the other)
+export const CIGAR_INDEL_MASK = 0b00001110; // (1<<1)|(1<<2)|(1<<3) = 14

package/esm/cigarRenderedSegments.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Walks pre-parsed (packed int) CIGAR ops in bp-space and fires a callback
+ * for each rendered segment. Small indels (width < MIN_INDEL_PX) are merged
+ * into surrounding context; tiny M segments (both accumulators advance <
+ * bpPerPx) are accumulated before emitting.
+ *
+ * Used by synteny and dotplot GPU renderers so both stay in sync.
+ * Re-exported via @jbrowse/synteny-core for consistent import paths.
+ *
+ * Callback receives bp-space segment boundaries (cumBp, no inter-region
+ * padding). Callers convert to screen positions with hp-math.
+ */
+export declare function visitCigarRenderedSegments(cigar: ArrayLike<number>, startBp1: number, startBp2: number, bpPerPx0: number, bpPerPx1: number, rev1: number, rev2: number, callback: (op: number, segBp1Start: number, segBp1End: number, segBp2Start: number, segBp2End: number) => void): void;