narrator-ts 0.0.0 → 0.1.1

package/dist/narrator/speak.js

@@ -0,0 +1,206 @@
+/**
+ * narrator.device's front half, end to end — `hunk+0x7fe` to `hunk+0x872` of
+ * build 33.2.
+ *
+ * The device's `CMD_WRITE` is a straight run of eleven jumps, and this is
+ * those eleven with the arrays threaded between them. Nothing here is a
+ * decision of its own: every stage is a routine ported and checked on its own
+ * against the binary, and the only thing this adds is the order and the shape
+ * of the workspace they share.
+ *
+ * The output is a **frame array** — eight bytes per frame, the thing
+ * `render()` turns into samples — and, if asked, the mouth-shape stream that
+ * runs alongside it.
+ *
+ * The tables are a parameter rather than a constant. They are Commodore's,
+ * extracted from a binary this project does not redistribute, so the library
+ * takes them from the caller and ships none.
+ */
+import { markContour, assignPitch } from './contour.js';
+import { assignDurations } from './duration.js';
+import { allocate, compact, continuationDurations, fill, markFirst, blendTransitions, markTransitions, } from './frames.js';
+import { applyGain, fillMarkedRuns, fillZeroRuns, intrinsicPitch, nasalise, shapeFrication, smooth7, smooth7Weighted, smoothMouths, } from './interpolate.js';
+import { markOnsets } from './onset.js';
+import { MAX_PHONEMES, parse, TERMINATOR } from './parse.js';
+import { nextPhrase, pitchLoopBody } from './prosody.js';
+import { rewrite } from './rewrite.js';
+import { spreadStress } from './stress.js';
+import { render } from './render.js';
+import { audioPeriod, PAL_CLOCK, renderTables, voiceFrom, } from './voice.js';
+/** What the device reports in `io_Error` rather than speaking. */
+export class SpeakError extends Error {
+    at;
+    constructor(message, 
+    /** 1-based offset of the offending character, when the parser found one. */
+    at) {
+        super(message);
+        this.at = at;
+        this.name = 'SpeakError';
+    }
+}
+/** The eight `0x80`-byte per-syllable arrays at `A5+0x6e8`. */
+const ARRAYS = 8;
+const ARRAY_LEN = 0x80;
+/** `hunk+0x1e1c` steps the three cursors past the parser's two lead-in slots. */
+const LEAD_IN = 2;
+/**
+ * Turn a phoneme string into frames, exactly as `CMD_WRITE` does.
+ *
+ * **One sentence per call.** The parser stops at the first `.` or `?` and
+ * reports how much of the input it took; `hunk+0x8ba` loops on that, speaking
+ * each sentence as a separate buffer. {@link synthesize} is that loop, and
+ * this is one turn of it — which is what a caller wants only if it is doing
+ * the looping itself.
+ *
+ * `input` is bytes rather than a string because the device works in Latin-1
+ * and reads one byte past what it was given.
+ */
+export function synthesizeSentence(input, voice, opts = {}) {
+    const { attrs, params } = voice;
+    const pitch = opts.pitch ?? 110;
+    const mode = opts.mode ?? 0;
+    // ------------------------------------------------------------------ 0xf68
+    const parsed = parse(input, voice.table);
+    if (parsed.error !== undefined) {
+        throw new SpeakError(`not a phoneme at character ${parsed.error}`, parsed.error);
+    }
+    // 0x804: the parser's `Z` exit — it found the lead-in and nothing else.
+    // The driver treats that as the end of the whole utterance and not as an
+    // empty sentence to skip, so trailing whitespace speaks nothing at all
+    // rather than a stray frame or two of it.
+    if (parsed.count === 0)
+        return null;
+    const { phonemes, stress, flags } = parsed;
+    const state = { phonemes, stress, flags, count: parsed.count };
+    // 0x112c, then the first rewrite pass, then the stress spreader.
+    markOnsets(state, attrs);
+    if (!rewrite(state, voice.rules[0], attrs)) {
+        throw new SpeakError('too many phonemes after the first rewrite pass');
+    }
+    spreadStress(state, attrs);
+    // ----------------------------------------------------------------- 0x1e1c
+    // The pitch stage's own workspace: eight arrays, seven counters, and three
+    // cursors that start past the lead-in.
+    const prosody = {
+        phonemes,
+        stress,
+        flags,
+        atPhoneme: LEAD_IN,
+        atStress: LEAD_IN,
+        atFlag: LEAD_IN,
+        arr: Array.from({ length: ARRAYS }, () => new Uint8Array(ARRAY_LEN)),
+        arrAt: 0,
+        counters: {
+            pass: 0, stresses: 0, syllables: 0, first: 0,
+            boundaries: 0, last: 0, total: 0,
+        },
+    };
+    // 0x832: one phrase per turn until there is none left.
+    while (nextPhrase(prosody, attrs))
+        pitchLoopBody(prosody, attrs, mode);
+    // 0x846: durations, then the second rewrite pass.
+    assignDurations(state, attrs, params);
+    if (!rewrite(state, voice.rules[1], attrs)) {
+        throw new SpeakError('too many phonemes after the second rewrite pass');
+    }
+    // ----------------------------------------------------------------- 0x1454
+    // Seven routines that turn phonemes and durations into the frame array.
+    compact(state, attrs);
+    continuationDurations(state, attrs, params);
+    const { frames, total } = allocate(state);
+    const mouths = opts.mouths ? new Uint8Array(total) : undefined;
+    fill(state, attrs, params, frames, opts.sex ? voice.altParams : undefined, mouths);
+    markFirst(frames);
+    blendTransitions(state, attrs, params, frames);
+    markTransitions(state, attrs, params, frames);
+    // ----------------------------------------------------------------- 0x19bc
+    markContour(state, attrs);
+    assignPitch(state, contourArrays(prosody), frames, { pitch, mode });
+    // ----------------------------------------------------------------- 0x29d8
+    // Four columns of holes filled, two smoothed, the microprosody, then the
+    // frication and nasal fixes, the amplitudes, and the gain curve.
+    for (const column of [0, 1, 2, 7])
+        fillZeroRuns(frames, column);
+    smooth7(frames, 1);
+    smooth7Weighted(frames, 2);
+    intrinsicPitch(phonemes, flags, attrs, frames);
+    smooth7(frames, 7);
+    shapeFrication(phonemes, flags, attrs, frames);
+    for (const column of [3, 4, 5])
+        fillMarkedRuns(frames, column);
+    applyGain(frames, voice.gain);
+    nasalise(phonemes, flags, attrs, params, frames);
+    if (mouths)
+        smoothMouths(mouths, total);
+    return { frames, total, mouths, consumed: parsed.consumed };
+}
+/**
+ * Everything a string has to say, one buffer per sentence.
+ *
+ * `hunk+0x7e6` to `hunk+0x8bc` — the driver's outer loop. It runs the whole
+ * pipeline, hands the frames to `audio.device`, and comes back for whatever
+ * the parser did not take, until the parser reports nothing left.
+ *
+ * The buffers are kept apart rather than joined because the device keeps them
+ * apart: every one is a separate `CMD_WRITE` to the audio hardware, and the
+ * renderer's waveform pointer and pitch phase start again at each. Joining
+ * the frames and rendering once would give different samples.
+ */
+export function synthesize(input, voice, opts = {}) {
+    const out = [];
+    let at = 0;
+    // 0x7e6: advance by what the last pass took, and go again.
+    while (at < input.length) {
+        const speech = synthesizeSentence(input.subarray(at), voice, opts);
+        // Nothing left worth speaking, however many bytes remain.
+        if (speech === null)
+            break;
+        // A pass that took nothing would loop forever; the device cannot reach
+        // it, because a parse that consumed nothing found nothing.
+        if (speech.consumed === 0)
+            break;
+        at += speech.consumed;
+        out.push(speech);
+    }
+    return out;
+}
+/**
+ * The four arrays `hunk+0x1a8e` reads, out of the eight the pitch stage keeps.
+ *
+ * It addresses them from the array *bases*, not from the cursors the loop
+ * advanced, so this is deliberately not `subarray(arrAt)`.
+ */
+function contourArrays(prosody) {
+    return {
+        onset: prosody.arr[0],
+        peak: prosody.arr[1],
+        end: prosody.arr[2],
+        tail: prosody.arr[3],
+    };
+}
+/** Re-exported so a caller can size a buffer without reaching into `parse`. */
+export { MAX_PHONEMES, TERMINATOR };
+/**
+ * Phonemes in, samples out — `CMD_WRITE` and the audio it would have written.
+ *
+ * Each sentence is rendered on its own and the samples joined, because that
+ * is what the device does: every sentence is a separate buffer handed to
+ * `audio.device`, and the renderer's waveform pointer and pitch phase start
+ * again at each.
+ *
+ * `input` is bytes rather than a string because the device works in Latin-1
+ * and reads one byte past what it was given.
+ */
+export function speak(input, data, opts = {}) {
+    const sentences = synthesize(input, voiceFrom(data), opts);
+    const tables = renderTables(data, opts);
+    const parts = sentences.map((s) => render(s.frames, tables));
+    const pcm = new Int8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const part of parts) {
+        pcm.set(part, at);
+        at += part.length;
+    }
+    const period = audioPeriod(opts.sampfreq);
+    return { pcm, period, sampleRate: Math.round(PAL_CLOCK / period), sentences };
+}

package/dist/narrator/stress.d.ts

@@ -0,0 +1,36 @@
+/**
+ * narrator.device's stress spreader — hunk+0x11bc of build 33.2.
+ *
+ * The parser leaves a stress digit sitting on the one phoneme it was written
+ * after. This stage turns that into something the frame generator can use: it
+ * walks the phoneme array vowel by vowel and spreads a descriptor across each
+ * syllable, out to the midpoint between one vowel and the next, and marks
+ * word and phrase boundaries in the flag array.
+ *
+ * It runs after the first rewrite pass, so it sees allophones rather than what
+ * was typed. See research/02-narrator.md.
+ */
+import type { Attrs } from './rewrite.js';
+/** Bits this stage writes into the stress array. */
+export declare const STRESS: {
+    /** 0x1274 and 0x124c: this phoneme carries a spread descriptor. */
+    readonly MARK: 128;
+    /** 0x1230: set on every spread byte. */
+    readonly SPREAD: 64;
+    /** 0x122e: the source vowel had a stress digit. */
+    readonly STRESSED: 32;
+};
+/** Bits this stage writes into the flag array. */
+export declare const FLAG: {
+    /** 0x1280: this phoneme is the vowel of its syllable. */
+    readonly VOWEL: 128;
+    /** 0x12b4: everything from the last vowel to a phrase-final pause. */
+    readonly PHRASE_END: 64;
+};
+export interface StressState {
+    phonemes: Uint8Array;
+    stress: Uint8Array;
+    flags: Uint8Array;
+}
+/** Spread stress across syllables and mark boundaries, in place. */
+export declare function spreadStress(state: StressState, attrs: Attrs): void;

package/dist/narrator/stress.js

@@ -0,0 +1,147 @@
+/**
+ * narrator.device's stress spreader — hunk+0x11bc of build 33.2.
+ *
+ * The parser leaves a stress digit sitting on the one phoneme it was written
+ * after. This stage turns that into something the frame generator can use: it
+ * walks the phoneme array vowel by vowel and spreads a descriptor across each
+ * syllable, out to the midpoint between one vowel and the next, and marks
+ * word and phrase boundaries in the flag array.
+ *
+ * It runs after the first rewrite pass, so it sees allophones rather than what
+ * was typed. See research/02-narrator.md.
+ */
+import { TERMINATOR } from './parse.js';
+/** Attribute bits this stage tests. */
+const ATTR = {
+    /** Bit 0: a stress digit may follow — which is also "is a vowel". */
+    VOWEL: 1 << 0,
+    /** Bit 25: ends a phrase — `.`, `?`, `,` or `-`. */
+    TERMINAL: 1 << 25,
+};
+/** Bits this stage writes into the stress array. */
+export const STRESS = {
+    /** 0x1274 and 0x124c: this phoneme carries a spread descriptor. */
+    MARK: 0x80,
+    /** 0x1230: set on every spread byte. */
+    SPREAD: 0x40,
+    /** 0x122e: the source vowel had a stress digit. */
+    STRESSED: 0x20,
+};
+/** Bits this stage writes into the flag array. */
+export const FLAG = {
+    /** 0x1280: this phoneme is the vowel of its syllable. */
+    VOWEL: 0x80,
+    /** 0x12b4: everything from the last vowel to a phrase-final pause. */
+    PHRASE_END: 0x40,
+};
+/** `LX` and `RX` are vowels by attribute but not by this stage's reckoning. */
+const LX = 0x18;
+const RX = 0x17;
+/**
+ * 68k `dbra`: the body runs once, then repeats while the decremented *word*
+ * is not -1.
+ *
+ * Written out rather than turned into a `for` because a count of -1 does not
+ * mean "no iterations" here — it means 65536 of them, walking off the end of
+ * the array. That is a real property of the routine, and a port that quietly
+ * treats a negative count as zero is not reproducing it.
+ */
+function dbra(count, body) {
+    let d = count & 0xffff;
+    for (;;) {
+        body();
+        d = (d - 1) & 0xffff;
+        if (d === 0xffff)
+            return;
+    }
+}
+/** Spread stress across syllables and mark boundaries, in place. */
+export function spreadStress(state, attrs) {
+    const { phonemes, stress, flags } = state;
+    let at = 1; // D0
+    let spanStart = 2; // D2, where the current syllable's spread begins
+    let vowel = 0; // D4, the last vowel's position; 0 for none
+    let desc = 0; // D6, the descriptor being spread — persists across spans
+    let lastAttrs = 0; // D3, the attributes of the last phoneme looked up
+    for (;;) {
+        at++;
+        const p = phonemes[at];
+        // 0x11e4 and 0x11f6: a space or a phrase-final pause closes the span.
+        // Note a space jumps here *without* looking the phoneme up, so `lastAttrs`
+        // still describes whatever came before it — which 0x12a6 then tests.
+        let boundary = p === 0;
+        if (!boundary) {
+            if (p === TERMINATOR)
+                return; // 0x11ec
+            lastAttrs = attrs[p] ?? 0;
+            boundary = (lastAttrs & ATTR.TERMINAL) !== 0;
+        }
+        if (!boundary) {
+            // 0x11fe: consonants are simply skipped.
+            if (!(lastAttrs & ATTR.VOWEL))
+                continue;
+            // 0x1206: and these two are vowels by attribute only.
+            if (p === LX || p === RX)
+                continue;
+            if (vowel === 0) {
+                // 0x1216: the first vowel of a span only records its position.
+                vowel = at;
+                continue;
+            }
+            // 0x121a: from the second vowel on, spread the *previous* vowel's
+            // descriptor forward to the midpoint between the two.
+            let n = at - vowel;
+            n = ((n - 1) >> 1) + vowel - spanStart;
+            desc = (((stress[vowel] & 0x10) << 1) | STRESS.SPREAD) & 0xff;
+            // 0x1234: a span starting on LX or RX gives it the descriptor without
+            // the mark bit, and the spread proper starts one later.
+            const first = phonemes[spanStart];
+            if (first === LX || first === RX) {
+                stress[spanStart] |= desc;
+                spanStart++;
+                n--;
+            }
+            // 0x124c sits *outside* the loop — the `dbra` at 0x1258 branches to
+            // 0x1252, not to it — so only the first byte of a spread is marked.
+            // Putting it inside is the obvious reading and marks the whole span.
+            stress[spanStart] |= STRESS.MARK;
+            dbra(n, () => {
+                stress[spanStart] |= desc;
+                spanStart++;
+            });
+            vowel = at;
+            continue;
+        }
+        // ---------------------------------------------------------- 0x1262
+        // A boundary. Close the span, then reset.
+        const first = phonemes[spanStart];
+        if (first === LX || first === RX)
+            spanStart++;
+        stress[spanStart] |= STRESS.MARK;
+        if (vowel !== 0) {
+            flags[vowel] |= FLAG.VOWEL;
+            // 0x1290: the descriptor keeps its SPREAD bit from the previous span
+            // and only its STRESSED bit is recomputed. That carry-over is why this
+            // reads as one running value rather than one per syllable.
+            desc = ((desc & ~STRESS.STRESSED) | ((stress[vowel] & 0x10) << 1)) & 0xff;
+            dbra(at - spanStart - 1, () => {
+                stress[spanStart] |= desc;
+                spanStart++;
+            });
+            // 0x12a6: only a phrase-final pause marks back to the vowel. A plain
+            // space does not, and `lastAttrs` being stale across a space is exactly
+            // what makes that work.
+            if (lastAttrs & ATTR.TERMINAL) {
+                spanStart = vowel;
+                dbra(at - vowel - 1, () => {
+                    flags[spanStart] |= FLAG.PHRASE_END;
+                    spanStart++;
+                });
+            }
+        }
+        // 0x12c0: begin the next span after the boundary.
+        spanStart = at + 1;
+        vowel = 0;
+        desc = 0;
+    }
+}

package/dist/narrator/voice.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The device's own tables, and the two numbers the renderer derives from the
+ * speech parameters.
+ *
+ * Everything here is Commodore's data rather than this project's, so it is
+ * loaded rather than written down: `tools/gen-voice.py` pulls it out of a
+ * `narrator.device` binary the user supplies, and {@link voiceFrom} turns that
+ * JSON into the shapes {@link synthesize} and {@link render} want.
+ */
+import type { RenderTables } from './render.js';
+import type { Rule } from './rewrite.js';
+import type { Voice } from './speak.js';
+/** One `narrator-<version>.json`, exactly as `gen-voice.py` writes it. */
+export interface VoiceData {
+    version: string;
+    source: string;
+    names: string[];
+    attrs: number[];
+    params: Record<string, number[]>;
+    paramsAlt: Record<string, number[]>;
+    stressed: number[];
+    unstressed: number[];
+    gain: number[];
+    rules: Record<'allophones' | 'frames', {
+        rules: Rule[];
+    }>;
+    wave: number[];
+    amp: number[];
+    fricatives: number[][];
+}
+/** The front half's tables, as {@link synthesize} wants them. */
+export declare function voiceFrom(data: VoiceData): Voice;
+/** The parameters the back half is sensitive to. */
+export interface RenderOptions {
+    /** `narrator_rb.sampfreq`, 5000..28000. The device's default is 22200. */
+    sampfreq?: number;
+    /** `narrator_rb.rate` in words per minute, 40..400. Default 150. */
+    rate?: number;
+    /** `narrator_rb.sex`. Anything non-zero shortens the waveform step. */
+    sex?: number;
+}
+/**
+ * hunk+0x53fa. How long a frame lasts, and how fast the waveform is walked.
+ *
+ * `periodCount` is `sampfreq x 75 / rate / 60 / 2` — samples per frame, so
+ * `rate` is a speaking rate in the most direct sense available: it divides the
+ * time every frame is given without touching any of the frame counts the front
+ * half computed. Doubling it halves the length of the utterance and changes
+ * nothing else.
+ *
+ * `waveStep` is how many samples pass between steps along the waveform table,
+ * and it is 9 for the second voice and 11 for the first — the one place `sex`
+ * reaches the renderer at all, and what makes the second voice brighter rather
+ * than merely higher.
+ */
+export declare function renderTables(data: VoiceData, opts?: RenderOptions): RenderTables;
+/**
+ * hunk+0x52e2. The Paula period the device asks `audio.device` for, which is
+ * what actually sets the sample rate.
+ *
+ * The numerator is the PAL colour clock over two, so playing the samples back
+ * at `3546895 / period` Hz is what a real Amiga would have done.
+ */
+export declare function audioPeriod(sampfreq?: number): number;
+/** PAL Paula's clock, for turning that period into a sample rate. */
+export declare const PAL_CLOCK = 3546895;

package/dist/narrator/voice.js

@@ -0,0 +1,78 @@
+/**
+ * The device's own tables, and the two numbers the renderer derives from the
+ * speech parameters.
+ *
+ * Everything here is Commodore's data rather than this project's, so it is
+ * loaded rather than written down: `tools/gen-voice.py` pulls it out of a
+ * `narrator.device` binary the user supplies, and {@link voiceFrom} turns that
+ * JSON into the shapes {@link synthesize} and {@link render} want.
+ */
+/** The front half's tables, as {@link synthesize} wants them. */
+export function voiceFrom(data) {
+    const col = (k) => data.params[k] ?? [];
+    const params = {
+        f1: col('f1'), f2: col('f2'), f3: col('f3'),
+        a1: col('a1'), a2: col('a2'), a3: col('a3'),
+        voicing: col('voicing'),
+        stressed: data.stressed,
+        unstressed: data.unstressed,
+        rank: col('rank'), weight: col('weight'),
+        transitionIn: col('transitionIn'), transitionOut: col('transitionOut'),
+        mouth: col('mouth'),
+    };
+    return {
+        table: { names: data.names, attrs: data.attrs },
+        attrs: data.attrs.slice(0, params.f1.length),
+        params,
+        altParams: {
+            f1: data.paramsAlt.f1 ?? [],
+            f2: data.paramsAlt.f2 ?? [],
+            f3: data.paramsAlt.f3 ?? [],
+        },
+        gain: data.gain,
+        rules: [data.rules.allophones.rules, data.rules.frames.rules],
+    };
+}
+/**
+ * hunk+0x53fa. How long a frame lasts, and how fast the waveform is walked.
+ *
+ * `periodCount` is `sampfreq x 75 / rate / 60 / 2` — samples per frame, so
+ * `rate` is a speaking rate in the most direct sense available: it divides the
+ * time every frame is given without touching any of the frame counts the front
+ * half computed. Doubling it halves the length of the utterance and changes
+ * nothing else.
+ *
+ * `waveStep` is how many samples pass between steps along the waveform table,
+ * and it is 9 for the second voice and 11 for the first — the one place `sex`
+ * reaches the renderer at all, and what makes the second voice brighter rather
+ * than merely higher.
+ */
+export function renderTables(data, opts = {}) {
+    const sampfreq = opts.sampfreq ?? 22200;
+    const rate = opts.rate ?? 150;
+    // `mulu.w`, `divu.w`, an `andi.l` that throws the remainder away, then a
+    // second `divu.w` and a shift — all in word arithmetic.
+    let n = (sampfreq * 0x4b) & 0xffffffff;
+    n = Math.floor(n / rate) & 0xffff;
+    n = Math.floor(n / 0x3c) >>> 1;
+    return {
+        wave: Uint8Array.from(data.wave),
+        ampTable: Uint8Array.from(data.amp),
+        fricatives: data.fricatives.map((f) => Uint8Array.from(f)),
+        periodCount: n,
+        // 0x5420: `+2` when `sex` is zero, so the *first* voice is the slow one.
+        waveStep: opts.sex ? 9 : 11,
+    };
+}
+/**
+ * hunk+0x52e2. The Paula period the device asks `audio.device` for, which is
+ * what actually sets the sample rate.
+ *
+ * The numerator is the PAL colour clock over two, so playing the samples back
+ * at `3546895 / period` Hz is what a real Amiga would have done.
+ */
+export function audioPeriod(sampfreq = 22200) {
+    return Math.floor(0x369c78 / sampfreq) & 0xffff;
+}
+/** PAL Paula's clock, for turning that period into a sample rate. */
+export const PAL_CLOCK = 3546895;

package/dist/translator/engines.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Behavioural differences between translator.library builds.
+ *
+ * The rule *tables* are near-identical across every shipped build — 1.3 has
+ * 700 rules, everything later has 701, and the text barely moves. What
+ * actually changes is the matcher, so version differences are expressed as
+ * code traits here rather than as data.
+ */
+export interface EngineTraits {
+    /**
+     * Whether `-ER` and `-ING` may be followed by a trailing `S` and still
+     * count as a suffix for `%`.
+     *
+     * 1.3's handler (hunk 0x422-0x47e) sends S, D and R alike to a single
+     * "next character must not be a letter" check. 31.7 onwards inserts a
+     * branch at 0x46a that accepts one `S` first, which is 16 bytes longer —
+     * visible in the jump table, where the following handler sits at 0x490
+     * instead of 0x480.
+     *
+     * The effect is on words like `brokers`, `atomizers` and `backsliders`:
+     * with the trailing S accepted, `[O]^%` fires and gives the long vowel
+     * (`BROW4KERZ`); without it the rule fails and the catch-all short vowel
+     * applies (`BRAA4KERZ`).
+     */
+    suffixAllowsTrailingS: boolean;
+}
+/**
+ * Confirmed by running every build under the oracle over the same 9,804
+ * phrases: 31.7, 33.2, 34.3, 36.1 and 37.1 are output-identical to each
+ * other, and 1.3 differs from all of them in 78 phrases.
+ *
+ * `reference/nrl-table.json` is not a build and is named `nrl-7948`. It takes
+ * the 1.3 behaviour, and not merely by falling through: the report's SNOBOL
+ * defines SUFFIX as ER/E/ES/ED/ING/ELY and requires the suffix to end the
+ * word outright. The trailing-S allowance is SoftVoice's addition.
+ */
+export declare function engineFor(version: string): EngineTraits;

package/dist/translator/engines.js

@@ -0,0 +1,26 @@
+/**
+ * Behavioural differences between translator.library builds.
+ *
+ * The rule *tables* are near-identical across every shipped build — 1.3 has
+ * 700 rules, everything later has 701, and the text barely moves. What
+ * actually changes is the matcher, so version differences are expressed as
+ * code traits here rather than as data.
+ */
+const V1 = { suffixAllowsTrailingS: false };
+const V31 = { suffixAllowsTrailingS: true };
+/**
+ * Confirmed by running every build under the oracle over the same 9,804
+ * phrases: 31.7, 33.2, 34.3, 36.1 and 37.1 are output-identical to each
+ * other, and 1.3 differs from all of them in 78 phrases.
+ *
+ * `reference/nrl-table.json` is not a build and is named `nrl-7948`. It takes
+ * the 1.3 behaviour, and not merely by falling through: the report's SNOBOL
+ * defines SUFFIX as ER/E/ES/ED/ING/ELY and requires the suffix to end the
+ * word outright. The trailing-S allowance is SoftVoice's addition.
+ */
+export function engineFor(version) {
+    if (version.startsWith('nrl'))
+        return V1;
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    return Number.isFinite(major) && major >= 31 ? V31 : V1;
+}

package/dist/translator/index.d.ts

@@ -0,0 +1,3 @@
+export { translate, createTranslator } from './translate.js';
+export { CLASS } from './types.js';
+export type { Rule, TranslatorTables, TranslateResult } from './types.js';

package/dist/translator/index.js

@@ -0,0 +1,2 @@
+export { translate, createTranslator } from './translate.js';
+export { CLASS } from './types.js';

package/dist/translator/translate.d.ts

@@ -0,0 +1,10 @@
+import { type EngineTraits } from './engines.js';
+import { type Rule, type TranslateResult, type TranslatorTables } from './types.js';
+export declare function translate(text: string, tables: TranslatorTables, outSize?: number): TranslateResult;
+/** Convenience wrapper around a fixed table set. */
+export declare function createTranslator(tables: TranslatorTables): {
+    version: string;
+    translate: (text: string, outSize?: number) => TranslateResult;
+};
+export type { Rule, TranslatorTables, TranslateResult };
+export type { EngineTraits };