entangled-worlds-orbiters-shared 2.12.0 → 2.14.0

package/README.md

@@ -93,6 +93,12 @@ import * as EntangledWorlds from 'entangled-worlds-orbiters-shared';
 - `createStatusChannel` - Status-line seam ("Saving…", "Saved")
 - `isTrustedHostOrigin`, `isEmbedded`, `postToHost` - Host-frame transport
 
+### Note head programs (`entangled-worlds-orbiters-shared/faust`)
+- `buildVoiceProgram`, `buildHeadPrograms` - Compose a rack's note head into FAUST source, keyed by shape
+- `exportHead` - Compose, compile, shrink, size and stamp a head's programs; the compiler and the shrink tool are handed in
+- `recipesFingerprint`, `readRecipes`, `readHeadShape`, `programsNamespace` - The recipes file a build publishes, and the checks a release step makes on it
+- `largestFunction`, `shrinkWasm` - The size check and the shrink step
+
 ### Uploads (`entangled-worlds-orbiters-shared/uploads`)
 - `uploadViaSignedUrl` - The API's signed-URL upload: `/spaces/upload-init` → PUT → `/spaces/upload-complete`, over the app's own authenticated JSON caller
 - `putToSignedUrl` - The storage PUT alone, with progress and abort

package/dist/clock/curves.d.ts

@@ -4,11 +4,87 @@ export declare const Ease: {
     linear: EaseFn;
     smooth: EaseFn;
 };
-/** A single curve keyframe: a time key `t` (seconds or beats) and its value. */
+/**
+ * A single curve keyframe: a time key `t` (seconds or beats) and its value. `curve` bends the segment
+ * to the next keyframe (see {@link bend}); absent or 0 falls back to the track's `ease`.
+ */
 export interface Keyframe {
     t: number;
     value: number;
+    curve?: number;
+}
+/**
+ * How a curve moves between keyframes: `line` ramps (bent by each keyframe's `curve`), `step` holds
+ * each value until the next keyframe.
+ */
+export type CurveShape = 'line' | 'step';
+/** The range of a keyframe's `curve`: −2 … 2, 0 linear. */
+export declare const CURVE_BEND_LIMIT = 2;
+/**
+ * The bend of one segment: maps the fraction `u` in [0, 1] through `curve` c. 0 is linear; c > 0 starts
+ * slow and ends fast (exponential), c < 0 starts fast (logarithmic). The automation editor and every
+ * player read the same function, so what is drawn is what plays.
+ */
+export declare function bend(u: number, curve?: number): number;
+/**
+ * The `curve` that puts a segment's midpoint at `mid`, a share of the way from its first value to its
+ * last (0 … 1, exclusive): the inverse of {@link bend} at u = ½, for a bend handle dragged up or down.
+ */
+export declare function curveForMidpoint(mid: number): number;
+/** What {@link sampleKeyframes} needs besides the keyframes. */
+export interface SampleOptions {
+    shape?: CurveShape;
+    /** For a segment whose keyframe has no `curve` (default linear). */
+    ease?: EaseFn;
+}
+/**
+ * The value of sorted keyframes at time key `key`: held before the first and after the last, ramped
+ * (or stepped) between. NaN when there are none: an empty lane writes nothing.
+ */
+export declare function sampleKeyframes(keyframes: readonly Keyframe[], key: number, { shape, ease }?: SampleOptions): number;
+/**
+ * A loop over a curve's time key: the curve plays from 0 up to `start + length`, then repeats
+ * `start` … `start + length` (a clip's loop). `start` 0 is a curve that loops on its own length.
+ */
+export interface CurveLoop {
+    start: number;
+    length: number;
+}
+/** The curve's own time key for a running key: before the loop's end as is, then wrapped into the loop. */
+export declare function loopKey(key: number, loop: CurveLoop | null | undefined): number;
+/** One of the shapes {@link insertShape} draws: points as [u, value, curve?] over one cycle, u in [0, 1). */
+export interface CurveShapeDef {
+    id: string;
+    label: string;
+    points: ReadonlyArray<readonly [number, number, number?]>;
+    /** A closing point at the range's end, for shapes that come back to where they started. */
+    end?: number;
 }
+/** The ten shapes of the automation editor's Insert shape menu. */
+export declare const CURVE_SHAPES: readonly CurveShapeDef[];
+/** The keyframes with every one inside [from, to] replaced by `insert` (sorted). */
+export declare function replaceRange(keyframes: readonly Keyframe[], from: number, to: number, insert: readonly Keyframe[]): Keyframe[];
+/**
+ * Draws a shape over [from, to], `cycles` times, replacing only the keyframes inside the range. Null
+ * when the shape is unknown or the range is too short to draw (under 1/16 of a key unit).
+ */
+export declare function insertShape(keyframes: readonly Keyframe[], shapeId: string, from: number, to: number, cycles?: number): Keyframe[] | null;
+/** Freehand draw: one keyframe at the start of the cell [cellStart, cellStart + cellLength), replacing the cell. */
+export declare function paintCell(keyframes: readonly Keyframe[], cellStart: number, cellLength: number, value: number): Keyframe[];
+/**
+ * Recording: the keyframes after the time key moved from `prevKey` to `key` while `value` was live.
+ * What was recorded over in that span is replaced (a wrap from a loop end back to its start clears both
+ * ends of the loop). A new keyframe is written only once `spacing` has passed since `lastWritten` (null: write now),
+ * so a recording is one point per grid step, not one per frame.
+ */
+export declare function recordSpan(keyframes: readonly Keyframe[], prevKey: number, key: number, value: number, { spacing, lastWritten, loop }: {
+    spacing: number;
+    lastWritten: number | null;
+    loop?: CurveLoop | null;
+}): {
+    keyframes: Keyframe[];
+    written: number | null;
+};
 export type TimeMode = 'absolute-seconds' | 'beat-locked';
 /**
  * Structural shape of a musical projection — typed here so `./clock/curves` never imports
@@ -22,6 +98,10 @@ export interface CurveTrackSpec {
     timeMode?: TimeMode;
     projection?: ProjectionLike | null;
     ease?: EaseFn;
+    /** Line (default) or step. */
+    shape?: CurveShape;
+    /** Loops the curve's time key (a clip loop, or its own length). Absent: plays once, then holds. */
+    loop?: CurveLoop | null;
     outputIntent?: unknown;
 }
 export declare class CurveTrack {
@@ -29,11 +109,16 @@ export declare class CurveTrack {
     timeMode: TimeMode;
     projection: ProjectionLike | null;
     ease: EaseFn;
+    shape: CurveShape;
+    loop: CurveLoop | null;
     outputIntent: unknown;
     constructor(spec: CurveTrackSpec);
-    /** The track's own time key for a given clock position. */
+    /** The track's own time key for a given clock position (looped when the track loops). */
     _key(positionSec: number): number;
+    /** The value at a clock position; NaN for a track with no keyframes. */
     sample(positionSec: number): number;
+    /** The value at the track's own time key (beats for a beat-locked track), with no loop applied. */
+    sampleKey(key: number): number;
 }
 /**
  * Structural shape of the transport a GestureRecorder/Orchestrator subscribes to — typed here so

package/dist/clock/curves.js

@@ -13,40 +13,164 @@ export const Ease = {
 function lerp(a, b, t) {
     return a + (b - a) * t;
 }
+/** The range of a keyframe's `curve`: −2 … 2, 0 linear. */
+export const CURVE_BEND_LIMIT = 2;
+/**
+ * The bend of one segment: maps the fraction `u` in [0, 1] through `curve` c. 0 is linear; c > 0 starts
+ * slow and ends fast (exponential), c < 0 starts fast (logarithmic). The automation editor and every
+ * player read the same function, so what is drawn is what plays.
+ */
+export function bend(u, curve = 0) {
+    if (!curve)
+        return u;
+    return curve > 0 ? Math.pow(u, 1 + curve * 3) : 1 - Math.pow(1 - u, 1 - curve * 3);
+}
+/**
+ * The `curve` that puts a segment's midpoint at `mid`, a share of the way from its first value to its
+ * last (0 … 1, exclusive): the inverse of {@link bend} at u = ½, for a bend handle dragged up or down.
+ */
+export function curveForMidpoint(mid) {
+    const m = Math.max(0.03, Math.min(0.97, mid));
+    const c = m <= 0.5 ? (Math.log(m) / Math.log(0.5) - 1) / 3 : -(Math.log(1 - m) / Math.log(0.5) - 1) / 3;
+    return Math.max(-CURVE_BEND_LIMIT, Math.min(CURVE_BEND_LIMIT, c));
+}
+/**
+ * The value of sorted keyframes at time key `key`: held before the first and after the last, ramped
+ * (or stepped) between. NaN when there are none: an empty lane writes nothing.
+ */
+export function sampleKeyframes(keyframes, key, { shape = 'line', ease = Ease.linear } = {}) {
+    const kf = keyframes;
+    if (!kf.length)
+        return NaN;
+    if (key <= kf[0].t)
+        return kf[0].value;
+    const last = kf[kf.length - 1];
+    if (key >= last.t)
+        return last.value;
+    // Binary search: the last keyframe at or before key.
+    let lo = 0;
+    let hi = kf.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (kf[mid].t <= key)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = kf[lo];
+    const b = kf[lo + 1];
+    if (shape === 'step')
+        return a.value;
+    const frac = b.t > a.t ? (key - a.t) / (b.t - a.t) : 1;
+    return lerp(a.value, b.value, a.curve ? bend(frac, a.curve) : ease(frac));
+}
+/** The curve's own time key for a running key: before the loop's end as is, then wrapped into the loop. */
+export function loopKey(key, loop) {
+    if (!loop || !(loop.length > 0))
+        return key;
+    const end = loop.start + loop.length;
+    if (key < end)
+        return key;
+    return loop.start + ((key - end) % loop.length);
+}
+/** The ten shapes of the automation editor's Insert shape menu. */
+export const CURVE_SHAPES = [
+    { id: 'sine', label: 'Sine', points: [[0, 0.5, -0.2], [0.25, 1, 0.2], [0.5, 0.5, -0.2], [0.75, 0, 0.2]], end: 0.5 },
+    { id: 'triangle', label: 'Triangle', points: [[0, 0], [0.5, 1]], end: 0 },
+    { id: 'sawDown', label: 'Saw down', points: [[0, 1], [0.999, 0]] },
+    { id: 'sawUp', label: 'Saw up', points: [[0, 0], [0.999, 1]] },
+    { id: 'square', label: 'Square', points: [[0, 1], [0.5 - 1e-3, 1], [0.5, 0], [0.999, 0]] },
+    { id: 'curveUp', label: 'Curve up', points: [[0, 0, 1.2], [0.999, 1]] },
+    { id: 'curveDown', label: 'Curve down', points: [[0, 1, -1.2], [0.999, 0]] },
+    { id: 'sCurveUp', label: 'S-curve up', points: [[0, 0, 0.8], [0.5, 0.5, -0.8], [0.999, 1]] },
+    { id: 'sCurveDown', label: 'S-curve down', points: [[0, 1, 0.8], [0.5, 0.5, -0.8], [0.999, 0]] },
+    { id: 'attackDecay', label: 'Attack / decay', points: [[0, 0, -0.6], [0.15, 1, -1], [0.999, 0]] },
+];
+const byKey = (a, b) => a.t - b.t;
+/** The keyframes with every one inside [from, to] replaced by `insert` (sorted). */
+export function replaceRange(keyframes, from, to, insert) {
+    const eps = 1e-6;
+    return keyframes.filter((k) => k.t < from - eps || k.t > to + eps).concat(insert).sort(byKey);
+}
+/**
+ * Draws a shape over [from, to], `cycles` times, replacing only the keyframes inside the range. Null
+ * when the shape is unknown or the range is too short to draw (under 1/16 of a key unit).
+ */
+export function insertShape(keyframes, shapeId, from, to, cycles = 1) {
+    const def = CURVE_SHAPES.find((s) => s.id === shapeId);
+    if (!def || to - from < 0.0625)
+        return null;
+    const n = Math.max(1, Math.floor(cycles));
+    const len = (to - from) / n;
+    const eps = Math.min(1 / 64, len / 8);
+    const made = [];
+    for (let k = 0; k < n; k++) {
+        for (const [u, value, curve] of def.points) {
+            const t = u >= 0.999 ? from + (k + 1) * len - eps : from + (k + u) * len;
+            made.push(curve ? { t, value, curve } : { t, value });
+        }
+    }
+    if (def.end != null)
+        made.push({ t: to, value: def.end });
+    return replaceRange(keyframes, from, to, made);
+}
+/** Freehand draw: one keyframe at the start of the cell [cellStart, cellStart + cellLength), replacing the cell. */
+export function paintCell(keyframes, cellStart, cellLength, value) {
+    const eps = 1e-6;
+    return keyframes
+        .filter((k) => k.t < cellStart - eps || k.t >= cellStart + cellLength - eps)
+        .concat({ t: cellStart, value })
+        .sort(byKey);
+}
+/**
+ * Recording: the keyframes after the time key moved from `prevKey` to `key` while `value` was live.
+ * What was recorded over in that span is replaced (a wrap from a loop end back to its start clears both
+ * ends of the loop). A new keyframe is written only once `spacing` has passed since `lastWritten` (null: write now),
+ * so a recording is one point per grid step, not one per frame.
+ */
+export function recordSpan(keyframes, prevKey, key, value, { spacing, lastWritten, loop }) {
+    const wrapped = key < prevKey;
+    const start = loop ? loop.start : 0;
+    const end = loop ? loop.start + loop.length : Infinity;
+    const over = (t) => (wrapped ? (t > prevKey && t < end) || (t >= start && t <= key) : t > prevKey && t <= key);
+    const kept = keyframes.filter((k) => !over(k.t));
+    const last = lastWritten == null || wrapped ? -Infinity : lastWritten;
+    if (key - last < spacing)
+        return { keyframes: kept, written: lastWritten };
+    return { keyframes: kept.concat({ t: key, value }).sort(byKey), written: key };
+}
 export class CurveTrack {
     keyframes;
     timeMode;
     projection;
     ease;
+    shape;
+    loop;
     outputIntent;
     constructor(spec) {
-        this.keyframes = spec.keyframes.slice().sort((a, b) => a.t - b.t);
+        this.keyframes = spec.keyframes.slice().sort(byKey);
         this.timeMode = spec.timeMode ?? 'absolute-seconds';
         this.projection = spec.projection ?? null;
         this.ease = spec.ease ?? Ease.linear;
+        this.shape = spec.shape ?? 'line';
+        this.loop = spec.loop ?? null;
         this.outputIntent = spec.outputIntent ?? null;
         if (this.timeMode === 'beat-locked' && !this.projection) {
             throw new Error('beat-locked CurveTrack needs a MusicalProjection');
         }
     }
-    /** The track's own time key for a given clock position. */
+    /** The track's own time key for a given clock position (looped when the track loops). */
     _key(positionSec) {
-        return this.timeMode === 'beat-locked' ? this.projection.secondsToBeats(positionSec) : positionSec;
+        const key = this.timeMode === 'beat-locked' ? this.projection.secondsToBeats(positionSec) : positionSec;
+        return loopKey(key, this.loop);
     }
+    /** The value at a clock position; NaN for a track with no keyframes. */
     sample(positionSec) {
-        const k = this._key(positionSec);
-        const kf = this.keyframes;
-        if (k <= kf[0].t)
-            return kf[0].value;
-        if (k >= kf[kf.length - 1].t)
-            return kf[kf.length - 1].value;
-        let i = 0;
-        while (i < kf.length - 1 && kf[i + 1].t <= k)
-            i++;
-        const a = kf[i];
-        const b = kf[i + 1];
-        const frac = (k - a.t) / (b.t - a.t);
-        return lerp(a.value, b.value, this.ease(frac));
+        return this.sampleKey(this._key(positionSec));
+    }
+    /** The value at the track's own time key (beats for a beat-locked track), with no loop applied. */
+    sampleKey(key) {
+        return sampleKeyframes(this.keyframes, key, { shape: this.shape, ease: this.ease });
     }
 }
 /**

package/dist/faust/headExport.d.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 { type VoiceSlot } from './voiceProgram.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 declare function collectParamAddresses(ui: FaustUiItem[] | null | undefined): string[];
+/** 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;
+}
+/**
+ * `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 declare function exportHead(slots: readonly VoiceSlot[], tools: HeadExportTools): Promise<HeadExport>;

package/dist/faust/headExport.js

@@ -0,0 +1,89 @@
+/**
+ * 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 } from './voiceProgram.js';
+import { HEAVY_FUNCTION_BYTES, largestFunction } from './wasmSize.js';
+/** Every control address in the DSP's UI tree, in Faust's own order. */
+export function collectParamAddresses(ui) {
+    const out = [];
+    const walk = (items) => items.forEach((item) => {
+        if (item.items)
+            walk(item.items);
+        else if (item.address)
+            out.push(item.address);
+    });
+    walk(ui ?? []);
+    return out;
+}
+function base64(bytes) {
+    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) {
+    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, source, tools) {
+    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 = 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, tools) {
+    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/dist/faust/index.d.ts

@@ -0,0 +1,4 @@
+export * from './voiceProgram.js';
+export * from './wasmSize.js';
+export * from './headExport.js';
+export * from './recipes.js';

package/dist/faust/index.js

@@ -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';

package/dist/faust/recipes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 { type VoiceSlot } from './voiceProgram.js';
+export interface Recipes {
+    /** `.dsp` file name → FAUST source. */
+    sources: Readonly<Record<string, string>>;
+    /** Library file name → FAUST source, mounted beside the standard ones. */
+    libraries: Readonly<Record<string, string>>;
+    /** The compiler: the version of the package that carries libfaust. */
+    faust: string;
+    /** The compiler's options. */
+    options: string;
+    /** The runtime contract a program compiled from these plays under. */
+    runtime: number;
+}
+export declare const isRecipesFingerprint: (value: unknown) => value is string;
+/** The file a fingerprint names, as the app publishes it. */
+export declare const recipesFileName: (fingerprint: string) => string;
+/** A hash of everything a compile reads and is told (SHA-256, its first 16 hex digits). */
+export declare function recipesFingerprint(recipes: Recipes): Promise<string>;
+/** A downloaded recipes file, if it reads as one; anything else is null. */
+export declare function readRecipes(value: unknown): Recipes | null;
+/**
+ * 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 declare 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 declare function programsNamespace(fingerprint: string, shrink: string): Promise<string>;
+/** The most World dimensions an Orbiter has: a head each. */
+export declare const MAX_HEADS = 3;
+/** The most note modules in front of an instrument: a generator and the MIDI effects. */
+export declare const MAX_HEAD_NOTE_MODULES = 12;
+/**
+ * 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 declare function readHeadShape(value: unknown, sources: Readonly<Record<string, string>>): VoiceSlot[];
+/** One head's programs on a release: their keys, and whether the author was told it is heavy. */
+export interface ReleasedHead {
+    /** Null when nothing sits in front of the instrument. */
+    notes: string | null;
+    instrument: string;
+    heavy?: boolean;
+}
+/** What a release carries of its programs: written by the server at release, never by a client. */
+export interface ReleasedPrograms {
+    /** The runtime contract the programs were built for. */
+    runtime: number;
+    /** Where they are filed (`programsNamespace`): what they were built from and with. */
+    sources: string;
+    /** By World dimension id. */
+    heads: Record<string, ReleasedHead>;
+}
+/** A release's programs, if what it carries reads as them; anything else is no programs. */
+export declare function readReleasedPrograms(value: unknown): ReleasedPrograms | null;