entangled-worlds-orbiters-shared 2.12.0 → 2.14.0

package/dist/faust/recipes.js

@@ -0,0 +1,102 @@
+/**
+ * The recipes file: everything one build of the app compiles its programs from, in one file named by
+ * a fingerprint of its content.
+ *
+ * The app publishes it beside its compiler; the release step fetches it by the fingerprint the author's
+ * page sends, checks the content against the name, and compiles from exactly that. The sources stay
+ * where they are authored: nothing else has to hold a copy of them in step.
+ *
+ * The fingerprint covers all of it (the sources, the libraries, the compiler's version and options,
+ * the runtime contract), so two builds that would compile a different program never share a name.
+ */
+import { MAX_NOTE_LANES } from './voiceProgram.js';
+const FINGERPRINT = /^[0-9a-f]{16}$/;
+export const isRecipesFingerprint = (value) => typeof value === 'string' && FINGERPRINT.test(value);
+/** The file a fingerprint names, as the app publishes it. */
+export const recipesFileName = (fingerprint) => `sources-${fingerprint}.json`;
+async function shortHash(parts) {
+    const text = new TextEncoder().encode(JSON.stringify(parts));
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', text));
+    return Array.from(digest.subarray(0, 8), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** A hash of everything a compile reads and is told (SHA-256, its first 16 hex digits). */
+export function recipesFingerprint(recipes) {
+    const sorted = (files) => Object.keys(files).sort().map((file) => [file, files[file]]);
+    return shortHash([sorted(recipes.sources), sorted(recipes.libraries), recipes.faust, recipes.options, recipes.runtime]);
+}
+const isTextMap = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+    && Object.values(value).every((text) => typeof text === 'string');
+/** A downloaded recipes file, if it reads as one; anything else is null. */
+export function readRecipes(value) {
+    const recipes = value;
+    if (!recipes || typeof recipes !== 'object')
+        return null;
+    if (!isTextMap(recipes.sources) || !isTextMap(recipes.libraries) || !Object.keys(recipes.sources).length)
+        return null;
+    if (typeof recipes.faust !== 'string' || typeof recipes.options !== 'string' || !Number.isInteger(recipes.runtime))
+        return null;
+    return { sources: recipes.sources, libraries: recipes.libraries, faust: recipes.faust, options: recipes.options, runtime: recipes.runtime };
+}
+/**
+ * How this package composes a program from a shape. Raise it when the same shape would compose to
+ * different text: a test keeps a fingerprint of the composed text beside it and fails until then.
+ */
+export const COMPOSER_VERSION = 1;
+/**
+ * Where a build's compiled programs are filed: the recipes, the shrink step and the composer
+ * together. A file under it is never replaced, so a release keeps the programs it was given.
+ */
+export function programsNamespace(fingerprint, shrink) {
+    return shortHash([fingerprint, shrink, COMPOSER_VERSION]);
+}
+/** The most World dimensions an Orbiter has: a head each. */
+export const MAX_HEADS = 3;
+/** The most note modules in front of an instrument: a generator and the MIDI effects. */
+export const MAX_HEAD_NOTE_MODULES = 12;
+/** The largest program constant an instrument takes. */
+const MAX_CONSTANT = 64;
+const whole = (value, most) => Number.isInteger(value) && value >= 1 && value <= most;
+/**
+ * A head's shape as a client sent it, checked before anything is composed from it: the note modules
+ * in rack order, then the instrument. Every file must be one of the recipes', every count a whole
+ * number inside the rack's limits. Returns the shape with nothing else on it; throws with the reason.
+ */
+export function readHeadShape(value, sources) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > MAX_HEAD_NOTE_MODULES + 1)
+        throw new Error('a head is 1 to 13 modules');
+    return value.map((slot, index) => {
+        const file = slot?.dspFileName;
+        const notes = slot?.notes;
+        if (typeof file !== 'string' || !Object.hasOwn(sources, file))
+            throw new Error(`module ${index}: no such source`);
+        const last = index === value.length - 1;
+        if (last) {
+            if (notes?.kind !== 'instrument' || !whole(notes.polyphony, MAX_NOTE_LANES))
+                throw new Error(`module ${index}: a head ends with an instrument of 1 to ${MAX_NOTE_LANES} voices`);
+            const constants = notes.constants ?? {};
+            if (typeof constants !== 'object' || Array.isArray(constants))
+                throw new Error(`module ${index}: constants`);
+            const entries = Object.entries(constants);
+            if (entries.length > 8 || entries.some(([name, n]) => !/^[A-Z][A-Z0-9_]{0,23}$/.test(name) || !whole(n, MAX_CONSTANT)))
+                throw new Error(`module ${index}: constants`);
+            return { dspFileName: file, notes: { kind: 'instrument', polyphony: notes.polyphony, ...(entries.length ? { constants: Object.fromEntries(entries) } : {}) } };
+        }
+        if ((notes?.kind !== 'generator' && notes?.kind !== 'midi') || !whole(notes.lanesPerLane, MAX_NOTE_LANES))
+            throw new Error(`module ${index}: a note module with 1 to ${MAX_NOTE_LANES} lanes per lane`);
+        return { dspFileName: file, notes: { kind: notes.kind, lanesPerLane: notes.lanesPerLane } };
+    });
+}
+const isHead = (head) => {
+    const h = head;
+    return Boolean(h && typeof h === 'object' && typeof h.instrument === 'string' && (h.notes === null || typeof h.notes === 'string'));
+};
+/** A release's programs, if what it carries reads as them; anything else is no programs. */
+export function readReleasedPrograms(value) {
+    const programs = value;
+    if (!programs || typeof programs !== 'object' || !Number.isInteger(programs.runtime) || typeof programs.sources !== 'string')
+        return null;
+    if (!/^[a-z0-9]+$/i.test(programs.sources) || !programs.heads || typeof programs.heads !== 'object')
+        return null;
+    const heads = Object.fromEntries(Object.entries(programs.heads).filter(([, head]) => isHead(head)));
+    return Object.keys(heads).length ? { runtime: programs.runtime, sources: programs.sources, heads } : null;
+}

package/dist/faust/voiceProgram.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Composing a rack description into one FAUST program.
+ *
+ * This is the play runtime's source: the same per-module `.dsp` files the edit
+ * runtime compiles standalone, stitched together with `component()` so both
+ * runtimes are built from one authored source. Parity is structural, and
+ * measured — a two-module chain renders bit-identically either way.
+ *
+ * ## The slot group is not optional
+ *
+ * Two instances of the same module in one program **silently collapse into a
+ * single control**:
+ *
+ *     process = component("psGain.dsp") : component("psGain.dsp");
+ *     -> one address: /psVoice/gain
+ *
+ * Both multiplies still happen, so the audio is right, but the two slots share
+ * one parameter and move together — and Faust does not warn. Wrapping each slot
+ * in its own group fixes it and costs nothing:
+ *
+ *     process = hgroup("s0", component(...)) : hgroup("s1", component(...));
+ *     -> /psVoice/s0/gain, /psVoice/s1/gain
+ *
+ * That group name is also the **per-slot identity** a single compiled program
+ * was said to lack. It has one — as long as the composer never forgets, which
+ * is why it is emitted here rather than left to each `.dsp`, and why
+ * `slotGroupId` is derived from the slot index and cannot be omitted.
+ *
+ * ## A note chain
+ *
+ * A head rack that plays notes composes as lanes (`lib/ps_notes.lib`):
+ *
+ *     process = nt.entry(8)                                            // the lanes the allocator writes
+ *       : hgroup("s0", nt.bypass(8, 1, library("pitch.dsp")[SLOT=0;].notes(8)))
+ *       : hgroup("tap0", nt.tap(8))                                    // the notes leaving s0
+ *       : hgroup("s1", library("synth.dsp")[SLOT=1;].play(8))          // a note voice per lane
+ *       : hgroup("s2", component("filter.dsp"));
+ *
+ * One entry at the head, sized by the instrument's polyphony; each generator or MIDI effect takes the
+ * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
+ * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
+ * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * since `notes(n)` is told only n.
+ */
+/** The most note lanes one head plays: what reaches the instrument after every note module has multiplied them. */
+export declare const MAX_NOTE_LANES = 16;
+/**
+ * What a slot does with notes: a notes instrument's polyphony (and its program constants, when it has
+ * any), or a generator's or MIDI effect's lanes out per lane in.
+ */
+export type SlotNotes = {
+    kind: 'instrument';
+    polyphony: number;
+    constants?: Readonly<Record<string, number>>;
+    copies?: number;
+} | {
+    kind: 'generator' | 'midi';
+    lanesPerLane: number;
+};
+/** One slot of a composed voice: the module's `.dsp`, by file name. */
+export interface VoiceSlot {
+    dspFileName: string;
+    /**
+     * A note module, with what it does with notes at its stored values (the registry's `resolveNotes`):
+     * a generator or MIDI effect's lanes out per lane in, or a notes instrument's polyphony. Both are
+     * structural: they shape the program.
+     */
+    notes?: SlotNotes;
+}
+/**
+ * The group name for a slot. Index-based, so it is stable across renames and
+ * unique by construction — the two properties the collision above needs.
+ */
+export declare function slotGroupId(index: number): string;
+/** The address a slot's control has once composed: `/<voice>/<group>/<control>`. */
+export declare function composedParamAddress(voiceName: string, index: number, controlName: string): string;
+/**
+ * Build the `.dsp` source for one voice. `voiceName` is the program name and the address root;
+ * `slots` the ordered rack chain.
+ */
+export declare function buildVoiceProgram({ voiceName, slots }?: {
+    voiceName?: string;
+    slots?: readonly VoiceSlot[];
+}): string;
+/** The group of the tap after a note module (its slot index): the notes leaving it. */
+export declare function tapGroupId(index: number): string;
+/**
+ * A stable key for a composed voice.
+ *
+ * The compiled program is a pure function of the ordered slot list, so this is
+ * what makes "compile once, then every listener fetches a finished artifact"
+ * possible. It deliberately covers *only* what changes the program: the modules
+ * and their order. Parameter **values** are written into the running unit and
+ * must not invalidate the cache — a knob turn is not a recompile
+ * (`reactivity: 'live'` versus `'structural'`).
+ *
+ */
+export declare function voiceCacheKey(slots: readonly VoiceSlot[] | null | undefined): string;
+/**
+ * The name every program of a released head declares. A control's address starts with it, so with one
+ * name the two programs of a head read as one (`/psHead/s0/rate`, `/psHead/s1/cutoff`), and an
+ * instrument's program is the same file whichever Orbiter plays it.
+ */
+export declare const HEAD_PROGRAM_NAME = "psHead";
+/** One program of a released head: what it is filed under, and its source. */
+export interface HeadProgram {
+    key: string;
+    source: string;
+}
+/**
+ * A released head, as the programs play mode downloads: the note modules as one (the entry, each
+ * module in its bypass, a tap after each; its outputs are the lanes), and the instrument as another
+ * (its inputs are those lanes), played one after the other in one audio processor.
+ */
+export interface HeadPrograms {
+    /** Null when nothing sits in front of the instrument: its program then carries the entry itself. */
+    notes: HeadProgram | null;
+    instrument: HeadProgram;
+    /** The lanes between the two (three signals a lane). */
+    lanes: number;
+}
+/**
+ * A head composed for release: always two programs when a note module sits in front of the
+ * instrument, so neither grows past the size a phone still optimises, and the instrument's (the
+ * large one) depends only on the instrument, its lanes, its constants and its place: every Orbiter
+ * with that instrument there shares one file.
+ *
+ * `slots`: the note modules in rack order, then the instrument (the audio effects after it stay
+ * units of their own). The addresses are the ones `buildVoiceProgram` gives the same chain.
+ */
+export declare function buildHeadPrograms(slots: readonly VoiceSlot[]): HeadPrograms;

package/dist/faust/voiceProgram.js

@@ -0,0 +1,242 @@
+/**
+ * Composing a rack description into one FAUST program.
+ *
+ * This is the play runtime's source: the same per-module `.dsp` files the edit
+ * runtime compiles standalone, stitched together with `component()` so both
+ * runtimes are built from one authored source. Parity is structural, and
+ * measured — a two-module chain renders bit-identically either way.
+ *
+ * ## The slot group is not optional
+ *
+ * Two instances of the same module in one program **silently collapse into a
+ * single control**:
+ *
+ *     process = component("psGain.dsp") : component("psGain.dsp");
+ *     -> one address: /psVoice/gain
+ *
+ * Both multiplies still happen, so the audio is right, but the two slots share
+ * one parameter and move together — and Faust does not warn. Wrapping each slot
+ * in its own group fixes it and costs nothing:
+ *
+ *     process = hgroup("s0", component(...)) : hgroup("s1", component(...));
+ *     -> /psVoice/s0/gain, /psVoice/s1/gain
+ *
+ * That group name is also the **per-slot identity** a single compiled program
+ * was said to lack. It has one — as long as the composer never forgets, which
+ * is why it is emitted here rather than left to each `.dsp`, and why
+ * `slotGroupId` is derived from the slot index and cannot be omitted.
+ *
+ * ## A note chain
+ *
+ * A head rack that plays notes composes as lanes (`lib/ps_notes.lib`):
+ *
+ *     process = nt.entry(8)                                            // the lanes the allocator writes
+ *       : hgroup("s0", nt.bypass(8, 1, library("pitch.dsp")[SLOT=0;].notes(8)))
+ *       : hgroup("tap0", nt.tap(8))                                    // the notes leaving s0
+ *       : hgroup("s1", library("synth.dsp")[SLOT=1;].play(8))          // a note voice per lane
+ *       : hgroup("s2", component("filter.dsp"));
+ *
+ * One entry at the head, sized by the instrument's polyphony; each generator or MIDI effect takes the
+ * lanes so far and multiplies them by its `lanesPerLane`, inside its note-domain bypass; the
+ * instrument plays every lane that reaches it. `SLOT` is the module's place, its part of the seed;
+ * a module that adds lanes (a structural `lanesOut`) also gets `LANES_OUT`, its lanes out per lane in,
+ * since `notes(n)` is told only n.
+ */
+/** The most note lanes one head plays: what reaches the instrument after every note module has multiplied them. */
+export const MAX_NOTE_LANES = 16;
+/** Faust identifiers: the group name goes into generated source, so keep it tame. */
+const SAFE_SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The group name for a slot. Index-based, so it is stable across renames and
+ * unique by construction — the two properties the collision above needs.
+ */
+export function slotGroupId(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`[voiceProgram] slot index must be a non-negative integer, got ${index}`);
+    }
+    return `s${index}`;
+}
+/** The address a slot's control has once composed: `/<voice>/<group>/<control>`. */
+export function composedParamAddress(voiceName, index, controlName) {
+    return `/${voiceName}/${slotGroupId(index)}/${controlName}`;
+}
+/**
+ * Build the `.dsp` source for one voice. `voiceName` is the program name and the address root;
+ * `slots` the ordered rack chain.
+ */
+export function buildVoiceProgram({ voiceName, slots } = {}) {
+    if (!SAFE_SEGMENT.test(String(voiceName ?? ''))) {
+        throw new Error(`[voiceProgram] unsafe voice name: ${voiceName}`);
+    }
+    if (!Array.isArray(slots) || slots.length === 0) {
+        throw new Error('[voiceProgram] a voice needs at least one slot');
+    }
+    slots.forEach((slot, index) => {
+        const file = String(slot?.dspFileName ?? '');
+        if (!/^[A-Za-z0-9_.-]+\.dsp$/.test(file)) {
+            throw new Error(`[voiceProgram] slot ${index}: unsafe dsp file name "${file}"`);
+        }
+    });
+    const head = slots.findIndex((slot) => slot.notes?.kind === 'instrument');
+    const noteParts = head < 0 ? [] : noteChain(slots, head);
+    if (head < 0 && slots.some((slot) => slot.notes)) {
+        throw new Error('[voiceProgram] a generator or MIDI effect needs a notes instrument after it');
+    }
+    // The group is emitted here, for every slot, always. See the note above.
+    const rest = slots.slice(head + 1).map((slot, i) => `hgroup("${slotGroupId(head + 1 + i)}", component("${slot.dspFileName}"))`);
+    const chain = [...noteParts, ...rest].join('\n  : ');
+    return `declare name "${voiceName}";\n`
+        + '// GENERATED per voice by src/audio/modules/engines/faust/voiceProgram.ts — not authored.\n'
+        + (noteParts.length ? 'nt = library("ps_notes.lib");\n' : '')
+        + `process = ${chain};\n`;
+}
+/** The group of the tap after a note module (its slot index): the notes leaving it. */
+export function tapGroupId(index) {
+    return `tap${index}`;
+}
+/** The entry and the note modules before `head` (the instrument), and the lanes that reach it. */
+function noteModules(slots, head) {
+    const instrument = slots[head].notes;
+    let lanes = wholeAtLeastOne(instrument.polyphony, `slot ${head}: polyphony`);
+    // A tap after every note module: the notes leaving it, for the meters and screens. The entry has
+    // none: the main thread knows what it sends in (the keys, MIDI in, the clip's notes reported back).
+    const parts = [`nt.entry(${lanes})`];
+    slots.slice(0, head).forEach((slot, index) => {
+        const notes = slot.notes;
+        if (!notes || notes.kind === 'instrument') {
+            throw new Error(`[voiceProgram] slot ${index}: only generators and MIDI effects sit before a notes instrument`);
+        }
+        const k = wholeAtLeastOne(notes.lanesPerLane, `slot ${index}: lanesPerLane`);
+        // A module that adds lanes is told how many it puts out per lane in (an echo's repeats + 1).
+        const env = k === 1 ? `SLOT = ${index};` : `SLOT = ${index}; LANES_OUT = ${k};`;
+        const fx = `library("${slot.dspFileName}")[${env}].notes(${lanes})`;
+        parts.push(`hgroup("${slotGroupId(index)}", nt.bypass(${lanes}, ${k}, ${fx}))`);
+        lanes *= k;
+        parts.push(`hgroup("${tapGroupId(index)}", nt.tap(${lanes}))`);
+    });
+    if (lanes > MAX_NOTE_LANES) {
+        throw new Error(`[voiceProgram] ${lanes} note lanes reach the instrument; it plays at most ${MAX_NOTE_LANES}`);
+    }
+    return { parts, lanes };
+}
+/** The instrument at `head`, playing `lanes` lanes: the last part of a note chain. */
+function instrumentPart(slots, head, lanes) {
+    // The instrument's place salts its random draws too (an LFO's Random), as every note module's does;
+    // its program constants (unison's `U`) shape it, as its polyphony does.
+    const constants = Object.entries(slots[head].notes.constants ?? {})
+        .map(([name, value]) => {
+        if (!/^[A-Z][A-Z0-9_]*$/.test(name))
+            throw new Error(`[voiceProgram] slot ${head}: unsafe constant ${name}`);
+        return ` ${name} = ${wholeAtLeastOne(value, `slot ${head}: ${name}`)};`;
+    }).join('');
+    return `hgroup("${slotGroupId(head)}", library("${slots[head].dspFileName}")[SLOT = ${head};${constants}].play(${lanes}))`;
+}
+/** The entry, the note modules and the instrument, up to `head` (the instrument): lanes all the way. */
+function noteChain(slots, head) {
+    const { parts, lanes } = noteModules(slots, head);
+    return [...parts, instrumentPart(slots, head, lanes)];
+}
+function wholeAtLeastOne(value, what) {
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error(`[voiceProgram] ${what} is a whole number of 1 or more, got ${value}`);
+    return value;
+}
+/**
+ * A stable key for a composed voice.
+ *
+ * The compiled program is a pure function of the ordered slot list, so this is
+ * what makes "compile once, then every listener fetches a finished artifact"
+ * possible. It deliberately covers *only* what changes the program: the modules
+ * and their order. Parameter **values** are written into the running unit and
+ * must not invalidate the cache — a knob turn is not a recompile
+ * (`reactivity: 'live'` versus `'structural'`).
+ *
+ */
+export function voiceCacheKey(slots) {
+    // A note module's lane count is structural too: it shapes the program.
+    const shape = (slots ?? []).map((slot) => {
+        const notes = slot?.notes;
+        const constants = notes?.kind === 'instrument' ? constantsKey(notes.constants) : '';
+        const lanes = !notes ? '' : notes.kind === 'instrument' ? `#p${notes.polyphony}${constants}` : `#${notes.kind}${notes.lanesPerLane}`;
+        return String(slot?.dspFileName ?? '') + lanes;
+    }).join('>');
+    return `v${fnv(shape)}`;
+}
+/**
+ * An instrument's program constants as part of a key: by name, each name closed off from its value
+ * (`U=12` and `U1=2` are different programs), so the same constants give the same key in any order.
+ */
+function constantsKey(constants) {
+    return Object.entries(constants ?? {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([name, value]) => `#${name}=${value}`).join('');
+}
+/**
+ * The hash of a released program's key: two passes of FNV-1a from different starts, 64 bits. Files
+ * are stored under it for good and shared between Orbiters, so two shapes must not meet in one.
+ */
+function fileKey(text) {
+    return fnv(text) + fnv(text, 0x9e3779b9);
+}
+/** FNV-1a: short, dependency-free, and only needs to distinguish rack shapes. */
+function fnv(text, start = 0x811c9dc5) {
+    let hash = start;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+/**
+ * The name every program of a released head declares. A control's address starts with it, so with one
+ * name the two programs of a head read as one (`/psHead/s0/rate`, `/psHead/s1/cutoff`), and an
+ * instrument's program is the same file whichever Orbiter plays it.
+ */
+export const HEAD_PROGRAM_NAME = 'psHead';
+/**
+ * A head composed for release: always two programs when a note module sits in front of the
+ * instrument, so neither grows past the size a phone still optimises, and the instrument's (the
+ * large one) depends only on the instrument, its lanes, its constants and its place: every Orbiter
+ * with that instrument there shares one file.
+ *
+ * `slots`: the note modules in rack order, then the instrument (the audio effects after it stay
+ * units of their own). The addresses are the ones `buildVoiceProgram` gives the same chain.
+ */
+export function buildHeadPrograms(slots) {
+    const head = slots.length - 1;
+    if (slots[head]?.notes?.kind !== 'instrument')
+        throw new Error('[voiceProgram] a head ends with its notes instrument');
+    const instrument = slots[head];
+    const notes = instrument.notes;
+    const constants = constantsKey(notes.constants);
+    const header = `declare name "${HEAD_PROGRAM_NAME}";\n// GENERATED per head by voiceProgram.ts (not authored).\n`;
+    if (head === 0) {
+        return {
+            notes: null,
+            instrument: {
+                key: `i${fileKey(`alone>${instrument.dspFileName}#p${notes.polyphony}${constants}`)}`,
+                source: buildVoiceProgram({ voiceName: HEAD_PROGRAM_NAME, slots }),
+            },
+            lanes: notes.polyphony,
+        };
+    }
+    slots.forEach((slot, index) => {
+        const file = String(slot?.dspFileName ?? '');
+        if (!/^[A-Za-z0-9_.-]+\.dsp$/.test(file))
+            throw new Error(`[voiceProgram] slot ${index}: unsafe dsp file name "${file}"`);
+    });
+    const { parts, lanes } = noteModules(slots, head);
+    // FAUST roots a program's controls in a group named after it only when it has several groups at the
+    // top: named here, both programs' addresses start as the one program's do, whatever each holds.
+    const root = (chain) => `vgroup("${HEAD_PROGRAM_NAME}", ${chain})`;
+    const shape = slots.slice(0, head).map((slot) => `${slot.dspFileName}#${slot.notes.kind}${slot.notes.lanesPerLane}`).join('>');
+    return {
+        notes: {
+            key: `n${fileKey(`${shape}>#p${notes.polyphony}`)}`,
+            source: `${header}nt = library("ps_notes.lib");\nprocess = ${root(parts.join('\n  : '))};\n`,
+        },
+        instrument: {
+            key: `i${fileKey(`behind>${instrument.dspFileName}#l${lanes}#s${head}${constants}`)}`,
+            source: `${header}process = ${root(instrumentPart(slots, head, lanes))};\n`,
+        },
+        lanes,
+    };
+}

package/dist/faust/wasmSize.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How large a compiled program's largest function is. Safari never optimises a wasm function over
+ * 100 000 bytes: a program past that line stays on its baseline tier for good, three to five times
+ * the cost, and FAUST writes a whole program as one `compute`.
+ */
+/** Under Safari's 100 000 with a margin: a program that reaches this is heavy on an iPhone. */
+export declare const HEAVY_FUNCTION_BYTES = 90000;
+/** The size of a wasm module's largest function body: for a compiled DSP, its `compute`. */
+export declare function largestFunction(wasm: Uint8Array): number;
+/**
+ * The shrink step's passes: only the ones that tidy locals. FAUST's wasm keeps a local for every
+ * value and never reuses one; these make the same program a quarter smaller, bit for bit the same
+ * output. Binaryen's general optimisation is no smaller and made the optimised code slower.
+ */
+export declare const SHRINK_PASSES: readonly ["simplify-locals", "coalesce-locals", "vacuum", "reorder-locals"];
+/** The part of Binaryen the shrink step uses: handed in, so this folder imports nothing. */
+export interface ShrinkTool {
+    readBinary(wasm: Uint8Array): {
+        runPasses(passes: string[]): void;
+        emitBinary(): Uint8Array;
+        dispose(): void;
+    };
+}
+/** A compiled DSP made smaller, computing exactly what it did. */
+export declare function shrinkWasm(binaryen: ShrinkTool, wasm: Uint8Array): Uint8Array;
+/** What the step is, for the stamp of a program it shrank: another Binaryen or other passes is another program. */
+export declare const shrinkVersion: (binaryenMajor: string | number) => string;

package/dist/faust/wasmSize.js

@@ -0,0 +1,56 @@
+/**
+ * How large a compiled program's largest function is. Safari never optimises a wasm function over
+ * 100 000 bytes: a program past that line stays on its baseline tier for good, three to five times
+ * the cost, and FAUST writes a whole program as one `compute`.
+ */
+/** Under Safari's 100 000 with a margin: a program that reaches this is heavy on an iPhone. */
+export const HEAVY_FUNCTION_BYTES = 90_000;
+/** The size of a wasm module's largest function body: for a compiled DSP, its `compute`. */
+export function largestFunction(wasm) {
+    let at = 8;
+    const leb = () => {
+        let value = 0;
+        for (let shift = 0;; shift += 7) {
+            const byte = wasm[at];
+            at += 1;
+            value |= (byte & 0x7f) << shift;
+            if (!(byte & 0x80))
+                return value >>> 0;
+        }
+    };
+    while (at < wasm.length) {
+        const id = wasm[at];
+        at += 1;
+        const size = leb();
+        if (id === 10) {
+            let largest = 0;
+            for (let count = leb(); count > 0; count -= 1) {
+                const body = leb();
+                largest = Math.max(largest, body);
+                at += body;
+            }
+            return largest;
+        }
+        at += size;
+    }
+    return 0;
+}
+/**
+ * The shrink step's passes: only the ones that tidy locals. FAUST's wasm keeps a local for every
+ * value and never reuses one; these make the same program a quarter smaller, bit for bit the same
+ * output. Binaryen's general optimisation is no smaller and made the optimised code slower.
+ */
+export const SHRINK_PASSES = ['simplify-locals', 'coalesce-locals', 'vacuum', 'reorder-locals'];
+/** A compiled DSP made smaller, computing exactly what it did. */
+export function shrinkWasm(binaryen, wasm) {
+    const module = binaryen.readBinary(wasm);
+    try {
+        module.runPasses([...SHRINK_PASSES]);
+        return module.emitBinary();
+    }
+    finally {
+        module.dispose();
+    }
+}
+/** What the step is, for the stamp of a program it shrank: another Binaryen or other passes is another program. */
+export const shrinkVersion = (binaryenMajor) => `binaryen-${binaryenMajor}:${SHRINK_PASSES.join(',')}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entangled-worlds-orbiters-shared",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "Shared library for entangled worlds orbiters - contains core world rendering, moons system, and UI components",
   "type": "module",
   "main": "src/index.js",
@@ -42,6 +42,10 @@
       "types": "./dist/capabilities/index.d.ts",
       "import": "./dist/capabilities/index.js"
     },
+    "./faust": {
+      "types": "./dist/faust/index.d.ts",
+      "import": "./dist/faust/index.js"
+    },
     "./notes": {
       "types": "./dist/notes/index.d.ts",
       "import": "./dist/notes/index.js"
@@ -84,6 +88,14 @@
     "three": "^0.166.1",
     "three-stdlib": "^2.34.0"
   },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    },
+    "three-stdlib": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^20.19.0",
@@ -114,10 +126,11 @@
     "test:clock": "node --test --import tsx src/clock/*.test.ts",
     "test:capabilities": "node --test --import tsx src/capabilities/*.test.js",
     "test:notes": "node --test --import tsx src/notes/*.test.ts",
+    "test:faust": "node --test --import tsx src/faust/*.test.ts",
     "test:studio": "node --test --import tsx src/studio/*.test.js",
     "test:uploads": "node --test --import tsx src/uploads/*.test.js",
     "test:render": "node --test src/render/*.test.js",
-    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
+    "test": "npm run test:clock && npm run test:capabilities && npm run test:notes && npm run test:faust && npm run test:studio && npm run test:uploads && npm run test:render && npm run test:moons && npm run test:star",
     "test:moons": "node --test src/moons/*.test.js",
     "test:star": "node --test --import tsx src/star/*.test.ts",
     "bench:star:build": "esbuild bench/star/main.ts --bundle --format=esm --target=es2022 --outfile=bench/star/build/main.js --log-level=warning",