@hraness/dawg 0.6.1 → 0.8.0

package/src/render.ts

@@ -36,6 +36,7 @@ import {
   sectionCues,
 } from "./audio/arrange.ts";
 import { SampleLibrary, hasSamplerTracks } from "./audio/samples.ts";
+import { withClipLengths } from "./audio/clips.ts";
 import {
   PackStore,
   creditsLine,
@@ -118,6 +119,14 @@ export async function runRenderCommand(
       );
       return 1;
     }
+    // Clips crossing the section's edges are cut against their files' real
+    // ends, so read their lengths first (load problems are reported below).
+    if (score.tracks.some((track) => track.clips)) {
+      const bank = await new SampleLibrary({ projectRoot: workspace }).load(
+        score,
+      );
+      score = withClipLengths(score, bank);
+    }
     // One section as it plays when looped: its mutes and variations, no form.
     score = withNoteCap(BAKED_NOTE_CAP, () =>
       sectionScore(bakeTrackTime(score), section),
@@ -226,7 +235,13 @@ export async function runRenderCommand(
   const sha = createHash("sha256").update(wav).digest("hex");
   const seconds = audio.frames / audio.sampleRate;
   stdout.write(
-    `rendered · ${target} · ${seconds.toFixed(2)} s · ${wav.byteLength} bytes · ${sha}\n`,
+    `rendered · ${target} · ${seconds.toFixed(2)} s · ${audio.sampleRate} Hz${
+      // A plain song keeps 0.4's 22.05 kHz (byte-identical renders); say
+      // so, since its ceiling is 11 kHz and cymbal air is lost.
+      rateArg === undefined && !score.master
+        ? " (--rate 48000 for full band)"
+        : ""
+    } · ${wav.byteLength} bytes · ${sha}\n`,
   );
   if (credits) stdout.write(`credits · ${credits}\n`);
   const clipped = clippedSamples(audio.pcm);
@@ -238,6 +253,10 @@ export async function runRenderCommand(
           : "lower track volumes or add a master with a limiter (master streaming, or master: { limiter: {} } in song.ts)"
       }\n`,
     );
+  if (audio.nonFinite)
+    stderr.write(
+      `warning · ${audio.nonFinite.samples} non-finite ${audio.nonFinite.samples === 1 ? "sample" : "samples"} zeroed · from ${audio.nonFinite.tracks.join(", ")} · an effect or voice setting is unstable\n`,
+    );
   if (options.has("--measure"))
     stdout.write(
       `loudness · ${measurementLine(measureRendered(audio, false).mix, audio.master)}\n`,

package/src/session/client.ts

@@ -8,8 +8,14 @@ import {
   LineDecoder,
   MAX_SERVER_FRAME_BYTES,
   parseServerMessage,
+  PROTOCOL_MAX,
+  PROTOCOL_MIN,
+  ProtocolError,
   type ApplyResult,
   type ClientMessage,
+  type LiveMessage,
+  type LiveStatus,
+  type PaneView,
   type PresenceEntry,
   type ServerMessage,
   type TransportAction,
@@ -34,6 +40,13 @@ export type DaemonClientOptions = {
   sessionId: string;
   label?: string;
   clientId?: string;
+  /** Who is at this window; see src/identity/actor.ts. */
+  actor?: { id: string; name: string };
+  /**
+   * Protocol range to offer. Defaults to this build's full range; tests pin
+   * `{vMin: 1, vMax: 1}` to act as an old client.
+   */
+  versions?: { vMin: number; vMax: number };
   focusedTrackId?: string | null;
   /** Spawn a detached daemon when none answers. Defaults to true. */
   spawn?: boolean;
@@ -74,6 +87,11 @@ export class DaemonClient {
   public transport!: TransportState;
   public presence: PresenceEntry[] = [];
   public daemonPid = 0;
+  /** Negotiated revision: 1 until a v2 daemon says otherwise. */
+  public protocol = 1;
+  public caps: readonly string[] = [];
+  /** Last intent seq this client issued; retries resend the same one. */
+  private seq = 0;
   private socket: Socket | undefined;
   private decoder = new LineDecoder(MAX_SERVER_FRAME_BYTES);
   private readonly pending = new Map<string, Pending>();
@@ -82,6 +100,9 @@ export class DaemonClient {
   private reconnecting: Promise<void> | undefined;
   private focusedTrackId: string | null;
   private welcomed: (() => void) | undefined;
+  private view: ClientMessage | undefined;
+  private monitoring = false;
+  private click: LiveMessage | undefined;
 
   private constructor(private readonly options: DaemonClientOptions) {
     this.paths = sessionPaths(options.workspace, options.sessionId);
@@ -113,6 +134,8 @@ export class DaemonClient {
     kind: string;
     payload: unknown;
     key?: string;
+    /** Reuse to retry the same intent; a fresh one is drawn otherwise. */
+    seq?: number;
     operations?: unknown[];
     composition?: unknown;
   }): Promise<ApplyResult> {
@@ -125,6 +148,7 @@ export class DaemonClient {
       kind: intent.kind,
       payload: intent.payload,
     };
+    if (this.protocol >= 2) message.seq = intent.seq ?? this.nextSeq();
     if (intent.operations) message.operations = intent.operations;
     else message.composition = intent.composition;
     return this.result(await this.request(message));
@@ -209,6 +233,51 @@ export class DaemonClient {
     );
   }
 
+  /** True when dawgd runs live notes and the click (`live` capability). */
+  public get sharedLive(): boolean {
+    return this.caps.includes("live");
+  }
+
+  /** This pane's own presence entry, as dawgd last broadcast it. */
+  public get self(): PresenceEntry | undefined {
+    return this.presence.find((entry) => entry.clientId === this.clientId);
+  }
+
+  /** Reports this pane's view fields; resent after a reconnect. */
+  public setView(view: PaneView): void {
+    this.view = { v: 1, type: "view", ...view };
+    if (this.connected) this.socket!.write(encodeFrame(this.view));
+  }
+
+  /** Turns this pane's share of the shared live engine on or off. */
+  public async liveMonitor(on: boolean): Promise<LiveStatus> {
+    this.monitoring = on;
+    const reply = await this.request({
+      v: 1,
+      type: "live",
+      action: "monitor",
+      id: randomUUID(),
+      on,
+    });
+    if (reply.type !== "liveStatus")
+      throw new Error("dawgd did not answer live monitor");
+    const { v: _v, type: _type, id: _id, ...status } = reply;
+    return status;
+  }
+
+  /** Fire-and-forget live note or click; the click is resent on reconnect. */
+  public live(message: Exclude<LiveMessage, { action: "monitor" }>): void {
+    if (message.action === "click")
+      this.click = message.on || message.countIn ? message : undefined;
+    if (this.connected) this.socket!.write(encodeFrame(message));
+  }
+
+  /** The next per-(actor, client) intent number. */
+  public nextSeq(): number {
+    this.seq += 1;
+    return this.seq;
+  }
+
   public close(): void {
     this.closed = true;
     for (const [id, pending] of this.pending) {
@@ -334,7 +403,21 @@ export class DaemonClient {
             socket.destroy();
             this.onClose(socket);
           });
-          // Resend everything that was unanswered on the previous socket.
+          // Resend everything that was unanswered on the previous socket,
+          // after this pane's view and live state (a respawned dawgd knows
+          // neither).
+          if (this.view) socket.write(encodeFrame(this.view));
+          if (this.monitoring)
+            socket.write(
+              encodeFrame({
+                v: 1,
+                type: "live",
+                action: "monitor",
+                id: randomUUID(),
+                on: true,
+              }),
+            );
+          if (this.click) socket.write(encodeFrame(this.click));
           for (const pending of this.pending.values())
             socket.write(pending.frame);
           resolve();
@@ -348,6 +431,17 @@ export class DaemonClient {
             label: (this.options.label ?? "dawg").slice(0, 128),
             clientId: this.clientId,
             focusedTrackId: this.focusedTrackId,
+            ...(this.options.versions ?? {
+              vMin: PROTOCOL_MIN,
+              vMax: PROTOCOL_MAX,
+            }),
+            caps: ["actor", "seq", "quantum", "panes", "live"],
+            ...(this.options.actor
+              ? {
+                  actorId: this.options.actor.id,
+                  actorName: this.options.actor.name,
+                }
+              : {}),
           }),
         );
       });
@@ -368,7 +462,11 @@ export class DaemonClient {
       let message: ServerMessage;
       try {
         message = parseServerMessage(line);
-      } catch {
+      } catch (error) {
+        // A newer daemon's message types are skipped, not fatal; a malformed
+        // frame of a known type still drops the connection.
+        if (error instanceof ProtocolError && error.code === "unknown-type")
+          continue;
         socket.destroy();
         return;
       }
@@ -379,6 +477,8 @@ export class DaemonClient {
   private onMessage(message: ServerMessage): void {
     if (message.type === "welcome") {
       this.daemonPid = message.pid;
+      this.protocol = message.protocol ?? 1;
+      this.caps = message.caps ?? [];
       this.record = message.record;
       this.digest = message.digest;
       this.transport = message.transport;
@@ -443,7 +543,11 @@ export class DaemonClient {
       this.emit({
         type: "status",
         connected: this.connected,
-        message: `dawgd error · ${message.code}`,
+        // Audio notices (a lost output, a dying player) carry their words.
+        message:
+          message.code === "audio"
+            ? `audio · ${message.message}`
+            : `dawgd error · ${message.code}`,
       });
       return;
     }

package/src/session/clipboard.ts

@@ -0,0 +1,79 @@
+/**
+ * The per-pane range clipboard on disk (op1-ux §6.3): it lives in `.dawg`
+ * next to the session, one file per session and pane letter, so it survives
+ * a restart of that pane and is never in the score file.
+ */
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { RangeClipboard } from "../commands/range.ts";
+import { stateDir } from "./store.ts";
+
+const SAFE = /^[A-Za-z0-9-]{1,64}$/;
+
+/** `.dawg/clipboard/<session>-<pane>.json`; `solo` without a pane letter. */
+export function clipboardPath(
+  workspace: string,
+  sessionId: string,
+  pane: string | undefined,
+): string | undefined {
+  const who = pane ?? "solo";
+  if (!SAFE.test(sessionId) || !SAFE.test(who)) return undefined;
+  return join(stateDir(workspace), "clipboard", `${sessionId}-${who}.json`);
+}
+
+function isBarRange(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const range = value as Record<string, unknown>;
+  return (
+    Number.isInteger(range.startBar) &&
+    Number.isInteger(range.bars) &&
+    (range.startBar as number) >= 0 &&
+    (range.bars as number) >= 1
+  );
+}
+
+/** A clipboard read back from disk, or undefined when absent or malformed. */
+export function parseClipboard(text: string): RangeClipboard | undefined {
+  try {
+    const value = JSON.parse(text) as Record<string, unknown>;
+    const clip = value.clip as Record<string, unknown> | undefined;
+    if (
+      typeof value.source !== "string" ||
+      !isBarRange(value.range) ||
+      !clip ||
+      typeof clip.all !== "boolean" ||
+      !Number.isInteger(clip.bars) ||
+      !Array.isArray(clip.tracks) ||
+      !Array.isArray(clip.barTicks)
+    )
+      return undefined;
+    return value as unknown as RangeClipboard;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function loadClipboard(
+  path: string | undefined,
+): Promise<RangeClipboard | undefined> {
+  if (!path) return undefined;
+  try {
+    return parseClipboard(await readFile(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Writes (or, for undefined, removes) the pane's clipboard. */
+export async function saveClipboard(
+  path: string | undefined,
+  board: RangeClipboard | undefined,
+): Promise<void> {
+  if (!path) return;
+  if (!board) {
+    await rm(path, { force: true });
+    return;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(board)}\n`);
+}

package/src/session/daemon.ts

@@ -6,9 +6,17 @@ import {
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
+import { DiffError, diffScores } from "../../core/diff.ts";
 import { TransportClock, transportMapFor } from "../audio/clock.ts";
 import { AudioEngine } from "../audio/engine.ts";
+import {
+  SampleLibrary,
+  hasSamplerTracks,
+  type SampleBank,
+} from "../audio/samples.ts";
+import { PackStore } from "../audio/packs.ts";
 import { acquireSessionLock } from "./lock.ts";
+import { LiveHost } from "./live-host.ts";
 import {
   compositionAt,
   MAX_REBASE_DISTANCE,
@@ -22,8 +30,12 @@ import {
   encodeFrame,
   LineDecoder,
   MAX_CLIENT_FRAME_BYTES,
+  DAEMON_CAPS,
   monotonicEpochMs,
+  negotiateProtocol,
   parseClientMessage,
+  PROTOCOL_MAX,
+  PROTOCOL_MIN,
   ProtocolError,
   type ApplyResult,
   chooseTrack,
@@ -39,6 +51,7 @@ import {
   SessionConflictError,
   sessionPaths,
   updateSessionMeta,
+  type EventActor,
   type SessionPaths,
   type SessionRecord,
 } from "./store.ts";
@@ -56,8 +69,24 @@ type Client = {
   decoder: LineDecoder;
   ready: boolean;
   presence?: PresenceEntry;
+  /** Negotiated protocol revision (1 for clients that sent no range). */
+  protocol?: number;
 };
 
+/** The lowest free pane letter (A, B, C in join order, reused when freed). */
+export function freePaneLetter(taken: ReadonlySet<string>): string {
+  for (let code = 65; code <= 90; code += 1) {
+    const letter = String.fromCharCode(code);
+    if (!taken.has(letter)) return letter;
+  }
+  return "Z";
+}
+
+/** Retry-dedupe key for an intent: (actor, client, seq). */
+function seqKey(actorId: string | undefined, clientId: string, seq: number) {
+  return `${actorId ?? "-"}\u0000${clientId}\u0000${seq}`;
+}
+
 export type DaemonOptions = {
   workspace: string;
   sessionId: string;
@@ -75,8 +104,13 @@ export class DawgDaemon {
   private readonly graceMs: number;
   private readonly clients = new Set<Client>();
   private readonly keys = new Map<string, number>();
+  /** (actor, client, seq) to the revision it produced; see `seqKey`. */
+  private readonly seqs = new Map<string, number>();
   private readonly clock = new TransportClock();
   private readonly audio: AudioEngine;
+  private readonly live: LiveHost;
+  private samples: SampleBank | undefined;
+  private sampleLibrary: SampleLibrary | undefined;
   private record!: SessionRecord<Composition>;
   private score!: TrackScore;
   private digest = "";
@@ -111,6 +145,37 @@ export class DawgDaemon {
         });
       },
     });
+    this.workspace = options.workspace;
+    this.live = new LiveHost({
+      sink: this.audio,
+      score: () => this.score,
+      samples: () => this.samples,
+      transportBeatAt: (ms) =>
+        this.clock.playing ? this.clock.beatAt(ms) : undefined,
+      toMonotonic: (epochMs) => epochMs - performance.timeOrigin,
+      log: (line) => void this.log(line),
+    });
+  }
+
+  private readonly workspace: string;
+
+  /** Notes each client played through the shared engine (tests read it). */
+  public get livePlayed(): ReadonlyMap<string, number> {
+    return this.live.played;
+  }
+
+  /** Decodes sampler voices for live notes, once per score that needs them. */
+  private async loadSamples(): Promise<void> {
+    if (!hasSamplerTracks(this.score)) return;
+    this.sampleLibrary ??= new SampleLibrary({
+      projectRoot: this.workspace,
+      packs: new PackStore(),
+    });
+    try {
+      this.samples = await this.sampleLibrary.load(this.score);
+    } catch (error) {
+      await this.log(`live samples: ${String(error)}`);
+    }
   }
 
   /** Returns false when another live daemon already owns this session. */
@@ -229,7 +294,10 @@ export class DawgDaemon {
     const drop = () => {
       if (!this.clients.delete(client)) return;
       socket.destroy();
-      if (client.presence) this.broadcastPresence();
+      if (client.presence) {
+        void this.live.drop(client.presence.clientId);
+        this.broadcastPresence();
+      }
       if (this.clients.size === 0) this.armGrace();
     };
     socket.on("end", drop);
@@ -246,13 +314,31 @@ export class DawgDaemon {
 
   private handle(client: Client, message: ClientMessage): void {
     if (message.type === "hello") {
+      const protocol = negotiateProtocol(message.vMin, message.vMax);
+      if (protocol === undefined) {
+        this.fail(
+          client,
+          new ProtocolError(
+            "version",
+            `dawgd speaks protocol ${PROTOCOL_MIN}-${PROTOCOL_MAX}`,
+          ),
+        );
+        return;
+      }
       client.ready = true;
+      client.protocol = protocol;
+      const letters = new Set<string>();
+      for (const other of this.clients)
+        if (other !== client && other.presence?.pane)
+          letters.add(other.presence.pane);
       client.presence = {
         clientId: message.clientId,
         pid: message.pid,
         label: message.label,
         focusedTrackId: message.focusedTrackId,
+        pane: freePaneLetter(letters),
       };
+      if (message.actorId) client.presence.actorId = message.actorId;
       this.send(client, {
         v: 1,
         type: "welcome",
@@ -261,6 +347,8 @@ export class DawgDaemon {
         record: this.record,
         digest: this.digest,
         transport: this.transportState(),
+        protocol,
+        caps: [...DAEMON_CAPS],
       });
       this.broadcastPresence();
       return;
@@ -379,6 +467,39 @@ export class DawgDaemon {
       });
       return;
     }
+    if (message.type === "view") {
+      const presence = client.presence!;
+      const { v: _v, type: _type, ...view } = message;
+      for (const key of [
+        "screen",
+        "param",
+        "recording",
+        "playing",
+        "pinned",
+        "follow",
+      ] as const)
+        delete presence[key];
+      Object.assign(presence, view);
+      this.broadcastPresence();
+      return;
+    }
+    if (message.type === "live") {
+      const clientId = client.presence!.clientId;
+      if (message.action === "monitor")
+        void (async () => {
+          if (message.on) await this.loadSamples();
+          const status = await this.live.handle(clientId, message);
+          if (status)
+            this.send(client, {
+              v: 1,
+              type: "liveStatus",
+              id: message.id,
+              ...status,
+            });
+        })();
+      else void this.live.handle(clientId, message);
+      return;
+    }
     if (message.type === "transport") {
       this.enqueue(async () => {
         this.transport(message.action, message.beat, message.bpm);
@@ -393,7 +514,7 @@ export class DawgDaemon {
       return;
     }
     this.enqueue(async () => {
-      const result = await this.apply(message);
+      const result = await this.apply(message, client);
       this.send(client, { v: 1, type: "result", id: message.id, ...result });
     });
   }
@@ -407,15 +528,35 @@ export class DawgDaemon {
 
   private async apply(
     message: Extract<ClientMessage, { type: "apply" }>,
+    client?: Client,
   ): Promise<ApplyResult> {
     const seen = this.keys.get(message.key);
     if (seen !== undefined) return { status: "duplicate", revision: seen };
+    // The authority stamps who made the event from the connection, never
+    // from the intent body.
+    const actor: EventActor | undefined = client?.presence
+      ? {
+          clientId: client.presence.clientId,
+          ...(client.presence.actorId
+            ? { actorId: client.presence.actorId }
+            : {}),
+          ...(message.seq !== undefined ? { seq: message.seq } : {}),
+        }
+      : undefined;
+    const retryKey =
+      actor?.seq !== undefined
+        ? seqKey(actor.actorId, actor.clientId, actor.seq)
+        : undefined;
+    const retried = retryKey ? this.seqs.get(retryKey) : undefined;
+    if (retried !== undefined)
+      return { status: "duplicate", revision: retried };
+    let operations: ScoreOperation[] | undefined;
     const stale = message.base !== this.record.revision;
     let rebased = false;
     let next: TrackScore;
     try {
       if (message.operations) {
-        const operations = message.operations.map(parseOperation);
+        operations = message.operations.map(parseOperation);
         if (stale) {
           // Operation intents from an older base replay on the current score
           // when nothing they touch changed in between.
@@ -435,6 +576,13 @@ export class DawgDaemon {
       else next = scoreFromJSON(message.composition);
       // Round-trip through the parser so only canonical score data is stored.
       next = scoreFromJSON(next.toJSON());
+      // Composition intents still log as ops, so the log replays as ops.
+      operations ??= derivedOperations(
+        this.score,
+        next,
+        MAX_DERIVED_OPS_BYTES -
+          Buffer.byteLength(JSON.stringify(message.payload ?? null), "utf8"),
+      );
     } catch (error) {
       return {
         status: "rejected",
@@ -459,7 +607,13 @@ export class DawgDaemon {
       this.record = await appendSessionEvent(
         this.paths,
         this.record,
-        { kind: message.kind, payload, id: message.key },
+        {
+          kind: message.kind,
+          payload,
+          id: message.key,
+          ...(actor ? { actor } : {}),
+          ...(operations ? { ops: operations } : {}),
+        },
         next.toJSON(),
       );
     } catch (error) {
@@ -488,6 +642,7 @@ export class DawgDaemon {
     this.score = next;
     this.digest = compositionDigest(this.record.composition);
     this.keys.set(message.key, this.record.revision);
+    if (retryKey) this.seqs.set(retryKey, this.record.revision);
     this.diskMtime = await this.recordMtime();
     const event = this.record.events[this.record.events.length - 1]!;
     this.broadcast({
@@ -578,6 +733,7 @@ export class DawgDaemon {
       beat: this.clock.beatAt(),
       bpm: this.score.tempoBpm,
       atMs,
+      quantum: this.score.beatsPerBar,
     };
   }
 
@@ -621,8 +777,15 @@ export class DawgDaemon {
     this.score = scoreFromJSON(this.record.composition);
     this.digest = compositionDigest(this.record.composition);
     this.keys.clear();
-    for (const event of this.record.events)
+    this.seqs.clear();
+    for (const event of this.record.events) {
       this.keys.set(event.id, event.revision);
+      if (event.actor?.seq !== undefined)
+        this.seqs.set(
+          seqKey(event.actor.actorId, event.actor.clientId, event.actor.seq),
+          event.revision,
+        );
+    }
     this.diskMtime = await this.recordMtime();
   }
 
@@ -704,10 +867,41 @@ const OPERATION_TYPES = new Set([
   "setTime",
   "setTuning",
   "setMaster",
+  "setCalibration",
+  "setStyle",
   "setSections",
+  "setLoop",
+  "setClips",
 ]);
 
 /** Shape gate before the reducer, which validates every field it reads. */
+/**
+ * Serialized budget for payload plus derived ops; the store bounds the two
+ * together at 64 KiB per event.
+ */
+const MAX_DERIVED_OPS_BYTES = 60 * 1024;
+
+/**
+ * The operations turning `before` into `after`, or undefined (a snapshot
+ * event) when the change has no op form or is too large to log as ops.
+ */
+export function derivedOperations(
+  before: TrackScore,
+  after: TrackScore,
+  budgetBytes = MAX_DERIVED_OPS_BYTES,
+): ScoreOperation[] | undefined {
+  let ops: readonly ScoreOperation[];
+  try {
+    ops = diffScores(before, after);
+  } catch (error) {
+    if (error instanceof DiffError) return undefined;
+    throw error;
+  }
+  if (Buffer.byteLength(JSON.stringify(ops), "utf8") > budgetBytes)
+    return undefined;
+  return [...ops];
+}
+
 function parseOperation(value: unknown): ScoreOperation {
   if (
     typeof value !== "object" ||