musicxml-io 0.1.0 → 0.2.0

package/dist/operations/index.mjs

@@ -41,10 +41,1353 @@ function getMeasureEndPosition(measure) {
   return state.position;
 }
 
+// src/validator/index.ts
+var DEFAULT_OPTIONS = {
+  checkDivisions: true,
+  checkMeasureDuration: true,
+  checkMeasureFullness: false,
+  // Piano Roll semantics - opt-in
+  checkPosition: true,
+  checkTies: true,
+  checkBeams: true,
+  checkSlurs: true,
+  checkTuplets: true,
+  checkPartReferences: true,
+  checkPartStructure: true,
+  checkVoiceStaff: true,
+  checkStaffStructure: true,
+  durationTolerance: 0
+};
+function validate(score, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const allErrors = [];
+  if (opts.checkPartReferences) {
+    allErrors.push(...validatePartReferences(score));
+  }
+  if (opts.checkPartStructure) {
+    allErrors.push(...validatePartStructure(score));
+  }
+  if (opts.checkDivisions) {
+    allErrors.push(...validateDivisions(score));
+  }
+  for (let partIndex = 0; partIndex < score.parts.length; partIndex++) {
+    const part = score.parts[partIndex];
+    let currentDivisions = 1;
+    let currentTime;
+    let currentStaves = 1;
+    for (let measureIndex = 0; measureIndex < part.measures.length; measureIndex++) {
+      const measure = part.measures[measureIndex];
+      const location = {
+        partIndex,
+        partId: part.id,
+        measureIndex,
+        measureNumber: measure.number
+      };
+      if (measure.attributes) {
+        if (measure.attributes.divisions !== void 0) {
+          currentDivisions = measure.attributes.divisions;
+        }
+        if (measure.attributes.time !== void 0) {
+          currentTime = measure.attributes.time;
+        }
+        if (measure.attributes.staves !== void 0) {
+          currentStaves = measure.attributes.staves;
+        }
+      }
+      if (opts.checkMeasureDuration && currentTime) {
+        allErrors.push(...validateMeasureDuration(
+          measure,
+          currentDivisions,
+          currentTime,
+          location,
+          opts.durationTolerance
+        ));
+      }
+      if (opts.checkMeasureFullness && currentTime) {
+        allErrors.push(...validateMeasureFullness(
+          measure,
+          currentDivisions,
+          currentTime,
+          location
+        ));
+      }
+      if (opts.checkPosition) {
+        allErrors.push(...validateBackupForward(measure, location));
+      }
+      if (opts.checkTies) {
+        allErrors.push(...validateTies(measure, location));
+      }
+      if (opts.checkBeams) {
+        allErrors.push(...validateBeams(measure, location));
+      }
+      if (opts.checkSlurs) {
+        allErrors.push(...validateSlurs(measure, location));
+      }
+      if (opts.checkTuplets) {
+        allErrors.push(...validateTuplets(measure, location));
+      }
+      if (opts.checkVoiceStaff) {
+        allErrors.push(...validateVoiceStaff(measure, currentStaves, location));
+      }
+    }
+    if (opts.checkStaffStructure) {
+      allErrors.push(...validateStaffStructure(part, partIndex));
+    }
+  }
+  const errors = allErrors.filter((e) => e.level === "error");
+  const warnings = allErrors.filter((e) => e.level === "warning");
+  const infos = allErrors.filter((e) => e.level === "info");
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    infos
+  };
+}
+function validateDivisions(score) {
+  const errors = [];
+  for (let partIndex = 0; partIndex < score.parts.length; partIndex++) {
+    const part = score.parts[partIndex];
+    let hasDivisions = false;
+    for (let measureIndex = 0; measureIndex < part.measures.length; measureIndex++) {
+      const measure = part.measures[measureIndex];
+      if (measure.attributes?.divisions !== void 0) {
+        hasDivisions = true;
+        if (measure.attributes.divisions <= 0) {
+          errors.push({
+            code: "INVALID_DIVISIONS",
+            level: "error",
+            message: `Invalid divisions value: ${measure.attributes.divisions}. Must be positive.`,
+            location: {
+              partIndex,
+              partId: part.id,
+              measureIndex,
+              measureNumber: measure.number
+            },
+            details: { divisions: measure.attributes.divisions }
+          });
+        }
+      }
+      if (!hasDivisions) {
+        const hasNotes = measure.entries.some((e) => e.type === "note");
+        if (hasNotes) {
+          errors.push({
+            code: "MISSING_DIVISIONS",
+            level: "error",
+            message: "Notes found before divisions are defined",
+            location: {
+              partIndex,
+              partId: part.id,
+              measureIndex,
+              measureNumber: measure.number
+            }
+          });
+          hasDivisions = true;
+        }
+      }
+    }
+  }
+  return errors;
+}
+function validateMeasureDuration(measure, divisions, time, location, tolerance = 0) {
+  const errors = [];
+  if (time.senzaMisura) {
+    return errors;
+  }
+  const beats = parseInt(time.beats, 10);
+  if (isNaN(beats)) {
+    return errors;
+  }
+  const expectedDuration = beats / time.beatType * 4 * divisions;
+  const voiceDurations = calculateVoiceDurations(measure);
+  for (const [voiceKey, actualDuration] of voiceDurations.entries()) {
+    const [staff, voice] = voiceKey.split("-").map(Number);
+    const diff = actualDuration - expectedDuration;
+    if (Math.abs(diff) > tolerance) {
+      if (diff > 0) {
+        errors.push({
+          code: "MEASURE_DURATION_OVERFLOW",
+          level: "error",
+          message: `Voice ${voice} (staff ${staff}) duration ${actualDuration} exceeds expected ${expectedDuration}`,
+          location: { ...location, voice, staff },
+          details: {
+            expected: expectedDuration,
+            actual: actualDuration,
+            difference: diff
+          }
+        });
+      } else {
+        errors.push({
+          code: "MEASURE_DURATION_UNDERFLOW",
+          level: "warning",
+          message: `Voice ${voice} (staff ${staff}) duration ${actualDuration} is less than expected ${expectedDuration}`,
+          location: { ...location, voice, staff },
+          details: {
+            expected: expectedDuration,
+            actual: actualDuration,
+            difference: diff
+          }
+        });
+      }
+    }
+  }
+  return errors;
+}
+function calculateVoiceDurations(measure) {
+  const voiceDurations = /* @__PURE__ */ new Map();
+  let currentPosition = 0;
+  const voiceMaxPositions = /* @__PURE__ */ new Map();
+  for (const entry of measure.entries) {
+    if (entry.type === "note") {
+      const staff = entry.staff ?? 1;
+      const voice = entry.voice;
+      const key = `${staff}-${voice}`;
+      if (!entry.chord) {
+        const endPosition = currentPosition + entry.duration;
+        const currentMax = voiceMaxPositions.get(key) ?? 0;
+        voiceMaxPositions.set(key, Math.max(currentMax, endPosition));
+        currentPosition = endPosition;
+      }
+    } else if (entry.type === "backup") {
+      currentPosition -= entry.duration;
+    } else if (entry.type === "forward") {
+      currentPosition += entry.duration;
+    }
+  }
+  for (const [key, maxPos] of voiceMaxPositions.entries()) {
+    voiceDurations.set(key, maxPos);
+  }
+  return voiceDurations;
+}
+function validateMeasureFullness(measure, divisions, time, location) {
+  const errors = [];
+  if (time.senzaMisura) {
+    return errors;
+  }
+  const beats = parseInt(time.beats, 10);
+  if (isNaN(beats)) {
+    return errors;
+  }
+  const expectedDuration = beats / time.beatType * 4 * divisions;
+  const voiceCoverage = /* @__PURE__ */ new Map();
+  let currentPosition = 0;
+  for (const entry of measure.entries) {
+    if (entry.type === "note") {
+      const staff = entry.staff ?? 1;
+      const voice = entry.voice;
+      const key = `${staff}-${voice}`;
+      if (!entry.chord) {
+        if (!voiceCoverage.has(key)) {
+          voiceCoverage.set(key, { segments: [] });
+        }
+        voiceCoverage.get(key).segments.push({
+          start: currentPosition,
+          end: currentPosition + entry.duration
+        });
+        currentPosition += entry.duration;
+      }
+    } else if (entry.type === "backup") {
+      currentPosition -= entry.duration;
+    } else if (entry.type === "forward") {
+      const staff = entry.staff ?? 1;
+      const voice = entry.voice ?? 1;
+      const key = `${staff}-${voice}`;
+      if (!voiceCoverage.has(key)) {
+        voiceCoverage.set(key, { segments: [] });
+      }
+      voiceCoverage.get(key).segments.push({
+        start: currentPosition,
+        end: currentPosition + entry.duration
+      });
+      currentPosition += entry.duration;
+    }
+  }
+  for (const [voiceKey, { segments }] of voiceCoverage.entries()) {
+    const [staff, voice] = voiceKey.split("-").map(Number);
+    const sorted = [...segments].sort((a, b) => a.start - b.start);
+    let lastEnd = 0;
+    const gaps = [];
+    for (const seg of sorted) {
+      if (seg.start > lastEnd) {
+        gaps.push({ start: lastEnd, end: seg.start });
+      }
+      lastEnd = Math.max(lastEnd, seg.end);
+    }
+    if (lastEnd < expectedDuration) {
+      gaps.push({ start: lastEnd, end: expectedDuration });
+    }
+    for (const gap of gaps) {
+      errors.push({
+        code: "VOICE_GAP",
+        level: "warning",
+        message: `Voice ${voice} (staff ${staff}) has gap from position ${gap.start} to ${gap.end}`,
+        location: { ...location, voice, staff },
+        details: {
+          gapStart: gap.start,
+          gapEnd: gap.end,
+          gapDuration: gap.end - gap.start
+        }
+      });
+    }
+    if (lastEnd < expectedDuration) {
+      errors.push({
+        code: "VOICE_INCOMPLETE",
+        level: "warning",
+        message: `Voice ${voice} (staff ${staff}) ends at ${lastEnd}, expected ${expectedDuration}`,
+        location: { ...location, voice, staff },
+        details: {
+          actualEnd: lastEnd,
+          expectedDuration,
+          missing: expectedDuration - lastEnd
+        }
+      });
+    }
+  }
+  return errors;
+}
+function validateBackupForward(measure, location) {
+  const errors = [];
+  let position = 0;
+  let minPosition = 0;
+  for (let entryIndex = 0; entryIndex < measure.entries.length; entryIndex++) {
+    const entry = measure.entries[entryIndex];
+    if (entry.type === "note") {
+      if (!entry.chord) {
+        position += entry.duration;
+      }
+    } else if (entry.type === "backup") {
+      const newPosition = position - entry.duration;
+      if (newPosition < 0) {
+        errors.push({
+          code: "BACKUP_EXCEEDS_POSITION",
+          level: "error",
+          message: `Backup of ${entry.duration} at position ${position} results in negative position ${newPosition}`,
+          location: { ...location, entryIndex },
+          details: {
+            backupDuration: entry.duration,
+            positionBefore: position,
+            positionAfter: newPosition
+          }
+        });
+      }
+      position = newPosition;
+      minPosition = Math.min(minPosition, position);
+    } else if (entry.type === "forward") {
+      position += entry.duration;
+    }
+  }
+  if (minPosition < 0) {
+    errors.push({
+      code: "NEGATIVE_POSITION",
+      level: "error",
+      message: `Position went negative (min: ${minPosition}) in measure`,
+      location,
+      details: { minPosition }
+    });
+  }
+  return errors;
+}
+function validateTies(measure, location) {
+  const errors = [];
+  const openTies = /* @__PURE__ */ new Map();
+  for (let entryIndex = 0; entryIndex < measure.entries.length; entryIndex++) {
+    const entry = measure.entries[entryIndex];
+    if (entry.type !== "note" || !entry.pitch) continue;
+    const pitchKey = `${entry.pitch.step}${entry.pitch.octave}${entry.pitch.alter ?? 0}-${entry.voice}-${entry.staff ?? 1}`;
+    const ties = entry.ties ?? (entry.tie ? [entry.tie] : []);
+    for (const tie of ties) {
+      if (tie.type === "start") {
+        if (openTies.has(pitchKey)) {
+        }
+        openTies.set(pitchKey, { entryIndex, pitch: entry.pitch });
+      } else if (tie.type === "stop") {
+        if (!openTies.has(pitchKey)) {
+          errors.push({
+            code: "TIE_STOP_WITHOUT_START",
+            level: "warning",
+            message: `Tie stop without matching start for ${entry.pitch.step}${entry.pitch.octave}`,
+            location: { ...location, entryIndex, voice: entry.voice, staff: entry.staff ?? 1 },
+            details: { pitch: entry.pitch }
+          });
+        } else {
+          openTies.delete(pitchKey);
+        }
+      }
+    }
+  }
+  return errors;
+}
+function validateBeams(measure, location) {
+  const errors = [];
+  const openBeams = /* @__PURE__ */ new Map();
+  for (let entryIndex = 0; entryIndex < measure.entries.length; entryIndex++) {
+    const entry = measure.entries[entryIndex];
+    if (entry.type !== "note" || !entry.beam) continue;
+    for (const beam of entry.beam) {
+      const beamKey = `${beam.number}-${entry.voice}-${entry.staff ?? 1}`;
+      if (beam.type === "begin") {
+        if (openBeams.has(beamKey)) {
+          errors.push({
+            code: "BEAM_BEGIN_WITHOUT_END",
+            level: "error",
+            message: `Beam ${beam.number} started again before previous beam ended`,
+            location: { ...location, entryIndex, voice: entry.voice, staff: entry.staff ?? 1 },
+            details: { beamNumber: beam.number }
+          });
+        }
+        openBeams.set(beamKey, entryIndex);
+      } else if (beam.type === "end") {
+        if (!openBeams.has(beamKey)) {
+          errors.push({
+            code: "BEAM_END_WITHOUT_BEGIN",
+            level: "error",
+            message: `Beam ${beam.number} end without matching begin`,
+            location: { ...location, entryIndex, voice: entry.voice, staff: entry.staff ?? 1 },
+            details: { beamNumber: beam.number }
+          });
+        } else {
+          openBeams.delete(beamKey);
+        }
+      }
+    }
+  }
+  for (const [beamKey, startIndex] of openBeams.entries()) {
+    const [beamNumber, voice, staff] = beamKey.split("-").map(Number);
+    errors.push({
+      code: "BEAM_BEGIN_WITHOUT_END",
+      level: "error",
+      message: `Beam ${beamNumber} started but never ended in measure`,
+      location: { ...location, entryIndex: startIndex, voice, staff },
+      details: { beamNumber }
+    });
+  }
+  return errors;
+}
+function validateSlurs(measure, _location) {
+  const errors = [];
+  const openSlurs = /* @__PURE__ */ new Map();
+  for (let entryIndex = 0; entryIndex < measure.entries.length; entryIndex++) {
+    const entry = measure.entries[entryIndex];
+    if (entry.type !== "note" || !entry.notations) continue;
+    for (const notation of entry.notations) {
+      if (notation.type !== "slur") continue;
+      const slurNumber = notation.number ?? 1;
+      const slurKey = `${slurNumber}-${entry.voice}-${entry.staff ?? 1}`;
+      if (notation.slurType === "start") {
+        if (openSlurs.has(slurKey)) {
+        }
+        openSlurs.set(slurKey, entryIndex);
+      } else if (notation.slurType === "stop") {
+        if (!openSlurs.has(slurKey)) {
+        } else {
+          openSlurs.delete(slurKey);
+        }
+      }
+    }
+  }
+  return errors;
+}
+function validateTuplets(measure, location) {
+  const errors = [];
+  const openTuplets = /* @__PURE__ */ new Map();
+  for (let entryIndex = 0; entryIndex < measure.entries.length; entryIndex++) {
+    const entry = measure.entries[entryIndex];
+    if (entry.type !== "note" || !entry.notations) continue;
+    for (const notation of entry.notations) {
+      if (notation.type !== "tuplet") continue;
+      const tupletNumber = notation.number ?? 1;
+      const tupletKey = `${tupletNumber}-${entry.voice}-${entry.staff ?? 1}`;
+      if (notation.tupletType === "start") {
+        if (openTuplets.has(tupletKey)) {
+          errors.push({
+            code: "TUPLET_START_WITHOUT_STOP",
+            level: "error",
+            message: `Tuplet ${tupletNumber} started again before previous tuplet ended`,
+            location: { ...location, entryIndex, voice: entry.voice, staff: entry.staff ?? 1 },
+            details: { tupletNumber }
+          });
+        }
+        openTuplets.set(tupletKey, entryIndex);
+      } else if (notation.tupletType === "stop") {
+        if (!openTuplets.has(tupletKey)) {
+          errors.push({
+            code: "TUPLET_STOP_WITHOUT_START",
+            level: "error",
+            message: `Tuplet ${tupletNumber} stop without matching start`,
+            location: { ...location, entryIndex, voice: entry.voice, staff: entry.staff ?? 1 },
+            details: { tupletNumber }
+          });
+        } else {
+          openTuplets.delete(tupletKey);
+        }
+      }
+    }
+  }
+  for (const [tupletKey, startIndex] of openTuplets.entries()) {
+    const [tupletNumber, voice, staff] = tupletKey.split("-").map(Number);
+    errors.push({
+      code: "TUPLET_START_WITHOUT_STOP",
+      level: "error",
+      message: `Tuplet ${tupletNumber} started but never ended in measure`,
+      location: { ...location, entryIndex: startIndex, voice, staff },
+      details: { tupletNumber }
+    });
+  }
+  return errors;
+}
+function validatePartReferences(score) {
+  const errors = [];
+  const partListIds = /* @__PURE__ */ new Set();
+  for (const entry of score.partList) {
+    if (entry.type === "score-part") {
+      partListIds.add(entry.id);
+    }
+  }
+  const partIds = /* @__PURE__ */ new Set();
+  for (const part of score.parts) {
+    partIds.add(part.id);
+  }
+  for (let partIndex = 0; partIndex < score.parts.length; partIndex++) {
+    const part = score.parts[partIndex];
+    if (!partListIds.has(part.id)) {
+      errors.push({
+        code: "PART_ID_NOT_IN_PART_LIST",
+        level: "error",
+        message: `Part "${part.id}" is not defined in partList`,
+        location: { partIndex, partId: part.id }
+      });
+    }
+  }
+  for (const entry of score.partList) {
+    if (entry.type === "score-part" && !partIds.has(entry.id)) {
+      errors.push({
+        code: "PART_LIST_ID_NOT_IN_PARTS",
+        level: "error",
+        message: `PartList entry "${entry.id}" has no corresponding part`,
+        location: { partId: entry.id }
+      });
+    }
+  }
+  return errors;
+}
+function validateVoiceStaff(measure, staves, location) {
+  const errors = [];
+  for (let entryIndex = 0; entryIndex < measure.entries.length; entryIndex++) {
+    const entry = measure.entries[entryIndex];
+    if (entry.type !== "note") continue;
+    if (entry.voice <= 0) {
+      errors.push({
+        code: "INVALID_VOICE_NUMBER",
+        level: "error",
+        message: `Invalid voice number: ${entry.voice}. Must be positive.`,
+        location: { ...location, entryIndex, voice: entry.voice }
+      });
+    }
+    const staff = entry.staff ?? 1;
+    if (staff <= 0) {
+      errors.push({
+        code: "INVALID_STAFF_NUMBER",
+        level: "error",
+        message: `Invalid staff number: ${staff}. Must be positive.`,
+        location: { ...location, entryIndex, staff }
+      });
+    } else if (staff > staves) {
+      errors.push({
+        code: "STAFF_EXCEEDS_STAVES",
+        level: "error",
+        message: `Staff number ${staff} exceeds declared staves count ${staves}`,
+        location: { ...location, entryIndex, staff },
+        details: { declaredStaves: staves }
+      });
+    }
+    if (entry.duration < 0) {
+      errors.push({
+        code: "INVALID_DURATION",
+        level: "error",
+        message: `Invalid duration: ${entry.duration}. Must be non-negative.`,
+        location: { ...location, entryIndex },
+        details: { duration: entry.duration }
+      });
+    }
+  }
+  return errors;
+}
+function validatePartStructure(score) {
+  const errors = [];
+  if (score.parts.length === 0) {
+    return errors;
+  }
+  const partIds = /* @__PURE__ */ new Map();
+  for (let partIndex = 0; partIndex < score.parts.length; partIndex++) {
+    const part = score.parts[partIndex];
+    if (partIds.has(part.id)) {
+      errors.push({
+        code: "DUPLICATE_PART_ID",
+        level: "error",
+        message: `Duplicate part ID "${part.id}" found at index ${partIndex} (first at index ${partIds.get(part.id)})`,
+        location: { partIndex, partId: part.id },
+        details: { firstIndex: partIds.get(part.id) }
+      });
+    } else {
+      partIds.set(part.id, partIndex);
+    }
+  }
+  const referencePart = score.parts[0];
+  const referenceMeasureCount = referencePart.measures.length;
+  for (let partIndex = 1; partIndex < score.parts.length; partIndex++) {
+    const part = score.parts[partIndex];
+    if (part.measures.length !== referenceMeasureCount) {
+      errors.push({
+        code: "PART_MEASURE_COUNT_MISMATCH",
+        level: "error",
+        message: `Part "${part.id}" has ${part.measures.length} measures, expected ${referenceMeasureCount} (same as first part)`,
+        location: { partIndex, partId: part.id },
+        details: {
+          expected: referenceMeasureCount,
+          actual: part.measures.length
+        }
+      });
+    }
+    const minLength = Math.min(part.measures.length, referenceMeasureCount);
+    for (let measureIndex = 0; measureIndex < minLength; measureIndex++) {
+      const refMeasure = referencePart.measures[measureIndex];
+      const partMeasure = part.measures[measureIndex];
+      if (refMeasure.number !== partMeasure.number) {
+        errors.push({
+          code: "PART_MEASURE_NUMBER_MISMATCH",
+          level: "warning",
+          message: `Part "${part.id}" measure at index ${measureIndex} has number "${partMeasure.number}", expected "${refMeasure.number}"`,
+          location: {
+            partIndex,
+            partId: part.id,
+            measureIndex,
+            measureNumber: partMeasure.number
+          },
+          details: {
+            expected: refMeasure.number,
+            actual: partMeasure.number
+          }
+        });
+      }
+    }
+  }
+  const openGroups = /* @__PURE__ */ new Map();
+  for (let i = 0; i < score.partList.length; i++) {
+    const entry = score.partList[i];
+    if (entry.type !== "part-group") continue;
+    const groupNumber = entry.number ?? 1;
+    if (entry.groupType === "start") {
+      if (openGroups.has(groupNumber)) {
+        errors.push({
+          code: "PART_GROUP_START_WITHOUT_STOP",
+          level: "error",
+          message: `Part group ${groupNumber} started again at index ${i} before previous group ended`,
+          location: {},
+          details: { groupNumber, partListIndex: i }
+        });
+      }
+      openGroups.set(groupNumber, i);
+    } else if (entry.groupType === "stop") {
+      if (!openGroups.has(groupNumber)) {
+        errors.push({
+          code: "PART_GROUP_STOP_WITHOUT_START",
+          level: "error",
+          message: `Part group ${groupNumber} stop at index ${i} without matching start`,
+          location: {},
+          details: { groupNumber, partListIndex: i }
+        });
+      } else {
+        openGroups.delete(groupNumber);
+      }
+    }
+  }
+  for (const [groupNumber, startIndex] of openGroups.entries()) {
+    errors.push({
+      code: "PART_GROUP_START_WITHOUT_STOP",
+      level: "error",
+      message: `Part group ${groupNumber} started at index ${startIndex} but never stopped`,
+      location: {},
+      details: { groupNumber, partListIndex: startIndex }
+    });
+  }
+  return errors;
+}
+function validateStaffStructure(part, partIndex) {
+  const errors = [];
+  let currentStaves = void 0;
+  let stavesDeclarationMeasure = void 0;
+  const clefsDeclaredForStaves = /* @__PURE__ */ new Set();
+  for (let measureIndex = 0; measureIndex < part.measures.length; measureIndex++) {
+    const measure = part.measures[measureIndex];
+    const location = {
+      partIndex,
+      partId: part.id,
+      measureIndex,
+      measureNumber: measure.number
+    };
+    if (measure.attributes?.staves !== void 0) {
+      const newStaves = measure.attributes.staves;
+      if (currentStaves !== void 0 && newStaves !== currentStaves) {
+        errors.push({
+          code: "STAVES_DECLARATION_MISMATCH",
+          level: "info",
+          message: `Staves count changed from ${currentStaves} to ${newStaves}`,
+          location,
+          details: {
+            previous: currentStaves,
+            new: newStaves,
+            previousMeasure: stavesDeclarationMeasure
+          }
+        });
+        clefsDeclaredForStaves.clear();
+      }
+      currentStaves = newStaves;
+      stavesDeclarationMeasure = measure.number;
+    }
+    if (measure.attributes?.clef) {
+      for (const clef of measure.attributes.clef) {
+        const staffNum = clef.staff ?? 1;
+        clefsDeclaredForStaves.add(staffNum);
+        if (currentStaves !== void 0 && staffNum > currentStaves) {
+          errors.push({
+            code: "CLEF_STAFF_EXCEEDS_STAVES",
+            level: "error",
+            message: `Clef declared for staff ${staffNum}, but only ${currentStaves} staves declared`,
+            location,
+            details: {
+              clefStaff: staffNum,
+              declaredStaves: currentStaves
+            }
+          });
+        }
+      }
+    }
+    if (currentStaves !== void 0) {
+      const usedStaves = /* @__PURE__ */ new Set();
+      for (const entry of measure.entries) {
+        if (entry.type === "note") {
+          usedStaves.add(entry.staff ?? 1);
+        } else if (entry.type === "forward" && entry.staff) {
+          usedStaves.add(entry.staff);
+        }
+      }
+      for (const usedStaff of usedStaves) {
+        if (usedStaff > currentStaves) {
+        }
+      }
+    }
+  }
+  if (currentStaves !== void 0 && currentStaves > 1) {
+    for (let staff = 1; staff <= currentStaves; staff++) {
+      if (!clefsDeclaredForStaves.has(staff)) {
+        errors.push({
+          code: "MISSING_CLEF_FOR_STAFF",
+          level: "warning",
+          message: `No clef declared for staff ${staff} in part "${part.id}"`,
+          location: { partIndex, partId: part.id },
+          details: { staff, totalStaves: currentStaves }
+        });
+      }
+    }
+  }
+  const allUsedStaves = /* @__PURE__ */ new Set();
+  for (const measure of part.measures) {
+    for (const entry of measure.entries) {
+      if (entry.type === "note" && entry.staff !== void 0) {
+        allUsedStaves.add(entry.staff);
+      }
+    }
+  }
+  if (allUsedStaves.size > 1 && currentStaves === void 0) {
+    errors.push({
+      code: "MISSING_STAVES_DECLARATION",
+      level: "warning",
+      message: `Part "${part.id}" uses staff numbers ${Array.from(allUsedStaves).sort().join(", ")} but has no staves declaration`,
+      location: { partIndex, partId: part.id },
+      details: { usedStaves: Array.from(allUsedStaves).sort() }
+    });
+  }
+  return errors;
+}
+var DEFAULT_LOCAL_OPTIONS = {
+  checkMeasureDuration: true,
+  checkMeasureFullness: false,
+  // Piano Roll semantics - opt-in
+  checkPosition: true,
+  checkBeams: true,
+  checkTuplets: true,
+  checkVoiceStaff: true,
+  durationTolerance: 0
+};
+function validateMeasureLocal(measure, context, options = {}) {
+  const opts = { ...DEFAULT_LOCAL_OPTIONS, ...options };
+  const errors = [];
+  const location = {
+    partIndex: context.partIndex,
+    partId: context.partId,
+    measureIndex: context.measureIndex,
+    measureNumber: measure.number
+  };
+  if (opts.checkMeasureDuration && context.time) {
+    errors.push(...validateMeasureDuration(
+      measure,
+      context.divisions,
+      context.time,
+      location,
+      opts.durationTolerance
+    ));
+  }
+  if (opts.checkMeasureFullness && context.time) {
+    errors.push(...validateMeasureFullness(
+      measure,
+      context.divisions,
+      context.time,
+      location
+    ));
+  }
+  if (opts.checkPosition) {
+    errors.push(...validateBackupForward(measure, location));
+  }
+  if (opts.checkBeams) {
+    errors.push(...validateBeams(measure, location));
+  }
+  if (opts.checkTuplets) {
+    errors.push(...validateTuplets(measure, location));
+  }
+  if (opts.checkVoiceStaff) {
+    errors.push(...validateVoiceStaff(measure, context.staves, location));
+  }
+  return errors;
+}
+function getMeasureContext(score, partIndex, measureIndex) {
+  const part = score.parts[partIndex];
+  if (!part) {
+    throw new Error(`Part index ${partIndex} out of bounds`);
+  }
+  let divisions = 1;
+  let time;
+  let staves = 1;
+  for (let i = 0; i <= measureIndex && i < part.measures.length; i++) {
+    const measure = part.measures[i];
+    if (measure.attributes) {
+      if (measure.attributes.divisions !== void 0) {
+        divisions = measure.attributes.divisions;
+      }
+      if (measure.attributes.time !== void 0) {
+        time = measure.attributes.time;
+      }
+      if (measure.attributes.staves !== void 0) {
+        staves = measure.attributes.staves;
+      }
+    }
+    for (const entry of measure.entries) {
+      if (entry.type === "attributes") {
+        if (entry.attributes.divisions !== void 0) {
+          divisions = entry.attributes.divisions;
+        }
+        if (entry.attributes.time !== void 0) {
+          time = entry.attributes.time;
+        }
+        if (entry.attributes.staves !== void 0) {
+          staves = entry.attributes.staves;
+        }
+      }
+    }
+  }
+  return {
+    divisions,
+    time,
+    staves,
+    partIndex,
+    partId: part.id,
+    measureIndex
+  };
+}
+
 // src/operations/index.ts
+function success(data, warnings) {
+  return { success: true, data, warnings };
+}
+function failure(errors) {
+  return { success: false, errors };
+}
+function operationError(code, message, location = {}, details) {
+  return {
+    code,
+    level: "error",
+    message,
+    location,
+    details
+  };
+}
 function cloneScore(score) {
   return JSON.parse(JSON.stringify(score));
 }
+function getMeasureDuration(divisions, time) {
+  const beats = parseInt(time.beats, 10);
+  if (isNaN(beats)) return divisions * 4;
+  return beats / time.beatType * 4 * divisions;
+}
+function getVoiceEntries(measure, voice, staff) {
+  const result = [];
+  let position = 0;
+  for (let i = 0; i < measure.entries.length; i++) {
+    const entry = measure.entries[i];
+    if (entry.type === "note") {
+      const noteStaff = entry.staff ?? 1;
+      if (entry.voice === voice && (staff === void 0 || noteStaff === staff)) {
+        if (!entry.chord) {
+          result.push({
+            entry,
+            entryIndex: i,
+            position,
+            endPosition: position + entry.duration
+          });
+          position += entry.duration;
+        } else {
+          if (result.length > 0) {
+            const prev = result[result.length - 1];
+            result.push({
+              entry,
+              entryIndex: i,
+              position: prev.position,
+              endPosition: prev.endPosition
+            });
+          }
+        }
+      } else if (!entry.chord) {
+        position += entry.duration;
+      }
+    } else if (entry.type === "backup") {
+      position -= entry.duration;
+    } else if (entry.type === "forward") {
+      if (entry.voice === voice) {
+        result.push({
+          entry,
+          entryIndex: i,
+          position,
+          endPosition: position + entry.duration
+        });
+      }
+      position += entry.duration;
+    }
+  }
+  return result;
+}
+function hasNotesInRange(voiceEntries, startPos, endPos) {
+  const conflicting = voiceEntries.filter((e) => {
+    if (e.entry.type !== "note") return false;
+    const note = e.entry;
+    if (note.rest) return false;
+    return e.position < endPos && e.endPosition > startPos;
+  });
+  return { hasNotes: conflicting.length > 0, conflictingNotes: conflicting };
+}
+function createRest(duration, voice, staff) {
+  return {
+    type: "note",
+    rest: { displayStep: void 0, displayOctave: void 0 },
+    duration,
+    voice,
+    staff
+  };
+}
+function rebuildMeasureWithVoice(measure, voice, newEntries, measureDuration, staff) {
+  const otherEntries = [];
+  let position = 0;
+  for (const entry of measure.entries) {
+    if (entry.type === "note") {
+      if (entry.voice !== voice || staff !== void 0 && (entry.staff ?? 1) !== staff) {
+        if (!entry.chord) {
+          otherEntries.push({ position, entry });
+          position += entry.duration;
+        } else {
+          otherEntries.push({ position, entry });
+        }
+      } else if (!entry.chord) {
+        position += entry.duration;
+      }
+    } else if (entry.type === "backup") {
+      position -= entry.duration;
+    } else if (entry.type === "forward") {
+      if (entry.voice !== voice) {
+        otherEntries.push({ position, entry });
+      }
+      position += entry.duration;
+    } else {
+      otherEntries.push({ position, entry });
+    }
+  }
+  const filledNewEntries = [];
+  let currentPos = 0;
+  const sortedNew = [...newEntries].sort((a, b) => a.position - b.position);
+  for (const { position: notePos, entry } of sortedNew) {
+    if (notePos > currentPos) {
+      filledNewEntries.push({
+        position: currentPos,
+        entry: createRest(notePos - currentPos, voice, staff)
+      });
+    }
+    filledNewEntries.push({ position: notePos, entry });
+    if (!entry.chord) {
+      currentPos = notePos + entry.duration;
+    }
+  }
+  if (currentPos < measureDuration) {
+    filledNewEntries.push({
+      position: currentPos,
+      entry: createRest(measureDuration - currentPos, voice, staff)
+    });
+  }
+  const allEntries = [...otherEntries, ...filledNewEntries];
+  allEntries.sort((a, b) => a.position - b.position);
+  const result = [];
+  let currentPosition = 0;
+  for (const { position: targetPos, entry } of allEntries) {
+    const diff = targetPos - currentPosition;
+    if (diff < 0) {
+      result.push({ type: "backup", duration: -diff });
+      currentPosition = targetPos;
+    } else if (diff > 0) {
+      result.push({
+        type: "forward",
+        duration: diff,
+        voice: entry.type === "note" ? entry.voice : 1,
+        staff: entry.type === "note" ? entry.staff : void 0
+      });
+      currentPosition = targetPos;
+    }
+    result.push(entry);
+    if (entry.type === "note" && !entry.chord) {
+      currentPosition += entry.duration;
+    } else if (entry.type === "forward") {
+      currentPosition += entry.duration;
+    }
+  }
+  return result;
+}
+function insertNote(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  if (options.duration <= 0) {
+    return failure([operationError("INVALID_DURATION", `Duration must be positive`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  if (options.position < 0) {
+    return failure([operationError("INVALID_POSITION", `Position cannot be negative`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
+  const context = getMeasureContext(result, options.partIndex, options.measureIndex);
+  const measureDuration = context.time ? getMeasureDuration(context.divisions, context.time) : context.divisions * 4;
+  const noteEnd = options.position + options.duration;
+  if (noteEnd > measureDuration) {
+    return failure([operationError(
+      "EXCEEDS_MEASURE",
+      `Note ending at ${noteEnd} exceeds measure duration ${measureDuration}`,
+      { partIndex: options.partIndex, measureIndex: options.measureIndex },
+      { noteEnd, measureDuration }
+    )]);
+  }
+  const voiceEntries = getVoiceEntries(measure, options.voice, options.staff);
+  const { hasNotes, conflictingNotes } = hasNotesInRange(voiceEntries, options.position, noteEnd);
+  if (hasNotes) {
+    return failure([operationError(
+      "NOTE_CONFLICT",
+      `Position ${options.position}-${noteEnd} conflicts with existing note(s)`,
+      { partIndex: options.partIndex, measureIndex: options.measureIndex, voice: options.voice },
+      { conflictingPositions: conflictingNotes.map((n) => ({ start: n.position, end: n.endPosition })) }
+    )]);
+  }
+  const newNote = {
+    type: "note",
+    pitch: options.pitch,
+    duration: options.duration,
+    voice: options.voice,
+    staff: options.staff,
+    noteType: options.noteType,
+    dots: options.dots
+  };
+  const existingNotes = voiceEntries.filter((e) => {
+    if (e.entry.type !== "note") return true;
+    const note = e.entry;
+    if (note.rest) {
+      return !(e.position < noteEnd && e.endPosition > options.position);
+    }
+    return true;
+  }).map((e) => ({ position: e.position, entry: e.entry }));
+  existingNotes.push({ position: options.position, entry: newNote });
+  measure.entries = rebuildMeasureWithVoice(
+    measure,
+    options.voice,
+    existingNotes,
+    measureDuration,
+    options.staff
+  );
+  const errors = validateMeasureLocal(measure, context, {
+    checkMeasureDuration: true,
+    checkPosition: true,
+    checkVoiceStaff: true
+  });
+  const criticalErrors = errors.filter((e) => e.level === "error");
+  if (criticalErrors.length > 0) {
+    return failure(criticalErrors);
+  }
+  return success(result, errors.filter((e) => e.level !== "error"));
+}
+function removeNote(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
+  let noteCount = 0;
+  let targetEntry = null;
+  let targetIndex = -1;
+  for (let i2 = 0; i2 < measure.entries.length; i2++) {
+    const entry = measure.entries[i2];
+    if (entry.type === "note" && !entry.rest) {
+      if (noteCount === options.noteIndex) {
+        targetEntry = entry;
+        targetIndex = i2;
+        break;
+      }
+      noteCount++;
+    }
+  }
+  if (!targetEntry || targetIndex === -1) {
+    return failure([operationError("NOTE_NOT_FOUND", `Note index ${options.noteIndex} not found`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  measure.entries[targetIndex] = createRest(
+    targetEntry.duration,
+    targetEntry.voice,
+    targetEntry.staff
+  );
+  let i = targetIndex + 1;
+  while (i < measure.entries.length) {
+    const entry = measure.entries[i];
+    if (entry.type === "note" && entry.chord) {
+      measure.entries.splice(i, 1);
+    } else {
+      break;
+    }
+  }
+  return success(result);
+}
+function addChord(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
+  let noteCount = 0;
+  let targetEntry = null;
+  let targetIndex = -1;
+  for (let i = 0; i < measure.entries.length; i++) {
+    const entry = measure.entries[i];
+    if (entry.type === "note" && !entry.rest && !entry.chord) {
+      if (noteCount === options.noteIndex) {
+        targetEntry = entry;
+        targetIndex = i;
+        break;
+      }
+      noteCount++;
+    }
+  }
+  if (!targetEntry || targetIndex === -1) {
+    return failure([operationError("NOTE_NOT_FOUND", `Note index ${options.noteIndex} not found`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const chordNote = {
+    type: "note",
+    pitch: options.pitch,
+    duration: targetEntry.duration,
+    voice: targetEntry.voice,
+    staff: targetEntry.staff,
+    chord: true,
+    noteType: targetEntry.noteType,
+    dots: targetEntry.dots
+  };
+  let insertIndex = targetIndex + 1;
+  while (insertIndex < measure.entries.length) {
+    const entry = measure.entries[insertIndex];
+    if (entry.type === "note" && entry.chord) {
+      insertIndex++;
+    } else {
+      break;
+    }
+  }
+  measure.entries.splice(insertIndex, 0, chordNote);
+  return success(result);
+}
+function changeNoteDuration(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  if (options.newDuration <= 0) {
+    return failure([operationError("INVALID_DURATION", `Duration must be positive`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
+  const context = getMeasureContext(result, options.partIndex, options.measureIndex);
+  const measureDuration = context.time ? getMeasureDuration(context.divisions, context.time) : context.divisions * 4;
+  let noteCount = 0;
+  let targetEntry = null;
+  let targetPosition = 0;
+  let position = 0;
+  for (const entry of measure.entries) {
+    if (entry.type === "note") {
+      if (!entry.rest && !entry.chord) {
+        if (noteCount === options.noteIndex) {
+          targetEntry = entry;
+          targetPosition = position;
+          break;
+        }
+        noteCount++;
+      }
+      if (!entry.chord) {
+        position += entry.duration;
+      }
+    } else if (entry.type === "backup") {
+      position -= entry.duration;
+    } else if (entry.type === "forward") {
+      position += entry.duration;
+    }
+  }
+  if (!targetEntry) {
+    return failure([operationError("NOTE_NOT_FOUND", `Note index ${options.noteIndex} not found`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const oldDuration = targetEntry.duration;
+  const newEnd = targetPosition + options.newDuration;
+  if (newEnd > measureDuration) {
+    return failure([operationError(
+      "EXCEEDS_MEASURE",
+      `New duration would exceed measure (ends at ${newEnd}, measure is ${measureDuration})`,
+      { partIndex: options.partIndex, measureIndex: options.measureIndex },
+      { newEnd, measureDuration }
+    )]);
+  }
+  const voiceEntries = getVoiceEntries(measure, targetEntry.voice, targetEntry.staff);
+  if (options.newDuration > oldDuration) {
+    const { hasNotes, conflictingNotes } = hasNotesInRange(
+      voiceEntries.filter((e) => e.position !== targetPosition),
+      // Exclude current note
+      targetPosition + oldDuration,
+      newEnd
+    );
+    if (hasNotes) {
+      return failure([operationError(
+        "NOTE_CONFLICT",
+        `Cannot extend note: conflicts with existing note(s)`,
+        { partIndex: options.partIndex, measureIndex: options.measureIndex },
+        { conflictingPositions: conflictingNotes.map((n) => ({ start: n.position, end: n.endPosition })) }
+      )]);
+    }
+  }
+  targetEntry.duration = options.newDuration;
+  if (options.noteType !== void 0) {
+    targetEntry.noteType = options.noteType;
+  }
+  if (options.dots !== void 0) {
+    targetEntry.dots = options.dots;
+  }
+  const existingNotes = voiceEntries.filter((e) => {
+    if (e.position === targetPosition) return true;
+    const note = e.entry;
+    if (note.rest) {
+      if (options.newDuration > oldDuration) {
+        return !(e.position >= targetPosition + oldDuration && e.position < newEnd);
+      }
+    }
+    return true;
+  }).map((e) => ({ position: e.position, entry: e.entry }));
+  const modifiedIdx = existingNotes.findIndex((e) => e.position === targetPosition);
+  if (modifiedIdx >= 0) {
+    existingNotes[modifiedIdx].entry = targetEntry;
+  }
+  measure.entries = rebuildMeasureWithVoice(
+    measure,
+    targetEntry.voice,
+    existingNotes,
+    measureDuration,
+    targetEntry.staff
+  );
+  const errors = validateMeasureLocal(measure, context, {
+    checkMeasureDuration: true,
+    checkPosition: true,
+    checkVoiceStaff: true
+  });
+  const criticalErrors = errors.filter((e) => e.level === "error");
+  if (criticalErrors.length > 0) {
+    return failure(criticalErrors);
+  }
+  return success(result, errors.filter((e) => e.level !== "error"));
+}
+function setNotePitch(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
+  let noteCount = 0;
+  for (const entry of measure.entries) {
+    if (entry.type === "note" && !entry.rest) {
+      if (noteCount === options.noteIndex) {
+        entry.pitch = options.pitch;
+        return success(result);
+      }
+      noteCount++;
+    }
+  }
+  return failure([operationError("NOTE_NOT_FOUND", `Note index ${options.noteIndex} not found`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+}
+function addVoice(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
+  const existingVoiceEntries = getVoiceEntries(measure, options.voice, options.staff);
+  if (existingVoiceEntries.length > 0) {
+    return failure([operationError(
+      "NOTE_CONFLICT",
+      `Voice ${options.voice} already exists in this measure`,
+      { partIndex: options.partIndex, measureIndex: options.measureIndex, voice: options.voice }
+    )]);
+  }
+  const context = getMeasureContext(result, options.partIndex, options.measureIndex);
+  const measureDuration = context.time ? getMeasureDuration(context.divisions, context.time) : context.divisions * 4;
+  const rest = createRest(measureDuration, options.voice, options.staff);
+  const currentEnd = getMeasureEndPosition(measure);
+  if (currentEnd > 0) {
+    measure.entries.push({ type: "backup", duration: currentEnd });
+  }
+  measure.entries.push(rest);
+  return success(result);
+}
 function transposePitch(pitch, semitones) {
   const currentSemitone = STEP_SEMITONES[pitch.step] + (pitch.alter ?? 0) + pitch.octave * 12;
   const targetSemitone = currentSemitone + semitones;
@@ -71,7 +1414,7 @@ function transposePitch(pitch, semitones) {
   };
 }
 function transpose(score, semitones) {
-  if (semitones === 0) return score;
+  if (semitones === 0) return success(score);
   const result = cloneScore(score);
   for (const part of result.parts) {
     for (const measure of part.measures) {
@@ -82,59 +1425,162 @@ function transpose(score, semitones) {
       }
     }
   }
-  return result;
+  return success(result);
 }
-function addNote(score, options) {
+function addPart(score, options) {
+  if (score.parts.find((p) => p.id === options.id)) {
+    return failure([operationError("DUPLICATE_PART_ID", `Part ID "${options.id}" already exists`, { partId: options.id })]);
+  }
   const result = cloneScore(score);
-  const part = result.parts[options.partIndex];
-  if (!part) return result;
-  const measure = part.measures[options.measureIndex];
-  if (!measure) return result;
-  const newNote = {
-    type: "note",
-    voice: options.voice,
-    staff: options.staff,
-    ...options.note
+  const insertIndex = options.insertIndex ?? result.parts.length;
+  const partInfo = {
+    type: "score-part",
+    id: options.id,
+    name: options.name,
+    abbreviation: options.abbreviation
   };
-  const currentPosition = getMeasureEndPosition(measure);
-  const positionDiff = options.position - currentPosition;
-  if (positionDiff < 0) {
-    measure.entries.push({
-      type: "backup",
-      duration: -positionDiff
-    });
-  } else if (positionDiff > 0) {
-    measure.entries.push({
-      type: "forward",
-      duration: positionDiff,
-      voice: options.voice,
-      staff: options.staff
-    });
+  let partListInsertIndex = result.partList.length;
+  let partCount = 0;
+  for (let i = 0; i < result.partList.length; i++) {
+    if (result.partList[i].type === "score-part") {
+      if (partCount === insertIndex) {
+        partListInsertIndex = i;
+        break;
+      }
+      partCount++;
+    }
   }
-  measure.entries.push(newNote);
-  return result;
+  result.partList.splice(partListInsertIndex, 0, partInfo);
+  const measureCount = result.parts.length > 0 ? result.parts[0].measures.length : 1;
+  const newPart = { id: options.id, measures: [] };
+  for (let i = 0; i < measureCount; i++) {
+    const measureNumber = result.parts.length > 0 ? result.parts[0].measures[i]?.number ?? String(i + 1) : String(i + 1);
+    const measure = { number: measureNumber, entries: [] };
+    if (i === 0) {
+      measure.attributes = {
+        divisions: options.divisions ?? 4,
+        time: options.time ?? { beats: "4", beatType: 4 },
+        key: options.key ?? { fifths: 0 },
+        clef: options.clef ? [options.clef] : [{ sign: "G", line: 2 }]
+      };
+    }
+    newPart.measures.push(measure);
+  }
+  result.parts.splice(insertIndex, 0, newPart);
+  const validationResult = validate(result, { checkPartReferences: true, checkPartStructure: true });
+  if (!validationResult.valid) {
+    return failure(validationResult.errors);
+  }
+  return success(result, validationResult.warnings);
+}
+function removePart(score, partId) {
+  const partIndex = score.parts.findIndex((p) => p.id === partId);
+  if (partIndex === -1) {
+    return failure([operationError("PART_NOT_FOUND", `Part "${partId}" not found`, { partId })]);
+  }
+  if (score.parts.length <= 1) {
+    return failure([operationError("PART_NOT_FOUND", "Cannot remove the only remaining part", { partId })]);
+  }
+  const result = cloneScore(score);
+  result.parts.splice(partIndex, 1);
+  const partListIndex = result.partList.findIndex((e) => e.type === "score-part" && e.id === partId);
+  if (partListIndex !== -1) {
+    result.partList.splice(partListIndex, 1);
+  }
+  return success(result);
+}
+function duplicatePart(score, options) {
+  const sourceIndex = score.parts.findIndex((p) => p.id === options.sourcePartId);
+  if (sourceIndex === -1) {
+    return failure([operationError("PART_NOT_FOUND", `Source part "${options.sourcePartId}" not found`, { partId: options.sourcePartId })]);
+  }
+  if (score.parts.find((p) => p.id === options.newPartId)) {
+    return failure([operationError("DUPLICATE_PART_ID", `Part ID "${options.newPartId}" already exists`, { partId: options.newPartId })]);
+  }
+  const result = cloneScore(score);
+  const sourcePart = result.parts[sourceIndex];
+  const newPart = JSON.parse(JSON.stringify(sourcePart));
+  newPart.id = options.newPartId;
+  const sourcePartInfo = result.partList.find((e) => e.type === "score-part" && e.id === options.sourcePartId);
+  const newPartInfo = {
+    type: "score-part",
+    id: options.newPartId,
+    name: options.newPartName ?? sourcePartInfo?.name,
+    abbreviation: sourcePartInfo?.abbreviation
+  };
+  result.parts.splice(sourceIndex + 1, 0, newPart);
+  const partListSourceIndex = result.partList.findIndex((e) => e.type === "score-part" && e.id === options.sourcePartId);
+  if (partListSourceIndex !== -1) {
+    result.partList.splice(partListSourceIndex + 1, 0, newPartInfo);
+  } else {
+    result.partList.push(newPartInfo);
+  }
+  return success(result);
 }
-function deleteNote(score, options) {
+function setStaves(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  if (options.staves < 1) {
+    return failure([operationError("INVALID_STAFF", `Staves count must be at least 1`, { partIndex: options.partIndex })]);
+  }
   const result = cloneScore(score);
   const part = result.parts[options.partIndex];
-  if (!part) return result;
-  const measure = part.measures[options.measureIndex];
-  if (!measure) return result;
+  const fromMeasureIndex = options.fromMeasure ?? 0;
+  const measure = part.measures[fromMeasureIndex];
+  if (!measure) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${fromMeasureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: fromMeasureIndex })]);
+  }
+  if (!measure.attributes) {
+    measure.attributes = {};
+  }
+  measure.attributes.staves = options.staves;
+  if (options.clefs) {
+    measure.attributes.clef = options.clefs;
+  } else {
+    const existingClefs = measure.attributes.clef ?? [];
+    const newClefs = [...existingClefs];
+    for (let staff = existingClefs.length + 1; staff <= options.staves; staff++) {
+      newClefs.push(staff === 2 ? { sign: "F", line: 4, staff } : { sign: "G", line: 2, staff });
+    }
+    measure.attributes.clef = newClefs;
+  }
+  const validationResult = validate(result, { checkVoiceStaff: true, checkStaffStructure: true });
+  if (!validationResult.valid) {
+    return failure(validationResult.errors);
+  }
+  return success(result, validationResult.warnings);
+}
+function moveNoteToStaff(score, options) {
+  if (options.partIndex < 0 || options.partIndex >= score.parts.length) {
+    return failure([operationError("PART_NOT_FOUND", `Part index ${options.partIndex} out of bounds`, { partIndex: options.partIndex })]);
+  }
+  const part = score.parts[options.partIndex];
+  if (options.measureIndex < 0 || options.measureIndex >= part.measures.length) {
+    return failure([operationError("MEASURE_NOT_FOUND", `Measure index ${options.measureIndex} out of bounds`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  if (options.targetStaff < 1) {
+    return failure([operationError("INVALID_STAFF", `Target staff must be at least 1`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
+  }
+  const result = cloneScore(score);
+  const measure = result.parts[options.partIndex].measures[options.measureIndex];
   let noteCount = 0;
-  let entryIndex = -1;
-  for (let i = 0; i < measure.entries.length; i++) {
-    if (measure.entries[i].type === "note") {
+  for (const entry of measure.entries) {
+    if (entry.type === "note" && !entry.rest) {
       if (noteCount === options.noteIndex) {
-        entryIndex = i;
-        break;
+        entry.staff = options.targetStaff;
+        const context = getMeasureContext(result, options.partIndex, options.measureIndex);
+        const errors = validateMeasureLocal(measure, context, { checkVoiceStaff: true });
+        const criticalErrors = errors.filter((e) => e.level === "error");
+        if (criticalErrors.length > 0) {
+          return failure(criticalErrors);
+        }
+        return success(result, errors.filter((e) => e.level !== "error"));
       }
       noteCount++;
     }
   }
-  if (entryIndex !== -1) {
-    measure.entries.splice(entryIndex, 1);
-  }
-  return result;
+  return failure([operationError("NOTE_NOT_FOUND", `Note index ${options.noteIndex} not found`, { partIndex: options.partIndex, measureIndex: options.measureIndex })]);
 }
 function changeKey(score, key, options) {
   const result = cloneScore(score);
@@ -142,9 +1588,7 @@ function changeKey(score, key, options) {
   for (const part of result.parts) {
     for (const measure of part.measures) {
       if (measure.number === targetMeasure) {
-        if (!measure.attributes) {
-          measure.attributes = {};
-        }
+        if (!measure.attributes) measure.attributes = {};
         measure.attributes.key = key;
       }
     }
@@ -157,9 +1601,7 @@ function changeTime(score, time, options) {
   for (const part of result.parts) {
     for (const measure of part.measures) {
       if (measure.number === targetMeasure) {
-        if (!measure.attributes) {
-          measure.attributes = {};
-        }
+        if (!measure.attributes) measure.attributes = {};
         measure.attributes.time = time;
       }
     }
@@ -174,15 +1616,9 @@ function insertMeasure(score, options) {
     if (insertIndex === -1) continue;
     const numericPart = parseInt(targetMeasure, 10);
     const newMeasureNumber = String(isNaN(numericPart) ? insertIndex + 2 : numericPart + 1);
-    const newMeasure = {
-      number: newMeasureNumber,
-      entries: []
-    };
-    if (options.copyAttributes) {
-      const sourceMeasure = part.measures[insertIndex];
-      if (sourceMeasure.attributes) {
-        newMeasure.attributes = { ...sourceMeasure.attributes };
-      }
+    const newMeasure = { number: newMeasureNumber, entries: [] };
+    if (options.copyAttributes && part.measures[insertIndex].attributes) {
+      newMeasure.attributes = { ...part.measures[insertIndex].attributes };
     }
     part.measures.splice(insertIndex + 1, 0, newMeasure);
     for (let i = insertIndex + 2; i < part.measures.length; i++) {
@@ -210,106 +1646,84 @@ function deleteMeasure(score, measureNumber) {
   }
   return result;
 }
-function setDivisions(score, options) {
-  const result = cloneScore(score);
-  const part = result.parts[options.partIndex];
-  if (!part) return result;
-  const measure = part.measures[options.measureIndex];
-  if (!measure) return result;
-  if (!measure.attributes) {
-    measure.attributes = {};
-  }
-  measure.attributes.divisions = options.divisions;
-  return result;
-}
-function addChordNote(score, options) {
-  const result = cloneScore(score);
-  const part = result.parts[options.partIndex];
-  if (!part) return result;
-  const measure = part.measures[options.measureIndex];
-  if (!measure) return result;
-  let noteCount = 0;
-  let entryIndex = -1;
-  let targetNote = null;
-  for (let i = 0; i < measure.entries.length; i++) {
-    const entry = measure.entries[i];
-    if (entry.type === "note") {
-      if (noteCount === options.afterNoteIndex) {
-        entryIndex = i;
-        targetNote = entry;
-        break;
-      }
-      noteCount++;
-    }
-  }
-  if (entryIndex !== -1 && targetNote) {
-    const chordNote = {
-      type: "note",
-      pitch: options.pitch,
-      duration: targetNote.duration,
-      voice: targetNote.voice,
-      staff: targetNote.staff,
-      chord: true,
-      noteType: targetNote.noteType,
-      dots: targetNote.dots
-    };
-    measure.entries.splice(entryIndex + 1, 0, chordNote);
-  }
-  return result;
-}
-function modifyNotePitch(score, options) {
-  const result = cloneScore(score);
-  const part = result.parts[options.partIndex];
-  if (!part) return result;
-  const measure = part.measures[options.measureIndex];
-  if (!measure) return result;
-  let noteCount = 0;
-  for (const entry of measure.entries) {
-    if (entry.type === "note") {
-      if (noteCount === options.noteIndex) {
-        entry.pitch = options.pitch;
-        break;
-      }
-      noteCount++;
-    }
-  }
-  return result;
-}
-function modifyNoteDuration(score, options) {
-  const result = cloneScore(score);
-  const part = result.parts[options.partIndex];
-  if (!part) return result;
-  const measure = part.measures[options.measureIndex];
-  if (!measure) return result;
-  let noteCount = 0;
-  for (const entry of measure.entries) {
-    if (entry.type === "note") {
-      if (noteCount === options.noteIndex) {
-        entry.duration = options.duration;
-        if (options.noteType !== void 0) {
-          entry.noteType = options.noteType;
-        }
-        if (options.dots !== void 0) {
-          entry.dots = options.dots;
-        }
-        break;
-      }
-      noteCount++;
-    }
-  }
-  return result;
-}
+var addNote = (score, options) => {
+  const result = insertNote(score, {
+    partIndex: options.partIndex,
+    measureIndex: options.measureIndex,
+    voice: options.voice,
+    staff: options.staff,
+    position: options.position,
+    pitch: options.note.pitch ?? { step: "C", octave: 4 },
+    duration: options.note.duration,
+    noteType: options.note.noteType,
+    dots: options.note.dots
+  });
+  return result.success ? result.data : score;
+};
+var deleteNote = (score, options) => {
+  const result = removeNote(score, options);
+  return result.success ? result.data : score;
+};
+var addChordNote = (score, options) => {
+  const result = addChord(score, { ...options, noteIndex: options.afterNoteIndex });
+  return result.success ? result.data : score;
+};
+var modifyNotePitch = (score, options) => {
+  const result = setNotePitch(score, options);
+  return result.success ? result.data : score;
+};
+var modifyNoteDuration = (score, options) => {
+  const result = changeNoteDuration(score, { ...options, newDuration: options.duration });
+  return result.success ? result.data : score;
+};
+var addNoteChecked = (score, options) => {
+  return insertNote(score, {
+    partIndex: options.partIndex,
+    measureIndex: options.measureIndex,
+    voice: options.voice,
+    staff: options.staff,
+    position: options.position,
+    pitch: options.note.pitch ?? { step: "C", octave: 4 },
+    duration: options.note.duration,
+    noteType: options.note.noteType,
+    dots: options.note.dots
+  });
+};
+var deleteNoteChecked = removeNote;
+var addChordNoteChecked = (score, options) => {
+  return addChord(score, { ...options, noteIndex: options.afterNoteIndex });
+};
+var modifyNotePitchChecked = setNotePitch;
+var modifyNoteDurationChecked = (score, options) => {
+  return changeNoteDuration(score, { ...options, newDuration: options.duration });
+};
+var transposeChecked = transpose;
 export {
+  addChord,
   addChordNote,
+  addChordNoteChecked,
   addNote,
+  addNoteChecked,
+  addPart,
+  addVoice,
   changeKey,
+  changeNoteDuration,
   changeTime,
   deleteMeasure,
   deleteNote,
+  deleteNoteChecked,
+  duplicatePart,
   insertMeasure,
+  insertNote,
   modifyNoteDuration,
+  modifyNoteDurationChecked,
   modifyNotePitch,
-  setDivisions,
-  transpose
+  modifyNotePitchChecked,
+  moveNoteToStaff,
+  removeNote,
+  removePart,
+  setNotePitch,
+  setStaves,
+  transpose,
+  transposeChecked
 };
-//# sourceMappingURL=index.mjs.map