> ## Documentation Index
> Fetch the complete documentation index at: https://musicready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MRS-S Spans, Directions & Structure

> Spans, directions, movements, and alternatives in MRS-S.

See: [`/MRS-Specification-RFC#4-mrs-s-the-canonical-storage-format`](/MRS-Specification-RFC#4-mrs-s-the-canonical-storage-format)

## Spans Section

Spans define relationships between events across time. All endpoints use UUID references.

```clojure theme={null}
(spans
  (slur
    :id #uuid "018c3f2c-0001-..."
    :from #uuid "018c3f2a-0001-..."
    :to #uuid "018c3f2a-0004-...")
  
  (hairpin
    :id #uuid "018c3f2c-0002-..."
    :type crescendo
    :from #uuid "018c3f2a-0001-..."
    :to #uuid "018c3f2a-0008-...")
  
  (beam
    :id #uuid "018c3f2c-0003-..."
    :events [#uuid "018c3f2a-0005-..." 
             #uuid "018c3f2a-0006-..."
             #uuid "018c3f2a-0007-..."]))
```

### Span Types

| Type         | Endpoint Style | Description              |
| ------------ | -------------- | ------------------------ |
| `slur`       | from/to        | Phrasing slur            |
| `tie`        | from/to        | Tie between same pitches |
| `hairpin`    | from/to        | Crescendo/diminuendo     |
| `beam`       | events list    | Beam grouping            |
| `ottava`     | from/to        | Octave transposition     |
| `pedal`      | from/to        | Piano pedal              |
| `trill-span` | from/to        | Extended trill line      |
| `gliss`      | from/to        | Glissando line           |
| `volta`      | from/to        | Ending bracket           |

### Span Attributes

```clojure theme={null}
(slur
  :id #uuid "..."
  :from #uuid "..."
  :to #uuid "..."
  :style legato)          ; Optional style

(hairpin
  :id #uuid "..."
  :type crescendo         ; crescendo or diminuendo
  :from #uuid "..."
  :to #uuid "...")

(beam
  :id #uuid "..."
  :events [#uuid "..." #uuid "..." #uuid "..."]
  :feather accelerando)   ; Optional feathered beam
```

### Span Immutability

Once created, span endpoints (`:from`, `:to`, `:events`) are **immutable**. To change endpoints, delete the span and create a new one.

### Boundary Markers

For spans that cross Working Set boundaries:

```clojure theme={null}
(slur
  :id #uuid "..."
  :from #uuid "..."        ; Inside scope
  :to #uuid "..."          ; Outside scope
  :boundary-exit true)     ; Marks endpoint outside
```

| Marker                 | Meaning                          |
| ---------------------- | -------------------------------- |
| `:boundary-entry true` | Span starts outside, ends inside |
| `:boundary-exit true`  | Span starts inside, ends outside |

Boundary-marked spans are **read-only** at their boundary endpoints.

## Directions

Directions are measure-level or instrument-level instructions.

### Measure-Level Directions

```clojure theme={null}
(measure :id #uuid "..." :number 45
  (dir :type tempo :beat 0 :text "Più mosso" :tempo 132)
  (dir :type dynamic :beat 0 :text "ff" :scope all)
  (dir :type rehearsal :beat 0 :text "B")
  (dir :type text :beat 2 :text "poco rit." :placement above)
  (dir :type segno :beat 0)
  (dir :type coda :beat 0)
  (dir :type fine :beat 0)
  (dir :type dc :beat 0 :text "D.C. al Coda")
  
  (flute-1 ...))
```

### Instrument-Level Directions

```clojure theme={null}
(measure :id #uuid "..." :number 45
  (flute-1
    (dir :type text :beat 0 :text "sul G" :placement above)
    (v1 ...)))
```

### Direction Types

| Type        | Description                  |
| ----------- | ---------------------------- |
| `tempo`     | Tempo marking                |
| `dynamic`   | Dynamic marking (score-wide) |
| `rehearsal` | Rehearsal mark               |
| `text`      | Text instruction             |
| `segno`     | Segno sign                   |
| `coda`      | Coda sign                    |
| `fine`      | Fine marking                 |
| `dc`        | D.C. (da capo)               |
| `ds`        | D.S. (dal segno)             |

## Movements

Multi-movement works use the movements structure:

```clojure theme={null}
(movements
  (movement 1 :title "Allegro" :key C :mode major :time 4/4
    (measures
      (measure :id #uuid "..." :number 1 ...) 
      ...))
  
  (movement 2 :title "Adagio" :key F :mode major :time 3/4
    (measures
      (measure :id #uuid "..." :number 1 ...) 
      ...))
  
  (movement 3 :title "Finale" :key C :mode major :time 2/4
    (measures
      (measure :id #uuid "..." :number 1 ...) 
      ...)))
```

Measure numbers restart in each movement. UUIDs remain globally unique.

## Alternatives (Ossia, Variants)

```clojure theme={null}
(alternatives
  (ossia
    :measures [#uuid "..." #uuid "..."]
    :instrument flute-1
    :label "easier version"
    :content
      (measures
        (measure :id #uuid "..." :number 123 ...)))
  
  (variant
    :measures [#uuid "..."]
    :label "manuscript variant"
    :source "autograph ms."
    :content ...))
```

### Alternative Types

| Type        | Purpose                              |
| ----------- | ------------------------------------ |
| `ossia`     | Alternative passage (usually easier) |
| `variant`   | Source variant (editorial)           |
| `editorial` | Editorial suggestion                 |

## Layout Hints (Optional)

Layout hints are NON-NORMATIVE suggestions for rendering:

```clojure theme={null}
(layout
  :bar-numbers (every 5)
  :multi-rest-style consolidated
  
  (break :type system :after #uuid "018c3f40-0008-...")
  (break :type page :after #uuid "018c3f40-0020-...")
  
  (hide-empty-staves true)
  
  (condense 
    :instruments [flute-1 flute-2]
    :measures [#uuid "..." #uuid "..."]
    :label "Fl. 1, 2"))
```

### Layout Elements

| Element             | Description                      |
| ------------------- | -------------------------------- |
| `break`             | System or page break             |
| `hide-empty-staves` | Hide staves with rests           |
| `condense`          | Combine instruments on one staff |
| `spacing`           | Measure spacing hints            |

Layout hints do not affect playback or semantic content.