From 0871573ea2a5407cb3a83860260a374ef27fe55e Mon Sep 17 00:00:00 2001 From: Chris <26607885+chrisglein@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:19:35 -0700 Subject: [PATCH 1/3] Add agent docs, skills, and VS Code/MCP config --- .github/copilot-instructions.md | 8 ++ .github/skills/booklet-song-from-abc/SKILL.md | 81 +++++++++++++++++++ .gitignore | 3 + .vscode/mcp.json | 9 +++ .vscode/settings.json | 25 ++++++ AGENTS.md | 44 ++++++++++ 6 files changed, 170 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/skills/booklet-song-from-abc/SKILL.md create mode 100644 .vscode/mcp.json create mode 100644 .vscode/settings.json create mode 100644 AGENTS.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..edc784f --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,8 @@ +# Copilot instructions — shanties + +**The primary artifact is the website** (`src/`): an interactive ABC-notation songbook — pick or type a song and abcjs live-renders staff notation, with transpose and lyrics / verses / guitar-tab / trumpet-fingering toggles. It deploys to https://brewingcode.github.io/shanties. The two printable **booklets** (`booklet/` = lyrics, `musicbook/` = staff) are secondary artifacts derived from the same `songs/`. **Read `AGENTS.md` for site architecture, URL params/filters, and the booklet/music-capture pipelines before any non-trivial change.** + +- Build the site: `npm run build` (Node-only, cross-platform → `dist/`). Serve with live reload: `npx pug-pack src -w` (http://localhost:3000); `npm run dev` rebuilds but does **not** serve. +- `src/songs.json` + `src/by-title.json` are generated & gitignored — run a build if they're missing. +- The Windows build is already fixed via `patches/pug-pack+1.11.0.patch` (applied by `postinstall`/patch-package). Don't re-diagnose or revert it. +- Prefer Node built-ins over new deps; don't leave throwaway scripts; this is a PowerShell box — use single-line commands. diff --git a/.github/skills/booklet-song-from-abc/SKILL.md b/.github/skills/booklet-song-from-abc/SKILL.md new file mode 100644 index 0000000..2396c48 --- /dev/null +++ b/.github/skills/booklet-song-from-abc/SKILL.md @@ -0,0 +1,81 @@ +--- +name: booklet-song-from-abc +description: 'Create or fix a Sea Shanties booklet song page/spread from its ABC-notation source, keeping chords in sync. USE WHEN: generating a new booklet/*.md song from a songs/*.txt ABC file; auditing or fixing chord transcription errors (wrong chord, wrong word, missing/extra chord) between a booklet markdown and its ABC; aligning [chord] placements to the ABC "chord"-before-note positions; transposing a booklet song to a new key. Covers both formats (ABC and booklet markdown), the note→syllable→chord alignment procedure, caller-vs-crew (`>`) refrain marking, and the common pitfalls (late chords vs pickup placement, dropped internal returns, key-signature accidentals, transposition drift, held-note melisma).' +--- + +# Booklet Song from ABC + +Build or repair a song in `booklet/` so its `[chord]` placements match the harmony encoded in the corresponding `songs/*.txt` ABC file. **The ABC is the primary reference for chords and lyrics** — but the songbook maintainer may deliberately override it by ear (see pitfall 11). + +## When to use + +- **Initial generation** — a `songs/.txt` ABC exists and you need a new `booklet/.md` spread. +- **Audit / fix** — a `booklet/.md` already exists and you're checking or correcting its chords against the ABC (the task that produced [SongAnalysis.md](../../../SongAnalysis.md)). +- **Transpose** — moving a booklet song to a different key for the singers' range while staying faithful to the ABC's progression. + +## The two formats + +### ABC source (`songs/*.txt`) + +Header fields: `X:` index, `T:` title, `M:` metre, `L:` default note length, `K:` key, `Q:` tempo, `V:` voice, `P:` part label (e.g. `Verse` / `Chorus`), `%%…` render directives. + +Body: +- Notes are letters (`A`–`G`, `a`–`g`, `,`/`'` shift octave). Digits/fractions after a note set duration (`e2`, `b,3/2`, `A4`). +- **Chords** are quoted text placed *immediately before the note they attach to*: `"F"ABcA` → the `F` chord starts on the `A`. +- `w:` is a lyric line aligned **one syllable per note, left to right**. Within a word, hyphens split syllables (`John-ny`); spaces separate words. `~`, `*`, `_` mark a **held note / melisma** (the previous syllable continues — do NOT advance to the next syllable). `\` continues a `w:` onto the next line. `y`/`z` are spacers/rests. +- `W:` (capital) holds extra verses as plain text (no note alignment). +- **Key signature changes which letter means which pitch.** In `K:Eb`, a written `A` note is actually **A♭** — this decides whether a passage fits, say, `Fm` vs `Cm`. Never infer the chord from the melody letter without applying the key signature. +- Multi-voice songs (`V: 1`, `V: 2`) put the melody usually in `V: 1`; read chords from the melody voice. + +### Booklet markdown (`booklet/*.md`) + +- `# Title` first line; optional credit as an italic line `*Artist, year*`. +- Verse lines are plain text lines. +- `{chorus}` opens a boxed chorus block (styled by `shanties.css`). +- `[Chorus]` on its own line is a **cue** ("repeat the chorus here"). +- A line beginning with `> ` renders in the **refrain style** (indented italic). Use it to mark everything the **crew** sings versus the **caller/lead**: the echoed repeats of a call line, the response refrains, and — in a traditional call-and-response shanty — *every* line of the `{chorus}`. Leave the caller's unique lead lines un-prefixed (roman). A modern verse/chorus song that isn't call-and-response (e.g. Joli Rouge) keeps its chorus un-prefixed. +- `[Chord]` is placed **immediately before the syllable it sits on**: `to[G]bacco` → `G` on the "bac" syllable. Put it on the note's **downbeat syllable**, not a pickup word before it (`There [Cm]once`, not `[Cm]There`). +- Separate stanzas within a long verse with a **blank line**. +- `---` marks the **spread/page break** inside the song. + +## Procedure: ABC → booklet + +1. **Read headers.** Note `K` (key + accidentals), `M`, `L`, and any `P:` (Verse/Chorus) and `V:` (which voice is the melody). +2. **Walk each melodic line note-by-note**, pairing every note with its `w:` syllable in order. Skip nothing: held-note markers (`~ * _`) keep the pointer on the current syllable. +3. **Record each chord's syllable** — the syllable of the note *immediately after* each `"chord"`. +4. **Emit booklet lines**, putting `[Chord]` right before that syllable. Copy the ABC's `w:` (and `W:`) text as the lyrics; prefer `w:` wording over `W:` when they differ. +5. **Structure & roles:** wrap the refrain in `{chorus}`; mark every **crew** line with `> ` (echoed call repeats, refrain answers, and all chorus lines of a call-and-response shanty), leaving the **caller's** lead lines un-prefixed; use `[Chorus]` as the repeat cue for later verses; break long verses into stanzas with a blank line; insert `---` near the middle so the song fills a two-page spread. +6. **House style for verses:** the booklet normally leaves verses **unchorded**, showing chords once (in the `{chorus}`, or on the first chorded instance). Keep verses unchorded **unless** the ABC's verse and chorus have genuinely different progressions, or the ABC only harmonizes the verse — then chord whichever section carries the harmony. +7. **Register the page** in [book.yaml](../../../booklet/book.yaml) (`pages:` list, `type: song`) if this is a new song. + +## Procedure: audit / fix an existing page + +1. Do the same note→syllable→chord alignment from the ABC. +2. Diff the booklet's `[chord]` positions against the derived positions. Classify each mismatch: **wrong chord**, **wrong word** (misaligned), **missing**, or **extra**. +3. Fix minimally — move/replace only the offending `[chord]`; don't rewrite lyrics unless they diverge from the ABC. +4. Record findings (per-song verdict) as in [SongAnalysis.md](../../../SongAnalysis.md). + +## Common pitfalls (ranked by how often they bite) + +1. **Late chords (the #1 error).** Put the chord on the exact syllable of the note the ABC attaches it to — *not* the next stressed word or the end of the line. Verify by the melody note sitting under the chord. +2. **Dropping an internal return.** `C → F → C` easily collapses to `C … F` with the `F` parked on the last word and the return to `C` lost. Preserve every change in the ABC. +3. **Key-signature accidentals.** e.g. `K:Eb` ⇒ written `A` = A♭. This flips which chord fits. Always apply the key signature before judging a chord. +4. **Transposition drift.** If the booklet is in a different key from the ABC, transpose **every** chord by the **same** interval. Keep a minor tonic minor (don't swap in the relative major), and **keep dominants** (a `V7`/`E7`/`A7` before the tonic must survive the transposition). +5. **Held notes / melisma.** `~ * _` extend the previous syllable — they do not consume a new lyric syllable. Miscounting them shifts every following chord. +6. **Chord on the downbeat, not the pickup.** The mirror image of pitfall 1: put the `[chord]` on the exact note the ABC attaches it to. When a pickup/anacrusis precedes that note (`And we'll`, `There`, `Oh`), the chord belongs on the following downbeat word (`roll`, `once`), not the pickup. +7. **Prefer whole-word placement; don't over-split.** Put the `[chord]` before the whole word when the change falls at/near the word start (`[Dm]swinging`, not `swing[Dm]ing`). Only split a word when the change genuinely occurs mid-word *and* it matters. If the ABC chord lands mid-word (e.g. the `B` on "whaler-**men**") but the booklet writes the word as one token, place the `[chord]` at the nearest word boundary. +8. **Shared verse/chorus tunes.** Many shanties reuse the verse melody for the chorus; a chord that's on word *N* of the verse maps to the *analogous* chorus word, which may differ in syllable count — align by melodic position, not word index. +9. **Fast response lines.** Call-and-response refrains change chords quickly (watch `G`/`D`/`D7` clusters); it's where misalignments concentrate. +10. **Modern / copyrighted songs.** The booklet may intentionally follow the artist's official chart rather than the ABC. Flag divergences and confirm with the user before "fixing". +11. **The maintainer's committed chords win.** The ABC is the reference, but the songbook owner may deliberately differ — adding passing chords by ear, re-voicing a section, or choosing the ABC's *own* key over a prior transposition. When asked to "err toward the ABC," adopt the ABC's actual key and chords rather than transposing an existing booklet version; and don't silently revert a maintainer's deliberate choice back to the ABC. + +## Verification / keeping in sync + +- Re-derive the booklet chords from the ABC and confirm each `[chord]` sits on the ABC-attached syllable. +- Build a proof and eyeball it: `npm run booklet:proof` (reading-order, one page per page) or `npm run booklet` (imposed), then open `booklet/sea-shanties.html`. +- If you added a song, make sure it's in `booklet/book.yaml` and the contents/page numbers still line up. + +## References + +- `ABCquickRefv0_6.pdf` and `abc_standard_v2.1 [abc wiki].mht` in the repo root — ABC notation reference. +- [booklet/README.md](../../../booklet/README.md) — build/print instructions and file roles. diff --git a/.gitignore b/.gitignore index f90e636..5cae7f5 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,6 @@ node_modules yarn.lock package-lock.json + +# Playwright MCP scratch (page snapshots, console logs) +/.playwright-mcp/ diff --git a/.vscode/mcp.json b/.vscode/mcp.json new file mode 100644 index 0000000..137db1f --- /dev/null +++ b/.vscode/mcp.json @@ -0,0 +1,9 @@ +{ + "servers": { + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp", "--headless", "--browser", "chromium"] + } + }, + "inputs": [] +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..f5e51f1 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,25 @@ +{ + // Workspace-level auto-approve list. Lives in the repo so it roams across + // all machines via git. Per-machine overrides go in %APPDATA%\Code\User\settings.json. + // + // Design rule: ONLY read-only / stdout-only cmdlets and a CLOSED, enumerated + // list of helper scripts may auto-approve. Nothing that writes to disk, + // executes an arbitrary script block, or names an unknown script belongs here. + // + // See .github/skills/_shared/scripts/README.md for the rationale and full mechanism. + "chat.tools.terminal.autoApprove": { + // --- Read-only inspection (no side effects) --- + "Test-Path": true, + "Get-Item": true, + "Get-ItemProperty": true, + "Get-Date": true, + // --- Read-only data shaping (stdout only; no -FilePath/-Path writes, + // no script-block execution) --- + "Group-Object": true, + "ConvertFrom-Json": true, + "ConvertTo-Json": true, + "ConvertFrom-Csv": true, + "ConvertTo-Csv": true, + "Out-String": true, + } +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1a1c5db --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS.md — shanties + +Fuller agent guide for the sea-shanties project. The always-loaded essentials live in `.github/copilot-instructions.md`; read this file for anything beyond a trivial change. + +The repo's **primary purpose is the website** (`src/`) — an interactive ABC-notation songbook. The two printable saddle-stitch booklets are secondary artifacts derived from the same `songs/`. The site deploys to https://brewingcode.github.io/shanties by `.github/workflows/gh-pages.yml` (Ubuntu, Node 20, `npm install` + `npm run build`). + +## Build & run +- `npm run build` — site → `dist/`: runs `songs-to-json.js`, then `pug-pack src`, then copies `Songbook.pdf` + `qr-code.svg`. Cross-platform (Node only — no python/`cp`). +- Serve locally with live reload: `npx pug-pack src -w` → http://localhost:3000 (browserSync). `npm run dev` watches + rebuilds but does not serve. +- `npm run booklet` / `booklet:proof` / `booklet:single` — lyrics booklet (`booklet/`). +- `npm run musicbook` / `musicbook:proof` — staff-notation booklet (`musicbook/`). +- Syntax-check CoffeeScript snippets by piping (dedented) to `npx coffee -s -c -p`. + +## The website (`src/`) — the primary artifact +Interactive ABC songbook: type ABC into `#abc` (or pick a song from the dropdown, or click "add a song" → GitHub `songs/`), and abcjs live-renders staff notation into `#paper`. Settings toggle inline lyrics (`#show-lyrics`), extended verses (`#show-verses`), trumpet fingering (`#show-trumpet`), and guitar tab (`#show-gtab`); `#transpose` shifts the key and shows from/to in `#fromKey`/`#toKey`. Parse warnings render to `#warnings`; on iPad the textarea sits behind an Edit button. +- `src/index.pug` is the whole page (extends pug-pack `_base`). All logic is CoffeeScript in a `:coffeescript` filter; abcjs/jquery/bootstrap are `include`d and inlined into one big `dist/index.html`. +- `songs/*.txt` are ABC songs. `songs-to-json.js` generates `src/songs.json` (keyed by filename) + `src/by-title.json` (keyed by `T:` title) — both are **generated and gitignored**; run a build if they're missing. +- abcjs renders into `#paper`. UI chrome is tagged `.noprint` (hidden in print and when `body.fullscreen`). +- URL params: `title=` / `file=` pick a song; `fullscreen=true` hides chrome; `lyrics=false`, `verses=false` hide inline / extended lyrics (read before first render). +- `setSong` filters ABC lines pre-render: lowercase `w:` = inline lyrics (or trumpet fingering if all digits), uppercase `W:` = extended verses. +- ABC songs use `%%` directives (e.g. `%%notelabels`, `%%notecolors`, `%%vocalfont`) alongside standard fields (`T:`, `M:`, `K:`, `w:`/`W:`). + +## Booklets (markdown-booklet) +- Engine: `node node_modules/markdown-booklet/src/cli.js build /book.yaml [--out … | --reading | --single]`. +- `booklet/` = lyrics (Markdown, two-page spreads). `musicbook/` = staff notation (single `type: html` pages, no spreads), parallel to the lyrics book. +- Song list source of truth is `booklet/book.yaml`. Before assuming a song has staff notation, confirm its `songs/.txt` exists (e.g. `skipper-jan-rebec` was booklet-only for a while). + +## Music-book staff capture (`musicbook/pages/*.svg`) +Each staff SVG is captured from the running site. To (re)generate one: +1. Serve the site (`npx pug-pack src -w`). +2. Headlessly load `?file=.txt&fullscreen=true&verses=false`, grab `#paper svg` outerHTML (strip its inline `style`, set `width=100%`, remove `height`). +3. **Post-process — required, or `` renders broken:** add `xmlns="http://www.w3.org/2000/svg"` to the root `` (abcjs omits it, so the standalone file is invalid XML) and replace ` ` → ` ` (` ` is undefined in standalone XML/SVG). Write UTF-8, no BOM. +The abcjs SVG already renders the `T:` title, so pages need no extra heading; `.staff img` fit-contains within the page (`music.css`). Each `.html` is just `
`. + +## Cross-platform — do not undo +- Windows builds work via **patch-package**: `patches/pug-pack+1.11.0.patch` (applied by the `postinstall` script) fixes pug-pack's Unix-`find` call, its Windows path/regex `srcname` bug, the git `cwd`, and registers a `coffeescript` pug filter (so it no longer depends on hoisting `jstransformer-coffeescript`). Don't revert these or re-diagnose "pug-pack broken on Windows". +- `pug-pack` is an **unpinned git-branch** dependency — if it changes upstream the patch may need refreshing (`npx patch-package pug-pack`). + +## Conventions & gotchas +- Prefer Node built-ins over new dependencies (e.g. `fs.cpSync`, not `shx`). +- Don't write throwaway scripts merely to execute them; validate by reasoning or a one-off inline command. Delete one-shot data-fix scripts after use. +- Don't hard-wrap Markdown to a fixed column width. +- This is a Windows/PowerShell dev box — prefer single-line commands; multi-line array/here-string pastes can mangle in the persistent shell. +- `.playwright-mcp/` is scratch output and is gitignored. From 964801260b95636c6db611b716a714c75d23c68d Mon Sep 17 00:00:00 2001 From: Chris <26607885+chrisglein@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:25:34 -0700 Subject: [PATCH 2/3] Update description of tool approvals --- .vscode/settings.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index f5e51f1..7dbf85d 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,12 +1,10 @@ { // Workspace-level auto-approve list. Lives in the repo so it roams across - // all machines via git. Per-machine overrides go in %APPDATA%\Code\User\settings.json. + // all machines via git. Per-machine overrides go in ~\Code\User\settings.json. // // Design rule: ONLY read-only / stdout-only cmdlets and a CLOSED, enumerated // list of helper scripts may auto-approve. Nothing that writes to disk, // executes an arbitrary script block, or names an unknown script belongs here. - // - // See .github/skills/_shared/scripts/README.md for the rationale and full mechanism. "chat.tools.terminal.autoApprove": { // --- Read-only inspection (no side effects) --- "Test-Path": true, From 5ebe489e3b988baa5a3837e7b6a65debfd0f194c Mon Sep 17 00:00:00 2001 From: Chris <26607885+chrisglein@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:27:51 -0700 Subject: [PATCH 3/3] Correct docs to current branch --- .github/copilot-instructions.md | 5 ++--- AGENTS.md | 29 +++++++++-------------------- 2 files changed, 11 insertions(+), 23 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index edc784f..7f792e7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,8 +1,7 @@ # Copilot instructions — shanties -**The primary artifact is the website** (`src/`): an interactive ABC-notation songbook — pick or type a song and abcjs live-renders staff notation, with transpose and lyrics / verses / guitar-tab / trumpet-fingering toggles. It deploys to https://brewingcode.github.io/shanties. The two printable **booklets** (`booklet/` = lyrics, `musicbook/` = staff) are secondary artifacts derived from the same `songs/`. **Read `AGENTS.md` for site architecture, URL params/filters, and the booklet/music-capture pipelines before any non-trivial change.** +**The primary artifact is the website** (`src/`): an interactive ABC-notation songbook — pick or type a song and abcjs live-renders staff notation, with transpose and lyrics / verses / guitar-tab / trumpet-fingering toggles. It deploys to https://brewingcode.github.io/shanties. The printable **booklet** (`booklet/` = lyrics) is a secondary artifact derived from the same `songs/`. **Read `AGENTS.md` for site architecture, URL params/filters, and the booklet pipeline before any non-trivial change.** -- Build the site: `npm run build` (Node-only, cross-platform → `dist/`). Serve with live reload: `npx pug-pack src -w` (http://localhost:3000); `npm run dev` rebuilds but does **not** serve. +- Build the site: `npm run build` → `dist/`. Serve with live reload: `npx pug-pack src -w` (http://localhost:3000); `npm run dev` rebuilds but does **not** serve. - `src/songs.json` + `src/by-title.json` are generated & gitignored — run a build if they're missing. -- The Windows build is already fixed via `patches/pug-pack+1.11.0.patch` (applied by `postinstall`/patch-package). Don't re-diagnose or revert it. - Prefer Node built-ins over new deps; don't leave throwaway scripts; this is a PowerShell box — use single-line commands. diff --git a/AGENTS.md b/AGENTS.md index 1a1c5db..c386245 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,42 +2,31 @@ Fuller agent guide for the sea-shanties project. The always-loaded essentials live in `.github/copilot-instructions.md`; read this file for anything beyond a trivial change. -The repo's **primary purpose is the website** (`src/`) — an interactive ABC-notation songbook. The two printable saddle-stitch booklets are secondary artifacts derived from the same `songs/`. The site deploys to https://brewingcode.github.io/shanties by `.github/workflows/gh-pages.yml` (Ubuntu, Node 20, `npm install` + `npm run build`). +The repo's **primary purpose is the website** (`src/`) — an interactive ABC-notation songbook. The printable saddle-stitch booklet is a secondary artifact derived from the same `songs/`. The site deploys to https://brewingcode.github.io/shanties by `.github/workflows/gh-pages.yml` (Ubuntu, Node 20, `npm install` + `npm run build`). ## Build & run -- `npm run build` — site → `dist/`: runs `songs-to-json.js`, then `pug-pack src`, then copies `Songbook.pdf` + `qr-code.svg`. Cross-platform (Node only — no python/`cp`). +- `npm run build` — site → `dist/`: runs `./songs-to-json`, then `pug-pack src`, then `cp`s `Songbook.pdf` + `qr-code.svg` into `dist/`. Uses Unix `cp`/`./` (not PowerShell-native). - Serve locally with live reload: `npx pug-pack src -w` → http://localhost:3000 (browserSync). `npm run dev` watches + rebuilds but does not serve. - `npm run booklet` / `booklet:proof` / `booklet:single` — lyrics booklet (`booklet/`). -- `npm run musicbook` / `musicbook:proof` — staff-notation booklet (`musicbook/`). - Syntax-check CoffeeScript snippets by piping (dedented) to `npx coffee -s -c -p`. ## The website (`src/`) — the primary artifact Interactive ABC songbook: type ABC into `#abc` (or pick a song from the dropdown, or click "add a song" → GitHub `songs/`), and abcjs live-renders staff notation into `#paper`. Settings toggle inline lyrics (`#show-lyrics`), extended verses (`#show-verses`), trumpet fingering (`#show-trumpet`), and guitar tab (`#show-gtab`); `#transpose` shifts the key and shows from/to in `#fromKey`/`#toKey`. Parse warnings render to `#warnings`; on iPad the textarea sits behind an Edit button. - `src/index.pug` is the whole page (extends pug-pack `_base`). All logic is CoffeeScript in a `:coffeescript` filter; abcjs/jquery/bootstrap are `include`d and inlined into one big `dist/index.html`. -- `songs/*.txt` are ABC songs. `songs-to-json.js` generates `src/songs.json` (keyed by filename) + `src/by-title.json` (keyed by `T:` title) — both are **generated and gitignored**; run a build if they're missing. +- `songs/*.txt` are ABC songs. `songs-to-json` (a Python script) generates `src/songs.json` (keyed by filename) + `src/by-title.json` (keyed by `T:` title) — both are **generated and gitignored**; run a build if they're missing. - abcjs renders into `#paper`. UI chrome is tagged `.noprint` (hidden in print and when `body.fullscreen`). - URL params: `title=` / `file=` pick a song; `fullscreen=true` hides chrome; `lyrics=false`, `verses=false` hide inline / extended lyrics (read before first render). - `setSong` filters ABC lines pre-render: lowercase `w:` = inline lyrics (or trumpet fingering if all digits), uppercase `W:` = extended verses. - ABC songs use `%%` directives (e.g. `%%notelabels`, `%%notecolors`, `%%vocalfont`) alongside standard fields (`T:`, `M:`, `K:`, `w:`/`W:`). -## Booklets (markdown-booklet) -- Engine: `node node_modules/markdown-booklet/src/cli.js build /book.yaml [--out … | --reading | --single]`. -- `booklet/` = lyrics (Markdown, two-page spreads). `musicbook/` = staff notation (single `type: html` pages, no spreads), parallel to the lyrics book. -- Song list source of truth is `booklet/book.yaml`. Before assuming a song has staff notation, confirm its `songs/.txt` exists (e.g. `skipper-jan-rebec` was booklet-only for a while). - -## Music-book staff capture (`musicbook/pages/*.svg`) -Each staff SVG is captured from the running site. To (re)generate one: -1. Serve the site (`npx pug-pack src -w`). -2. Headlessly load `?file=.txt&fullscreen=true&verses=false`, grab `#paper svg` outerHTML (strip its inline `style`, set `width=100%`, remove `height`). -3. **Post-process — required, or `` renders broken:** add `xmlns="http://www.w3.org/2000/svg"` to the root `` (abcjs omits it, so the standalone file is invalid XML) and replace ` ` → ` ` (` ` is undefined in standalone XML/SVG). Write UTF-8, no BOM. -The abcjs SVG already renders the `T:` title, so pages need no extra heading; `.staff img` fit-contains within the page (`music.css`). Each `.html` is just `
`. - -## Cross-platform — do not undo -- Windows builds work via **patch-package**: `patches/pug-pack+1.11.0.patch` (applied by the `postinstall` script) fixes pug-pack's Unix-`find` call, its Windows path/regex `srcname` bug, the git `cwd`, and registers a `coffeescript` pug filter (so it no longer depends on hoisting `jstransformer-coffeescript`). Don't revert these or re-diagnose "pug-pack broken on Windows". -- `pug-pack` is an **unpinned git-branch** dependency — if it changes upstream the patch may need refreshing (`npx patch-package pug-pack`). +## Booklet (markdown-booklet) +- Engine: `node node_modules/markdown-booklet/src/cli.js build booklet/book.yaml [--out … | --reading | --single]`. +- `booklet/` = lyrics (Markdown, two-page spreads). +- Song list source of truth is `booklet/book.yaml`. Not every booklet song has a matching `songs/.txt` ABC (e.g. `skipper-jan-rebec` was booklet-only for a while). ## Conventions & gotchas -- Prefer Node built-ins over new dependencies (e.g. `fs.cpSync`, not `shx`). +- Prefer Node built-ins over new dependencies. +- `pug-pack` is an **unpinned git-branch** dependency (`brewingcode/pug-pack` in `package.json`) — upstream changes can affect the build. - Don't write throwaway scripts merely to execute them; validate by reasoning or a one-off inline command. Delete one-shot data-fix scripts after use. - Don't hard-wrap Markdown to a fixed column width. - This is a Windows/PowerShell dev box — prefer single-line commands; multi-line array/here-string pastes can mangle in the persistent shell.