# neumaRk — Specifica completa (v0.6.0)

> Specifica completa del linguaggio neumaRk (versione 0.6.0), concatenata in un unico file leggibile da un'IA.

Source: https://neumark.dev/it/

## Contents

- neumaRk
- Panoramica
- Specifica formale
- Header
- Datapack
- Note e Durate
- Accordi
- Seconda voce per rigo
- Grace notes (appoggiature e acciaccature)
- Articolazioni (riga `A)`)
- Dinamiche e annotation testuali
- Testo cantato (riga `L)`)
- Markup testuale
- Markers
- Flusso, Battute e Ripetizioni
- PLAY) e FORM)
- Play directive
- Versioni del brano
- Collezioni (book / playlist)
- Formati
- Changelog ufficiale

# neumaRk

**Un linguaggio testuale per la musica, leggibile dall'uomo e interpretabile
dalla macchina.**

neumaRk è un modo testuale di scrivere musica — chiaro per le persone e preciso
per i computer. Si colloca tra la notazione musicale tradizionale e i moderni
workflow digitali, rendendo la musica facile da scrivere, condividere,
analizzare, trasformare e versionare.

È progettato per essere scritto **direttamente da tastiera**, senza mouse né
palette grafiche, ed è ottimizzato per **lead sheet**, bozze musicali e
strutture armoniche — contenuti a una o poche voci, accordi e struttura. Non è
pensato per grandi partiture orchestrali, né per sostituire la notazione
tradizionale: ne è una base complementare, focalizzata sul **significato**
musicale più che sulla resa grafica.

Se sai leggere sigle di accordo e pattern ritmici, sai già leggere neumaRk.

---

## Da dove partire

- **Cos'è, obiettivi e casi d'uso** → **Overview** (`neumaRk_overview.md`)
- **Il linguaggio, in dettaglio normativo** → **Specification**
  (`neumaRk_specification.md`) e i documenti collegati (note e durate, accordi,
  flusso e ripetizioni, dinamiche, markup testuale, voci, collezioni
  book/playlist, …)
- **Le evoluzioni del linguaggio** → **Changelog** (`neumaRk_changelog.md`)

> I concetti di fondo — livelli di dettaglio (Compact / Human / Verbose),
> sintassi formale e informale, relazione con la notazione tradizionale,
> obiettivi di progettazione — sono trattati nell'**Overview**.


---

# Panoramica

## 1. Cos'è neumaRk

**neumaRk** è un sistema formale di rappresentazione testuale della musica. È progettato per essere contemporaneamente **human‑readable** e **machine‑readable**, con una sintassi e una semantica definite che consentono di descrivere eventi musicali, strutture temporali, armonia, dinamiche, testi e sezioni formali.

neumaRk è, allo stesso tempo:

- un **linguaggio di markup musicale**;
- una **DSL (Domain Specific Language)** orientata alla notazione musicale;
- un **formato testuale puro**, utilizzabile come file standalone.

Il linguaggio nasce per colmare lo spazio tra la scrittura musicale tradizionale e le esigenze dei sistemi software moderni: versionamento, parsing affidabile, compattezza, condivisione e trasformazione automatica.

---

## 2. Obiettivi di progettazione

neumaRk è progettato attorno ai seguenti obiettivi principali:

1. **Chiarezza semantica**  
   Ogni costrutto ha un significato preciso e non ambiguo.

2. **Leggibilità umana**  
   Un file neumaRk può essere letto e compreso direttamente da un musicista o da un autore.

3. **Efficienza e rapidità di scrittura**

   neumaRk è progettato per favorire una scrittura musicale rapida ed
   efficiente, basata su input testuale e deduzione contestuale,
   riducendo al minimo le informazioni ridondanti.

4. **Affidabilità del parsing**  
   La sintassi consente un parsing deterministico, anche in presenza di informazioni implicite.

5. **Flessibilità espressiva**  
   Lo stesso contenuto musicale può essere espresso in forme più compatte o più verbose.

6. **Neutralità rispetto al rendering**  
   Il linguaggio descrive _cosa_ è la musica, non _come_ deve essere disegnata.

7. **Compatibilità con workflow moderni**  
   File testuali, diff‑friendly, adatti a sistemi di versionamento e a scambi via URL.

---

## 3. neumaRk come DSL musicale

neumaRk è una DSL: un linguaggio specializzato, con un dominio ben definito.

Il dominio di neumaRk comprende:

- tempo e metrica;
- altezze e durate;
- articolazioni e dinamiche;
- armonia e sigle di accordo;
- testo (lyrics);
- struttura formale (marker, sezioni, ripetizioni);
- suggerimenti di layout e formattazione.

Il linguaggio non tenta di replicare ogni aspetto grafico della notazione musicale tradizionale, ma di fornire una rappresentazione testuale coerente e trasformabile.

---

## 4. Human‑readable e Machine‑readable

neumaRk è progettato per essere:

- **leggibile dall'uomo**, senza necessità di strumenti dedicati;
- **interpretabile dalla macchina**, senza euristiche fragili.

Questo risultato è ottenuto tramite:

- una sintassi line‑based;
- un insieme ridotto di simboli con significato stabile;
- regole esplicite per la deduzione delle informazioni implicite.

Un file neumaRk può essere scritto rapidamente a mano, ma anche generato, validato e trasformato automaticamente.

---

## 5. Sintassi formale e sintassi informale

Uno degli elementi centrali di neumaRk è la coesistenza di **due livelli di sintassi**:

- **Sintassi formale**  
  Rigorosa, completamente disambiguata, pensata per garantire un parsing affidabile in qualsiasi situazione.

- **Sintassi informale**  
  Più compatta e naturale da scrivere, basata su convenzioni comuni e deduzione contestuale.

Le due sintassi non sono linguaggi separati: sono due modalità espressive dello stesso linguaggio.

L'autore può decidere, caso per caso, se privilegiare:

- la massima precisione semantica;
- la massima velocità e leggibilità.

---

## 6. Formati di file e livelli di dettaglio

neumaRk supporta diversi **livelli di esplicitazione**, che influenzano la quantità di informazione presente nel file:

- **Compact**  
  Informazioni ridotte all'essenziale. Massima compattezza.

- **Human**  
  Compromesso tra compattezza e chiarezza. Orientato alla lettura umana.

- **Verbose**  
  Tutte le informazioni sono esplicite. Nessuna ambiguità semantica.

Questi livelli non definiscono linguaggi diversi, ma modalità di utilizzo dello stesso linguaggio.

---

## 7. Casi d'uso tipici

neumaRk è pensato per supportare, tra gli altri, i seguenti scenari:

- scrittura e condivisione di leadsheet;
- rappresentazione testuale di partiture;
- embedding di musica in URL o messaggi;
- parsing e rendering automatico;
- editing collaborativo e versionamento;
- conversione verso formati grafici o audio.

---

## 8. Relazione con la notazione musicale tradizionale

neumaRk non è una trascrizione diretta della notazione su pentagramma.

Molti concetti sono condivisi (durate, battute, legature, accordi), ma il linguaggio:

- privilegia la **semantica** rispetto alla grafica;
- consente informazioni implicite non esplicitabili facilmente su carta;
- separa la descrizione musicale dalla resa visiva.

La notazione tradizionale è una possibile _rappresentazione di output_, non il modello interno.

---

## 9. Non‑obiettivi

neumaRk **non** ha come obiettivo:

- sostituire la notazione musicale tradizionale in ambito editoriale;
- definire uno standard grafico unico;
- rappresentare micro‑dettagli calligrafici;
- coprire ogni possibile pratica musicale esistente.

Il linguaggio è intenzionalmente focalizzato e modulare.

---

## 10. Organizzazione della specifica

La documentazione di neumaRk è suddivisa in più file, ciascuno con una
responsabilità specifica: questa panoramica concettuale, la specifica
normativa, e i documenti di dettaglio (header, datapack, note e durate,
accordi, flusso, dinamiche, markup, voci, grace notes, ecc.).

L'elenco completo e aggiornato dei documenti normativi è in
`neumaRk_specification.md` §7. Per la pagina d'ingresso e la navigazione,
vedi `index.md`.

Questa suddivisione consente una lettura progressiva e una manutenzione evolutiva della specifica.


---

# Specifica formale

## 1. Scopo del documento

Questo documento definisce la **specifica formale** del linguaggio neumaRk.

Stabilisce in modo normativo:

- quali costrutti sono validi
- come devono essere interpretati
- quali regole devono essere rispettate da parser, validatori e strumenti di rendering

Tutto ciò che è descritto in questo documento è da considerarsi **vincolante**.

---

## 2. Livelli della specifica

La specifica neumaRk è organizzata in più livelli, ciascuno con responsabilità precise:

1. **Livello sintattico**

   - definisce la grammatica testuale
   - stabilisce quali sequenze di caratteri sono valide

2. **Livello strutturale**

   - definisce la struttura logica del documento
   - stabilisce le relazioni tra le varie sezioni

3. **Livello semantico**

   - definisce il significato musicale dei costrutti
   - chiarisce ambiguità e casi limite

4. **Livello di validazione**
   - definisce le condizioni di validità
   - stabilisce gli errori e gli stati non validi

## 2.1 Contesto musicale persistente

Il parsing di un documento neumaRk avviene all’interno di un **contesto musicale persistente**.

Il contesto musicale conserva le ultime informazioni esplicite rilevanti
(altezze, durate, stato metrico) e **persiste lungo l’intero documento**,
attraversando:

- righe;
- misure;
- datapack consecutivi.

Il contesto musicale **non viene automaticamente resettato** all’inizio di un
nuovo datapack.

Un datapack rappresenta un’unità strutturale e di sincronizzazione verticale,
ma **non costituisce un confine semantico per la deduzione musicale**.

In assenza di valori espliciti, le regole di deduzione fanno sempre riferimento
allo stato corrente del contesto musicale.

---

## 3. Terminologia normativa

In questo documento si utilizzano i seguenti termini con significato normativo:

- **deve** / **non deve**: requisito obbligatorio
- **può** / **può non**: comportamento opzionale
- **non è valido**: il documento deve essere rifiutato
- **viene interpretato come**: comportamento deterministico

---

## 4. Uso contestuale dei simboli

Alcuni simboli testuali di neumaRk hanno una semantica **contestuale**,
determinata dal tipo di riga musicale in cui compaiono. L'algoritmo
normativo con cui il **tipo di riga** stesso viene dedotto (in assenza di
marcatore esplicito) è in `neumaRk_datapack.md §3.bis`.

In particolare:

- il simbolo `.` (punto)
- il simbolo `!` (punto esclamativo)

assumono significati differenti a seconda che compaiano in:

- righe di note (`N) `);
- righe di accordi (`C) `).

Essi assumono significati differenti, anche all'interno delle stesse righe, a seconda della loro posizione.

Il contesto di riga e la posizione in relazione agli altri elementi della riga sono sempre sufficienti a risolvere la semantica del simbolo in modo deterministico.

Non esiste alcun caso valido in cui un simbolo possa essere ambiguo
all’interno dello stesso contesto di riga.

## 5. Identificazione del documento e estensione

Un documento neumaRk è un file di testo codificato in UTF-8.

L’estensione di file raccomandata per i documenti neumaRk è:

```
.nrk
```

L’uso dell’estensione `.nrk` consente a strumenti, editor e sistemi operativi
di riconoscere in modo affidabile i documenti neumaRk.

L’estensione è **raccomandata ma non obbligatoria**.  
Un documento è considerato valido in quanto documento neumaRk in base al suo
contenuto, e non in base al nome del file o alla sua estensione.

Gli strumenti **possono** assumere l’estensione `.nrk` come predefinita
in fase di lettura o scrittura di file neumaRk.

## 6. Struttura generale di un documento neumaRk

Un documento neumaRk può contenere, in ordine:

1. Header (metadati)
2. Contenuto musicale e contenuto di formattazione

L’ordine delle sezioni è significativo e deve essere rispettato.

### Delimitazione strutturale

In neumaRk, un **rigo vuoto ha valore strutturale**.

I righi vuoti delimitano blocchi logici del documento, in particolare:

- la fine dell’header;
- la separazione tra datapack musicali consecutivi.

Un blocco strutturale (header o datapack) è sempre costituito da una o più
righe non vuote consecutive.

---

## 7. Riferimenti ai documenti correlati

La presente specifica fa riferimento ai seguenti documenti:

- `neumaRk_overview.md`
- `neumaRk_formats.md`
- `neumaRk_header.md`
- `neumaRk_datapack.md`
- `neumaRk_markers.md`
- `neumaRk_chords.md`
- `neumaRk_notes_and_durations.md`
- `neumaRk_grace_notes.md`
- `neumaRk_voices.md`
- `neumaRk_articulations.md`
- `neumaRk_lyrics.md`
- `neumaRk_flow_and_repeats.md`
- `neumaRk_dynamics.md`
- `neumaRk_text_markup.md`
- `neumaRk_play_and_form.md`
- `neumaRk_play_directive.md`
- `neumaRk_versions.md`
- `neumaRk_collections.md`

Ciascun documento approfondisce in modo normativo un aspetto specifico del linguaggio.

---

## 8. Compatibilità e versioning

Ogni documento neumaRk deve dichiarare esplicitamente la versione del linguaggio utilizzata.
La prima riga del documento deve riportare la sequenza `nrk:`seguita dalla versione di riferimento nella forma major.minor

esempio

```
nrk:0.6
```

Le regole di compatibilità tra versioni e l'evoluzione del linguaggio sono documentate nel `neumaRk_changelog.md`.

---

## 9. Estensioni

Il linguaggio neumaRk può essere esteso solo nei limiti esplicitamente consentiti dalla specifica.

Costrutti non definiti o non riconosciuti rendono il documento **non valido**, salvo diversa indicazione esplicita.


---

# Header

## 1. Definizione e ruolo dell’header

L’**header** è una sezione opzionale di un documento neumaRk, collocata all’inizio del file dopo la dichiarazione di versione.

Il suo scopo è contenere tutte le **informazioni non strettamente musicali** necessarie a:

- identificare il brano;
- contestualizzarlo (autore, stile, tempo, tonalità, ecc.);
- fornire indicazioni globali valide per l’intero documento.

In neumaRk l’header **coincide integralmente con i metadati del file**.  
Non esistono metadati esterni, distribuiti o dichiarati altrove.

---

## 2. `nrk:version` e relazione con l’header

Ogni file neumaRk **deve** iniziare con una riga di versione nella forma:

nrk:<major>.<minor>

Esempio:

```
nrk:0.6
```

Caratteristiche:

- è **obbligatoria**;
- deve essere la **prima riga del file**;
- **non fa parte dell’header**.

Dopo la riga `nrk:version` possono comparire uno o più righi vuoti, seguiti da:

- un header, oppure
- direttamente dal primo datapack musicale.

---

## 3. Blocco di header e criterio di riconoscimento

### 3.1 Blocco iniziale

L’header, se presente, è costituito da un **blocco di righe consecutive** che:

- segue la riga `nrk:version` (dopo eventuali righi vuoti);
- precede qualsiasi datapack musicale;
- **non contiene righe vuote**.

L’header **termina al primo rigo vuoto**.  
Il contenuto successivo è interpretato come datapack musicale.

---

### 3.2 Criterio “tutto o niente” (parsing conservativo)

Il blocco iniziale viene riconosciuto come header **solo se tutte le sue righe sono valide** secondo le regole di questo documento.

Se anche una sola riga:

- viola una regola sintattica;
- contiene un elemento non ammesso;
- oppure è interpretabile come riga musicale,

l’intero blocco viene classificato come **non header**.

In tal caso:

- il parsing dell’header fallisce;
- il blocco viene successivamente analizzato come datapack musicale.

Non è ammesso parsing parziale dell’header.

---

### 3.3 Principio di deduzione conservativa e anti-collisione

La deduzione implicita nell’header di neumaRk è governata da un principio fondamentale:

> **un elemento dell’header non deve mai poter essere confuso con un elemento musicale.**

In particolare, una riga dell’header **non deve collidere semanticamente** con:

- una riga di note;
- una riga di accordi;
- una riga di markers;
- qualunque riga valida come datapack musicale.

Questo principio ha lo scopo di:

- evitare ambiguità strutturali;
- rendere il parsing affidabile;
- garantire che la deduzione non produca interpretazioni errate.

La deduzione è quindi **conservativa**:

- se una riga può essere interpretata sia come elemento di header sia come riga musicale,
  **prevale l’interpretazione musicale**;
- in tal caso, il parsing dell’header fallisce e il blocco viene trattato come datapack musicale.

La specifica **non impone una grammatica formale completa** per distinguere in modo assoluto header e contenuto musicale.
Alcuni aspetti della deduzione possono dipendere da euristiche implementative, purché rispettino il principio di non-collisione e la strategia conservativa descritta.

#### Deduzione di _style_

Nella deduzione implicita dell’header, gli elementi testuali debolmente
tipizzati (come lo _style_) devono sempre evitare collisioni con elementi
strutturalmente più forti, quali `Key`, `Meter` e `BPM`.

## 5. Sintassi formale e sintassi informale

L’header supporta due modalità sintattiche: **formale (esplicita)** e **informale (implicita)**.

### 5.1 Sintassi formale (esplicita)

Caratteristiche:

- uso di marcatori di riga espliciti;
- nessuna ambiguità sintattica;
- ordine delle righe **arbitrario**;
- ogni elemento occupa una riga dedicata.

È la modalità raccomandata per l’uso automatico.

---

### 5.2 Sintassi informale (implicita)

Caratteristiche:

- uso minimo o assente di marcatori;
- deduzione basata su contenuto e posizione;
- ordine delle righe **vincolato**;
- deduzione basata su regole conservative.

La sintassi informale privilegia la leggibilità e la scrittura rapida.

---

### 5.3 Precedenze

In caso di ambiguità o conflitto, prevale:

1. la sintassi formale;
2. le regole di posizione;
3. la deduzione semantica;
4. il fallimento del parsing dell’header.

---

## 6. Elementi ammessi nell’header

L’header riconosce esclusivamente i seguenti elementi:

- **Titolo**
- **Credits**
  - Music by
  - Lyrics by
  - Arranger
  - Transcriber
- **Year**
- **Style**
- **Key**
- **Meter**
- **BPM**
- **Versions** (solo forma esplicita `HV)`, vedi §11.6)

Tutti gli elementi sono opzionali.  
Qualunque altro contenuto invalida l’intero header.

---

## 7. Marcatori di header

### 7.1 Definizione

I marcatori di header sono sequenze alfabetiche maiuscole seguite dal carattere `)` e da uno spazio.

- il primo carattere è sempre `H`;
- la lunghezza varia da due a tre lettere.

---

### 7.2 Elenco dei marcatori

| Marcatore | Significato      |
| --------- | ---------------- |
| `HT) `    | Titolo           |
| `HC) `    | Credits generici |
| `HCM) `   | Music by         |
| `HCL) `   | Lyrics by        |
| `HCA) `   | Arranger         |
| `HCT) `   | Transcriber      |
| `HY) `    | Year             |
| `HS) `    | Style            |
| `HK) `    | Key              |
| `HM) `    | Meter            |
| `HB) `    | BPM              |
| `HV) `    | Versions         |

---

## 8. Titolo

### 8.1 Forma esplicita

- marcatore: `HT) `;
- la prima riga `HT)` è il **titolo principale**; sono ammesse righe `HT)`
  successive come **titoli alternativi** (alias di ricerca / per-lingua);
- può contenere qualsiasi testo;
- può portare un **tag lingua** finale `[lingua]` (es. `HT) No More Blues
  [EN]`): forma sintattica `[a-z]{2,3}(-regione)?`, case-insensitive,
  strippato dal testo memorizzato. Associa quel titolo a una lingua — è il
  **titolo tradotto** per le edizioni di quella lingua
  (`neumaRk_lyrics.md` §8.8).

---

### 8.2 Forma implicita

In assenza di marcatore, il titolo:

- deve essere la **prima riga dell’header**;
- deve iniziare con una lettera maiuscola o un numero (dopo eventuali spazi);
- **non deve essere interpretabile come riga musicale** (note, accordi o markers).

La deduzione del titolo implicito è **conservativa**:  
in caso di dubbio, l’header fallisce.

---

### 8.3 Titolo e credits sulla stessa riga

È ammesso indicare i credits sulla stessa riga del titolo **solo in forma implicita**.

In tal caso:

- i credits devono essere racchiusi tra parentesi tonde;
- non deve essere presente alcun marcatore esplicito sulla riga.

---

## 9. Credits

### 9.1 Ruolo

I credits identificano i contributori del brano.

---

### 9.2 Credits con marcatori specifici

Ogni elemento appare su una riga autonoma con marcatore dedicato:

- `HCM) ` — Music by
- `HCL) ` — Lyrics by
- `HCA) ` — Arranger
- `HCT) ` — Transcriber

L’ordine è arbitrario.

> **Nota (edizioni del testo).** `HCL)` indica l'autore del **testo di
> default** (edizione neutra). L'autore di un'**edizione** taggata si scrive
> col gruppo `<…>` sul blocco `LYRICS)` (`neumaRk_lyrics.md` §8.8), non qui.
> Il vecchio credit per-lingua `HCL) … [lingua]` è **rimosso**: una riga
> `HCL)` setta sempre e solo il lyricsBy primario.

---

### 9.3 Credits con marcatore generico

- marcatore: `HC) `;
- una sola riga;
- parentesi opzionali;
- elementi separati da `/`.

Assegnazione:

- primo elemento senza prefisso → Music by;
- secondo elemento senza prefisso → Lyrics by;
- `arr:` → Arranger;
- `trans:` → Transcriber;
- elementi successivi senza prefisso vengono ignorati.

---

### 9.4 Credits impliciti

Senza marcatore esplicito, i credits:

- devono essere racchiusi tra parentesi tonde;
- devono comparire su una sola riga;
- devono essere separati da `/`.

Posizione ammessa:

- stessa riga del titolo;
- oppure riga immediatamente successiva.

---

## 10. Year, Style, Key, Meter, BPM

### 10.1 Regole comuni

- tutti opzionali;
- possono comparire **solo dopo titolo e credits** (se presenti);
- in forma esplicita l’ordine è arbitrario.

---

### 10.2 Forma esplicita

- ogni elemento su riga dedicata;
- uso del marcatore corrispondente.

---

### 10.3 Forma implicita

- possono essere combinati sulla stessa riga;
- nessun marcatore;
- riconoscimento basato su pattern.

---

## 11. Regole specifiche per elemento

### 11.1 Year

Indica l'anno di composizione: numero a 4 cifre compreso fra 1000 e 2999.

### 11.2 Style

Lo _style_ è una descrizione testuale del carattere musicale del brano
(es. `swing`, `bossa`, `latin`, `rock ballad`).

Il valore dichiarato nell'header inizializza `currentStyle` e può
essere **sovrascritto localmente** in una qualsiasi misura tramite una
play directive `(=Style,…)` nella riga `M)` (vedi
`neumaRk_play_directive.md`).

#### Forma implicita

In forma implicita, lo style:

- deve iniziare con una lettera minuscola (dopo eventuali spazi);
- non deve collidere con pattern validi di:
  - tonalità (`Key`);
  - metro (`Meter`);
  - tempo (`BPM`).

Se una porzione di testo può essere interpretata sia come style sia come
altro elemento strutturato dell’header, **prevale sempre l’interpretazione strutturata**.

In caso di ambiguità non risolvibile, la deduzione dello style fallisce
senza invalidare l’intero header.

---

### 11.3 Key

Forma:

- nota `A–G`;
- alterazione `b` o `#` opzionale;
- maggiore implicita;
- `m` o `-` per il minore.

Valore speciale:

```
X
```

che indica assenza di tonalità, politonalità o atonalità.

---

### 11.4 Meter

Forma frazionaria:

N/D

con `N` e `D` numeri interi di una o due cifre.

Esempi:

```
4/4
3/8
```

È consentita la forma estesa con suddivisione interna del numeratore (clave):

Esempio:

```
[3+3+2]/8
```

---

### 11.5 BPM

- numero intero di due o tre cifre;
- in forma implicita deve essere seguito da `BPM` (case-insensitive);
- in forma esplicita (`HB) `) il suffisso è opzionale;
- non sono ammessi numeri decimali.

Il valore dichiarato nell'header inizializza `currentBPM` e può essere
**sovrascritto localmente** in una qualsiasi misura tramite una play
directive `(=…,Nbpm)` o metric modulation `(=…,figura=figura)` nella
riga `M)` (vedi `neumaRk_play_directive.md`).

### 11.6 Versions

Dichiara le **versioni alternative** del brano. Disponibile solo in
forma **esplicita** (`HV) `).

```
HV) versions: [original, miles, jarrett] default=original
```

- `versions:` parola chiave obbligatoria.
- Lista di label fra parentesi quadre, separate da virgole.
- `default=<label>` opzionale: specifica la variante mostrata alla
  prima apertura del brano.

Vedi `neumaRk_versions.md` per la spec completa dei blocchi
`%%NAME … %%end` e la semantica di sostituzione.

`HV)` è **opzionale**: in sua assenza le versioni sono dedotte
direttamente dai blocchi `%%NAME "label"` presenti nel documento.

---

## 12. Righe vietate e fallimento dell’header

Invalidano l’intero header:

- righe vuote;
- elementi non riconosciuti;
- righe interpretabili come datapack musicale;
- conflitti non risolvibili.

---

## 13. Esempi

```
My Song (John Doe / Jane Roe)
1998 Swing 120BPM 4/4 Dm
```

equivale a

```
HT) My Song
HC) John Doe / Jane Roe
HY) 1998
HS) Swing
HB) 120
HM) 4/4
HK) Dm
```

---

## 14. Note di implementazione

- il parsing dell’header è conservativo;
- non è prevista alcuna correzione automatica;
- non è previsto fallback parziale.


---

# Datapack

## 1. Concetto di datapack

Un **datapack** è l’unità strutturale fondamentale del contenuto musicale in neumaRk.

Rappresenta un **blocco verticale di informazione musicale sincronizzata nel tempo**, tipicamente corrispondente a uno o più righi allineati:

- markers
- accordi
- note
- articolazioni
- dinamiche
- lyrics
- formattazione

Ogni datapack descrive una sequenza temporale coerente (una o più misure consecutive).
I datapack musicali sono separati tra loro da uno o più righi vuoti,
che hanno valore di delimitazione strutturale. La presenza di una riga vuota implica la conlusione del datapack precedente.

---

## 2. Tipi di righe

Ogni riga del datapack ha un **tipo semantico**.

Il tipo può essere:

- **esplicito**, tramite marcatore
- **implicito**, dedotto dal contenuto e dalla posizione

### 2.1 Marcatori espliciti di riga

I marcatori espliciti sono:

- una, due o tre lettere maiuscole
- seguite da `)`
- seguite da uno spazio

| Marcatore | Tipo          |
| --------- | ------------- |
| `M)`      | Markers       |
| `C)`      | Chords        |
| `A)`      | Articulations |
| `N)`      | Notes         |
| `D)`      | Dynamics      |
| `L)`      | Lyrics        |
| `F)`      | Format        |

I marcatori sono opzionali.

Il marker `N)` ammette due varianti morfologiche di 2 caratteri,
previste esplicitamente dalla specifica:

- `N+` — nuovo rigo introdotto in questo datapack (§4.5);
- `N2` — seconda voce sullo stesso rigo (vedi `neumaRk_voices.md`).

La cifra `2` e il segno `+` sostituiscono la `)`, preservando
l'invariante di larghezza a 2 caratteri necessaria all'allineamento
verticale.

Analogamente, il marker `C)` ammette una variante:

- `C+` — riga di accordi **alternativi** sopra la riga base (comment-label
  e scope di riga in `neumaRk_chords.md` §7).

Il segno `+` sostituisce la `)` come in `N+`, preservando la stessa
invariante di larghezza.

---

## 3. Ordine logico delle righe (deduzione implicita)

In assenza di marcatori espliciti, il tipo delle righe viene dedotto seguendo l’ordine logico:

1. **Markers** (al massimo una riga, opzionale)
2. **Chords**
   - zero o più righe
   - l’ultima è considerata la riga principale
3. **Gruppi di note**, ciascuno composto da:
   - una riga di **Articulations** (opzionale, prima)
   - una riga di **Notes** (obbligatoria in assenza di chords)
   - una riga di **Dynamics** (opzionale, dopo — vedi `neumaRk_dynamics.md`)
   - una riga di **Lyrics** (opzionale, ultima)

   Un datapack può contenere **da 1 a 4 gruppi di note**: ogni gruppo
   corrisponde a un rigo del sistema (vedi §4).
4. **Format** (al massimo una riga, opzionale, sempre finale)

---

## 3.bis Deduzione del tipo di riga (algoritmo normativo)

Il §3 dà l'**ordine logico** dei tipi; questa sezione ne formalizza
l'**algoritmo di deduzione**: come, in assenza di marcatore esplicito, il
tipo di una riga è determinato da contenuto + posizione. La regola qui scritta
è **normativa** — è la lingua, non un dettaglio d'implementazione. Un marcatore
esplicito (§2.1) vince sempre: l'algoritmo che segue si applica solo alle righe
**senza marcatore**.

### 3.bis.1 Struttura del datapack

Solo **Markers** e **Chords** sono unici per datapack (sono condivisi
dall'intero sistema, §4.1); tutto il resto è un **gruppo di note ripetuto**,
una volta per (rigo × voce):

```
datapack ::= [Markers]?  Testa  Gruppo{1..8}  [Format]?

Testa    ::= ( [A]? Chord )*        // 0+ chord-row, ognuna eventualmente
                                    //   decorata da un'A) sopra
Gruppo   ::= [A]? N [D]? [L]?       // un (rigo × voce)
```

- **Testa** (Markers + Chords): unica, condivisa. La riga di articolazioni
  può precedere una chord-row per decorarla (una chord-row può portare ritmo
  proprio, `neumaRk_chords.md §4`); per questo `A)` è ammessa **prima** di
  `C)`.
- **Gruppo**: si ripete fino a **8 volte** = max **4 righi** (§4) × **2 voci**
  per rigo (§4.6). La voce 2 **non è deducibile implicitamente** — non esiste
  modo di distinguere dal solo contenuto "voce 2 dello stesso rigo" da "nuovo
  rigo": va sempre dichiarata col marcatore esplicito `N2`. Quindi la
  deduzione *implicita* da sola produce fino a 4 gruppi (i righi); gli 8 si
  raggiungono solo con `N2`.
- **Format**: unica, sempre finale (§9).

### 3.bis.2 Modello di calcolo

La deduzione è un **automa a passo singolo, per-datapack**, che scorre le
righe in ordine di sorgente mantenendo due elementi di stato:

- `lastType` — il tipo dell'ultima riga (init `Empty`);
- `headClosed` — `false` finché non compare la prima riga **Notes** del
  datapack, poi `true` per sempre. Marca il confine fra Testa e Gruppi.

I guard `lastType` **sono la funzione di transizione** dell'automa: codificano
sia l'ordine *dentro* un gruppo, sia il **loop-back** che apre il gruppo
successivo (rientro su `A` o su `N`). `headClosed` impedisce a Chords di
ricomparire una volta entrati nei righi.

### 3.bis.3 Pre-filtro: righe decorative

Prima della cascata, una riga **puramente decorativa** — composta solo da
segni di battuta semplici, `:`, forme compatte di ritornello (`neumaRk_flow_and_repeats.md §6.1`),
punti, spazi e tab — viene **saltata** e non riceve un tipo musicale (resta
strutturale, le sue decorazioni di battuta appartengono semanticamente alle
altre righe). Eccezione: il **rescue `>`/`^`** in §3.bis.6.

### 3.bis.4 Cascata di classificazione (precedenza normativa)

Sulle righe non-decorative senza marcatore, si applica una cascata
**first-match-wins**. L'**ordine è vincolante**: i predicati di contenuto sono
volutamente permissivi e non sovra-matchano *solo* grazie a (a) questo ordine e
(b) la guardia di posizione. Il trittico che definisce ogni tipo è
**predicato + guardia + esclusioni**.

| # | Tipo | Predicato (contenuto) | Guardia (posizione) | Esclusioni |
|---|------|-----------------------|---------------------|------------|
| 1 | **Markers** | solo `[…]` / barline / spazi | è la **prima riga** del datapack | — |
| 2 | **Chords** | ≥1 accordo valido (`neumaRk_chords.md §3`) + barline / `.` / `%` / comment-label / spazi — **oppure** soli `%` (TB1bis) | **testa aperta** (`!headClosed`) | non slash-only (TB2); non rest-only `r`/`!` (TB1) |
| 3 | **Articulations** | charset del vocabolario `A)` (`neumaRk_articulations.md`) | `lastType ≠ Articulations` | non `^`-only (TB3); non notes-line valida (TB4) |
| 4 | **Dynamics** | charset dinamiche (`< > c d f m p s z - . \| :`) | `lastType == Notes` | — |
| 5 | **Lyrics** | word-char + `. - _ ' \| :` (**il più permissivo**) | `lastType ∈ {Notes, Dynamics, Lyrics}` | — |
| 6 | **Notes** | *default / sink* | qualsiasi | — |

Note sulle guardie:

- **Markers** (riga 1): la deduzione *implicita* di Markers avviene **solo
  sulla prima riga** del datapack. Una riga markers-shaped più in basso non è
  Markers (un `M)` esplicito resta possibile ovunque la spec lo consenta).
- **Chords** (riga 2): la condizione normativa è **testa aperta**. Equivale a
  dire che gli accordi vivono solo prima della prima riga di note: gli accordi
  sono unici e condivisi (§4.1), nessun datapack valido ha una chord-row dopo
  una notes-row. Il parser realizza il vincolo col flag posizionale `headClosed`
  (chiuso alla prima riga Notes del datapack) — allineato a §3.bis dal 2026-05-25
  (FU.3a).
- **Lyrics** (riga 5): il predicato è il più permissivo (matcha quasi ogni
  testo). È **intenzionale**: la permissività è contenuta dalla guardia di
  posizione, e in ogni caso il tipo di default è Notes. Non si restringe (sarebbe
  non-monotòno e rischierebbe di cambiare la classificazione di brani esistenti).
- **Default Notes**: la riga 6 è il *sink* — ogni riga che arriva in fondo alla
  cascata è una riga di note. È anche il meccanismo del loop-back: due `N)`
  consecutive (entrambe sink) sono due righi distinti.

### 3.bis.5 Tiebreaker

Tre disambiguazioni risolvono casi in cui un predicato permissivo
matcherebbe il tipo sbagliato:

- **TB1 — rest-only → Notes.** Una riga composta **solo** da rest-token
  (`r` / `!`), barline, `.`, `%` e spazi appartiene allo **stave** (è una riga
  di note di soli silenzi), non a una chord-row vuota. Vale dopo Chords/Alt
  **e dopo Articulations**:

  ```
  A7        ← Chords          | > .       ← Articulations
  r         ← Notes (TB1)     r           ← Notes (TB1)
  ```

  > Realizzato dal 2026-05-25 come regola unica **«rest-only forza Notes»**: la
  > riga è intercettata *prima* di Chords e Articulations, a prescindere da
  > `lastType` (FU.3b dopo Articulations + FU.3c dopo Chords — entrambi davano
  > il tipo sbagliato, rispettivamente chord-row vuota e Articolazioni). Una
  > guardia richiede un rest-token `r`/`!` o `%` reale, così `| > |` (anacrusi)
  > resta gestito dal rescue (§3.bis.6).

- **TB1bis — `%`-only senza chord-row → Chords.** Una riga composta **solo** da
  `%` (più barline, `.`, spazi — **nessun** rest-token `r`/`!`) **in testa
  aperta** (`!headClosed`) e **in assenza di una chord-row reale** nel datapack
  è una **chord-row di sole ripetizioni di misura**: ogni `%` ripete l'ultima
  misura-accordo (anche dal datapack precedente — il lookback dei measure-repeat
  è cross-datapack). È l'eccezione a TB1: i `%` *senza* rest-token non vengono
  forzati a Notes, ma cadono nel ramo Chords (la cui `isChordLine` accetta già
  `%`).

  ```
  | C7 | F7 |     ← Chords
  | a b c | …     ← Notes (chiude la testa)

  | % | % |       ← Chords (TB1bis): ripete C7, F7 dal datapack sopra
  | d e f | …     ← Notes
  ```

  > Decisione **2026-05-26**, *supera* il principio precedente «se vuoi una
  > chord-row di soli `%` devi dichiararla con `C)`». Motivazione: «accordi che
  > si ripetono mentre la melodia cambia» è il pattern di lead-sheet più comune;
  > forzare `C)` su ogni continuazione era attrito gratuito. Due guardie tengono
  > il caso stretto:
  >
  > 1. **niente rest-token** — una riga con `r`/`!` resta sempre Notes (TB1):
  >    i silenzi sono inequivocabilmente note;
  > 2. **`!sawRealChordRow`** — se la testa ha *già* una chord-row con accordo
  >    reale, una riga `%`-only successiva resta Notes (è una notes-row di
  >    ripetizioni), perché la chord-row del datapack è già definita.
  >
  > Escape-hatch per la lettura opposta (un *secondo rigo di note* di soli `%`):
  > marcatore esplicito `N+` / `N)`. Limite noto: un datapack di **soli** `%`
  > (senza alcuna notes-row) viene letto come chord-row e viola la grammatica
  > `(A?ND?L?)+` (serve ≥1 `N`); dichiararlo con `N)` se l'intento è una
  > notes-row standalone di ripetizioni.

- **TB2 — slash-only → Notes.** Una riga di soli `/` standalone (più barline,
  `.`, spazi) è **slash rhythm** (`neumaRk_notes_and_durations.md §10`), mai
  una chord-row: `/` da solo è sintatticamente quasi-accordo ma semanticamente
  un evento di nota.

  ```
  | / / | / / |     ← Notes (TB2)
  ```

- **TB3 — `^`-only → Notes.** Una riga di soli `^` (più `|` e spazi) è una
  riga di note con sole **legature di valore** (`neumaRk_notes_and_durations.md §6`),
  non Articulations.

  ```
  | ^ |     ← Notes (TB3)
  ```

- **TB4 — notes-line valida → Notes.** Una riga che è una **notes-line valida**
  ha priorità sulle Articulations, anche se cade interamente nel charset del
  vocabolario `A)`. Necessario perché alcune lettere del vocabolario sono pure
  note-name/durate: in particolare **`g`** (compone `gl` glissato, §9) è anche
  la nota G, e le durate `1`–`4` stanno nel charset → `g`, `g4`, `g g g`
  matchavano `articulations_line` ed erano rubati ad A).

  ```
  A7        ← Chords
  g         ← Notes (TB4), non Articulations
  ```

  > Predicato: ogni token (split su spazi; le barline `|`/`:` ai bordi sono
  > spogliate) è un note-token valido secondo la grammatica **canonica**
  > `parse_notes` (fonte unica → niente divergenza), e almeno un token porta un
  > pitch reale `[a-g]`/`r`. I token di sola articolazione (`>`, `tr`, `-`, `o`,
  > `gl`, `~`…) **non** matchano `parse_notes` → la riga resta Articulations;
  > una riga di soli `.`/`,`/`^` (placeholder, nessun pitch reale) → resta
  > Articulations. Realizzato 2026-05-26 (`isNotesLineForTiebreak` in
  > `map_functions.cpp`), gate anche sul rescue `>`/`^`/`~` (§3.bis.6). Principio:
  > *in caso di ambiguità A)↔N), vince la nota.*

### 3.bis.6 Rescue `>` / `^`

Una riga che il pre-filtro (§3.bis.3) avrebbe scartato come decorativa — perché
`>` è leggibile come anacrusi attaccata a una barline — ma che contiene `>`
oppure `^` ed è **interamente** charset-articolazioni, viene recuperata come
**Articulations** (qui `>` è un accento, non un'anacrusi):

```
| > |     ← Articulations (rescue): accento sul primo evento della misura
```

Il rescue è un ramo **fuori cascata** e produce sempre Articulations (le
articolazioni possono aprire un gruppo in qualsiasi posizione); è soggetto allo
stesso vincolo `lastType ≠ Articulations` e all'esclusione `^`-only (TB3).

> **Prima riga del datapack.** Il rescue presuppone un contesto a monte. In
> prima posizione (`line_id == 0`) una riga `| > |` è letta come
> **Markers/anacrusi**, non come accento: il pre-filtro Markers (cascata riga 1)
> ha precedenza e `>` è ambiguo fra accento e levare quando non c'è una riga di
> note sotto a disambiguarlo. È una scelta consapevole (decisione 2026-05-25):
> in assenza di contesto la lettura anacrusi prevale.

### 3.bis.7 Post-pass: promozione AlternateChords

La classificazione di base assegna **Chords** a tutte le chord-row implicite.
Una pass successiva rietichetta come **AlternateChords** (`C+`, accordi
alternativi sopra la base) le chord-row consecutive che precedono l'ultima,
**solo** se nessuna chord-row del datapack porta un marcatore esplicito (se
l'utente ha scelto i marcatori, la sua scelta è rispettata). Limite: max 2 righe
alternative per datapack (**E127**). Spec completa in
`docs/feature-alternate-chords.md` e `neumaRk_chords.md §7`.

### 3.bis.8 Derivazioni e vincolo

- Il **charset di `articulations_line`** (riga 3) **deriva** dal vocabolario
  chiuso di `neumaRk_articulations.md` (fonte unica): la deduzione e la
  semantica del renderer non devono divergere.
- **Invariante**: l'algoritmo può solo essere **esteso** verso quanto qui
  scritto, mai cambiare in silenzio una mappatura riga→tipo esistente. Le
  divergenze parser↔spec sulla classificazione (FU.3a *testa chiusa*, FU.3b
  *rest-only dopo `A)`*, FU.3c *rest-only dopo Chords*) sono state **chiuse il
  2026-05-25**, verificate per differenza sulla batteria "classification golden"
  (`wasm/tests/fixtures/classify_*`). Resta aperto **FU.1** (charset
  articolazioni dal vocabolario chiuso), che non cambia la mappatura riga→tipo.
- **Cambio di mappatura 2026-05-26 (TB1bis)**: la riga `%`-only senza rest-token
  in testa aperta e senza chord-row reale passa da **Notes** a **Chords**
  (§3.bis.5 TB1bis). È un cambio *deliberato e documentato* della mappatura, non
  silenzioso — ammesso perché il linguaggio non è ancora diffuso (nessun bump di
  versione). Coperto dai golden `classify_pct_only_chords` (promozione) e
  `classify_pct_after_real_chords` (guardia `sawRealChordRow`).
- **Correzione 2026-05-26 (TB4)**: la riga che è una notes-line valida ma cade
  nel charset `A)` (tipicamente le righe di sola nota **`g`**: `g`, `g4`,
  `g g g`) passa da **Articulations** a **Notes** (§3.bis.5 TB4). È un bug-fix
  verso il comportamento corretto («vince la nota»), non un'estensione
  controversa. Coperto dai golden `classify_note_g_after_chords` e
  `classify_note_g_vs_artic` (con negativo `> . . .` → resta Articulations).

---

## 4. Più righi per datapack (multi-stave)

Un datapack può rappresentare un **sistema con più righi allineati**
(es. melodia + basso). Il numero di righi è dato dal **numero di gruppi
di note** (`A?ND?L?`) presenti, fino a un massimo di **4**.

Il numero di righi può **variare da un datapack all’altro** nello stesso
brano: un datapack può contenere un solo rigo e quello successivo due o
più, senza dichiarazioni preventive.

### 4.1 Elementi condivisi dal sistema

I seguenti elementi sono **comuni a tutti i righi** del datapack:

- riga di **Markers**
- riga(he) di **Chords**
- **segni di battuta** e **decoratori di misura** (volte, cambio di
  metro/tonalità, `$`, `@`, `DC`, `FINE`, ecc.)
- tonalità e metro del sistema

Le stanghette di misura attraversano verticalmente tutti i righi.

### 4.2 Elementi indipendenti per rigo

Ogni gruppo `(A?ND?L?)` definisce un rigo indipendente con propri:

- **Notes** (obbligatorie)
- **Articulations**, **Dynamics**, **Lyrics** (opzionali)
- **chiave** dichiarata via direttiva inline `(@…)` come primo token
  della riga di Notes — vedi `neumaRk_notes_and_durations.md` §9. In
  assenza di direttiva, vale l’ultima chiave definita nel contesto
  (default: chiave di violino).
- legature, travi e gruppi irregolari (tutti contenuti nel rigo)

### 4.3 Allineamento orizzontale

Tutti i righi del sistema devono contenere lo **stesso numero di
misure**: l’allineamento verticale fra righi è temporale.

### 4.4 Esempio

```
C) | Gm6 |
N) | g | a | bb | a |
N) | (@F) g,4 bb8 d e4 d | g,4 bb8 d e4 d | g,4 bb8 d e4 d | g,4 bb8 d e4 d |
```

Sistema a 2 righi: il primo in chiave di violino (default), il secondo
in chiave di basso. L’accordo `Gm6` è comune al sistema.

---

### 4.5 Continuità degli stave fra datapack (`N+`)

Quando un brano ha più datapack, ogni rigo (stave) ha una **identità
persistente**: il "primo rigo" di un datapack è lo stesso "primo rigo"
del precedente — eredita pitch context, chiave in vigore, durCtx, e
viene reso nella stessa posizione verticale.

L'identità di base è **posizionale**: la prima `N)` del datapack
corrisponde alla prima `N)` del datapack precedente, la seconda alla
seconda, e così via.

Per **aggiungere un nuovo rigo** in un datapack senza romperne
l'identità con i precedenti, si usa il marker `N+` al posto di `N)`.

```
N+   <contenuto del rigo nuovo>
```

Il `+` sostituisce la `)` (non la aggiunge): il prefisso resta a 2
caratteri come `N)`, così l'allineamento verticale delle misure resta
identico fra righi adiacenti.

#### Regole

- `N)` = **continuazione** del prossimo rigo del datapack precedente
  (FIFO, in source order). Ne eredita il context (pitch, chiave,
  durata).
- `N+` = **nuovo rigo** introdotto in questo datapack. Parte con
  context fresh (riferimento di orientamento dipende dalla chiave
  iniziale, vedi `neumaRk_notes_and_durations.md` §2.2).
- L'**ordine in source = ordine visuale** top→bottom. Il marker `N+`
  determina solo l'identità (nuovo vs. continuazione), non la
  posizione.
- `N+` nel **primo datapack** del brano è ammesso ma ridondante (in
  assenza di precedenti tutti i righi sono per forza nuovi); viene
  trattato come un normale `N)`.
- **Limite invariato:** max 4 righi totali per datapack (somma di `N)`
  + `N+`).

#### Errori

- **E122** — `N) senza match`: il datapack ha più `N)` di quanti
  righi avesse il precedente. Mancano `N+` (o un `N)` di troppo).

#### Esempio

Datapack 1 (intro a 2 righi, treble + bass):

```
M) [intro]
C) G7
N) |: <d b>2 <e c>4 | <f d>2 <e c>4 :|
N) (@F) g,4. d'8 e d | f4. d8 e d
```

Datapack 2 (Theme): aggiunge un terzo rigo **in alto** (melodia di
voce), mantenendo treble e bass dell'intro al centro e in basso.

```
M) [Theme]
C) > | G7
N+ >  d8 | b'^ | b2 r8 d,
A) >    | . ! | . !
N) > |: <d b>2 <e c>4 | <f d>2 <e c>4 :|
N) > | g,4. d'8 e d   | f4. d8 e d
```

Mapping risultante (per l'engine, non visibile in source):

| source row | tipo  | identità                         |
|------------|-------|----------------------------------|
| 1 (`N+`)   | nuovo | nuovo stave (top)                |
| 2 (`N)`)   | cont. | = primo rigo intro (treble)      |
| 3 (`N)`)   | cont. | = secondo rigo intro (bass)      |

Il context (last_pitch, chiave, durCtx) dei righi 2 e 3 del Theme
viene dai righi 1 e 2 dell'intro; il rigo 1 del Theme parte fresh.

#### Casi non coperti

La sintassi `N)`/`N+` esprime la situazione comune *"aggiungo un
rigo in cima/in mezzo/in fondo"*, ma non copre:

- **drop selettivo** (datapack che mantiene il 2° rigo del precedente
  ma droppa il 1°);
- **reorder** (scambiare l'ordine visuale di righi esistenti, mantenendone
  l'identità).

Per questi casi una futura estensione potrebbe introdurre un riferimento
esplicito all'ID interno del rigo (es. `N<n>)`). Non spec'd in questa
versione.

---

### 4.6 Seconda voce per rigo (`N2`)

Ogni rigo può ospitare una **seconda voce** indipendente, introdotta
dalla riga `N2`. Stave e voce sono concetti distinti: il rigo è il
pentagramma, la voce è uno stream musicale all'interno del rigo.

La voce 2 condivide chiave, tonalità, metro, stanghette e riga degli
accordi con la voce 1, ma mantiene contesto musicale persistente
indipendente. Voce 1 ha gambi in alto, voce 2 in basso.

La specifica completa di sintassi, contesto, binding e diagnostica
è in **`neumaRk_voices.md`**.

---

## 5. Regole di validità del datapack

Un datapack è valido se:

- contiene **almeno una riga di Notes o una riga di Chords**
- rispetta l’ordine logico delle righe
- tutte le righe musicali sono **temporalmente allineabili**

Non è valido:

- un datapack con sole righe di testo
- un datapack con una riga di Format non finale

---

## 6. Segni di battuta e misure

Tutte le righe musicali (Markers, Chords, Articulations, Notes, Dynamics, Lyrics):

- contengono segni di battuta — semplici e composti — ed eventuali decoratori di misura (in assenza di barline tutto il contenuto apparterrà alla prima misura del rigo)
- definiscono implicitamente la suddivisione in misure

La riga di **Format** è l'unica eccezione: non ammette segni di battuta (né semplici né composti) e nessun decoratore di misura.

### 6.1 Segni di battuta supportati

I segni di battuta ammessi sono:

- `|` battuta semplice
- `||` doppia barra
- `|.` o `.|` fine
- `|:` inizio ripetizione
- `:|` fine ripetizione

Il **segno finale di battuta** deve essere preceduto da uno spazio.

---

## 7. Decoratori di misura

I decoratori di misura sono elementi **adiacenti a una barline** e si dividono in:

- **BEGIN decorators** (a destra della barline)
- **END decorators** (a sinistra della barline)

### 7.1 BEGIN decorators

Posizionati immediatamente a destra della barline.

Possibili decoratori:

- **Cambio di metro e/o tonalità**

  - fra parentesi tonde
  - separati da virgola
  - ordine arbitrario

  Esempi:

  ```
  |(3/4,Dm)
  |([3+3+2]/8)
  ```

- **Volta endings**

  - testo fra parentesi quadre
  - opzionale `+n` per la durata in misure

  Esempio:

  ```
  |[1.]+4
  ```

  In assenza di `+n`, la volta si chiude **automaticamente** al primo `:|`
  incontrato entro **4 battute** (caso tipico dei finali `[1.]`).
  Se nelle 4 battute successive non compare un `:|`, la volta indica
  un'**uscita** — usare `+n` per i casi non standard.

- `$` segno
- `@` coda

Se presenti, **metro e tonalità devono precedere** ogni altro decoratore BEGIN.

---

### 7.2 END decorators

Posizionati immediatamente a sinistra della barline.

Decoratori supportati:

- `DC`
- `DCal@`
- `DCalFINE`
- `D$`
- `D$al@`
- `D$alFINE`
- `FINE`
- `al@`
- testo libero fra parentesi quadre (annotazione grafica)

I segni `$` e `@` sono **BEGIN decorator** (vedi §7.1): identificano il punto in cui il segno o la coda si trova, non un salto verso di essi.

---

## 8. Riga di Markers

La riga di **Markers**:

- contiene marcatori racchiusi fra parentesi quadre
- i marker si riferiscono **all’inizio della battuta**

Se un marker è preceduto da una barline:

- deve esserci **uno spazio** fra barline e marker
- per evitare ambiguità con i volta-decorators

È **best practice** collocare i decoratori di flusso (DC, D$, coda, ecc.) in questa riga.

---

## 9. Riga di Format

La riga di **Format** può essere dichiarata:

- in forma esplicita, tramite il marcatore `F)`;
- in forma implicita, se il contenuto della riga è riconoscibile
  univocamente come riga di format.

La riga di Format, se presente, deve essere:

- unica per datapack;
- sempre l’ultima riga del datapack.

In caso di ambiguità con una riga musicale, prevale sempre
l’interpretazione musicale e la riga non viene considerata Format.

Contiene indicazioni di allineamento:

| Simbolo | Allineamento        |
| ------- | ------------------- |
| `\|*`   | LEFT                |
| `*\|`   | RIGHT               |
| `\|*\|` | CENTER              |
| `\|**\|` | JUSTIFIED (default) |

---

## 10. Margini fra datapack

Una riga:

- che segue una riga vuota
- che inizia con `-`
- che contiene solo `-`, spazi, tab o `%`

indica un **margine verticale** fra datapack.

La profondità del margine è data dal massimo numero di `-` consecutivi:

- `- - -` → margine 1
- `- -- -` → margine 2
- `--- -` → margine 3

Il simbolo `%` indica un **possibile page break**.

## 11. Commenti

Sono permessi commenti single-line nella forma `// comment`. Lo scope è la riga: tutto ciò che segue `//` fino al newline viene ignorato dal parser. I commenti possono stare su riga propria (sopra/sotto un datapack, o tra le righe di un datapack) oppure a fine riga di una riga di codice.

Il discriminante fra le due forme è **posizionale**: se prima di `//` c'è almeno un carattere non-whitespace, il commento è **trailing** (la parte di codice prima di `//` resta valida); altrimenti l'**intera riga** è commento.

I commenti multi-riga (`/* … */`) non sono supportati: NRK è un linguaggio column-sensitive (le `|` di battuta allineano verticalmente le righe del datapack) e i block comments romperebbero l'allineamento.

La sequenza `%%` ad inizio riga **non è un commento**: è riservata per i blocchi di versione del brano (vedi `neumaRk_versions.md`).

---

## 12. Blocchi di versione

Fra un datapack e l'altro possono comparire **blocchi di versione**, marcati `%%NAME … %%end`, che racchiudono uno o più datapack alternativi del brano. I blocchi vivono standalone fra datapack, non al loro interno. Vedi `neumaRk_versions.md` per la spec completa.


---

# Note e Durate

Questo documento definisce la sintassi e la semantica delle **note musicali** in neumaRk: altezze (pitch), accidenti, durate, prolungamenti e meccanismi di deduzione implicita.

L’obiettivo è fornire una specifica **deterministica**, ma compatibile con la scrittura rapida in modalità informale.

---

## 1. Evento nota

Un **evento nota** è l’unità musicale atomica nella riga `N)` di neumaRk.

Ogni evento nota rappresenta un accadimento musicale puntuale nel tempo
e contribuisce alla costruzione della sequenza ritmica e melodica del brano.

Un evento nota può specificare, in forma esplicita o implicita:

- un’altezza (pitch);
- una durata;
- modificatori di durata;
- modificatori di ottava;
- annotazioni;
- legature di valore.

Alcuni di questi elementi possono essere omessi, purché possano essere
dedotti in modo deterministico dal **contesto musicale persistente**,
secondo le regole definite in questo documento.

### Continuità della deduzione

La deduzione di altezze e durate in neumaRk si basa sull’ultimo valore
esplicito incontrato **nell’intero documento**, e non è limitata al singolo
rigo di note o al singolo datapack.

All’inizio di un nuovo datapack musicale, il riferimento per la deduzione
delle altezze e delle durate è l’ultimo evento nota del datapack precedente,
se presente.

In assenza di qualunque riferimento precedente (ad esempio all’inizio del
brano), la deduzione utilizza i valori di default definiti dalla specifica,
oppure fallisce nei casi in cui non sia possibile una deduzione deterministica.

---

### 1.1 Struttura sintattica dell’evento nota

Un evento nota è costituito da una **sequenza ordinata di elementi adiacenti**,
senza spazi intermedi.

L’ordine degli elementi è **fisso** e deve essere il seguente:

1. **Legatura alla nota precedente** (`^`), opzionale
2. **Altezza (pitch)**, opzionale perché deducibile
3. **Forzatura di accidente** (`!`), opzionale  
   (ammessa solo se l’altezza è esplicitamente indicata)
4. **Modificatori di ottava**, opzionali  
   (ottave relative tramite `'` o `,`, oppure ottava assoluta)
5. **Durata**, opzionale
   - durata esplicita (numero potenza di 2, con eventuali punti o moltiplicatori);
   - indicatori di tuplet;
   - oppure `?` per durata sconosciuta
6. **Annotazioni**, opzionali, fra doppi apici
7. **Legatura alla nota successiva** (`^`), opzionale

Tutti gli elementi che compongono un evento nota **devono essere adiacenti**.
La presenza di uno spazio separa eventi nota distinti.

> **Gruppi fra parentesi tonde `(…)`.** Oltre alla durata esplicita in lista
> (`r(…)`, suffisso) e al cambio di chiave (`(@…)`, prefisso), un evento nota può
> portare gruppi `(…)` aggiuntivi che ne specificano la **testa** o un **glissato
> ornamentale**. Il loro significato si determina per contenuto e posizione: vedi
> la regola unica in §11. Al massimo per nota: una chiave (prefisso), un
> glissato-in (prefisso), un notehead (suffisso), un glissato-out (suffisso).

Un evento nota può omettere uno o più elementi secondo le regole di deduzione
definite in questo documento, ma **l’ordine relativo degli elementi non può
mai essere alterato**.

---

#### Eventi nota costituiti da un singolo simbolo

È ammesso un evento nota costituito esclusivamente da un singolo simbolo,
senza indicazione esplicita di pitch o durata, purché esista un contesto
musicale precedente valido.

I seguenti simboli possono costituire da soli un evento nota valido:

- **Modificatori di ottava** (`'` o `,`)
- **Legatura di valore** (`^`)

In tali casi, l’evento nota:

- eredita il **pitch** dall’evento nota precedente;
- eredita la **durata** dall’evento nota precedente;
- applica esclusivamente la semantica del simbolo indicato.

In particolare:

- un evento costituito da `'` o `,` modifica l’ottava del pitch ereditato;
- un evento costituito da `^` prolunga la nota precedente **dello stesso valore**.

Un evento nota costituito da un singolo simbolo è valido **solo se**
pitch e durata possono essere dedotti in modo deterministico dal contesto.
In assenza di tale contesto (ad esempio all’inizio del brano),
l’evento non è valido.

---

## 2. Pitch (altezza)

### 2.1 Sintassi di base

Un pitch è espresso come:

```
<nota>[alterazione][ottava]
```

Dove:

- `nota` ∈ `{a b c d e f g}`
- `alterazione` ∈ `{#, b}` (opzionale, anche doppi)
- `cambio di ottava` (opzionale, vedi il prossimo paragrafo)

Esempi:

```
c   d#   fb   g##
```

---

### 2.2 Ottave relative

Il calcolo dell'ottava viene fatto in base all'altezza della nota precedente, considerando l'intervallo meno ampio da essa.

Esempi:

```
f4 bb f c
```

Il carattere `'` subito dopo l'altezza della nota, ne sposta l'ottava in senso ascendente.
Il carattere `,` subito dopo l'altezza della nota, ne sposta l'ottava in senso discendente.

Esempi:

```
f4 bb, f' c'
```

Sono permessi più segni consecutivi per il cambio di ottava.

Esempi:

```
a,4 g''' a,,,
```

All'inizio del brano (o all'inizio di uno stave, in un datapack
multi-rigo) l'altezza di orientamento è la **nota marcata dalla
chiave di partenza**: chiavi in G usano un riferimento `g`, chiavi
in F un riferimento `f`, chiavi in C un riferimento `c`.

In dettaglio, per le chiavi previste da neumaRk:

| Chiave                          | Notazione               | Riferimento |
|---------------------------------|-------------------------|-------------|
| violino                         | `(@G)`                  | **g4**      |
| violino 8va alta                | `(@G8va)`               | **g5**      |
| violino 8va bassa               | `(@G8vb)`               | **g3**      |
| soprano                         | `(@C1)`                 | **c4**      |
| mezzo-soprano                   | `(@C2)`                 | **c4**      |
| contralto                       | `(@C3)`                 | **c4**      |
| tenore                          | `(@C4)`                 | **c4**      |
| baritono (variante in do)       | `(@C5)`                 | **c4**      |
| baritono (variante in fa)       | `(@F3)`                 | **f3**      |
| basso                           | `(@F)` o `(@F4)`        | **f3**      |
| basso 8va bassa                 | `(@F8)` o `(@F8vb)`     | **f2**      |

> **Solo la chiave dichiarata all'inizio** (del brano o del rigo)
> determina il riferimento di orientamento. Un eventuale cambio
> di chiave successivo (vedi §9) modifica la chiave grafica e la
> resa visiva delle note, ma **non** altera il riferimento usato
> per il calcolo delle ottave relative.

---

### 2.3 Ottave assolute

È comunque possibile affermare l'ottava assoluta di una nota aggiungendo
il carattere `@` seguito dal numero dell'ottava (4 per il do centrale)
e dal carattere `_`. La numerazione è quella scientifica: C-1 è il
MIDI 0, C9 è il MIDI 120; il range pratico utile è circa `-1`..`9`.

Esempi:

```
c@4_8. g@3_2
```

> **La durata è obbligatoria** quando si usa `@<n>_`: il `_` funge da
> separatore tra il numero d'ottava e il valore di durata, ed è privo
> di significato senza un valore che lo segua. Una scrittura come
> `c@4_` (senza durata) produce errore **E008**.

`'`/`,` restano ammessi come "nudge" sopra l'ottava assoluta — `c@4_'`
equivale a C5, `c@4_,8` equivale a C3 da ottavo. Sono sconsigliati
perché ridondanti: usare direttamente `c@5_` / `c@3_8`.

Dopo una nota con ottava assoluta, l'inferenza per gli eventi successivi
riparte da quella nota come `last_pitch` standard (intervallo minimo
via DIATONIC_MATRIX, come in §2.2).

**Ottava assoluta in chord-stack `<…>`**

Dentro un chord-stack, l'ottava assoluta è ammessa **soltanto sulla
prima pitch**, nella forma:

```
<a@4_ c>4
```

Vincoli obbligatori:

1. il `_` che chiude `@<n>_` sulla prima pitch è **obbligatorio** (è
   il separatore richiesto dalla notazione);
2. la **durata dell'accordo dopo `>` è obbligatoria** (es. `>4`).
   La durata vive fuori dalle graffe e si riferisce a tutto l'accordo;
   omettendola si ricade nello stesso errore **E008** del caso
   monofonico, perché internamente il token viene riformulato come
   `a@4_4` (prima pitch + durata) e quel `_` resta senza un valore
   numerico che lo segua.

Le pitch successive del chord-stack (le "extras") accettano per ora
solo notazione relativa: la loro ottava è inferita per intervallo
minimo a partire dalla pitch primaria (vedi §2.2). Una scrittura
come `<a@4_ c@5_>4` non è supportata; vedi backlog per estensione
futura agli extras.

---

### 2.4 Pitch implicito

Se una nota **non specifica un pitch**, essa erediterà l'ultimo
pitch incontrato nel parsing; se nessun pitch è ancora stato
visto, si usa il **riferimento di orientamento iniziale** definito
in §2.2 (`g4` per chiave di violino, `f3` per chiave di basso,
`c4` per chiavi in do, ecc.).

Esempio:

```
f4 8 8 g 4 8
```

---

### 2.5 Accidenti forzati

Il carattere `!` immediatamente dopo il pitch **forza la visualizzazione dell’accidente**, anche se sarebbe implicitamente deducibile dalla tonalità.

Esempio:

```
f#!8
```

Questo indica che l’accidente `#` deve essere mostrato graficamente.

#### 2.5.1 Propagazione degli accidenti entro la misura

Un accidente, una volta mostrato, **propaga** secondo la convenzione standard
fino alla fine della misura. La regola è modellata da una **matrice
`[lettera][ottava]`** che memorizza l'inflessione attiva per ogni coppia
lettera+ottava; la matrice è **inizializzata dalla tonalità** all'inizio di ogni
misura (e di ogni rigo).

- Una nota mostra il proprio simbolo di accidente **solo se** la sua inflessione
  **differisce** dal valore corrente in matrice per quella lettera+ottava (oppure
  se forzata con `!`, §2.5); altrimenti **nessun simbolo**. Quando il simbolo è
  mostrato, la matrice viene **aggiornata**.
- La propagazione è **per-ottava**: un accidente su `c` (ottava 4) **non**
  influenza `c` di un'altra ottava (`c5`). Ogni coppia lettera+ottava è
  indipendente.
- **Chord-stack** (§2.6): ogni pitch dello stack è valutata singolarmente vs la
  matrice.
- **Voce 2** (`N2`): ha matrice di propagazione indipendente dalla voce 1.
- **Grace notes** (precedono la main): sono valutate vs la matrice ma **non la
  aggiornano**; se una grace devia dalla matrice, **rompe la propagazione** per
  quella lettera+ottava → le main successive della stessa misura mostrano un
  accidente esplicito anche se coincidono con la matrice (così il lettore non è
  ingannato dall'inflessione introdotta dalla grace). Vedi
  `neumaRk_grace_notes.md §8`.

---

### 2.6 Accordi impilati (chord-stack) `<…>`

Più altezze suonate insieme si scrivono fra parentesi angolari come **un unico
evento**: `<p1 p2 …>` seguito da una durata.

```
N) <c e g>4 .          do maggiore tenuto per due quarti
N) <f c'> f            bicordo + fa al canto
```

**Sintassi interna.** Le pitch dentro `<…>` sono separate da spazio; ognuna usa
la sintassi delle note (lettera + accidente + `'`/`,` per le ottave). Le ottave
si inferiscono **a cascata**: la prima pitch dalla nota precedente *fuori* dallo
stack, ciascuna successiva dalla precedente *dentro* lo stack (intervallo minimo,
§2.2). L'ottava assoluta è ammessa solo sulla prima pitch (§2.3).

**Durata.** Sta **fuori** dalle angolari, dopo `>` (`<c e g>4`), e vale per
l'intero accordo. Se omessa, l'evento eredita la durata dal contesto come una
nota normale (`<c e g> .`).

**Un solo evento.** Il chord-stack conta come **un** evento nell'allineamento
count-based con le righe `A)`/`D)`/`L)`.

**Legatura `^`.** Vale per l'intero evento; in resa lega i tasti corrispondenti
per indice (`<c e>4^ <c e>4` → due legature).

**Ancoraggio primario (regola normativa).** L'evento **successivo** allo stack
inferisce altezza e ottava dalla **prima** pitch dello stack, **non** dall'ultima.
Internamente lo stack mantiene la cascata; verso l'esterno conta solo la primaria.

```
N) <c e g>^ <c e g>     due accordi identici (senza la regola il 2º salirebbe d'ottava)
N) <f c'> f             il 2º f resta all'ottava del primo f della triade
N) <f bb, d> f          triade di Sib con fa al canto; f successivo = primo dello stack
```

**Errori e limiti.**

- `<>` vuoto o `<…` non chiuso → **E001** (token malformato).
- Stack attaccato alla nota seguente senza spazio (`<c e g>e4`) → **E001**;
  rimedio: aggiungere lo spazio.
- `r` (rest) e `s` (spacer, §14) **non sono validi** dentro uno stack;
  attualmente sono ignorati in silenzio (candidato a un diagnostic futuro).

> Il `>` che **chiude** uno stack appartiene al token: non è mai una stanghetta
> né un'anacrusi (§7), anche quando è seguito da una pitch (`<c e g> e4`).
> Analogamente la `|` interna a un polychord `[top|bottom]` è il separatore del
> polychord, non una stanghetta (`neumaRk_chords.md §7.2`).

---

## 3. Durata

### 3.1 Durata esplicita

La durata può essere indicata subito dopo il pitch:

```
c4   d8   e16
```

I valori ammessi sono quelli standard della notazione musicale (unità con denominatore basato su potenze del 2):
1 => semibreve
2 => minima
4 => semiminima
8 => croma
16 => semicroma
32 => biscroma

---

### 3.2 Gruppi irregolari (tuplet)

Una durata può essere seguita dalla lettera `t` che indica un valore di tuplet.
Se non ci sono altri caratteri a completamento, s'intenderà un a tuplet con rapporto 3:2 (terzina).
Se la lettera `t` è seguita da n:n il gruppo irregolare sarà basato su quel rapporto (es 5:3, 7:8).
La seconda parte del rapporto può essere omessa nei casi più frequenti:
t4 equivale a t4:3
t5 equivale a t5:4
t7 equivale a t7:4

#### 3.2.1 Eredità della ratio nel gruppo

Una nota **senza marcatore di tuplet** che segue una nota tuplet, mentre il
gruppo è **ancora aperto** (non ha raggiunto un ciclo completo del rapporto),
**eredita** la ratio del gruppo corrente (`t_num:t_den`). Solo la **prima** nota
del gruppo deve portare il marcatore; le successive lo ereditano fino a chiusura.

```
N) c8t d e | …      # d, e ereditano la terzina 3:2 aperta da c8t
```

#### 3.2.2 Gruppo irregolare incompleto a fine misura

Se a fine misura un gruppo irregolare resta **aperto** (la somma delle sue unità
non raggiunge un ciclo completo del rapporto), l'autofill lo **completa con
pause** della stessa unità di tuplet (lo stesso `base_dur` dell'ultima nota del
gruppo), finché il gruppo si chiude o la misura è piena.

- Se la chiusura riesce, **nessun diagnostic** (è il caso tipico del round-trip
  di una terzina completa il cui rest finale era stato omesso).
- Se l'autofill **non** riesce a chiudere il gruppo, viene emesso **W002**
  («Tuplet not closed before measure end; auto-filled with 1/64 rests»).

---

### 3.3 Durata implicita

Se una nota **non specifica una durata**, valgono le seguenti regole, in ordine di priorità:

1. se è l’unica nota della battuta, essa occupa l’intera durata della battuta;
2. viene usata l’ultima durata esplicita incontrata nel contesto musicale;
3. se è all’inizio del brano e non esiste alcun riferimento precedente,
   la durata è considerata sconosciuta (`?`).

La regola della nota unica che occupa l’intera battuta
ha **priorità superiore a tutte le altre forme di deduzione**,
incluse quelle basate sul contesto musicale persistente.

#### 3.3.1 Riconciliazione con la durata della misura (algoritmo normativo)

Una volta attribuita a ogni evento una durata (esplicita o ereditata), la somma
della misura può non coincidere con la durata del metro. La riconciliazione segue
un algoritmo deterministico. Ogni evento è prima **classificato**:

- **esplicito** — durata scritta nell'evento. *In anacrusi* (§7) con più di una
  nota, **tutti** gli eventi sono trattati come espliciti (l'anacrusi non riempie
  la misura, quindi non si redistribuisce);
- **sconosciuto** — durata `?` (§3.4);
- **implicito** — durata ereditata dal contesto. Solo gli impliciti **in coda**
  (la sequenza di impliciti dopo l'ultimo esplicito) partecipano alla
  redistribuzione.

> **Invariante**: le durate **esplicite non vengono mai modificate** dalla
> riconciliazione. Si toccano solo gli impliciti in coda, gli `?`, o si aggiunge
> una pausa finale.

**Caso A — nessun `?` (tutte le durate note).** Sia `S` la somma della misura e
`M` la durata del metro:

1. `S ≈ M` (entro tolleranza) → la misura è valida, nessuna azione.
2. `S > M` (**eccesso**):
   - se esistono impliciti in coda e la durata ricalcolata
     `(M − S + somma_impliciti_coda) / numero_impliciti_coda` cade su un **valore
     ritmico rappresentabile** (potenza di 2 con da 0 a 3 punti) → **redistribuzione
     silenziosa** su quegli impliciti. Idioma tipico: `c2 d e` in 4/4 → `d`/`e`
     ereditano la minima (totale 1½ semibrevi), vengono compressi a semiminime;
   - altrimenti è un **eccesso reale** → errore **E005** (durata oltre il metro),
     misura marcata non valida, troncamento delle note finali finché la misura
     rientra, più un'eventuale pausa finale di riempimento. Copre sia l'eccesso
     puramente esplicito (`4 4 4 4 4` in 4/4) sia l'eccesso implicito non
     rappresentabile.
3. `S < M` (**difetto**):
   - se una tuplet è rimasta aperta, viene prima completata (§3.2.2);
   - poi la durata residua è riempita con una **pausa finale**. È **autofill
     standard NRK**: **nessun diagnostic** (il vecchio W001 è stato ritirato).

**Caso B — misto (`?` insieme a durate note).** La durata residua `M − S` è
ripartita **equamente** fra i soli eventi `?` (vedi §3.4); non si aggiunge pausa
finale (gli `?` assorbono il residuo).

---

### 3.4 Durata sconosciuta (`?`)

Indicando `?` come durata, il valore è considerato **indeterminato**.

Il valore mancante per completare la misura viene ripartito equamente fra tutte le note con durata `?`.

Esempio:

```
c? d? e?
```

in una misura di 4/4 individuerà una terzina di minime.

---

## 4. Prolungamenti di durata

#### N.B.

Il significato del punto (`.`) è specifico del contesto delle righe di note
e non coincide con quello utilizzato nelle righe di accordi.
Il carattere punto assume significati differenti a seconda della sua posizione **adiacente** o **distanziata** all'evento nota.

### 4.1 Punto adiacente

Un punto immediatamente adiacente al valore prolunga la durata della **metà del valore precedente**, come nella notazione standard:

```
g4.
```

---

### 4.2 Punto distanziato

Un punto separato da spazio prolunga la durata **dello stesso valore**, e può essere ripetuto:

```
g8 . .
g8 ..
```

individuerà una durata di tre crome.

Conta solo lo spazio dopo la nota, non fra i punti: entrambe le forme sono equivalenti.

---

### 4.3 Moltiplicatori

Un moltiplicatore esplicito può essere indicato come:

```
g16*5
g16x5
```

individuerà una durata pari a 5/16.
Entrambe le forme sono equivalenti.

---

## 5. Ripetizione (`!`)

Il punto esclamativo (distanziato dall'evento nota) ripete la **stessa nota e la stessa durata**:

```
g8 !!!
```

Equivale a:

```
g8 g8 g8 g8
```

È possibile combinare `.` e `!`.

---

## 6. Legatura di valore (`^`)

Il simbolo `^` indica una legatura di valore (tie).

- se adiacente a un evento nota, subito dopo di esso, esso lega con la nota successiva
- se adiacente a un evento nota, precedendolo, esso lega con la nota precedente
- se isolato, equivale a un punto (`.`)
- se è l’unico segno nella battuta, lega con una nota che riempie la battuta

**Accidenti attraverso la legatura.** Una nota legata alla precedente segue due
regimi rispetto alla propagazione (§2.5.1):

- **continuazione naturale** — stesso spelling (es. `eb ^eb`): **nessun simbolo**
  di accidente (la legatura grafica esprime la continuazione), ma la nota
  **semina** comunque la matrice, così che note successive con la stessa
  lettera+ottava ma inflessione diversa mostrino l'accidente esplicito;
- **respelling enarmonico** — lettera/inflessione diverse attraverso la legatura
  (es. `eb ^d#`): la seconda nota è trattata come una nota nuova e **mostra**
  l'accidente, perché è la prima volta che quella lettera compare nella misura.

---

## 7. Anacrusi

L’anacrusi (battuta in levare) è introdotta dal segno `>` come **marcatore di
barline iniziale** della prima misura:

```
N) > c8 d | e4 e e e | …      # levare di due crome prima della misura 1
```

Regole:

- **Dove vale.** `>` è anacrusi **solo** in una riga di note o accordi (C/N). In
  `A)` è accento, in `D)` decrescendo, in `M)`/`L)` testo (vedi
  `neumaRk_datapack.md §3.bis` per il filtro di classificazione). Il `>` è
  riconosciuto come anacrusi solo se **seguito da contenuto** (pitch / `<` /
  barline), così un `>` finale d'accento non viene confuso.
- **Misura non contata.** La misura d'anacrusi **non** entra nella numerazione
  delle misure.
- **Durate esplicite.** In una misura d'anacrusi con più di una nota, tutti gli
  eventi sono trattati come **espliciti**: l'anacrusi è parziale per definizione,
  quindi non si redistribuisce per riempirla (§3.3.1). Le durate implicite si
  calcolano solo in base all'ultimo valore esplicito ricevuto.
- **Pausa di completamento all'inizio.** Se la misura d'anacrusi è più corta della
  misura piena, la pausa di completamento è aggiunta **in testa** (non in coda),
  così gli eventi si allineano al tempo forte che segue.

### 7.1 Anacrusi di sezione (a metà brano)

L'anacrusi non è confinata all'inizio del brano: una sezione interna
(tipicamente un **Refrain** dopo un Verse) può aprirsi *in levare*. In quel
caso l'ultima misura della sezione precedente mostra i propri valori **fino
alle note del levare escluse**, e la sezione nuova inizia con l'anacrusi.

Il caso si esprime con **due marcatori distinti**, uno per lato:

| Marcatore | Posizione | Riga su cui sta | Significato |
|-----------|-----------|-----------------|-------------|
| **`>>>`** | **in coda** alla misura | nessun contenuto dopo | **misura aperta**: la misura non viene completata con la pausa di coda, perché un levare la completa più avanti |
| **`>`**   | **in testa** alla misura | seguito da contenuto | **levare entrante**: come §7, ma ammesso come barline iniziale del **primo datapack di una sezione**, non solo del primo datapack del brano |

```
[Verse]
a b | c d | a2 r8 >>>          # ultima misura del verse, lasciata APERTA

>       || [Refrain]           # Markers: `>` tiene vuota la colonna del levare
> g a b || c1 ...              # Notes:   `>` apre il levare g a b, poi battere c1
```

Regole:

- **`>` leading vs `>` trailing.** Lo stesso segno è disambiguato dalla
  **posizione**, esattamente come §7 distingue l'anacrusi dall'accento: `>`
  **seguito da contenuto** (pitch / `<` / `|`) è levare *entrante*; `>>>`
  **non seguito da nulla** è misura *aperta* (uscente). Il sigillo di coda è a
  **forma fissa** (`>>>`): il numero di `>` non ha significato.

- **`>>>` esplicito, obbligatorio.** La misura aperta richiede il marcatore
  `>>>`: senza, una misura corta riceve la normale pausa di completamento di
  coda (autofill standard). NRK **non** deduce l'apertura dal datapack
  successivo — ogni datapack resta **auto-descrittivo**, e il marcatore
  sopravvive a riordini/spostamenti delle sezioni.

- **`>>>` è strutturale (propaga al system).** La misura aperta `>>>` è alla
  stregua di un **segno di misura / barline**: è una proprietà del **system**,
  non della singola voce. È perciò **sufficiente su un rigo** del datapack per
  **propagarsi a tutti gli altri**, esattamente come le barline condivise (§4.1
  di `neumaRk_datapack.md`). Non va replicato voce per voce.

- **`>` entrante è per-riga.** Il levare entrante `>` è invece **per-riga**
  (come §6.4 di `neumaRk_voices.md`): ogni voce porta il proprio. Sulle righe
  **senza note** (Markers, Chords) il `>` **prenota la colonna del levare
  lasciandola vuota**, così l'etichetta di sezione (`[Refrain]`) e la barra di
  battere si allineano alla **prima misura reale** e non sopra l'anacrusi. La
  grammatica lo consente già perché `|` conta come contenuto valido dopo `>`
  (`>  || [Refrain]`).

- **Numerazione.** Il levare di sezione **non** è contato (come §7). La misura
  aperta che lo precede **è** contata normalmente: è una misura reale della
  sezione precedente, solo più corta.

- **Niente doppia pausa.** A differenza dell'anacrusi iniziale (§7), il levare
  di sezione **non** riceve la pausa di completamento in testa: è la misura
  aperta che lo precede a fornire la rincorsa. La coppia *(misura aperta +
  levare)* è temporalmente contigua nel playback. Simmetricamente, la misura
  aperta **non** riceve la pausa di completamento in coda.

- **Nessuna validazione metrica.** *(Misura aperta + levare)* sono presi così
  come scritti, anche se non sommano a una misura piena: nessun warning. Resta
  responsabilità dell'autore.

- **Senza misura aperta.** Se la sezione precedente termina su una misura
  **piena** (nessun `>>>`) ma quella nuova apre con `>`, il `>` si comporta come
  un'anacrusi §7 a sé stante (levare parziale con pausa di completamento in
  testa). `>>>` è ciò che lega i due lati; in sua assenza non c'è legame.

- **Barre di sezione.** NRK non impone la convenzione tipografica "doppia barra
  *prima* del levare": le barline (incluse `||`) si collocano dove l'autore le
  scrive. La forma `… || c1` con la doppia barra **sul battere** è legittima.

> **Composizione con i lyrics.** Il gruppo *pickup* `<…>` del blocco `LYRICS)`
> (`neumaRk_lyrics.md §8.4.1`) è la controparte testuale di questo levare: le
> sillabe pickup si appoggiano alle note del levare di sezione qui definito.

---

## 8. Annotazioni

Dopo una nota è possibile aggiungere, ad essa adiacente,
un'annotazione testuale in due forme container, **semanticamente
equivalenti**, che differiscono solo per la presenza del box grafico:

- **`"<testo>"`** — forma primaria, senza box;
- **`[<testo>]`** — forma variante, con box.

```
c4"text"          annotation senza box
c4[text]          annotation con box
c4"$F1"           fingering (prefisso riservato, vedi §8.1)
```

L'annotation ammette il **markup testuale** definito in
`neumaRk_text_markup.md`. Lo stile di default è **plain, size ridotta**,
in entrambe le forme.

### 8.1 Prefissi riservati

Se il primo carattere dopo l'apertura del container è `$` seguito da
una lettera maiuscola riservata, il markup è **disabilitato**
sull'intera annotation: il contenuto è interpretato come **direttiva
strutturale**.

| Prefisso | Significato      |
|----------|------------------|
| `$F`     | fingering        |
| `$S`     | string number    |

Altri prefissi potranno essere definiti in estensioni future.

### 8.2 Disambiguazione con grace notes

In note-row il delimitatore `[…]` è condiviso con il blocco grace
(vedi `neumaRk_grace_notes.md`). La disambiguazione è **posizionale**
rispetto al pitch adiacente:

| Pattern                                       | Interpretazione         |
|-----------------------------------------------|-------------------------|
| `[…]MAIN` (nessuno spazio dopo `]`)            | grace block             |
| `PITCH[…]` con whitespace o EOT dopo `]`       | annotation con box      |
| `PITCH[…]MAIN` (nessuno spazio prima né dopo)  | grace block (priorità)  |
| `[…]` orfana (no pitch adiacente)              | W004 grace senza main   |

Esempi:

```
c4[text] d4         annotation con box su c4 (spazio dopo `]`)
c4 [d8/^]e4         grace block ancorato a e4
c4[d8/^]e4          grace block ancorato a e4 (priorità grace)
c4 [text] d4        quadre orfane → W004 (grace ignorato)
```

Per evitare ambiguità in casi limite, è raccomandato usare la forma
primaria `c4"text"` per le annotation: il delimitatore `"…"` non
collide con il blocco grace.

---

## 9. Cambio di chiave

La chiave di default è quella di violino.
Si può definire un cambio chiave con le notazioni:

- `(@G)` per la chiave di violino
- `(@C1)` per la chiave di soprano
- `(@C2)` per la chiave di mezzo-soprano
- `(@C3)` per la chiave di contralto
- `(@C4)` per la chiave di tenore
- `(@F3)` oppure `(@C5)` per la chiave di baritono
- `(@F)` oppure `(@F4)` per la chiave di basso
- `(@G8va)` per la chiave di violino all'ottava acuta
- `(@G8vb)` per la chiave di violino all'ottava bassa
- `(@F8)` oppure `(@F8vb)` per la chiave di basso all'ottava bassa

Il cambio di chiave si mantiene nel brano fino a una nuova definizione.

> **Disambiguazione con la tonalità.** In un decoratore di battuta `(…)` (vedi
> `neumaRk_datapack.md §7.1`) possono comparire sia un cambio di chiave (`(@F)`)
> sia un cambio di tonalità (`(F)`, `(Dm)`). Il prefisso **`@`** identifica la
> chiave: la direttiva di chiave è riconosciuta **prima** della tonalità, così
> `(@F)` non viene letto come tonalità di Fa.

In un datapack a più righi (vedi `neumaRk_datapack.md` §4), la chiave
dichiarata come primo token di una riga `N)` si applica al rigo
corrispondente. In assenza di direttiva, ciascun rigo eredita l’ultima
chiave definita nel proprio contesto.

## 10. notazioni non standard

### Slash notation

Sul pentagramma, al posto delle note, vengono disegnati degli **slash** (barre oblique) in numero pari ai movimenti della misura. Esistono due modi per generarla:

**1. Implicita (default).** In una misura con **armonia attiva**, se la riga di note è vuota (senza neanche pause), la misura viene resa con slash notation. È armonia attiva: un accordo esplicito, un `%`, **oppure** un accordo che persiste da una misura precedente (cella d'accordo vuota, vedi `neumaRk_chords.md §1.1`). Una misura marcata `NC` (`neumaRk_chords.md §1.2`) **non** è armonia attiva: con riga di note vuota riceve una **pausa**, non slash.

**2. Esplicita, con il costrutto `/`.** Il simbolo `/` nella riga `N)` è un evento del linguaggio che genera slash notation. Può essere usato da solo per riempire l'intera misura, oppure mescolato a note: la sua durata è implicita (autofill) e occupa **tutto lo spazio non coperto dalle altre note** della misura.

Esempi (in 4/4):

```
N) a b c d  |   /        |  a b c d
```
Tre misure: la prima e la terza con note, quella centrale tutta in slash notation.

```
N)   a4  /
```
Una nota da un quarto + slash sui restanti tre movimenti.

```
N)   /   a8  b
```
Slash sui primi tre movimenti + due crome finali.

**Regole.**

- Al più **un `/` per misura** (più d'uno produce errore E006).
- Lo slash non accetta una durata: la sua durata è sempre quella residua della misura.
- Quando la regione slash inizia o finisce a metà di un movimento (es. `| a8 / |`), viene aggiunta una pausa interna per chiudere il movimento parziale, e gli slash disegnati coprono i movimenti interi restanti (in `| a8 / |` in 4/4: 1 croma + 1 pausa-croma + 3 slash da un quarto).
- Se dopo l'allineamento ai movimenti non resta spazio per almeno uno slash, il `/` viene declassato a pausa (errore E007).
- Una riga composta **solo da `/`** (più barlines/punti/spazi) non richiede il prefisso `N)`: viene riconosciuta automaticamente come riga di note. Es. `| / | / | / | / |` è già una valida riga di note.

---

---

# Estensioni dell'evento nota (sigillate 2026-05-24)

> Le sezioni §11-§13 sono **normative e implementate** end-to-end (Fasi 3.2-3.3).
> Stato/dettagli: `neumaRk_changelog.md §0.6`. Impatto sulla classificazione
> **basso**: `N)` è il *default sink* della cascata (`neumaRk_datapack.md §3.bis`),
> quindi una riga con `(x)`, `(u-)…`, `{…}` o `R4` cade in Notes senza toccare gli
> altri predicati (`{` `}` `R` non sono in nessun charset; `R` maiuscola è libera,
> i pitch sono minuscoli).

## 11. Teste di nota e glissato di nota (la regola delle parentesi `(…)`)

In `N)` le parentesi tonde sono sovraccariche. Il significato di `(…)` legato a una
nota si determina per **contenuto** (e posizione prefisso/suffisso):

| Contenuto della parentesi | Significato | Posizione |
|---------------------------|-------------|-----------|
| `@…` (es. `@G`) | cambio chiave (§9) | prefisso/inline |
| cifre / lista (es. `4`, `16,8,8`) | ritmo esplicito (§3, anche `r(…)`) | suffisso |
| notehead-token `x` `d` `t` `s` `/`, oppure **vuoto** | testa nota / nota fra parentesi (§11.2) | suffisso |
| direzione+trattino `u-` `d-` `u--` `d--` | **glissato di nota** (§11.3) | prefisso = *in*, suffisso = *out* |

**Discrimine operativo: primo carattere + presenza del trattino finale.** Caso
chiave: `(d)` = diamante (notehead); `(d-)` = glissato giù (il trattino marca il
glissato). Senza il trattino i due collidono.

Una nota può combinare gruppi-parentesi **distinti** (uno per concetto):
`(u-)a2(x)` = glissato-in-su corto + `a2` + testa a croce; `a2(x)(d-)` = `a2` testa
a croce + glissato-out-giù.

### 11.1 Le tre cose "slash" da non confondere

- **`/` standalone**: slash-region ritmica (1 slash = 1 movimento, beat-aligned),
  vedi §10.
- **`(/)`**: testa slash su una nota, **all'altezza reale** del pitch (§11.2).
- **`{…}`**: notazione ritmica, slash **centrata** senza pitch (§12).

### 11.2 Teste di nota (noteheads)

> **Implementato** end-to-end (Fase 3.2). Stato/dettagli: `neumaRk_changelog.md §0.6`.

Suffisso `(…)` su una nota, **insieme chiuso**:

| Forma | Testa |
|------|-------|
| `(x)` | croce |
| `(d)` | diamante |
| `(t)` | triangolo (orientamento unico; varianti su/giù rinviate) |
| `(s)` | quadrato |
| `(/)` | slash (testa rhythm **all'altezza del pitch**) |
| `()` *(vuote)* | nota **fra parentesi** (editoriale / ghost) |

```
N) a2(x) b2(/) c2() d2(d)
```

- **Chord-stack**: `<c e g>(x)` applica la testa a **tutte** le pitch dello stack.
- Un solo notehead per nota.

> **Overload posizionale**: dentro `()` la lettera `t` è triangolo; fuori `t` è il
> marcatore **tuplet** (`8t`, §3.2); in `A)` è il gruppetto. Disambigua la posizione
> dentro/fuori parentesi (regola §11). Idem `d` (fuori da `()` non è notehead).
> Per `s`: dentro `()` è la testa **quadrata**; fuori, come token-pitch a sé, è lo
> **spacer** (§14).

### 11.3 Glissato di singola nota (scoop / fall / doit / plop)

> **Implementato** end-to-end (Fase 3.2b). Stato/dettagli: `neumaRk_changelog.md §0.6`.
> Co-locabile con i noteheads (`a(x)(d-)`).

Glissato ornamentale **in entrata o uscita** da una nota (diverso dal glissato *fra
due note*, che vive in `A)` come `gl` — `neumaRk_articulations.md §9`).

- direzione: `u` (su) / `d` (giù); lunghezza: `-` corto, `--` lungo;
- in/out dalla **posizione**: prefisso = in, suffisso = out;
- il **trattino marca il glissato** (lo distingue dal notehead, §11).

| Scrittura | Significato | Nome jazz |
|-----------|-------------|-----------|
| `(u-)a` | gliss IN su, corto | scoop |
| `(d-)a` / `(d--)a` | gliss IN giù | plop / drop |
| `a(u-)` | gliss OUT su, corto | doit / lift |
| `a(d-)` / `a(d--)` | gliss OUT giù | fall (corto / lungo) |

```
N) (u-)a2 a8 a(d--) | (d-)a a(u-)
```

## 12. Notazione ritmica `{…}`

> **Implementato** end-to-end (Fase 3.2c). Stato/dettagli: `neumaRk_changelog.md §0.6`.

Un gruppo `{…}` è reso come **notazione ritmica**: teste slash **centrate** sul
rigo, senza altezza. `{` e `}` sono delimitatori **nuovi** in NRK.

```
N) a4 r | b4 {8 8 16 16 8 4}
```

- Contenuto: **solo durate** (niente pitch); **rest ammessi** (`{8 8 r8}` → glifi
  di pausa) e **spacer ammessi** (`{8 8 s8}` → posizione ritmica saltata, nessuna
  testa, §14). L'altezza è sempre centrata.
- Notehead di default = slash. **Override** col suffisso notehead di §11.2:
  `{8 8 16}(x)` = teste a croce.
- Solo le note **dentro** le graffe sono rese come rhythm notation; il resto della
  misura è normale.
- **Tuplet ammessi** dentro `{…}` (es. `{8t 8t 8t}`); marcatore tuplet non valido →
  warning **W007**.

## 13. Pausa multi-misura (MMR) `RN`

> **Implementato** end-to-end (Fase 3.3): parse, validazione span-vuoto (**W008**),
> playback ×N, glifo MMR dedicato e rinumerazione +N. Stato/dettagli:
> `neumaRk_changelog.md §0.6`.

`RN` (es. `R4`) rende una **pausa multi-misura** di **N battute**: un'unica cella
che vale N misure, col conteggio misure che avanza di N. Resa: glifo MMR standard
(barra spessa) col **numero N** sopra. `R` è maiuscola (libera in `N)`, dove i
pitch sono minuscoli). Richiede **N ≥ 2** (`R1` = pausa di battuta singola,
ridondante → pausa normale). *(Forma `Rx4` scartata: si usa `RN`, coerente con
`%N`.)*

### 13.1 Quando si usa (condizione di span vuoto)

Le stanghette sono **condivise dal sistema**: non si collassa un rigo mentre se ne
mostra un altro. Quindi un MMR si rende **solo se l'intero span è vuoto a livello
di sistema** — tutte le voci/stave a riposo **e accordi vuoti**. È utile
esattamente in due casi: (a) singolo staff/voice con span vuoto; (b) più
staff/voices tutti `RN` allineati sullo stesso span (incluso il doppio rigo
pianistico a riposo).

```
C) A |    | B          # accordi vuoti sullo span centrale
N) a | R4 | b          # → MMR di 4 battute; conteggio misure +4
```

Se sullo span c'è **qualsiasi contenuto** (accordi, note di un'altra voce, marker),
`RN` non è lo strumento: **warning** e degrado a N pause per-battuta (si scrivono
direttamente pause normali).

> Corollario: poiché `RN` vive solo in span uniformemente vuoti, **non esiste mai**
> un'altra parte con contenuto da allineare in quello span → nessuna macchineria
> "espandi-per-allineare".

### 13.2 `RN` ≠ collasso in estrazione

Vanno tenuti separati:

- **`RN`** = "voglio un MMR **qui**, in **questa** vista" (notazione esplicita, span
  vuoto).
- **Collasso in estrazione** = **automatico**: estraendo una parte singola da uno
  score multi-parte, le battute vuote di quella parte collassano in MMR **senza
  notazione speciale** (si scrivono pause normali). È feature **futura** (arriva con
  l'estrazione parti); `RN` su span vuoto è invece implementabile da subito. La
  scelta "nella parte gli accordi si omettono" è un'**impostazione di estrazione**,
  non un marcatore MMR.

### 13.3 Regole di confine (resa)

- **Solo battute intere**: se la parte entra a metà battuta, le battute intere vanno
  in MMR e il mezzo-tempo ai bordi resta pausa normale.
- **Lo span si spezza** a: cambio di sistema (line break), doppia stanghetta,
  ritornello `:|`/`|:`, cambio di tonalità/metro/tempo, lettera di prova. Es. `R8`
  con un cambio di tonalità a metà → due MMR.

---

## 14. Spacer — pausa invisibile (`s`)

> **Implementato** end-to-end (2026-05-27): parser, classificazione, serializer,
> render (GhostNote) e playback. Vedi `neumaRk_changelog.md §0.6`. Impatto sulla
> classificazione **basso**: come per `r`, una riga di soli `s` cade nel
> default sink `N)` (`neumaRk_datapack.md §3.bis`, TB1 esteso a `s`).

Lo **spacer** è un evento che **occupa durata** esattamente come una pausa
(`r`), ma **non rende alcun glifo**: avanza il tempo metrico senza disegnare
nulla sul rigo. È mutuato dal costrutto omonimo di LilyPond. Serve a riservare
spazio metrico senza segno grafico: allineare per colonna una seconda voce o le
sillabe (`L)`), lasciare "vuoti" pilotati in una misura, posizionare un'unica
annotazione su un punto del tempo senza pausa visibile.

### 14.1 Sintassi

`s` è un **token-pitch speciale** (come `r`): sostituisce l'altezza e accetta
tutta la grammatica di durata di una pausa.

| Forma | Significato |
|-------|-------------|
| `s` | spacer di durata **implicita** (eredita dal contesto, §3.3) |
| `s4` `s8` `s16` | durata esplicita (§3.1) |
| `s4.` `s2..` | punto adiacente (§4.1) |
| `s8 . .` | punto distanziato (§4.2) |
| `s4t` `s8t5` | dentro un tuplet (§3.2) |
| `s16*5` `s16x5` | moltiplicatore (§4.3) |
| `s !!!` | ripetizione (§5) |

```
N) c4 s4 e4 s4        # due eventi reali alternati a due spacer da un quarto
N) s2 g2              # primo tempo "vuoto" (invisibile), poi g da minima
```

### 14.2 Semantica

Lo spacer è **indistinguibile da `r`** per: durata, conteggio della misura,
autofill (§3.3.1) e playback (silenzio — evento non udibile). L'**unica**
differenza è la resa grafica.

| | `r` (pausa) | `s` (spacer) |
|---|---|---|
| Resa | glifo di pausa | **nessun glifo** |
| Durata / metro | conta | conta (identico) |
| Playback | silenzio | silenzio (identico) |
| Classificazione riga | Notes | Notes |

**Misura interamente di spacer.** La misura appare otticamente vuota ma il tempo
avanza normalmente. **Non** si applica la pausa-di-misura di riempimento (whole
rest) né la slash notation riservata alle misure armoniche vuote (§10): lo spacer
è una scelta esplicita di "niente segno".

### 14.3 Restrizioni

Lo spacer non ha altezza né presenza grafica, quindi **non accetta** i modificatori
che presuppongono una nota o un ancoraggio visivo. In tutti i casi seguenti il
modificatore è **ignorato** con warning **W009**:

| Scrittura | Esito |
|-----------|-------|
| `^s` / `s^` | nessuna legatura: lo spacer non lega (§6). Per prolungare, usa la nota reale o `r` |
| `s"…"` / `s[…]` | nessuna annotazione (§8): manca l'ancora visiva |
| `s(x)` `(u-)s` | nessun notehead/glissato (§11): riservati alle note reali |

Inoltre, per simmetria con `r`:

- **Chord-stack `<…>`**: `s` al suo interno **non è valido**, ignorato in silenzio
  (§2.6).
- **Grace block**: `s` **non ammesso** come evento grace → **E013** (come `r`,
  `neumaRk_grace_notes.md`).

### 14.4 Niente forma multi-misura

Non esiste uno spacer multi-misura (`SN` **non** è definito): la `S` maiuscola è
il marcatore d'intestazione *Style* (`neumaRk_header.md`), e una MMR (§13) è per
definizione una pausa **visibile**. Per saltare N misure in modo invisibile si
ripete `s` misura per misura.

---

## 15. Regole di deduzione (riassunto)

- pitch o durata omessi vengono dedotti dal contesto
- la deduzione non deve mai produrre ambiguità semantica
- in caso di conflitto, prevale sempre la sintassi esplicita

---

Questo documento definisce il **livello atomico** della notazione musicale in neumaRk.


---

# Accordi

Questo documento definisce la sintassi e la semantica degli **accordi** in neumaRk, inclusi:

- dizionario delle sigle ammesse
- normalizzazione delle varianti
- gestione del basso
- ritmo degli accordi (implicito, esplicito, misto)
- accordi opzionali
- polyaccordi (polychord)

Gli accordi sono contenuti nelle righe `C)` e possono essere utilizzati per determinare sia l'armonia che il suo aspetto ritmico.

---

## 1. Evento accordo

Un **evento accordo** è un’unità armonica che può avere:

- una sigla di accordo
- un basso opzionale, oppure solo un basso
- una durata (implicita o esplicita)
- modificatori di durata

Un evento accordo può anche rappresentare:

- una pausa (`r`)
- un ribattuto (`!`)
- un **polyaccordo** (due sigle sovrapposte verticalmente, vedi §6)

Ogni evento accordo in neumaRk è un’entità ritmica autonoma, con durata
implicita o esplicita.

Un accordo può includere un **basso esplicito** nella forma di _slash chord_
(es. `A/B`), oppure consistere esclusivamente di un basso (es. `/B`).

In entrambi i casi, l’evento è soggetto alle stesse regole ritmiche degli
altri accordi.

### 1.1 Persistenza dell’armonia (cella vuota)

Una **misura di accordi vuota** — priva di sigle, di `%` e del token `NC`
(§1.2) — **non** rappresenta un vuoto armonico: l’**armonia della misura
precedente persiste**. Il contenuto armonico vigente viene **ri-realizzato
sul battere** della misura vuota (ri-attacco, con la stessa logica di `%`),
non sostenuto come una legatura.

La persistenza:

- si propaga su più misure vuote consecutive;
- attraversa i confini di datapack, coerentemente col **contesto musicale
  persistente** (`neumaRk_specification.md`);
- si **interrompe** su un evento `NC` (§1.2) e riprende solo dal successivo
  accordo esplicito.

```
C) C |   |   F
```

Le misure 1 e 2 suonano `C`; la misura 3 suona `F`. Sopra le misure
persistenti **non viene disegnato alcun glifo**: il rigo accordi resta
pulito.

> **Resa sul rigo di note.** Se la riga `N)` di una misura persistente è
> vuota, la misura è resa in **slash notation** (c’è armonia attiva da
> accompagnare): vedi `neumaRk_notes_and_durations.md §10 → Slash notation`.

#### 1.1.1 Continuazione parziale (`.` iniziale)

Quando una misura **inizia** con un punto `.` (prima di qualsiasi sigla), il
punto è una **continuazione dell’armonia persistente**: ri-attacca l’armonia
vigente (§1.1) **solo per il proprio slot**, lasciando il resto della misura
agli accordi che seguono. È l’estensione, a livello di slot, della
persistenza di cella vuota. (Distinto dal `.` che **segue** un accordo nella
stessa misura, che ne prolunga la durata: vedi §4.)

```
C) A7 DM |   | . GM
```

Nella misura 3 il primo tempo continua `DM` — l’armonia attiva, ereditata
dalla misura 1 attraverso la cella vuota della misura 2 — e il secondo tempo
suona `GM`. In playback equivale a `A7 DM | DM | DM GM`.

Più punti iniziali (`. .`) estendono la continuazione su più slot. Se
l’armonia non è attiva (inizio del brano, o dopo `NC`), un `.` iniziale resta
muto. Sul rigo accordi il punto di continuazione **non disegna alcun glifo**.

### 1.2 Assenza di accordo (`NC`)

Il token **`NC`** (due lettere maiuscole, senza punti) dichiara
l’**assenza di armonia**: interrompe la persistenza (§1.1) e indica che in
quella misura **non suona alcun accordo**.

- occupa **l’intera misura** ed è l’**unico contenuto** della sua cella; non
  è miscelabile con sigle o durate (`C NC` → errore **E128**);
- in playback è **muto** (nessun accordo realizzato);
- è **renderizzato** sul rigo accordi con il glifo dedicato `N.C.`
  (codepoint riservato `U+EFB2` dei font BravuraLS/PetalumaLS);
- se la riga `N)` corrispondente è vuota, la misura **non** riceve slash
  notation ma una **pausa** (non c’è armonia da accompagnare).

```
C) C |  NC |  F
```

La misura 1 suona `C`; la misura 2 è muta (con `N.C.` disegnato); la misura
3 suona `F`. Dopo un `NC`, una cella vuota **resta muta** finché non compare
un nuovo accordo esplicito.

---

## 2. Sigla di accordo

### 2.1 Struttura generale

La forma generale di una sigla è:

```
<root><quality>[<extensions>][/<bass>]
```

Dove:

- `root` ∈ `{A B C D E F G}` con alterazioni opzionali `#` o `b` (massimo un'alterazione)
- `suffix` identifica il suffisso dell'accordo
- `bass` opzionale, indica un basso differente dalla root

Esempi:

```
C   Dm  GM  F#7alt   BbM13   C7/E
```

---

## 3. Dizionario degli accordi

### 3.1 Triadi

| Input ammessi | Normalizzazione |
| ------------- | --------------- |
| C             | C               |
| Cm, C-        | C-              |
| Co, Cdim      | C°              |
| C+, C5+, Caug | Caug            |
| Csus2         | Csus2           |
| Csus4         | Csus4           |

---

### 3.2 Accordi maggiori (4 o più suoni)

| Input ammessi          | Normalizzazione |
| ---------------------- | --------------- |
| C6                     | C6              |
| C69                    | C69             |
| CM, CM7, CMaj7, Cmaj7, C7M | CΔ          |
| CM9, Cmaj9             | CΔ9             |
| CM13, Cmaj13           | CΔ13            |
| CM#11, CM7#11, Cmaj#11 | CΔ#11           |
| CM9#11                 | CΔ9#11          |
| CM13#11                | CΔ13#11         |
| CM+, CM#5, CM7#5, C+M7 | CΔ#5            |

---

### 3.3 Accordi minori

| Input ammessi        | Normalizzazione |
| -------------------- | --------------- |
| C-b6, Cmb6           | C-b6            |
| C-6, Cm6, C-69, Cm69 | C-6             |
| C-7, Cm7             | C-7             |
| C-9, Cm9             | C-9             |
| C-11, Cm11           | C-11            |
| C-13, Cm13           | C-13            |
| C-M, CmM, C-M7, CmM7 | C-M             |

---

### 3.4 Accordi di dominante

| Input ammessi              | Normalizzazione |
| -------------------------- | --------------- |
| C7                         | C7              |
| C9                         | C9              |
| C13                        | C13             |
| C7#11, C9#11, C13#11, C7b5 | C7#11           |
| C7b9                       | C7b9            |
| C7alt                      | C7alt           |
| C7#5, C+7                  | C7#5            |
| C7#9                       | C7#9            |
| C13b9                      | C13b9           |
| C7sus, C9sus, C13sus       | C7sus           |
| C7susb9                    | C7susb9         |

---

### 3.5 Accordi diminuiti e semidiminuiti

| Input ammessi     | Normalizzazione |
| ----------------- | --------------- |
| Co7, Cdim7        | C°7             |
| CoM7, CdimM7, CoM | C°M             |
| Cm7b5, Ch         | Cø              |

### 3.6 Suffissi fuori dizionario

Il dizionario (§3.1–§3.5) è l'insieme dei suffissi **riconosciuti**. Le grafie della
settima maggiore `maj`/`Maj` (`Cmaj7`, `Cmaj9`, `Cmaj#11`, …) e il `7` ridondante
(`M7`/`7M`) sono **canonicalizzate alla forma `M`** (§3.2) — riconosciute, non
warning. Un suffisso davvero fuori dizionario (es. `dom7`) **non rende il documento non
valido**: la sigla viene **conservata** (root + eventuale basso) ma il suffisso non
ha resa significativa, e il parser emette il warning non-bloccante **W103**
(*unrecognized chord suffix*). Si tratta di un **degrado best-effort**, non di un
errore: il flusso di parsing prosegue.

---

## 4. Ritmo degli accordi

#### N.B.

Il significato del punto (`.`) è specifico del contesto delle righe di accordi
e non coincide con quello utilizzato nelle righe di note.
Il carattere punto assume significati differenti a seconda della sua posizione **distanziata** dall'evento accordo o inserita nel contesto di **durata**.

### 4.1 Modalità implicita

In assenza di durate esplicite, il ritmo degli accordi è **dedotto**.

Principio:

- gli eventi accordo in una misura sono contati
- la durata della misura è suddivisa equamente
- il punto (`.`) prolunga l’accordo **della sua stessa durata**

Esempi in 4/4:

```
| C Dm |
| C . . Dm |
| r C . Dm . D#o . Em |
```

In modalità implicita il ritmo **non viene visualizzato**, ma serve per l’allineamento.

---

### 4.2 Modalità esplicita

La durata di un accordo può essere indicata fra parentesi tonde:

```
C(4)   Dm(8.)   G7(8t)
```

La durata può contenere:

- valore della nota (obbligatorio)
- punti (`.`), modalità standard, aggiungono la metà del valore
- `t` per terzina (tuplet 3:2)
- moltiplicatori (`*n`)

Simboli speciali:

- `r` → pausa
- `!` → ribattuto (ripete la durata, non la sigla)

Per l’ultimo accordo della misura, `^` crea una legatura verso la misura successiva.

Con questa modalità di notazione, il ritmo degli accordi **viene notato sopra al pentagramma**.

---

### 4.3 Modalità mista

È possibile combinare modalità implicita ed esplicita nella stessa misura.

- solo le durate esplicite vengono visualizzate
- le altre sono dedotte

```
C   Dm(8^)
```

**La pausa `r` segue le stesse regole di un accordo**, sia per la
deduzione del ritmo sia per la visualizzazione:

- `r` (senza parentesi) è **implicita**: concorre alla deduzione come
  qualunque altro evento (la durata della misura, sottratte le durate
  esplicite, è suddivisa equamente fra gli eventi impliciti, considerando
  anche i punti `.`) e **non viene disegnata** nel rhythm-row;
- `r(...)` (con parentesi) è **esplicita** e **viene disegnata** come
  pausa visibile sopra al pentagramma.

Esempio — anticipo di croma su misura altrimenti vuota:

```
r EbM(8^) | EbM
```

rende solo l'ottava di anticipo legata a `EbM` della misura successiva,
senza pause visibili a riempire la prima misura. Equivale, per
posizionamento e ritmo, a quanto già si ottiene con un accordo
implicito al posto di `r` (`Gm EbM(8^)`), con la differenza che qui non
c'è alcuna sigla all'inizio della misura.

> *Limitazione attuale.* Quando un evento implicito (accordo o `r`) cade
> **dentro a una tuplet** la soppressione visiva non è attiva e il rest
> torna disegnato. Non si tratta di una scelta semantica: è un vincolo
> del renderer che potrà essere rimosso in futuro senza modifiche alla
> sintassi.

---

### 4.4 Lista compatta di durate

Quando lo stesso accordo si protrae su più figure ritmiche, invece di
ripetere `!` per ogni continuazione si può usare una **lista di durate
separate da virgola** dentro le parentesi:

```
D/Eb(16,8,8,16,16,r16,16,16)
```

è la forma compatta, **equivalente** a:

```
D/Eb(16) !(8) !(8) !(16) !(16) r(16) !(16) !(16)
```

Regole:

- ogni segmento ammette `valore`, `valore.` (puntato), `valore..`,
  `valore...`, `valoret` (terzina);
- un segmento può iniziare con `r` per inserire una **pausa interna**
  (es. `r16`): l'accordo si interrompe per quella durata e poi riprende
  con il segmento successivo;
- il **primo segmento non può essere `r`** (la lista deve aprire con
  l'accordo): `D(r16,8)` è un errore;
- `*n` (moltiplicatore) e `^` (legatura) **non sono ammessi all'interno**
  dei segmenti, solo nella forma single-rhythm `(valore*n)` o sul
  segmento finale del gruppo (vedi sotto);
- spazi attorno alle virgole sono tollerati: `D(16, 8, 8)` è valido.

**Legatura `^` su lista compatta.** Il `^` finale lega l'**ultimo
segmento** del gruppo all'evento successivo, come una normale legatura
di valore sull'ultima nota della misura:

```
D/Eb(16,8,8,16,16,r16,16,16)^   A
                              ↑
                              ultimo `16` legato ad `A`
```

**Resa visiva.** La sigla `D/Eb` compare una sola volta sopra il
pentagramma (ancorata al primo segmento). Sopra al pentagramma viene
disegnato il ritmo dell'intero gruppo: la prima figura ha il nome
dell'accordo, le successive sono continuazioni mute (nessuna sigla
ripetuta), eventuali `r` interni sono pause visibili.

**Round-trip.** Salvando e ricaricando, la forma compatta viene
**preservata**: il file `.nrk` torna identico a quanto scritto.

---

## 5. Accordi opzionali

Una parentesi tonda aperta avvia un gruppo di **accordi opzionali**:

```
(C Dm G7)
```

Il gruppo può estendersi su **più misure**, includendo barline
interne:

```
(FM F#-7 | B7 EM)
```

Le parentesi tonde sono **renderizzate visivamente** intorno al
gruppo. Gli accordi al suo interno mantengono normale semantica
ritmica e di allineamento con le altre righe del datapack.

Un gruppo opzionale può portare un **comment-label** (§7) attaccato
alla parentesi di chiusura, senza whitespace intermedio:

```
(FM F#-7 | B7 EM)[Bill Evans changes]
```

---

## 6. Polyaccordi (polychord)

Un **polyaccordo** è un evento accordo costituito da **due sigle sovrapposte**, lette simultaneamente: una sigla _superiore_ e una sigla _inferiore_, separate visivamente da una linea orizzontale.

Il polyaccordo è un evento armonico distinto dallo _slash chord_ (§1):

- _slash chord_ (`A/B`) → un unico accordo `A` con basso `B`
- polyaccordo (`[A|B]`) → due accordi indipendenti `A` e `B` suonati insieme

### 6.1 Sintassi

Un polyaccordo è racchiuso fra parentesi quadre, con il carattere `|` come separatore interno:

```
[<top>|<bottom>]
```

Dove:

- `top` e `bottom` sono **sigle di accordo valide** secondo §2 (root, qualità, estensioni, basso opzionale)
- le parentesi quadre `[ ]` sono **obbligatorie**
- il separatore `|` è **obbligatorio** e compare **esattamente una volta**
- non è ammesso whitespace interno

Esempi validi:

```
[D|EbM]            polyaccordo: D maggiore sopra EbM7
[CM7|F#-7]         polyaccordo con sigle estese
[D/F#|EbM]         top con basso esplicito (slash chord) sopra accordo semplice
[Am|G](8.)         polyaccordo con durata esplicita
```

Esempi non validi:

```
[D|EbM|F]          tre livelli non ammessi
[|EbM]             sigla superiore mancante
[D|]               sigla inferiore mancante
[D | EbM]          whitespace interno non ammesso
```

### 6.2 Resa visiva

Il polyaccordo viene visualizzato come due sigle impilate verticalmente, separate da una linea orizzontale:

```
 D
───
EbM
```

La larghezza orizzontale riservata al polyaccordo è pari alla maggiore fra le due sigle.

### 6.3 Durata e ritmo

Il polyaccordo è un **singolo evento accordale** ai fini del ritmo. Tutte le regole di §4 si applicano al polyaccordo come a qualunque altro evento:

- durata implicita: il polyaccordo conta come **un solo evento** nella suddivisione della misura
- durata esplicita: la parentesi tonda segue le parentesi quadre, es. `[D|EbM](4)`
- ribattuto (`!`) e ripetizione (`.`) operano sull’intero polyaccordo

```
| [D|EbM] . . [F|G7] |     polyaccordo ripetuto tre volte, poi cambio
| [D|EbM](2) [F|G7](2) |   due polyaccordi, durata esplicita
```

### 6.4 Trasposizione

In trasposizione, **entrambe le sigle** del polyaccordo vengono trasposte indipendentemente secondo le regole del singolo accordo.

### 6.5 Limiti

- numero di livelli: **esattamente 2** in neumaRk 0.6; estensioni a N livelli sono fuori specifica
- annidamento: un polyaccordo non può contenere a sua volta un altro polyaccordo
- gruppo opzionale: un polyaccordo **può** comparire dentro un gruppo `( … )` di accordi opzionali (§5)

---

## 7. Comment-label

Un **comment-label** è una stringa libera fra parentesi quadre,
attaccata in postfix a un evento accordale per annotarlo con testo
arbitrario.

### 7.1 Sintassi

Un comment-label è espresso in due forme container, **semanticamente
equivalenti**, che differiscono solo per la presenza del box grafico:

- **`"<testo>"`** — forma primaria, senza box;
- **`[<testo>]`** — forma variante, con box.

Il testo è una stringa di caratteri stampabili (spazi inclusi) e
ammette il **markup testuale** definito in `neumaRk_text_markup.md`.
Il carattere di chiusura del container (`"` o `]`) non può comparire
letteralmente nel testo: usare l'escape `\"` o `\]`.

Lo stile di default del comment-label è **italic, size ridotta**, in
entrambe le forme. Il box grafico è applicato solo nella variante
`[…]`.

Tre scope ammessi, distinti per **punto di attacco**:

- **chord-level** — attaccato a un chord event (anche polychord),
  senza whitespace intermedio:

  ```
  Eb7alt"tritone"            no box (primaria)
  Eb7alt[tritone]            con box (variante)
  [A|EbM]"polychord exp."
  ```

- **group-level** — attaccato alla parentesi di chiusura `)` di un
  gruppo di accordi opzionali (§5):

  ```
  (FM F#-7 | B7 EM)"Bill Evans changes"
  (FM F#-7 | B7 EM)[Bill Evans changes]
  ```

- **row-level** — come **primo token utile** della chord-row,
  preceduto solo dal marker di riga `C)` / `C+`. Due forme equivalenti
  semanticamente:

  - **senza barlines** — label come unico contenuto della riga (la
    chord-row non contiene eventi musicali):

    ```
    C+ "solos changes"
    C+ [solos changes]
    ```

  - **con barlines** — label come primo token dentro le bar della
    riga, prima di qualunque chord-event:

    ```
    C+ | "solos changes" | Cm7 | F7 |
    C+ | [solos changes] | Cm7 | F7 |
    ```

    Equivale alla forma senza barlines per il segmento di label, e
    permette di coesistere con eventi successivi della stessa row.

### 7.2 Disambiguazione

Il delimitatore `[…]` è condiviso con altri costrutti già definiti
nella spec. La disambiguazione è **posizionale**:

| Costrutto | Forma riconosciuta |
|-----------|--------------------|
| Polychord (§6) | `[<top>\|<bottom>]` — contiene `\|` interno, nessun whitespace |
| Volta (`flow §3.2`) | attaccato a barline d'inizio misura: `\|[1.]` |
| End-decorator (`flow §4.3`) | attaccato a `:\|` o barline di fine: `[xN]:\|`, `[D.S.]` |
| Comment-label (con box) | attaccato a chord / `)` di optional group, o primo token della row, nella forma `[…]` |

Il parser riconosce il polychord per primo (vincola la forma a `|`
interno), gli altri sono distinti per posizione di attacco.

La forma `"…"` del comment-label non collide con nessuno di questi
costrutti, perché il delimitatore `"` non è condiviso. La
disambiguazione del comment-label `"…"` resta posizionale (attaccato a
chord, `)` di gruppo opzionale, o primo token della row).

### 7.3 Resa visiva

- **chord-level** — italic ridotto sopra al chord (sopra l'eventuale
  notazione ritmica); box grafico solo nella variante `[…]`.
- **group-level** — italic ridotto sopra al gruppo, allineato a
  sinistra; box grafico solo nella variante `[…]`. Le parentesi degli
  optional restano invariate in entrambe le forme.
- **row-level** — italic ridotto a inizio riga, allineato col primo
  evento musicale; box grafico solo nella variante `[…]`.

Lo stile di default (italic, size ridotta) è proprietà del **costrutto**
e si applica in entrambe le forme. Il container (`"…"` vs `[…]`) decide
solo la presenza del box (vedi `neumaRk_text_markup.md`).

### 7.4 Limiti

- al massimo **un** comment-label per evento (errore `E126` se
  duplicato sullo stesso evento), indipendentemente dalla forma
  container usata (`[…]` o `"…"`)
- il label è puramente annotativo: non influisce su pitch, durata,
  ritmo, flusso musicale né trasposizione
- ammesso sia su riga base `C)` sia su righe alternative `C+`
- i container `[…]` e `"…"` sono **single-line**: il delimitatore di
  chiusura deve comparire entro fine riga

---

## 8. Regole generali di durata

- in caso di conflitto prevale la sintassi esplicita
- la normalizzazione non altera la semantica
- il ritmo implicito è deterministico

---

Questo documento definisce la **semantica armonica e ritmica** delle righe di accordi in neumaRk.


---

# Seconda voce per rigo

Questo documento definisce la sintassi e la semantica della **seconda voce
musicale** su uno stesso rigo (stave) in neumaRk: marker, posizione
strutturale, regole di contesto, resa grafica e diagnostica.

La seconda voce è uno **stream musicale indipendente** che condivide lo
stesso pentagramma della voce principale ma evolve con il proprio ritmo
e con il proprio contesto musicale persistente.

---

## 1. Definizione

In neumaRk un **rigo** (stave) può contenere fino a **due voci**
indipendenti:

- la **voce 1** (o *voce principale*), introdotta dalla riga `N)` (o `N+`,
  vedi `neumaRk_datapack.md` §4.5);
- la **voce 2** (o *voce secondaria*), introdotta dalla riga `N2`,
  opzionale.

Le due voci:

- condividono il rigo, la chiave, la tonalità, il metro, le stanghette
  di misura e la riga degli accordi `C)`;
- mantengono **stream ritmici e melodici indipendenti**;
- hanno **contesti musicali persistenti separati** (`last_pitch`,
  `durCtx`).

Un rigo può avere **al massimo una voce 2**. La voce 2 esiste solo se
esplicitamente dichiarata: in sua assenza il rigo è monodico.

> **Stave ≠ voce.** Il concetto di *rigo* (`N)` / `N+`) descrive il
> pentagramma; il concetto di *voce* (1ª o 2ª) descrive lo stream
> musicale all'interno di quel pentagramma. Un brano a 4 righi può
> avere fino a 8 voci totali (4 stave × 2 voci), senza ulteriori
> limiti aggregati.

---

## 2. Sintassi del marker

### 2.1 Forma

Il marker della voce 2 è la sequenza di **due caratteri**:

```
N2
```

seguita da uno spazio, in analogia a `N)` e `N+`. La cifra `2` sostituisce
la `)`, preservando l'invariante di larghezza a 2 caratteri richiesta per
l'allineamento verticale delle stanghette nelle righe del datapack.

### 2.2 Relazione con le regole generali di marcatura

La regola generale (`neumaRk_datapack.md` §2.1) prevede marcatori formati
da una, due o tre lettere maiuscole seguiti da `)`. I marker `N+` e `N2`
sono **varianti morfologiche di `N)`** previste in modo esplicito dalla
specifica e non rappresentano un'eccezione arbitraria: la lettera
identificativa `N` resta invariata, e il secondo carattere distingue il
ruolo (`)` continuazione, `+` nuovo rigo, `2` seconda voce).

---

## 3. Posizione strutturale e binding

### 3.1 Gruppo voce

Ogni voce è descritta da un **gruppo voce** della forma:

```
[A)] N) [D)] [L)]      ← gruppo della voce 1
[A)] N2 [D)] [L)]      ← gruppo della voce 2 (opzionale)
```

Le righe `A)`, `D)`, `L)` legano per **posizione**:

- `A)` (articolazioni) precede la sua `N)` / `N2`;
- `D)` (dinamiche) e `L)` (lyrics) seguono la sua `N)` / `N2`, in
  quest'ordine.

Entrambe le voci possono dichiarare le proprie articolazioni, dinamiche
e lyrics in modo indipendente.

### 3.2 Binding al rigo parent

Una riga `N2` lega al **rigo immediatamente precedente** nello stesso
datapack, identificato dalla più recente riga `N)` o `N+`. Tra la `N)` /
`N+` parent e la `N2` sono ammesse soltanto:

- le eventuali `D)` / `L)` del gruppo voce 1;
- l'eventuale `A)` del gruppo voce 2.

Qualsiasi altra riga interposta interrompe il binding e rende la `N2`
non riconosciuta come voce 2 del rigo precedente (errore **E123**).

### 3.3 Unicità per rigo

In uno stesso datapack, ciascun rigo può avere **al massimo una** riga
`N2`. La presenza di più `N2` consecutive che leghino allo stesso rigo
produce errore **E124**.

### 3.4 N2 come prima riga di note

Una `N2` non preceduta da una `N)` o `N+` nello stesso datapack
non ha un parent valido ed è non valida (**E123**).

---

## 4. Contesto musicale della voce 2

### 4.1 Stream indipendente

Il contesto musicale persistente definito in `neumaRk_specification.md`
§2.1 è **per-stream**: ogni coppia *(rigo, voce)* mantiene il proprio
`last_pitch`, la propria `durCtx` e lo stato di propagazione degli
accidenti di misura.

Gli aggiornamenti di contesto effettuati dagli eventi della voce 1
**non** modificano il contesto della voce 2, e viceversa.

### 4.2 Inizializzazione alla prima apparizione

Quando la voce 2 di un rigo compare per la **prima volta** in un
datapack — cioè quando nel datapack precedente lo stesso rigo non
conteneva una voce 2 — il suo riferimento iniziale (`last_pitch` e
`durCtx`) è ereditato dalla **voce 1 dello stesso rigo**, nello stato
*all'inizio del datapack corrente*.

Equivalentemente: la voce 2 entra come se fosse, in quel preciso
istante musicale, una continuazione della voce 1 — e da quell'istante
in poi mantiene il proprio stream separato.

```
DP1:
N) a4

DP2:
N) c           ← eredita a4 → c5 (intervallo minimo)
N2 a           ← prima apparizione: eredita a4 (voce 1 a inizio DP2)
               → a4. Da qui voce 2 prosegue con stream proprio.
```

### 4.3 Apparizioni successive

Quando la voce 2 era già presente nel datapack precedente, eredita
normalmente dal proprio stream:

```
DP3:
N) c           ← eredita da voce 1 di DP2
N2 a           ← eredita da voce 2 di DP2
```

### 4.4 Voci sospese

Se la voce 2 di un rigo è presente in un datapack, **assente** nel
successivo, e ricompare in un datapack ancora successivo, alla
ricomparsa si applica nuovamente la regola §4.2: il contesto della
voce 2 è reinizializzato dalla voce 1 dello stesso rigo all'inizio del
datapack di ricomparsa.

Il contesto storico della voce 2 anteriore alla sospensione non viene
recuperato.

### 4.5 Voci in stave introdotto con `N+`

Se la voce 2 compare in un rigo introdotto in quel datapack tramite
`N+`, la voce 1 del rigo è essa stessa "fresh" (riferimento di
orientamento basato sulla chiave, vedi `neumaRk_notes_and_durations.md`
§2.2). La voce 2 eredita di conseguenza lo stesso riferimento
clef-dipendente all'inizio del proprio stream.

---

## 5. Resa grafica

### 5.1 Direzione dei gambi

La presenza simultanea di voce 1 e voce 2 su uno stesso rigo fissa la
direzione dei gambi in modo **normativo**:

- voce 1 → gambi sempre **in alto**;
- voce 2 → gambi sempre **in basso**.

Questa regola si applica indipendentemente dall'altezza delle note e
sovrascrive ogni euristica di rendering automatico in vigore quando il
rigo è monodico.

### 5.2 Pause

Le pause delle due voci sono indipendenti. Quando la posizione verticale
naturale di una pausa entra in collisione con quella dell'altra voce, il
renderer applica un offset di chiarezza secondo le convenzioni standard
della notazione musicale; questo non altera la semantica.

---

## 6. Allineamento e validità

### 6.1 Numero di misure

La voce 2 deve contenere **lo stesso numero di misure** del rigo parent.
È la stessa regola che vale fra righi di un sistema multi-stave
(`neumaRk_datapack.md` §4.3).

### 6.2 Riga degli accordi

La riga `C)` è system-wide ed è condivisa da tutte le voci di tutti i
righi del datapack. Non esiste una `C)` per-voce.

### 6.3 Chiave

La chiave è proprietà del rigo, non della voce. Una direttiva di chiave
inline come primo token di una riga `N2` (es. `N2 (@F) …`) non è ammessa
e produce errore **E125**.

### 6.4 Anacrusi

Il segno di anacrusi `>` è per-riga e può comparire indipendentemente in
`N)` e in `N2`.

### 6.5 Misura ripetuta

Il token `%` (e varianti `%!`, `%2`, `%!2`, `%4`, `%!4`, vedi
`neumaRk_flow_and_repeats.md` §7) si applica **per-riga**: la sua
presenza in `N2` ripete la voce 2 della misura sorgente, senza
coinvolgere la voce 1. Le copie eventuali di `A)`, `D)`, `L)` seguono
le stesse regole di layer già definite per le righe singole.

### 6.6 Grace notes

Le grace notes (`[ … ]`, vedi `neumaRk_grace_notes.md`) sono ammesse
all'interno di `N2` con le stesse regole della voce 1. Il loro contesto
locale di pitch ed accidenti vive nello stream della voce 2.

---

## 7. Diagnostica

### 7.1 Codici di errore

| Codice | Descrizione                                                    |
| ------ | -------------------------------------------------------------- |
| E123   | `N2` senza un rigo parent (`N)` o `N+`) valido nel datapack    |
| E124   | Più di una `N2` legata allo stesso rigo nel medesimo datapack  |
| E125   | Direttiva di chiave inline su una riga `N2`                    |

### 7.2 Misure non allineate

Un disallineamento del numero di misure fra `N2` e il rigo parent ricade
sotto le stesse regole di validità del multi-stave
(`neumaRk_datapack.md` §4.3).

---

## 8. Esempi

### 8.1 Voce 2 minimale

```
C) A7
N) a1
N2 e4 d e2
```

Rigo unico in chiave di violino. Voce 1: una semibreve `a` per la
misura. Voce 2: due semiminime e una minima.

### 8.2 Entrambe le voci con A/D/L indipendenti

```
C) A7
A) .
N) a1
D) f
L) ah
A) ! !
N2 e4 d e2
D) p
L) la la la
```

La riga `A) .` lega a `N) a1`; la riga `A) ! !` lega a `N2`.
Dinamiche e lyrics di ciascuna voce sono indipendenti.

### 8.3 Multi-stave con voce 2 sul rigo superiore

```
C) G7
N) | <d b>2 <e c>4 |
N2 | g8 a b a g a b a |
N) (@F) | g,4. d'8 e d |
```

Sistema a due righi. Il rigo superiore (treble) contiene due voci; il
rigo inferiore (basso) è monodico.

### 8.4 Multi-stave con voce 2 sul rigo inferiore

```
C) G7
N) | <d b>2 <e c>4 |
N+ (@F) | g,4. d'8 e d |
N2 | r4 c8 d e d c b, |
```

Sistema a due righi introdotto in questo datapack. La `N2` lega al
rigo introdotto da `N+` (basso), che resta quindi a due voci, mentre
il rigo superiore (treble) è monodico.

### 8.5 Voce 2 alla prima apparizione

```
N) a4

N) c
N2 a

N) c
N2 a
```

- DP1: voce 1 termina con `a4`.
- DP2: voce 1 `c` eredita `a4` → `c5`; voce 2 `a` è alla prima
  apparizione, eredita `a4` da voce 1 all'inizio del datapack → `a4`.
- DP3: voce 1 `c` eredita da voce 1 di DP2 → `c5`; voce 2 `a` eredita
  dal proprio stream (voce 2 di DP2) → `a4`.

### 8.6 Voce sospesa e ricomparsa

```
N) c4
N2 a

N) e

N) c
N2 a
```

- DP1: voce 1 `c4`, voce 2 `a4` (prima apparizione, eredita da voce 1
  → `a4`, intervallo minimo).
- DP2: solo voce 1 → la voce 2 è sospesa.
- DP3: voce 2 ricompare → la regola §4.2 si applica nuovamente; voce 2
  eredita dalla voce 1 di DP3 all'inizio del datapack, non dal proprio
  stream storico.


---

# Grace notes (appoggiature e acciaccature)

Questo documento definisce la sintassi e la semantica delle **grace notes**
in neumaRk: appoggiature e acciaccature, con relativi modificatori grafici
e regole di interazione con il contesto musicale.

Le grace notes sono **eventi musicali ornamentali**: vengono eseguite in
prossimità di una nota reale (la *main*) ma non concorrono al computo
ritmico della misura.

---

## 1. Definizione

Una **grace note** è una nota ornamentale racchiusa tra parentesi quadre
`[ … ]` e ancorata, in posizione adiacente a sinistra, a una **nota reale**
detta *main*.

Una grace note:

- **non occupa tempo**: la sua durata è grafica, non ritmica, e non
  contribuisce al riempimento della misura;
- **deve avere durata esplicita** all’interno delle parentesi quadre;
- **non aggiorna il contesto musicale persistente**: né la pitch né la
  durata di una grace note vengono memorizzate come riferimento per la
  deduzione degli eventi successivi (vedi `neumaRk_specification.md` §2.1).

---

## 2. Sintassi

Un blocco grace è costituito da una **parentesi quadra aperta**, da una
sequenza di **eventi grace** separati da spazi, e da una **parentesi
quadra chiusa**, immediatamente seguita — senza spazi — dalla nota main.

```
[ <grace> [<grace> …] ] <main>
```

### 2.1 Evento grace

Un evento grace è formato da:

1. **Pitch** — obbligatorio, con la stessa sintassi delle note ordinarie
   (vedi `neumaRk_notes_and_durations.md` §2). È ammessa anche la forma
   di **chord-stack** `<…>`. L'**inferenza dell'ottava** ha per
   riferimento la pitch della **main** a cui il blocco è ancorato
   (la nota reale che segue `]`), non il contesto musicale che precede
   il blocco — vedi §7.1.
2. **Durata** — obbligatoria **sul primo evento grace del blocco**; sugli
   eventi successivi è opzionale e, se omessa, **eredita** dal valore
   precedentemente esplicitato nel blocco (vedi §3).
3. **Modificatori** `/` e/o `^` — opzionali, ammessi **solo sull’ultimo
   evento grace del blocco** (vedi §4).

Esempi di eventi grace validi:

```
f#8        g16        <c e g>8       a16/^       g           f#/^
```

Negli ultimi due esempi la durata è omessa: viene ereditata dal valore
esplicito della grace precedente nel blocco. Il primo evento di un
blocco senza durata produce **E009**.

Non sono ammessi all’interno di un evento grace:

- pause (rest);
- annotazioni `"…"`;
- modificatori `!` di forzatura accidente;
- gruppi irregolari (`t`);
- prolungamenti distanziati (`.` separato, `^` distanziato, ripetizione `!`).

### 2.2 Adiacenza con la main

La parentesi quadra di chiusura `]` deve essere **immediatamente adiacente**
alla nota main, senza spazi intermedi.

```
[f#8/^]c4        ✓
[f#8/^] c4       ✗  (spazio tra blocco grace e main)
```

In assenza di adiacenza, il blocco grace non viene riconosciuto come tale
e produce **W003** (vedi §8).

---

## 3. Durate ammesse e ereditarietà

I valori di durata ammessi per una grace note sono esclusivamente:

```
4    8    16
```

**Non sono ammessi**:

- prolungamenti adiacenti (`.`);
- moltiplicatori (`*` o `x`);
- gruppi irregolari (`t`);
- durata indeterminata (`?`).

Una grace note con durata non conforme produce **E009**.

### 3.1 Ereditarietà locale al blocco

La durata del **primo** evento grace del blocco è obbligatoria. Gli
eventi grace successivi, se omettono la cifra di durata, ereditano il
valore esplicitato per ultimo all’interno dello stesso blocco.

```
[f#8 g a]c4         ≡  [f#8 g8 a8]c4
[f#16 g8 a]c4       ≡  [f#16 g8 a8]c4       (a eredita 8, non 16)
[f# g8]c4           → E009 (primo evento senza durata)
```

L’ereditarietà è **strettamente locale al blocco**: non interagisce con
il contesto musicale persistente (vedi §7) né attraversa il `]`. Due
blocchi grace consecutivi non condividono il valore: ognuno deve avere
la propria durata esplicita sul primo evento.

Il valore ereditato viene preservato dal serializer in forma compatta
(no cifra) per round-trip lossless del sorgente.

---

## 4. Modificatori grafici

All’interno della parentesi quadra sono ammessi due modificatori, posti
in coda all’**ultimo evento grace del blocco**, in qualunque ordine:

- `/` — **barrata**: la grace viene resa graficamente con una barra
  obliqua sulla cediglia (acciaccatura);
- `^` — **legata**: la grace è collegata alla main da una legatura
  grafica (slur). Riusa il simbolo `^` della legatura di valore
  (vedi `neumaRk_notes_and_durations.md` §6), in contesto grace.

I due modificatori sono combinabili: `/^` o `^/` indicano una grace
**barrata e legata** alla main, forma tipica dell’acciaccatura classica.

### 4.1 Vincolo di posizione dei modificatori

I modificatori `/` e `^` sono ammessi **soltanto sull’ultimo evento
grace del blocco**. La loro presenza su un evento grace non finale
produce **E010**.

```
[f#8 g8 a16/^]c        ✓
[f#8/]c                ✓
[f#8/ g8]c             ✗  (modificatore su grace non finale → E010)
[f#8/ g8/^]c           ✗  (idem)
```

---

## 5. Cardinalità del blocco

Un blocco grace **deve contenere almeno un evento grace** e **al massimo
quattro**.

- Blocco vuoto `[]` → **E011**.
- Blocco con più di quattro eventi grace → **E012**.

```
[f#8]c                       ✓  (1 grace)
[f#8 g8 a16 b16/^]c          ✓  (4 grace, ultima con modificatori)
[f#8 g8 a16 b16 c16/^]c      ✗  (5 grace → E012)
```

---

## 6. Ancoraggio alla nota main

Il blocco grace **deve essere seguito**, in posizione adiacente, da una
**nota reale** (pitch o chord-stack), che ne costituisce la main.

La nota main:

- è una nota ordinaria a tutti gli effetti, soggetta alle normali regole
  di deduzione di pitch e durata (vedi `neumaRk_notes_and_durations.md`);
- è l’evento ritmicamente rilevante al quale la grace è graficamente
  e musicalmente subordinata.

### 6.1 Blocco grace senza main

Un blocco grace non seguito da una nota main valida (es. ultimo evento
della misura o del datapack, oppure seguito da pausa, barlinea, marker
strutturale) viene **ignorato** dal parser e produce **W004**.

```
| c4 d4 e4 [f#8/^] |       → grace ignorata, W004
| c4 d4 e4 [f#8/^] r |     → grace ignorata, W004 (main non può essere rest)
```

---

## 7. Effetto sul contesto musicale

Una grace note **non altera il contesto musicale persistente**:

- la **pitch** di una grace non viene memorizzata come ultima pitch
  esplicita ai fini della deduzione delle pitch successive;
- la **durata** di una grace non viene memorizzata come ultima durata
  esplicita ai fini della deduzione delle durate successive.

Esempio (in 4/4):

```
c4 [f#8/^]c [f#8/^]c8 c4.
```

- `c4` — main esplicita, contesto: pitch=c, durata=4.
- `[f#8/^]c` — grace `f#8` ignorata ai fini del contesto; main `c`
  eredita durata `4` (ultima durata esplicita rimasta nel contesto).
- `[f#8/^]c8` — main `c8` aggiorna il contesto a durata=8.
- `c4.` — main aggiorna durata=4. (puntato).

Il contesto al termine della sequenza è coerente come se le grace non
fossero mai state scritte.

### 7.1 Inferenza dell’ottava delle grace

La pitch di una grace **deduce l’ottava** rispetto alla pitch della
**main** a cui il blocco è ancorato (la nota reale che segue `]`), non
rispetto al contesto musicale che precede il blocco. Le grace sono
ornamentazioni della main e l’ottava più vicina è quella che le rende
adiacenti al loro target visivo.

Esempio (treble, 4/4):

```
N) a [f8/^]g'
```

- `a` — main, pitch **a4**.
- `g'` — main della grace, pitch **g5** (intervallo minimo da `a4`
  porterebbe a `g4`; il modificatore `'` aggiunge +1 ottava).
- `[f8/^]` — grace `f` con riferimento `g5`: la `f` più vicina a `g5`
  è **f5** (un tono sotto), non `f4` (che disterebbe una nona). Risultato:
  grace **f5** → main **g5**, intervallo di seconda maggiore discendente.

All’interno del blocco grace, le ottave dei singoli eventi grace si
calcolano in **catena**: il **primo** evento grace è ottava-inferito
dalla main; i **successivi** sono ottava-inferiti dall’evento grace
precedente nello stesso blocco (inferenza monodica standard
intra-blocco). La chain del contesto della linea, invece, **non
attraversa** il blocco: l’evento subito dopo la main eredita il
contesto della main, non delle grace (vedi §7).

---

## 8. Rendering degli accidenti

Per la resa grafica degli accidenti, una grace note **non aggiorna** lo
stato di propagazione della misura, ma **lo influenza**. Tre regole.

### 8.1 Accidente sulla grace

L’accidente viene **disegnato sulla grace** se e soltanto se la pitch
della grace devia dalla **matrice corrente** della misura (cioè dalla
key signature aggiornata dagli accidenti già occorsi nella misura prima
del blocco grace).

In altre parole, il criterio è lo stesso che si applica alle main: la
grace mostra un accidente quando suona "inatteso" rispetto allo stato
visivo corrente.

Esempi (key signature: G major, F# in chiave; 4/4):

| Contesto a sinistra | Input grace | Resa grafica della grace                 |
|---------------------|-------------|------------------------------------------|
| (misura nuova)      | `[f#8/^]c`  | nessun accidente (F# coincide con chiave)  |
| `f4` (F♮)           | `[f#8/^]g`  | `#` (matrix=’f’→♮, la grace ne devia)   |
| (misura nuova)      | `[f8/^]c`   | `♮` (F♮ devia da F# in chiave)            |
| (misura nuova)      | `[g8/^]c`   | nessun accidente (G♮ coincide con chiave)  |
| `g#4`               | `[g#8/^]c`  | nessun accidente (matrix=’g’→# dopo `g#4`) |

### 8.2 Rottura della propagazione dopo la grace

Una grace che **devia dalla matrice corrente** (cioè una grace che ha
fatto disegnare un accidente per §8.1) **rompe** la propagazione degli
accidenti per le main successive della misura aventi la stessa
pitch-letter e ottava.

Concretamente, dopo una grace di questo tipo, ogni main successiva con
stessa (lettera, ottava) deve riportare a video un accidente esplicito
(`#`, `b` o `♮`), anche se la matrice corrente coincide con la pitch.

Esempio (key signature: G major; misura in 4/4):

```
f4 [f#8/^]g4 f4
```

Resa grafica:

| Evento       | matrix[‘f’][4] prima  | Accidente a video                          |
|--------------|-----------------------|--------------------------------------------|
| `f4` (F♮)    | 1 (F# da key sig)     | `♮` (devia dalla matrice). matrix → 0      |
| `[f#8/^]g4`  | 0 (dopo `f4`)         | `#` sulla grace (devia, §8.1). matrix → 0  |
| `f4` (F♮)    | 0                     | `♮` (precauzionale, propagazione rotta)    |

Nota: la grace **non aggiorna** la matrice. La main `f4` finale legge
ancora `matrix[‘f’][4] = 0` (lo stato lasciato dal primo `f4`); senza
§8.2 non mostrerebbe alcun accidente. Il `♮` precauzionale è imposto
dal "broken propagation" registrato dalla grace.

### 8.3 Indipendenza interna al blocco

All’interno di un blocco grace, ciascun evento grace è isolato rispetto
agli altri ai fini del rendering: poiché nessuna grace aggiorna la
matrice (§8.1 / regola implicita), tutte le grace del blocco vedono la
stessa matrice di partenza, valutate indipendentemente l’una dall’altra.

> **Nota.** Le regole di §8 riguardano esclusivamente la **resa grafica**.
> L’input neumaRk usa sempre pitch assolute: `f` denota F♮, `f#` denota
> F#, indipendentemente da contesto e key signature.

---

## 9. Esempi riassuntivi

Acciaccatura classica (barrata, legata):

```
N) c4 [f#8/^]c [f#8/^]c8 c4.
```

Appoggiatura semplice (non barrata, non legata):

```
N) c4 [f#8]c4
```

Appoggiatura legata, non barrata:

```
N) c4 [f#8^]c4
```

Cluster di grace (legatura sull’ultimo):

```
N) c4 [d8 e8 f8/^]g4
```

Grace con accordo:

```
N) c4 [<c e g>8/^]c4
```

---

## 10. Errori e warning

| Codice | Tipo    | Condizione                                                                                                |
|--------|---------|------------------------------------------------------------------------------------------------------------|
| E009   | error   | Durata grace mancante sul primo evento del blocco, oppure durata non conforme (ammesse soltanto `4`, `8`, `16`) |
| E010   | error   | Modificatore `/` o `^` su evento grace non finale del blocco                 |
| E011   | error   | Blocco grace vuoto `[]`                                                       |
| E012   | error   | Blocco grace con più di quattro eventi grace                                  |
| E013   | error   | Pause non ammesse come evento grace (es. `[r8]c`)                              |
| W003   | warning | Blocco grace non adiacente a una nota main (spazio tra `]` e main)            |
| W004   | warning | Blocco grace senza nota main a destra; il blocco viene ignorato               |

Ulteriori condizioni di errore generali (pitch non valida, durata
malformata, parentesi quadre non bilanciate, ecc.) ricadono sulle
diagnostiche già definite per le note ordinarie.

---

## 11. Limitazioni note

In questa versione della specifica, le grace notes:

- non ammettono articolazioni, dinamiche né annotazioni;
- non ammettono pause (rest) come eventi grace;
- non sono valide nelle righe di accordi (`C)`), né nelle righe
  di chord-rhythm: il costrutto `[ … ]` è riservato alle righe `N)`.

Estensioni a questi vincoli saranno oggetto di versioni successive.


---

# Articolazioni (riga `A)`)

> **STATO: SPEC.** §1-§7 sigillate 2026-05-23 (deduzione `A)` attuale, già nel
> parser); §8-§12 sigillate 2026-05-24 (estensioni: modello token, glissato `gl`,
> span legatura/onda). **Implementate** end-to-end (parser Fase 3.1 + rendering
> 3.1b); stato/dettagli in `neumaRk_changelog.md §0.6`. Limite noto: la collisione
> verticale onda↔legatura è un follow-up di layout. Binding e ordine non sono
> ridefiniti qui: vedi `neumaRk_datapack.md §2.1` e §3. Decisioni di sigillo in §7
> (base) e §12 (estensioni).

## 1. Definizione

La riga `A)` (Articulations) porta le **articolazioni e gli ornamenti** da
applicare, posizione per posizione, agli eventi della riga musicale a cui è
legata. È un layer parallelo: non altera ritmo, durate o flusso, solo gli
attributi notazionali degli eventi.

## 2. Posizione strutturale e binding

Marcatore, opzionalità e ordine logico sono definiti in `neumaRk_datapack.md`
§2.1 (tabella marcatori) e §3 (ordine implicito: `A)` è **opzionale e precede**
la riga `N)` del proprio gruppo di note). In sintesi operativa:

- `A)` **lega alla riga sotto** ("modello §4.A.5"): i suoi token sono messi in
  attesa (*pending*) e drenati sul primo target musicale successivo nello stesso
  gruppo/rigo.
- Target del drain, in ordine di priorità:
  1. la **chord-rhythm** della riga `C)` immediatamente sotto — **solo per lo
     stave 0** (il chord-rhythm vive in `MeasureShared`), se la `C)` ha ritmo;
  2. altrimenti la riga `N)` dello **stesso stave**.
- In multi-stave ogni rigo ha il proprio bucket di pending; la **voce 2** (`N2`)
  ha un bucket `A)` indipendente (vedi `neumaRk_voices.md §3.1`).

## 3. Vocabolario

Ogni token è un simbolo (o combinazione) che mappa a un'articolazione o
ornamento. I token sono separati da spazio; più articolazioni sulla **stessa**
nota si scrivono come token unico senza spazi (es. `>!`).

| Token | Significato            | Tipo         |
| ----- | ---------------------- | ------------ |
| `-`   | tenuto                 | articolazione |
| `>`   | accento                | articolazione |
| `!`   | staccato               | articolazione |
| `^`   | marcato                | articolazione |
| `+`   | pizzicato (mano sx)    | articolazione |
| `o`   | fermata (sopra)        | articolazione |
| `os`  | fermata breve          | articolazione |
| `ol`  | fermata lunga          | articolazione |
| `-!`  | portato (tenuto+staccato) | combinazione |
| `>!`  | accento staccato       | combinazione |
| `tr`  | trillo                 | ornamento    |
| `m`   | mordente               | ornamento    |
| `M`   | mordente inverso       | ornamento    |
| `t`   | gruppetto              | ornamento    |
| `T`   | gruppetto inverso      | ornamento    |
| `,`   | respiro                | ornamento    |
| `h`   | armonico               | articolazione *(estensione §8+)* |
| `v`   | arco in su             | articolazione *(estensione §8+)* |
| `n`   | arco in giù            | articolazione *(estensione §8+)* |
| `.`   | **placeholder**: nessuna articolazione su quella posizione | — |

> `h` per l'armonico (il simbolo `°` non è ASCII e `o` è già fermata); `v`/`n`
> per gli archi (`n` ricorda il ⊓). A questi si aggiungono un token **per-coppia**
> (glissato `gl`, §9) e due **span** (legatura `( )`, onda `~`, §10), introdotti
> dal modello di token decomponibile in §8.

Il vocabolario è l'**insieme chiuso** della tabella sopra (più il placeholder
`.`, i per-coppia/span delle estensioni §8+). Solo questi token sono articolazioni
valide; il **charset di classificazione del parser deriva da questo insieme**
(vedi §6 e §11). Un token fuori dal vocabolario non è un'articolazione valida.

I marcatori `>` e `^` rendono una riga **univocamente** articulations in fase di
classificazione (`articulations_specific_marker`): nessun'altra riga musicale li
usa isolati.

## 4. Allineamento count-based

La corrispondenza con gli eventi della riga target è **strettamente posizionale
per conteggio** (come `neumaRk_dynamics.md §4.1`), left-to-right:

```
N) | a8 b  c  d |
A) | >  .  !  ^ |
     ↑      ↑  ↑
   accento staccato marcato (b: nessuna)
```

- Il token `.` o un token vuoto = **nessuna** articolazione su quella nota.
- Se i token sono **meno** delle note, le note residue restano senza
  articolazione (no-op).
- Se i token sono **più** degli eventi, gli extra sono **scartati
  silenziosamente** (filosofia auto-fix; nota: a differenza di `D)` non viene
  emesso un warning — vedi Decisioni aperte).
- L'allineamento **conta anche i rest** (a differenza di `L)`, che li salta):
  una posizione sopra un rest è un evento a tutti gli effetti. È ciò che permette
  a uno span (§10) di **coprire un rest** (vi si scrive `~` e lo span prosegue).

## 5. Esempi

```
A) | >    !  |
N) | c4 d e f |     accento su c, staccato su e

A) | >!         |
C) | C7  F7     |     accento-staccato sul primo evento di chord-rhythm (stave 0)
```

## 6. Il vocabolario è parte della deduzione (fonte unica)

Il parser **non è agnostico** rispetto a questo vocabolario: per dedurre che una
riga prefix-less è `A)` deve riconoscerne i token. Storicamente il vocabolario era
**diviso e duplicato** — metà sintattica nel parser (charset di
`articulations_line` / `articulations_specific_marker`, usato per la
classificazione) e metà semantica nel renderer (`nrkArticToModifiers`, token-NRK →
codice VexFlow) — e le due metà divergevano (il charset ammetteva `_` e lettere
isolate non mappate).

**Modello normativo (deciso 2026-05-23): questo documento è la fonte unica.** La
spec definisce `token-NRK → significato musicale` (es. `!`→staccato); il
*significato* è normativo, i codici VexFlow no (un altro renderer ne userebbe
altri). Da questa tabella **derivano**: il charset di classificazione e la
tokenizzazione del parser; la mappa `significato → glifo` del renderer.

## 7. Decisioni (chiuse 2026-05-23)

1. **Fonte unica** ✓ — la spec è normativa; charset-parser e mappa-renderer ne
   derivano. Elimina il drift.
2. **Vocabolario = insieme chiuso** ✓ — i simboli fuori tabella (es. `_`, lettere
   isolate) **non** sono articolazioni valide; il charset va ristretto al
   vocabolario.
3. **Eccesso di token** ✓ — `A)` emette **W131** come `D)` (era silent drop).
4. **Significato normativo, VexFlow implementativo** ✓ — la colonna "significato"
   è vincolante; i codici `a-`/`a>`/… sono nota d'implementazione.

> **Follow-up lato codice** (D(L)→D(P), tracciato in
> `docs/feature-deduction-spec-audit.md`), tutti ✅ fatti (Fase 3.1): charset di
> classificazione derivato dal vocabolario chiuso; **W131** su eccesso token;
> **W139** (validazione lessicale) su qualsiasi token con sequenza fuori-vocabolario,
> inclusa la lettera-frammento isolata (`s` di `os`, `r` di `tr`).

---

# Estensioni `A)` (sigillate 2026-05-24)

> Le sezioni §8-§12 sono **normative e implementate** (parser Fase 3.1 + render
> 3.1b). Estendono il vocabolario per-posizione di §3 con: un modello di token
> decomponibile (§8), un token per-coppia (glissato `gl`, §9) e due span (§10).

## 8. Modello del token: decomposizione e co-locazioni

Il vocabolario base (§3) usa, nel parser attuale, uno `switch` su token interi
(`nrkArticToModifiers`, con `case ">!"`). Le estensioni richiedono un vero
**decompositore per-posizione**, analogo a `parseDynamicsToken` di `D)`.

Ogni **posizione** (token separato da spazi) è una **concatenazione order-free**
di **elementi**, decomposta con **greedy longest-match** sugli atomi multi-char
(prima `os`/`ol` di `o`, prima `tr` di `t`):

```
elemento :=
  | onda            ~[1-4]? ("…")?      # §10.2 (cifra/etichetta solo in apertura)
  | legatura-apre   (                    # §10.1
  | legatura-chiude )                    # §10.1
  | staffa-apre     [ ("…")?             # §10.3 (etichetta solo in apertura)
  | staffa-chiude   ]                    # §10.3
  | ottava-apre     8u | 8d              # §10.4 (alta / bassa)
  | ottava-chiude   8.                   # §10.4 (8 + punto)
  | glissato        gl                   # §9 (verso la nota successiva)
  | fermata         o | os | ol          # greedy: os/ol prima di o
  | trillo          tr                   # greedy: tr prima di t
  | gruppetto       t | T
  | mordente        m | M
  | per-nota 1ch    - > ! ^ + , h v n
  | placeholder     .                    # nessun elemento su quella posizione
```

Conseguenza: **`-!` e `>!` non sono più token speciali** ma **co-locazioni**
(`-`+`!` = portato; `>`+`!` = accento-staccato). Tutte le combinazioni emergono
dalla concatenazione: `(!` = legatura-apre + staccato; `>gl` = accento + glissato.
La voce "combinazione" della tabella §3 resta valida come *significato*, non come
token atomico.

> La **decomposizione** (tokenize) è separata dalla **risoluzione degli span**
> (post-pass), come `D)` separa `parseDynamicsToken` da `extract_hairpins` (§10).

## 9. Glissato fra note (`gl`)

`gl` sulla posizione di una nota = quella nota **glissa verso la successiva**. La
direzione (su/giù) è implicita dalle due altezze. È **per-coppia**, non uno span.

```
A) .  gl .  .
N) r4 a  b  r       # a glissa verso b
```

Distinto dal **glissato di singola nota** (scoop/fall, entrata/uscita da *una*
nota), che vive in `N)` come modificatore fra parentesi — vedi
`neumaRk_notes_and_durations.md` (estensioni N).

## 10. Span

Due span, mutuati dal modello di `D)` (apertura/chiusura risolte in un post-pass).

### 10.1 Legatura di portamento `( )` (span delimitato)

Stile LilyPond: `(` apre sulla nota della sua posizione, `)` chiude sulla nota
della sua posizione; la curva copre dall'apertura alla chiusura.

```
A) . ( . . )
N) c d e f g      # legatura da d a g
```

- **Cross-barline**: sì.
- **Confinata al rigo**: una legatura aperta a fine rigo si **chiude lì con
  warning**; una `)` orfana → **warning**, ignorata.
- **No sovrapposizione/annidamento (v1)**: al massimo una legatura aperta per
  volta; un secondo `(` mentre una è aperta → **warning**. (Annidamento rinviato.)
- **Apertura+chiusura sulla stessa nota** (`()`): degenere → ignorata/warning.
- **Co-locabile** coi per-nota: `(!` = legatura-apre + staccato.

### 10.2 Onda `~[1-4]` (span per ripetizione)

Una linea ondulata **sempre sopra** il rigo. Unifica **vibrato / shake /
long-vibrato / laid-back**: l'**ampiezza** è la larghezza visiva, l'**etichetta**
ne dà il nome.

**Ampiezza** — cifra opzionale `1`–`4` (default `~` = livello 1):

- `~N` (con cifra) **apre un nuovo span** di ampiezza N, **chiudendo** quello
  corrente;
- `~` (nudo) **estende** lo span corrente; se nessuno è aperto, ne apre uno di
  livello 1.

```
A) ~3 ~ ~ ~1 ~ ~      # onda grande su 3 note, poi onda piccola su 3
```

**Estensione e rest**: `~` consecutivi (anche **cross-barline**) = un'unica onda;
una posizione **senza `~`** (inclusa una misura vuota) chiude lo span. I **rest non
interrompono** (l'allineamento conta i rest, §4).

```
A) ~2 ~ ~ ~ |   | ~3 ~ ~ ~
N) a4 b r c | d | a4 b r c
#  └─ ampiezza-2 su a b r(rest) c ─┘  (mis.2 vuota → niente onda)  └─ ampiezza-3 ─┘
```

**Etichetta** (opzionale, solo sul token di **apertura**): `"…"` subito dopo
l'onda, resa sopra il suo inizio. L'etichetta è un **container di text markup**
(`neumaRk_text_markup.md` §2.2): accetta i marcatori `#`/`##`/`###`, `*`/`**`,
`__`; il **default è tondo** (corsivo/grassetto/underline/size solo via i
marcatori). Ampiezza ed etichetta sono indipendenti.

```
A) ~3"shake" ~ ~ ~
A) ~"vibrato" ~ ~
A) ~4"laid back" ~ ~ ~ ~
```

L'etichetta dà la **semantica** (vibrato vs shake vs laid-back); il glifo `~` da
solo è solo "onda di ampiezza N". Per uno strumento di trascrizione la pagina è la
verità; un eventuale playback inferirà da etichetta/ampiezza.

### 10.3 Staffa d'analisi `[ ]` (span delimitato)

Una **staffa di raggruppamento** sopra il rigo, come le parentesi dell'analisi
formale. `[` apre sulla nota della sua posizione, `]` chiude su quella della sua
(stile LilyPond, esattamente come la legatura §10.1).

```
A) . . ["triade di DO" . . ] |
N) a a c            e | g e c a
```

- **Etichetta** (opzionale): stringa `"…"` **subito dopo** `[` (riusa lo stesso
  token opaco dell'onda). Resa **allineata a sinistra** sopra l'apertura ed è un
  **container di text markup** (`neumaRk_text_markup.md` §2.2: `#`/`*`/`__`),
  **tonda di default**. Una staffa **senza** etichetta (`[ … ]`) è ammessa.
- **Resa**: parentesi quadra **sempre sopra** il rigo, con i due montanti
  rivolti **verso il basso** (verso le note).
- **Cross-barline / cross-system**: sì.
- **No overlap/annidamento (v1)**: al più una staffa aperta per volta; una
  seconda `[` con una aperta → **warning** (`W144.bracket_open_overlap`); una
  `]` orfana → **warning** (`W144.bracket_close_unmatched`); `[]` degenere
  (apertura+chiusura sulla stessa nota) → **warning** (`W144.bracket_degenerate`);
  staffa non chiusa a fine rigo → **chiusura implicita + warning**
  (`W144.bracket_unclosed_eol`).
- **Puramente grafica**: nessun effetto sul playback (è un'annotazione analitica).
- **Nota di sintassi**: nelle righe `A)` un `[ … | … ]` è una staffa che
  attraversa la barra, quindi il `|` interno è una **barline reale** — NON un
  polychord `[X|Y]` (§accordi) né una volta `[1.`. La mappa sopprime il
  rilevamento polychord sulle righe Articulations.

### 10.4 Ottava `8u` / `8d` … `8` (span delimitato)

Una linea di **ottava**. `8u` apre un'**8va alta**, `8d` apre un'**8vb bassa**;
`8.` **chiude** lo span (inclusivo sull'ultima nota coperta). **Delimitata**
come la legatura (§10.1) — volutamente NON il modello a estensione dell'onda
(§10.2): la linea d'ottava è rada, ripetere un token su ogni nota sarebbe
macchinoso. Un `8` nudo (senza `u`/`d`/`.`) è **fuori-vocabolario** (probabile
refuso di `8.`) → `W139`.

```
A) . . . . . . . 8u . . . | . . . 8. |
N) c d e f g a b c  d e f | a g f e d c b a g
#                  └─ 8va dall'8ª nota, attraverso la barra, fino alla chiusura ─┘
```

- **Resa**: la sigla SMuFL standard — **`8va`** (alta, glifo `U+E511`) / **`8ba`**
  (bassa, glifo `U+E513`) — seguita da una linea orizzontale **tratteggiata** e un
  **gancio finale** verso il rigo; **sopra** per `8u`, **sotto** per `8d`. (Entrambi
  i glifi sono nel subset BravuraLS/PetalumaLS.)
- **Playback**: le note coperte sono **trasposte di ±12 semitoni** (`8u` = +12,
  `8d` = −12). L'**altezza scritta resta invariata** — le teste-nota non si
  muovono; solo la riproduzione viene spostata.
- **Cross-barline / cross-system**: sì.
- **No overlap/annidamento (v1)**: seconda apertura con una aperta → **warning**
  (`W144.octave_open_overlap`); `8.` di chiusura orfano → **warning**
  (`W144.octave_close_unmatched`); `8u8.` degenere → **warning**
  (`W144.octave_degenerate`); apertura non chiusa a fine rigo → **chiusura
  implicita + warning** (`W144.octave_unclosed_eol`).

> **Convenzione span** (decisa per `A)`, da riusare per le forcelle/`cresc.` di
> `D)`): ogni span lungo è **delimitato** — un token di apertura (eventualmente
> parametrizzato) + un token di chiusura; le posizioni intermedie sono
> placeholder `.`. Legatura `( )`, staffa `[ ]` e ottava `8u…8` la seguono.
> L'**onda `~`** mantiene il modello a **estensione** come unica eccezione
> documentata, perché il suo glifo è una linea ondulata *continua* su ogni nota.

## 11. Impatto sulla deduzione (charset esteso)

Le estensioni allargano la superficie di classificazione delle righe
(`neumaRk_datapack.md §3.bis`):

- **Charset `A)`**: include i nuovi simboli `( ) ~ h v n g` e le cifre `1-4`, più
  `[ ] 8 u d` (§10.3 staffa, §10.4 ottava), oltre al vocabolario base §6 (da cui
  il charset è derivato — fonte unica).
- **`~` è marker specifico**: una riga che contiene `~` è classificata
  **univocamente** come `A)`, malgrado le cifre che altrimenti la avvicinerebbero a
  chords/notes.
- **`[` `]` `8` `d` NON sono marker specifici**: sono molto sovraccarichi (`[` =
  sezione `[NAME]`, etichetta alternate-chord, grace/annotation in `N)`; `8`/`d`
  = durata/nota). Allargano solo il charset `A)`; la priorità notes-line (TB4)
  protegge le righe `N)`, e una riga staffa/ottava implicita richiede il prefix
  esplicito `A)` per essere classificata come articolazioni.
- **`g`/`gl` vs nota G — TB4**: `g` (testa del token `gl` glissato, §9) è anche
  la nota G, e con le durate `1`–`4` rende ambigue righe come `g`, `g4`, `g g g`.
  La regola **TB4** (`neumaRk_datapack.md §3.bis.5`) dà priorità alle note: una
  riga che è una **notes-line valida** (ogni token matcha la grammatica `parse_notes`
  + almeno un pitch reale) è `N)`, non `A)`. Il token `gl` non è una nota valida,
  quindi una riga di articolazioni con `gl` resta `A)`.
- **Quote-aware**: il contenuto di un'etichetta `"…"` (es. `shake`) è escluso dal
  match di classificazione — lettere fuori-charset o un `~` *dentro il testo* non
  rompono né marcano falsamente la riga.

## 12. Decisioni (estensioni, chiuse 2026-05-24)

1. **Glissato fra-note (`gl`, §9) ≠ glissato singola-nota** (scoop/fall, in `N)`). ✓
2. **Vocabolario esteso = insieme chiuso**; significato normativo, codici VexFlow
   implementativi (eredita §6/§7). ✓
3. **Modello token unificato** (decompositore + co-locazioni, §8). ✓
4. **Legatura `( )`** delimitata, no overlap v1 (§10.1). ✓
5. **Arco su `v`, giù `n`; armonico `h`** (§3). ✓
6. **Onda `~`**: livelli 1–4; cifra = nuovo span, nudo = estende; sempre sopra;
   copre i rest; etichetta `"…"` in apertura, corsivo (§10.2). ✓
7. **Shake / long-vibrato / laid-back unificati** nell'onda `~N` + etichetta. ✓
8. **Staffa d'analisi `[ ]`** delimitata, etichetta `"…"` opzionale, sempre
   sopra, puramente grafica; no overlap v1 (§10.3). ✓ *(aggiunta 2026-05-31)*
9. **Ottava `8u`/`8d` … `8.`** delimitata (`8.` chiude), tratteggiata sopra/
   sotto, **trasporta il playback ±12**; no overlap v1 (§10.4). ✓ *(2026-05-31)*
10. **Convenzione span**: gli span lunghi sono delimitati (apertura + chiusura);
    l'onda è l'unica eccezione (estensione), avendo un glifo a linea continua. ✓


---

# Dinamiche e annotation testuali

Questo documento definisce la sintassi e la semantica della **riga di
dinamiche** `D)` in neumaRk: vocabolario degli elementi, allineamento
agli eventi musicali, sintassi delle annotation testuali, regole di
estensione e diagnostica.

La riga `D)` è la **fascia annotativa sotto il rigo**: ospita le
indicazioni dinamiche tradizionali (`p`, `mf`, `ff`, hairpin, cresc./dim.)
e — coerentemente con la pratica jazz/lead-sheet — anche **annotation
testuali** ancorate a eventi musicali (es. "drums fill", "freely",
"w synth") o alle stanghette di misura (es. "Vamp till cue").

---

## 1. Definizione

La riga `D)` è una **riga musicale opzionale** del datapack
(`neumaRk_datapack.md` §3, gruppo di note) che descrive eventi sotto-pentagramma
allineati per posizione agli eventi della riga `N)` parent.

Esistono **due classi ortogonali** di elementi in `D)`:

1. **Elementi note-anchored** — token in corrispondenza 1:1 con le note
   della riga `N)` parent (o `N2`). La classe principale.
2. **Elementi barline-anchored** — annotation testuali ancorate
   all'inizio o alla fine di una misura, indipendentemente dagli eventi
   note interni.

Le due classi convivono nella stessa riga: barline-anchored sono
riconoscibili per **adiacenza a un bordo barline composto**;
note-anchored sono tutti gli altri token.

---

## 2. Posizione strutturale e binding

La riga `D)` segue le regole generali del gruppo voce
(`neumaRk_datapack.md` §3, gruppo di note, e `neumaRk_voices.md` §3.1):

```
[A)]  N)|N2|N+  [D)]  [L)]
```

- è opzionale; può apparire al massimo **una** per gruppo voce;
- è legata alla **riga `N)` / `N+` / `N2` immediatamente precedente**;
- segue le stesse stanghette di misura (`|`, `||`, `:|`, `|:`, ecc.) e
  gli stessi decoratori di misura della riga parent.

Una riga `D)` non legata a una `N)`/`N+`/`N2` valida nello stesso
datapack produce warning **W130**.

---

## 3. Vocabolario degli elementi

### 3.1 Dynamic puntuali

Marcatori dinamici tradizionali, ognuno **puntuale** (vale su una sola
nota):

```
p   mp   mf   f   ff   fff   pp   ppp   pppp   ffff   sf   sfz   fp
```

Non si estendono nel tempo: il volume implicato dal mark vale per il
beat dell'evento e — interpretativamente — fino al prossimo dynamic
mark, ma graficamente compare una sola volta.

### 3.2 Hairpin grafici

Due token, ognuno renderizzato come segno grafico (crescendo/decrescendo
"a forcina"):

| Token | Effetto       |
|-------|---------------|
| `<`   | crescendo     |
| `>`   | decrescendo   |

I hairpin si estendono **per ripetizione**: una sequenza `< < <` su tre
note produce un singolo segno grafico che copre quelle tre note. Una
singola occorrenza è ammessa (puntuale).

### 3.3 Hairpin testuali

Due token brevi che generano un'indicazione **testuale** con linea di
estensione tratteggiata:

| Token | Rendering       |
|-------|-----------------|
| `c`   | "cresc. - - - - " |
| `d`   | "dim. - - - - "   |

Si estendono per ripetizione, esattamente come §3.2: una sequenza
`c c c c` produce un'unica scritta "cresc." seguita da una linea
tratteggiata che copre le quattro note.

**Co-locazione con hairpin grafico (`c<` / `d>`)**: quando `c` e `<`
(o `d` e `>`) compaiono sulla stessa nota come token co-located, vince
la forcella **grafica**. Il token testuale è ignorato dal post-pass di
estrazione hairpin. Per ottenere il testo "cresc."/"dim." senza
forcella, usare `c`/`d` da soli. Per ottenere entrambi i segni
contemporaneamente serve scriverli su note diverse (es. `c <` su due
note adiacenti).

**Compound testuali `pc` / `fd`**: NON sono supportati. Un token
co-located con dynamic puntuale seguito da hairpin testuale (es. `pc`,
`fd`) produce solo il dynamic puntuale; l'hairpin testuale viene
ignorato. Per esprimere "p e poi cresc." scrivere su due note: `p c`.

### 3.4 Annotation testuali

Container testuali con o senza box (vedi `neumaRk_text_markup.md` §2):

| Forma     | Effetto                                          |
|-----------|--------------------------------------------------|
| `"text"`  | annotation senza box                             |
| `[text]`  | annotation con box                               |

Il contenuto del container è soggetto al **markup unificato** definito
in `neumaRk_text_markup.md`. Lo **stile di default** delle annotation
`D)` è *plain, dimensione ridotta*: italic, bold e underline sono
applicati solo se richiesti esplicitamente tramite il markup utente
(`*…*`, `**…**`, `__…__`).

Le annotation testuali sono **puntuali** di default; diventano
**estese** se seguite da `-` adiacente (vedi §5).

### 3.5 Placeholder `.`

Il token `.` indica **nessun elemento** sulla nota corrispondente.
Serve a "saltare" una nota mantenendo l'allineamento posizionale.

Il `.` ha anche un ruolo **chiusura**: una `.` su una nota interrompe
qualunque extension testuale in corso (vedi §5.4).

### 3.6 Continuation `-`

Il token `-` come **token standalone** (separato da spazi) significa
"prosegue l'extension testuale aperta a sinistra". Si applica alle sole
annotation testuali (vedi §5).

`-` ha anche un ruolo **adiacente** (senza spazi) come marcatore di
apertura extension (`"text"-`) o di ancoraggio barline
(`[1.]-"text"`, `"text"-:|`). I tre ruoli sono distinguibili per
posizione e adiacenza (vedi §4, §5, §6).

---

## 4. Elementi note-anchored

### 4.1 Corrispondenza 1:1 con la riga `N)` parent

Ogni token note-anchored della riga `D)` cade su una nota della riga
parent, in ordine left-to-right. La corrispondenza è strettamente
posizionale:

```
N) | a8 b c d e f g a |
D) | p  .  .  < < < f .  |
     ↑           ↑   ↑
   nota 1     note 4-6  nota 7
```

### 4.2 Co-locazione: più elementi sulla stessa nota

Più elementi sulla stessa nota si scrivono come **token unico** senza
spazi interni:

```
N) | a4    b   c   d |
D) | f"piano fill"   .   c<   .  |
     ↑ 3 elementi sulla stessa nota: f + "piano fill" + (nessuno su b)
```

L'ordine degli elementi co-located è **libero**: `f"text"c<` e
`"text"<fc` sono equivalenti dal punto di vista semantico (stessa nota,
stessi elementi). Il renderer può applicare un ordine canonico in
display.

### 4.3 Autofill di note residue

Se la riga `D)` contiene **meno** token note-anchored della riga `N)`
parent, le note residue ricevono un `.` **implicito**:

```
N) | a a a a a a a a |
D) | f               |     ≡  D) | f . . . . . . . |
```

Se la riga `D)` contiene **più** token di quanti siano gli eventi nota
nella riga parent (extra-token), produce warning **W131**.

### 4.4 Misure e barline

La suddivisione in misure è definita dalle stanghette `|` come per le
altre righe musicali. Le stanghette di `D)` devono allinearsi a quelle
della riga parent (regole generali di `neumaRk_datapack.md` §6).

---

## 5. Estensione testuale `-`

### 5.1 Solo i testi sono estendibili

Le annotation testuali (`"text"`, `[text]`) sono **gli unici elementi
estendibili tramite trattino `-`**. Dynamic puntuali (§3.1) non si
estendono per loro natura; hairpin grafici e testuali (§3.2, §3.3) si
estendono per **ripetizione**, non con `-`.

### 5.2 Apertura

Un trattino `-` **adiacente** (senza spazi) a destra di
un'annotation testuale apre un'extension:

```
D) | "intro"-  -  -  -  mp |
       ↑ apre extension     ↑ chiude
```

In un gruppo co-located, il `-` adiacente vale per l'annotation testuale
del gruppo, non per gli altri elementi:

```
D) | ff"drums fill"-  -  -  -  -  -  -  ppp  -  -  -  - |
       ↑ apre extension del testo (ff resta puntuale sulla nota 1)
                                   ↑ ppp puntuale, chiude "drums fill"
```

### 5.3 Continuazione

Un `-` **standalone** (token separato da spazi) prosegue l'extension
aperta a sinistra. Funziona per qualunque numero di note successive,
**anche attraverso le stanghette di misura**:

```
N) | a16 a a a a a a a    a a a a a a a a | a8 a a a a a a a |
D) | ff"drums fill"- - - - - - - ppp- - - - - - - - -   -  - - - pp
     ─────── extension 1 ───────┘ ───── extension 2 ────────┘   ── pp puntuale
                                                          (continua cross-bar)
```

### 5.4 Chiusura

Una extension testuale termina quando si incontra **uno dei seguenti
eventi**:

- un **nuovo elemento** note-anchored *senza* `-` adiacente sopra di
  sé (dynamic mark, hairpin, annotation, placeholder `.`);
- la **fine del system** corrente (chiusura implicita);
- una nuova annotation testuale aperta con `-` adiacente: chiude la
  precedente e ne apre una nuova;
- un **nuovo begin-bar anchor** `-"text"` (vedi §6.2) come primo
  token di una misura: chiude l'extension precedente sulla nota
  immediatamente anteriore e apre un nuovo ancoraggio begin-bar
  allineato alla barline di apertura della misura corrente.

L'ultima regola si applica anche quando l'extension precedente è
cross-bar barline-anchored (apertura `-"prev"- … -` continua sulle
misure intermedie): un nuovo begin-bar `-"new"` la **chiude
implicitamente** e ne apre uno nuovo, allineato al bordo barline di
ingresso della misura corrente. Non occorre chiusura esplicita.

Esempio:

```
D) | "intro"- - - - - - - - | -"new"  p . . ff |
       ↑ extension aperta      ↑ chiude "intro" sulla nota 8 della
                                misura precedente, apre "new"
                                begin-bar nella misura corrente
```

Per chiudere esplicitamente prima della fine del system senza aprire
un nuovo ancoraggio, inserire `.` (placeholder) o un altro elemento
note-anchored privo di `-` adiacente.

### 5.5 Cross-bar libero

La stanghetta di misura `|` (e le sue varianti composte) è
**trasparente** all'extension testuale: un `-` continua attraverso `|`
senza necessità di sintassi speciale. Per ancorare un'annotation alla
barline anziché a una nota interna, si usa la forma barline-anchored
(§6).

### 5.6 Extension parallele

Più extension parallele (es. testo + hairpin) si ottengono per
**combinazione delle regole**: il testo si estende con `-`, il hairpin
si ripete per nota. Non esiste un meccanismo `-` per estendere
hairpin:

```
N) | a a a a a a a a |
D) | "cresc."- - - - < < < < |
     ↑ testo esteso            ↑ hairpin grafico per 4 note
```

Il rendering presenta entrambi i segni nella fascia D), con regole di
posizionamento verticale a cura del renderer.

---

## 6. Elementi barline-anchored

### 6.1 Contesto: bordo barline e contenuto di D)

In neumaRk un "bordo barline" è il **gruppo composto** formato dalla
stanghetta `|` e dai suoi decoratori adiacenti: ripetizione (`:`),
cambio metro/tonalità (`(3/4)`, `(@F)`), volta (`[1.]`, `[2.]`),
conteggio ripetizioni (`:x3`), ecc. Il bordo barline è proprietà della
**riga** (vedi `neumaRk_datapack.md` §6) ed è **comune a tutte le righe
musicali** del datapack: D) non lo replica nel proprio contenuto.

Di conseguenza, il **contenuto di D) per ciascuna misura** è il testo
fra una barline e la successiva, **escluso** ogni decoratore del bordo
barline. È su questo contenuto pulito che si applicano le regole di
ancoraggio di §6.2-§6.4.

### 6.2 Begin-bar

Un trattino `-` come **carattere iniziale** del primo token della
misura, seguito (senza spazi) da un'annotation testuale, ancora
l'annotation all'**inizio della misura**:

```
D) | -"my text 1"  p . . ff |
       ↑ "my text 1" begin-bar anchored
```

Il `-` iniziale non rappresenta extension qui: rappresenta **ancoraggio
barline**. L'annotation resta puntuale di default; per estenderla
attraverso le misure successive si applica la regola di §6.4.

> **Interazione con extension precedente** (§5.4): se la misura
> precedente aveva una extension testuale aperta (note-anchored o
> barline-anchored cross-bar), il nuovo begin-bar `-"text"` la
> **chiude implicitamente** sulla nota immediatamente anteriore e
> apre il nuovo ancoraggio allineato al bordo barline. Per chiudere
> esplicitamente l'extension prima del begin-bar, inserire `.` o
> altro closing element sull'ultima nota della misura precedente.

### 6.3 End-bar

Simmetricamente: un'annotation testuale seguita (senza spazi) da `-`
come **ultimo token** della misura ancora l'annotation alla **fine
della misura**:

```
D) | ff "my text 2"- |
            ↑ "my text 2" end-bar anchored
```

### 6.4 Extension barline-anchored cross-bar

Un'annotation barline-anchored può estendersi attraverso più misure
combinando **due trattini** sul primo token (ancora + apre) e uno
sull'ultimo (ancora + chiude):

```
D) | -"Vamp till cue"-  -  -  - | -  -  -  -  - | -  -  - "end"- |
       ↑ begin-bar + apre ext      ↑ continua ext (cross-bar)        ↑ end-bar (chiude)
```

- Il **primo `-`** ancora l'annotation a begin-bar.
- Il **secondo `-`** adiacente al testo apre l'extension testuale
  (come per le note-anchored).
- Nelle misure successive, `-` standalone continua l'extension.
- La chiusura segue le stesse regole di §5.4; in più, una forma
  end-bar `"end"-` come ultimo token può chiudere esplicitamente
  un'extension aperta (anche con `"end"` qui usato simbolicamente —
  un nuovo elemento barline-anchored chiude quello in corso).

### 6.5 Convivenza begin + end nella stessa misura

Una misura può contenere sia un'annotation begin-bar sia una end-bar:

```
D) | -"text 1"   p . . ff   "text 2"- |
       ↑ begin                ↑ end
```

Eventuali elementi note-anchored della misura (`p . . ff`) si
intercalano normalmente fra l'annotation begin e quella end.

---

## 7. Regole di parsing

### 7.1 Tokenizzazione

La riga `D)` è tokenizzata su **spazi bianchi**. All'interno di un
token possono comparire più elementi co-located (§4.2). I container
testuali `"…"` e `[…]` ammettono spazi interni (sono delimitati dalle
loro virgolette/parentesi quadre).

### 7.2 Disambiguazione del `-`

Il carattere `-` ha tre ruoli, distinguibili per **posizione e
adiacenza** rispetto al contenuto della misura D):

| Forma                          | Ruolo                              |
|--------------------------------|------------------------------------|
| `"text"-` (adiacente a annot, non ultimo token della misura) | apre extension testuale (§5.2)     |
| `-` (token standalone)         | continua extension (§5.3)          |
| `-"text"` come PRIMO token della misura | ancoraggio begin-bar (§6.2)    |
| `"text"-` come ULTIMO token della misura | ancoraggio end-bar (§6.3)    |
| `-"text"-` come primo token    | begin-bar + apre extension cross-bar (§6.4) |

Un `-` non riconducibile a nessuno di questi tre pattern produce
warning **W132**.

### 7.3 Disambiguazione `[…]`

Il container `[…]` in `D)` è sempre un'annotation testuale con box. Non
collide con il volta begin (`[1.]`) perché quest'ultimo compare nella
riga di Markers, non in `D)`. Non collide con polychord
(`[top|bottom]`) per lo stesso motivo.

### 7.4 Single-line e container vuoti

I container testuali sono single-line (vedi `neumaRk_text_markup.md`
§6.2). Container vuoti `""` e `[]` sono letterali e non interpretati
come annotation (sono token testuali vuoti).

### 7.5 Markup interno

Il contenuto di `"…"` e `[…]` in `D)` è soggetto al markup unificato di
`neumaRk_text_markup.md` §3. Lo stile di default applicato è *plain,
size ridotta*: italic, bold e underline si attivano solo tramite
markup esplicito (`*…*`, `**…**`, `__…__`).

---

## 8. Resa grafica

### 8.1 Fascia D)

Tutti gli elementi della riga `D)` sono renderizzati **sotto il
pentagramma** del rigo parent, in una fascia dedicata. Quando il rigo
parent è una voce 2 (`N2`), la fascia `D)` della voce 2 può essere
sovrapposta o adiacente a quella della voce 1: il posizionamento
verticale è scelta del renderer.

### 8.2 Dynamic puntuali

I dynamic mark (§3.1) sono renderizzati come testo bold-italic
tradizionale (convenzione tipografica musicale), allineati orizzontalmente
al beat della nota corrispondente.

### 8.3 Hairpin grafici

I hairpin (`<`/`>`) sono renderizzati come singolo segno "a forcina" che
copre l'intervallo da prima all'ultima ripetizione, con estremi
allineati ai beat delle note di apertura e chiusura.

### 8.4 Hairpin testuali

`c` e `d` producono rispettivamente "cresc." e "dim." come testo
italic, seguiti da una **linea tratteggiata** che si estende fino al
beat dell'ultima ripetizione. Lo stile è coerente con la convenzione
tipografica musicale.

### 8.5 Annotation testuali

Stile default: *italic ridotto*. Le annotation con `[…]` (con box)
mostrano un rettangolo grafico attorno al testo; le annotation con
`"…"` (senza box) sono solo testo.

Le **extension** testuali sono renderizzate come linea continua o
tratteggiata (a discrezione del renderer) che parte dalla fine del
testo e si estende fino al beat di chiusura.

### 8.6 Annotation barline-anchored

Le annotation begin-bar sono allineate verticalmente al bordo sinistro
della misura; quelle end-bar al bordo destro. Le extension cross-bar
attraversano graficamente le stanghette di misura.

---

## 9. Diagnostica

### 9.1 Codici diagnostici

| Codice | Descrizione                                                              |
|--------|--------------------------------------------------------------------------|
| W130   | `D)` senza una riga `N)`/`N+`/`N2` parent valida nel datapack            |
| W131   | Numero di token note-anchored in `D)` superiore agli eventi di `N)`      |
| W132   | Token `-` in posizione non riconducibile a extension o ancoraggio barline|
| W133   | Container testuale non chiuso entro fine riga (`"…` o `[…` senza chiusura) |

### 9.2 Extension non chiuse

Una extension testuale che arriva alla fine del system è chiusa
**implicitamente** a fine system (§5.4). Non è un errore: la spec
considera questo un comportamento valido e robusto. Per chiudere
esplicitamente prima della fine del system, basta inserire `.` o un
altro elemento note-anchored senza `-` adiacente.

### 9.3 Hairpin con singola occorrenza

Un hairpin (`<`, `>`, `c`, `d`) che compare una sola volta su una nota
non è errore: produce un segno grafico/testuale puntuale (di
estensione minima). Non viene emesso warning.

---

## 10. Esempi

### 10.1 Dinamiche essenziali

```
N) | a4 b c d | e f g a |
D) | p  .  .  f  | .  <  <  ff |
```

`p` su nota 1 di misura 1, `f` su nota 4; crescendo grafico su note
2-3 di misura 2 che culmina in `ff` su nota 4.

### 10.2 Annotation puntuale e estesa

```
N) | a8 a a a a a a a | a a a a a a a a |
D) | "intro"- - - mp< < < f | "verse"- - - - - - - - |
```

Misura 1: "intro" esteso per 4 note, poi `mp` chiude e parte hairpin
grafico fino a `f`. Misura 2: "verse" esteso per tutta la misura;
chiusura implicita a end-of-system.

### 10.3 Hairpin testuale `c` / `d`

```
N) | a8 a a a a a a a | a a a a a a a a |
D) | p c c c c c c c | c f . . d d d d |
```

Misura 1: `p` puntuale su nota 1, "cresc." si estende per 7 note. La
prima ripetizione `c` cade sulla stessa nota di `p` (co-located).
Misura 2: ulteriore `c` continua il "cresc." fino alla nota 1, poi `f`
chiude. Da nota 5: "dim." si estende per 4 note.

### 10.4 Co-locazione complessa

```
N) | a4 b c d |
D) | ff"drum fill"c<  .  .  ppp |
```

Sulla nota 1: 4 elementi co-located (`ff` puntuale + testo "drum fill"
+ hairpin testuale `c` + hairpin grafico `<`). Le note 2-3 sono vuote;
`ppp` puntuale su nota 4.

### 10.5 Barline-anchored begin

```
M) |[V.]                                          …
D) | -"Vamp till cue"- p . . . . . . . . |
```

"Vamp till cue" ancorato all'inizio della misura `[V.]` (volta), esteso
per tutta la misura (i `-` continuano sulle note successive perché il
trattino adiacente alla destra del testo apre l'extension).

Il decoratore `[V.]` di M) **non è replicato** nel contenuto di D): il
parser lavora sul contenuto pulito della misura (vedi §6.1).

### 10.6 Barline-anchored cross-bar

```
D) | -"Vamp till cue"- p . . . . . . . . | - - - - - - - - | - - - - mp - - - |
```

"Vamp till cue" copre 3 misure; chiude su `mp` in misura 3.

### 10.7 Begin + end nella stessa misura

```
M) |:(3/4)[1.]                              :x3|
D) | -"intro"   p . . ff   "outro"- |
```

Annotation "intro" begin-bar + annotation "outro" end-bar nella stessa
misura. Dinamiche `p` e `ff` sulle note interne. Il bordo barline di
M) (`:(3/4)[1.]` / `:x3|`) non compare nel contenuto di D).

### 10.8 Voce 2 con dinamiche indipendenti

```
N)  | a4 b c d |
D)  | f . . ff |
N2  | e4 d e2  |
D)  | p . pp   |
```

La voce 1 ha `f` su nota 1 e `ff` su nota 4; la voce 2 ha `p` su nota
1 e `pp` su nota 3. Le due `D)` sono entrambe legate alle rispettive
`N)`/`N2` per posizione (vedi `neumaRk_voices.md` §3.1).

---

## 11. Riassunto

| Concetto              | Sintassi                                  | Sezione |
|-----------------------|-------------------------------------------|---------|
| Dynamic puntuale      | `p mp mf f ff fff pp ppp pppp ffff sf sfz fp` | §3.1 |
| Hairpin grafico       | `<` `>` (per ripetizione)                  | §3.2    |
| Hairpin testuale      | `c` (→ cresc.) `d` (→ dim.)                | §3.3    |
| Annotation testuale   | `"text"` / `[text]`                        | §3.4    |
| Placeholder           | `.`                                        | §3.5    |
| Continuation          | `-` standalone                             | §3.6    |
| Co-locazione          | adiacenza senza spazi                      | §4.2    |
| Autofill              | note residue → `.` implicito               | §4.3    |
| Extension testuale    | `"text"-` apre, `-` continua, `.` chiude   | §5      |
| Begin-bar             | `-"text"` come PRIMO token della misura     | §6.2    |
| End-bar               | `"text"-` come ULTIMO token della misura    | §6.3    |
| Cross-bar barline-anch| `-"text"-` … `"end"-` (cross-bar)           | §6.4    |
| Cross-bar note-anch   | `-` attraversa `|` trasparente             | §5.5    |

Il sistema è **ortogonale**: i tre meccanismi (dynamic puntuali,
hairpin per ripetizione, testi con extension `-`) coesistono senza
interferenze e si combinano per co-locazione.

---

Questo documento definisce la riga `D)` di neumaRk come **fascia
annotativa sotto-pentagramma** unificata, in grado di esprimere
dinamiche tradizionali, indicazioni di crescendo/decrescendo,
annotation testuali puntuali ed estese e ancoraggi alle stanghette di
misura, attraverso un vocabolario compatto e regole ortogonali.


---

# Testo cantato (riga `L)`)

> **STATO: SPEC.** §1–§7 sigillate 2026-05-23 (semantica di deduzione della
> riga `L)` inline). §8 (blocco di lyrics per sezione `LYRICS)`) è **DESIGN
> 2026-05-27** con decisioni sigillate, implementazione in corso (§8.4.1
> pickup sigillato 2026-05-28) — vedi
> `docs/feature-lyrics-sections-and-editions.md`. Binding e ordine di `L)`
> non sono ridefiniti qui: vedi `neumaRk_datapack.md §2.1` e §3. Decisioni
> di sigillo e note residue in §7; follow-up lato codice in
> `docs/feature-deduction-spec-audit.md`.
>
> **Questo file IT è la source of truth**; la versione EN
> (`../en/neumaRk_lyrics.md`) la rispecchia.

## 1. Definizione

La riga `L)` (Lyrics) porta il **testo cantato**, sillaba per sillaba, allineato
agli eventi della riga `N)` a cui è legata. È un layer parallelo: non altera
ritmo né flusso. Più righe `L)` consecutive dello stesso rigo formano **strofe**
distinte (multi-verse).

## 2. Posizione strutturale e binding

Marcatore, opzionalità e ordine logico sono definiti in `neumaRk_datapack.md`
§2.1 e §3 (ordine implicito: `L)` è **opzionale e ultima** del gruppo di note).
La riga lega alla `N)` del proprio gruppo/rigo; la **voce 2** (`N2`) ha le proprie
righe `L)` (vedi `neumaRk_voices.md`).

## 3. Allineamento count-based (solo note, non pause)

La corrispondenza è **posizionale per conteggio**, left-to-right, ma calcolata
**solo sugli eventi-nota**: le **pause non ricevono sillabe**.

```
N) | c4 d  r  e  |
L) | la la    sol |
     ↑  ↑  ↑   ↑
     la la (pausa: niente) sol
```

- Il contatore delle sillabe avanza **solo** sulle note effettive (`isNote()`);
  su una pausa si emette un padding vuoto (mantiene l'allineamento posizionale).
- Token `.` = **placeholder**: nessuna sillaba su quella nota (la nota resta
  senza testo, ma la posizione è consumata).
- Token in eccesso oltre il numero di note: emette **W131** (come `D)`; allineato
  2026-05-23, follow-up parser).

## 4. Strofe multiple (multi-verse)

Ogni riga `L)` **consecutiva** dello stesso rigo è una **strofa** successiva:

```
N) | c  d  e  f |
L) | first verse syllables… |     ← strofa 1
L) | second verse…          |     ← strofa 2
```

- Limite: **10 strofe** per misura/rigo; le righe oltre la decima sono scartate
  silenziosamente.
- Padding fra strofe: per ogni strofa, le note senza token ricevono una sillaba
  vuota, così tutte le note hanno lo stesso numero di strofe (allineamento
  verticale fra versi).

## 5. Meccanica delle sillabe

Ogni token di testo è una **parola**, eventualmente sillabata con `-`:

| Forma          | Effetto |
| -------------- | ------- |
| `parola`       | una sillaba (parola intera) sulla nota corrente |
| `pa-ro-la`     | tre sillabe su tre note consecutive; le sillabe non finali sono marcate **`word_continues`** (trattino di sillabazione in render) |
| `_`            | **melisma**: estende la sillaba precedente sulla nota corrente (nessuna nuova sillaba) |
| `.`            | placeholder: nessuna sillaba (vedi §3) |
| `-coda`        | token con `-` **iniziale**: **continuazione** della parola precedente — retro-marca l'ultima sillaba emessa come `word_continues` e aggiunge `coda` come sillaba successiva (forma per-sillaba prodotta dal serializer) |

Dettagli di robustezza (come da parser):

- le sillabe **vuote** generate da trattini spurii (`-mar`, `mar--ti`, `-`
  isolato) sono **scartate**;
- una sillaba è `word_continues` se esiste una sillaba **non vuota** dopo di essa
  nello stesso token (o se un token di continuazione `-X` segue).

## 6. Esempi

```
N) | c4   d    e   f    |
L) | Ave-       _    ma- ri-a  |
```
`Ave` (con trattino di sillabazione) → `_` estende `Ave` sulla 2ª nota →
`ma`/`ri` proseguono; `a` chiude la parola.

## 7. Decisioni (chiuse 2026-05-23) e note residue

Chiuse:

1. **Eccesso di sillabe** ✓ — emette **W131** come `D)` (era silent drop;
   follow-up parser in `docs/feature-deduction-spec-audit.md`).
2. **Meccanica di §5 normativa** ✓ — sillabazione, melisma `_`, continuazione `-`
   come descritti.

Note residue (comportamento attuale documentato come normativo salvo revisione,
non bloccanti):

- **Cap 10 strofe**: oltre la decima, silent drop. Limite confermato; il
  comportamento su overflow (silent vs warning) resta rivedibile.
- **Pause**: interrompono sempre il conteggio sillabe — la pausa non riceve testo
  e il melisma `_` non la "scavalca". Normativo.
- **Forma di sillabazione canonica del serializer**: il parser accetta sia
  `pa-ro-la` sia la forma per-sillaba `pa- -ro- -la`; quale forma il serializer
  *emetta* è una scelta di output separata (non influisce sul parsing), da fissare
  quando si lavora al round-trip serializer.

## 8. Blocco di lyrics per sezione (riga `LYRICS)`)

> **DESIGN 2026-05-27, decisioni sigillate.** Roadmap e razionale in
> `docs/feature-lyrics-sections-and-editions.md`.

### 8.1 Scopo e relazione con `L)`

Il blocco `LYRICS)` è un **modo alternativo di scrivere le stesse strofe**
che `L)` scrive inline. Invece di allineare le sillabe alle note di un
singolo datapack, porta il testo **per sezione** e lascia al motore il
compito di distribuire le sillabe sulle note di quella sezione
automaticamente.

`LYRICS)` **non** introduce un modello di lyrics diverso: alimenta gli
stessi slot `Lyric` per-nota che alimenta `L)` (§3, §5). La riga `L)`
inline resta pienamente valida; i due si compongono (§8.5).

L'equivalenza con `L)` vale però **solo per il rendering**: il blocco porta
informazione che l'inline non sa esprimere — l'**edizione del testo**
(lingua + autore, §8.8). Per questo il **round-trip serializer conserva la forma scelta
dall'utente**: un blocco `LYRICS)` riemette `LYRICS)` (verbatim, lingua inclusa),
una riga `L)` riemette `L)`. Il serializer NON converte automaticamente l'uno
nell'altro; la conversione esplicita è un'azione utente separata (menu
contestuale WRITE, non ancora implementata). Implementazione: `Music::lyrics_blocks`
(blocco grezzo + posizione) + `Lyric::from_section` (sopprime la ri-emissione
inline dei versi che round-trippano come blocco).

### 8.2 Sintassi

```
LYRICS)
[A] sillabe del verso…
[B] sillabe del verso…
[A] (una seconda riga [A] = secondo verso su A)
```

- Il blocco si apre con una riga il cui primo token non-blank è il marker
  `LYRICS)` (opzionalmente seguito da un tag di **edizione**
  `[lingua] [<autore>]`, §8.8).
- Ogni **entry** inizia con un riferimento di sezione `[NAME]` (§8.3). Il
  testo dopo `]` sulla stessa riga, e/o le righe successive non-blank che
  **non** iniziano con `[`, sono le **sillabe** di quell'entry.
- L'entry può iniziare con un gruppo **pickup** `<…>` — sillabe che
  legano alle note che *precedono* la sezione (anacrusi). Vedi §8.4.1.
- **Righe vuote dentro il blocco sono ammesse** (separatori visuali): non
  chiudono il blocco.
- Il blocco si estende fino al primo **top-level marker** (`LYRICS)`,
  `PLAY)`, `FORM)`, `%%…`) o **prefisso di datapack** (`M) N) C) A) D) L) F)`).

Forma compatta ed estesa sono entrambe accettate ed equivalenti:

```
LYRICS)                          LYRICS)
[A] questo è un testo    ≡       [A]
                                 questo è un testo
```

La grammatica delle sillabe è **identica a `L)`** (§5): `pa-ro-la`,
melisma `_`, placeholder `.`, continuazione con `-` iniziale.

### 8.3 Riferimento di sezione e posizione strutturale

`[NAME]` è lo stesso **reference-by-name** usato da `PLAY)` / `FORM)`
(`neumaRk_play_and_form.md` §3.1): il matching è per **text-equality sul
NAME** con markup strippato (`neumaRk_text_markup.md` §7.1). Un blocco
`LYRICS)` può apparire **ovunque tra i datapack**; la posizione nel file
non influenza la sezione a cui un entry si lega (binding by name, come
`%%versions`).

Un riferimento a una sezione inesistente è **reference-broken**: warning
**W157** (non bloccante, §8.9).

### 8.4 Aggregazione di sezione cross-datapack

È il comportamento distintivo: le sillabe di `[A]` si distribuiscono su
**tutte le note della sezione `[A]`**, concatenate in ordine di flow,
**attraversando i confini datapack / system / misura**. (Per contro
`L)` inline è locale a un singolo datapack.)

Una misura appartiene alla sezione il cui marker `[…]` è il **più recente**
in cima o prima della misura stessa (le annotazioni `"…"` **non**
aprono sezione, `neumaRk_markers.md` §3.1, §4.1). Una corsa massimale di
misure consecutive con la stessa sezione corrente è un'**occorrenza** di
quella sezione.

```
M) [A]
N) a b c d

N) e f g a          ← stessa [A], datapack successivo, nessun marker

LYRICS)
[a] mol-te sil-la be su_un ri-go
     └─ distribuite su a b c d  e f g a (8 note, una occorrenza, cross-datapack) ─┘
```

Dentro un'occorrenza, le note (primo rigo, voce 1 — §8.7) sono raccolte
in ordine di flow e le sillabe legate esattamente come in `L)` (§3):
**positional-by-count, le pause non ricevono sillabe**, `.` placeholder,
`_` melisma.

**Più occorrenze (template).** Se `[A]` ricorre più di una volta (es.
AABA), l'entry è un **template** applicato a **ogni** occorrenza: le
stesse sillabe sono legate, indipendentemente, a ciascuna occorrenza. Le
sillabe **non** si distribuiscono attraverso le occorrenze. (Testo
diverso per-occorrenza — es. strofa 1 / strofa 2 cross-ripetizione — è
fuori scope; usa nomi distinti `[A1]`/`[A2]`, §8.10.)

### 8.4.1 Sillabe pickup (anacrusi) — `<…>`

> **DESIGN 2026-05-28, decisioni sigillate.** Chiude il gap dei testi che
> devono iniziare *prima* del bordo di sezione (anacrusi). Roadmap in
> `docs/feature-lyrics-sections-and-editions.md` §2.5.

Un entry può iniziare con un **gruppo pickup** delimitato da `<…>`. Le
sillabe nel gruppo legano alle **ultime N note che precedono**
l'occorrenza della sezione in ordine di flow, dove **N è il conteggio
sillabe** del gruppo (dopo espansione della grammatica: `pa-ro-la` vale
3, `_` e `.` valgono 1 ciascuno). Le sillabe *dopo* `>` continuano
normalmente dalla prima nota dell'occorrenza (§8.4).

```
M) [intro]      | a4 a a a |
M) [intro]      | h2 r4 c,8 d |
M) [A]          | e         |

LYRICS)
[A] <do re> mi
     │      └─ prima nota dell'occorrenza di [A]
     └──────── ultime 2 note della sezione precedente ([intro]: c,8 d)
```

**Dove atterra il pickup.** Per ogni occorrenza di `[NAME]`, il pickup
scandisce **all'indietro** dalla prima nota di quell'occorrenza sulla
corsa contigua di note la cui sezione corrente **non** è `[NAME]`. Le N
ultime note di quella corsa ricevono le sillabe pickup (le pause sono
saltate, esattamente come in §3 / §8.6). Lo scan si ferma alla:

- prima nota appartenente a `[NAME]` (non entra mai nell'occorrenza
  stessa né in una occorrenza precedente di `[NAME]`);
- testa del brano (nessuna nota prima della prima occorrenza di `[NAME]`).

**Volte.** Quando la corsa precedente contiene volte
(`|[1.]` … `|[2.]` …, `neumaRk_flow_and_repeats.md` §6), solo la
**volta finale** contribuisce note al pickup; le misure interne a volte
precedenti sono **saltate** dallo scan all'indietro. L'intuizione è che
l'anacrusi è la rincorsa *verso* `[NAME]` lungo il percorso che la
musica effettivamente prende l'ultima volta — quello che termina in
`[NAME]`. Le misure non-volta contribuiscono normalmente.

**Più occorrenze (template).** Come per le sillabe post-`>`, il gruppo
pickup è un **template**: applicato **indipendentemente a ciascuna
occorrenza** di `[NAME]`, ciascuna guardando indietro nella propria
corsa di note non-`[NAME]`. In AABA, ogni `[A]` ha il proprio pickup
dalle note immediatamente precedenti.

**Overflow / nessuna nota precedente.**

- Se la corsa precedente ha **zero** note (es. l'occorrenza è all'inizio
  del brano), il pickup è **silenziosamente droppato per quella
  occorrenza** — nessun warning. Le sillabe post-`>` legano normalmente.
- Se `0 < disponibili < N` (overflow parziale: la corsa esiste ma è più
  corta del pickup), le note disponibili ricevono le sillabe pickup
  **finali** (le iniziali in eccesso sono droppate) e si emette **W158**
  **una volta per occorrenza affetta** (non bloccante, §8.9). Le sillabe
  post-`>` legano normalmente comunque.

**Accumulo verse (slot del proprio body, OVERRIDE).** Il pickup di
un'entry occupa lo **stesso slot del body di quella entry** sulle
pre-notes, **sostituendo** le sillabe già presenti su quel slot
(**sigillato 2026-05-28, dopo test su brano reale**):

- Il **body** occupa lo **slot naturale** della sezione,
  `verseCount[NAME]` — la prima riga libera della sezione, come
  un'entry senza pickup (§8.5).
- Il **pickup** occupa lo **stesso slot del proprio body** sulle
  pre-notes: `pickupSlot = bodySlot`. Se le pre-notes hanno **già**
  sillabe su quel slot (ad es. il body della sezione precedente che
  canta quelle note), il pickup le **sovrascrive**. Se non le hanno,
  il pickup ci scrive direttamente (padding implicito).

L'effetto musicale corrisponde alla convenzione tradizionale: la
strofa di `[NAME]` "ruba" letteralmente le ultime N note del
predecessore alla strofa di quel predecessore (stessa lingua / stessa
posizione di verse), e ci canta l'anacrusi.

Esempio brano multi-strofa (port = slot 0, eng = slot 1): le ultime 2
note di `[B]` ospitano **due** sillabe pickup: `<E vol>` di `[A2]` port
sostituisce le ultime 2 sillabe del body `[B]` port (slot 0); `<So I>`
di `[A2]` eng sostituisce le ultime 2 del body `[B]` eng (slot 1). Il
body `[A2]` (port e eng) resta sui suoi slot naturali (0 e 1), in
continuità con `[A1]` e `[B]`. Per ottenere questa sostituzione,
l'engine processa **prima** tutti i body, **poi** tutti i pickup
(così il pickup vede e sovrascrive il body già scritto sulle pre-notes).

**Vincoli.**

- Un solo gruppo pickup per entry, deve venire **immediatamente** dopo
  `[NAME]` (e whitespace opzionale), prima di qualunque sillaba post-`>`.
- **`<>` vuoto** è un **no-op** silenzioso: consumato senza effetto,
  nessun warning. Le sillabe post-`>` legano come se il gruppo non
  esistesse.
- `<` e `>` sono riservati **solo dentro gli entry `LYRICS)`**; non sono
  token della grammatica delle sillabe altrove (`L)`, `D)`).
- Dentro `<…>` la grammatica è identica a `L)` (§5): `pa-ro-la`, `_`,
  `.`, continuazione `-` iniziale. Un token di continuazione `-X` come
  *primo* token del gruppo pickup è **droppato** (non c'è una sillaba
  precedente nello stesso entry da continuare).
- Binding rigo/voce identico al corpo dell'entry: **primo rigo, voce 1**
  (§8.7).

### 8.5 Accumulo dei versi (`L)` inline ++ blocchi `LYRICS)`)

Per ogni sezione, i versi si impilano top-to-bottom in questo ordine
(**sigillato 2026-05-27**):

```
versi(sezione) = [ versi L) inline, in ordine ] ++ [ entry [NAME] dai blocchi LYRICS), in ordine di file ]
```

Ogni entry `[NAME]` (una riga) aggiunge **un** verse. Due entry `[A]`
(stesso blocco o blocchi diversi) aggiungono due versi, in ordine di
apparizione.

Per tenere i versi **allineati verticalmente** lungo una sezione che si
estende su più datapack (i cui conteggi inline possono differire), il
motore prima padda ogni nota della sezione a
`n_inline = max(note.lyrics.size())` su tutta la sezione, poi appende
ogni verse di blocco a un indice uniforme su tutte le occorrenze.

I tre frammenti seguenti producono lo **stesso** risultato a due versi su `[A]`:

```
// (a) tutto inline             // (b) misto                  // (c) tutto a blocco
N) ...                          N) ...                        N) ...
L) tes-to u-no                  L) tes-to u-no                LYRICS)
L) tes-to du-e                  LYRICS)                       [A] tes-to u-no
                                [A] tes-to du-e               [A] tes-to du-e
```

### 8.6 Regole di allineamento (riuso da `L)`)

Identiche a §3 e §5: positional-by-count sulle note, **le pause non
ricevono sillabe**, sillabazione `pa-ro-la` (`word_continues`), melisma
`_`, placeholder `.`, continuazione `-` iniziale. Sillabe in eccesso
sulle note di un'occorrenza emettono **W131** (come `L)` / `D)`); note
in eccesso sulle sillabe ricevono un `Lyric{}` vuoto (padding).

### 8.7 Binding rigo / voce

Un entry `LYRICS)` lega sempre al **primo rigo, voce 1** (la linea
vocale principale) — **sigillato 2026-05-27**. Per lyrics su altri righi
o sulla voce 2 (`N2`) si usa la riga `L)` inline, che ha già quella
granularità (`neumaRk_voices.md`). Il blocco scambia la granularità
per-voce con la comodità per-sezione.

### 8.8 Edizioni del testo (`LYRICS) [lingua] [<autore>]`)

> **DESIGN 2026-05-30, sigillato (Fase B).** Generalizza la multilingua
> (Fase 3): la "lingua" è ora un caso particolare di **edizione del testo**.
> Roadmap e decisioni in `docs/feature-lyrics-sections-and-editions.md`
> §9-§11.

Un'**edizione** è una versione del testo cantato; un brano può averne più
d'una. L'header `LYRICS)` può portare due elementi opzionali, su **assi
distinti e separati anche sintatticamente**:

- un **token lingua** (`LYRICS) pt-br`): un codice (`it`, `en`, `pt-br`, …;
  forma `[a-z]{2,3}(-regione)?`, case-insensitive, normalizzato in
  minuscolo) — una traduzione;
- un **autore** fra `<…>` (`LYRICS) en <Frank Sinatra>`): chi ha scritto
  *quel* testo. Testo libero, può contenere spazi (le parentesi delimitano:
  niente euristiche di disambiguazione).

| Forma | Natura |
|---|---|
| `LYRICS)` nudo / `L)` inline | **neutra** (default, no lingua/autore) |
| `LYRICS) pt-br` | **lingua** |
| `LYRICS) en <Frank Sinatra>` | **lingua + autore** |
| `LYRICS) <Al Jarreau>` | **autore-only** (no lingua) |

Un'edizione è identificata dalla coppia **(lingua, autore)**. Sono ammesse
**più edizioni nella stessa lingua** con autori diversi (vocalese /
traduzioni concorrenti: `en <Jon Hendricks>` + `en <Eddie Jefferson>`).

#### Default — Rule A

- **neutra** (no lingua, no autore) → testo di default;
- **lingua** (ha lingua, ± autore) → *intrinseca*, concorre al default;
- **autore-only** (autore senza lingua) → **opt-in**, mai default.

Il **testo di default** è il neutro (`L)` inline o `LYRICS)` nudo) se
presente, altrimenti la **prima edizione-lingua in ordine di file**. Se non
esiste alcuna edizione intrinseca (solo `<autore>`-only) il brano apre
**strumentale**: nessun testo di default, le edizioni si attivano dalla
selezione.

#### Selezione

L'**edizione attiva** è una **user preference** scalare (una per brano,
chiave = la coppia lingua+autore), selezionabile da menu — stesso pattern
di `%%versions` ma scalare. Seleziona **quale** edizione alimenta gli slot
`Lyric` per-nota; gli entry delle altre edizioni non vengono legati. Se la
coppia attiva non esiste fra le edizioni, si usa il **default** (Rule A); se
non c'è default (strumentale), nessuna lyric da blocco viene legata.

La riga `L)` **inline** è l'edizione **neutra di default**: si accumula
secondo §8.5 quando l'edizione neutra è il testo mostrato.

#### Metadati (titolo / autore)

- **Titolo per lingua**: un titolo per lingua (condiviso da *tutte* le
  edizioni di quella lingua — è la traduzione del nome del brano, non cambia
  col paroliere), dichiarato col tag `[lingua]` sui titoli `HT)`
  (`neumaRk_header.md` §8.1). Vive nei **metadati**, non nel testo del blocco.
- **Autore del testo**: per il default → `lyricsBy` globale (`HCL)`); per
  un'edizione taggata → il gruppo `<…>` sul blocco `LYRICS)`. Per l'autore-
  only il nome **È** il lyricsBy di quell'edizione. Il vecchio credit
  per-lingua `HCL) … [lingua]` è **rimosso** (`neumaRk_header.md` §9.2).

L'asse edizione è **ortogonale** all'asse `%%versions`: due scelte utente
indipendenti che si compongono. Il filtraggio versioni
(`applyVersionFiltering`) riscrive prima il flow; le lyrics dell'edizione
attiva si legano poi by-name alle note residue. Le lingue disponibili sono
**dedotte** dai blocchi `LYRICS)` + dai tag `[lingua]` dei titoli; non c'è
header di dichiarazione (`HL)` resta fuori scope, come per l'opzionale `HV)`).

#### 8.8.1 Ponte titolo ↔ lingua

Un titolo che porta un tag lingua (`neumaRk_header.md` §8.1, es.
`HT) No More Blues [EN]`) è legato a quel codice. Aprire il brano **come**
quel titolo (es. da un risultato di ricerca) preseleziona la lingua per la
sessione: il titolo mostrato e la lingua delle lyrics ne seguono la scelta.
È un **override di sessione** (come un parametro URL): **non** sovrascrive
una user preference salvata, che resta settabile dal menu.

### 8.9 Diagnostica

| Codice | Severità | Descrizione |
|--------|----------|-------------|
| W157 | WARNING  | `LYRICS) [NAME]` riferisce una sezione inesistente (reference-broken) |
| W158 | WARNING  | gruppo pickup `<…>` di `LYRICS)` eccede la corsa di note precedenti disponibile (corsa più corta di N, eccesso iniziale droppato) — una per occorrenza affetta; silent skip se la corsa è vuota (§8.4.1) |
| W131 | WARNING  | sillabe in eccesso sulle note di un'occorrenza (condiviso con `L)` / `D)`) |

Tutte non bloccanti. (Il cap di 10 strofe per nota, §4, vale sul totale
inline+blocco.)

### 8.10 Fuori scope (MVP)

- **Testo per-occorrenza** (AABA che canta parole diverse a ogni passata
  della stessa `[A]`): non coperto — i versi si impilano verticalmente,
  non per-occorrenza. Workaround: nomi sezione distinti `[A1]`/`[A2]`.
- **Volte `|[1.]` / `|[2.]`** con testo diverso per ending.
- **Binding multilingua a titoli alternativi** (Fase 3, §8.8).

### 8.11 Esempi

Due versi su `[A]`, uno su `[B]`, `[Instrumental]` lasciato senza testo:

```
M) [A]      | c4 d  e  f |
M) [Instrumental] | g a  b  c |
M) [B]      | c  b  a  g |

LYRICS)
[A] questo è il primo verso qui
[A] e qui passa il secondo verso
[B] il bridge ha le sue parole proprie
```

Occorrenza cross-datapack (una `[A]` su due datapack):

```
M) [A]
N) c d e f

N) g a b c

LYRICS)
[A] ot-to sil-la be su due ri-ghi
```

Anacrusi con pickup (§8.4.1):

```
M) [intro]  | a4 a a a |
M) [intro]  | h2 r4 c,8 d |
M) [A]      | e         |

LYRICS)
[A] <do re> mi
```


---

# Markup testuale

Questo documento definisce la sintassi e la semantica del **markup testuale**
in neumaRk: regole comuni di formattazione applicabili a tutti i container
testuali del linguaggio (marker, end-decorator, comment-label, annotation
note, label di sezione, prosa di forma).

L'obiettivo è fornire un sistema **unificato e ortogonale** in cui un primo
asse decide il box grafico (container), un secondo asse decide lo stile
di default (costrutto ospitante), e un terzo asse — opzionale — consente
all'utente di applicare markup esplicito.

---

## 1. Tre assi ortogonali

Il rendering del testo in neumaRk è funzione di tre assi indipendenti:

1. **Container** — `[…]` (con box) oppure `"…"` (senza box).
2. **Stile di default** — determinato dal costrutto ospitante (marker,
   comment-label, annotation, prosa, ecc.).
3. **Markup utente** — opzionale, definito tramite un sottoinsieme di
   Markdown applicato dentro il container.

Nessuno dei tre assi vincola gli altri. Lo stesso testo può essere
espresso in qualunque combinazione di box/no-box, qualunque default
semantico, con o senza markup esplicito.

> **Eccezione: marker `M)`.** Nei marker della riga `M)` (sezioni e
> annotazioni, vedi `neumaRk_markers.md` §3.1) il container `[…]` vs
> `"…"` porta anche **semantica strutturale**, non solo box grafico:
> `[…]` = sezione (target di PLAY/FORM, delimita scope collassabili),
> `"…"` = annotazione (testo descrittivo, non strutturale). La regola
> di "intercambiabilità sintattica" di §2.1 ha quindi un'eccezione
> normativa in M).

---

## 2. Container testuali

### 2.1 Forme

Un container testuale è una sequenza di caratteri delimitata da:

- `[` … `]` → **container con box**;
- `"` … `"` → **container senza box**.

Le due forme sono **sintatticamente intercambiabili** in ogni contesto
che ammette uno dei due. La differenza è la presenza del box grafico
nel rendering, fatta eccezione per i marker della riga `M)` dove le
due forme portano anche semantica strutturale distinta (sezione vs
annotazione, vedi `neumaRk_markers.md` §3.1).

### 2.2 Dove si applica il markup

Il markup definito in questo documento si applica a tutti i container
testuali del linguaggio:

| Costrutto                                  | Container ammessi  | Riferimento                            |
|--------------------------------------------|--------------------|----------------------------------------|
| Sezione `M)`                               | `[…]`              | `neumaRk_markers.md` §3.1              |
| Annotazione `M)`                           | `"…"`              | `neumaRk_markers.md` §3.1              |
| End-decorator testuale                     | `[…]`, `"…"`       | `neumaRk_flow_and_repeats.md` §4.3     |
| Comment-label chord / group / row          | `[…]`, `"…"`       | `neumaRk_chords.md` §7                 |
| Annotation note                            | `[…]`, `"…"`       | `neumaRk_notes_and_durations.md` §8    |
| Annotation dinamiche `D)`                  | `[…]`, `"…"`       | `neumaRk_dynamics.md` §3.4             |
| Label articolazione `A)` (onda, staffa)    | `"…"`              | `neumaRk_articulations.md` §10.2/§10.3 |
| Top/bottom label box di sezione            | `"…"`              | `neumaRk_play_and_form.md` §3.3        |
| Prosa libera in `PLAY)` / `FORM)`           | tutta la prosa     | `neumaRk_play_and_form.md` §5          |

Il markup **non si applica** a:

- valori dell'header (titolo, credits, year, style, key, meter, BPM),
  che sono renderizzati in modo autonomo dal sistema;
- nomi tecnici dei marker quando referenziati in `PLAY)` / `FORM)`,
  dove il matching è per text-equality (il markup, se presente, è
  applicato in display ma stripped per il matching);
- volta begin (`|[1.]`), che è un container simil-box predeterminato e
  non ammette markup interno.

---

## 3. Sintassi del markup

Il markup neumaRk è un sottoinsieme di Markdown, scelto per essere
deterministico e single-line.

### 3.1 Dimensione del testo

I 3 prefissi `#`/`##`/`###` selezionano una **dimensione relativa** che
dipende dal **ruolo size** del costrutto (vedi §5):

- **role `reduced`** (default per: comment-label chord/group/row,
  annotation note, annotation D), label PLAY/FORM, annotation marker
  `"…"`): il default è la dimensione **più piccola**; i prefissi
  scalano solo SOPRA.
- **role `body`** (default per: marker `M)` `[NAME]`, prosa PLAY/FORM):
  il default è la dimensione **media**; i prefissi scalano SOPRA e
  SOTTO.

| Prefisso  | role `reduced`               | role `body`                   |
|-----------|------------------------------|-------------------------------|
| `# `      | grande (2.0× default)        | grande (1.5× default)         |
| `## `     | medio (1.5× default)         | medio (1.0× default = body)   |
| `### `    | default (1.0×, = no prefix)  | piccolo (0.7× default)        |

Regole:

- lo **spazio dopo `#`/`##`/`###` è obbligatorio**: `#hashtag` è
  letterale, `# title` apre lo span;
- il prefisso compare **solo all'inizio del testo del container** o
  **all'inizio di un run di prosa** (in `PLAY)` / `FORM)`, dopo un
  token strutturale o all'inizio del body);
- lo span aperto da `#`/`##`/`###` si **chiude** al primo dei seguenti
  eventi: fine del container, prossimo token strutturale in `PLAY)` /
  `FORM)` (`[…]`, `&kw`, `$`, `@`);
- `####` e oltre sono trattati come letterali;
- `### ` è ammesso per esplicitare il proprio livello size anche se è
  ridondante col default (es. in role `reduced`).

### 3.2 Enfasi

Tre forme di emphasis, attivate da delimitatori in coppia:

| Sintassi      | Effetto             |
|---------------|---------------------|
| `*foo*`       | italic              |
| `**foo**`     | bold                |
| `***foo***`   | bold + italic       |

Regole:

- gli span sono **delimitatori chiusi**: un `*` non chiuso è letterale
  (nessun render parziale);
- l'asterisco chiudente deve essere preceduto da contenuto non vuoto;
- gli span possono comparire in qualunque posizione del testo;
- **non è ammesso annidamento** di emphasis (per esempio
  `**foo *bar* baz**` non è valido): la forma `***foo***` è atomica.

### 3.3 Underline

Sintassi attivata dal **doppio underscore**:

| Sintassi      | Effetto             |
|---------------|---------------------|
| `__foo__`     | underline           |

Regole:

- come gli span di emphasis, lo span è **delimitatore chiuso**: un
  `__` non chiuso è letterale;
- il `__` chiudente deve essere preceduto da contenuto non vuoto;
- lo span può comparire in qualunque posizione del testo;
- **underscore singolo `_` è letterale**: `_x_` non è italic alternativo
  (NRK non adotta la convenzione Markdown di `_` come alias di `*`);
- **`___foo___`** (tre o più underscore di apertura/chiusura) è
  trattato come letterale, analogamente a `####` per i prefissi di
  dimensione.

Underline **non è una forma di emphasis**: è un **asse ortogonale** a
bold/italic. La regola "non annidamento di emphasis" di §3.2 non si
applica all'underline.

### 3.4 Combinazione

Più span di emphasis possono coesistere nello stesso testo, purché
disgiunti:

```
*foo* and **bar**            ✓  italic + bold disgiunti
*foo and **bar***            ✗  annidamento non ammesso
***foo*** plain ***bar***    ✓  due span bold-italic disgiunti
```

L'underline è un asse ortogonale: può coesistere con bold e italic
nello stesso span:

```
**__foo__**                  ✓  bold + underline
*__foo__*                    ✓  italic + underline
***__foo__***                ✓  bold + italic + underline
__**foo**__                  ✓  ordine delimitatori libero
__*foo* and **bar**__        ✓  underline su span con emphasis disgiunti interni
```

Uno span di emphasis o underline può coesistere con un prefisso di
dimensione: il prefisso vale per l'intero span del testo, gli altri
delimitatori modificano solo la porzione interna:

```
# Title with **bold** and __underline__ words
```

---

## 4. Escape

Il carattere `\` (backslash) precede un meta-carattere per renderlo
letterale.

| Token | Forma escaped |
|-------|---------------|
| `*`   | `\*`          |
| `_`   | `\_`          |
| `#`   | `\#`          |
| `[`   | `\[`          |
| `]`   | `\]`          |
| `"`   | `\"`          |
| `\`   | `\\`          |

L'escape `\_` serve quando si vuole inserire un `__` letterale in un
testo che dovrebbe esserne consumato dal markup (raro: i singoli `_`
sono già letterali by default).

Esempi:

```
M) | [The \*Real\* Book] |
c4"track \#3"
```

Un `\` non seguito da un meta-carattere è letterale.

---

## 5. Stile di default per costrutto

Il container `[…]` vs `"…"` decide **solo** la presenza del box. Lo
stile di default (size, weight, italic) è proprietà del **costrutto
ospitante**.

| Costrutto                                | Default style                                  |
|------------------------------------------|------------------------------------------------|
| Marker `M)` `[NAME]`                     | bold, size body (role `body`, vedi §3.1)       |
| Annotation marker `M)` `"…"`             | plain, size ridotta (role `reduced`)           |
| End-decorator testuale                   | plain, size body (role `body`)                 |
| Comment-label chord / group / row        | italic, size ridotta (role `reduced`)          |
| Annotation note                          | plain, size ridotta (role `reduced`)           |
| Annotation dinamiche `D)`                | plain, size ridotta (role `reduced`)           |
| Top/bottom label box PLAY/FORM           | plain, size ridotta (role `reduced`)           |
| Prosa PLAY/FORM                          | plain, size body (role `body`)                 |

Il **role size** decide come i prefissi `#`/`##`/`###` scalano sopra al
default (vedi §3.1 tabella). I costrutti `role body` ammettono `###`
per scendere SOTTO il default; quelli `role reduced` no (`###` = default).

Il markup utente (§3) sovrascrive sempre il default. Per esempio in
comment-label `chord"*plain*"` resta italic (default del costrutto) e
applica `*` come override visivo addizionale.

---

## 6. Regole di parsing

### 6.1 Disambiguazione `[…]` per ruolo

In neumaRk il delimitatore `[…]` è condiviso fra più costrutti
(polychord, volta, end-decorator, comment-label, annotation note,
grace block, ecc.). La disambiguazione è **posizionale** e definita
nelle spec dei singoli costrutti. Una volta che il parser ha
identificato il ruolo del `[…]`, il contenuto è interpretato secondo
le regole di questo documento.

### 6.2 Single-line dentro container

I container `[…]` e `"…"` sono **single-line**: non ammettono caratteri
di nuova riga. Una `]` o `"` non chiusa entro fine riga è errore di
parsing.

La prosa di `PLAY)` / `FORM)` ammette continuazione di riga (vedi
documenti correlati).

### 6.3 Container vuoti

`[]` e `""` sono **letterali**: non vengono interpretati come container.

### 6.4 Prefissi riservati

In **annotation note**, se il primo carattere dopo l'apertura del
container è `$` seguito da una lettera maiuscola riservata (`$F`, `$S`,
ecc., vedi `neumaRk_notes_and_durations.md` §8), il markup è
**disabilitato** sull'intera annotation: il contenuto è interpretato
come direttiva strutturale (fingering, string number, ecc.).

---

## 7. Casi limite

### 7.1 Markup nei nomi di reference

Dentro `[NAME]` di reference in `PLAY)` / `FORM)`, il NAME è
interpretato come testo. Il markup interno è applicato in **display**
ma rimosso prima del matching con i marker definiti:

```
PLAY) [**Solo**] [A]
```

`[**Solo**]` cerca un marker chiamato "Solo" e lo rende in bold se
trovato. Se il NAME contiene markup non chiuso o malformato, il
fallback è il matching letterale comprensivo dei caratteri di markup.

### 7.2 Spazi attorno ai delimitatori di emphasis e underline

A differenza di Markdown standard, neumaRk **non richiede** che i
delimitatori (`*`, `__`) siano "tight" rispetto al contenuto: `* foo *`
è equivalente a `*foo*`, `__ foo __` è equivalente a `__foo__`. La
scelta riduce errori comuni e mantiene il markup più tollerante.

### 7.3 Mix di container in costrutti che ne ammettono entrambi

Sezioni che ammettono entrambi i container (`[…]` e `"…"`) possono
usarne liberamente in punti diversi dello stesso documento. La scelta è
guidata dal significato grafico voluto (con o senza box).

```
M) | [Intro] | "freely" | [Verse 1] |
```

---

## 8. Riassunto

| Asse              | Valori                       | Decide                                |
|-------------------|------------------------------|---------------------------------------|
| Container         | `[…]` / `"…"`                 | box / no-box                          |
| Costrutto         | marker, label, annotation, … | size + weight + italic di default     |
| Markup utente     | `*…*`, `**…**`, `__…__`, `# …`, ecc. | override esplicito             |

I tre assi sono ortogonali. Nessuno dei tre vincola gli altri.

---

Questo documento definisce il **sistema di formattazione testuale**
unificato di neumaRk, applicabile a tutti i container testuali del
linguaggio.


---

# Markers

## 1. Cos’è un Marker

Un _marker_ è un elemento strutturale non musicale che identifica un punto significativo nel flusso del brano. I marker non si riferiscono a un elemento sonoro, non hanno durata musicale propria e non influiscono direttamente sul contenuto musicale (note, accordi, ritmi), ma servono a:

- segmentare il brano in sezioni logiche;
- facilitare la lettura e l’orientamento umano;
- fornire ancoraggi semantici per il rendering, la navigazione e il playback;
- supportare forme musicali, ripetizioni e riferimenti.

I marker fanno parte del **datapack musicale**, ma appartengono alla sfera della **struttura**, non della notazione musicale.

### Appartenenza semantica

Un _marker_ appartiene semanticamente a una **misura**.

Esso identifica, etichetta o qualifica una misura come unità strutturale
del brano e non è legato al flusso musicale o all’ordine di esecuzione.

---

## 2. Riga dei Markers

I marker sono contenuti in una **riga di markers**, che può essere:

- dichiarata esplicitamente con il marcatore di riga `M) `;
- dedotta implicitamente dal contenuto della riga.

### 2.1 Posizione nel datapack

- La riga dei markers, se presente, è **la prima riga del datapack**.
- È **opzionale**.
- Può comparire una sola riga di markers per datapack.

Best practice: collocare nella riga dei markers anche i **decoratori di misura** (volta, segno, coda, ecc.), per concentrare la struttura formale in un unico punto.

---

## 3. Sintassi dei Markers

Un marker è espresso in due forme container, che differiscono per il
**ruolo strutturale** e per la presenza del box grafico:

- **`[<testo>]`** — **sezione**: unità strutturale del brano, con box;
- **`"<testo>"`** — **annotazione**: testo descrittivo, senza box.

```
[Intro]            sezione (con box)
[A]                sezione
"freely"           annotazione
"swing feel"       annotazione
```

Il marker ammette il **markup testuale** definito in
`neumaRk_text_markup.md`. Lo stile di default è **bold, size body**, in
entrambe le forme.

### 3.1 Sezione vs annotazione

I due container hanno **valore semantico diverso**:

| Forma     | Tipo         | Valore strutturale            | Target PLAY/FORM | Chiude scope collapsible |
|-----------|--------------|-------------------------------|------------------|--------------------------|
| `[…]`     | sezione      | sì (unità del brano)          | sì               | sì                       |
| `"…"`     | annotazione  | no (testo descrittivo)        | no               | no                       |

Una **sezione** identifica un'unità strutturale ricorribile e
referenziabile (Intro, Verse, Chorus, A, B, …). Le sezioni sono i
target di `PLAY)` / `FORM)` (vedi `neumaRk_play_and_form.md` §3.1) e
delimitano lo scope delle sezioni collassabili (vedi §4).

Un'**annotazione** è un testo libero senza valore strutturale (es.
`"freely"`, `"swing feel"`, `"con feeling"`). Le annotazioni non sono
referenziabili da `PLAY)` / `FORM)` e **non chiudono** lo scope di una
sezione collassabile.

> **Nota normativa.** Questa distinzione è un raffinamento della
> spec 0.5, dove `[…]` e `"…"` erano considerate semanticamente
> equivalenti. Documenti esistenti sono retrocompatibili (le
> annotazioni `"…"` continuano a esistere come testo); l'unica
> differenza operativa è il binding selettivo da PLAY/FORM e il
> comportamento di `[? …]` (vedi §4).

### 3.2 Ancoraggio temporale

- Un marker si riferisce **all'inizio della battuta** in cui compare.
- Se preceduto da una barline e nella forma con box `[…]`, **deve essere
  separato da essa da almeno uno spazio**, per evitare ambiguità con i
  decoratori di volta.
- La forma `"…"` non collide con i decoratori di volta e può essere
  adiacente alla barline; resta tuttavia raccomandato lo spazio per
  leggibilità.

Esempio valido:

```
| [A]
| "freely"
```

Esempio non valido:

```
|[A]   // ambiguo: potrebbe essere interpretato come volta
```

---

## 4. Sezioni collassabili

Una sezione può essere dichiarata **collassabile** (anche detta
*opzionale*) anteponendo il prefisso `? ` (carattere `?` seguito da
**uno spazio**) all'interno del marker:

```
[? Verse]
[? Solo 2]
[? Outro]
```

Una sezione collassabile è una **proprietà UX** del marker: l'utente
può espandere/comprimere la sezione nell'interfaccia di lettura
(accordion). Lo stato espanso/compresso è preference utente, salvato in
user-index (Firestore `users/{uid}/song_view_state/{songId}`) e **non
nel file NRK**.

### 4.1 Scope della sezione collassabile

Lo scope di `[? NAME]` si estende dalla misura del marker fino al
primo dei seguenti eventi:

- **inizio di un'altra sezione** `[…]` (di qualsiasi nome,
  collassabile o no, incluso il marker anonimo `[!]` di §4.2);
- **fine del documento**.

Le **annotazioni** `"…"` interposte **non chiudono** lo scope:
appartengono comunque alla sezione collassabile corrente.

```
M) [? Verse] | … | "freely" | … | [Chorus] | …
   └─────── scope di Verse ─────┘
                                  └ Chorus apre nuovo scope
```

### 4.2 Marker anonimo `[!]` (chiusura implicita di sezione opzionale)

Quando una sezione opzionale termina e non c'è un marker successivo
che la chiude naturalmente (perché segue flusso "anonimo", non
strutturato come sezione), si usa il token speciale `[!]` (parentesi
quadre con un singolo `!`, senza spazi).

`[!]` è semanticamente un marker di **apertura di sezione non-opzionale
anonima**: aderisce alla convenzione "marker = inizio-misura" (§3.2)
e la chiusura dello scope precedente è il side-effect naturale della
regola §4.1.

```
M) [? Coda] | … | … | [!] | … |
   └── scope di Coda ─┘
                       └ flusso non-collassabile, anonimo
```

Proprietà:

- **Non renderizzato** come marker (nessun box, nessuna etichetta).
- **Non referenziabile** da `PLAY)` / `FORM)`: non ha NAME. Se usato
  come reference è reference-broken (vedi `neumaRk_play_and_form.md`
  §7.3).
- **Ammesso ovunque**: `[!]` non richiede una sezione opzionale
  aperta. Se non c'è scope da chiudere il token è ridondante (warning
  **W146**, non bloccante).

### 4.3 Niente annidamento

Una `[? Inner]` interna a un'altra `[? Outer]` **chiude** lo scope di
Outer e apre quello di Inner, secondo la regola generale §4.1. Non
esiste un meccanismo di sezioni collassabili annidate.

```
M) [? Outer] | … | [? Inner] | … |
   └ Outer ──┘   └─ Inner ─────…
```

### 4.4 Stato di default

All'apertura di un brano per la prima volta, le sezioni collassabili
sono **espanse**. L'utente le collassa esplicitamente; lo stato è poi
persistente in user-index.

Il `?` nel marker è ben evidenziato in UI (chevron nel margine, stile
distinto del titolo) perché la presenza di sezioni collassabili sia
immediatamente riconoscibile, anche quando tutte espanse.

### 4.5 Riferimenti da PLAY/FORM

Una sezione `[? NAME]` è referenziata da `PLAY)` / `FORM)` usando il
solo **NAME**, senza prefisso `?`:

```
M) [? Verse] | … | [Chorus] | …
PLAY) [Verse] [Chorus]
```

Il prefisso `?` è una proprietà UX della sezione, non parte del nome
strutturale. Il binding fra `PLAY)` e `M)` è per text-equality sul
NAME, ignorando il prefisso `?`.

### 4.6 Esecuzione

Lo stato collassato/espanso è **UX-only**: il player esegue una
sezione collassabile esattamente come una sezione ordinaria,
indipendentemente dal fatto che l'utente l'abbia collassata o espansa
nella vista.

Una sezione collassata non viene "saltata" dal player. Per omettere
una sezione dall'esecuzione esistono altri meccanismi (versioni,
`PLAY)` esplicita che la esclude).

### 4.7 Vincolo a inizio rigo

Una sezione collassabile **deve iniziare e finire a inizio rigo**
(= a inizio di un system / datapack). Concretamente:

- il marker `[? NAME]` deve comparire nella **prima misura** del
  system in cui appare;
- la chiusura dello scope (qualsiasi altro `[…]` o `[!]`) deve a sua
  volta comparire nella **prima misura** del system in cui appare;
- lo scope termina anche a EOF (caso valido).

Razionale: l'accordion UX comprime righe intere; una sezione che
inizia o finisce a metà rigo produrrebbe una resa ambigua (mezzo rigo
sparirebbe, lasciando moncheria visiva).

In caso di violazione:

- emessa **W151** (warning, non bloccante);
- la sezione **non è collassabile lato UX**: il toggle utente è
  ignorato sul render (la sezione resta sempre espansa).

---

## 5. Rilevanza identitaria

Il prefisso `~` su un marker di sezione la dichiara **identitaria**: ne
segnala il tema come quello che **caratterizza** il brano ("la parte che
fa riconoscere il pezzo"). È una proprietà **strutturale e portabile**
della composizione — viaggia col file — non un dato dell'host.

```
M) [Intro] | … |
M) [~ Tema] | … |          ← sezione identitaria del brano
M) [Coda] | … |
```

`~` **non è renderizzato** (nessun box, nessuna etichetta aggiuntiva: la
sezione si disegna come una `[Tema]` normale) ed è **preservato in
round-trip** dal serializer.

> La rilevanza identitaria è un'**annotazione musicale**, non un'etichetta
> host: indica *quale* musica caratterizza il brano. Il marker è
> **agnostico alla dimensione** d'analisi: l'host può derivarne ciò che
> serve sotto qualunque profilo — melodia, armonia, ritmo, ritmo armonico,
> ecc. (elenco non esaustivo). Lo spec definisce *quale regione* è
> identitaria; *cosa* se ne estrae e *su quale dimensione* è fuori dal
> linguaggio.

### 5.1 Scope della regione di rilevanza

Lo scope di `[~ NAME]` si estende dalla misura del marker fino al
**primo** dei seguenti eventi:

- l'inizio di una nuova sezione `[…]` **priva** del prefisso `~`;
- la fine del documento.

Una sezione successiva che porta **anch'essa** `~` **non chiude** la
regione: la **continua**. Sezioni `~` consecutive formano quindi
un'**unica** area di rilevanza; solo una sezione senza `~` la chiude.

```
M) [~ A] | … | [~ B] | … | [C] | … | [~ D] | …
   └──── area di rilevanza 1 (A+B) ────┘        └ area 2 (D)
                              └ C non rilevante, chiude l'area 1
```

Le **annotazioni** `"…"` interposte non chiudono lo scope (come in §4.1).

### 5.2 Più aree per brano

Sono ammesse **più aree di rilevanza melodica** nello stesso brano (le
`~` non consecutive sono aree distinte, vedi `[~ D]` sopra). Il modo in
cui l'host usa una o più aree (es. quale considerare per quale scopo)
non è materia di linguaggio.

### 5.3 Default (nessun marker `~`)

In assenza di qualsiasi `[~ …]` nel brano, la regione melodicamente
rilevante è **implicitamente** il tratto **dall'inizio del brano fino
alla prima sezione esclusa** (o fino a EOF se non ci sono sezioni). I
brani che non usano il marker hanno quindi una regione di rilevanza
ben definita e host-independent.

### 5.4 Marker anonimo `[~]`

`[~]` (parentesi quadre con un solo `~`, senza spazi) è una sezione
**anonima** identitaria: si comporta come il marker anonimo
`[!]` (§4.2) — apre una sezione non-opzionale e chiude lo scope
precedente — ma è **flaggata `~`**. Serve a marcare "da qui è
rilevante" quando il tema non è una sezione nominata. Specularmente, un
`[!]` (senza `~`) che segue una regione di rilevanza la **chiude**
(è una sezione priva di `~`, §5.1).

### 5.5 Composizione con `?` (collassabile + rilevante)

Una sezione può essere **insieme** collassabile e identitaria. I due
prefissi si accettano in **ordine libero** in input: `[?~ NAME]` e
`[~? NAME]` sono **equivalenti**. Essendo semanticamente identiche, il
serializer le **normalizza** alla forma canonica `[?~ NAME]` (come già
normalizza spaziatura e altri aspetti dei marker).

```
M) [?~ Bridge] | … |     ≡     M) [~? Bridge] | … |
```

### 5.6 Riferimenti da PLAY/FORM

Come per `?` (§4.5), una sezione `[~ NAME]` è referenziata da `PLAY)` /
`FORM)` con il **solo NAME**, senza prefisso. Il binding è per
text-equality sul NAME, ignorando i prefissi `~` e `?`.

```
M) [~ Tema] | … |
PLAY) [Intro] [Tema] [Coda]
```

### 5.7 Ancoraggio

`[~ NAME]` / `[~]` seguono l'ancoraggio delle sezioni (§3.2, §4.7):
compaiono a inizio misura; i confini di scope (sezione senza `~`, o EOF)
cadono a inizio rigo come ogni altro confine di sezione.

---

## 6. Play directive in riga `M)`

La riga `M)` ammette, oltre ai marker testuali `[…]` / `"…"`, anche
**play directive** nella forma `(=Style,Tempo)` per cambiare lo style
e/o il tempo del brano a partire da una misura specifica. Vedi
`neumaRk_play_directive.md` per la spec completa.

La play directive convive liberamente con i marker testuali nella
stessa misura. La disambiguazione fra i token è per **delimitatori**:

| Token            | Tipo                                 |
|------------------|--------------------------------------|
| `[…]`            | sezione (marker strutturale)         |
| `[? …]`          | sezione collassabile (vedi §4)       |
| `[~ …]`          | sezione identitaria (§5)             |
| `[!]`            | sezione anonima non-opzionale (§4.2) |
| `[~]`            | sezione anonima identitaria (§5.4)   |
| `"…"`            | annotazione (testo descrittivo)      |
| `(=…)`           | play directive                       |

Esempio:

```
M) | [Intro] (=Rock,120bpm) | | | [A] (=swing,140bpm) |
```

---

## 7. Regole di Validità

Una riga di markers è valida se:

- contiene solo sezioni `[…]` / `[? …]` / `[~ …]`, marker anonimi `[!]`
  / `[~]`, annotazioni `"…"` e play directive `(=…)`, separati da spazi e
  segni di battuta;
- non contiene pattern riconducibili a note o accordi;
- rispetta le regole di separazione da barline.

In caso di violazione:

- la riga **non viene riconosciuta come riga di markers**;
- il parsing del datapack prosegue secondo le regole di deduzione
  standard.

### 7.1 Codici diagnostici

| Codice | Severità | Descrizione                                              |
|--------|----------|----------------------------------------------------------|
| W146   | WARNING  | `[!]` ridondante: nessuna sezione opzionale da chiudere  |
| W151   | WARNING  | Sezione opzionale non-collassabile: `[? NAME]` o la sua chiusura non a inizio rigo (§4.7) |


---

# Flusso, Battute e Ripetizioni

Questo documento definisce la **semantica temporale** di neumaRk: battute, segni di battuta, decorator, ripetizioni e salti di flusso.

L’obiettivo è descrivere un sistema **deterministico**, testuale e leggibile, capace di rappresentare strutture musicali complesse senza ambiguità.

---

## 1. Battuta e segno di battuta (barline)

Le righe di **note** e **accordi**, così come quelle di altro tipo, contengono segni di battuta che delimitano le misure.

### 1.1 Segni di battuta ammessi

I segni di battuta riconosciuti sono:

```
|    ||    |.    .|    :|    |:
```

Regole:

- il segno di battuta finale di misura deve essere preceduto da uno spazio
- i segni composti (`:|`, `|:`) non ammettono spazi interni, **eccetto** la label compatta del ritornello di rimando (`:xN|`, `:open|`, vedi §6.1)

---

## 2. Decorator di misura

I **decorator** sono simboli o costrutti testuali adiacenti a una barline.

Essi modificano il flusso musicale, la struttura formale o il rendering.

Esistono due classi di decorator:

- **BEGIN decorator** → agiscono all’inizio della misura
- **END decorator** → agiscono alla fine della misura

La loro posizione è semanticamente rilevante.

### Decorators e segni di battuta

Un _decorator_ appartiene semanticamente a un **segno di battuta**.

I decorators qualificano il flusso musicale (ripetizioni, salti, coda,
fine, ecc.) e sono sempre associati a una barline specifica, non a una
misura in senso strutturale.

---

## 3. BEGIN decorator (a destra della barline)

### 3.1 Cambio di metro e tonalità

Fra parentesi tonde può essere indicato un nuovo metro e/o una nuova tonalità:

```
|(3/4,Dm)
```

Regole:

- metro e tonalità possono apparire in ordine arbitrario
- entrambi sono opzionali
- il metro può usare la forma con clave al numeratore (es. `[3+2]/8`)

Se presenti, questi decorator **devono essere i primi**, immediatamente adiacenti alla barline.

---

### 3.2 Volta (alternative ending)

Una parentesi quadra indica una **volta**:

```
|[1.]
```

La volta:

- si riferisce all’inizio della misura
- può includere un testo arbitrario

#### 3.2.1 Estensione della volta

La durata della volta può essere estesa aggiungendo `+n`:

```
|[1.]+4
```

In assenza di estensione, la volta si chiude **automaticamente** al primo segno di chiusura di ritornello (`:|`) incontrato entro **4 battute** (caso tipico dei finali `[1.]`).

Se nelle 4 battute successive non compare un `:|`, la volta non si chiude automaticamente e indica un'**uscita** (estensione esplicita `+n` raccomandata in tutti i casi non standard).

---

### 3.3 Segni di struttura

Altri BEGIN decorator ammessi:

- `$` → segno
- `@` → coda

Possono seguire i decorator di cambio metro/tonalità.

---

## 4. END decorator (a sinistra della barline)

Gli END decorator modificano il flusso **al termine della misura**.

### 4.1 Salti di flusso

Sono ammessi i seguenti costrutti:

- `DC` → Da Capo
- `DCal@` → Da Capo al Coda
- `DCalFINE` → Da Capo al Fine
- `D$` → Dal Segno
- `D$al@` → Dal Segno al Coda
- `D$alFINE` → Dal Segno al Fine

---

### 4.2 Fine e Coda

- `FINE` → termine del brano
- `al@` → salto alla coda

---

### 4.3 Decorator testuali

Un decorator testuale è espresso in due forme container,
**semanticamente equivalenti**, che differiscono solo per la presenza
del box grafico:

- **`[<testo>]`** — forma con box;
- **`"<testo>"`** — forma senza box.

```
[D.S.]:|            decorator testuale con box
"freely":|          decorator testuale senza box
[x4]                decorator testuale con box
```

Viene visualizzato in alto, al margine destro della misura.

Il decorator ammette il **markup testuale** definito in
`neumaRk_text_markup.md`. Lo stile di default è **plain, size body**,
in entrambe le forme.

Per il caso particolare di numero di esecuzioni di un ritornello
(`[xN]:|`) o di ritornello aperto (`[open]:|`), è disponibile anche la
forma compatta `:xN|` / `:open|` (vedi §6.1), che è **interpretata dal
player** come istruzione di esecuzione.

---

## 5. Ordine e combinazione dei decorator

Regole di composizione:

1. i decorator BEGIN precedono sempre il contenuto della misura
2. i decorator END seguono sempre il contenuto della misura
3. all’interno di ciascuna classe, l’ordine è semanticamente rilevante
4. in caso di conflitto, prevale il decorator più vicino alla barline

---

## 6. Ripetizioni

Le ripetizioni sono indicate tramite i segni di battuta:

- `|:` → inizio ripetizione
- `:|` → fine ripetizione

La semantica delle ripetizioni interagisce con:

- volte
- segni (`$`)
- DC / D$

La risoluzione del flusso deve essere **deterministica**.

### 6.1 Numero di esecuzioni e ritornello aperto

Per indicare **quante volte** eseguire un ritornello, o per marcarlo come **aperto** (numero non specificato, tipico delle code in stile jazz/pop), il segno `:|` ammette una **label compatta** fra i due caratteri:

- `:xN|` (o equivalentemente `:Nx|`) con `N` intero in `[2..99]` → eseguire il ritornello `N` volte
- `:open|` → ritornello aperto (numero di esecuzioni a discrezione dell'esecutore)

Esempi:

```
|: a b c d | e f g a :x8|
|: a b c d | e f g a :8x|
|: a b c d | e f g a :open|
```

Regole:

- il token è atomico: nessuno spazio fra `:`, la label e `|`
- `N` deve avere 1 o 2 cifre; `:x1|` / `:1x|` e `:x100|` / `:100x|` (o oltre) sono errore di parsing
- `open` è **case-insensitive**: `:open|`, `:Open|`, `:OPEN|` sono tutti accettati
- la label è renderizzata **sopra la barline, allineata a destra** (stessa posizione del decorator testuale `[xN]` di §4.3), nella forma canonica `xN` indipendentemente dall'ordine usato in input

#### 6.1.1 Relazione con la forma testuale `[xN]:|`

La forma compatta `:xN|` / `:open|` e la forma con decorator testuale
`[xN]:|` / `[open]:|` (§4.3) producono la **stessa resa grafica**, ma
hanno **semantiche di playback differenti**:

| Forma               | Render             | Play                                       |
|---------------------|--------------------|--------------------------------------------|
| `:xN|`              | box "xN" sopra     | **executable** — il player esegue N volte  |
| `:open|`            | box "open" sopra   | **executable** — repeat aperto (prompt UX) |
| `[xN]:|`            | box "xN" sopra     | **decorative** — il player usa default (2x) |
| `[text]:|`          | box "text" sopra   | **decorative** — testo arbitrario          |

La forma compatta `:xN|` è una **istruzione strutturata** che il
player legge ed esegue; la forma con decorator testuale è **testo
informativo** per l'umano, e il player la ignora ai fini del conteggio
delle ripetizioni (segue il default standard, tipicamente 2 esecuzioni).

Entrambe restano valide. La forma compatta è raccomandata per i
ritornelli di rimando dove il numero di esecuzioni deve essere
rispettato dal playback; la forma con decorator testuale resta utile
per label arbitrarie diverse da `xN`/`open` (es. `[D.S.]`, `[fade]`)
oppure quando il numero di esecuzioni è puramente informativo.

---

## 7. Ripetizione di misura

Il simbolo `%` indica la **ripetizione del contenuto della/e misura/e precedente/i**. Esistono sei forme, che distinguono la **resa grafica** dalla **realizzazione esplicita** del contenuto, per span di 1, 2 o 4 misure:

| Token | Resa | Span |
|-------|------|------|
| `%`   | glifo simile (`repeat1Bar`)         | 1 misura |
| `%!`  | copia visibile del contenuto        | 1 misura |
| `%2`  | glifo simile-2 (`repeat2Bars`)      | 2 misure |
| `%!2` | copia visibile del contenuto        | 2 misure |
| `%4`  | glifo simile-4 (`repeat4Bars`)      | 4 misure |
| `%!4` | copia visibile del contenuto        | 4 misure |

Le forme con `!` e senza `!` sono **musicalmente equivalenti**: differiscono solo nell'engraving.

### 7.1 Regole sintattiche

- il token è atomico: nessun whitespace fra `%`, `!`, e il numero
- 1 cell NRK = 1 misura: anche le forme con span > 1 (`%N`/`%!N` per N>1) occupano una sola misura per cell. **Il token compare in ognuna delle N misure consecutive del run.**

  Esempi (4/4):
  ```
  N) | a | b | %2  | %2  |
  N) | a | b | %!2 | %!2 |
  N) | a | b | c | d | %4 | %4 | %4 | %4 |
  N) | a | b | c | d | %!4 | %!4 | %!4 | %!4 |
  ```

- il token deve essere **l'unico contenuto** della sua misura (non miscelabile con note/accordi)
- `N` ammessi: `{1, 2, 4}` (corrispondono ai glifi SMuFL standard `repeat1Bar`, `repeat2Bars`, `repeat4Bars`). Altri valori (`%3`, `%5`, …) sono errore di parsing
- per i token `%N` glyph: il glifo SMuFL è disegnato **una sola volta** per run, ancorato alla **barline centrale** del run (N=2: barline fra m1 e m2; N=4: barline fra m2 e m3). Le altre misure del run sono musicalmente parte dell'evento ma non aggiungono notazione grafica
- non confondere con la ripetizione di evento nota `!` di `neumaRk_notes_and_durations.md` §5: il lexer riconosce `%!` come token unico

### 7.2 Scope e risoluzione

Il simbolo si applica alla **chord-row** e alla **notes-row**. La risoluzione è indipendente per row-type: un `%` nella chord-row eredita dalla chord-row precedente; un `%` nella notes-row eredita dalla notes-row precedente.

> **Classificazione di una riga di soli `%`.** Senza marker esplicito, una riga composta solo da `%` (più barline e spazi) è classificata secondo `neumaRk_datapack.md §3.bis.5` **TB1bis**: in testa al datapack e in assenza di una chord-row reale è una **chord-row** di ripetizioni (eredita gli accordi, anche cross-datapack); dopo una chord-row reale, o se contiene rest-token `r`/`!`, è una **notes-row**. Per forzare la lettura opposta usa il marker (`C)` per gli accordi, `N+`/`N)` per un rigo di note).

Per ogni misura del run, la sorgente è la misura **`i - N`** nella stessa row-type (offset semplice). Per `%2` ripetuto in run (`m_a m_b → %2 %2`), la 1ª misura `%2` ha sorgente `m_a`, la 2ª ha sorgente `m_b`. Stessa logica per N=4: ogni misura del run di 4 copia dalla corrispondente offset-4 indietro.

La risoluzione **risale la catena**: se la sorgente `i - N` è essa stessa un `%`/`%!`, si prosegue all'indietro usando l'`N` della misura sorgente incontrata, finché si raggiunge una misura "vera" (non-repeat). Questo rende corretto il caso idiomatico del run di `%` (N=1), in cui ogni `%` ripete la misura precedente:

```
N) | a | % | % |     → a a a
```

La 1ª `%` ha sorgente `a`; la 2ª `%` ha come sorgente la 1ª `%`, quindi risale ancora di 1 fino ad `a`. Nei misti la risalita usa l'offset della sorgente di volta in volta (es. `| a | b | %2 | %2 | % |`: l'ultima `%` risale alla 2ª `%2`, che ha sorgente `b` → la misura vale `b`). Il limite di risalita è 32 passi; oltre, o se non esiste alcuna misura sorgente valida, la misura è segnalata con **E300** (vedi §7.1 e la regola sotto).

`%`/`%!` non sono ammessi come prima misura del brano (e in generale se non esistono N misure precedenti nella stessa row-type).

### 7.3 Comportamento per layer

Quando il contenuto sorgente viene ereditato:

- **note, accordi, ritmo, durate** → copiati
- **articolazioni** (staccato, accento, tenuto, …) → copiate (sono attributi della nota)
- **dinamiche** point (`p`, `f`, `mf`, …) → **non** ri-emesse: la dinamica vigente prima della misura sorgente continua a valere per ereditarietà notazionale standard
- **dinamiche** spanning (cresc., decresc., hairpin) → troncate al confine della misura sorgente
- **lyrics** → **non** copiate

L'utente può **aggiungere** nuove lyrics o nuove dinamiche allineate a una misura `%`/`%!` senza confliggere col simbolo (sono layer paralleli).

### 7.4 Casi limite

- **Tie out dalla sorgente**: nel caso `%!` la copia mantiene la legatura di valore iniziale se la misura `%!` non è l'ultima della catena; la legatura propaga al successore. Per `%` la regola è la stessa, applicata al contenuto realizzato.
- **Cambio di chiave o di metro nella sorgente**: è strutturale e non viene ri-applicato nella misura `%`/`%!`.
- **Sorgente autofill**: se la misura sorgente è una rest-only di autofill, il `%` produce una misura di pause (comportamento intenzionale, non warning).

---

## 8. Righe di markers e best practice

I segni di battuta (semplici e composti — `|`, `||`, `|.`, `.|`, `:|`, `|:`) e i decoratori di misura si possono trovare in tutte le righe musicali (markers, accordi, articolazioni, note, dinamiche, lyrics).

L'unica eccezione è la riga di **Format**, che non ammette né segni di battuta né decoratori.

La riga dei markers, se presente, è quella più indicata per contenere i decoratori di flusso (DC, D$, coda, ecc.).

Dato che i markers sono indicati fra parentesi quadre e si riferiscono all'inizio della battuta, se sono preceduti da segno di battuta (con eventuali modificatori) devono essere da essa distanziati da uno spazio per differenziarsi da un volta-decorator.

---

## 9. Principi di risoluzione del flusso

- il flusso è risolto come una sequenza lineare di misure
- i salti non introducono ambiguità temporali
- ogni misura ha una posizione temporale unica


---

# PLAY) e FORM)

Questo documento definisce la sintassi e la semantica delle due sezioni
di neumaRk dedicate alla **forma del brano**:

- **`PLAY)`** — sub-programma di esecuzione, **inline** fra datapack,
  letto dal player nell'ordine del documento;
- **`FORM)`** — descrizione panoramica della forma, **una sola** per
  documento, posizionata in fondo, per uso umano e di indicizzazione.

Le due sezioni condividono la stessa **grammatica di box di sezione** e
lo stesso vocabolario di postfix, ma differiscono per posizione,
molteplicità e ruolo semantico (imperativo vs descrittivo).

---

## 1. Definizione

### 1.1 PLAY)

Una sezione `PLAY)` contiene un **sub-programma di esecuzione**: una
sequenza di box di sezione (con eventuali ripetizioni, dinamiche,
fermate, prosa libera) che il player esegue **al momento in cui la
incontra** nel documento.

Più sezioni `PLAY)` possono coesistere nello stesso documento; sono
lette **dall'alto in basso**, nell'ordine in cui appaiono.

### 1.2 FORM)

Una sezione `FORM)` contiene una **descrizione panoramica della forma**
del brano (es. "AABA con coda", oppure prosa estesa che dettaglia
articolazione e dinamica delle sezioni). Esiste al massimo **una**
`FORM)` per documento, posizionata **in fondo**.

`FORM)` non è eseguibile dal player: ha valore descrittivo, per il
lettore umano e per l'indicizzazione/ricerca.

> In una **playlist**, una voce può dichiarare un proprio `form` che
> **sostituisce** la `FORM)` del brano per quell'occorrenza ("la forma
> di stasera è questa"). È un overlay descrittivo a livello di
> scaletta, non eseguito; `PLAY)`, essendo posizionale, non è
> esprimibile a quel livello. Vedi `neumaRk_collections.md` §8.

### 1.3 Distinzione semantica

| Aspetto      | `PLAY)`                            | `FORM)`                           |
|--------------|------------------------------------|-----------------------------------|
| Ruolo        | imperativo ("esegui questo")        | descrittivo ("ecco la forma")     |
| Molteplicità | multiple, inline                   | al massimo una, in fondo          |
| Player       | esegue                             | ignora                            |
| Uso          | playback, sketch di esecuzione     | summary, ricerca, didattica       |

La scelta fra "il player esegue PLAY" e "il player segue il flusso
naturale dei datapack" **non è una proprietà del documento**: è una
**preference utente** salvata nello user-index (toggle UI). Il
documento contiene entrambe le forme di informazione; l'utente decide
cosa visualizzare/eseguire.

---

## 2. Posizione strutturale

### 2.1 PLAY)

- È **una riga di sezione**, marcata da `PLAY)` come primo token.
- Compare **fra datapack**, mai dentro un datapack.
- È **non ricorsiva by design**: una `PLAY)` non può apparire come
  riga interna di un'altra `PLAY)`. Garanzia statica del parser.
- Una `PLAY)` può estendersi su **più righe** del documento: il
  newline è whitespace dentro la sezione (vedi §6).

La sezione `PLAY)` termina al primo dei seguenti eventi:

- inizio del datapack successivo (riga che apre con un marcatore
  musicale `M)`, `C)`, `N)`, `A)`, `D)`, `L)`, `F)`);
- inizio di un'altra sezione (`PLAY)`, `FORM)`);
- fine del documento.

### 2.2 FORM)

- È **una riga di sezione**, marcata da `FORM)` come primo token.
- Compare **alla fine del documento**, dopo l'ultimo datapack.
- È **unica** per documento. Più `FORM)` producono warning **W140**.
- Una `FORM)` può estendersi su più righe (newline = whitespace).

`FORM)` termina solo a fine documento.

---

## 3. Grammatica del box di sezione

Sia in `PLAY)` sia in `FORM)`, l'unità atomica è il **box di sezione**:

```
SECTION_BOX  := TOP_LABEL? '[' NAME ('|' BARS)? ']' POSTFIX*
TOP_LABEL    := '"text"'           // adiacente, no spazio
POSTFIX      := REPEAT | DYNAMIC | HAIRPIN | KEYWORD | BOTTOM_LABEL
                                    // tutti adiacenti al precedente
```

Tutti i token del box sono **adiacenti**: nessuno spazio fra
top-label, parentesi quadre, postfix.

### 3.1 NAME

Il `NAME` dentro `[…]` è il **nome di una sezione** definita da una
riga `M)` del documento (`neumaRk_markers.md` §3). Il matching è per
**text-equality** sul contenuto della sezione (dopo strip del markup,
vedi §3.2 di `neumaRk_text_markup.md` §7.1).

Il binding è **selettivo**: vengono considerate solo le **sezioni**
`[…]` di M) (incluse le collassabili `[? NAME]`, con il prefisso `?`
ignorato nel matching). Le **annotazioni** `"…"` di M) non sono
referenziabili da `PLAY)` / `FORM)` (vedi
`neumaRk_markers.md` §3.1).

Esempi:

```
[A]       riferisce una sezione [A] in M)
[Intro]   riferisce [Intro] o [? Intro] (prefisso ? ignorato)
[Solo 1]  multi-parola, riferisce [Solo 1] o [? Solo 1]
```

Una `"freely"` in M) **non** è target valido: `[freely]` in PLAY/FORM
sarebbe reference broken (vedi §7.3).

Se il NAME non corrisponde a nessun marker definito nel documento, il
box è **reference broken**: viene renderizzato come testo
non-cliccabile, **non eseguito**, e **non genera errore o warning**
(vedi §7.3).

### 3.2 Durata in misure `[NAME|BARS]`

Opzionale: un `|` interno e un numero di battute.

```
[A|8]     A per 8 misure (informativo)
[B|4]     B per 4 misure
[A]       A senza durata dichiarata
```

`BARS` è un **intero positivo** (1–999). Decimali, zero o negativi
producono warning **W141**.

La durata in `[NAME|BARS]` ha valore **puramente informativo**: è un
hint grafico per il lettore. Non viene confrontata con l'estensione
reale della sezione marcata `M)`; è responsabilità di chi scrive
mantenere coerenza. Nessun warning o errore in caso di discrepanza.

Le durate sono ammesse **solo** in `PLAY)` / `FORM)`. Un marker in
`M)` non ammette `|N` (vedi `neumaRk_markers.md`).

### 3.3 Top e bottom label

Top label: container `"…"` **adiacente prima** di `[`.
Bottom label: container `"…"` **adiacente dopo** la parentesi quadra
chiusa (può apparire come postfix in qualsiasi ordine, vedi §3.4).

```
"Tema"[A|8]                  solo top
[A|8]"Variazione"            solo bottom
"Tema"[A|8]"con feeling"     top + bottom
```

Le label ammettono **solo** il container `"…"` (senza box). La forma
`[…]` collide grammaticalmente con il box di sezione e non è ammessa
come label.

Le label sono soggette al **markup unificato** di
`neumaRk_text_markup.md`. Stile di default: **plain, dimensione
ridotta**.

### 3.4 Postfix

Sono tutti **adiacenti** al token precedente (no spazi). L'ordine
fra postfix è **libero**: il parser identifica ogni postfix per la
sua forma. La pluralità è ammessa solo per la bottom label (una sola
per box) e per le keyword (più keyword distinte possibili).

#### 3.4.1 Repeat count

`xN` con `N` in 2–99 indica numero di esecuzioni:

```
[A|8]x2       esegui A due volte (×2)
[A|8]x4       esegui A quattro volte
```

`x1` o `x0` o `xN` con `N > 99` produce warning **W142**.

#### 3.4.2 Dynamic

Dynamic puntuale del vocabolario `D)` (vedi `neumaRk_dynamics.md` §3.1):

```
[A|8]ff       sezione A a fortissimo
[B|4]p        sezione B a piano
```

Vale per **tutta la durata della sezione**.

#### 3.4.3 Hairpin

`<` o `>` adiacenti aprono un hairpin **solo dentro il box di
apertura**: si chiude alla prossima dynamic adiacente, anch'essa dentro
lo stesso postfix-stack.

```
[A|8]<ff      cresc. fino a ff alla fine della sezione
[B|4]>p       decresc. fino a p
```

Hairpin **non cross-box**: `[A|8]< [B|4]ff` apre un hairpin che non
trova chiusura nel box A e viene chiuso implicitamente a fine box.
Nessun errore, render decide la rappresentazione.

#### 3.4.4 Keyword

Famiglia `&keyword`, case-insensitive, prefix per estensioni future.

| Keyword       | Effetto                                                |
|---------------|--------------------------------------------------------|
| `&fermata`    | corona sul beat finale della sezione                   |
| `&caesura`    | cesura dopo la sezione                                 |
| `&breath`     | respiro dopo la sezione                                |
| `&GP`         | grand pause dopo la sezione                            |
| `&niente`     | dinamica "al niente" (decresc. fino al silenzio)       |

Le keyword sono **riservate**: keyword sconosciute producono errore
**W143**. La lista è estendibile in versioni future della spec.

#### 3.4.5 Bottom label

Container `"…"` adiacente, vedi §3.3.

### 3.5 Esempi di box completi

```
[A]                            riferimento minimale
[A|8]                          A per 8 misure
"Tema"[A|8]                    A con top label
[A|8]x2&fermata                A ripetuto 2× con corona finale
"Tema"[A|8]ff<>p"crescendo"x2  combinazione complessa
[FREE IMPRO!]                  reference broken (no marker omonimo)
```

---

## 4. Token speciali ammessi in PLAY/FORM

Oltre ai box di sezione, sono ammessi:

| Token       | Effetto                                                 |
|-------------|---------------------------------------------------------|
| `$`         | segno (segno musicale, target di D.S.)                  |
| `@`         | coda (target di D.C. al Coda)                           |
| `&fermata`  | corona stand-alone (fuori da un box)                    |

Questi token mantengono la stessa semantica dei decorator inline
omonimi delle righe musicali (vedi `neumaRk_flow_and_repeats.md`).

---

## 5. Prosa libera

Tutto ciò che non è un token strutturale (box, `&keyword`, `$`, `@`) è
**prosa libera** in modalità markup `neumaRk_text_markup.md`.

```
PLAY) [Intro] then go to [A|8] twice [A|8]x2 finally [Outro]
```

In questo esempio "then go to", "twice", "finally" sono prosa libera
interpolata fra box. Vengono renderizzate come testo descrittivo nel
display della PLAY (es. in una banda separata o accanto al box).

Il **player ignora** la prosa libera in `PLAY)`: esegue solo i box e i
token strutturali. La prosa libera è valore esclusivamente
informativo per il lettore.

In `FORM)`, l'intero contenuto è prosa descrittiva con box di sezione
interpolati: il player non esegue nulla di `FORM)` in ogni caso.

---

## 6. Whitespace e continuazione

### 6.1 Newline = whitespace, blank line = terminator

Dentro `PLAY)` e `FORM)`, un **singolo newline** ha lo stesso valore
di uno spazio: la sezione può estendersi su quante righe l'utente
preferisce, semplicemente proseguendo (eventualmente con
indentazione) sulla riga successiva.

```
PLAY) [Intro]
      [A|8]x4
      [B|8]
      [A|8]
      [Outro]&fermata
```

è equivalente a:

```
PLAY) [Intro] [A|8]x4 [B|8] [A|8] [Outro]&fermata
```

Una **riga vuota** (blank line) invece **chiude** la sezione,
coerentemente con la convenzione del resto del linguaggio NRK dove
una blank line separa i datapack. Quanto segue è quindi
interpretato fuori dalla `PLAY)`:

```
PLAY) [Intro]
      [A|8]

C7
a
```

Le tre righe `C7` / `a` formano un nuovo datapack indipendente; la
sezione `PLAY)` si è chiusa dopo `[A|8]`.

### 6.2 Continuazione esplicita

Non è richiesto alcun carattere di continuazione. La sezione termina
al primo dei seguenti eventi (vedi anche §2.1 / §2.2):

- prossimo prefisso di datapack (`M)/C)/N)/A)/D)/L)/F)`);
- nuova sezione globale (`PLAY)`, `FORM)`, `%%…`);
- **riga vuota**;
- fine documento.

---

## 7. Semantica del player

### 7.1 Modello base

Senza alcun `PLAY)` nel documento, il player esegue i datapack
nell'ordine del documento, applicando i decorator standard (volte,
ripetizioni, D.S., D.C., coda) descritti in `neumaRk_flow_and_repeats.md`.

### 7.2 Con `PLAY)`

Quando il player incontra una sezione `PLAY)`, esegue il
sub-programma in essa contenuto **al posto** del flusso naturale dei
datapack a quel punto. Dopo aver completato la `PLAY)`, prosegue dal
datapack immediatamente successivo nel documento.

Multiple `PLAY)` consecutive sono lette in ordine: il player esegue
ciascuna a turno. Datapack interposti fra una `PLAY)` e l'altra sono
**ignorati** dal flusso eseguito, se referenziati da box di sezione
dentro le `PLAY)` (i datapack sono comunque tabellati per nome marker;
servono come "definizione" delle sezioni, non come flusso lineare).

### 7.3 Reference broken

Un box `[NAME]` il cui `NAME` non corrisponde a nessun marker `M)` del
documento è **reference broken**:

- viene renderizzato come testo non-cliccabile (visibile, marcato come
  irrisolvibile);
- **non viene eseguito** dal player;
- **non genera warning o errore**.

Questo permette di scrivere PLAY/FORM come sketch o annotazione
informale senza vincoli sulla coerenza con i marker del documento.

### 7.4 Esecuzione di un box

L'esecuzione di un box `[A|8]ff<x2&fermata` consiste in:

1. salto al primo datapack la cui riga `M)` contiene il marker `A`;
2. applicazione della dinamica `ff` come dynamic iniziale della
   sezione;
3. esecuzione di tutti i datapack della sezione `A` (fino al prossimo
   marker o fine documento), con hairpin `<` se presente;
4. ripetizione N volte (per `xN`);
5. corona finale (per `&fermata`).

La durata `|8` non influisce sull'esecuzione: l'estensione effettiva è
data dai datapack del documento.

---

## 8. Render

### 8.1 PLAY)

Le sezioni `PLAY)` sono renderizzate come **banda compatta** sopra o
sotto lo score, con i box di sezione disegnati come **rettangoli con
NAME e durata** (se presente). Le label, dinamiche, hairpin e keyword
sono renderizzate accanto al box secondo le convenzioni tipografiche
musicali.

I box reference broken sono renderizzati con stile distinto (es. testo
italic in grigio chiaro) per segnalare l'irrisolvibilità senza
ostacolare la lettura.

### 8.2 FORM)

Le sezioni `FORM)` sono renderizzate come **blocco descrittivo** in
calce al documento, con prosa Markdown interpolata ai box di sezione.
Lo stile è meno enfatico di `PLAY)`: testo body, box con bordo sottile.

### 8.3 Markup

Tutti i testi (top/bottom label, prosa libera) supportano il markup
unificato di `neumaRk_text_markup.md` §3. Lo stile di default è quello
indicato in `neumaRk_text_markup.md` §5 (label: plain ridotto; prosa
PLAY/FORM: plain body).

---

## 9. Diagnostica

### 9.1 Codici diagnostici

| Codice | Descrizione                                                                |
|--------|----------------------------------------------------------------------------|
| W140   | Più di una sezione `FORM)` nel documento                                   |
| W141   | Durata `|BARS` non valida (atteso intero 1–999)                            |
| W142   | Repeat count `xN` fuori range (atteso 2–99)                                |
| W143   | Keyword `&xxx` non riservata                                               |
| W145   | `FORM)` non in fondo al documento (datapack successivi a `FORM)`)          |

> `PLAY)` nidificata (dentro un'altra `PLAY)` o dentro un datapack) è **impedita
> strutturalmente** (§3, non-ricorsiva by design): il parser non la produce mai e
> **non emette alcuna diagnostica**. Il codice `W144` è usato dal parser per la
> legatura `A)` malformata (vedi `neumaRk_articulations.md`).

### 9.2 Non-errori

I seguenti non sono errori (vedi §3.1, §3.2):

- box `[NAME]` con NAME non riconducibile a nessun marker (reference
  broken);
- discrepanza fra durata `|N` dichiarata e numero reale di misure
  della sezione;
- hairpin aperto senza chiusura entro fine box;
- prosa libera con caratteri arbitrari (purché non coincida con
  pattern strutturali).

---

## 10. Esempi

### 10.1 PLAY minimale

```
M) [Intro]
… datapack Intro …

M) [A]
… datapack A …

M) [B]
… datapack B …

PLAY) [Intro] [A|8]x2 [B|8] [A|8]
```

Il player esegue: Intro → A → A → B → A.

### 10.2 PLAY con dinamiche e keyword

```
PLAY) [Intro]p [A|8]<ff [B|4]x2 [A|8]>pp&fermata
```

- Intro a piano.
- A con crescendo fino a ff su 8 misure.
- B ripetuto 2 volte (mantiene ff).
- A con decresc. fino a pp, corona finale.

### 10.3 PLAY con prosa libera

```
PLAY) Start with [Intro] freely.
      Then [A|8] twice, then [B|8].
      Optional [C|4] if vibe is right.
      End on [Outro] &fermata.
```

Prosa interpolata serve il lettore; il player esegue solo i box:
Intro → A → A → B → C → Outro+fermata.

### 10.4 FORM descrittiva

```
M) [Intro]
…

M) [A]
…

M) [B]
…

FORM) Standard AABA jazz: [Intro|4] sets the mood, then
      [A|8] is the main theme, [A|8] repeats with melodic
      variation, [B|8] is the bridge (modulating to IV), and
      a final [A|8] resolves to a [Coda|4] tag.
```

`FORM)` descrive la forma; il player la ignora (esecuzione segue il
flusso documento o eventuali `PLAY)` separate).

### 10.5 Reference broken (sketch informale)

```
PLAY) [Intro] [FREE IMPRO! whatever feels right] [A|8] [Outro]
```

`[FREE IMPRO! whatever feels right]` non è un marker definito: viene
renderizzato come testo descrittivo (irrisolvibile) e saltato dal
player. Esecuzione: Intro → A → Outro.

### 10.6 Multiple PLAY in sequenza

```
M) [A]
…

M) [B]
…

PLAY) [A|8] [B|8]

M) [C]
…

PLAY) [C|8]x3 &fermata
```

Il player esegue: A → B (prima PLAY), poi C → C → C con corona
(seconda PLAY). Il datapack `[C]` definisce la sezione referenziata
dalla seconda PLAY ma non viene eseguito linearmente dal flusso
documento (è già coperto dalla seconda PLAY).

### 10.7 Toggle player vs flow naturale

Lo stesso documento può essere:

- **letto come PLAY**: il player segue la/le `PLAY)` e ignora il
  flusso lineare dei datapack;
- **letto come flow**: il player ignora le `PLAY)` e segue i datapack
  in ordine documento.

La scelta è preference utente (user-index), non proprietà del
documento.

---

## 11. Riassunto

| Concetto              | Sintassi                                          | Sezione |
|-----------------------|---------------------------------------------------|---------|
| Sezione PLAY          | `PLAY) …`                                         | §1.1    |
| Sezione FORM          | `FORM) …`                                         | §1.2    |
| Box di sezione        | `"top"?[NAME(|BARS)?]POSTFIX*`                    | §3      |
| Top label             | `"text"` adiacente prima di `[`                   | §3.3    |
| Bottom label          | `"text"` adiacente come postfix                   | §3.3    |
| Repeat count          | `xN` (N 2–99)                                     | §3.4.1  |
| Dynamic               | `p`/`mp`/`mf`/`f`/`ff`/`sf`/`sfz` postfix         | §3.4.2  |
| Hairpin               | `<` / `>` postfix (no cross-box)                  | §3.4.3  |
| Keyword               | `&fermata`/`&caesura`/`&breath`/`&GP`/`&niente`   | §3.4.4  |
| Segno / coda          | `$` / `@`                                         | §4      |
| Prosa libera          | tutto ciò che non è token strutturale             | §5      |
| Whitespace            | newline = spazio                                  | §6      |
| Reference broken      | `[NAME]` senza marker omonimo, non eseguito       | §7.3    |
| Durata informativa    | `|BARS` solo grafica, no controllo                | §3.2    |
| Toggle player/flow    | preference utente                                 | §1.3    |

---

Questo documento definisce `PLAY)` e `FORM)` come le due sezioni di
neumaRk dedicate alla **forma del brano**, completando il vocabolario
strutturale del linguaggio insieme a `M)` marker, `D)` annotation e
play directive.


---

# Play directive

Questo documento definisce la sintassi e la semantica della **play
directive**: un meccanismo per cambiare in modo locale lo **style** e il
**tempo** del brano, agendo a partire da una misura specifica e
restando in vigore fino a una nuova direttiva.

La play directive risolve l'esigenza di lead sheet con sezioni a tempo
o groove diversi (es. "vamp till cue" rallentando, "double-time" su un
solo, cambio da swing a latin a metà brano) senza ricorrere a brani
distinti.

---

## 1. Definizione

Una play directive è un **token** della riga `M)` (Markers) che
dichiara, in modo locale, uno o entrambi i seguenti elementi:

- uno **style** (descrizione testuale del carattere musicale);
- un **tempo**, espresso come BPM esplicito oppure come metric
  modulation (relazione metrica fra due figure NRK).

La play directive **non è un decoratore di barline**: non si attacca al
segno `|` e non appartiene alla famiglia dei decoratori di misura
(`[1.]` volta, `(3/4,Dm)` cambio metro/tonalità). È un token autonomo
che convive con i marker testuali nella riga `M)`.

---

## 2. Sintassi

### 2.1 Forma generale

Due forme alternative:

```
(=[Style][,Tempo])         con prefisso `=` (Style/BPM/combinato)
(<figura>=<figura>)        metric modulation pura (senza prefisso)
```

Dentro le parentesi tonde:

- Il **prefisso `=`** apre una direttiva con slot Style e/o Tempo
  (BPM o metric modulation), distinguendola da un cambio metro o
  tonalità `(3/4,Dm)`.
- Una direttiva di **sola metric modulation** (es. `(4=4.)`) si
  scrive **senza prefisso `=`**: la `=` interna fra due figure NRK
  è già auto-disambiguante rispetto agli altri token in parentesi.

Quando il prefisso `=` è presente e Style/Tempo sono entrambi
dichiarati, l'ordine è **fisso**: Style prima, Tempo dopo, separati
da virgola.

### 2.2 Slot _Style_

Testo libero che descrive il carattere musicale (es. `Rock`,
`Fast swing`, `rock ballad`, `bossa`, `funk`). Valgono le stesse regole
testuali dello slot `HS) Style` dell'header
(`neumaRk_header.md` §11.2):

- testo libero multi-parola, spazi interni ammessi;
- **virgole interne ammesse** (es. `Fast, dirty swing`): il parser
  ricostruisce lo Style usando la regola "parse from end" descritta sotto;
- nessun vincolo di capitalization (il rendering preserva la grafia);
- non deve collidere con pattern interpretabili come `Tempo` (vedi §2.3
  e §3.2).

#### 2.2.1 Disambiguazione Style/Tempo ("parse from end")

Quando la direttiva contiene una virgola, il parser cerca **l'ultima**
virgola e prova a interpretare ciò che segue come Tempo (BPM o metric
modulation). Se il match riesce → split lì (Style = tutto a sinistra,
Tempo = tutto a destra). Se fallisce, il body intero è trattato come
un unico slot (Style se l'utente non ha tentato un Tempo, oppure
Tempo-only se non ci sono virgole e il body è un Tempo valido).

Conseguenze pratiche:

| Body                              | Style                | Tempo  |
|-----------------------------------|----------------------|--------|
| `=Rock,120bpm`                    | `Rock`               | 120bpm |
| `=Fast, dirty swing, 180bpm`      | `Fast, dirty swing`  | 180bpm |
| `=swing, 4=4.`                    | `swing`              | 4=4.   |
| `=foo, bar` (no Tempo finale)     | `foo, bar`           | —      |
| `=120bpm` (no virgola, è Tempo)   | —                    | 120bpm |

### 2.3 Slot _Tempo_

Due forme alternative, mutuamente esclusive:

#### 2.3.1 BPM esplicito

```
Nbpm
```

dove `N` è un **intero a 2 o 3 cifre** (range 10–999), seguito
immediatamente dal suffisso `bpm` (case-insensitive: `bpm`, `BPM`,
`Bpm` tutti ammessi). Esempi:

```
60bpm     120bpm     200bpm     90BPM
```

Range fuori bounds (`5bpm`, `1000bpm`) produce warning **W136**.
Decimali (`120.5bpm`) non sono ammessi (errore di parsing).

#### 2.3.2 Metric modulation

```
<figura-precedente>=<figura-nuova>
```

dove ciascun lato è una **figura NRK** (`1`, `2`, `4`, `8`, `16`, `32`,
con dotted `.` e tuplet `t` ammessi). Convenzione standard (Grove,
Carter): il valore a **sinistra** è una figura nel **tempo precedente**,
il valore a **destra** è una figura nel **tempo nuovo**; le due figure
hanno la stessa durata fisica. Esempi:

```
4=2     ♩ = 𝅗𝅥    (la semiminima del tempo precedente vale come minima nuova → double-time)
4=4.    ♩ = ♩.   (la semiminima precedente vale come semiminima puntata nuova → accelera)
2=4     𝅗𝅥 = ♩    (la minima precedente vale come semiminima nuova → half-time)
4.=4    ♩. = ♩   (la semiminima puntata precedente vale come semiminima nuova → rallenta)
8t=8    ♪₃ = ♪   (la croma di terzina precedente vale come croma nuova → accelera)
```

La metric modulation è **executable**: il player ricalcola il BPM
effettivo dalla relazione metrica applicata al `currentBPM` corrente
(formula in §5.2). Figure non valide (es. `5=4`, `4=k`) producono
warning **W137**.

### 2.4 Esempi sintattici

```
(=Rock,120bpm)                 style + tempo
(=swing,4=4.)                  style + metric modulation
(=fast swing)                  solo style (multi-parola)
(=Fast, dirty swing, 180bpm)   style con virgole interne + tempo
(=foo, bar)                    solo style con virgola (no Tempo finale)
(=120bpm)                      solo BPM
(8=4)                          solo metric modulation (NO prefisso `=`)
```

Forme non valide:

```
(=)                        W134 — direttiva vuota
(=120bpm,Rock)             W135 — ordine slot invertito
(=5bpm)                    W136 — BPM fuori range
(4=q)                      W137 — figura NRK non valida
```

---

## 3. Posizione strutturale

### 3.1 Solo nella riga `M)`

Una play directive può apparire **esclusivamente** in una riga di
Markers (`M)`, esplicita o dedotta secondo
`neumaRk_markers.md` §2). La sua presenza in qualunque altra riga
musicale (`C)`, `N)`, `A)`, `D)`, `L)`, `F)`) produce warning **W138**.

### 3.2 Co-locazione con marker testuali

Una play directive convive **liberamente** con marker testuali
(`[Mark]`, `"freely"`) nella stessa misura della riga `M)`. La
disambiguazione è per **delimitatori**:

| Token            | Tipo                                    |
|------------------|-----------------------------------------|
| `[…]` / `"…"`    | marker testuale                         |
| `(=…)`           | play directive (Style/BPM/combinato)    |
| `(fig=fig)`      | play directive (metric modulation pura) |
| `(…)` altro      | decorator di barline (cambio metro/key) — non in `M)` |

Esempio:

```
M) | [A] (=Rock,120bpm) |
```

Misura 1 contiene sia il marker `[A]` sia la play directive che imposta
Rock 120 BPM dalla stessa misura in poi.

L'ordine fra marker testuali e play directive è **libero** nella
stessa misura: il parser identifica i token per delimitatori.

### 3.3 Ancoraggio temporale

Una play directive si applica a partire dal **beat 1 della misura di
apparizione**, e resta in vigore fino a una nuova play directive (vedi
§4).

Non sono ammessi cambiamenti mid-bar: la posizione orizzontale del
token nella riga `M)` non altera il punto di applicazione, che è
sempre l'inizio della misura.

---

## 4. Persistenza e contesto

### 4.1 State machine `currentStyle` / `currentBPM`

Il contesto musicale persistente del brano (`neumaRk_specification.md`
§2.1) include due variabili **cross-datapack**:

- `currentStyle` — inizializzato da `HS) Style` dell'header;
- `currentBPM` — inizializzato da `HB) BPM` dell'header.

Ogni play directive **aggiorna** una o entrambe le variabili, a partire
dalla misura di apparizione. Le variabili restano poi in vigore fino a
una nuova play directive, **attraversando i confini fra datapack**.

### 4.2 Direttive a slot singolo

Una direttiva che dichiara un solo slot **aggiorna solo quella
variabile**, lasciando l'altra invariata:

```
M) | (=Rock,120bpm) | | (=fast swing) | (2=4) |
```

- Misura 1: `currentStyle ← Rock`, `currentBPM ← 120`.
- Misura 3: `currentStyle ← fast swing`, `currentBPM` resta 120.
- Misura 4: `currentBPM ← currentBPM × (2/4) = 60` (metric modulation),
  `currentStyle` resta "fast swing".

### 4.3 Niente reset esplicito

Non esiste un token speciale per "tornare ai valori dell'header". Per
ripristinare lo style/BPM iniziale si ridichiara esplicitamente:

```
HS) swing
HB) 140

…
M) | (=Rock,80bpm) | … | (=swing,140bpm) |    ← ripristino esplicito
```

Questa scelta mantiene la spec ortogonale: ogni direttiva è un'azione
positiva, non c'è semantica nascosta di "spegnimento".

---

## 5. Semantica del player

### 5.1 Executable

Le play directive sono **istruzioni eseguibili** dal player runtime:

- un cambio di `currentBPM` (esplicito o via metric modulation) altera
  immediatamente la velocità di esecuzione;
- un cambio di `currentStyle` segnala al motore di accompagnamento di
  cambiare groove (Rock → Bossa → Swing produce pattern diversi di
  batteria, basso, chitarra di accompagnamento).

L'effettiva mappatura `style → groove` è responsabilità del player e
non è definita da questa specifica. Style sconosciuti al player sono
trattati come fallback al groove di default, senza errore.

### 5.2 Metric modulation: calcolo del BPM

Convenzione (musicale standard, vedi Grove Music Online ed Elliott
Carter): in una metric modulation `S = D` il valore a **sinistra** è
una figura nel tempo **precedente**, il valore a **destra** è una
figura nel tempo **nuovo**. Le due figure hanno la **stessa durata
fisica**.

Da questa equivalenza si deriva:

```
dur(S) × (60 / oldBPM) = dur(D) × (60 / newBPM)
⟹ newBPM = oldBPM × dur(D) / dur(S)
```

dove `dur(F)` è la durata della figura NRK `F` in beat unitari
(quarter = 1, whole = 4, half = 2, eighth = 0.5; dotted = 1.5×;
tuplet `t` = 2/3×).

Esempi (assumendo `currentBPM = 120`):

| Modulation | newBPM      | Effetto musicale                   |
|------------|-------------|------------------------------------|
| `4=2`      | 240         | double-time (old ♩ → new 𝅗𝅥)       |
| `4=4.`     | 180         | accelera (old ♩ → new ♩.)          |
| `8t=8`     | 180         | accelera (old ♪₃ → new ♪)          |
| `2=4`      | 60          | half-time (old 𝅗𝅥 → new ♩)         |
| `4.=4`     | 80          | rallenta (old ♩. → new ♩)          |

---

## 6. Render

### 6.1 Fascia marker

Tutte le play directive sono renderizzate nella **stessa fascia dei
marker** (sopra il rigo), allineate orizzontalmente al beat 1 della
misura di apparizione.

### 6.2 Style

Lo style è renderizzato come **testo italic**, dimensione body. Quando
co-localizzato con un marker testuale nella stessa misura, il renderer
applica un offset verticale per evitare sovrapposizione, mantenendo
entrambi visibili.

### 6.3 Tempo BPM esplicito

`Nbpm` è renderizzato in **notazione tradizionale**:

```
♩ = N
```

dove la figura della pulsazione è derivata dal denominatore del metro
corrente (4/4 → ♩, 6/8 → ♪., 3/2 → 𝅗𝅥, ecc.). In assenza di un metro
identificabile, default `♩`.

### 6.4 Metric modulation

`figura₁=figura₂` è renderizzato in notazione tradizionale come:

```
glyph(figura₁) = glyph(figura₂)
```

dove `glyph(F)` è la testa di nota nera/bianca/aperta della figura `F`,
con dot se dotted, con `³` (o equivalente) se tuplet.

Esempi:

```
4=4.    →   ♩ = ♩.
8=4     →   ♪ = ♩
8t=8    →   ♪³ = ♪
```

### 6.5 Style + Tempo combinati

Quando una direttiva contiene entrambi gli slot, il render presenta
**style sopra il tempo** in due righe verticali, oppure sulla stessa
riga separati da spazio. La scelta è del renderer.

---

## 7. Diagnostica

### 7.1 Codici diagnostici

| Codice | Descrizione                                                              |
|--------|--------------------------------------------------------------------------|
| W134   | Direttiva vuota `(=)`: nessuno slot dichiarato                           |
| W135   | Ordine slot invertito: tempo prima di style                              |
| W136   | BPM fuori range (atteso intero 10–999)                                   |
| W137   | Figura NRK non valida in metric modulation                               |
| W138   | Play directive in riga diversa da `M)`                                   |

### 7.2 Style sconosciuto

Uno style non riconosciuto dal player (es. `(=mood music)`) **non è un
errore**: viene rispettato come testo descrittivo e ignorato dal motore
di accompagnamento (fallback al groove di default).

### 7.3 BPM = 0 o negativo

Esclusi dal range; produce **W136**.

### 7.4 Direttive ridondanti

Una direttiva che riasserisce esattamente i valori correnti (es.
`(=Rock,120bpm)` quando `currentStyle="Rock"` e `currentBPM=120`) è
ammessa, non genera warning. Il player la applica come no-op.

---

## 8. Esempi

### 8.1 Cambio tempo a metà brano

```
HS) swing
HB) 140

…
M) | [Solo] | | | (=200bpm) | | | | |
```

Solo che parte a 140 BPM; dalla misura 4 in poi accelera a 200 BPM.

### 8.2 Cambio style + tempo combinato

```
M) | [Intro] (=Rock,120bpm) | | | [A] | | (=swing,160bpm) | |
```

- Misura 1: marker `[Intro]` + setup Rock 120 BPM.
- Misura 4: marker `[A]` (style e tempo invariati).
- Misura 6: switch a swing 160 BPM.

### 8.3 Metric modulation

```
M) | (=swing,120bpm) | | | (2=4) | | | | (4=2) | | |
```

- Misura 1: swing a 120 BPM.
- Misura 4: half-time (currentBPM = 60).
- Misura 8: double-time rispetto al precedente (currentBPM = 120, torna
  al valore iniziale).

### 8.4 Style multi-parola

```
M) | (=Fast swing,200bpm) |
```

Style "Fast swing" (due parole, spazio interno ammesso), 200 BPM.

### 8.5 Vamp till cue con cambio style

```
M) | [A] | | | | [? Vamp] (=funk,90bpm) | | | (=swing,140bpm) [B] |
```

- Misure 1–4: sezione A (style/tempo dall'header).
- Misure 5–7: vamp in funk a 90 BPM (la sezione collassabile `[? Vamp]`
  è definita in `neumaRk_markers.md` §4).
- Misura 8: ritorno a swing 140 BPM, sezione B.

### 8.6 Solo metric modulation

```
HS) jazz
HB) 120

…
M) | [Theme] | | (4=4.) | | | (4.=4) | |
```

Tema a 120 BPM; dalla misura 3 accelera a 180 BPM (la semiminima
precedente diventa una semiminima puntata nel nuovo tempo, quindi le
nuove semiminime sono più corte); dalla misura 6 si torna a 120 BPM
(`4.=4`: la semiminima puntata precedente diventa la nuova semiminima).

---

## 9. Riassunto

| Concetto              | Sintassi                                  | Sezione |
|-----------------------|-------------------------------------------|---------|
| Direttiva Style/BPM   | `(=[Style][,Tempo])`                      | §2.1    |
| Metric modulation pura| `(figura=figura)` (senza prefisso `=`)    | §2.1    |
| Style                 | testo libero multi-parola                 | §2.2    |
| Tempo BPM             | `Nbpm` (intero 10–999)                    | §2.3.1  |
| Metric modulation     | `figura=figura` (NRK valide)              | §2.3.2  |
| Posizione             | solo riga `M)`, beat 1 misura             | §3      |
| Persistenza           | cross-datapack, fino a nuova direttiva    | §4      |
| Semantica             | executable (player applica)               | §5      |
| Render                | notazione tradizionale (♩ = N, ♩ = ♩.)    | §6      |

Le play directive estendono le indicazioni globali dell'header (`HS)`,
`HB)`) con la possibilità di **cambi locali** durante il brano,
preservando la natura testuale e parsabile del linguaggio.

---

Questo documento definisce la play directive come **meccanismo locale
di controllo style e tempo** in neumaRk, completando il sistema di
indicazioni performative del linguaggio.


---

# Versioni del brano

Questo documento definisce la sintassi e la semantica delle **versioni**
in neumaRk: meccanismo per rappresentare nello stesso file più varianti
dello stesso brano (arrangiamenti alternativi, riarmonizzazioni di
singole sezioni, intere riscritture).

L'utente sceglie quale variante visualizzare/eseguire tramite UI; la
preferenza è persistente in user-index e **non nel file NRK**.

---

## 1. Definizione

Una **versione** è una variante alternativa di una porzione del brano,
delimitata da un **blocco named** della forma:

```
%%NAME
… contenuto …
%%end
```

Esistono due classi di blocchi:

- **Default** — blocco `%%NAME` senza label, fa parte del flusso lineare
  del brano (è la versione "canonica" che il lettore vede di base);
- **Variante** — blocco `%%NAME "label"` con label, vive a lato del
  flusso. Si attiva esplicitamente dall'utente.

Una variante sostituisce **tutte** le occorrenze del blocco default
omonimo durante l'esecuzione/rendering.

### 1.1 Esempio minimale

```
M) [Intro]
… intro originale …

%%BRIDGE
M) [Bridge]
… bridge originale …
%%end

M) [A]
… A finale originale …

%%BRIDGE "Bill Evans version"
M) [Bridge]
… bridge Bill Evans …
%%end
```

L'utente apre il brano e vede la versione canonica. Selezionando "Bill
Evans version" dal selettore UI, il blocco `%%BRIDGE` viene sostituito
dalla variante; il resto del brano (Intro, A) resta invariato.

---

## 2. Sintassi

### 2.1 Apertura del blocco

```
%%NAME                       blocco default
%%NAME "label"               blocco variante
```

- `%%` deve essere **all'inizio della riga** (eventualmente preceduto
  da soli spazi, secondo le regole generali di whitespace di neumaRk).
- `NAME` è un identificatore: una o più lettere/cifre/underscore,
  case-sensitive. Niente spazi interni.
- `"label"` (opzionale, presente solo nelle varianti) è un container
  testuale `"…"` adiacente al NAME, con uno spazio di separazione.
  Ammette il markup unificato (`neumaRk_text_markup.md`).

### 2.2 Chiusura del blocco

```
%%end
```

- Anche `%%end` deve essere all'inizio della riga.
- Chiude il blocco aperto più recente.
- Un `%%end` senza blocco aperto produce warning **W148**.

### 2.3 Contenuto del blocco

Un blocco contiene **uno o più datapack** validi (vedi
`neumaRk_datapack.md`). Tutte le regole musicali (marker, accordi,
note, dinamiche, ecc.) si applicano normalmente dentro il blocco.

### 2.4 Annidamento non ammesso

Un blocco `%%NAME` non può essere aperto dentro un altro blocco. Il
parser produce warning **W149** se incontra `%%X` mentre un blocco è
aperto.

### 2.5 Riservato: `%%`

La sequenza `%%` ad inizio riga è **riservata** per i blocchi versions.
Non è ammessa in altri contesti del linguaggio (i commenti NRK usano
`//`, vedi `neumaRk_datapack.md` per la spec dei commenti single-line).

---

## 3. Posizione strutturale

### 3.1 Standalone fra datapack

I blocchi `%%NAME` vivono **fra datapack** musicali, non al loro
interno. La struttura del documento è una sequenza alternata di:

- datapack normali (flusso comune a tutte le versioni);
- blocchi default `%%NAME` (sezioni named del flusso);
- blocchi variante `%%NAME "label"` (varianti delle sezioni named).

```
[datapack] [datapack] %%BRIDGE [datapack] %%end [datapack]
                     └─ default ─┘
[datapack] %%BRIDGE "Bill Evans" [datapack] %%end
          └─────────── variante ───────────┘
```

### 3.2 Posizione delle varianti

Le varianti `%%NAME "label"` possono apparire in **qualsiasi posizione**
del documento (raccomandato: subito dopo il blocco default omonimo, o
in coda al documento). Il matching è per nome, non per posizione.

---

## 4. Semantica della sostituzione

### 4.1 Regola fondamentale

Quando l'utente attiva la variante `%%NAME "label"`, **tutte** le
occorrenze del blocco default `%%NAME` nel documento vengono
sostituite dal contenuto della variante.

Le porzioni del brano **fuori da blocchi** (datapack normali) restano
invariate in tutte le versioni: appartengono al "tronco comune".

### 4.2 Multi-occorrenze del default

Se un blocco `%%NAME` default appare più volte (es. AABA con tre `%%A`
distinti), una singola variante `%%NAME "label"` **sostituisce tutte
le occorrenze**.

```
%%A
… A original …
%%end

%%B
… B …
%%end

%%A
… A original (seconda occorrenza, può essere musicalmente identica
   o variata) …
%%end

%%A "miles"
… A Miles version …
%%end
```

Attivando "miles": entrambe le `%%A` default sono sostituite dalla
versione Miles. Per varianti per posizione (es. solo la seconda A è
diversa), usare nomi distinti: `%%A1`, `%%A2`.

### 4.3 Marker M) ortogonali

I marker della riga `M)` interni a un blocco `%%NAME` sono
**indipendenti** dal nome del blocco. Il parser non richiede che
`M) [Bridge]` appaia dentro `%%BRIDGE`: convention dell'autore
nominarli uguale, ma non è vincolato.

```
%%PEDAL
M) [A pedal]
… …
%%end
```

`PEDAL` è il nome del blocco (per il selettore versioni); `A pedal` è
il marker della sezione (per PLAY/FORM, render, navigazione).

### 4.4 Riscritture totali

Per arrangiamenti completi (es. "Round Midnight, arrangiamento Miles"),
l'autore può racchiudere l'intero brano in un blocco `%%NAME` default
(con nome a scelta: `%%SONG`, `%%MAIN`, ecc.) e fornire la riscrittura
come variante.

```
%%SONG
M) [Intro]
… brano completo originale …
M) [Outro]
…
%%end

%%SONG "Miles Davis arrangement"
M) [Intro Miles]
… arrangiamento completo Miles …
M) [Coda]
…
%%end
```

Non esiste una keyword riservata per "tutto il brano": qualsiasi nome
funziona, l'autore sceglie quello che preferisce.

---

## 5. Header opzionale `HV)`

L'header del documento (`neumaRk_header.md`) ammette una nuova voce
opzionale **`HV)`** per dichiarare esplicitamente le versioni
disponibili e quella di default:

```
HV) versions: [original, miles, jarrett] default=original
```

### 5.1 Sintassi

```
HV) versions: [<label1>, <label2>, …] [default=<label>]
```

- `versions:` parola chiave obbligatoria.
- Lista di label fra parentesi quadre, separate da virgole.
- `default=<label>` opzionale: specifica quale variante mostrare alla
  prima apertura (in assenza di preferenza utente). In assenza di
  `default=`, il default è il **flusso default** (blocchi `%%NAME`
  senza label).

### 5.2 Funzioni dell'`HV)`

- **Documentazione**: rende esplicite le versioni del brano nell'header.
- **Ordinamento UI**: le label sono presentate nel selettore UI
  nell'ordine dichiarato.
- **Label nominata del default**: senza `HV)`, il default è "unnamed";
  con `HV)` può ricevere un nome (es. `original`) e apparire nel
  selettore insieme alle varianti.

### 5.3 `HV)` opzionale

In assenza di `HV)`, le varianti sono dedotte dai blocchi
`%%NAME "label"` presenti nel documento. L'ordine è quello di
apparizione nel file. Il default è il flusso non-etichettato.

### 5.4 Discrepanze

Una label dichiarata in `HV)` ma assente nel documento (o viceversa)
**non è un errore**: il selettore UI mostra solo le varianti
effettivamente presenti. È responsabilità dell'autore mantenere
coerenza.

---

## 6. Preferenza utente

Lo stato "versione corrente" è una **preference utente** salvata in
user-index Firestore (es.
`users/{uid}/song_view_state/{songId}.version`).

- Alla prima apertura, il documento mostra il **default** (flusso senza
  blocchi `%%NAME` etichettati, oppure quanto dichiarato in `HV)
  default=`).
- L'utente cambia versione tramite selettore UI (badge con tendina).
- La scelta è persistente per quel brano specifico per quell'utente.

Lo stato della versione **non viene mai scritto nel file NRK**: il file
è immutabile rispetto alla preferenza di lettura.

---

## 7. Diagnostica

### 7.1 Codici diagnostici

| Codice | Descrizione                                                                 |
|--------|-----------------------------------------------------------------------------|
| W147   | Blocco `%%NAME` non chiuso (manca `%%end` entro fine documento)             |
| W148   | `%%end` orfano (nessun blocco aperto)                                       |
| W149   | Blocco `%%NAME` annidato dentro un altro blocco                             |
| W150   | `HV)` malformato (atteso `versions: [list] [default=label]`)                |

### 7.2 Non-errori

- Variante senza default omonimo (`%%X "label"` ma nessun `%%X`
  default): la variante è ignorata in esecuzione, ma resta nel file.
  Render UI può segnalarla come "orfana".
- Default senza varianti (`%%X` solo): consentito; il blocco è una
  semplice sezione "preparata per future varianti".
- Label `%%X "label"` ripetuta più volte: l'ultima vince (silently),
  oppure render mostra warning UI.

---

## 8. Esempi

### 8.1 Days of Wine and Roses con Bill Evans bridge

```
HT) Days of Wine and Roses
HC) Henry Mancini
HK) F
HM) 4/4
HV) versions: [original, bill_evans] default=original

M) [Intro]
… intro …

M) [A]
… A original …

%%BRIDGE
M) [Bridge]
… bridge original …
%%end

M) [A]
… A finale original …

%%BRIDGE "bill_evans"
M) [Bridge]
… bridge ri-armonizzato Bill Evans …
%%end
```

### 8.2 Round Midnight, riscrittura totale Miles

```
HT) Round Midnight
HC) Thelonious Monk
HV) versions: [original, miles] default=original

%%SONG
M) [Intro]
… intro standard …
M) [A]
… A originale …
M) [B]
… B originale …
M) [A]
… A finale …
%%end

%%SONG "miles"
M) [Intro Miles]
… intro Miles …
M) [A]
… A con accordi cambiati …
M) [B]
… B con frase aggiunta …
M) [Coda]
… coda Miles …
%%end
```

L'utente sceglie "miles" dal selettore → il blocco `%%SONG` originale è
sostituito dalla riscrittura.

### 8.3 AABA con A "miles" che sostituisce tutte le A

```
%%A
… A originale …
%%end

%%A
… (seconda occorrenza, identica o variata) …
%%end

%%B
… B …
%%end

%%A
… A finale …
%%end

%%A "miles"
… Miles version dell'A …
%%end
```

Attivando "miles": le tre `%%A` default sono sostituite dalla variante.
Il `%%B` resta invariato.

### 8.4 Variante per posizione (nomi distinti)

```
%%A1
… prima A …
%%end

%%B
… B …
%%end

%%A2
… seconda A (lievemente diversa) …
%%end

%%A2 "minor key"
… A2 in minor mode …
%%end
```

Solo la seconda A è sostituibile dalla variante "minor key". La prima
A non è coinvolta perché ha nome diverso (`%%A1`).

---

## 9. Riassunto

| Concetto              | Sintassi                                          | Sezione |
|-----------------------|---------------------------------------------------|---------|
| Blocco default        | `%%NAME … %%end`                                  | §2.1    |
| Blocco variante       | `%%NAME "label" … %%end`                          | §2.1    |
| Chiusura blocco       | `%%end`                                           | §2.2    |
| Posizione blocchi     | standalone fra datapack, no annidamento           | §3.1    |
| Sostituzione          | variante sostituisce tutte le `%%NAME` default    | §4.1    |
| Marker M)             | ortogonali al nome del blocco                     | §4.3    |
| Riscrittura totale    | racchiudere il brano in un blocco unico (es. `%%SONG`) | §4.4 |
| Header               | `HV) versions: [list] default=label` (opzionale)  | §5      |
| Preference utente     | user-index Firestore, non NRK                     | §6      |

---

Questo documento definisce le **versioni del brano** in neumaRk:
meccanismo robusto e granulare per rappresentare arrangiamenti
alternativi, ri-armonizzazioni puntuali e riscritture complete dello
stesso brano dentro un singolo file.


---

# Collezioni (book / playlist)

Questo documento definisce il formato testuale con cui un **insieme
ordinato di brani** — un *book* o una *playlist* — è rappresentato in un
unico file neumaRk.

Una collezione **non introduce un nuovo linguaggio**: è un sottile
strato contenitore attorno a una sequenza di brani, ciascuno dei quali
è un documento neumaRk standalone già definito dal resto della
specifica. Lo stesso parser legge brani singoli e collezioni; la
distinzione avviene sulla **prima riga del file**.

---

## 1. Scopo e ruolo

Il formato collezione serve a **esportare, condividere e re-importare**
un book o una playlist come singolo file `.nrk`, autonomo e leggibile.

Il principio guida è la **portabilità**: il file è una *foto
autosufficiente* della collezione. Tutti i brani sono incorporati come
**snapshot** (copie congelate), così che il file possa essere aperto e
importato da chiunque, anche senza accesso ai brani originali e anche se
gli originali cambiano o spariscono.

Tutto ciò che è **specifico del prodotto** (e non del linguaggio
musicale) — copertina, tag curati, condivisione, ruoli, identificatori
di database — **non fa parte del file** (vedi §7).

---

## 2. Collezione e brano singolo

Un file neumaRk può rappresentare:

- un **brano singolo**, la cui prima riga è la dichiarazione di versione
  `nrk:<major>.<minor>` (vedi `neumaRk_header.md` §2);
- una **collezione**, la cui prima riga è `nrk-book:<v>` oppure
  `nrk-playlist:<v>` (§3).

La distinzione è data **dal solo contenuto della prima riga**, mai
dall'estensione del file: un `.nrk` può contenere l'uno o l'altra.

Un file che inizia con `nrk:` è un brano singolo come sempre: il formato
collezione è **retro-compatibile** e non altera la lettura dei file
esistenti.

> Il termine **collezione** è un'ombrello concettuale usato in questa
> specifica e nel tooling; **non compare mai come token** nel file. Il
> tipo (book o playlist) è scritto direttamente nel marcatore di riga 1.

---

## 3. Riga di apertura e tipo

La prima riga di una collezione è una dichiarazione di versione che
**incorpora il tipo**:

```
nrk-book:0.6
```

oppure

```
nrk-playlist:0.6
```

Caratteristiche:

- è **obbligatoria** e deve essere la **prima riga del file**;
- il tipo (`book` / `playlist`) è parte del marcatore: leggendo la prima
  riga si conosce subito *sia* che il file è una collezione *sia* di
  quale tipo;
- la versione segue la stessa numerazione `nrk:` del linguaggio.

Differenza funzionale fra i due tipi:

- un **book** è una raccolta curata di brani, **senza** override
  per-brano;
- una **playlist** è una sequenza eseguibile in cui ogni brano può
  portare un **override per-occorrenza** (§6).

---

## 4. Header di collezione

Dopo la riga di apertura, ed eventuali righe vuote, può comparire un
**header di collezione**: un blocco di **direttive** nella forma
`chiave: valore`.

```
nrk-playlist:0.6
name: My Setlist
desc: live al Blue Note
```

| Direttiva | Significato | Obbligatoria |
|---|---|---|
| `name:` | nome della collezione | no (consigliata) |
| `desc:` | descrizione libera | no |

Le direttive di header:

- usano `:` come separatore (stessa famiglia sintattica di `nrk:`);
- precedono qualunque blocco-brano;
- sono **parte di neumaRk** (come il titolo `HT)` lo è per il brano):
  identità testuale della collezione.

Una direttiva di header che compaia **dopo** il primo blocco-brano è
fuori posizione (**W155**).

---

## 5. Blocchi-brano

Il corpo della collezione è una **sequenza di blocchi-brano**. Ogni
blocco:

- è un **documento neumaRk standalone**, che inizia con la propria riga
  `nrk:<v>` e prosegue con header e datapack come di consueto;
- è una **snapshot** autosufficiente (il contenuto musicale è
  incorporato, non riferito);
- è copia-incollabile come file `.nrk` valido a sé.

L'**ordine dei brani è l'ordine dei blocchi nel file**: non esiste una
chiave d'ordinamento numerica.

```
nrk-playlist:0.6
name: My Setlist

nrk:0.6
First Tune (Author)
F 120bpm
F| Bb| C7| F|

nrk:0.6
Second Tune (Author)
Bb 90bpm
Bb| Eb| F7| Bb|
```

Una collezione **priva di blocchi-brano** è degenere (**W156**).

---

## 6. Override per-item (solo playlist)

In una playlist, ciascun brano può essere preceduto da una riga
`item:` che ne dichiara gli **override per quell'occorrenza nella
scaletta**. Gli override **non sono proprietà del brano** (lo stesso
brano in due playlist può averne di diversi): sono uno strato della
*voce di scaletta*.

```
item: transpose=+2 notes="capo 3" form=[Intro] [A|8]x2 [B|8] [A|8]
nrk:0.6
My Tune (Author)
…
```

Regole:

- la riga `item:` **si applica al blocco-brano che la segue**
  immediatamente (il prossimo `nrk:`);
- compare **solo se c'è almeno un override**; la sua assenza significa
  "nessun overlay";
- è ammessa **solo nelle playlist**. Una riga `item:` in un `nrk-book:`
  è fuori contesto (**W152**).

### 6.1 Sintassi dei parametri

I parametri sono coppie `chiave=valore` separate da spazi. Il segno `=`
distingue il **parametro inline** dalla direttiva di header (`:`), così
nessun simbolo ha doppio ruolo.

Un `valore`:

- è un **token semplice** (senza spazi), es. `transpose=+2`; oppure
- è **quotato** `"…"` quando contiene spazi (testo letterale,
  quote-aware come nel resto di neumaRk), es. `notes="capo 3"`.

Chiavi ammesse: `transpose`, `notes`, `form`. Una chiave sconosciuta è
ignorata con diagnostica **W153**.

| Chiave | Tipo | Significato |
|---|---|---|
| `transpose` | intero con segno | trasposizione di esecuzione (overlay, ±semitoni) |
| `notes` | testo | annotazione personale per questa voce |
| `form` | grammatica FORM | forma di esecuzione per questa occorrenza (§8) |

### 6.2 `form=` consuma il resto della riga

Poiché la grammatica FORM usa essa stessa i container `"…"` per le
label (vedi §8), il parametro `form=` **non è quotato**: consuma
**tutto ciò che segue fino a fine riga**, verbatim. Per questo `form=`,
se presente, è **l'ultimo parametro** della riga `item:`.

```
item: transpose=-1 form="Tema"[A|8]ff [B|4]x2 "Coda"[A|8]&fermata
```

Le virgolette qui sono **interne alla grammatica FORM** (label), non
delimitatori del parametro. (Una forma su più righe è fuori scope in
questa versione.)

Un `transpose` nullo (`+0`, no-op) e un `notes` vuoto non sono errori.

---

## 7. Modalità portabilità: dentro e fuori dal file

La collezione porta **solo musica e struttura minima**. Tutto ciò che è
prodotto applicativo viene **ricostruito all'import** dai default, come
quando si crea una collezione nuova.

**Nel file (è neumaRk):**

- il tipo (`nrk-book:` / `nrk-playlist:`);
- `name:` / `desc:`;
- l'ordine dei brani (= ordine dei blocchi);
- per le playlist: gli override `transpose` / `notes` / `form` su
  `item:`;
- ogni brano per intero, come **snapshot**.

**Fuori dal file (non è neumaRk):**

- copertina, tag curati, conteggio iscritti;
- condivisione, ruoli, permessi;
- identificatori di database dei brani;
- la distinzione *dynamic vs snapshot* delle voci playlist (in export
  ogni voce è **risolta a snapshot**).

### 7.1 Il file è intenzionalmente anonimo

Per coerenza con il principio sopra, un file di collezione **non porta
alcuna identità d'origine**: né identificatori di database, né chiavi di
deduplicazione, né tag dell'host. È, di proposito, *anonimo*.

Conseguenza: l'**identità** di un brano (decidere se due brani sono "lo
stesso") **non è una proprietà del file** — è una questione dell'host,
e va derivata semmai dalla **musica** (vedi §7.2), mai da un'etichetta
opaca incollata al file. Questa è una scelta deliberata: il formato non
trasporta dati che esso stesso non comprende.

### 7.2 Semantica di import (comportamento dell'host)

*Come* un host re-importa una collezione **non è definito da neumaRk** —
è comportamento applicativo. In leadsheet.app, dato che il file è
anonimo (§7.1):

- l'import di un **book** crea **copie** dei brani nella libreria
  dell'utente; l'import non è idempotente — reimportare lo stesso book
  ricrea le copie;
- la **deduplica** ("ho già questo brano?") è **rimandata** e, quando
  arriverà, sarà basata sull'**impronta melodica** (proprietà della
  musica, condivisa con la ricerca) come *advisory* — non su una chiave
  esatta incollata al file. Una identità esatta e durevole, con un
  formato volutamente puro, non è ottenibile dal file; perciò la dedup
  nasce dalla musica, ed è per natura un suggerimento, non un automatismo.

### 7.3 Assorbimento dell'header all'import — modulo header-probe (lossless)

All'import, ogni brano viene **separato** in header (→ `prop`) e datapack
(→ `cont` pulito), così il brano importato è **coerente con quelli salvati
da WRITE** (header nelle property, corpo nel `cont`) e il round-trip
export→import è **lossless**.

La separazione usa il **vero parser** (`parseText`, text→`Music`) esposto da
un **modulo WASM dedicato** (`createModuleHeader`, sorgente
`wasm/src/neumark/header_probe.cpp` → `parseHeaderOnly`), servito sotto
`assets/wasm/header/` e **caricato lazy solo all'import**. Il bundle WASM
dell'app *library* resta volutamente snello (non include il parser nel boot
normale); il costo del parser si paga una sola volta, alla prima importazione.

In *view*, che il parser lo bundla già, `parseHeaderOnly` è esposto sullo
**stesso modulo** (`createModuleView`) e usato dal salvataggio persistito
(`collection-view.service`), senza caricare un modulo separato.

Da `parseHeaderOnly` si ricavano:

- `prop`: header completo nello shape DB (`tit`, `crd{mus,lyr,arr,trs}`,
  `key`, `bpm`, `mtr`, `sty`, `sub`, `yr`, `alt[]`, `lng[]`) — valori dal
  `Music` parsato, presenza dai range di `map.header`;
- `cont`: il datapack puro (righe dopo l'header, blank iniziali/finali rimossi).

**Fallback:** se il modulo non si carica, l'import ripiega sullo **scan
leggero** (`parse_block_header` in `collections.cpp`, sottoinsieme dei campi)
con l'header lasciato dentro `cont`, che WRITE normalizza al primo
ri-salvataggio. Lo scan leggero resta quindi come rete di sicurezza, non più
come comportamento primario.

**Limite noto:** la separazione richiede la riga vuota fra header e datapack
(che `generate_nrk` emette sempre in export); su file scritti a mano **senza**
quel separatore `parseText` non distingue header e corpo — stesso comportamento
dell'import in WRITE.

---

## 8. FORM a livello di collezione

Il parametro `form` di una voce playlist (§6) usa la **grammatica
`FORM)`** definita in `neumaRk_play_and_form.md` (box di sezione,
durate informative `|N`, label, dinamiche, keyword, prosa libera).

### 8.1 Semantica: sostituzione

Se una voce playlist porta un `form`, esso **sostituisce** la sezione
`FORM)` eventualmente contenuta nello snapshot del brano, **per quella
occorrenza**.

Serve a dichiarare: *"la forma con cui suoniamo questo brano stasera è
questa, a prescindere dalla forma originale del brano."*

- override presente → l'item-`form` **vince** sulla `FORM)` del brano;
- override assente → resta la `FORM)` del brano (se presente).

È una sostituzione, **non** una fusione.

### 8.2 Perché FORM e non PLAY

`FORM)` è **posizione-indipendente** (una sola, descrittiva, in fondo
al documento; il player la ignora): si presta a essere dichiarata a
livello di scaletta, dove esiste solo il *riferimento* a un brano.

`PLAY)` invece è **posizionale/inline**: il suo effetto dipende da
*dove* è collocata fra i datapack (vedi `neumaRk_play_and_form.md`
§2.1). A livello di scaletta non esiste una posizione interna al brano
in cui iniettarla, quindi `PLAY)` **non è esprimibile** come override di
voce. L'override di forma è perciò sempre **descrittivo** (FORM), mai
eseguito: non altera il playback, ma *ciò che i musicisti leggono come
forma*.

### 8.3 Risoluzione dei riferimenti

I box `[NAME]` dell'item-`form` si risolvono sui **marker `M)` del
brano della voce** (lo snapshot che segue), con lo stesso modello di
`neumaRk_play_and_form.md` §3.1. Un box che non corrisponde a nessun
marker è **reference broken**: renderizzato come testo non eseguito,
**senza errore o warning** (`neumaRk_play_and_form.md` §7.3). Questo
consente forme di scaletta informali.

Le diagnostiche di box (`W141` durata, `W142` repeat, `W143` keyword)
restano applicabili; quelle di posizionamento del documento (`W140` più
`FORM)`, `W145` `FORM)` non in fondo) **non** si applicano all'item-`form`.

---

## 9. Regole di parsing

### 9.1 Split prima del parsing musicale

Il file di collezione viene **suddiviso in blocchi alle righe `nrk:`
prima** di qualunque analisi musicale. Il parser di brano riceve
**solo** il testo da una riga `nrk:` alla successiva.

Conseguenza: i token di collezione (`nrk-book:` / `nrk-playlist:`,
`name:` / `desc:`, `item:`) vivono **nei segmenti esterni ai blocchi** e
**non possono collidere** con il contenuto musicale.

### 9.2 Riconoscimento

- prima riga `nrk-book:` → collezione book;
- prima riga `nrk-playlist:` → collezione playlist;
- prima riga `nrk:` → brano singolo.

L'entry-point del parser, che per i brani impone "`nrk:` deve essere la
prima riga", accetta `nrk-book:` / `nrk-playlist:` come **token di
riga 1 alternativi**. Sono prefissi letterali distinti: il
riconoscimento è additivo e non ambiguo.

### 9.3 Righe vuote e versioni

- Le righe vuote separano l'header di collezione dai blocchi e i blocchi
  tra loro, coerentemente con la delimitazione dei datapack
  (`neumaRk_datapack.md` §1).
- Il blocco `%%NAME … %%end` (versioni del brano,
  `neumaRk_versions.md`) resta **interno al singolo blocco-brano**: è
  testo che il parser di brano vede, non un token di collezione. Lo
  strato collezione **non usa `%%`**.

---

## 10. Diagnostica

| Codice | Descrizione |
|---|---|
| W152 | Riga `item:` in una collezione `nrk-book:` (i book non hanno override per-item) |
| W153 | Chiave override sconosciuta in `item:` (ammessi `transpose` / `notes` / `form`) |
| W154 | Riga `item:` non seguita da un blocco-brano (`nrk:`) |
| W155 | Direttiva di header collezione (`name:` / `desc:`) dopo il primo blocco-brano |
| W156 | Collezione priva di blocchi-brano |

### 10.1 Non-errori

- un blocco snapshot la cui `FORM)` è sostituita dall'item-`form` (§8.1);
- un box `[NAME]` dell'item-`form` senza marker omonimo (reference
  broken, §8.3);
- `transpose=+0` (no-op) e `notes` vuoto;
- righe vuote supplementari nell'header o fra i blocchi.

---

## 11. Esempi

### 11.1 Playlist con override

```
nrk-playlist:0.6
name: Friday Gig
desc: trio set

item: transpose=+2
nrk:0.6
Blue Bossa (Kenny Dorham)
Cm 140bpm
Cm| Fm| Dm7b5| G7| Cm|

item: form=[Intro|4] [A|16]x2 [Solos] [A|16] [Outro]&fermata
nrk:0.6
So What (Miles Davis)
M) [A] [Solos] [Outro]
…datapack…
```

La prima voce suona Blue Bossa trasposto +2; la seconda dichiara una
forma di esecuzione che sostituisce quella del brano.

### 11.2 Book (nessun override)

```
nrk-book:0.6
name: My Real Book — Vol. 1

nrk:0.6
Autumn Leaves (J. Kosma)
…

nrk:0.6
All The Things You Are (J. Kern)
…
```

### 11.3 Collezione a un solo brano

```
nrk-playlist:0.6
name: Solo Spot

nrk:0.6
Naima (J. Coltrane)
…
```

Degrada in modo trasparente: una collezione con un solo blocco è
valida.

---

## 12. Riassunto

| Concetto | Sintassi | Sezione |
|---|---|---|
| Apertura book | `nrk-book:<v>` | §3 |
| Apertura playlist | `nrk-playlist:<v>` | §3 |
| Header collezione | `name:` / `desc:` | §4 |
| Blocco-brano | `nrk:<v>` … (snapshot) | §5 |
| Ordine | ordine dei blocchi nel file | §5 |
| Override voce | `item: chiave=valore …` (solo playlist) | §6 |
| Parametri voce | `transpose` / `notes` / `form` | §6.1 |
| Forma di voce | `form=` (grammatica FORM, rest-of-line) | §6.2, §8 |
| Sostituzione forma | item-`form` sostituisce la `FORM)` del brano | §8.1 |
| Split | alle righe `nrk:`, prima del parsing musicale | §9.1 |
| Portabilità | tutto snapshot; copertina/tag/ruoli fuori | §7 |

---

Questo documento definisce le **collezioni** (book e playlist) come
strato contenitore portabile di neumaRk, costruito per riuso attorno ai
documenti-brano e alla forma del brano (`neumaRk_play_and_form.md`).


---

# Formati
## 1. Scopo

Questo documento definisce i **formati di presentazione** del linguaggio neumaRk.
I formati non modificano il significato musicale o temporale dei dati, ma solo il modo in cui il contenuto è organizzato, spaziato e reso leggibile.

---

## 2. Principio generale

- Il **contenuto musicale è identico** in tutti i formati
- I formati influenzano solo:
  - disposizione delle righe
  - allineamento
  - uso degli spazi
  - compattezza del testo

Un parser deve poter leggere **tutti i formati** producendo la stessa struttura interna.

---

## 3. Formati supportati

### 3.1 Compact

Formato minimalista, pensato per:

- trasmissione
- storage
- URL/embedding

Caratteristiche:

- numero di righe vuote ridotto al minimo
- spazi ridotti al minimo
- scrittura stenografica (implicita) dove possibile, nei limiti dell sicurezza deterministica

Esempio:

```
nrk:0.6
My Tune (John Dowe)
Waltz Ballad 3/4 Bb 135bpm

Bb6| |Cm7|F7|Bb6|
d|c bb c|d4 8 d eb d|c|bb|^.|
```

---

### 3.2 Human

Formato leggibile, pensato per:

- editing manuale
- revisione
- collaborazione

Caratteristiche:

- spaziatura esplicita
- righe separate logicamente
- commenti ammessi

Esempio:

```
nrk:0.6

                My Tune (John Dowe)
              3/4 Waltz Ballad 135bpm
Bb

| Bb6 |         | Cm7          | F7  | Bb6   |      .|
| d2. | c4 bb c | d4 d8 d eb d | c2. | bb2.^ | bb2. .|
```

---

### 3.3 Verbose

Formato esplicito e ridondante, pensato per:

- debug
- ispezione
- tooling

Caratteristiche:

- ogni riga è etichettata
- nessuna deduzione implicita
- massimo dettaglio

Esempio:

```
nrk:0.6

HT)                       My Tune
HCM) John Dowe
HCA) gino bart
HM) 3/4
HS) Waltz Ballad
HB) 135
HK) Bb

C) | Bb6 |           | Cm7             | F7  | Bb6   |      .|
N) | d2. | c4 bb4 c4 | d4 d8 d8 eb8 d8 | c2. | bb2.^ | bb2. .|
```

### 3.4 Tipologi miste

Queste modalità non sono nettamente separate, è possibile avere gradi intermedi di verbosità, compattezza, notazione implicita/esplicita, leggibilità per l'umano.

### 3.5 Equivalenza semantica dei formati

I formati **Compact**, **Human** e **Verbose** sono semanticamente
equivalenti.

Ogni documento neumaRk valido può essere espresso in uno qualunque di
questi formati senza perdita di informazione musicale o strutturale.

Le differenze tra i formati riguardano esclusivamente:

- il grado di esplicitazione;
- la leggibilità per l’essere umano;
- la compattezza testuale.

La normalizzazione tra i formati non altera la semantica del brano
rappresentato.

---

## 4. Allineamento

### 4.1 Allineamento temporale

- l'allineamento tra righe musicali è basato sulle **barline**
- i separatori `|` definiscono i punti di sincronizzazione

### 4.2 Allineamento visivo

Il whitespace ha **due ruoli distinti**:

- **Whitespace di allineamento/padding** — *non* significativo: la lunghezza di un
  run di spazi/tab, e gli spazi aggiunti per incolonnare verticalmente le righe o
  per leading/trailing, servono solo alla leggibilità e possono essere
  normalizzati liberamente.
- **Spazi significativi** — *non* normalizzabili, perché portano significato:
  - **separatori di token/evento**: uno spazio separa due eventi (`c d` = due
    note; `c4 d` ≠ `c4d`), e su righe `A)`/`D)` separa i token allineati per
    conteggio;
  - **contenuto letterale dentro span delimitati**: gli spazi dentro un
    chord-stack `<c e g>` separano le pitch; dentro un'annotation `"…"` (e `[…]`)
    sono **testo letterale**.

Un formatter può comprimere/espandere solo il whitespace del primo tipo; rimuovere
uno spazio del secondo tipo **altera la semantica** (vedi §6).

---

## 5. Righe vuote

Le righe vuote servono per delineare i vari datapack.
Righe vuote supplementari:

- sono consentite in Human e Verbose
- ignorate semanticamente
- non consentite in Compact

---

## 6. Normalizzazione

Un formatter può:

- convertire qualsiasi formato in un altro
- rimuovere spazi superflui
- espandere o comprimere il datapack

La normalizzazione **non deve** modificare:

- ritmo
- flusso
- semantica musicale
- riconoscimento deterministico in caso di notazione stenografica (implicita)

---

## 7. Compatibilità

Un documento neumaRk è valido se:

- rispetta la sintassi di base
- utilizza uno dei formati supportati

Il formato può essere dedotto automaticamente o dichiarato esplicitamente tramite header.

---

## 8. Collezioni

Un file `.nrk` può rappresentare un **brano singolo** (prima riga
`nrk:<v>`) oppure una **collezione** — un book o una playlist — che
incapsula una sequenza ordinata di brani. In quel caso la prima riga è
`nrk-book:<v>` o `nrk-playlist:<v>`. I formati Compact / Human / Verbose
di questo documento si applicano a ogni singolo blocco-brano della
collezione. Vedi `neumaRk_collections.md`.


---

# Changelog ufficiale

---

## neumaRk 0.6.0 — Versione corrente (in sviluppo)

Versione di riferimento dichiarata dagli esempi della specifica
(`nrk:0.6`). Estende la 0.5.0 con un'ampia ondata di feature, elencate
qui sotto.

### Novità della 0.6

La 0.6 estende la 0.5.0 con le feature seguenti; ognuna è specificata nel
documento indicato.

| Feature | Documento |
|---|---|
| Grace notes | `neumaRk_grace_notes.md` |
| Seconda voce `N2` | `neumaRk_voices.md` |
| Continuità stave `N+` / multi-stave | `neumaRk_datapack.md` §4 |
| Ripetizione di misura `%` | `neumaRk_flow_and_repeats.md` §7 |
| Polyaccordi `[top\|bottom]` | `neumaRk_chords.md` §6 |
| Comment-label / accordi alternativi `C+` | `neumaRk_chords.md` §7 |
| Persistenza armonia (cella vuota + `.` di continuazione iniziale) + assenza accordo `NC` | `neumaRk_chords.md` §1.1-1.2 |
| Markup testuale unificato | `neumaRk_text_markup.md` |
| Sezioni collassabili `[? …]` / `[!]` | `neumaRk_markers.md` §4 |
| Dinamiche `D)` estese | `neumaRk_dynamics.md` |
| Play directive `(=Style,Tempo)` | `neumaRk_play_directive.md` |
| `PLAY)` / `FORM)` | `neumaRk_play_and_form.md` |
| Versioni `%%NAME … %%end` | `neumaRk_versions.md` |
| Articolazioni `A)` (base + estensioni §8-12) | `neumaRk_articulations.md` |
| Lyrics `L)` + blocco `LYRICS)` | `neumaRk_lyrics.md` |
| Note estese `N)` (noteheads, glissato, ritmo `{}`) | `neumaRk_notes_and_durations.md` §11-12 |
| Pausa multi-misura `RN` | `neumaRk_notes_and_durations.md` §13 |
| Spacer `s` (pausa invisibile) | `neumaRk_notes_and_durations.md` §14 |
| Anacrusi di sezione (`>>>` misura aperta + `>` levare mid-brano) | `neumaRk_notes_and_durations.md` §7.1 |
| Collezioni (book / playlist) | `neumaRk_collections.md` |

### Cambiamenti normativi rilevanti nella 0.6

Oltre alle nuove feature, la 0.6 introduce alcuni cambiamenti che modificano
sintassi o codici rispetto alle bozze precedenti:

- **Codici del blocco `LYRICS)` rinumerati in `W157`/`W158`.** In una prima
  bozza il blocco `LYRICS)` condivideva `W152`/`W153` con le Collezioni; ora
  ogni codice ha un solo significato (Collezioni: `W152`–`W156`; blocco
  `LYRICS)`: `W157` = sezione inesistente, `W158` = pickup in overflow).
- **Chiusura di sezione opzionale: `[!]` sostituisce `[?]`**
  (`neumaRk_markers.md` §4.2). `[!]` è un marker anonimo di apertura di sezione
  non-opzionale e chiude lo scope opzionale precedente come effetto della regola
  generale §4.1.
- **Ripetizione di misura `%` con span N>1**: il token compare in *ognuna* delle
  N misure consecutive del run (es. `| a | b | %2 | %2 |`), preservando
  l'invariante "una cell = una misura" (`neumaRk_flow_and_repeats.md` §7).
- **La cella d'accordo vuota ora fa *persistere* l'armonia** (prima:
  silenzio). Una misura `C)` priva di sigle/`%`/`NC` ri-realizza l'accordo
  precedente sul battere (`neumaRk_chords.md` §1.1). Per dichiarare
  esplicitamente l'assenza di armonia si usa il nuovo token **`NC`** (§1.2,
  glifo `N.C.`, errore `E128` se misto a un accordo). Cambia di conseguenza
  il trigger della slash notation implicita: ora include l'armonia
  persistente ed esclude `NC` (`neumaRk_notes_and_durations.md` §10).

### Convenzione dei codici diagnostici

- **`E###`** — *error*: costrutto non valido, emesso come errore
  bloccante (`LOG_ERROR`).
- **`W###`** — *warning*: diagnostica non bloccante, best-effort
  (`LOG_WARNING`); il parsing prosegue.

Il prefisso indica la **severità**, non la categoria. L'intera famiglia
diagnostica 0.6+ (`W130`–`W158`: dinamiche, articolazioni, play directive,
`PLAY)` / `FORM)`, sezioni collassabili, versioni, `HV)`, collezioni, blocco
`LYRICS)`) è emessa come **warning** ed è stata rinominata da
`E13x`/`E14x`/`E15x` a `W13x`/`W14x`/`W15x` per allineare il prefisso alla
severità reale.

Le due tabelle che seguono — **codici di base** (pre-0.6 e fondamentali) e
**codici 0.6+** — insieme costituiscono la mappa **completa e autorevole**
codice → significato, allineata al parser. Ogni codice ha un solo significato.
I codici interni `E901`–`E905` sono dev-facing (EN-only) e non normativi.

#### Allocazione codici di base (pre-0.6 e fondamentali)

| Codice | Significato | Famiglia (doc) |
|---|---|---|
| E001 | Token non interpretabile: nota / evento grace / chord-stack `<…>` / rhythm group `{…}` malformato o non chiuso | Note e durate / Grace |
| E002 | Una durata non può seguire `.` o `!` | Note e durate |
| E003 | Tuplet non valido | Note e durate |
| E004 | Impossibile interpretare la pitch | Note e durate |
| E005 | Le durate delle note superano il metro della misura | Note e durate |
| E006 | Più di uno slash-rhythm `/` per misura | Note e durate |
| E007 | Slash `/` senza spazio (meno di un beat dopo l'allineamento) | Note e durate |
| E008 | Ottava assoluta `@<n>_` richiede durata esplicita | Note e durate |
| E009 | Durata grace mancante sul primo evento, o non conforme (solo `4`/`8`/`16`) | Grace notes |
| E010 | Modificatore `/` o `^` ammesso solo sull'ultimo evento grace | Grace notes |
| E011 | Blocco grace vuoto `[]` | Grace notes |
| E012 | Blocco grace con più di 4 eventi | Grace notes |
| E013 | Pausa non ammessa come evento grace | Grace notes |
| E101 | Lista ritmica compatta / polychord / espressione accordo non interpretabile | Accordi |
| E102 | Token non riconosciuto nella riga accordi | Accordi |
| E110 | Troppi stave nel datapack (max 4) | Datapack / multi-stave |
| E122 | `N)` senza match: più continuazioni che stave nel datapack precedente (usa `N+`) | Datapack (`N+`) |
| E123 | `N2` senza rigo parent valido | Voci |
| E124 | `N2` duplicata sullo stesso rigo | Voci |
| E125 | Direttiva di chiave non ammessa in riga `N2` | Voci |
| E126 | Più di un comment-label sullo stesso chord / group / row | Accordi (alternate) |
| E127 | Max 2 righe alternative `C+` per datapack | Accordi (alternate) |
| E128 | `NC` misto ad altro contenuto nella stessa misura | Accordi |
| E300 | Measure-repeat (`%` / `RN`) senza sorgente valida | Flusso / MMR |
| E301 | Impossibile interpretare la nota dell'armatura di chiave | Header / chiave |
| W002 | Tuplet non chiuso prima della fine misura (auto-riempito con pause 1/64) | Note e durate |
| W003 | Blocco grace non adiacente alla main (ignorato) | Grace notes |
| W004 | Blocco grace privo di main adiacente (ignorato) | Grace notes |
| W006 | Pitch fuori dal range MIDI [1..127] | Note e durate |
| W007 | Token di notazione ritmica `{…}` non valido (durata o tuplet) | Note e durate |
| W008 | Pausa multi-misura `RN` su span con contenuto: degrado a pausa normale | Note e durate (MMR) |
| W009 | Modificatore non ammesso su spacer `s` (ignorato) | Note e durate (spacer) |
| W103 | Suffisso accordo non riconosciuto | Accordi |
| W301 | Impossibile dedurre titolo o credits dalla prima riga di header | Header |
| W400 | Nota del ritmo accordi con durata non positiva (omessa) | Accordi (ritmo) |

#### Allocazione codici 0.6+ (fonte unica)

Le righe `A)`/`D)`/`L)` condividono **W131** (eccesso token) per identità
semantica, non per collisione.

| Codice | Significato | Famiglia (doc) |
|---|---|---|
| W130 | `D)` senza riga `N)`/`N+`/`N2` parent valida | Dinamiche |
| W131 | Token in eccesso rispetto agli eventi `N)` | `A)`/`D)`/`L)` (condiviso) |
| W132 | `D)` token `-` non riconducibile a extension/barline | Dinamiche |
| W133 | Container testuale non chiuso a fine riga | Dinamiche |
| W134 | Play directive vuota `(=)` | Play directive |
| W135 | Ordine slot invertito (tempo prima di style) | Play directive |
| W136 | BPM fuori range (10–999) | Play directive |
| W137 | Figura NRK non valida in metric modulation | Play directive |
| W138 | Play directive in riga diversa da `M)` | Play directive |
| W139 | Token `A)` fuori dal vocabolario | Articolazioni |
| W140 | Più di una sezione `FORM)` | PLAY/FORM |
| W141 | Durata `|BARS` non valida (1–999) | PLAY/FORM |
| W142 | Repeat count `xN` fuori range (2–99) | PLAY/FORM |
| W143 | Keyword `&xxx` non riservata | PLAY/FORM |
| W144 | Legatura `A)` malformata (non chiusa a fine riga) | Articolazioni |
| W145 | `FORM)` non in fondo al documento | PLAY/FORM |
| W146 | `[!]` ridondante: nessuna sezione opzionale da chiudere | Markers |
| W147 | Blocco `%%NAME` non chiuso (manca `%%end`) | Versioni |
| W148 | `%%end` orfano (nessun blocco aperto) | Versioni |
| W149 | Blocco `%%NAME` annidato | Versioni |
| W150 | `HV)` malformato | Versioni |
| W151 | Sezione collassabile non a inizio rigo (§4.7) | Markers |
| W152 | Riga `item:` in collezione `nrk-book:` | Collezioni |
| W153 | Chiave override sconosciuta in `item:` | Collezioni |
| W154 | Riga `item:` non seguita da un blocco-brano | Collezioni |
| W155 | Direttiva header collezione dopo il primo blocco | Collezioni |
| W156 | Collezione priva di blocchi-brano | Collezioni |
| W157 | `LYRICS) [NAME]` riferisce una sezione inesistente (reference-broken) | Lyrics (blocco `LYRICS)`) |
| W158 | Gruppo pickup `<…>` di `LYRICS)` in overflow sulla corsa di note precedente | Lyrics (blocco `LYRICS)`) |

> Nota storica: `W144` era stato bozzato anche per "`PLAY)` nidificata", caso
> **impedito strutturalmente** dal parser (mai emesso); il codice resta quindi
> alle articolazioni. La sezione collassabile non-a-inizio-rigo è stata spostata
> da `W147` (che collideva con Versioni) a **`W151`** (2026-05-26).

---

## neumaRk 0.5.0 — Prima versione pubblica

### Stato

Public preview. Il linguaggio è utilizzabile e coerente,
ma soggetto a evoluzioni a breve termine.

### Significato della versione

Questa è la **prima versione pubblica** di neumaRk.
Il numero 0.5 riflette una maturazione concettuale già avanzata,
pur senza garantire stabilità definitiva dell’interfaccia semantica.

### Funzionalità incluse

- struttura a datapack
- header con deduzione conservativa
- note con durate implicite ed esplicite
- accordi con semantica ritmica e durate implicite ed esplicite
- accordi con **lista compatta di durate** `X(a,b,r16,c,...)` (vedi §4.4)
- gestione di ripetizioni e flusso
- supporto a formati Compact / Human / Verbose

### Chiarimenti normativi

- contesto musicale persistente
- semantica contestuale dei simboli
- priorità della nota unica nella battuta
- riga Format deducibile

### Non ancora stabilizzato

> Elenco storico **alla 0.5.0**; molte di queste voci sono state introdotte
> nella 0.6 (vedi *Novità della 0.6*).

- articolazioni, dinamiche, lyrics
- polyaccordi (sintassi `[top|bottom]`, vedi `neumaRk_chords.md` §6)
- multi-stave per datapack (fino a 4 righi, vedi `neumaRk_datapack.md` §4)
- ripetizione di misura (sintassi `%` / `%!` / `%2` / `%!2` / `%4` / `%!4`, vedi `neumaRk_flow_and_repeats.md` §7)
- possibili estensioni sintattiche
- raffinamento delle regole di deduzione
- validazione formale completa

### Compatibilità

Non esistono versioni pubbliche precedenti.