# Page and system layout

## Start systems and pages at musical places

A `system-map` lists the first measure of each new system; a `page-map`
lists the first measure of each new page. Measure 1 is implicit. Put the map
inside a part when it describes that player's page.

```scorescript
scorescript 0.3
score "Four lines" {
  parts { fl }
  fl {
    system-map {3, 5, 7}
    page-map {5}
    m1-8 { 1C5 | D | E | F | G | F | E | C }
  }
}
```

`system-map {5:2}` starts a system at measure 5 and requests exactly two
semantic measures. A plain `5` starts a system without prescribing its count.
When copying a printed part, read each system's first measure number directly.
Page starts imply system starts; system starts alone do not imply new pages.
Conflicting authored cuts can cause the renderer to decline an exact-count
span; inspect the render report instead of treating it as an override.
The example requests systems beginning at 1, 3, 5, and 7, with measure 5
starting a new page. The inline preview is flowing SVG; use paginated SVG
or PDF output to see page boundaries.

## Local cuts

`\n` starts a system **before its containing measure**. `\p` starts a page
and system there. Prefer placing either immediately after the preceding
barline, before the target measure's first note. A trailing cut before a
barline still belongs to the current measure; it does not mean “after this bar.”

| Source within a musical row | Result |
| --- | --- |
| `1C5 \| D \n \| E` | New system before D, measure 2 |
| `1C5 \| D \| \n E` | New system before E, measure 3 |
| `1C5 \| D \| \p E` | New page and system before E, measure 3 |

Address a cut inside omitted silence by attaching its number, such as `\n29`.
A part's cut belongs to that part. A score-level `layout { \n13 \p46 }`
applies globally.

These are actual backslash letters in the source, not escaped newlines in a
programming string. A lone backslash at the end of a physical source line
continues the same musical row instead of requesting an engraved break.

## Inside parts-first and measures-first music

These two sources request the same notes and player-local cuts. In both,
flute starts a system at measure 2 and a page at measure 4; oboe has no
player-local cuts.

Parts-first:

```scorescript
scorescript 0.3
score "Part-local cuts" {
  parts { fl ob }
  fl { m1-4 { 1C5 | \n D | E | \p F } }
  ob { m1-4 { 1C4 | D | E | F } }
}
```

Measures-first:

```scorescript
scorescript 0.3
score "Measure-row cuts" {
  parts { fl ob }
  m1-4 {
    fl { 1C5 | \n D | E | \p F }
    ob { 1C4 | D | E | F }
  }
}
```

In a parts-first body, `system-map {2}` and `page-map {4}` can express
those same flute boundaries. Do not put these maps inside the flute's
measures-first row or invent a map-only detached flute body beside it:
those placements are not supported. Use inline cuts in that row, or a
score-level map when the intent is genuinely global.

## Duration inheritance still applies around cuts

```scorescript
qEb5 Bb D E | wD | A | \n eD D D D hr | eEb G Bb er hr
```

The first bar has four quarters. `wD` changes the inherited duration to a
whole note, so the next `A` is also whole. In measure 4, `eD` changes it to
an eighth; four eighth notes plus `hr` fill the bar. The `\n` begins a
system before that measure and consumes no duration.

After `hr`, the inherited duration is a half. Therefore measure 5 needs
the explicit `e` on `Eb`: three eighth notes, an eighth rest, and a half
rest fill 4/4. Writing only `Eb G Bb er hr` there would overfill the bar.
Layout placement and rhythmic validity are independent checks.

## Score Page versus Parts Page

| Placement | Combined score | Extracted player part |
| --- | --- | --- |
| Score-level map or `layout` block | Applies globally | Also applies to every extracted part |
| Cut in one player's music | Does not alone force an ensemble break | Applies to that player |
| Same local cut on every present part | Also becomes an ensemble boundary | Applies individually |
| Selected view's layout configuration | Refines that selected score view | Refines that selected part view |

Global and player-local source cuts **add together**. A part map does not
override or remove global cuts. For a full-score-only paper arrangement,
use a score view's layout configuration instead of imposing global source
cuts that every extracted player will inherit.

A “Score Page” configuration and a “Flute Page” configuration can select
different page settings and additional breaks from the same source. A
part view is not a parts-first source file; a score view is not a
measures-first source file. See [source arrangements and output views](representations.md).

## What normalization changes

`arrange=parts` and `arrange=measures` reorganize source music.
`maps=top|inline` moves musical context such as meter; it does **not**
toggle system/page maps versus inline cuts. Break formatting independently
uses maps for multiple cuts of a kind or exact-count system entries.
`hoist-breaks` can move matching per-part break maps to global scope;
it is not a command to discard player-specific layout.

Physical source wrapping changes code readability. Engraved systems and
pages follow musical layout directives and the selected output settings,
not the width of your code editor. Normalization is an optional source
rewrite; choosing another output view need not rewrite the music.

## Rest groups

`[|]` begins a new engraved multirest group at a silent bar.
`multi-map {3, 7}` records several such points compactly. This splits rest
grouping without forcing a system or page break. Keep the map in the same
scope as the intended rest grouping.

## Instrument brackets and braces

Left-side brackets identify groups of staves in each system. By default,
consecutive catalog instruments from the same family share a bracket when
there are at least two: for example, flute/oboe together and trumpet/trombone
together. A family separated by another family is not joined across it.
Unknown instruments and keyboards are not guessed into automatic groups.

Use a layout configuration's `staff_groups` to customize the marks:

| Value | Result |
| --- | --- |
| Omitted or `null` | Automatic family brackets |
| `[]` | No grouping symbols |
| Nonempty array | Exactly the specified groups, replacing automatic groups |

Each group has `first`, `last`, and `symbol` (`"bracket"` or `"brace"`).
Endpoints are exact printed part names, not roster abbreviations or indices.
Every staff between the endpoints is included. Groups must span at least
two staves in score order. Disjoint and nested groups are allowed; duplicate,
crossing, reversed, missing, or ambiguous endpoints are reported rather than
silently reassigned.

For `parts { fl ob tpt tbn }`, this saved configuration explicitly groups
the winds and brass:

```json
{
  "format": "scorescript-layouts",
  "version": 2,
  "default": "Ensemble",
  "layouts": [{
    "name": "Ensemble",
    "staff_groups": [
      {"first": "Flute", "last": "Oboe", "symbol": "bracket"},
      {"first": "B-flat Trumpet", "last": "Tenor Trombone", "symbol": "bracket"}
    ]
  }]
}
```

Save it beside `piece.scorescript` as `piece.layouts.json`. Use the actual
compiled part names when your roster has numbered players or custom labels.
To brace two deliberately authored keyboard staves, select those staves'
names and set `"symbol": "brace"`. A brace does not create a second staff,
assign hands, merge separately extractable parts, or alter playback.

Grouping is output layout, not an exercise `section` or a shared-music reader.
Full-score groups are removed when extracting one part. Both flowing SVG and
PDF draw the same group marks; source notes and identities are unchanged.

## Paper and engraving settings

The score source carries musical layout intent. An optional
`name.layouts.json` beside `name.scorescript` carries named paper and
engraving configurations. It can refine page size, margins, staff size,
spacing, and the selected part. A score still opens without the sidecar.
Use the editor's layout controls to create a configuration rather than
guessing JSON property names.

Layout affects the printed view. It does not change the pitches, durations,
or identities in the music. Always inspect the exported pages: a source
system map alone does not prove good spacing or correct pagination.