got-feedBack/feedBack
1
0
Fork 0
mirror of https://github.com/got-feedBack/feedBack.git synced 2026-08-11 11:19:24 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

feat(core): host per-instrument workingTuning capability + read-API/event (working-tuning PR 1) (#658)

Browse Source 
* feat(core): host per-instrument workingTuning capability + read-API/event (working-tuning PR 1)

Introduce window.feedBack.workingTuning — the live, host-authoritative current
instrument tuning (offsets + string-count + reference pitch + assumed/verified
provenance), distinct from any one song's tuning and from a soft opt-in default.
It's the single source of truth the highway, library, and plugins (tuner,
Virtuoso, minigames) will read so a retune or instrument swap is reflected
app-wide instead of being re-derived per surface.

PER-INSTRUMENT: state is a map keyed by `${instrument}-${stringCount}` (e.g.
guitar-6 / bass-4, the selector's key) — your guitar's tuning and your bass's are
kept separately; get() returns the selected instrument's, and switching the
selector surfaces that instrument's own remembered tuning. You only ever deal
with the one you've picked.

Modeled on the shipped `tuning` capability + the `feedBack.theme` read-API:
synchronous get(instrument?), set(state,{provenance,instrument}) mutator,
setCurrentInstrument(), resetToDefault(), and a `working-tuning-changed` event
that fires on change and once on hydration (carrying which instrument changed).
In-memory, seeded from /api/settings, reset-on-restart. Registered as a separate
`working-tuning` exclusive-owner capability (tuner = sole writer, others read).

Foundation only — pure plumbing, nothing writes to it yet and no behavior
changes. The tuner becomes the writer (and the gate's E->C# asymmetry is fixed)
in a later PR.

Frontend-only: new static/capabilities/working-tuning.js, loaded from
static/index.html + static/v3/index.html. Per-instrument state machine verified
by a stubbed node harness (separate guitar/bass slots, selector switch, isolated
writes, verified stamp, reset, defensive copies, capability registration).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QbexxfTt8q2tAn436MqGWF

* fix(working-tuning): resolve review P1/P2s + add behavioral test harness

Addresses the manual + Codex review of PR 1 (working-tuning foundation).

P1 — named tunings were dropped by the boot seed: /api/settings.tuning may be a
name ("Drop D") OR an offsets list, but the seed only handled the list and stored
offsets:null for names. The seed now resolves a name to per-string semitone offsets
via /api/tunings (ratio vs Standard; reference pitch cancels).

P1 — async seed could clobber state a consumer had already written: _seedFromSettings
resolves after boot and used to overwrite _currentKey/_byInstrument unconditionally.
It now bails when state was already _touched (and re-checks after the /api/tunings
leg), so an explicit set()/setCurrentInstrument()/resetToDefault() before hydration
wins. Hydration still fires.

P1/P2 — shallow copy leaked live nested arrays: get() and set() now clone offsets and
verifiedStrings on both ingress and egress, honouring the "readers can't mutate live
state" contract.

P2 — provenance/verification state machine made coherent by construction:
verified <=> verifiedStrings is an array AND verifiedAt is a finite number. A tuning
change invalidates prior verification unless a fresh bundle is supplied; a "verified"
claim with no strings or a null/absent timestamp is repaired (assumed / stamped now).

P2 — bare-instrument writes targeted a hard-coded default string count: _keyOfResolved()
resolves an omitted string count against the current selection (same instrument), so
set({instrument:'bass'}) / set({stringCount:5}) hit the selected bass-5, not bass-4.

Test — adds tests/js/working_tuning.test.js (the harness the PR described but did not
commit): 11 behavioral cases over a stubbed window — registration, per-instrument
isolation + selector switch, defensive copies, the verification invariant, bare-key
routing, named + offsets-list seeding, and the boot-race guard. Full tests/js suite:
no new failures (the 12 pre-existing branch failures are unrelated).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: byrongamatos <xasiklas@gmail.com>
This commit is contained in:
ChrisBeWithYou
2026-07-01 08:05:56 +02:00
committed by GitHub
co-authored by Claude Opus 4.8 byrongamatos
parent f9607c5c94
commit 491039a12d
5 changed files with 524 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
static/capabilities/working-tuning.js
+315
View File
@@ -0,0 +1,315 @@
// Core "working tuning" capability domain — the live, host-authoritative CURRENT
// instrument tuning (session state), distinct from the soft opt-in default and from
// any one song's tuning. This is the single source of truth the whole app reads:
// the highway, the library/song-picker, Virtuoso, and the minigames all consult it,
// and the tuner is the sole WRITER (it updates this when the player retunes, clears
// the gate, or switches instruments).
//
// PER-INSTRUMENT: a player has separate physical instruments, each in its OWN tuning
// ("I'm not tuning two instruments when I pick a song"). So state is a MAP keyed by
// instrument — `${instrument}-${stringCount}` (e.g. "guitar-6", "bass-4"), the same key
// the v3 instrument selector uses. `get()` returns the CURRENTLY-SELECTED instrument's
// tuning; switching the selector surfaces that instrument's own remembered tuning. You
// only ever deal with the one you've picked.
//
// Design: WORKING-TUNING-STATE-DESIGN.md (host-first PR series, PR 1 = this file).
// Pattern mirrors `capabilities/tuning.js` (capability registration) + the host theme
// read-API (`window.feedBack.theme`): a synchronous `get()` plus a `working-tuning-
// changed` event that also fires once on hydration.
//
// State is IN-MEMORY and NOT persisted — reset-to-home on restart is deliberate (a
// stale "you're in drop-A" assumption is worse than re-asking). The opt-in "default
// tuning on app open" lands later; for now we seed the selected instrument from
// /api/settings.
//
// PR 1 is PURE PLUMBING: it introduces the state + read/write surface + event, but
// nothing writes to it yet and no behavior changes. The tuner becomes the writer (and
// the gate's E->C# asymmetry is fixed) in a later PR.
(function () {
'use strict';
window.feedBack = window.feedBack || {};
const capabilities = window.feedBack.capabilities;
const _byInstrument = {}; // key -> tuning state (the per-instrument map)
let _currentKey = null; // the selected instrument's key; cached so get() is sync
let _hydrated = false;
let _touched = false; // set once anything explicitly writes/selects; gates the async seed
function _normInstrument(instrument) {
return instrument === 'bass' ? 'bass' : 'guitar';
}
function _keyOf(instrument, stringCount) {
const inst = _normInstrument(instrument);
const sc = Number(stringCount) || (inst === 'bass' ? 4 : 6);
return inst + '-' + sc;
}
// Like _keyOf, but when the caller omits a string count we resolve it against the
// current selection (if it's the same instrument) before falling back to the
// per-instrument default — so `set({instrument:'bass'})` targets the selected
// bass-5, not a hard-coded bass-4.
function _keyOfResolved(instrument, stringCount) {
const inst = _normInstrument(instrument);
let sc = Number(stringCount);
if (!sc) {
if (_currentKey) {
const cur = _splitKey(_currentKey);
if (cur.instrument === inst) sc = cur.stringCount;
}
if (!sc) sc = (inst === 'bass' ? 4 : 6);
}
return inst + '-' + sc;
}
function _splitKey(key) {
const parts = (typeof key === 'string' ? key : '').split('-');
const inst = parts[0] === 'bass' ? 'bass' : 'guitar';
return { instrument: inst, stringCount: Number(parts[1]) || (inst === 'bass' ? 4 : 6) };
}
// The shape every consumer reads. `offsets` are per-string semitone offsets from
// standard (same vocabulary as song_info.tuning and /api/tunings); `instrument`
// disambiguates the open-string base so offsets resolve to real pitches. A drop-A
// 8-string is just an offsets array — fully custom tunings are first-class.
// `provenance` is the honesty flag: 'verified' means the tuner did a choreographed
// per-string mic check this session; everything else is 'assumed'.
function _defaultState(key) {
const id = _splitKey(key);
return {
offsets: null,
stringCount: id.stringCount,
instrument: id.instrument,
referencePitch: 440,
provenance: 'assumed',
verifiedStrings: null,
verifiedAt: null,
source: 'default',
};
}
// Resolve which instrument key a get/set targets: an explicit arg wins (a string
// key "guitar-6", a bare "guitar"/"bass", or { instrument, stringCount }); else the
// cached current selection.
function _resolveKey(instrument) {
if (instrument && typeof instrument === 'object') return _keyOfResolved(instrument.instrument, instrument.stringCount);
if (typeof instrument === 'string' && instrument) {
return instrument.indexOf('-') > 0 ? instrument : _keyOfResolved(instrument, null);
}
return _currentKey || _keyOf('guitar', 6);
}
// Synchronous read of an instrument's current tuning (default = selected
// instrument). Returns a deep-enough copy — the object plus its mutable array
// fields (`offsets`, `verifiedStrings`) — so a reader can't mutate the live state.
function get(instrument) {
const key = _resolveKey(instrument);
const state = Object.assign(_defaultState(key), _byInstrument[key] || {});
if (Array.isArray(state.offsets)) state.offsets = state.offsets.slice();
if (Array.isArray(state.verifiedStrings)) state.verifiedStrings = state.verifiedStrings.slice();
return state;
}
function _emitChanged(key) {
if (window.feedBack && typeof window.feedBack.emit === 'function') {
window.feedBack.emit('working-tuning-changed', { key: key, instrument: _splitKey(key).instrument, tuning: get(key) });
}
}
// The single mutator. The tuner calls this on retune / gate-clear / swap. Writes to
// the instrument the state targets (opts.instrument, or next.instrument+stringCount,
// or the current selection) and makes that the active instrument. `opts.provenance`
// stamps 'verified' (mic-confirmed) vs the default 'assumed'. Changing the tuning
// invalidates a prior verification unless fresh verifiedStrings are supplied — fail
// toward "assumed".
function set(next, opts) {
opts = opts || {};
next = next || {};
// Resolve the target key. An explicit opts.instrument wins; otherwise a
// next.instrument/next.stringCount targets that slot — but a bare stringCount
// (no instrument) applies to the CURRENTLY-SELECTED instrument, not a hard-coded
// guitar, so `set({stringCount:5})` on a selected bass writes bass-5.
let key;
if (opts.instrument) {
key = _resolveKey(opts.instrument);
} else if (next.instrument || next.stringCount) {
const inst = next.instrument ? _normInstrument(next.instrument)
: (_currentKey ? _splitKey(_currentKey).instrument : 'guitar');
key = _keyOfResolved(inst, next.stringCount);
} else {
key = _currentKey || _resolveKey();
}
const id = _splitKey(key);
const merged = Object.assign(get(key), next); // get() gives copies, so `merged` is ours to mutate
merged.instrument = id.instrument; // keep coherent with the key
merged.stringCount = id.stringCount; // the key is authoritative for string count
const tuningChanged = ('offsets' in next) || ('stringCount' in next) || ('referencePitch' in next);
// Provenance: explicit opts wins; a bare tuning change downgrades to 'assumed'.
if (opts.provenance) {
merged.provenance = opts.provenance;
} else if (tuningChanged) {
merged.provenance = 'assumed';
}
// Verification metadata is coherent by construction: a tuning change invalidates
// prior per-string verification unless the caller supplies a fresh bundle, and the
// metadata exists ONLY while provenance === 'verified'. So verified <=> we hold
// verifiedStrings — a "verified with no strings" state is impossible.
if (!('verifiedStrings' in next) && tuningChanged) {
merged.verifiedStrings = null;
}
if (merged.provenance === 'verified' && !Array.isArray(merged.verifiedStrings)) {
merged.provenance = 'assumed'; // claimed verified but no evidence — fail toward assumed
}
if (merged.provenance === 'verified') {
// verified always carries a real timestamp — a caller-supplied null/NaN/absent
// verifiedAt is stamped now, so 'verified' can never mean "at no known time".
if (typeof merged.verifiedAt !== 'number' || !isFinite(merged.verifiedAt)) {
merged.verifiedAt = Date.now();
}
} else {
merged.verifiedStrings = null;
merged.verifiedAt = null;
}
// Store copies of the mutable arrays so a caller can't mutate live state post-set.
if (Array.isArray(merged.offsets)) merged.offsets = merged.offsets.slice();
if (Array.isArray(merged.verifiedStrings)) merged.verifiedStrings = merged.verifiedStrings.slice();
_byInstrument[key] = merged;
_currentKey = key; // writing a tuning makes that instrument the active one
_touched = true; // an explicit write must not be clobbered by the async seed
_emitChanged(key);
return get(key);
}
// Tell the host which instrument is now selected (the v3 selector calls this when
// the player switches guitar<->bass / string count) so get() returns the right
// instrument's tuning. Emits if the selection actually changed.
function setCurrentInstrument(instrument, stringCount) {
const key = (typeof instrument === 'string' && instrument.indexOf('-') > 0) ? instrument : _keyOfResolved(instrument, stringCount);
_touched = true; // an explicit selection must not be reverted by the async seed
if (key === _currentKey) return get(key);
_currentKey = key;
_emitChanged(key);
return get(key);
}
// Reset an instrument's live tuning back to its baseline (the home/default).
function resetToDefault(instrument) {
const key = _resolveKey(instrument);
_byInstrument[key] = _defaultState(key);
_touched = true;
_emitChanged(key);
return get(key);
}
// Per-string semitone offsets of a named tuning relative to Standard, derived from
// the /api/tunings frequency tables. The reference pitch cancels in the ratio, so
// this is pitch-independent. Returns null if either row is missing/mismatched.
function _offsetsFromFreqs(named, standard) {
if (!Array.isArray(named) || !Array.isArray(standard) || named.length !== standard.length) return null;
const out = [];
for (let i = 0; i < named.length; i++) {
const a = Number(named[i]);
const b = Number(standard[i]);
if (!(a > 0) || !(b > 0)) return null;
out.push(Math.round(12 * Math.log2(a / b)));
}
return out;
}
// Seed the SELECTED instrument's slot from settings on boot (best-effort 'assumed'
// starting point, NOT a persisted working tuning). settings.tuning may be an offsets
// list OR a name ("Drop D") — a name is resolved to offsets via /api/tunings so a
// named tuning isn't lost. If settings can't be read we still hydrate so consumers
// aren't stuck waiting; an explicit set()/select before we resolve wins (no clobber).
function _seedFromSettings() {
fetch('/api/settings')
.then(function (r) { return r && r.ok ? r.json() : null; })
.then(function (s) {
if (!s || _touched) return; // nothing to seed, or a consumer already wrote — don't clobber
const inst = _normInstrument(s.instrument);
const sc = Number(s.string_count) || (inst === 'bass' ? 4 : 6);
const key = _keyOf(inst, sc);
function commit(offsets) {
if (_touched) return; // re-check: a write may have raced the /api/tunings fetch
_currentKey = key;
_byInstrument[key] = {
offsets: Array.isArray(offsets) ? offsets.slice(0, sc) : null,
stringCount: sc,
instrument: inst,
referencePitch: Number(s.reference_pitch) || 440,
provenance: 'assumed',
verifiedStrings: null,
verifiedAt: null,
source: 'settings',
};
}
if (Array.isArray(s.tuning)) { commit(s.tuning); return; }
if (typeof s.tuning === 'string' && s.tuning) {
return fetch('/api/tunings')
.then(function (r) { return r && r.ok ? r.json() : null; })
.then(function (t) {
const byName = t && t[key];
commit(byName ? _offsetsFromFreqs(byName[s.tuning], byName.Standard) : null);
})
.catch(function () { commit(null); });
}
commit(null);
})
.catch(function () { /* keep defaults */ })
.then(function () { _hydrate(); });
}
function _hydrate() {
if (_hydrated) return;
_hydrated = true;
_emitChanged(_currentKey || _resolveKey());
}
// ---- Capability registration (mirrors capabilities/tuning.js) ----------------
if (capabilities && capabilities.version === 1 &&
!(window.feedBack.workingTuning && window.feedBack.workingTuning.version === 1)) {
capabilities.registerOwner('working-tuning', {
description: 'The live, host-authoritative current instrument tuning (session state), per ' +
'instrument: offsets + string-count + reference pitch + assumed/verified provenance. ' +
'Written by the tuner, read by the highway/library/Virtuoso/minigames.',
operations: ['get-working-tuning', 'set-working-tuning'],
events: ['working-tuning-changed'],
kind: 'command',
ownership: 'exclusive-owner',
});
capabilities.registerParticipant('plugin.tuner', {
'working-tuning': {
roles: ['contributor', 'requester'],
operations: ['get-working-tuning', 'set-working-tuning'],
emits: ['working-tuning-changed'],
mode: 'active',
compatibility: 'none',
safety: 'safe',
},
});
capabilities.registerParticipant('core.settings.instruments', {
'working-tuning': {
roles: ['requester'],
operations: ['get-working-tuning'],
events: ['working-tuning-changed'],
mode: 'active',
compatibility: 'none',
safety: 'safe',
},
});
}
// ---- Public read/write surface (attached defensively, like feedBack.theme) ----
window.feedBack.workingTuning = Object.freeze({
version: 1,
get: get,
set: set,
setCurrentInstrument: setCurrentInstrument,
resetToDefault: resetToDefault,
});
_seedFromSettings();
})();
static/index.html
+1
View File
@@ -24,6 +24,7 @@
<script src="/static/capabilities.js"></script>
<script src="/static/capabilities/library.js"></script>
<script src="/static/capabilities/tuning.js"></script>
<script src="/static/capabilities/working-tuning.js"></script>
<script src="/static/capabilities/audio-session.js"></script>
<script src="/static/capabilities/audio-effects.js"></script>
<script src="/static/capabilities/playback.js"></script>
static/v3/index.html
+1
View File
@@ -87,6 +87,7 @@
<script src="/static/capabilities.js"></script>
<script src="/static/capabilities/library.js"></script>
<script src="/static/capabilities/tuning.js"></script>
<script src="/static/capabilities/working-tuning.js"></script>
<script src="/static/capabilities/audio-session.js"></script>
<script src="/static/capabilities/audio-effects.js"></script>
<script src="/static/capabilities/playback.js"></script>