Imported from jg-wright/reaper-vinyl-cue-sheet (AGENTS.md). Install upstream with npx skills add jg-wright/reaper-vinyl-cue-sheet. Copyright stays with the author.

Vinyl Cue Sheet — Agent Guide

A REAPER ReaScript (Lua) that generates a vinyl cue sheet (HTML + PDF) from a project's regions/markers laid out in ruler lanes. Distributed via ReaPack. See README.md for user-facing setup/usage and PLAN.md for design and milestones.

Architecture

• Entry actions live in Vinyl Cue Sheet/:
  • vinyl_cue_sheet.lua — generates the cue sheet.
  • vinyl_cue_sheet_settings.lua — settings editor (@noindex).
• Logic lives in Vinyl Cue Sheet/lib/: config, regions (model building), html, pdf, project, render_format, timecode.
• Keep lib/* pure and REAPER-free where it already is (html, render_format, timecode, pdf command builders). This is what makes offline unit tests possible. REAPER-dependent code (reaper.* calls) belongs in the entry scripts, config, and project; inject dependencies (e.g. pdf.convert(html, pdf, cfg, deps) where deps = {os, exists, exec}) so tests can mock them.
• Entry scripts set package.path from the action context, then require("lib.xxx").

Build & test

There is no build. Tests run pure Lua without REAPER (they mock reaper). Run from the repo root — the path contains a space, so quote it:

# Syntax check
for f in "Vinyl Cue Sheet"/*.lua "Vinyl Cue Sheet"/lib/*.lua; do luac -p "$f"; done

# Unit tests
for t in render_format model html pdf; do lua "Vinyl Cue Sheet/test/${t}_spec.lua"; done

Specs are in Vinyl Cue Sheet/test/. CI mirrors this in .github/workflows/pull-request.yml (Lua 5.3). On macOS install Lua via brew install lua.

Conventions & pitfalls

• Config: every setting has a default in config.DEFAULTS; values are strings (ExtState stores strings). Add new settings there and expose them in the settings editor.
• Lane specs may be a number ("0") or a lane name; resolve via regions.resolve_lane_spec.
• Timecodes reset to 0 at each side start; per-side track numbering also resets.
• ReaImGui: call the raw reaper.ImGui_* API directly, NOT the imgui.lua shim (the shim's version filter hides InputText/SeparatorText). Enums are functions, e.g. reaper.ImGui_Cond_FirstUseEver(). Detect with reaper.APIExists(...). ReaImGui can't be exercised offline — syntax-check only and verify GUI in REAPER.
• render_format decodes REAPER's base64 RENDER_FORMAT sink config; the decoder must drop consumed bits per byte to avoid a float-precision bug. It's regression-tested.
• Do not hand-edit index.xml — it is generated by reapack-index in CI.

Releasing (ReaPack)

reapack-index converts the @about markdown header to RTF via pandoc; if pandoc is missing the package is silently skipped and index.xml comes out empty. CI must install pandoc and pass --name. See .github/workflows/reapack.yml. When adding a lib/*.lua file, also add it to the @provides list in vinyl_cue_sheet.lua, and add a -- @noindex line at the top so reapack-index doesn't treat it (or the test/*.lua files) as a standalone package and warn about a missing @version.