fretboard-renderer-core

Platform-agnostic parsing, music-theory, and SVG-rendering core for guitar fretboard diagrams. Extracted from fretboard-renderer (an Obsidian plugin) so the same logic can be shared with fretboard-renderer-vscode and other consumers (e.g. browser/HTML renderers) without depending on the Obsidian API.

This package has no knowledge of Obsidian or VSCode — it parses the ​```fretboard YAML syntax, resolves it into a diagram model, and builds a platform-agnostic virtual SVG tree that callers serialize either to a live DOM node (toDom, needs a global document) or to a plain string (toSvgString, works anywhere).

See the consuming projects' documentation for the YAML syntax itself.

Usage

import { parseFretboardBlock, resolveFretboardModel, buildFretboardSvg, toSvgString, DEFAULT_SETTINGS } from "fretboard-renderer-core";

const block = parseFretboardBlock(yamlSource);
const model = resolveFretboardModel(block, DEFAULT_SETTINGS);
const svg = toSvgString(buildFretboardSvg(model));

Browser usage: <fretboard-renderer>

Registering the <fretboard-renderer> custom element renders the same ​```fretboard YAML directly from an element's own content, with no server-side step. Styling ships inside the element's shadow root, so there's no separate CSS file to load.

With a bundler:

import "fretboard-renderer-core/browser";

Without one — a single self-contained script, dependencies included:

<script type="module" src="https://cdn.jsdelivr.net/npm/fretboard-renderer-core/dist/cdn/fretboard-renderer.js"></script>

Either way, the element then works anywhere in the page:

<fretboard-renderer>
  startFret: 3
  notes:
    - {s: 6, f: 5, label: root}
    - [5, 7]
</fretboard-renderer>

If a note's label needs an HTML-unsafe character (<, &), wrap the YAML in a <script type="text/yaml"> child instead — the HTML parser leaves <script> content untouched, so nothing needs escaping:

<fretboard-renderer>
  <script type="text/yaml">
    notes:
      - {s: 6, f: 5, label: "<3"}
  </script>
</fretboard-renderer>

A diagrams: block (see the parser) renders as several diagrams side by side, same as in Obsidian/VSCode.

Page-wide defaults (the "System" layer — same role as the Obsidian plugin's settings tab) are set with configureFretboardRenderer, which re-renders every mounted instance:

import { configureFretboardRenderer } from "fretboard-renderer-core/browser";

configureFretboardRenderer({ defaultTuning: "D,A,D,G,B,E", orientation: "vertical" });

To theme the diagram, override the --fretboard-* custom properties from outside — they inherit through the shadow boundary:

fretboard-renderer {
  --fretboard-color-accent: tomato;
}

Development

npm install
npm run build   # emits dist/ (compiled JS + .d.ts)
npm test        # runs the test suite

License

MIT