@libraz/libcantus 0.9.4 → 1.0.0

package/dist/index-BGFW-8P2.d.cts

@@ -0,0 +1,2307 @@
+import { a as Articulation, g as NoteEvent, d as KeyScale } from './index-B9MNZboQ.cjs';
+import { S as SeedPath, d as PositionalRng, I as InstrumentProfile, f as StringedProfile } from './positional-DvH_sd8u.cjs';
+import { T as TimeSignature } from './index-BkGmlyI3.cjs';
+import { d as ChordQuality, e as ChordSegment, c as ChordLike, K as KeyLike, b as Chord, m as ProfileWeights, g as ChordSpan } from './index-C_8o--VE.cjs';
+import { e as ChordTimeline, B as BorrowedSource, H as HarmonicFunction } from './index-Dzr13q3d.cjs';
+import { H as HarmonyRole } from './index-B4o55NDr.cjs';
+
+/**
+ * The samplers a generator needs, each addressed by the position it is drawing
+ * for rather than by how many draws came before it.
+ *
+ * Every method is a pure function of the source and the path: asking twice
+ * gives the same answer, asking in a different order changes nothing, and a
+ * position nobody asks about costs nothing. That is what lets a caller change
+ * one parameter — or one bar — without redrawing the rest of the piece.
+ *
+ * @category Composition
+ */
+type Draw = {
+    /** The raw draw at a position: a float in [0, 1). */
+    at: (...path: SeedPath) => number;
+    /**
+     * Whether an event of probability `p` happens at a position. Because the
+     * underlying draw is fixed by the path, raising `p` only ever turns more
+     * positions on.
+     */
+    prob: (p: number, ...path: SeedPath) => boolean;
+    /** An integer in the inclusive range [lo, hi] at a position. */
+    range: (lo: number, hi: number, ...path: SeedPath) => number;
+    /** A float in [lo, hi) at a position. */
+    float: (lo: number, hi: number, ...path: SeedPath) => number;
+};
+
+/** Internal drum style selected by the public groove style. */
+type DrumStyle = 'sparse' | 'standard' | 'fourOnFloor' | 'upbeat' | 'rock' | 'synth' | 'trap' | 'latin';
+/** Every groove feel, in declaration order. */
+declare const DRUM_FEELS: readonly ["straight", "swing", "shuffle"];
+/** Groove feel controlling off-beat swing. */
+type Feel = (typeof DRUM_FEELS)[number];
+/**
+ * Groove feel (the swing/straight rhythmic character), under the name the
+ * public surface uses.
+ *
+ * @category Composition
+ */
+type GrooveFeel = Feel;
+/**
+ * Every public groove style, in declaration order. The type is derived from
+ * this list so the runtime guard and the type can never disagree.
+ */
+declare const GROOVE_STYLES: readonly ["standard", "funk", "shuffle", "bossa", "trap", "halftime", "breakbeat", "house", "synthpop"];
+/**
+ * Public groove style identifiers.
+ *
+ * @category Composition
+ */
+type GrooveStyle = (typeof GROOVE_STYLES)[number];
+/** Every public role, in declaration order. */
+declare const DRUM_ROLES: readonly ["full", "ambient", "minimal", "fxOnly"];
+/**
+ * Public role identifiers gating which voices are present.
+ *
+ * @category Composition
+ */
+type DrumRole = (typeof DRUM_ROLES)[number];
+/** Every public section, in declaration order. */
+declare const PUBLIC_SECTIONS: readonly ["intro", "verse", "prechorus", "chorus", "bridge", "outro"];
+/**
+ * Public section identifiers for {@link generateDrums}.
+ *
+ * These are the names a caller writes. The generator maps them onto a
+ * narrower internal set the pattern tables are keyed by, which answers to
+ * `'a'` and `'b'` and refuses `'verse'` and `'prechorus'`. That set is not
+ * published: a caller who reached for it by name would be held to a
+ * vocabulary that is not this one.
+ *
+ * @category Composition
+ */
+type Section = (typeof PUBLIC_SECTIONS)[number];
+
+/**
+ * The shared vocabulary model: a remembered figure, plus the conditions under
+ * which a player would reach for it.
+ *
+ * A rule-based generator can build a correct line and still sound characterless,
+ * because a player does not synthesise from scales — they assemble figures they
+ * already know. Those figures are not derivable, so they are held as data here:
+ * one record per figure, carrying its own applicability conditions, so choosing
+ * one is a deterministic lookup rather than a branch in a generator.
+ *
+ * ## Provenance
+ *
+ * No entry may reproduce a phrase from a particular recorded song. Only figures
+ * that belong to nobody are admitted — the common currency of a genre, the
+ * things every player of that music already plays. Every entry records which
+ * basis it qualifies under in {@link Vocabulary.provenance}, and the field is
+ * required so the judgment cannot be skipped while curating.
+ */
+
+/**
+ * Every genre the built-in dictionaries name, in declaration order.
+ *
+ * The list is open in spirit even though the type is closed: a caller with a
+ * genre of its own supplies entries through the generation context rather than
+ * waiting for this list to grow.
+ *
+ * @category Composition
+ */
+declare const GENRES: readonly ["pop", "rock", "motown", "funk", "soul", "gospel", "jazz", "blues", "bossa", "samba", "reggae", "country", "hiphop", "house", "dnb"];
+/**
+ * The genre a figure belongs to. Genre is what selects material; it never
+ * deforms or rejects it.
+ *
+ * @category Composition
+ */
+type Genre = (typeof GENRES)[number];
+/**
+ * Every ground on which a figure may enter a dictionary, in declaration order.
+ *
+ * - `'idiom'`: a genre-defining figure no one owns, played by every player of
+ *   that music — a backbeat, a walking approach, a two-and-four side stick.
+ * - `'construction'`: derived here from the genre's rhythmic grid rather than
+ *   remembered from any performance.
+ * - `'traditional'`: from a folk or traditional repertoire with no author.
+ *
+ * @category Composition
+ */
+declare const PROVENANCE_BASES: readonly ["idiom", "construction", "traditional"];
+/**
+ * The ground on which a figure qualifies for a dictionary.
+ *
+ * @category Composition
+ */
+type ProvenanceBasis = (typeof PROVENANCE_BASES)[number];
+/**
+ * Why a figure may be published as vocabulary.
+ *
+ * @category Composition
+ */
+type Provenance = {
+    /** Which ground the figure qualifies under. */
+    basis: ProvenanceBasis;
+    /**
+     * What the figure is, in the terms a player would use — "the genre's
+     * two-and-four side stick", not the name of a record it appears on.
+     */
+    note: string;
+};
+/**
+ * One remembered figure, together with the conditions it fits.
+ *
+ * The optional conditions are read as "no restriction" when absent: an entry
+ * with no `sections` fits every section, one with no `tempoRange` fits every
+ * tempo. {@link Vocabulary.difficulty} is on the same 1..5 scale as the
+ * playability report, and is compared against the difficulty ceiling: an entry
+ * harder than the ceiling is rejected, never simplified in place.
+ *
+ * @typeParam T - The material this kind of figure is made of: chord-relative
+ *   degrees for a bass lick, voices on a grid for a drum pattern.
+ *
+ * @category Composition
+ */
+type Vocabulary<T> = {
+    /** Stable identifier; a caller entry with the same id replaces a built-in. */
+    id: string;
+    genre: Genre;
+    /** The figure itself. */
+    material: T;
+    /**
+     * How the figure is played, over and above the material's own strokes.
+     *
+     * These are requirements, not decoration: where a query names the techniques
+     * the instrument can produce, an entry asking for one the instrument does not
+     * have is not offered. A kit with no flam is never handed flam material.
+     */
+    articulations: Articulation[];
+    /** Chord qualities the figure works over; absent means any chord. */
+    fitsOver?: ChordQuality[];
+    /** Sections the figure suits; absent means any section. */
+    sections?: Section[];
+    /** Inclusive tempo band in BPM; absent means any tempo. */
+    tempoRange?: [number, number];
+    /** Time signature the figure is written in; absent means any. */
+    ts?: TimeSignature;
+    /** How hard the figure is to play, from 1 to 5. */
+    difficulty: number;
+    /** Why this figure may be published; see the module documentation. */
+    provenance: Provenance;
+};
+/**
+ * What a generator knows about the moment it is choosing a figure for.
+ *
+ * Every field is optional and an absent field asks nothing: a query with no
+ * genre matches every genre, exactly as an entry with no `sections` matches
+ * every section.
+ *
+ * @category Composition
+ */
+type VocabularyQuery = {
+    genre?: Genre;
+    section?: Section;
+    /** Tempo in BPM, matched against each entry's band. */
+    bpm?: number;
+    ts?: TimeSignature;
+    /** The difficulty ceiling: entries above it are rejected. */
+    difficulty?: number;
+    /** The chord in force, matched against each entry's `fitsOver`. */
+    quality?: ChordQuality;
+    /**
+     * The techniques the instrument this part is written for can produce, from
+     * its profile. An entry asking for one that is not here is not offered;
+     * absent asks nothing, which is the programmed case.
+     */
+    articulations?: readonly Articulation[];
+};
+/**
+ * Whether one entry answers a query.
+ *
+ * @param entry The dictionary entry.
+ * @param query What the generator knows about the moment.
+ * @returns True when every condition the entry states is met.
+ *
+ * @category Composition
+ */
+declare function fitsQuery<T>(entry: Vocabulary<T>, query: VocabularyQuery): boolean;
+/**
+ * Every entry of a dictionary that answers a query, in dictionary order.
+ *
+ * Order is preserved so a selection made from the result is reproducible: the
+ * same dictionary and the same query always offer the same candidates in the
+ * same positions.
+ *
+ * @param dictionary The entries to search.
+ * @param query What the generator knows about the moment.
+ * @returns The matching entries, in the order they appear in the dictionary.
+ *
+ * @example
+ * ```ts
+ * import { BASS_LICKS, selectVocabulary } from '@libraz/libcantus';
+ * const candidates = selectVocabulary(BASS_LICKS, { genre: 'motown', difficulty: 3 });
+ * ```
+ *
+ * @category Composition
+ */
+declare function selectVocabulary<T>(dictionary: readonly Vocabulary<T>[], query: VocabularyQuery): Vocabulary<T>[];
+/**
+ * Choose one entry from a dictionary at a position.
+ *
+ * The choice is addressed by the path, not by how many choices came before it,
+ * so the figure at bar 12 does not move because the figure at bar 3 changed.
+ *
+ * @param dictionary The entries to choose from.
+ * @param query What the generator knows about the moment.
+ * @param draw The position-addressed sampler.
+ * @param path Where the choice is being made.
+ * @returns The chosen entry, or undefined when nothing fits.
+ *
+ * @category Composition
+ */
+declare function pickVocabulary<T>(dictionary: readonly Vocabulary<T>[], query: VocabularyQuery, draw: Draw, ...path: readonly (string | number)[]): Vocabulary<T> | undefined;
+/**
+ * Merge a caller's dictionary into a built-in one.
+ *
+ * Caller entries are appended, so every built-in figure stays reachable, except
+ * where a caller entry carries the id of a built-in: that one is a replacement
+ * and takes the built-in's place, which is how a caller corrects a figure it
+ * disagrees with rather than having both offered.
+ *
+ * @param builtIn The library's own entries.
+ * @param supplied The caller's entries, if any.
+ * @returns The merged dictionary, built-ins first.
+ *
+ * @category Composition
+ */
+declare function mergeVocabulary<T>(builtIn: readonly Vocabulary<T>[], supplied: readonly Vocabulary<T>[] | undefined): Vocabulary<T>[];
+/**
+ * Narrow a mixed dictionary to the entries one part understands.
+ *
+ * A context carries a single list, because a caller thinks in terms of "the
+ * vocabulary of this piece" rather than of one list per generator. Each
+ * generator recognises its own material by shape, so an entry meant for the
+ * bass is invisible to the drums instead of being mis-read by it.
+ *
+ * @param entries The mixed dictionary.
+ * @param isMaterial Guard recognising one kind of material.
+ * @returns The entries whose material the guard accepts.
+ *
+ * @category Composition
+ */
+declare function vocabularyOfKind<T>(entries: readonly Vocabulary<unknown>[], isMaterial: (material: unknown) => material is T): Vocabulary<T>[];
+/**
+ * Reject a dictionary entry whose declared fields are outside their domains.
+ *
+ * Applied to caller-supplied entries at the point they enter a generator: an
+ * entry with a difficulty of 40 would otherwise pass every ceiling and be
+ * chosen for a beginner's part.
+ *
+ * @param entry The entry to check.
+ * @param label Name used in the error message.
+ * @returns The entry, unchanged.
+ * @throws If the difficulty is outside 1..5 or the tempo band is inverted.
+ *
+ * @category Composition
+ */
+declare function assertVocabulary<T>(entry: Vocabulary<T>, label?: string): Vocabulary<T>;
+
+/**
+ * The generation context: one seed, one set of dials, one tempo, shared by
+ * every generator.
+ *
+ * Before it, each generator carried its own idea of "how involved should this
+ * be" — a 0..1 density here, a style name there, a boolean somewhere else — and
+ * only the drums knew the tempo. A context names those things once, so a piece
+ * can be asked for at a given complexity in one place, and every part derives
+ * its own randomness from the same project seed.
+ */
+
+/**
+ * How involved the generated music should be, on axes that do not imply one
+ * another.
+ *
+ * The first three ask for more of something and are continuous: moving one of
+ * them adds material without disturbing what is already sounding.
+ * {@link Complexity.difficulty} is not one of those — it is a ceiling, and it
+ * only ever takes candidates away.
+ *
+ * @category Composition
+ */
+type Complexity = {
+    /** Subdivision and syncopation, in [0, 1]. */
+    rhythmic?: number;
+    /** Tension, substitution and passing chords, in [0, 1]. */
+    harmonic?: number;
+    /** Ghosts, flams and decoration, in [0, 1]. */
+    ornament?: number;
+    /**
+     * The hardest the result may be to play, from 1 (a beginner's part) to 5 (at
+     * the limit of the instrument). It is a ceiling rather than a strength:
+     * "involved but easy" and "plain but hard" are both real requests, so this
+     * filters what the other three proposed instead of scaling it. It governs the
+     * timing layer alone — whether the note exists on the instrument, and whether
+     * the shape can be held, follow from {@link GenerationContext.instruments} and
+     * apply whatever the ceiling says.
+     */
+    difficulty?: number;
+};
+/**
+ * Everything a generator needs that is not about the notes themselves.
+ *
+ * @category Composition
+ */
+type GenerationContext = {
+    /**
+     * The project seed every part derives its own randomness from. Optional, and
+     * zero when left out: a context naming only a tempo is a whole request, and
+     * requiring the seed beside it would make the commonest context unwritable
+     * now that it is the only place a seed can go.
+     */
+    seed?: number;
+    /** The dials; see {@link Complexity}. */
+    complexity?: Complexity;
+    /**
+     * Draw from this source instead of one derived from `seed`. Each part still
+     * addresses its own namespace, so parts do not collide.
+     */
+    rng?: PositionalRng;
+    /**
+     * The instruments the parts are written for, keyed by part name — `'bass'`,
+     * `'drums'`. Naming one is itself the request that the part be playable on
+     * it, so its range and physical limits always apply.
+     */
+    instruments?: Record<string, InstrumentProfile>;
+    /**
+     * Tempo in quarter-note beats per minute. Without it no generator can judge
+     * whether a passage is reachable in the time available, so a ceiling on
+     * difficulty has nothing to measure against.
+     */
+    bpm?: number;
+    /**
+     * The algorithm version to generate under; defaults to the version this build
+     * produces. See {@link resolveAlgorithmVersion} for what the number promises.
+     */
+    algorithmVersion?: number;
+    /**
+     * Figures this piece may draw on, over and above the library's own.
+     *
+     * Genres are endless, which is the reason the vocabulary is data at all: a
+     * caller brings the dictionary for the music it is writing instead of waiting
+     * for the library to grow one. Entries for every part travel in one list —
+     * each generator recognises its own material by shape — and an entry carrying
+     * the id of a built-in replaces it rather than being offered alongside.
+     */
+    vocabulary?: readonly Vocabulary<unknown>[];
+};
+/**
+ * A context, or just the seed for one.
+ *
+ * A bare number is sugar for `{ seed }`: the common case is a caller who wants
+ * reproducible output and nothing else.
+ *
+ * @category Composition
+ */
+type GenerationContextInput = GenerationContext | number;
+/**
+ * A context with everything resolved: dials validated, tempo and ceiling
+ * settled, and a positional source ready for each part.
+ */
+type ResolvedContext = {
+    seed: number;
+    /** Requested rhythmic density, or undefined when the caller named none. */
+    rhythmic: number | undefined;
+    /** Requested harmonic richness, or undefined when the caller named none. */
+    harmonic: number | undefined;
+    /** Requested ornament density, or undefined when the caller named none. */
+    ornament: number | undefined;
+    /** The difficulty ceiling, or undefined for no ceiling. */
+    difficulty: number | undefined;
+    /** Tempo in BPM, or undefined when the caller named none. */
+    bpm: number | undefined;
+    /** The resolved algorithm version. */
+    algorithmVersion: number;
+    /** The profile written for a part, if one was named for it. */
+    instrument: (part: string) => InstrumentProfile | undefined;
+    /** The figures the caller brought, validated; empty when it brought none. */
+    vocabulary: readonly Vocabulary<unknown>[];
+    /** The position-addressed samplers for a part. */
+    part: (name: string) => Draw;
+};
+/**
+ * Resolve a context (or a bare seed) into the form the generators use.
+ *
+ * The algorithm version takes part in every derivation, so two versions never
+ * share a draw: pinning one is what makes a saved project reopen as the piece
+ * it was, and a version this build does not produce is rejected rather than
+ * quietly rendered as another.
+ *
+ * @param input The context, the seed alone, or nothing.
+ * @returns The resolved context.
+ * @throws If the seed is not a 32-bit integer, a dial is out of range, the
+ *   tempo is not positive, or the algorithm version is unknown.
+ * @example
+ * ```ts
+ * import { resolveContext } from '@libraz/libcantus';
+ * const ctx = resolveContext({ seed: 42, complexity: { rhythmic: 0.8 }, bpm: 96 });
+ * ctx.part('drums').prob(0.5, 'ghost', 1, 2); // the same answer however often it is asked
+ * ```
+ */
+declare function resolveContext(input?: GenerationContextInput): ResolvedContext;
+
+/**
+ * The transformation rules that deform a remembered figure into the one this
+ * bar needs.
+ *
+ * The division of labour is the whole point of keeping these separate from the
+ * dictionary: **genre selects the material, complexity deforms it, difficulty
+ * rejects it.** A transform therefore never consults a genre and never consults
+ * a ceiling — it takes the figure it is given and reshapes it, and whether the
+ * result is playable is decided afterwards, by {@link withinCeiling}.
+ *
+ * Every figure is a list of onsets on a sixteenth grid, whatever it is made of,
+ * so the rules are written once and used by both the bass and the drums.
+ */
+
+/** Sixteenth steps in one 4/4 bar; the grid every figure is written on. */
+declare const BAR_STEPS = 16;
+/** Sixteenth steps in one quarter-note beat. */
+declare const BEAT_STEPS = 4;
+/** One sixteenth expressed in quarter-note beats. */
+declare const STEP_BEATS: number;
+/**
+ * An onset on the shared sixteenth grid.
+ *
+ * Both kinds of material are lists of these with their own extra fields, so a
+ * transform is generic over the record and only ever reads the fields named
+ * here.
+ *
+ * @category Composition
+ */
+type GridEvent = {
+    /** Sixteenth-note index from the start of the figure. */
+    step: number;
+    /** Loudness as a factor of the passage's base velocity. */
+    velocity: number;
+    /**
+     * The voice this onset is played on, where the material has more than one.
+     * A figure written for a single voice — a bass lick — leaves it out.
+     */
+    voice?: string;
+    /**
+     * The limb that plays it, where the material names one. It outranks
+     * {@link GridEvent.voice} as the stream an onset belongs to, since what
+     * crowds a player is one limb rather than one drum.
+     */
+    limb?: string;
+};
+/**
+ * How strongly a position on the sixteenth grid is felt, from 4 (the downbeat)
+ * to 0 (an off sixteenth).
+ *
+ * This is the ranking the thinning rule works down: the notes a player drops
+ * first when asked for something easier are the ones carrying the least of the
+ * metre. It is named for the grid it reads because the analysis layer has a
+ * metric weight of its own, on another scale and against a time signature; the
+ * two answer different questions and are deliberately not the same function.
+ *
+ * @param step Sixteenth index within the bar.
+ * @returns The weight, 0 to 4.
+ *
+ * @category Composition
+ */
+declare function gridMetricWeight(step: number): number;
+/**
+ * Drop the notes carrying the least of the metre.
+ *
+ * The easing direction: at 0 nothing is dropped, and as the amount rises whole
+ * ranks of positions go, off sixteenths first and the downbeat last. It is a
+ * ranking rather than a sampling, so the same amount always removes the same
+ * notes and a caller can explain which ones went.
+ *
+ * @param events The figure.
+ * @param amount How much to thin, in [0, 1].
+ * @returns The surviving events, in the order given.
+ *
+ * @category Composition
+ */
+declare function thin<T extends GridEvent>(events: readonly T[], amount: number): T[];
+/**
+ * Fill in the gaps of a figure, one note per gap.
+ *
+ * Doubling is what a player does when asked for more of the same rather than
+ * for something different: the added note sits halfway between two the figure
+ * already has, takes its predecessor's identity, and is played softer.
+ *
+ * @param events The figure, which need not be sorted.
+ * @param spanSteps Length of the figure in sixteenths.
+ * @returns The figure with the midpoints filled, sorted by position.
+ *
+ * @category Composition
+ */
+declare function double<T extends GridEvent>(events: readonly T[], spanSteps?: number): T[];
+/**
+ * Stretch a figure to twice its length: everything falls half as often.
+ *
+ * @param events The figure.
+ * @param spanSteps Length of the figure in sixteenths; notes stretched past it
+ *   are dropped, since the bar is the bar however the figure is felt.
+ * @returns The stretched figure.
+ *
+ * @category Composition
+ */
+declare function halfTime<T extends GridEvent>(events: readonly T[], spanSteps?: number): T[];
+/**
+ * Compress a figure to half its length and play it twice.
+ *
+ * The repeat is what makes this the mirror of {@link halfTime} rather than a
+ * figure with a hole in it: the bar stays full.
+ *
+ * @param events The figure.
+ * @param spanSteps Length of the figure in sixteenths.
+ * @returns The compressed figure, repeated to fill the span.
+ *
+ * @category Composition
+ */
+declare function doubleTime<T extends GridEvent>(events: readonly T[], spanSteps?: number): T[];
+/**
+ * Anticipate beats, one sixteenth early.
+ *
+ * Anticipation is the direction syncopation runs in every genre this library
+ * names: the note arrives before the beat it belongs to. It is written as an
+ * addition rather than a displacement — the anticipating stroke is softer, and
+ * the note it anticipates stays where it was, the way a player ties into the
+ * beat rather than abandoning it — because this is one of the dials that only
+ * ever add material. Displacing instead would move onsets around under the
+ * finger of anyone who puts the dial on a slider, and a saved project reopened
+ * one notch along would not contain the piece it was. Which beats are
+ * anticipated is fixed by position, so the bar next door is unaffected either
+ * way.
+ *
+ * A position already taken blocks the anticipation only within the same stream
+ * — the same limb, else the same voice. A ghost snare sitting where the hi-hat
+ * wants to anticipate is another hand playing, not an obstacle, and whether two
+ * limbs can actually strike together is the playability layer's question rather
+ * than this one's.
+ *
+ * @param events The figure.
+ * @param amount How much syncopation, in [0, 1].
+ * @param draw The position-addressed sampler.
+ * @param path Where the figure sits, so the same bar always syncopates alike.
+ * @returns The figure with its anticipations, sorted by position.
+ *
+ * @category Composition
+ */
+declare function syncopate<T extends GridEvent>(events: readonly T[], amount: number, draw: Draw, ...path: readonly (string | number)[]): T[];
+/**
+ * How much decoration a figure keeps.
+ *
+ * A decorated note — a ghost, a flam, anything the figure marks as ornament —
+ * survives on its own draw, so raising the dial only ever brings more of them
+ * back and never disturbs the ones already sounding. Notes that are not
+ * decoration are untouched.
+ *
+ * @param events The figure.
+ * @param isOrnament Which events count as decoration.
+ * @param amount The ornament dial, in [0, 1].
+ * @param draw The position-addressed sampler.
+ * @param path Where the figure sits.
+ * @returns The figure with the surviving decoration.
+ *
+ * @category Composition
+ */
+declare function ornamentBy<T extends GridEvent>(events: readonly T[], isOrnament: (event: T) => boolean, amount: number, draw: Draw, ...path: readonly (string | number)[]): T[];
+/**
+ * Everything the complexity dials do to a figure, in one pass.
+ *
+ * @category Composition
+ */
+type DeformOptions = {
+    /**
+     * Subdivision and syncopation, in [0, 1]. Below the neutral middle the figure
+     * is thinned; above it, syncopated. The middle leaves it as the dictionary
+     * wrote it, which is what makes the dictionary the thing a reader can check.
+     */
+    rhythmic?: number;
+    /** Ghosts and decoration, in [0, 1]; absent keeps every ornament. */
+    ornament?: number;
+    /** Which events are decoration, for the ornament dial. */
+    isOrnament?: (event: GridEvent) => boolean;
+    /**
+     * Rate: stretch or compress the figure before the dials are applied. It is
+     * named for what it does to the note values, since "feel" elsewhere in the
+     * drum surface names the swing a figure is played with — a different
+     * question, asked of the same figure.
+     */
+    rate?: 'straight' | 'half' | 'double';
+    /** Length of the figure in sixteenths. */
+    spanSteps?: number;
+};
+/**
+ * Apply the complexity dials to a figure.
+ *
+ * This is the one place complexity touches vocabulary: genre has already chosen
+ * the material, and the ceiling has not been consulted yet.
+ *
+ * @param events The figure.
+ * @param opts What the dials say.
+ * @param draw The position-addressed sampler.
+ * @param path Where the figure sits.
+ * @returns The deformed figure, sorted by position.
+ *
+ * @example
+ * ```ts
+ * import { deform, resolveContext } from '@libraz/libcantus';
+ * const figure = [
+ *   { step: 0, velocity: 1, limb: 'kick' },
+ *   { step: 4, velocity: 0.9, limb: 'snare' },
+ *   { step: 8, velocity: 1, limb: 'kick' },
+ *   { step: 12, velocity: 0.9, limb: 'snare' },
+ * ];
+ * const draw = resolveContext(7).part('drums');
+ * const busier = deform(figure, { rhythmic: 0.9 }, draw, 'bar', 0);
+ * // Above the neutral middle the figure is syncopated: onsets are added off
+ * // the beat, and the result comes back sorted by position.
+ * busier.length; // 7
+ * busier.map((event) => event.step); // [0, 3, 4, 7, 8, 11, 12]
+ * ```
+ *
+ * @category Composition
+ */
+declare function deform<T extends GridEvent>(events: readonly T[], opts: DeformOptions, draw: Draw, ...path: readonly (string | number)[]): T[];
+/**
+ * Whether a figure is inside the difficulty ceiling at this tempo.
+ *
+ * The ceiling is measured against the closest pair of onsets the figure asks
+ * one player for, which is the thing that actually stops a hand — so the pairs
+ * are counted within a stream (the limb, else the voice) rather than across the
+ * whole kit, because a hi-hat and a kick a sixteenth apart are two limbs and not
+ * one hand playing twice. A figure that fails is rejected — never quietly
+ * simplified, because a simplified figure is a different figure and the caller
+ * asked for this one.
+ *
+ * @param events The figure.
+ * @param bpm Tempo, or undefined when the caller gave none.
+ * @param difficulty The ceiling, or undefined for no ceiling.
+ * @returns True when the figure is playable at the ceiling, and whenever either
+ *   the ceiling or the tempo is unknown.
+ *
+ * @category Composition
+ */
+declare function withinCeiling(events: readonly GridEvent[], bpm: number | undefined, difficulty: number | undefined): boolean;
+
+/**
+ * Deterministic bass-line generation over a chord placement.
+ *
+ * Given a sequence of chord segments and a key, this builds a monophonic bass
+ * line in a chosen low register. Several idiomatic styles are supported, from a
+ * single held root per segment to a quarter-note walking line that leads by
+ * step into each chord change. All pitches are kept in a narrow bass band and
+ * consecutive notes move by small intervals; given a seed the output is fully
+ * reproducible.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention.
+ */
+
+/**
+ * A chord sounding over a half-open beat span `[startBeat, endBeat)`.
+ *
+ * The same record {@link ChordSegment} names, so a timeline segment can be fed
+ * straight to the bass generator.
+ *
+ * @category Composition
+ */
+type BassSegment = ChordSegment;
+/**
+ * Every bass-line idiom, in declaration order.
+ *
+ * @category Composition
+ */
+declare const BASS_STYLES: readonly ["root", "rootFifth", "pop", "walking", "arpeggio"];
+/**
+ * The bass-line idiom to generate.
+ *
+ * @category Composition
+ */
+type BassStyle = (typeof BASS_STYLES)[number];
+/**
+ * Options controlling {@link generateBassLine}.
+ *
+ * @category Composition
+ */
+type BassLineOptions = {
+    /**
+     * Chord placement to follow; need not be pre-sorted. Each segment's chord may
+     * be written as a chord symbol as well as given as chord data.
+     */
+    segments: readonly (Omit<BassSegment, 'chord'> & {
+        chord: ChordLike;
+    })[];
+    /**
+     * Key/scale context, used for diatonic approach tones in `walking`. A key
+     * name such as `'C major'` is read as that key.
+     */
+    key: KeyLike;
+    /**
+     * Time signature; used for metric accents.
+     *
+     * @defaultValue `{ numerator: 4, denominator: 4 }`
+     */
+    ts?: TimeSignature;
+    /**
+     * Bass-line idiom.
+     *
+     * @defaultValue `'root'`
+     */
+    style?: BassStyle;
+    /**
+     * Target register as a base MIDI octave; roots land around `octave*12+12`.
+     * An octave pickup in the `pop` style may drop a note into the octave below
+     * that band, which is where such a pickup belongs.
+     *
+     * @defaultValue 2
+     */
+    octave?: number;
+    /**
+     * The instrument the line is written for. Giving one is itself the request
+     * that the line be playable on it: `octave` then says where in that
+     * instrument to aim rather than which absolute band to use, and where the two
+     * disagree the instrument wins — a note below the lowest string comes back an
+     * octave up, the way a player would take it. Leave it out for a programmed
+     * part, which is generated exactly as before.
+     */
+    instrument?: StringedProfile;
+    /**
+     * The generation context. Its `complexity.rhythmic` sets how often the `pop`
+     * style takes a weak-beat pickup, its `instruments.bass` names the instrument
+     * when `instrument` does not, its `bpm` together with
+     * `complexity.difficulty` keeps leaps the hand could not make in time out of
+     * the line, and its `seed` fixes every deterministic choice the line makes.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+    /**
+     * Maximum number of segments, and of notes, {@link generateBassLine} may
+     * work through. The line is built segment by segment, so this is the guard
+     * against an unbounded caller rather than a limit on any search.
+     *
+     * @defaultValue 1000000
+     */
+    budget?: number;
+};
+/**
+ * Generate a bass line following a chord placement.
+ *
+ * Each segment contributes notes in the chosen bass register per the selected
+ * style; consecutive notes are kept within roughly a fifth. Every note's
+ * duration extends to the next onset (the final note extends to the last
+ * segment's end). Given a seed the output is fully reproducible.
+ *
+ * The `pop` style's pickups are drawn per position, so raising
+ * `complexity.rhythmic` adds pickups without moving the notes already written.
+ *
+ * With an `instrument` the line is written for that instrument: the register
+ * band is moved into its range and any note still outside comes back an octave,
+ * so every pitch has a fret. Nothing is dropped or replaced — the rhythm and
+ * the note count are the same either way.
+ *
+ * @param opts Segments, key, and generation options.
+ * @returns Bass notes sorted by onset, non-overlapping.
+ *
+ * @example
+ * ```ts
+ * import { generateBassLine, makeChord, majorKey } from '@libraz/libcantus';
+ * const segments = [
+ *   { startBeat: 0, endBeat: 4, chord: makeChord(0, 'maj') },
+ *   { startBeat: 4, endBeat: 8, chord: makeChord(7, 'maj') },
+ * ];
+ * const notes = generateBassLine({ segments, key: majorKey(0), style: 'walking' });
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateBassLine(opts: BassLineOptions): NoteEvent[];
+
+/**
+ * Options controlling {@link generateCounterMelody}.
+ *
+ * @category Voicing & Counterpoint
+ */
+type CounterMelodyOptions = {
+    /** The lead line to write against, in ascending onset order. */
+    melody: readonly NoteEvent[];
+    /**
+     * The harmony to write against. A timeline carries its own segment
+     * boundaries, so a chord change anywhere — including off the generator's
+     * half-beat probe grid — is seen; prefer it over `chordAt`.
+     *
+     * Exactly one of `timeline` and `chordAt` is required; `timeline` wins when
+     * both are given.
+     */
+    timeline?: ChordTimeline;
+    /**
+     * Chord sounding at an absolute beat position, or null when none applies.
+     *
+     * A callback is opaque: the generator cannot see where it changes, so it
+     * probes a half-beat grid and otherwise relies on `chordChangeBeats`. A held
+     * counter note that spans an unseen change is not checked against the new
+     * chord.
+     */
+    chordAt?: (beat: number) => Chord | null;
+    /**
+     * Exact chord-change beats the `chordAt` callback does not expose. Ignored
+     * when `timeline` is given, since a timeline lists its own boundaries.
+     */
+    chordChangeBeats?: number[];
+    /**
+     * Key/scale context for scale-tone decisions. A key name such as `'C major'`
+     * is read as that key.
+     */
+    key: KeyLike;
+    /**
+     * Meter used for strong-beat decisions.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
+    /**
+     * Which side of the melody the counter line occupies.
+     *
+     * @defaultValue 'below'
+     */
+    register?: 'above' | 'below';
+    /**
+     * Onset strategy: `'complement'` moves where the melody holds or rests and
+     * reinforces some strong beats; `'follow'` mirrors melody onsets.
+     *
+     * @defaultValue 'complement'
+     */
+    rhythm?: 'complement' | 'follow';
+    /**
+     * Style profile applied to candidate pitches. It sets what is rejected
+     * outright and, through {@link PROFILE_WEIGHTS}, what is preferred among the
+     * candidates that remain: `'strict'` seeks contrary motion and avoids
+     * similar, `'pop'` treats a run of parallel thirds or sixths as the harmony
+     * line an arranger would write.
+     *
+     * @defaultValue 'pop'
+     */
+    profile?: 'strict' | 'pop';
+    /**
+     * Per-field overrides of the profile's ranking weights, for a preference the
+     * two stock profiles do not express — a line that should leap more freely, or
+     * one that should hold a pedal wherever it can.
+     */
+    weights?: Partial<ProfileWeights>;
+    /** Lowest MIDI pitch the counter line may use (default derived from `register`). */
+    pitchLow?: number;
+    /** Highest MIDI pitch the counter line may use (default derived from `register`). */
+    pitchHigh?: number;
+    /**
+     * The generation context, so the counter line is drawn from the same project
+     * source as every other part and no two parts collide.
+     *
+     * Its `seed` places the `'complement'` onsets and breaks ties between equally
+     * good candidate pitches; the same seed always yields the same line. Where the
+     * constraints leave only one good answer — which is common with
+     * `rhythm: 'follow'`, whose onsets are fixed by the melody — changing the seed
+     * changes nothing.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+};
+/**
+ * Generate a counter melody against a lead line.
+ *
+ * Onsets are chosen per `rhythm`: `'follow'` places one counter note on each
+ * melody onset; `'complement'` fills melody rests and sustains and reinforces
+ * an occasional strong beat, spaced at least a beat apart. Each onset's pitch
+ * is picked from the safe pitches in the counter register (chord tones and
+ * consonant tensions against the sounding melody note), rejecting candidates
+ * that would form a parallel perfect interval with the melody or sit on the
+ * wrong side of it, then ranked by the profile's weights — which is where the
+ * two styles part company: `'strict'` prefers contrary motion and penalizes
+ * similar, `'pop'` rewards a run of parallel thirds or sixths and is content
+ * with a pedal. Ties are broken by a seeded perturbation far
+ * below any real score difference (see `TIE_BREAK_JITTER`), so the same
+ * seed always yields the same line while a different seed can only reshuffle
+ * candidates that were already equally good. Notes extend to the next counter
+ * onset (the last to the melody's end) at a velocity slightly under the melody.
+ *
+ * @param opts The lead line, chord context callback, key, and generation knobs.
+ * @returns The counter line as note events sorted by onset; `[]` for an empty melody.
+ * @example
+ * ```ts
+ * import { generateCounterMelody, majorKey, parseChordSymbol } from '@libraz/libcantus';
+ * const melody = [{ pitch: 72, startBeat: 0, durationBeat: 2 }];
+ * const counter = generateCounterMelody({
+ *   melody,
+ *   chordAt: () => parseChordSymbol('C'),
+ *   key: majorKey(0),
+ * }); // note events below the melody, in onset order
+ * ```
+ * @category Voicing & Counterpoint
+ */
+declare function generateCounterMelody(opts: CounterMelodyOptions): NoteEvent[];
+
+/**
+ * The percussion voices the generator emits, as General MIDI note numbers.
+ *
+ * A {@link DrumHit} carries only its pitch, so splitting a kit across tracks —
+ * kick to one, snare to another — means comparing against these numbers. They
+ * are published so that comparison is a named constant covered by semver
+ * rather than a hard-coded 36.
+ *
+ * @example
+ * ```ts
+ * import { DRUM_NOTES, generateDrums } from '@libraz/libcantus';
+ * const hits = generateDrums({
+ *   bars: 1,
+ *   style: 'standard',
+ *   section: 'verse',
+ *   ctx: { bpm: 120, complexity: { rhythmic: 0.5 } },
+ * });
+ * const kick = hits.filter((hit) => hit.pitch === DRUM_NOTES.kick);
+ * ```
+ * @category Composition
+ */
+declare const DRUM_NOTES: Readonly<{
+    readonly kick: 36;
+    readonly snare: 38;
+    readonly sideStick: 37;
+    readonly handClap: 39;
+    readonly closedHiHat: 42;
+    readonly pedalHiHat: 44;
+    readonly openHiHat: 46;
+    readonly crash: 49;
+    readonly ride: 51;
+    readonly tambourine: 54;
+    readonly highTom: 50;
+    readonly midTom: 47;
+    readonly lowTom: 45;
+    readonly shaker: 82;
+}>;
+/**
+ * A percussion voice name, one key of {@link DRUM_NOTES}.
+ *
+ * @category Composition
+ */
+type DrumVoice = keyof typeof DRUM_NOTES;
+/**
+ * The voice a percussion note number names.
+ *
+ * @param pitch The General MIDI note number.
+ * @returns The voice, or undefined for a note this generator never emits.
+ * @category Composition
+ */
+declare function drumVoiceOf(pitch: number): DrumVoice | undefined;
+/**
+ * A single percussion onset.
+ *
+ * @category Composition
+ */
+type DrumHit = {
+    /** General MIDI note number; {@link drumVoiceOf} names it. */
+    pitch: number;
+    startBeat: number;
+    durationBeat: number;
+    velocity: number;
+    /**
+     * How the stroke is played, when it is more than a plain hit. A flam is one
+     * onset carrying `'flam'`, not a pair of notes a fraction of a beat apart, so
+     * the grace stroke is the reader's to place — as a second note, a key switch,
+     * or a sample layer — and any pattern can carry one.
+     */
+    articulation?: Articulation;
+};
+
+/**
+ * A Euclidean (Bjorklund) kick pattern for {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type EuclideanKick = {
+    /** Number of kick onsets, clamped to `[0, steps]`. */
+    pulses: number;
+    /**
+     * Total steps in the bar (1..16).
+     *
+     * @defaultValue 16
+     */
+    steps?: number;
+    /**
+     * Steps to rotate the onsets toward later positions.
+     *
+     * @defaultValue 0
+     */
+    rotation?: number;
+};
+/**
+ * Options controlling {@link generateDrums}.
+ *
+ * @category Composition
+ */
+type DrumsOptions = {
+    /**
+     * Number of bars to generate.
+     */
+    bars: number;
+    style: GrooveStyle;
+    section: Section;
+    /**
+     * Time signature.
+     *
+     * Only 4/4 is accepted: every shape this generator writes — the backbeat, the
+     * hi-hat subdivisions, the open-hat and crash beats, the beat a fill starts on
+     * — is written against a four-beat bar, so another meter would come back with
+     * 4/4 accents in a bar of the wrong length and no sign that anything was
+     * wrong. A meter it cannot place is refused rather than mis-placed. Use
+     * {@link generateRhythm} or {@link placeDrumPattern} for other meters.
+     *
+     * @defaultValue `{ numerator: 4, denominator: 4 }`
+     */
+    ts?: TimeSignature;
+    /**
+     * Replace the final bar with a fill.
+     *
+     * A pre-chorus leading into a chorus builds instead: the two-bar lift takes
+     * precedence over the fill, since the buildup already marks the phrase end.
+     * Set `nextSection` to anything but `'chorus'` to get the fill.
+     *
+     * @defaultValue false
+     */
+    fills?: boolean;
+    /**
+     * The swing the groove is played with. Naming one is taken at its word by
+     * every style, including the ones whose own character is straight: a feel the
+     * caller asked for and did not get is worse than one it has to ask for twice.
+     * Left out, the style's own feel applies.
+     */
+    feel?: GrooveFeel;
+    /**
+     * Voicing role, from busiest to sparsest:
+     *
+     * - `'full'`: every voice, backbeat snare at full weight.
+     * - `'ambient'`: side-stick backbeat, ride instead of hi-hat.
+     * - `'minimal'`: side-stick backbeat quieter still, pedal hi-hat, no
+     *   auxiliary percussion.
+     * - `'fxOnly'`: no kick, snare, ghost notes, timekeeping hi-hat, or fills —
+     *   only the fx and auxiliary voices.
+     *
+     * Roles express orchestration priority and peak dynamics, not a strict hit
+     * count: style-specific ride, foot-hi-hat, and auxiliary patterns may make a
+     * sparser role emit more individual onsets in a particular bar.
+     *
+     * @defaultValue `'full'`
+     */
+    role?: DrumRole;
+    /**
+     * The generation context: the tempo, the complexity dials, and the kit this
+     * part is written for.
+     *
+     * `bpm` is the tempo in quarter-note beats per minute. `complexity.rhythmic`
+     * is how busy the backing is, in [0, 1]; the dial is continuous, so every
+     * value moves the result and raising it only adds onsets — the ones already
+     * sounding stay where they were. `complexity.ornament` sets how many ghost
+     * notes survive, `complexity.difficulty` caps how fast the generator writes,
+     * `instruments.drums` — a percussion profile — restricts the output to voices
+     * that kit actually has, and `seed` fixes every deterministic choice.
+     *
+     * @defaultValue `{ seed: 0, bpm: 120, complexity: { rhythmic: 0.5 } }`
+     */
+    ctx?: GenerationContextInput;
+    /**
+     * Section the final-bar fill leads into. Shapes which fill archetype is
+     * chosen (into-chorus and out-of-intro fills differ from generic ones).
+     * Defaults to `section`, i.e. a within-section fill.
+     */
+    nextSection?: Section;
+    /**
+     * When set, the kick follows this Euclidean rhythm instead of the
+     * style/section pattern, giving direct access to evenly spread onsets.
+     */
+    euclideanKick?: EuclideanKick;
+    /**
+     * Maximum number of onsets {@link generateDrums} may write. Generation is
+     * linear in bar count, so this is the guard against an unbounded caller
+     * rather than a limit on any search.
+     *
+     * @defaultValue 1000000
+     */
+    budget?: number;
+};
+/**
+ * Generate a drum performance as a flat list of onsets.
+ *
+ * Every voice (kick, snare, ghost snares, closed/open/foot hi-hats, ride, toms,
+ * crash, and auxiliary percussion) is emitted as a {@link DrumHit} distinguished
+ * by its General MIDI pitch. Groove style selects an internal style and feel;
+ * `complexity.rhythmic` sets the backing-density level; `section` shapes kick,
+ * hi-hat, ghost, and percussion density. 16th-note hi-hats drop to 8ths at or
+ * above 150 BPM. When `fills` is true the final bar is replaced with a fill whose
+ * archetype is shaped by `nextSection`; a fill that would emit nothing on its
+ * beat falls back to the normal groove so the phrase end is never silent.
+ * `euclideanKick` overrides the kick with an evenly-spread Euclidean pattern.
+ * Output is fully determined by the options plus the context's seed.
+ *
+ * The patterns are 4/4 only — backbeats, hi-hat subdivisions, and fills are all
+ * written against a four-beat bar — so beat positions are quarter notes and bar
+ * `n` starts at beat `4n`.
+ *
+ * @param opts Generation options.
+ * @returns Percussion onsets in onset order, ties broken by pitch.
+ *
+ * @example
+ * ```ts
+ * import { generateDrums } from '@libraz/libcantus';
+ * const hits = generateDrums({
+ *   bars: 4,
+ *   style: 'standard',
+ *   section: 'chorus',
+ *   fills: true,
+ *   ctx: { seed: 0, bpm: 120, complexity: { rhythmic: 0.6 } },
+ * });
+ * // Fully determined by the options plus the context's seed (defaults to 0).
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateDrums(opts: DrumsOptions): DrumHit[];
+
+/**
+ * Groove and humanization: nudging quantized note events toward a more human
+ * feel, and capturing/replaying the timing-and-velocity "feel" of a
+ * performance as a reusable groove template.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention. Randomness, where used, always goes through the
+ * seeded PRNG from the `random` module so results are fully reproducible.
+ */
+
+/**
+ * Options controlling {@link humanize}.
+ *
+ * @category Rhythm & Meter
+ */
+type HumanizeOptions = {
+    /**
+     * Time signature used to derive metric accents.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
+    /**
+     * Maximum timing jitter in quarter-note beats, applied as ±this value.
+     *
+     * @defaultValue 0.02
+     */
+    timing?: number;
+    /**
+     * Maximum velocity jitter (MIDI units), applied as ±this value.
+     *
+     * @defaultValue 8
+     */
+    velocity?: number;
+    /**
+     * How much louder strong beats get relative to weak ones, in MIDI velocity units.
+     *
+     * @defaultValue 12
+     */
+    accent?: number;
+    /**
+     * Velocity assumed for events with no `velocity` of their own.
+     *
+     * @defaultValue 80
+     */
+    baseVelocity?: number;
+    /**
+     * The generation context, so one project seed covers this call as well as the
+     * generators that wrote the notes. Its `seed` fixes the jitter, so the same
+     * seed always humanizes the same way.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+    /**
+     * The name this call draws under. Humanizing two parts from one context with
+     * the same name gives notes at the same position and pitch the same jitter,
+     * which is what a doubled line does not want; naming each part keeps them
+     * independent.
+     *
+     * @defaultValue `'humanize'`
+     */
+    part?: string;
+};
+/**
+ * Humanize a sequence of note events by nudging their timing and velocity
+ * with small, deterministic (seeded) randomness plus a metric-accent shape:
+ * events on strong beats (see {@link metricWeight}) come out louder on
+ * average than events on weak ones.
+ *
+ * Each returned event is a copy; `startBeat` is jittered within
+ * `[-timing, +timing]` beats — not floored at 0, because a pickup sounds before
+ * the downbeat and flooring it there would play two upbeats as one — and
+ * `velocity` is the event's own velocity (or `baseVelocity` if it has none) plus an
+ * accent term scaled by the event's metric weight plus a jitter within
+ * `[-velocity, +velocity]`, clamped to `[1, 127]` and rounded. The metric
+ * weight is computed from each event's original (pre-jitter) `startBeat`.
+ * `pitch` and `durationBeat` pass through unchanged, and the output keeps the
+ * input order.
+ *
+ * The jitter is drawn from the generation context, addressed by the event's own
+ * onset and pitch rather than by its position in the array: an event added or
+ * removed leaves every other event's jitter exactly where it was, and a part
+ * humanized under its own name is independent of the others sharing the seed.
+ *
+ * @param events The events to humanize.
+ * @param opts Humanization options.
+ * @returns Humanized copies of `events`, in input order.
+ * @example
+ * ```ts
+ * import { humanize } from '@libraz/libcantus';
+ * const events = [{ pitch: 60, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * humanize(events, { ctx: 1, timing: 0.03 }); // copies with jittered timing and accented velocity
+ * humanize(events, { ctx: { seed: 42 }, part: 'lead' }); // under a project context
+ * ```
+ * Notes with a zero or negative duration never sound and are dropped, so the
+ * result can be shorter than the input.
+ *
+ * @category Rhythm & Meter
+ */
+declare function humanize(events: readonly NoteEvent[], opts?: HumanizeOptions): NoteEvent[];
+/**
+ * The recorded feel at a single grid slot: an average timing deviation and velocity.
+ *
+ * @category Rhythm & Meter
+ */
+type GrooveSlot = {
+    /** Average `actualStartBeat - quantizedBeat` (in quarter-note beats) for events landing on this slot. */
+    timingOffset: number;
+    /**
+     * Average velocity of events landing on this slot, or `null` if no event
+     * with a velocity did. `null` (not 0) is the "unrecorded" sentinel so that a
+     * genuine velocity of 0 is preserved and applied like any other value.
+     */
+    velocity: number | null;
+};
+/**
+ * A per-bar grid of timing and velocity deviations captured from a performance.
+ *
+ * @category Rhythm & Meter
+ */
+type GrooveTemplate = {
+    /** Grid resolution: equal grid steps per quarter-note beat. */
+    subdivision: number;
+    /** Number of grid slots per bar (`beatsPerBar(ts) * subdivision`). */
+    slotsPerBar: number;
+    /** One entry per grid slot, in slot-index order (slot 0 is the downbeat). */
+    slots: GrooveSlot[];
+    /**
+     * The time signature the template was extracted under. {@link applyGrooveTemplate}
+     * requires the apply-time meter to match this so the per-bar grid lines up
+     * instead of silently drifting. Optional for backward compatibility with
+     * templates constructed without it (in which case no check is performed).
+     */
+    ts?: TimeSignature;
+};
+/**
+ * Extract a groove template from a set of note events: for each grid slot,
+ * the average timing deviation from the quantized grid and the average
+ * velocity of events landing on it. Slots with no velocity-carrying event
+ * record `velocity: null` (the "unrecorded" sentinel); empty slots default to
+ * `{ timingOffset: 0, velocity: null }`. The time signature is stored on the
+ * template so {@link applyGrooveTemplate} can verify the meter matches.
+ *
+ * @param events The (typically "groovy", human-played) events to analyze.
+ * @param ts The time signature, used to compute the bar length.
+ * @param subdivision Grid resolution: equal grid steps per quarter-note beat.
+ *   Defaults to a sixteenth-note grid, which is where the timing deviations a
+ *   template records — swing, push, drag — are audible.
+ * @returns The extracted groove template.
+ * @category Rhythm & Meter
+ */
+declare function extractGrooveTemplate(events: readonly NoteEvent[], ts: TimeSignature, subdivision?: number): GrooveTemplate;
+/**
+ * Apply a groove template to a set of (typically quantized) note events: each
+ * event is snapped to its grid slot and then offset by that slot's recorded
+ * timing deviation, pushing stiff timing toward the template's feel.
+ * Velocity is set to the slot's recorded average when it recorded one (a
+ * non-`null` velocity, including a genuine 0); otherwise the event's own
+ * velocity is left untouched.
+ * Non-positive-duration input artefacts are omitted, so output positions do
+ * not retain a one-to-one correspondence with the input array.
+ *
+ * If the template carries a time signature (see {@link GrooveTemplate.ts}) it
+ * must match `ts`, since a differing bar length would misalign the per-bar
+ * grid and drift the feel; a mismatch throws rather than corrupting timing
+ * silently.
+ *
+ * @param events The events to reshape.
+ * @param template The groove template, from {@link extractGrooveTemplate}.
+ * @param ts The time signature, used to compute the bar length.
+ * @returns Reshaped copies of `events`, in input order.
+ * @throws If `template.ts` is set and does not match `ts`.
+ * @example
+ * ```ts
+ * import { extractGrooveTemplate, applyGrooveTemplate, parseTimeSignature } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * // Learn the feel from a loosely played performance...
+ * const groovy = [
+ *   { pitch: 36, startBeat: 0.02, durationBeat: 1, velocity: 100 },
+ *   { pitch: 38, startBeat: 1.06, durationBeat: 1, velocity: 70 },
+ * ];
+ * const template = extractGrooveTemplate(groovy, ts, 4);
+ * // ...then impose it on stiff, quantized events.
+ * const quantized = [{ pitch: 36, startBeat: 0, durationBeat: 1, velocity: 80 }];
+ * applyGrooveTemplate(quantized, template, ts); // events nudged toward the captured feel
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function applyGrooveTemplate(events: readonly NoteEvent[], template: GrooveTemplate, ts: TimeSignature): NoteEvent[];
+
+/**
+ * Broad production style a progression preset suits.
+ *
+ * @category Composition
+ */
+type ProgStyle = 'minimal' | 'dance' | 'idol' | 'rock';
+/**
+ * Harmonic-function role of a progression as a whole.
+ *
+ * @category Composition
+ */
+type ProgFunction = 'loop' | 'tensionBuild' | 'cadenceStrong' | 'stable';
+/**
+ * A named chord-progression preset expressed in scale degrees.
+ *
+ * @category Composition
+ */
+type ProgressionPreset = {
+    id: string;
+    name: string;
+    /**
+     * The chord roots, in order, as {@link ProgressionDegree} codes: 0..6 for the
+     * key's own scale degrees and {@link BORROWED_DEGREES} for the borrowed ones.
+     */
+    degrees: ProgressionDegree[];
+    functional: ProgFunction;
+    styles: ProgStyle[];
+};
+/**
+ * The borrowed (non-diatonic) chord roots a preset can name, as their semitone
+ * code for a borrowed degree. These are stable identifiers, not semitone
+ * offsets: their pitch-class offsets are resolved internally.
+ *
+ * Scale degrees 1..7 address the key's own chords; these codes continue the
+ * numbering for the chromatic chords a pop progression borrows, so a preset is
+ * one flat list of degree codes.
+ *
+ * @example
+ * ```ts
+ * import { BORROWED_DEGREES, generateProgression, majorKey } from '@libraz/libcantus';
+ * generateProgression({
+ *   key: majorKey(0),
+ *   style: 'rock',
+ *   bars: 4,
+ *   preset: { degrees: [1, BORROWED_DEGREES.bVII, 4, 1] },
+ * });
+ * ```
+ * @category Composition
+ */
+declare const BORROWED_DEGREES: Readonly<{
+    /** Flat submediant: bVI. */
+    readonly bVI: 8;
+    /** Flat subtonic: bVII. */
+    readonly bVII: 10;
+    /** Flat mediant: bIII. */
+    readonly bIII: 11;
+    /** Minor subdominant borrowed from the parallel minor: iv. */
+    readonly iv: 12;
+    /** Neapolitan: bII. */
+    readonly bII: 13;
+    /** Sharp subdominant, the diminished #IV. */
+    readonly sharpIV: 14;
+}>;
+/**
+ * A chord root in a preset: a scale degree 1..7, or one of
+ * {@link BORROWED_DEGREES}.
+ *
+ * @category Composition
+ */
+type ProgressionDegree = number;
+/**
+ * Options controlling {@link generateProgression}.
+ *
+ * @category Composition
+ */
+type ProgressionOptions = {
+    /**
+     * The key the degrees are resolved against; a key name such as `'C major'` is
+     * read as that key.
+     */
+    key: KeyLike;
+    /**
+     * Which pool of built-in presets to choose from. Ignored when `preset` names
+     * the progression outright.
+     */
+    style: ProgStyle;
+    bars: number;
+    /** Pick a specific built-in preset by id instead of choosing one by style. */
+    presetId?: string;
+    /**
+     * Use this progression rather than a built-in one. Only `degrees` is
+     * required; see {@link BORROWED_DEGREES} for the non-diatonic codes.
+     */
+    preset?: Partial<ProgressionPreset> & {
+        degrees: ProgressionDegree[];
+    };
+    ext?: ChordQuality | 'auto';
+    /**
+     * The generation context.
+     *
+     * Its `complexity.harmonic` sets how much of the progression is replaced by
+     * the secondary dominant of what follows: 0 — the default — leaves it alone,
+     * 0.5 takes about half of what the voice-leading rules allow, and 1 takes
+     * every one of them. Its `seed` fixes both the preset choice and which chords
+     * are replaced, so the same seed always yields the same progression.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+};
+/**
+ * All built-in progression presets.
+ *
+ * @category Composition
+ */
+declare function progressions(): ProgressionPreset[];
+/**
+ * Presets whose style list includes the given style.
+ *
+ * @category Composition
+ */
+declare function progressionsByStyle(style: ProgStyle): ProgressionPreset[];
+/**
+ * The preset {@link generateProgression} would choose for a style and seed.
+ *
+ * The choice is otherwise invisible: the generator returns chords, not the
+ * preset it drew them from, so a caller who wants to show or reproduce it has
+ * no way to name it.
+ *
+ * @param style The style pool to choose from.
+ * @param seed The same seed the generator would be given.
+ * @returns The preset that seed selects.
+ * @throws If no preset claims the style.
+ * @example
+ * ```ts
+ * import { pickProgressionPreset } from '@libraz/libcantus';
+ * pickProgressionPreset('dance', 3).name;
+ * ```
+ * @category Composition
+ */
+declare function pickProgressionPreset(style: ProgStyle, seed?: number): ProgressionPreset;
+/**
+ * Generate a chord progression laid out one chord per bar.
+ *
+ * A preset is chosen by `presetId` when given, otherwise deterministically from
+ * the presets matching `style`, seeded by the context's `seed`. An unknown
+ * `presetId`, or a `style` no preset claims, is a caller error and throws rather
+ * than silently falling back to a random preset. The preset's degrees cycle to
+ * fill `bars`; each bar is four beats, so `startBeat` is `barIndex * 4`. Chord
+ * roots come from the key's diatonic scale-degree mapping. When `ext` is
+ * omitted or `'auto'`, each chord takes its diatonic triad quality; otherwise
+ * `ext` is forced on every chord — except a reharmonized chord, which is a
+ * secondary dominant and is therefore always a `dom7`. With
+ * `complexity.harmonic` above 0, some chords are deterministically replaced with
+ * the secondary dominant (V7) of the following chord, flagged with
+ * `secondaryDominant`.
+ *
+ * @param opts Generation options.
+ * @returns One chord per bar in timeline order.
+ * @throws If `presetId` matches no built-in preset, or `style` matches none.
+ *
+ * @example
+ * ```ts
+ * import { generateProgression, majorKey } from '@libraz/libcantus';
+ * const chords = generateProgression({ key: majorKey(0), style: 'dance', bars: 4 });
+ * // Deterministic for a given seed (defaults to 0); one ChordSpan per bar.
+ * const richer = generateProgression({
+ *   key: majorKey(0),
+ *   style: 'dance',
+ *   bars: 4,
+ *   ctx: { seed: 3, complexity: { harmonic: 0.5 } },
+ * });
+ * // Some chords are now the secondary dominant of the chord that follows.
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateProgression(opts: ProgressionOptions): ChordSpan[];
+
+/**
+ * A melody note supplied to the harmonizer: a {@link NoteEvent}.
+ *
+ * @category Reharmonization
+ */
+type MelodyNote = NoteEvent;
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * @category Reharmonization
+ */
+type HarmonizePlacement = {
+    /**
+     * Move the melody into the key it is harmonized in. The search reports the
+     * shift it chose in `transposeSemitones`; transposing the melody by that many
+     * semitones puts it in the returned `key`, so melody and harmony always agree.
+     *
+     * Use it for a melody notated in one key that has to be sung or played in
+     * another. It never changes register on its own — that is `octaveSearch`.
+     *
+     * @defaultValue false
+     */
+    transposeSearch: boolean;
+    /**
+     * Search octave placements as well, so a melody written too high or too low
+     * is moved into a comfortable register. Octaves leave every pitch class where
+     * it was, so this changes neither the key nor the chords.
+     *
+     * @defaultValue false
+     */
+    octaveSearch: boolean;
+};
+/**
+ * Options controlling {@link harmonizeMelody}.
+ *
+ * Only `melody` is required; every other knob has the default a first call
+ * wants.
+ *
+ * @category Reharmonization
+ */
+type HarmonizeOptions = {
+    /** The melody to harmonize, in ascending onset order. */
+    melody: readonly MelodyNote[];
+    /**
+     * The key to harmonize in, or `'infer'` to estimate it from the melody's
+     * pitch-class weighting — which is what a caller who has only a melody
+     * wants, and so the default. A key name such as `'C major'` is read as that
+     * key; `'infer'` names no key and always asks for the estimate.
+     *
+     * @defaultValue `'infer'`
+     */
+    key?: KeyLike | 'infer';
+    /**
+     * Length of each chord slot in beats. Harmonization places chords on a fixed
+     * grid of this length — unlike {@link chordTimelineFromNotes}, which searches
+     * for the boundaries an existing piece already implies. Any positive value is
+     * honoured; a value fine enough to make the search explode is rejected by the
+     * generation budget rather than rounded up.
+     *
+     * Left out, it is read from `ts`: half a bar where the half falls on a pulse,
+     * and the whole bar where it does not, so a waltz changes chord on its
+     * downbeats rather than across them. In 4/4 that is one chord per half bar.
+     *
+     * @defaultValue half a bar of `ts` — 2 in 4/4
+     */
+    harmonicRhythm?: number;
+    /**
+     * Time signature the melody is barred in. It weights the metric accents the
+     * chords are chosen against and sets the default chord grid, so a waltz or a
+     * jig is harmonized on its own beats rather than on a 4/4 reading of them.
+     *
+     * @defaultValue `4/4`
+     */
+    ts?: TimeSignature;
+    /**
+     * How far beyond the key's own triads the chord vocabulary reaches:
+     * `'diatonic'` uses only them, `'secondaryDominant'` adds the dominants that
+     * tonicize each degree, and `'borrowed'` adds the parallel mode's chords too.
+     *
+     * Sugar for `ctx: { complexity: { harmonic } }` at the three dial positions
+     * these names have always stood for; a context names how far the vocabulary
+     * reaches instead of which of three steps it stops at, and wins where both
+     * are given.
+     *
+     * @defaultValue `'diatonic'`
+     */
+    reharmonize?: 'diatonic' | 'secondaryDominant' | 'borrowed';
+    /**
+     * Whether to search transpositions and octave placements for the melody.
+     * Both are off by default, so the melody is harmonized where it was written.
+     *
+     * @defaultValue both false
+     */
+    placement?: HarmonizePlacement;
+    /**
+     * Beats at which the melody's phrases end, so a longer line closes at each of
+     * them instead of only at its end.
+     *
+     * Naming a beat asks for a close there, and three things follow from it. The
+     * beat divides the chord grid, so the slot the phrase closes in ends where the
+     * phrase does rather than running on into the next one. The harmony moves into
+     * that slot — the chord under a named close is never the chord that was
+     * already sounding, which is what makes the close audible as one. And the note
+     * the phrase comes to rest on is read as a structural tone rather than as an
+     * ornament of the next phrase's first note, so a phrase resting on the tonic
+     * is harmonized by the tonic.
+     *
+     * Which cadence that close forms is still the melody's to decide: a phrase
+     * coming to rest on the tonic over an approach that can carry the dominant
+     * cadences authentically, and one whose approach cannot is harmonized by what
+     * it sounds.
+     *
+     * The melody always closes where it ends, whatever this says; these are the
+     * closes *inside* it. `phrasesFromTimeline` finds the phrases of a line
+     * already labelled with chords, and its `endBeat` values are what this
+     * expects, so a caller harmonizes a whole piece in one call rather than
+     * harmonizing each phrase and joining the results.
+     *
+     * A boundary landing exactly on a chord-slot boundary closes the slot before
+     * it — the beat a phrase ends on is where the next phrase begins.
+     *
+     * @defaultValue none — one close, at the end
+     */
+    phraseEnds?: readonly number[];
+    /**
+     * The generation context. Its `complexity.harmonic` is how far the chord
+     * vocabulary reaches beyond the key's own triads — 0 uses them alone, 0.5 has
+     * every secondary dominant, 1 the parallel mode's chords as well — and its
+     * `seed` drives the deterministic tie-break perturbation.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+};
+/**
+ * The chosen transpose, key, chord path, and per-note roles.
+ *
+ * @category Reharmonization
+ */
+type HarmonizeResult = {
+    /**
+     * How far the melody was moved, in semitones. Transposing the melody by this
+     * much puts it in `key`, which is the key the chords are in.
+     */
+    transposeSemitones: number;
+    key: KeyScale;
+    /** One span per chord change, each starting on a harmonic-rhythm boundary. */
+    chords: ChordSpan[];
+    /** Each melody note's role in the chord sounding under it, once chosen. */
+    melodyRoles: {
+        noteIndex: number;
+        role: HarmonyRole;
+    }[];
+};
+/**
+ * Harmonize a melody with a min-cost chord progression.
+ *
+ * The melody's ornaments are classified first, from the melody and the metre
+ * alone (see {@link classifyMelodyTones}); the chords then have to explain the
+ * structural tones only, so a passing tone no longer buys itself a chord. The
+ * melody is segmented by `harmonicRhythm`; each segment is scored against the
+ * candidate chords the harmonic dial opens — the key's own triads, then the
+ * secondary dominants, then the parallel mode's chords, one at a time as
+ * `ctx.complexity.harmonic` rises from 0 to 1 — by the fit of those structural
+ * tones, and a Viterbi search picks the lowest-cost path using a
+ * functional-flow transition cost and a cadence bonus at the end of the melody
+ * it is given — one cadence, at the close, unless `phraseEnds` names the closes
+ * inside a longer line, and then one at each of them as well. Runs of the same
+ * chord are reported once, so the chord count follows the harmony rather than
+ * the grid.
+ *
+ * With `placement.transposeSearch` the melody is moved into the key it is
+ * harmonized in, and `transposeSemitones` reports how far; with
+ * `placement.octaveSearch` it is moved by octaves into a comfortable register,
+ * which leaves the key and the chords untouched. Both may be set, and the
+ * reported shift is their sum.
+ *
+ * The `seed` drives a deterministic tie-break only: it perturbs candidates by a
+ * magnitude far below any real cost difference (see `TIE_BREAK_JITTER`),
+ * so it can decide between chords or paths of otherwise-equal cost but never
+ * overrides melody fit or functional flow. For a well-determined melody the
+ * result is identical across seeds; the same seed always yields the same result.
+ *
+ * @param opts The melody and, optionally, the generation context, key, harmonic
+ *   rhythm, reharmonization strength, placement search, meter, and seed. Only
+ *   `melody` is required.
+ * @returns The chosen transpose, key, chord path, and per-note roles.
+ * @example
+ * ```ts
+ * import { harmonizeMelody } from '@libraz/libcantus';
+ * const result = harmonizeMelody({
+ *   melody: [
+ *     { pitch: 60, startBeat: 0, durationBeat: 1 },
+ *     { pitch: 64, startBeat: 1, durationBeat: 1 },
+ *   ],
+ * });
+ * result.chords; // one ChordSpan per chord change, on the harmonic-rhythm grid
+ * ```
+ * @category Reharmonization
+ */
+declare function harmonizeMelody(opts: HarmonizeOptions): HarmonizeResult;
+
+/**
+ * A transformation applicable to a motif cell.
+ *
+ * @category Composition
+ */
+type MotifTransform = 'transposeDiatonic' | 'transposeChromatic' | 'invert' | 'retrograde' | 'augment' | 'diminish' | 'sequence';
+/**
+ * A single note within a motif cell.
+ *
+ * @category Composition
+ */
+type MotifNote = {
+    pitch: number;
+    startBeat: number;
+    durationBeat: number;
+};
+/**
+ * A short melodic cell.
+ *
+ * @category Composition
+ */
+type MotifCell = {
+    notes: MotifNote[];
+};
+/**
+ * Melodic contour shape for {@link generateMotif}.
+ *
+ * @category Composition
+ */
+type MotifContour = 'arch' | 'ascending' | 'descending' | 'wave';
+/**
+ * Options controlling {@link generateMotif}.
+ *
+ * @category Composition
+ */
+type MotifOptions = {
+    /** The key the line is written in; a key name such as `'C major'` is read as that key. */
+    key: KeyLike;
+    /**
+     * Chord the downbeats are pulled to, if any; it may be written as a chord
+     * symbol as well as given as chord data.
+     */
+    chord?: ChordLike | null;
+    /** Length of the motif in bars of `ts`. */
+    bars: number;
+    /**
+     * Meter the bars are counted in. It sets the bar length, so a motif shares a
+     * bar grid with the other generators instead of assuming four beats.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
+    /**
+     * Melodic contour shape the line follows.
+     *
+     * @defaultValue `'arch'`
+     */
+    contour?: MotifContour;
+    /**
+     * Probability in [0, 1] that a note is nudged by a single diatonic step. The
+     * nudge direction is balanced (up or down with equal odds), so it adds
+     * variety without biasing the line off its contour. Default 0, which
+     * reproduces the requested contour exactly (no drift, tails return to tonic).
+     *
+     * Sugar for `ctx: { complexity: { ornament } }` — a nudge off the contour is
+     * decoration rather than rhythm; the context wins where both are given. Being
+     * the same dial, it takes the same values: one outside [0, 1] is rejected here
+     * exactly as it is there, rather than being folded to the nearest end.
+     *
+     * @defaultValue 0
+     * @throws If it is not a finite number in [0, 1].
+     */
+    jitter?: number;
+    /**
+     * The generation context. Its `complexity.ornament` is this generator's
+     * jitter, and its `seed` fixes which notes are nudged.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+};
+/**
+ * Generate a short seed motif over `bars`.
+ *
+ * The melody follows the requested contour in diatonic steps from the tonic,
+ * snapped to the key. When a chord is supplied, notes landing on bar downbeats
+ * are pulled to the nearest chord tone. An optional `jitter` adds balanced
+ * per-note variation without biasing the contour; it is off by default, so the
+ * contour is reproduced exactly. Output is deterministic for a given seed.
+ *
+ * @param opts Key, optional chord, length, contour, jitter, and context.
+ * @returns The generated motif cell.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 2, contour: 'arch' });
+ * // cell.notes is a deterministic MotifCell (seed defaults to 0)
+ * ```
+ *
+ * @category Composition
+ */
+declare function generateMotif(opts: MotifOptions): MotifCell;
+/**
+ * Turn a motif cell into note events.
+ *
+ * A {@link MotifNote} already carries the {@link NoteEvent} fields, but a cell
+ * wraps them in an object; this unwraps it, so a motif can be humanized,
+ * grooved, or written out like any other line.
+ *
+ * @param cell The motif to convert.
+ * @returns The cell's notes, copied, in the order they are stored.
+ * @example
+ * ```ts
+ * import { generateMotif, humanize, majorKey, motifToNoteEvents } from '@libraz/libcantus';
+ * humanize(motifToNoteEvents(generateMotif({ key: majorKey(0), bars: 2 })));
+ * ```
+ * @category Composition
+ */
+declare function motifToNoteEvents(cell: MotifCell): NoteEvent[];
+/**
+ * Apply a transformation to a motif cell.
+ *
+ * `invert` reflects pitches about the first note (chromatic, self-inverse);
+ * `retrograde` mirrors onsets about the cell span, preserving rests (self-inverse);
+ * `augment`/`diminish` scale time by `amount ?? 2` and its reciprocal;
+ * `transposeChromatic` adds `amount` semitones; `transposeDiatonic` shifts by
+ * `amount` scale degrees when a `key` is given, or — with no `key` — falls back
+ * to a chromatic shift of `amount` semitones; `sequence` appends a shifted copy
+ * (by `amount` diatonic degrees with a `key`, or by `amount` semitones without
+ * one, since it delegates to `transposeDiatonic`).
+ *
+ * @param cell The cell to transform.
+ * @param t The transformation.
+ * @param amount Optional parameter (semitones, degrees, or time factor).
+ * @param key Key context for the diatonic transforms, as a key name such as
+ *   `'C major'` or as a key/scale; without it, `transposeDiatonic` and
+ *   `sequence` shift chromatically by semitones.
+ * @returns The transformed cell.
+ * @throws If a transformed pitch would fall outside the MIDI range 0..127.
+ *
+ * @example
+ * ```ts
+ * import { generateMotif, transformMotif, majorKey } from '@libraz/libcantus';
+ * const cell = generateMotif({ key: majorKey(0), bars: 1 });
+ * const inverted = transformMotif(cell, 'invert');
+ * ```
+ *
+ * @category Composition
+ */
+declare function transformMotif(cell: MotifCell, t: MotifTransform, amount?: number, key?: KeyLike): MotifCell;
+/**
+ * Lay a motif across `bars` and snap it to a chord timeline.
+ *
+ * The cell is tiled back-to-back to fill the requested span. Notes that carry
+ * structural weight — the head of each tile and every bar line — are pulled to
+ * the nearest chord tone of the segment sounding at that onset, so the
+ * developed line spells the underlying harmony. The notes between them are kept
+ * in the key as passing and neighbour tones, and two pitches that differ in the
+ * cell still differ in the development, so the development is still recognizably
+ * the motif rather than a chord arpeggiated over the cell's rhythm.
+ *
+ * @param cell The source motif.
+ * @param timeline Chord segments to snap against.
+ * @param key Key context, as a key name such as `'C major'` or as a key/scale;
+ *   the notes off the structural positions are kept in it.
+ * @param bars Number of bars to fill.
+ * @param ts Meter the bars are counted in; defaults to 4/4.
+ * @returns The developed, harmony-aware cell.
+ *
+ * @example
+ * ```ts
+ * import { chordTimelineFromChords, developMotif, generateMotif, majorKey } from '@libraz/libcantus';
+ * const key = majorKey(0);
+ * const timeline = chordTimelineFromChords([{ rootPc: 0, quality: 'maj', startBeat: 0 }], 8);
+ * const developed = developMotif(generateMotif({ key, bars: 1 }), timeline, key, 2);
+ * developed.notes.map((n) => n.pitch); // [60, 62, 60, 60, 62, 60] — the C-D-C cell, twice
+ * ```
+ *
+ * @category Composition
+ */
+declare function developMotif(cell: MotifCell, timeline: ChordTimeline, key: KeyLike, bars: number, ts?: TimeSignature): MotifCell;
+
+/**
+ * Ornaments applied to material that already exists.
+ *
+ * Decoration is not a property of generation: this layer takes notes and gives
+ * notes back, the way {@link humanize} does, so a line from any source — a
+ * generator, a MIDI import, a caller's own array — can be decorated without
+ * being generated again by whichever generator happens to write ghost notes.
+ *
+ * The decoration is carried as an {@link Articulation}, not baked into extra
+ * onsets: a flam is one note marked `'flam'`, so the grace stroke stays the
+ * reader's to voice and nothing downstream has to guess which of two onsets was
+ * the ornament.
+ */
+
+/**
+ * Every ornament idiom, in declaration order.
+ *
+ * @category Composition
+ */
+declare const ORNAMENT_STYLES: readonly ["ghost", "flam", "drag", "slide", "accent"];
+/**
+ * The kind of ornament to apply.
+ *
+ * - `'ghost'`: soften weak-position notes into ghosted strokes.
+ * - `'flam'`: mark accented notes as flammed — the strong positions `'accent'`
+ *   also takes, voiced as a grace stroke instead of a velocity lift.
+ * - `'drag'`: mark notes leading into a strong position as dragged. A weak-position
+ *   note qualifies only when the next onset in the material falls on a strong one.
+ * - `'slide'`: mark a note reached by a step or a leap as slid into.
+ * - `'accent'`: mark strong-position notes as accented, and lift their velocity.
+ *
+ * @category Composition
+ */
+type OrnamentStyle = (typeof ORNAMENT_STYLES)[number];
+/**
+ * Options controlling {@link ornament}.
+ *
+ * @category Composition
+ */
+type OrnamentOptions = {
+    /**
+     * The ornament to apply.
+     *
+     * @defaultValue `'ghost'`
+     */
+    style?: OrnamentStyle;
+    /**
+     * How much of the eligible material is decorated, in [0, 1]. Raising it only
+     * ornaments more notes; the notes already ornamented keep the ornament they
+     * had. Defaults to `complexity.ornament` from the context, or 0.5.
+     */
+    amount?: number;
+    /**
+     * Time signature, used to tell strong positions from weak ones.
+     *
+     * @defaultValue 4/4
+     */
+    ts?: TimeSignature;
+    /**
+     * The generation context. Its `complexity.ornament` sets the amount, its
+     * `complexity.difficulty` — with a tempo — keeps ornaments off passages too
+     * fast to play them in, and its `seed` fixes which notes are decorated.
+     *
+     * @defaultValue `{ seed: 0 }`
+     */
+    ctx?: GenerationContextInput;
+};
+/**
+ * Decorate existing notes with an ornament.
+ *
+ * Which notes are eligible follows from the style and the meter — ghosts fall on
+ * weak positions, drags on the weak position before a strong one, flams and
+ * accents on strong ones, slides on notes reached by a leap — and `amount`
+ * decides how many of those eligible notes are taken. The choice is addressed by
+ * each note's own position, so raising `amount` adds ornaments without moving the
+ * ones already there, and no onset is ever added or shifted: a decorated note is
+ * the same note carrying an {@link Articulation}. A note that already carries one
+ * is left alone, so ornament passes can be layered.
+ *
+ * With a difficulty ceiling and a tempo in the context, a passage whose strokes
+ * come too fast for that ceiling is left plain — the ornament is exactly the
+ * kind of candidate a ceiling exists to reject.
+ *
+ * @param notes The material to decorate.
+ * @param opts Style, amount, meter, and context.
+ * @returns Copies of the sounding notes, in input order, with ornaments applied.
+ * @example
+ * ```ts
+ * import { generateBassLine, majorKey, makeChord, ornament } from '@libraz/libcantus';
+ * const line = generateBassLine({
+ *   segments: [{ startBeat: 0, endBeat: 4, chord: makeChord(0, 'maj') }],
+ *   key: majorKey(0),
+ *   style: 'pop',
+ * });
+ * ornament(line, { style: 'ghost', amount: 0.4, ctx: 3 });
+ * ```
+ * Notes with a zero or negative duration never sound and are dropped, so the
+ * result can be shorter than the input.
+ *
+ * @category Composition
+ */
+declare function ornament(notes: readonly NoteEvent[], opts?: OrnamentOptions): NoteEvent[];
+
+/**
+ * Reharmonization: chord substitution, modal-interchange palettes, and negative
+ * harmony. These transforms take an existing chord (or a key) and propose
+ * alternative harmonies that preserve a chosen relationship — a shared function,
+ * a common tone, or a reflection across the key axis.
+ *
+ * Roots are pitch classes (0..11); no spelled key signature is required. Every
+ * proposed chord nevertheless carries the spelling hints of the key it was asked
+ * for, so a flat-side key names its chromatic chords with flats (the tritone
+ * substitute of G7 in C major is Db7, not C#7).
+ */
+
+/**
+ * The kind of substitution relationship a candidate realizes.
+ *
+ * An applied dominant is not among them: which dominant applies is decided by
+ * the harmony that follows, and {@link substituteChord} is given one chord and a
+ * key. Build one with `secondaryDominantOf` where the target is known, or let
+ * `harmonizeMelody` open its vocabulary with `reharmonize: 'secondaryDominant'`
+ * where the progression is being chosen as a whole.
+ *
+ * @category Reharmonization
+ */
+type SubstitutionType = 'tritone' | 'relative' | 'borrowed' | 'chromaticMediant';
+/**
+ * A proposed chord substitution with its relationship, numeral, and function.
+ *
+ * @category Reharmonization
+ */
+type Substitution = {
+    chord: Chord;
+    type: SubstitutionType;
+    roman: string;
+    function: HarmonicFunction;
+};
+/**
+ * Options controlling which substitutions {@link substituteChord} returns.
+ *
+ * @category Reharmonization
+ */
+type SubstituteOptions = {
+    /**
+     * Melody pitch classes that must remain chord tones. When given, only
+     * substitutions whose pitch classes contain every listed pitch class are
+     * kept, so the melody stays consonant against the new harmony.
+     */
+    melodyPcs?: number[];
+};
+/**
+ * Propose substitutions for a chord within a key.
+ *
+ * Candidates are generated by several relationships and deduplicated against the
+ * original chord and each other:
+ *
+ * - `tritone`: for a dominant-type chord, the dominant seventh a tritone away.
+ * - `relative`: a diatonic triad a third away that shares two common tones.
+ * - `borrowed`: a triad from the parallel mode with the same harmonic function.
+ * - `chromaticMediant`: a major/minor triad a third away sharing one common
+ *   tone.
+ *
+ * These four are the whole vocabulary. An applied dominant is not proposed
+ * because the chord it applies to is the one that follows, which a call about a
+ * single chord cannot see; `secondaryDominantOf` builds one from a named target.
+ *
+ * Each result carries its Roman numeral and harmonic function in `key`. When
+ * `opts.melodyPcs` is given, only substitutions whose pitch classes contain all
+ * of those pitch classes are returned.
+ *
+ * Every substitution is spelled the way `key` writes it, as `rootSpelling` and
+ * `bassSpelling` hints, so a flat-side key keeps flat names: in C major the
+ * tritone substitute of G7 formats as `Db7` and its chromatic mediants as `Bb`
+ * and `Eb`. Where the substitution's function and the bare pitch class disagree,
+ * the function decides — a tritone substitute is a bII7 and so is written on the
+ * flattened supertonic of the chord it resolves to, and a borrowed chord takes
+ * the spelling of the mode it is borrowed from.
+ *
+ * @param chord The chord to reharmonize, as a chord symbol or as chord data.
+ * @param key The prevailing key, as a key name or as a key/scale.
+ * @param opts Optional melody-preservation constraint.
+ * @returns The deduplicated substitution candidates.
+ * @example
+ * ```ts
+ * import { substituteChord, makeChord, majorKey, formatChordSymbol } from '@libraz/libcantus';
+ * const subs = substituteChord(makeChord(7, 'dom7'), majorKey(0));
+ * subs
+ *   .filter((sub) => sub.type === 'tritone')
+ *   .map((sub) => formatChordSymbol(sub.chord)); // ['Db7'] — the bII7 of C major, not 'C#7'
+ * ```
+ * @category Reharmonization
+ */
+declare function substituteChord(chord: ChordLike, key: KeyLike, opts?: SubstituteOptions): Substitution[];
+/**
+ * A borrowed chord in the modal-interchange palette of a key.
+ *
+ * @category Reharmonization
+ */
+type BorrowedChord = {
+    chord: Chord;
+    roman: string;
+    source: BorrowedSource;
+};
+/**
+ * The modal-interchange palette of a key.
+ *
+ * Lists the diatonic triads of the parallel key that are not diatonic to
+ * `key` (the classic borrowed chords such as `iv`, `bVI`, and `bVII` in a major
+ * key), plus the Neapolitan (a major triad on the flat second degree). Each
+ * carries its Roman numeral and {@link borrowedSource} relative to `key`.
+ *
+ * Every chord is spelled as the mode it is borrowed from writes it, recorded as
+ * a `rootSpelling` hint: C major borrows `Fm`, `Ab` and `Bb` from C minor and
+ * takes `Db` as its Neapolitan, while a minor key borrows in the other direction
+ * (A minor borrows `A`, `D` and `F#m` from A major, with `Bb` as its
+ * Neapolitan). The major dominant of a minor key — `E` in A minor — is not among
+ * them: raising the seventh degree is an alteration inside the key rather than a
+ * chord taken from the parallel mode.
+ *
+ * @param key The prevailing key, as a key name or as a key/scale.
+ * @returns The borrowed-chord palette.
+ * @example
+ * ```ts
+ * import { modalInterchangePalette, majorKey, formatChordSymbol } from '@libraz/libcantus';
+ * const palette = modalInterchangePalette(majorKey(0));
+ * palette.map((borrowed) => formatChordSymbol(borrowed.chord));
+ * // ['Cm', 'Ddim', 'Eb', 'Fm', 'Gm', 'Ab', 'Bb', 'Db'] — flat-side, not 'D#'/'G#'/'A#'
+ * ```
+ * @category Reharmonization
+ */
+declare function modalInterchangePalette(key: KeyLike): BorrowedChord[];
+/**
+ * Reflect a chord across the tonic–dominant axis of a key (negative harmony).
+ *
+ * Every pitch class `p` maps to `(2*T + 7 - p) mod 12`, where `T` is the key
+ * tonic — the reflection that swaps the tonic with the dominant. The mirrored
+ * pitch classes (including the bass, if set) are reassembled into a chord by
+ * {@link detectChordBest}; when no chord is recognized, the mirrored root and
+ * the original quality are used as a fallback.
+ *
+ * The result is spelled the way `key` writes it, as `rootSpelling` and
+ * `bassSpelling` hints, so the reflection of a chord in a flat-side key keeps
+ * flat names: in Eb major the mirror of Bb formats as `Abm`, not `G#m`.
+ *
+ * @param chord The chord to reflect, as a chord symbol or as chord data.
+ * @param key The prevailing key, as a key name or as a key/scale.
+ * @returns The negative-harmony counterpart of the chord.
+ * @example
+ * ```ts
+ * import { negativeHarmonyMirror, makeChord, majorKey } from '@libraz/libcantus';
+ * negativeHarmonyMirror(makeChord(7, 'maj'), majorKey(0));
+ * // G major reflected across C's axis => F minor (rootPc 5, quality 'min')
+ * ```
+ * @category Reharmonization
+ */
+declare function negativeHarmonyMirror(chord: ChordLike, key: KeyLike): Chord;
+
+/**
+ * Deterministic rhythm generation over a metric grid.
+ *
+ * Builds a fixed-resolution grid across one or more bars of a time signature
+ * and decides, per grid slot, whether it becomes a note onset. Onset
+ * probability follows the metric-accent hierarchy from the `meter` module, so
+ * strong positions (downbeats, secondary pulses) are favored over weak
+ * off-pulse subdivisions. Given a seed the output is fully reproducible.
+ *
+ * Positions and durations are measured in quarter-note beats, matching the
+ * library-wide convention.
+ */
+
+/**
+ * A single rhythmic note: an onset position and how long it sounds.
+ *
+ * @category Rhythm & Meter
+ */
+type RhythmEvent = {
+    /** Onset position in quarter-note beats, absolute from the start of the span. */
+    position: number;
+    /** Duration in quarter-note beats, extending to the next onset. */
+    duration: number;
+};
+/**
+ * Turn rhythm events into note events at a fixed pitch.
+ *
+ * {@link RhythmEvent} names its fields `position`/`duration` because a rhythm
+ * has no pitch; every other generator in the library speaks {@link NoteEvent}.
+ * This is the bridge, so a generated rhythm can be humanized, grooved, or
+ * written out like any other line.
+ *
+ * @param events The rhythm events to convert.
+ * @param pitch The MIDI pitch to give every note.
+ * @param velocity Velocity for every note; defaults to a mezzo-forte 96.
+ * @returns The note events, in the order given.
+ * @example
+ * ```ts
+ * import { generateRhythm, humanize, rhythmToNoteEvents } from '@libraz/libcantus';
+ * const rhythm = generateRhythm({ numerator: 4, denominator: 4 }, { bars: 2 });
+ * humanize(rhythmToNoteEvents(rhythm, 38));
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function rhythmToNoteEvents(events: RhythmEvent[], pitch: number, velocity?: number): NoteEvent[];
+/**
+ * Options controlling {@link generateRhythm}.
+ *
+ * @category Rhythm & Meter
+ */
+type RhythmOptions = {
+    /**
+     * Number of bars to generate.
+     *
+     * @defaultValue 1
+     */
+    bars?: number;
+    /**
+     * Grid resolution as the number of equal grid steps per quarter-note beat.
+     * The default of 2 yields an eighth-note grid; 4 yields a sixteenth-note
+     * grid, 3 an eighth-note triplet grid, and so on.
+     *
+     * @defaultValue 2
+     */
+    subdivision?: number;
+    /**
+     * The generation context.
+     *
+     * Its `complexity.rhythmic` is this generator's overall onset density: it
+     * scales the per-slot onset probability, so higher values fill more grid
+     * slots. A value outside [0, 1] is rejected. Its `seed` fixes which slots are
+     * taken, so the same seed always yields the same pattern.
+     *
+     * @defaultValue `{ seed: 0, complexity: { rhythmic: 0.5 } }`
+     */
+    ctx?: GenerationContextInput;
+};
+/**
+ * Map a metric weight (0–3 from {@link metricWeight}) to a base onset
+ * probability before density scaling. Strong positions are much more likely to
+ * carry an onset than weak ones; the curve is intentionally small and explicit
+ * so its behavior is easy to inspect and test.
+ *
+ * @param weight The metric weight, 0 (off-pulse) to 3 (downbeat).
+ * @returns A base onset probability in [0, 1].
+ * @category Rhythm & Meter
+ */
+declare function onsetWeightCurve(weight: number): number;
+/**
+ * Generate a deterministic rhythmic pattern over `bars` bars of a time
+ * signature. A grid is built at the chosen subdivision; each slot becomes an
+ * onset when the draw belonging to that slot falls under its metric weight
+ * scaled by the density dial. Because the draw belongs to the slot rather than
+ * to the order the slots were visited, raising the dial only adds onsets:
+ * everything already sounding stays where it was. Every bar's downbeat is always
+ * an onset, so a pattern of any length has a reliable pulse independent of the
+ * seed. Each event's duration extends to the next onset, and the last event
+ * extends to the end of the span.
+ *
+ * @param ts The time signature.
+ * @param opts Generation options.
+ * @returns Onset events sorted by position, non-overlapping, covering the span.
+ * @example
+ * ```ts
+ * import { parseTimeSignature, generateRhythm } from '@libraz/libcantus';
+ * const ts = parseTimeSignature('4/4');
+ * generateRhythm(ts, { ctx: { seed: 42, complexity: { rhythmic: 0.6 } } });
+ * // onset events over one bar
+ * ```
+ * @category Rhythm & Meter
+ */
+declare function generateRhythm(ts: TimeSignature, opts?: RhythmOptions): RhythmEvent[];
+/**
+ * Onset density of a generated pattern: the mean number of onsets per bar.
+ *
+ * @param events Events from {@link generateRhythm}.
+ * @param ts The time signature.
+ * @returns The onset count divided by the number of bars the events span.
+ * @category Rhythm & Meter
+ */
+declare function rhythmDensity(events: RhythmEvent[], ts: TimeSignature): number;
+
+export { type Section as $, type MotifCell as A, BAR_STEPS as B, type Complexity as C, DRUM_NOTES as D, type EuclideanKick as E, type MotifContour as F, GENRES as G, type HarmonizeOptions as H, type MotifNote as I, type MotifOptions as J, type MotifTransform as K, type OrnamentOptions as L, type MelodyNote as M, type OrnamentStyle as N, ORNAMENT_STYLES as O, PROVENANCE_BASES as P, type ProgFunction as Q, type ProgStyle as R, type ProgressionDegree as S, type ProgressionOptions as T, type ProgressionPreset as U, type Provenance as V, type ProvenanceBasis as W, type ResolvedContext as X, type RhythmEvent as Y, type RhythmOptions as Z, STEP_BEATS as _, BASS_STYLES as a, type SubstituteOptions as a0, type Substitution as a1, type SubstitutionType as a2, type Vocabulary as a3, type VocabularyQuery as a4, applyGrooveTemplate as a5, assertVocabulary as a6, deform as a7, developMotif as a8, double as a9, rhythmDensity as aA, rhythmToNoteEvents as aB, selectVocabulary as aC, substituteChord as aD, syncopate as aE, thin as aF, transformMotif as aG, vocabularyOfKind as aH, withinCeiling as aI, doubleTime as aa, drumVoiceOf as ab, extractGrooveTemplate as ac, fitsQuery as ad, generateBassLine as ae, generateCounterMelody as af, generateDrums as ag, generateMotif as ah, generateProgression as ai, generateRhythm as aj, gridMetricWeight as ak, halfTime as al, harmonizeMelody as am, humanize as an, mergeVocabulary as ao, modalInterchangePalette as ap, motifToNoteEvents as aq, negativeHarmonyMirror as ar, onsetWeightCurve as as, ornament as at, ornamentBy as au, pickProgressionPreset as av, pickVocabulary as aw, progressions as ax, progressionsByStyle as ay, resolveContext as az, BEAT_STEPS as b, BORROWED_DEGREES as c, type BassLineOptions as d, type BassSegment as e, type BassStyle as f, type BorrowedChord as g, type CounterMelodyOptions as h, type DeformOptions as i, type Draw as j, type DrumHit as k, type DrumRole as l, type DrumStyle as m, type DrumVoice as n, type DrumsOptions as o, type GenerationContext as p, type GenerationContextInput as q, type Genre as r, type GridEvent as s, type GrooveFeel as t, type GrooveSlot as u, type GrooveStyle as v, type GrooveTemplate as w, type HarmonizePlacement as x, type HarmonizeResult as y, type HumanizeOptions as z };