Printable music book

.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.

.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+	"servers": {
+		"playwright": {
+			"command": "npx",
+			"args": ["-y", "@playwright/mcp", "--headless", "--browser", "chromium"]
+		}
+	},
+	"inputs": []
+}

.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,
+    }
+}

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 <dir>/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/<slug>.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=<slug>.txt&fullscreen=true&verses=false`, grab `#paper svg` outerHTML (strip its inline `style`, set `width=100%`, remove `height`).
+3. **Post-process — required, or `<img>` renders broken:** add `xmlns="http://www.w3.org/2000/svg"` to the root `<svg>` (abcjs omits it, so the standalone file is invalid XML) and replace `&nbsp;` → `&#160;` (`&nbsp;` 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 `<slug>.html` is just `<div class="staff"><img src="pages/<slug>.svg"></div>`.
+
+## 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.

musicbook/all-for-me-grog.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/all-for-me-grog.svg" alt="Staff notation for All For Me Grog">
+</div>

musicbook/barretts-privateers.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/barretts-privateers.svg" alt="Staff notation for Barrett's Privateers">
+</div>

musicbook/book.yaml

@@ -0,0 +1,38 @@
+title: "Sea Shanties — Music"
+
+# Logical page + margins, matching the lyrics songbook so the two fold alike.
+# The physical sheet is derived as two pages wide.
+config:
+  page:
+    width: 5.5in
+    height: 8.5in
+  margins:
+    inner: 0.75in
+    outer: 0.5in
+    top: 0.6in
+    bottom: 0.6in
+  signatureSize: all
+  stylesheet: music.css
+
+# Staff notation captured from the running site at
+#   ?file=<song>.txt&fullscreen=true&verses=false
+# Each song is a single page (no spreads). Order mirrors the lyrics songbook,
+# with Old Maui filling what was the blank second page (cover + 15 = 16 pages).
+# (skipper-jan-rebec now has ABC on master but is not included here yet.)
+pages:
+  - { file: cover.html, showPageNumber: false }
+  - { file: old-maui.html }
+  - { file: all-for-me-grog.html }
+  - { file: barretts-privateers.html }
+  - { file: bully-boys.html }
+  - { file: bully-in-the-alley.html }
+  - { file: drunken-sailor.html }
+  - { file: health-to-the-company.html }
+  - { file: joli-rouge.html }
+  - { file: leave-her-johnny.html }
+  - { file: mingulay-boat-song.html }
+  - { file: randy-dandy-o.html }
+  - { file: roll-the-old-chariot-along.html }
+  - { file: south-australia.html }
+  - { file: wellerman.html }
+  - { file: whiskey-johnny.html }

musicbook/bully-boys.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/bully-boys.svg" alt="Staff notation for Bully Boys">
+</div>

musicbook/bully-in-the-alley.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/bully-in-the-alley.svg" alt="Staff notation for Bully in the Alley">
+</div>

musicbook/cover.html

@@ -0,0 +1,12 @@
+<!--
+type: html
+showPageNumber: false
+-->
+<div class="cover">
+  <div class="cover-title">Sea<br>Shanties</div>
+  <div class="cover-sub">Music Edition</div>
+  <div class="cover-byline">
+    <p>Staff notation for the crew</p>
+    <p>Chris Glein and Alex Deakin</p>
+  </div>
+</div>

musicbook/drunken-sailor.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/drunken-sailor.svg" alt="Staff notation for Drunken Sailor">
+</div>

musicbook/health-to-the-company.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/health-to-the-company.svg" alt="Staff notation for Health to the Company">
+</div>

musicbook/joli-rouge.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/joli-rouge.svg" alt="Staff notation for Joli Rouge">
+</div>

musicbook/leave-her-johnny.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/leave-her-johnny.svg" alt="Staff notation for Leave Her Johnny">
+</div>

musicbook/mingulay-boat-song.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/mingulay-boat-song.svg" alt="Staff notation for Mingulay Boat Song">
+</div>

musicbook/music.css

@@ -0,0 +1,56 @@
+/* Sea Shanties — music (staff notation) edition.
+   Appended after markdown-booklet's base CSS. url() paths resolve relative to
+   the OUTPUT html file, so build into this folder and keep pages/ as a sibling. */
+
+:root {
+  --display: "Primitive", "UnifrakturCook", "Blackletter", serif;
+  --body: "Lucida Bright", "Lucida Serif", "Georgia", "Times New Roman", serif;
+}
+
+.page-content { font-family: var(--body); }
+
+/* ---- Staff pages ------------------------------------------------------- */
+/* Each song page is a single captured abcjs SVG (which already renders the
+   song title). Fit it within the page content box, preserving aspect ratio. */
+.staff {
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.staff img {
+  max-width: 100%;
+  max-height: 100%;
+  width: auto;
+  height: auto;
+}
+
+/* ---- Cover ------------------------------------------------------------- */
+.cover {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+}
+.cover-title {
+  font-family: var(--display);
+  font-weight: 400;
+  font-size: 56pt;
+  line-height: 1.02;
+}
+.cover-sub {
+  font-family: var(--body);
+  font-size: 15pt;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  margin-top: 0.2in;
+  color: #333;
+}
+.cover-byline {
+  font-family: var(--body);
+  font-size: 13pt;
+  margin-top: 0.6in;
+}
+.cover-byline p { margin: 0.06in 0; }

musicbook/old-maui.html

@@ -0,0 +1,3 @@
+<div class="staff">
+  <img src="pages/old-maui.svg" alt="Staff notation for Old Maui">
+</div>