mirror of https://github.com/got-feedBack/feedBack.git synced 2026-09-13 08:29:28 +00:00

Files

T

Miguel_LZPFandBret Mogilefsky 1214a6c0a0 docs: extract plugin contracts into modular docs and slim CLAUDE.md

CLAUDE.md had grown to 545 lines / 50 KB — most of it plugin-author
content that other AI tools (Cursor, Copilot, Codex, Aider) and humans
without AI never reach. Extract the plugin surface into 10 focused
docs and a JSON Schema for plugin.json, then slim CLAUDE.md to a
156-line navigable index.

New docs (~999 lines total, all self-contained):

  docs/PLUGIN_AUTHORING.md            — entry point and quickstart
  docs/plugin-manifest.md             — plugin.json field reference
  docs/plugin-visualization-contracts.md — setRenderer / overlay / note-state
  docs/plugin-audio-mixer.md          — fader registration
  docs/plugin-logging.md              — context["log"] + env vars
  docs/plugin-diagnostics.md          — server_files / callable
  docs/plugin-keyboard-shortcuts.md   — registerShortcut + scopes
  docs/plugin-sibling-imports.md      — load_sibling pattern
  docs/websocket-protocol.md          — /ws/highway message reference
  docs/testing-plugins.md             — pytest fixtures + Playwright

  schema/plugin.schema.json           — Draft 2020-12 schema for
                                        plugin.json; license enum
                                        mirrors CONTRIBUTING's curated
                                        allowlist. Backs CI validation
                                        and the plugin-validate skill.

CLAUDE.md slim (581 lines changed, -485):

  - Removed ~300 lines of plugin-author prose (now in docs/).
  - Kept architecture quick reference, running the app, testing,
    git workflow, versioning, song formats, frontend/backend
    conventions, plugin authoring INDEX (table → docs/), first-hour
    pitfalls, "For AI agents" footer.
  - Anchor stubs preserved next to the new index entries so deep
    links from specs/001-slopsmith-platform/analyze.md still resolve.

Verification:
  python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]"
  # ok — validates highway_3d, app_tour_library, app_tour_settings
Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>

2026-06-18 00:38:50 -07:00

4.2 KiB

Raw Blame History

Highway WebSocket protocol reference

The highway WebSocket at /ws/highway/{filename}?arrangement={index} streams a song's chart data to the player. Plugins that drive their own highway, replace the renderer (see plugin-visualization-contracts.md), or consume the stream directly all read these frames.

Message order

Each connection receives the following JSON frames, roughly in this order:

Message	Shape	Description
`loading`	`{ type: 'loading', stage }`	Status/progress message during extraction or conversion.
`song_info`	`{ type, title, artist, arrangement, arrangement_index, arrangements, duration, tuning, capo, format, audio_url, audio_error, stems }`	Song metadata. `arrangements` is the full list for the switcher. `audio_url` is `null` when audio is unavailable, in which case `audio_error` is non-null; otherwise `audio_error` is `null`. `stems` is always present — an empty array for non-sloppak songs or sloppak songs with no split stems. `tuning` is an array (6 for guitar, 4 for bass).
`beats`	`{ type, data: [{ time, measure }] }`	Beat timestamps with measure numbers.
`sections`	`{ type, data: [{ time, name }] }`	Named sections (Intro, Verse, Chorus, etc.).
`anchors`	`{ type, data: [{ time, fret, width }] }`	Fret zoom anchors.
`chord_templates`	`{ type, data: [{ name, frets: [6] }] }`	Named chord shapes.
`lyrics`	`{ type, data: [{ w, t, d }] }`	Syllables: `w`=word, `t`=time, `d`=duration. `-` joins to previous, `+` = line break.
`tone_changes`	`{ type: 'tone_changes', base, data: [{ time, name }] }`	Optional — tone change events relative to the arrangement base tone; only sent if tones were found.
`notes`	`{ type, data: [{ t, s, f, sus, ho, po, sl, bn, ... }] }`	Single notes.
`chords`	`{ type, data: [{ t, notes: [{ s, f, sus, ... }] }] }`	Chord events.
`phrases`	`{ type, data: [{ start_time, end_time, max_difficulty, levels: [...] }], total }`	Optional — per-phrase difficulty ladder for master-difficulty slider (slopsmith#48). Only sent when the source chart carries multi-level phrase data (PSARC / phrase-aware sloppak). Sent in chunks (`data` is a batch, `total` is the full count across messages) to avoid multi-MB single frames. Absent for GP imports and legacy sloppak; consumers must treat missing message as "single fixed difficulty — slider disabled".
`ready`	`{ type: 'ready' }`	All data sent — safe to finalize and start rendering.

Delivery guarantees

Message delivery is incremental. You may receive loading updates and lyrics before note/chord payloads. tone_changes comes after lyrics when present and may be omitted entirely. Do not finalize rendering until you receive ready.

Consumer notes

Tuning array length follows arrangement. 6 strings for guitar, 4 for bass, more for extended-range GP imports. Use highway.getStringCount() for the authoritative count rather than tuning.length (which can be the RS-XML padded 6-string form).
Chord templates are static. Every chord_id referenced by chords is guaranteed to be present in chord_templates.
Notes carry technique fields. ho = hammer-on, po = pull-off, sl = slide target, bn = bend amount. The full set is defined in lib/song.py.
Multiple connections are supported. Split-screen panels, lyrics panes, and jumping-tab panes each open their own WebSocket. By design — don't try to multiplex.

Phrase payload (slopsmith#48)

phrases.data is an array of phrase objects. Each phrase has start_time, end_time, max_difficulty, and levels. Each level has difficulty, notes, chords, anchors, handshapes — fully scoped to that phrase. The master-difficulty slider applies a single difficulty across all phrases by selecting the matching level.

PLUGIN_AUTHORING.md — guide index
plugin-visualization-contracts.md — bundle shape passed to draw()
sloppak-spec.md — sloppak format these messages are derived from
lib/song.py — server-side Note, Chord, Arrangement, Song data models

4.2 KiB Raw Blame History