entangled-worlds-orbiters-shared 2.13.0 → 2.14.0

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.13.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",

package/src/faust/headExport.ts

@@ -0,0 +1,171 @@
+/**
+ * A head made ready for play mode: its programs composed, compiled, shrunk, sized and stamped.
+ *
+ * Play mode downloads finished programs: no compiler in the page, no first-build wait on a phone.
+ * This is the step that makes them, once, when an Orbiter is released. It runs where a compiler and
+ * the shrink step exist (a server, a build, a test), never in a listener's browser, so both arrive
+ * as tools rather than imports: this file stays pure.
+ *
+ * For one head (`voiceProgram.ts`, `buildHeadPrograms`):
+ *
+ * 1. **Compose** its programs: the note modules as one, the instrument as another; the instrument
+ *    alone when nothing sits in front of it.
+ * 2. **Compile** each with the app's own options.
+ * 3. **Shrink** each (the same step the module build uses: the same program, a quarter smaller).
+ * 4. **Size** each: past the heavy line its largest function is one Safari may never optimise. The
+ *    export still goes through; the author is told.
+ * 5. **Stamp** the export with what it was built from and the runtime it expects.
+ *
+ * A released Orbiter keeps its sound: an export stays valid when a module's source changes later
+ * (the stamp says what it was built from). Play mode refuses it only when the runtime it expects is
+ * no longer the app's, and then plays as it would have without one.
+ */
+import { buildHeadPrograms, HEAD_PROGRAM_NAME, type VoiceSlot } from './voiceProgram.js';
+import { HEAVY_FUNCTION_BYTES, largestFunction } from './wasmSize.js';
+
+/** One item of Faust's UI tree: a group (with `items`) or a control. */
+export interface FaustUiItem {
+  type: string;
+  label: string;
+  address?: string;
+  init?: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  items?: FaustUiItem[];
+  [field: string]: unknown;
+}
+
+/** Faust's metadata for a compiled DSP (its JSON): the UI tree, inputs, outputs, declares. */
+export interface FaustDspMeta {
+  name: string;
+  inputs: number;
+  outputs: number;
+  compile_options: string;
+  ui: FaustUiItem[];
+  meta?: Array<Record<string, string>>;
+  [field: string]: unknown;
+}
+
+/** A compiled program as it is stored and downloaded: its wasm and the description of its controls. */
+export interface CompiledProgram {
+  /** Faust's sha key; the `registerProcessor` name. */
+  processorName: string;
+  dspName: string;
+  dspMeta: FaustDspMeta;
+  /** Fully-qualified control addresses, in Faust's order. */
+  paramAddresses: string[];
+  wasmBase64: string;
+  /** 4 for a single-precision build, 8 for -double. */
+  sampleSize: 4 | 8;
+}
+
+/** Every control address in the DSP's UI tree, in Faust's own order. */
+export function collectParamAddresses(ui: FaustUiItem[] | null | undefined): string[] {
+  const out: string[] = [];
+  const walk = (items: FaustUiItem[]) => items.forEach((item) => {
+    if (item.items) walk(item.items);
+    else if (item.address) out.push(item.address);
+  });
+  walk(ui ?? []);
+  return out;
+}
+
+/** What an export was built from, and what it needs to play. */
+export interface HeadExportStamp {
+  /** The runtime contract the programs were built for: the app's, as its recipes file names it. */
+  runtime: number;
+  /** The FAUST compiler's version, and its options. */
+  faust: string;
+  options: string;
+  /** The shrink step's version. */
+  shrink: string;
+  /** The fingerprint of the recipes file: every `.dsp` source and library the compiler could read. */
+  sources: string;
+}
+
+/** The compiler and the shrink step, handed in by whoever runs the export. */
+export interface HeadExportTools {
+  /** Compile `source` under `name` with the sources and libraries mounted: FAUST's factory. */
+  compile(name: string, source: string): Promise<{ code: Uint8Array; json: string; shaKey: string }>;
+  /** The same program, smaller. */
+  shrink(wasm: Uint8Array): Uint8Array;
+  /**
+   * A program already filed under this key, if there is one: it is taken as it is, never compiled
+   * again (an instrument's program is the same file for every Orbiter that plays it).
+   */
+  find?(key: string): Promise<CompiledProgram | null>;
+  stamp: HeadExportStamp;
+}
+
+/** One finished program of a head. */
+export interface ExportedProgram {
+  /** What it is filed under: its shape. */
+  key: string;
+  artifact: CompiledProgram;
+  /** Its largest function, in bytes, and whether that is past the heavy line. */
+  largestFunction: number;
+  heavy: boolean;
+}
+
+export interface HeadExport {
+  /** Null when nothing sits in front of the instrument. */
+  notes: ExportedProgram | null;
+  instrument: ExportedProgram;
+  stamp: HeadExportStamp;
+}
+
+function base64(bytes: Uint8Array): string {
+  let binary = '';
+  // In pieces: one call with every byte as an argument overflows the stack on a large program.
+  for (let at = 0; at < bytes.length; at += 0x8000) binary += String.fromCharCode(...bytes.subarray(at, at + 0x8000));
+  return btoa(binary);
+}
+
+function bytes(text: string): Uint8Array {
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+async function exportProgram(key: string, source: string, tools: HeadExportTools): Promise<ExportedProgram> {
+  const filed = await tools.find?.(key);
+  if (filed) {
+    const size = largestFunction(bytes(filed.wasmBase64));
+    return { key, artifact: filed, largestFunction: size, heavy: size > HEAVY_FUNCTION_BYTES };
+  }
+  const factory = await tools.compile(HEAD_PROGRAM_NAME, source);
+  const wasm = tools.shrink(factory.code);
+  const dspMeta: FaustDspMeta = JSON.parse(factory.json);
+  const size = largestFunction(wasm);
+  return {
+    key,
+    artifact: {
+      processorName: factory.shaKey,
+      dspName: HEAD_PROGRAM_NAME,
+      dspMeta,
+      paramAddresses: collectParamAddresses(dspMeta.ui),
+      wasmBase64: base64(wasm),
+      sampleSize: dspMeta.compile_options.includes('-double') ? 8 : 4,
+    },
+    largestFunction: size,
+    heavy: size > HEAVY_FUNCTION_BYTES,
+  };
+}
+
+/**
+ * `slots`: the head's note modules in rack order, then its instrument, each with what it does with
+ * notes. Throws when a program does not compile: the caller saves the release without programs, and
+ * play mode plays as it does without them.
+ */
+export async function exportHead(slots: readonly VoiceSlot[], tools: HeadExportTools): Promise<HeadExport> {
+  const programs = buildHeadPrograms(slots);
+  // One after the other: one libfaust compiles one program at a time.
+  const notes = programs.notes ? await exportProgram(programs.notes.key, programs.notes.source, tools) : null;
+  const instrument = await exportProgram(programs.instrument.key, programs.instrument.source, tools);
+  if (notes && notes.artifact.dspMeta.outputs !== instrument.artifact.dspMeta.inputs) {
+    throw new Error(`[headExport] the note modules put out ${notes.artifact.dspMeta.outputs} signals; the instrument takes ${instrument.artifact.dspMeta.inputs}`);
+  }
+  return { notes, instrument, stamp: tools.stamp };
+}

package/src/faust/index.ts

@@ -0,0 +1,7 @@
+// Composing a rack's note head into FAUST programs, and making them ready for play mode: shared by
+// the app that plays them and the server step that compiles them at release, so the source, its key
+// and its file name are the same on both sides. Pure: the compiler and the shrink tool are handed in.
+export * from './voiceProgram.js';
+export * from './wasmSize.js';
+export * from './headExport.js';
+export * from './recipes.js';