Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* ChiptunePanel (#2911) — prompt-based looping 8-bit score generation for the
* Track editor. The user picks any configured AI provider/model, describes the
* music, and gets a structured chiptune score persisted on the track. The
* score previews as a seamless in-browser loop (chiptunePlayback.js), renders
* into the track's history as an OGG loop, and publishes into a managed app's
* repo (default `game/assets/music/`) as game-ready assets.
*
* Sibling of MusicGenPanel (the diffusion engines) — TracksManager toggles
* between the two. Provider/model + publish prefs persist in
* `settings.music.chiptune` so the next session starts where this one left off.
*/
import { useEffect, useMemo, useRef, useState } from 'react';
import { Loader2, Wand2, Play, Square, Disc3, Gamepad2 } from 'lucide-react';
import ListLoadError from '../ui/ListLoadError';
import toast from '../ui/Toast';
import useProviderModels from '../../hooks/useProviderModels';
import useMounted from '../../hooks/useMounted';
import ProviderModelSelector from '../ProviderModelSelector';
import { buildChiptuneSchedule, createChiptunePlayer } from '../../lib/chiptunePlayback.js';
import { formatTimecode } from '../../utils/formatters';
import {
generateTrackChiptune, renderTrackChiptune, publishTrackChiptune,
getApps, getSettings, patchSettingsSlice,
} from '../../services/api';
const slugify = (s) => String(s || '').toLowerCase().trim().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 64);
const DEFAULT_SUBDIR = 'game/assets/music';
const buildSourceBrief = (sourcePrompt, sourceLyrics) => [
sourcePrompt?.trim(),
sourceLyrics?.trim() ? `Lyrics:\n${sourceLyrics.trim()}` : '',
].filter(Boolean).join('\n\n');
export default function ChiptunePanel({ track, onTrackUpdate, remix, sourcePrompt = '', sourceLyrics = '' }) {
const sourceBrief = buildSourceBrief(sourcePrompt, sourceLyrics);
const [prompt, setPrompt] = useState(track?.chiptunePrompt || sourceBrief);
const [fresh, setFresh] = useState(false);
const [generating, setGenerating] = useState(false);
const [rendering, setRendering] = useState(false);
const [publishing, setPublishing] = useState(false);
const [playing, setPlaying] = useState(false);
const [publishOpen, setPublishOpen] = useState(false);
const [apps, setApps] = useState([]);
const [appsError, setAppsError] = useState(null);
const [publishAppId, setPublishAppId] = useState('');
const [publishSubdir, setPublishSubdir] = useState(DEFAULT_SUBDIR);
const [publishSlug, setPublishSlug] = useState('');
const [publishedFiles, setPublishedFiles] = useState(null);
// Saved provider/model pin, held until the provider list has loaded — the
// hook auto-selects a default when its list arrives, so applying the pin
// immediately would race that load and be nondeterministically overwritten.
const [savedPin, setSavedPin] = useState(null);
// StrictMode-safe (re-armed on remount) — a plain `useRef(true)` + cleanup
// would stay false after StrictMode's dev double-mount and wedge every
// post-await state update.
const mountedRef = useMounted();
const {
providers, selectedProviderId, selectedModel, availableModels,
setSelectedProviderId, setSelectedModel, loading: providersLoading,
} = useProviderModels({ silent: true });
const score = track?.chiptuneScore || null;
// The player re-reads this ref on every play, so a regeneration is heard
// without rebuilding the player instance.
const scoreRef = useRef(score);
scoreRef.current = score;
const playerRef = useRef(null);
if (!playerRef.current) {
playerRef.current = createChiptunePlayer(() => scoreRef.current);
}
// Stop playback when the selected track changes or the panel unmounts.
useEffect(() => () => { playerRef.current?.stop(); setPlaying(false); }, [track?.id]);
// Reseed the prompt + publish slug from the newly-selected track.
useEffect(() => {
setPrompt(track?.chiptunePrompt || sourceBrief);
setFresh(false);
setPublishedFiles(null);
setPublishSlug(slugify(track?.title));
}, [track?.id]);
// Remix from a chiptune take: seed the panel prompt with the take's prompt
// and default to a FRESH composition — renders don't snapshot their score,
// so iterating would revise the track's LATEST score, not the selected take.
// The visible "start fresh" checkbox makes the choice overridable. Keyed on
// the nonce so re-remixing the same take re-applies.
useEffect(() => {
if (remix?.prompt) {
setPrompt(remix.prompt);
setFresh(true);
}
}, [remix?.nonce, remix?.prompt]);
// Load saved prefs once. Publish prefs apply immediately; the provider pin
// is parked in `savedPin` and applied by the effect below only after the
// provider list has loaded.
useEffect(() => {
getSettings({ silent: true }).then((settings) => {
if (!mountedRef.current) return;
const saved = settings?.music?.chiptune || {};
if (saved.providerId) setSavedPin({ providerId: saved.providerId, model: saved.model || '' });
if (saved.publishAppId) setPublishAppId(saved.publishAppId);
if (saved.publishSubdir) setPublishSubdir(saved.publishSubdir);
}).catch(() => {});
}, []);
// Apply the saved provider pin once providers are loaded. A stale saved
// provider id degrades to the hook's own default selection; a stale saved
// MODEL (removed/renamed since it was pinned) is skipped too — the select
// doesn't render unmatched values, so applying it would silently send a
// model the provider no longer has while displaying a different one.
useEffect(() => {
if (!savedPin || providersLoading || !providers.length) return;
const provider = providers.find((p) => p.id === savedPin.providerId);
if (provider) {
setSelectedProviderId(savedPin.providerId);
const models = (provider.models?.length ? provider.models : [provider.defaultModel])
.map((m) => (typeof m === 'string' ? m : m?.id)).filter(Boolean);
if (savedPin.model && models.includes(savedPin.model)) setSelectedModel(savedPin.model);
}
setSavedPin(null); // apply once
}, [savedPin, providersLoading, providers, setSelectedProviderId, setSelectedModel]);
const summary = useMemo(() => {
if (!score) return null;
const { totalSec } = buildChiptuneSchedule(score);
return {
title: score.title || 'Untitled loop',
bpm: score.bpm,
patterns: Object.keys(score.patterns || {}).length,
order: (score.order || []).join(' '),
seconds: Math.round(totalSec * 10) / 10,
totalSec,
};
}, [score]);
// Preview playhead — painted straight into the DOM by the rAF loop below, so
// the bar tracks at frame rate without re-rendering the panel 60x a second.
const progressRef = useRef(null);
const elapsedRef = useRef(null);
const totalRef = useRef(null);
// Idle loop length — the CURRENT score's, shown before playback starts and
// again once it stops.
const idleTotalSec = summary?.totalSec || 0;
// rAF clock, mirroring PianoRoll's: animate while playing, paint one idle
// frame otherwise. Cancelled on stop (the effect re-runs) and on unmount.
useEffect(() => {
const paint = (fraction, sec, totalSec) => {
if (progressRef.current) progressRef.current.style.transform = `scaleX(${fraction})`;
if (elapsedRef.current) elapsedRef.current.textContent = formatTimecode(sec);
if (totalRef.current) totalRef.current.textContent = formatTimecode(totalSec);
};
if (!playing) { paint(0, 0, idleTotalSec); return undefined; }
let raf = 0;
const loop = () => {
const player = playerRef.current;
// The SOUNDING schedule's length, not the current score's — a
// regeneration mid-preview must not re-scale the bar (or the readout)
// against a loop nobody is hearing yet.
const loopSec = player.loopSec();
// position() is monotonic across loop passes and NEGATIVE during the
// transport's lead-in — clamp, then modulo onto the current pass.
const within = loopSec > 0 ? Math.max(0, player.position()) % loopSec : 0;
paint(loopSec > 0 ? within / loopSec : 0, within, loopSec > 0 ? loopSec : idleTotalSec);
raf = requestAnimationFrame(loop);
};
raf = requestAnimationFrame(loop);
return () => cancelAnimationFrame(raf);
}, [playing, idleTotalSec]);
// The server merges into the stored `music.chiptune`, so neither a failed
// prefs load nor the Music Designer's own saves can be overwritten from here.
const persistChiptunePrefs = (patch) => {
patchSettingsSlice('music.chiptune', patch, { silent: true }).catch(() => {});
};
const handleGenerate = async () => {
if (!track?.id) { toast.error('Save the track first, then generate'); return; }
if (!prompt.trim()) { toast.error('Describe the music first'); return; }
if (!selectedProviderId) { toast.error('Pick an AI provider first'); return; }
setGenerating(true);
const res = await generateTrackChiptune(track.id, {
prompt: prompt.trim(),
providerId: selectedProviderId,
model: selectedModel || undefined,
...(fresh ? { fresh: true } : {}),
}, { silent: true }).catch((err) => { toast.error(err.message || 'Generation failed'); return null; });
if (!mountedRef.current) return;
setGenerating(false);
if (res?.track) {
onTrackUpdate?.(res.track);
setFresh(false);
persistChiptunePrefs({ providerId: selectedProviderId, model: selectedModel || '' });
toast.success(score ? 'Score revised' : 'Score composed');
}
};
const togglePlay = async () => {
if (playerRef.current.isPlaying()) {
playerRef.current.stop();
setPlaying(false);
return;
}
setPlaying(true);
// A blocked/interrupted AudioContext.resume() rejects — swallow it so the
// state correction below still runs (otherwise the button wedges on
// "Stop" with an idle transport).
await playerRef.current.play().catch((err) => {
console.error(`🎹 Chiptune preview failed to start: ${err.message}`);
});
if (mountedRef.current && !playerRef.current.isPlaying()) setPlaying(false);
};
const handleRender = async () => {
if (playerRef.current.isPlaying()) { playerRef.current.stop(); setPlaying(false); }
setRendering(true);
const res = await renderTrackChiptune(track.id, { silent: true })
.catch((err) => { toast.error(err.message || 'Render failed'); return null; });
if (!mountedRef.current) return;
setRendering(false);
if (res?.track) {
onTrackUpdate?.(res.track);
toast.success(`Loop rendered (${res.durationSec}s)`);
}
};
// A failed read leaves `apps` empty and sets `appsError`, so the panel shows
// a Retry instead of the "no managed apps" copy it reserves for a real empty list.
const loadPublishTargets = async () => {
setAppsError(null);
const list = await getApps({ silent: true }).catch((err) => {
if (mountedRef.current) setAppsError(err instanceof Error ? err : new Error('Request failed'));
return null;
});
if (!mountedRef.current || !list) return;
// Publishable targets are managed apps with a repo on disk — PortOS
// itself is excluded (its repo is not a game asset destination); the
// server enforces the same policy.
const publishable = (Array.isArray(list) ? list : []).filter((a) => a.repoPath && a.id !== 'portos-default' && !a.archived);
setApps(publishable);
// A remembered target that is no longer publishable (deleted/archived/
// repo-less) would leave the select showing nothing while Publish sends
// the stale id — clear it so the user picks a live target.
setPublishAppId((id) => (id && !publishable.some((a) => a.id === id) ? '' : id));
};
const openPublish = async () => {
setPublishedFiles(null);
if (!publishOpen && apps.length === 0) await loadPublishTargets();
if (!mountedRef.current) return;
setPublishOpen((o) => !o);
};
const handlePublish = async () => {
if (!publishAppId) { toast.error('Pick a target app first'); return; }
setPublishing(true);
const res = await publishTrackChiptune(track.id, {
appId: publishAppId,
subdir: publishSubdir.trim() || undefined,
slug: publishSlug.trim() || undefined,
}, { silent: true }).catch((err) => { toast.error(err.message || 'Publish failed'); return null; });
if (!mountedRef.current) return;
setPublishing(false);
if (res) {
setPublishedFiles(res);
persistChiptunePrefs({ publishAppId, publishSubdir: publishSubdir.trim() || DEFAULT_SUBDIR });
toast.success(`Published to ${res.appName}`);
}
};
// Generate/render/publish all mutate the same track record via RMW writes —
// letting two fire concurrently races those writes, so gate all three on
// any one being in flight rather than just their own flag.
const busy = generating || rendering || publishing;
const canGenerate = !!track?.id && !!prompt.trim() && !!selectedProviderId && !busy;
return (
<div className="space-y-2 border border-port-border rounded-lg p-3 bg-port-bg/40">
<div className="flex items-center gap-2 text-sm text-gray-300">
<Gamepad2 size={14} className="text-port-accent" /> Chiptune score — looping 8-bit background music
</div>
<p className="text-xs text-gray-400">
This brief is seeded from the track editor's Prompt and Lyrics. Refine it here for the chiptune composer; changes are used when you compose the score.
</p>
<label className="block">
<span className="block text-[11px] uppercase tracking-wider text-gray-500 mb-1">Describe the music</span>
<textarea
value={prompt}
onChange={(e) => setPrompt(e.target.value)}
rows={2}
maxLength={8000}
placeholder="Upbeat farm-chores theme — bouncy melody, walking bass, light hats, loops every 20s."
className="w-full px-2 py-1.5 bg-port-bg border border-port-border rounded text-white text-sm"
/>
</label>
<ProviderModelSelector
providers={providers}
selectedProviderId={selectedProviderId}
selectedModel={selectedModel}
availableModels={availableModels}
onProviderChange={setSelectedProviderId}
onModelChange={setSelectedModel}
label="AI provider"
layout="row"
/>
<div className="flex items-center gap-2 flex-wrap">
<button
type="button"
onClick={handleGenerate}
disabled={!canGenerate}
title={!track?.id ? 'Save the track first' : !prompt.trim() ? 'Describe the music first' : score && !fresh ? 'Revise the current score' : 'Compose a new score'}
className="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg bg-port-accent text-white text-sm font-medium disabled:opacity-50"
>
{generating ? <Loader2 size={14} className="animate-spin" /> : <Wand2 size={14} />}
{generating ? 'Composing…' : score && !fresh ? 'Revise score' : 'Compose score'}
</button>
{score ? (
<label className="inline-flex items-center gap-1.5 text-xs text-gray-400">
<input type="checkbox" checked={fresh} onChange={(e) => setFresh(e.target.checked)} />
Start fresh (ignore current score)
</label>
) : null}
</div>
{summary ? (
<div className="space-y-2 pt-2 border-t border-port-border/60">
<div className="text-xs text-gray-400">
<span className="text-white">{summary.title}</span>
{' — '}{summary.bpm} BPM · {summary.patterns} pattern{summary.patterns === 1 ? '' : 's'} · order {summary.order} · ~{summary.seconds}s loop
</div>
<div className="flex items-center gap-2 flex-wrap">
<button
type="button"
onClick={togglePlay}
className="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg bg-port-bg border border-port-border text-white text-sm hover:border-port-accent"
>
{playing ? <Square size={14} /> : <Play size={14} />}
{playing ? 'Stop' : 'Preview loop'}
</button>
<button
type="button"
onClick={handleRender}
disabled={busy}
title="Render the loop to audio and add it to this track's renders"
className="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg bg-port-bg border border-port-border text-white text-sm hover:border-port-accent disabled:opacity-50"
>
{rendering ? <Loader2 size={14} className="animate-spin" /> : <Disc3 size={14} />}
{rendering ? 'Rendering…' : 'Render take'}
</button>
<button
type="button"
onClick={openPublish}
disabled={busy}
className="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg bg-port-bg border border-port-border text-white text-sm hover:border-port-accent disabled:opacity-50"
>
<Gamepad2 size={14} /> Publish to app…
</button>
</div>
{/* Preview position. The bar is decorative (aria-hidden) — the
timecode beside it carries the same information as text. */}
<div className="flex items-center gap-2">
<div className="flex-1 h-1.5 rounded-full bg-port-border overflow-hidden" aria-hidden="true">
<div
ref={progressRef}
data-testid="chiptune-progress-bar"
className="h-full w-full origin-left bg-port-accent"
style={{ transform: 'scaleX(0)' }}
/>
</div>
<span className="text-[11px] font-mono text-gray-500 tabular-nums whitespace-nowrap">
<span ref={elapsedRef} data-testid="chiptune-progress-time">0:00.00</span>
{' / '}
<span ref={totalRef} data-testid="chiptune-progress-total">{formatTimecode(summary.totalSec)}</span>
</span>
</div>
{publishOpen ? (
<div className="space-y-2 border border-port-border rounded-lg p-2 bg-port-bg">
{appsError ? (
<ListLoadError what="managed apps" error={appsError} onRetry={loadPublishTargets} />
) : apps.length === 0 ? (
<p className="text-xs text-gray-500">No managed apps with a repo path — add the game app under Apps first.</p>
) : (
<>
<div className="grid grid-cols-1 sm:grid-cols-2 gap-2">
<label className="block">
<span className="block text-[11px] uppercase tracking-wider text-gray-500 mb-1">Target app</span>
<select
value={publishAppId}
onChange={(e) => setPublishAppId(e.target.value)}
className="w-full px-2 py-1.5 bg-port-card border border-port-border rounded text-white text-sm"
>
<option value="">— pick an app —</option>
{apps.map((a) => <option key={a.id} value={a.id}>{a.name}</option>)}
</select>
</label>
<label className="block">
<span className="block text-[11px] uppercase tracking-wider text-gray-500 mb-1">Filename slug</span>
<input
value={publishSlug}
onChange={(e) => setPublishSlug(e.target.value)}
placeholder={slugify(track?.title) || 'track'}
className="w-full px-2 py-1.5 bg-port-card border border-port-border rounded text-white text-sm"
/>
</label>
</div>
<label className="block">
<span className="block text-[11px] uppercase tracking-wider text-gray-500 mb-1">Folder inside the app repo</span>
<input
value={publishSubdir}
onChange={(e) => setPublishSubdir(e.target.value)}
placeholder={DEFAULT_SUBDIR}
className="w-full px-2 py-1.5 bg-port-card border border-port-border rounded text-white text-sm"
/>
</label>
<button
type="button"
onClick={handlePublish}
disabled={busy || !publishAppId}
className="inline-flex items-center gap-2 px-3 py-1.5 rounded-lg bg-port-accent text-white text-sm font-medium disabled:opacity-50"
>
{publishing ? <Loader2 size={14} className="animate-spin" /> : <Gamepad2 size={14} />}
{publishing ? 'Publishing…' : 'Publish loop'}
</button>
</>
)}
{publishedFiles ? (
<div className="text-[11px] text-gray-400 space-y-0.5">
<p className="text-port-success">Published to {publishedFiles.appName}:</p>
{publishedFiles.files.map((f) => <p key={f} className="font-mono truncate">{f}</p>)}
<p>{publishedFiles.note}</p>
</div>
) : null}
</div>
) : null}
</div>
) : (
<p className="text-[11px] text-gray-500">
No score yet — describe the vibe and compose. The score previews as a seamless loop, renders to audio, and publishes straight into a managed game app.
</p>
)}
</div>
);
}